Skip to content

[scroll-animations-1] Describe scroll/view-timeline-attachment #8680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Apr 21, 2023
Merged

[scroll-animations-1] Describe scroll/view-timeline-attachment #8680

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0ad0e1a
[scroll-animations-1] Describe scroll/view-timeline-attachment
andruud Apr 4, 2023
c857f21
No multiple attachments, Oxford comma, etc
andruud Apr 5, 2023
7d71af1
[scroll-animations-1] Minor clean-up of definitions / term linking.
fantasai Apr 10, 2023
78a5ad7
[scroll-animations-1] Recast timeline attachment as a name binding. #…
fantasai Apr 11, 2023
8ac6693
[scroll-animations-1] Remove scroll container requirements
andruud Apr 14, 2023
39ab738
[scroll-animations-1] Editorial improvements to name attachment
fantasai Apr 21, 2023
0f45add
[scroll-animations-1] Remove scroll container requirements, part 2
andruud Apr 21, 2023
97741bd
[scroll-animations-1] Scroll timelines are only active on scroll cont…
fantasai Apr 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 242 additions & 32 deletions scroll-animations-1/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,79 +310,160 @@ spec: cssom-view-1; type: dfn;
## Named Scroll Progress Timelines ## {#scroll-timelines-named}

[=Scroll progress timelines=] can also be defined on the [=scroll container=] itself,
and then referenced by name.
See [[#timeline-scope]].
and then referenced by name
by elements within the name’s scope
(see [[#timeline-scope]]).

Named scroll progress timelines are declared in the [=coordinated value list=]
Such <dfn>named scroll progress timelines</dfn>
are declared in the [=coordinated value list=]
constructed from the [=longhands=] of the 'scroll-timeline' [=shorthand property=],
which form a [=coordinating list property group=]
with 'scroll-timeline-name' as the [=coordinating list base property=].
See [[css-values-4#linked-properties]].

Depending on its <dfn local-lt='attachment'>name attachment</dfn>
('scroll-timeline-attachment'),
a name specified by 'scroll-timeline-name'
can be attached to a [=scroll progress timeline=] defined on the element’s own box
(''scroll-timeline-attachment/local''),
declared for the element’s scope but deferred
to a descendant [=scroll container=]’s [=scroll progress timeline=]
(''scroll-timeline-attachment/defer''),
or used to attach the element’s [=scroll progress timeline=]
to a name declared and deferred by an ancestor
(''scroll-timeline-attachment/ancestor''),
effectively allowing its [[#timeline-scope|scope]] to expand
beyond this element and its descendants.

### Naming a Scroll Progress Timeline: the 'scroll-timeline-name' property ### {#scroll-timeline-name}

<pre class='propdef'>
Name: scroll-timeline-name
Value: none | <<custom-ident>>#
Initial: none
Applies to: [=scroll containers=]
Applies to: all elements
Inherited: no
Computed value: the keyword ''scroll-timeline-name/none'' or a list of <<custom-ident>>s
Animation type: not animatable
</pre>

Specifies names for the [=scroll progress timelines=]
associated with this [=scroll container=].
The axis for this timeline is given by 'scroll-timeline-axis'.
Specifies names for the [=named scroll progress timelines=]
associated with this element.
Depending on the name’s [=attachment=] ('view-timeline-attachment'),
this element can declare a name,
define its [=scroll progress timeline=],
or both (the default).

### Axis of a Scroll Progress Timeline: the 'scroll-timeline-axis' property ### {#scroll-timeline-axis}

<pre class='propdef'>
Name: scroll-timeline-axis
Value: [ block | inline | vertical | horizontal ]#
Initial: block
Applies to: [=scroll containers=]
Applies to: all elements
Inherited: no
Computed value: a list of the keywords specified
Animation type: not animatable
</pre>

Specifies an axis for each [=scroll progress timeline=]
associated with this [=scroll container=].
The name for this timeline is given by 'scroll-timeline-name'.
Specifies the axis of any [=named scroll progress timelines=]
sourced from this [=scroll container=].
If this box is not a [=scroll container=],
then the corresponding [=named scroll progress timeline=]
is [=inactive timeline|inactive=].

Values are as defined for ''scroll()''.

Note: This property has no effect when combined
with a 'scroll-timeline-attachment' of ''scroll-timeline-attachment/defer''.

### Attachment of a Scroll Progress Timeline: the 'scroll-timeline-attachment' property ### {#scroll-timeline-attachment}

<pre class='propdef'>
Name: scroll-timeline-attachment
Value: [ local | defer | ancestor ]#
Initial: local
Applies to: all elements
Inherited: no
Computed value: a list of the keywords specified
Animation type: not animatable
</pre>

Specifies the [=name attachment=]
of each [=scroll progress timeline=] name
specified by 'scroll-timeline-name'.

Values have the following meanings:

<dl dfn-type=value dfn-for=scroll-timeline-attachment>
<dt><dfn>local</dfn>
<dd>
This [=scroll progress timeline=] name
[=attaches=] to the corresponding [=scroll progress timeline=]
defined on this box.

<dt><dfn>defer</dfn>
<dd>
This [=scroll progress timeline=] name’s [=attachment=]
is deferred to its descendants.
In other words,
this element declares a [=scroll progress timeline=]’s name
and defines its scope (see [[#timeline-scope]]),
but defers the timeline’s definition
([=scroll container=] source and axis)
to its descendants.

If more than one matching descendant [=scroll progress timeline=] exists,
or if no such timeline exists,
then the timeline name has no [=attachment=],
and represents an [=inactive timeline=].

ISSUE: Should it instead be ignored (be invisible to lookup)?
(This might make it harder to implement.)
If multiple, should it attach instead to the last declared timeline (in tree order)
rather than invalidating the attachment?

<dt><dfn>ancestor</dfn>
<dd>
This [=scroll progress timeline=] definition,
attaches to the closest matching [=scroll progress timeline=] name
that was deferred (''scroll-timeline-name/defer'')
by an ancestor (if any).

If no such ancestor exists,
the [=attachment=] is treated as ''scroll-timeline-attachment/local''.
</dl>

### Scroll Timeline Shorthand: the 'scroll-timeline' shorthand ### {#scroll-timeline-shorthand}

<pre class='propdef shorthand'>
Name: scroll-timeline
Value: [ <<'scroll-timeline-name'>> <<'scroll-timeline-axis'>>? ]#
Applies to: [=scroll containers=]
Value: [ <<'scroll-timeline-name'>> [ <<'scroll-timeline-axis'>> || <<'scroll-timeline-attachment'>> ]? ]#
Applies to: all elements
Inherited: no
Animation type: not animatable
</pre>

This property is a [=shorthand=] for setting
'scroll-timeline-name' and 'scroll-timeline-axis'
'scroll-timeline-name', 'scroll-timeline-axis', and 'scroll-timeline-attachment'
in a single declaration.

# View Progress Timelines # {#view-timelines}

Often animations are desired to start and end
during the portion of the [=scroll progress timeline=]
that a particular element
(the <dfn>view progress subject</dfn> element)
that a particular box
(the <dfn>view progress subject</dfn>)
is in view within the [=scrollport=].
<dfn export>View progress timelines</dfn>
are segments of a [=scroll progress timeline=]
that are scoped to the scroll positions
in which any part of the associated element’s [=principal box=]
in which any part of the subject element’s [=principal box=]
intersects its nearest ancestor [=scrollport=]
(or more precisely, the relevant [=view progress visibility range=]
of that [=scrollport=]).
The startmost such scroll position represents 0% progress
and the endmost such scroll position represents 100% progress,
The startmost such scroll position represents 0% progress,
and the endmost such scroll position represents 100% progress;
see [[#view-timeline-progress]].

Note: The 0% and 100% scroll positions are not always reachable,
Expand Down Expand Up @@ -623,15 +704,25 @@ spec: cssom-view-1; type: dfn;
## Named View Progress Timelines ## {#view-timelines-named}

[=View progress timelines=] can also be defined declaratively
and then referenced by name.
See [[#timeline-scope]].
and then referenced by name
by elements within the name’s scope
(see [[#timeline-scope]]).

Named view progress timelines are declared in the [=coordinated value list=]
Such <dfn>named view progress timelines</dfn>
are declared in the [=coordinated value list=]
constructed from the 'view-timeline-*' properties,
which form a [=coordinating list property group=]
with 'view-timeline-name' as the [=coordinating list base property=].
See [[css-values-4#linked-properties]].

[[#scroll-timelines-named|As for named scroll progress timelines]],
[=named view progress timelines=] can have various [=name attachments=],
allowing a name specified by 'view-timeline-name'
to be attached to the box’s own [=view progress timeline=],
deferring it to a descendant box’s [=view progress timeline=],
or connecting the box’s [=view progress timeline=]
to the scope of an ancestor.

### Naming a View Progress Timeline: the 'view-timeline-name' property ### {#view-timeline-name}

<pre class='propdef'>
Expand All @@ -644,8 +735,12 @@ spec: cssom-view-1; type: dfn;
Animation type: not animatable
</pre>

Specifies names for any [=view progress timelines=]
associated with this element’s [=principal box=].
Specifies names for the [=named view progress timelines=]
associated with this element.
Depending on the name’s [=attachment=] ('view-timeline-attachment'),
this element can declare a name,
define its [=view progress timeline=],
or both (the default).

### Axis of a View Progress Timeline: the 'view-timeline-axis' property ### {#view-timeline-axis}

Expand All @@ -659,8 +754,13 @@ spec: cssom-view-1; type: dfn;
Animation type: not animatable
</pre>

Specifies an axis for each named [=view progress timeline=]
associated with this [=scroll container=].
Specifies the axis of any [=named view progress timelines=]
derived from this element’s [=principal box=].

Values are as defined for ''view()''.

Note: This property has no effect when combined
with a 'view-timeline-attachment' of ''view-timeline-attachment/defer''.

### Inset of a View Progress Timeline: the 'view-timeline-inset' property ### {#view-timeline-inset}

Expand Down Expand Up @@ -695,16 +795,74 @@ spec: cssom-view-1; type: dfn;
defines an inward offset from the corresponding edge of the scrollport.
</dl>

Note: This property has no effect when combined
with a 'view-timeline-attachment' of ''view-timeline-attachment/defer''.

### Attachment of a View Progress Timeline: the 'view-timeline-attachment' property ### {#view-timeline-attachment}

<pre class='propdef'>
Name: view-timeline-attachment
Value: [ local | defer | ancestor ]#
Initial: local
Applies to: all elements
Inherited: no
Computed value: a list of the keywords specified
Animation type: not animatable
</pre>

Specifies the [=name attachment=]
of each [=view progress timeline=] name
specified by 'view-timeline-name'.

Values have the following meanings:

<dl dfn-type=value dfn-for=view-timeline-attachment>
<dt><dfn>local</dfn>
<dd>
This [=view progress timeline=] name
[=attaches=] to the corresponding [=view progress timeline=]
defined on this box.

<dt><dfn>defer</dfn>
<dd>
This [=view progress timeline=] name’s [=attachment=]
is deferred to its descendants.
In other words,
this element declares a [=view progress timeline=]’s name
and defines its scope (see [[#timeline-scope]]),
but defers the timeline’s definition
([=view progress subject|subject=],
[=scroll container=] source,
axis, and
[=view progress visibility range|visibility range=])
to its descendants.

If more than one matching descendant [=view progress timeline=] exists,
or if no such timeline exists,
then this timeline name has no [=attachment=],
and represents an [=inactive timeline=].

<dt><dfn>ancestor</dfn>
<dd>
This [=view progress timeline=] definition
[=attaches=] to the closest matching [=view progress timeline=] name
that was deferred (''view-timeline-name/defer'')
by an ancestor (if any).

If no such ancestor exists,
the [=attachment=] is treated as ''view-timeline-attachment/local''.
</dl>

### View Timeline Shorthand: the 'view-timeline' shorthand ### {#view-timeline-shorthand}

<pre class='propdef shorthand'>
Name: view-timeline
Value: [ <<'view-timeline-name'>> <<'view-timeline-axis'>>? ]#
Value: [ <<'view-timeline-name'>> [ <<'view-timeline-axis'>> || <<'view-timeline-attachment'>> ]? ]#
Applies to: all elements
</pre>

This property is a [=shorthand=] for setting
'view-timeline-name' and 'view-timeline-axis'
'view-timeline-name', 'view-timeline-axis', and 'view-timeline-attachment'
in a single declaration.
It does not set 'view-timeline-inset'.

Expand Down Expand Up @@ -763,20 +921,72 @@ spec: cssom-view-1; type: dfn;
The editors would be interested in hearing about
any real use cases for multiple iterations here.

## Named Timeline Scoping ## {#timeline-scope}
## Named Timeline Scoping and Lookup ## {#timeline-scope}

A named [=scroll progress timeline=] or [=view progress timeline=]
is referenceable in 'animation-timeline' by:
* the declaring element itself
is referenceable by:
* the name-declaring element itself
* that element’s descendants

If multiple elements have declared the same timeline name,
the matching timeline is the one declared
on the nearest element in tree order.
In case of a name conflict on the same element,
names declared later in the naming property
('scroll-timeline-name', 'view-timeline-name')
take precedence, and
[=scroll progress timelines=] take precedence over [=view progress timelines=].

ISSUE(7759): We plan to add functionality to expand the scope.
Note: Although only names on the ancestor chain
are visible to a timeline name lookup,
a deferred [=name attachment=] allows a name declared on an ancestor
to be attached to a timeline sourced elsewhere in its subtree,
effectively allowing lookup of a timeline sourced
from a sibling, cousin, or descendant.
See 'scroll-timeline-attachment'/'view-timeline-attachment'.

<div class=example>
Using ''scroll-timeline-attachment: defer'',
an element can refer to timelines
bound to elements that are siblings, cousins, or even descendants.
For example, the following creates an animation on an element
that is linked to a [=scroll progress timeline=]
defined by the subsequent sibling.

<xmp highlight=html>
<style>
@keyframes anim {
from { color: red; }
to { color: green; }
}

.root {
scroll-timeline: scroller defer;
}

.root .animation {
animation: anim;
animation-timeline: scroller;
}

.root .animation + .scroller {
scroll-timeline: scroller ancestor;
}
</style>
&hellip;
<section class="root">
<div class="animation">Animating Box</div>
<div class="scroller">Scrollable Box</div>
</section>
</xmp>
</div>

If a timeline name has been declared,
but does not have a usable [=attachment=]
(e.g. if it is declared with ''scroll-timeline-name/defer'',
but no [=scroll progress timeline=] or [=view progress timeline=]
is [=attachment|attached=] to it),
it refers to an [=inactive timeline=].

## Animation Events ## {#events}

Expand Down