[scroll-animations-1] Define named view timeline phases and their usage. w3c#7044

Author: fantasai

scroll-animations-1/Overview.bs

@@ -347,6 +347,59 @@ spec: cssom-view-1; type: dfn;
 	In the Web Animations API,
 	they can be represented anonymously by a {{ViewTimeline}} object.
 
+## View Progress Timeline Ranges ## {#view-timelines-ranges}
+
+	[=View progress timelines=] define the following [=named timeline ranges=]:
+
+	<dl dfn-for="animation-timeline-range" dfn-type="value">
+		<dt><dfn>cover</dfn>
+		<dd>
+			Represents the full range of the [=view progress timeline=]:
+			* 0% progress represents the position at which
+				the [=start=] [=border edge=] of the element’s [=principal box=]
+				coincides with the [=end=] edge of its [=view progress visibility range=].
+			* 100% progress represents the position at which
+				the [=end=] [=border edge=] of the element’s [=principal box=]
+				coincides with the [=start=] edge of its [=view progress visibility range=].
+
+		<dt><dfn>contain</dfn>
+		<dd>
+			Represents the range during which the [=principal box=]
+			is either fully contained by, or fully covers,
+			its [=view progress visibility range=] within the [=scrollport=].
+			* 0% progress represents the earlier position at which:
+				* the [=start=] [=border edge=] of the element’s [=principal box=]
+					coincides with the [=start=] edge of its [=view progress visibility range=].
+				* the [=end=] [=border edge=] of the element’s [=principal box=]
+					coincides with the [=end=] edge of its [=view progress visibility range=].
+			* 100% progress represents the later position at which:
+				* the [=start=] [=border edge=] of the element’s [=principal box=]
+					coincides with the [=start=] edge of its [=view progress visibility range=].
+				* the [=end=] [=border edge=] of the element’s [=principal box=]
+					coincides with the [=end=] edge of its [=view progress visibility range=].
+
+		<dt><dfn>entry</dfn>
+		<dd>
+			Represents the range during which the [=principal box=]
+			is entering the [=view progress visibility range=].
+			* 0% is equivalent to 0% of the ''animation-timeline-range/cover'' range.
+			* 100% is equivalent to 0% of the ''animation-timeline-range/contain'' range.
+
+			ISSUE: Should this be ''entry'' or ''enter''?
+
+		<dt><dfn>exit</dfn>
+		<dd>
+			Represents the range during which the [=principal box=]
+			is exiting the [=view progress visibility range=].
+			* 0% is equivalent to 100% of the ''animation-timeline-range/contain'' range.
+			* 100% is equivalent to 100% of the ''animation-timeline-range/cover'' range.
+	</dl>
+
+	ISSUE: Insert diagrams.
+
+	In all cases, the [=writing mode=] used to resolve the [=start=] and [=end=] sides
+	is the [=writing mode=] of the relevant [=scroll container=].
+
 ## Anonymous View Progress Timelines ## {#view-timelines-anonymous}
 
 ### The {{ViewTimeline}} Interface ### {#viewtimeline-interface}
@@ -602,3 +655,146 @@ spec: cssom-view-1; type: dfn;
 	In such cases, the rendered scroll offset
 	and the state of a scroll-driven animation
 	may be inconsistent in the composited frame.
+
+# Appendix A: Named Timeline Ranges # {#timeline-ranges}
+
+	ISSUE: This section should move to CSS-ANIMATIONS-2 and WEB-ANIMATIONS-2.
+
+	This specification introduces the concept of [=named timeline ranges=]
+	to <a href="https://www.w3.org/TR/css-animations/">CSS Animations</a>
+	and <a href="https://www.w3.org/TR/web-animations/">Web Animations</a>.
+
+	A <dfn export>named timeline range</dfn>
+	is a named segment of an animation [=timeline=].
+	The start of the segment is represented as 0% progress through the range;
+	the end of the segment is represented as 100% progress through the range.
+	Multiple [=named timeline ranges=] can be attached to a given [=timeline=],
+	and multiple such ranges can overlap.
+	For example, the ''animation-timeline/contain'' range of a [=view progress timeline=]
+	overlaps with its ''animation-timeline/cover'' range.
+	[=Named timeline ranges=] are represented by
+	the <dfn><<timeline-range-name>></dfn> value type,
+	which indicates a [=CSS identifier=] representing
+	one of the predefined [=named timeline ranges=].
+
+	Note: In this specification, [=named timeline ranges=]
+	must be defined to exist by a specification
+	such as [[SCROLL-ANIMATIONS-1]].
+	A future level may introduce APIs for authors to declare
+	their own custom [=named timeline ranges=].
+
+## Named Timeline Range Keyframe Selectors ## {#named-range-keyframes}
+
+	[=Named timeline range=] names and percentages
+	can be used to attach keyframes
+	to specific progress points within the [=named timeline range=].
+	The CSS ''@keyframes'' rule is extended thus:
+
+	<pre class="prod">
+		<<keyframe-selector>> = from | to | <<percentage>> | <<timeline-range-name>> <<percentage>>
+	</pre>
+
+	where <<timeline-range-name> is the [=CSS identifier=]
+	that represents a chosen predefined [=named timeline range=],
+	and the <<percentage>> after it represents the percentage progress
+	between the start and end of that [=named timeline range=].
+
+	Keyframes are attached to the specified point in the timeline.
+	If the timeline does not have a corresponding [=named timeline range=],
+	then any keyframes attached to points on that [=named timeline range=]
+	are ignored.
+
+## Attaching Animations to Timeline Ranges ## {#named-range-animation-declaration}
+
+	A set of animation keyframes can be attached
+	in reference to [=named timeline ranges=]
+	by adjusting the duration of the animation.
+
+	<pre class="propdef shorthand">
+		Name: animation-delay, animation-range
+		Value: [ <<'animation-delay-start'>> <<'animation-delay-end'>>? | <<timeline-range-name>> ]#
+	</pre>
+
+	The 'animation-delay' and 'animation-range' properties
+	are both [=shorthand property|shorthands=]
+	that set 'animation-delay-start' and 'animation-delay-end'
+	together in a single declaration.
+	If the <<'animation-delay-end'>> value is omitted,
+	it is set to zero.
+	If a <<timeline-range-name>> alone is specified,
+	'animation-delay-start' is set to that name plus ''0%''
+	and 'animation-delay-end' is set to that name plus ''100%''.
+
+	<pre class="propdef">
+		Name: animation-delay-start
+		Value: [ <<time>> | <<timeline-range-name>> <<percentage>>
+		Initial: 0s
+		Applies to: all elements
+		Inherited: no
+		Percentages: relative to the specified [=named timeline range=]
+		Computed value: list, each item either a duration or a timeline range and progress percentage
+		Animatable: no
+	</pre>
+
+	Defines a delay between the start of the animation
+	and when it begins executing
+	(i.e. when keyframes attached to 0% progress are mapped).
+
+	<dl dfn-for="animation-delay-start, animation-delay-end" dfn-type=value>
+		<dt><dfn><<time>></dfn>
+		<dd>
+			Defines the delay as a duration. See [[CSS-ANIMATIONS-1]].
+		<dt><dfn><<timeline-range-name>> <<percentage>></dfn>
+		<dd>
+			Calculates the delay as the difference between
+			the start of the animation
+			and the specified point on the [=timeline=].
+	</dl>
+
+	<pre class="propdef">
+		Name: animation-delay-end
+		Value: [ <<time>> | <<timeline-range-name>> <<percentage>>
+		Initial: 0s
+		Applies to: all elements
+		Inherited: no
+		Percentages: relative to the specified [=named timeline range=]
+		Computed value: list, each item either a duration or a timeline range and progress percentage
+		Animatable: no
+	</pre>
+
+	Defines a delay between the end of the animation
+	and when it ends executing
+	(i.e. when keyframes attached to 100% progress are mapped).
+	Values are as for 'animation-delay-start',
+	but calculating backwards from the end,
+	i.e. a ''2s'' delay effectively shortens the animation duration,
+	whereas ''-2s'' lengthens it.
+
+## Reporting Timeline Range Progress: the ''getTime()'' method ## {#named-range-getTime}
+
+	Progress through named ranges is exposed on the {{AnimationTimeline}} object
+	by the {{AnimationTimeline/getCurrentTime()}} method:
+
+	<pre class="idl">
+		[Exposed=Window]
+		interface AnimationTimeline {
+		  readonly attribute CSSNumberish? currentTime;
+		  CSSNumericValue? getCurrentTime(optional CSSOMString rangeName);
+		};
+	</pre>
+
+	<dl class=methods dfn-type=method dfn-for="AnimationTimeline">
+		<dt><dfn>getCurrentTime(rangeName)</dfn>
+		<dd>
+			If a rangeName is provided,
+			and is a valid [=named timeline range=] on this {{AnimationTimeline}},
+			returns the percentage progress through that range.
+
+			If a rangeName is provided,
+			and is not a valid [=named timeline range=] on this {{AnimationTimeline}},
+			returns null.
+
+			If a rangeName is not provided,
+			returns {{AnimationTimeline/currentTime}},
+			representing any time-based value using milliseconds (''ms'').
+	</dl>