[scroll-animations-1] Define scroll/view-timeline-attachment #7759

This is a squashed commit; PR discussion at
#8680
and
andruud#1

Co-authored-by: fantasai <fantasai.bugs@inkedblade.net>

Author: andruud

scroll-animations-1/Overview.bs

@@ -317,79 +317,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,
@@ -649,15 +730,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'>
@@ -670,8 +761,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}
 
@@ -685,8 +780,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}
 
@@ -721,16 +821,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'.
 
@@ -789,20 +947,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}