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

Issue 7759.

Author: andruud

scroll-animations-1/Overview.bs

@@ -149,9 +149,10 @@ spec: cssom-view-1; type: dfn;
 	(<var>[=scrollable overflow=] size</var> &minus;
 		<var>[=scroll container=] size</var>)
 
-	If the 0% position and 100% position coincide
-	(i.e. the denominator in the [=timeline/current time=] formula is zero),
-	the timeline is [=inactive timeline|inactive=].
+	The timeline is [=inactive timeline|inactive=] when:
+	- The 0% position and 100% position coincide
+	(i.e. the denominator in the [=timeline/current time=] formula is zero), or
+	- The timeline has no [=current attachment=].
 
 ## Anonymous Scroll Progress Timelines ## {#scroll-timelines-anonymous}
 
@@ -353,20 +354,113 @@ spec: cssom-view-1; type: dfn;
 
 	Values are as defined for ''scroll()''.
 
+	The [=used value=] of 'scroll-timeline-axis'
+	is the axis of the [=current attachment=],
+	or the initial value if there is no [=current attachment=].
+
+### 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 attachment behavior for each [=scroll progress timeline=]
+	associated with this element.
+
+	A scroll timeline has a set of <dfn>attachments</dfn>,
+	that determine which [=scroll container=] and {{ScrollTimeline/axis}} to use
+	when calculating the [progress of the timeline](#scroll-timeline-progress).
+
+	<dl>
+		<dt><dfn>'local'</dfn>
+		<dd>
+			The [=attachments=] of the timeline is a single item set
+			containing that timeline.
+
+		<dt><dfn>'defer'</dfn>
+		<dd>
+			The [=attachments=] is the set of timelines in the flat-tree descendants
+			that satisfy all of the following:
+			 - The timeline has a matching 'scroll-timeline-name'.
+			 - The timeline has [=ancestor=] attachment.
+			 - The timeline has no intermediate [=defer|deferred=] timeline
+			   that would capture it.
+
+		<dt><dfn>'ancestor'</dfn>
+		<dd>
+			The set of [=attachments=] is empty.
+
+			Timelines with [=ancestor=] attachment are treated as nameless
+			for the purposes of timeline lookup;
+			they can't be referenced by 'animation-timeline'.
+	</dl>
+
+	The <dfn>current attachment</dfn> of a timeline is determined as follows:
+
+	<dl class="switch">
+		:   If the set of [=attachments=] contains exactly one timeline
+		::  The [=current attachment=] is that timeline.
+
+		:   Otherwise,
+		::  There is no [=current attachment=].
+	</dl>
+
+	<div class=example>
+		Using a [=defer|deferred timeline=],
+		an element can effectively refer to timelines
+		that appear <em>after it</em> in tree order.
+		For example, the following creates an animation on <code>#target</code> that
+		is ultimately linked to a scroll timeline defined on the subsequent sibling.
+
+		<pre class=lang-css>
+		@keyframes anim {
+		  from { color: red; }
+		  to { color: green; }
+		}
+
+		#root {
+		  scroll-timeline-name: mytimeline;
+		  scroll-timeline-attachment: defer;
+		}
+
+		#root #target {
+			animation: anim auto;
+			animation-timeline: mytimeline;
+		}
+
+		#root #target + #scroller {
+			scroll-timeline-name: mytimeline;
+		  scroll-timeline-attachment: ancestor;
+		}
+		</pre>
+	</div>
+
 ### Scroll Timeline Shorthand: the 'scroll-timeline' shorthand ### {#scroll-timeline-shorthand}
 
 	<pre class='propdef shorthand'>
 	Name: scroll-timeline
-	Value: [ <<'scroll-timeline-name'>> <<'scroll-timeline-axis'>>? ]#
+	Value: [ <<'scroll-timeline-name'>> [ <<'scroll-timeline-axis'>> | <<'scroll-timeline-attachment'>> ] ? ]#
 	Applies to: [=scroll containers=]
 	Inherited: no
 	Animation type: not animatable
 	</pre>
 
 	This property is a [=shorthand=] for setting
-	'scroll-timeline-name' and 'scroll-timeline-axis'
+	'scroll-timeline-name' and either 'scroll-timeline-axis' or 'scroll-timeline-axis'
 	in a single declaration.
 
+	If the 'scroll-timeline-axis' property is omitted,
+	it is set to its [=initial value=].
+
+	If the 'scroll-timeline-attachment' property is omitted,
+	it is set to its [=initial value=].
+
 # View Progress Timelines # {#view-timelines}
 
 	Often animations are desired to start and end
@@ -496,9 +590,10 @@ spec: cssom-view-1; type: dfn;
 		the [=scroll offset=] corresponding to
 		the end of the ''animation-timeline-range/cover'' range
 
-	If the 0% position and 100% position coincide
-	(i.e. the denominator in the [=timeline/current time=] formula is zero),
-	the timeline is [=inactive timeline|inactive=].
+	The timeline is [=inactive timeline|inactive=] when:
+	- The 0% position and 100% position coincide
+	(i.e. the denominator in the [=timeline/current time=] formula is zero), or
+	- The timeline has no [=current attachment=].
 
 ## Anonymous View Progress Timelines ## {#view-timelines-anonymous}
 
@@ -662,6 +757,10 @@ spec: cssom-view-1; type: dfn;
 	Specifies an axis for each named [=view progress timeline=]
 	associated with this [=scroll container=].
 
+	The [=used value=] of 'view-timeline-axis'
+	is the axis of the [=current attachment=],
+	or the initial value if there is no [=current attachment=].
+
 ### Inset of a View Progress Timeline: the 'view-timeline-inset' property ### {#view-timeline-inset}
 
 	<pre class='propdef'>
@@ -695,18 +794,49 @@ spec: cssom-view-1; type: dfn;
 			defines an inward offset from the corresponding edge of the scrollport.
 	</dl>
 
+	The [=used value=] of 'view-timeline-inset'
+	is the inset of the [=current attachment=],
+	or the initial value if there is no [=current attachment=].
+
+### 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 attachment behavior for each [=view progress timeline=]
+	associated with this element.
+
+	The behavior of 'view-timeline-attachment'
+	is similar to that of 'scroll-timeline-attachment',
+	except that the [=attachments=] of a view timeline also determine
+	the <a property lt="view-timeline-inset">inset</a>
+	and {{ViewTimeline/subject}} to use
+	when calculating the [progress of the timeline](#view-timeline-progress).
+
 ### 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'
-	in a single declaration.
-	It does not set 'view-timeline-inset'.
+	'view-timeline-name' and either 'view-timeline-axis' or 'view-timeline-attachment'
+	in a single declaration. It does not set 'view-timeline-inset'.
+
+	If the 'view-timeline-axis' property is omitted,
+	it is set to its [=initial value=].
+
+	If the 'view-timeline-attachment' property is omitted,
+	it is set to its [=initial value=].
 
 	ISSUE: Should it reset 'view-timeline-inset' also?
 
@@ -776,7 +906,7 @@ spec: cssom-view-1; type: dfn;
 	In case of a name conflict on the same element,
 	[=scroll progress timelines=] take precedence over [=view progress timelines=].
 
-	ISSUE(7759): We plan to add functionality to expand the scope.
+	Note: [=defer|Deferred timelines=] effectively allow scoping beyond this.
 
 ## Animation Events ## {#events}