diff --git a/scroll-animations-1/Overview.bs b/scroll-animations-1/Overview.bs index 93000d1b6b9..3e718c0231d 100644 --- a/scroll-animations-1/Overview.bs +++ b/scroll-animations-1/Overview.bs @@ -310,30 +310,49 @@ 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 named scroll progress timelines + 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 name attachment + ('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}
 	Name: scroll-timeline-name
 	Value: none | <>#
 	Initial: none
-	Applies to: [=scroll containers=]
+	Applies to: all elements
 	Inherited: no
 	Computed value: the keyword ''scroll-timeline-name/none'' or a list of <>s
 	Animation type: not animatable
 	
- 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} @@ -341,48 +360,110 @@ spec: cssom-view-1; type: dfn; 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 - 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} + +
+	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
+	
+ + Specifies the [=name attachment=] + of each [=scroll progress timeline=] name + specified by 'scroll-timeline-name'. + + Values have the following meanings: + +
+
local +
+ This [=scroll progress timeline=] name + [=attaches=] to the corresponding [=scroll progress timeline=] + defined on this box. + +
defer +
+ 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? + +
ancestor +
+ 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''. +
+ ### Scroll Timeline Shorthand: the 'scroll-timeline' shorthand ### {#scroll-timeline-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
 	
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 view progress subject element) + that a particular box + (the view progress subject) is in view within the [=scrollport=]. View progress timelines 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, @@ -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 named view progress timelines + 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}
@@ -644,8 +735,12 @@ spec: cssom-view-1; type: dfn;
 	Animation type: not animatable
 	
- 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} @@ -659,8 +754,13 @@ spec: cssom-view-1; type: dfn; Animation type: not animatable - 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} @@ -695,16 +795,74 @@ spec: cssom-view-1; type: dfn; defines an inward offset from the corresponding edge of the scrollport. + 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} + +
+	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
+	
+ + Specifies the [=name attachment=] + of each [=view progress timeline=] name + specified by 'view-timeline-name'. + + Values have the following meanings: + +
+
local +
+ This [=view progress timeline=] name + [=attaches=] to the corresponding [=view progress timeline=] + defined on this box. + +
defer +
+ 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=]. + +
ancestor +
+ 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''. +
+ ### View Timeline Shorthand: the 'view-timeline' shorthand ### {#view-timeline-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
 	
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'. @@ -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'. + +
+ 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. + + + <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> + +
+ + 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}