8000 [scroll-animations-1] Define named view timeline phases and their usa… · w3c/csswg-drafts@2152a23 · GitHub
Skip to content

Commit 2152a23

Browse files
fantasaifantasai
committed
[scroll-animations-1] Define named view timeline phases and their usage. #7044 
1 parent 3f5b834 commit 2152a23

File tree

1 file changed

+196
-0
lines changed

1 file changed

+196
-0
lines changed

‎scroll-animations-1/Overview.bs

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -347,6 +347,59 @@ spec: cssom-view-1; type: dfn;
347347
In the Web Animations API,
348348
they can be represented anonymously by a {{ViewTimeline}} object.
349349

350+
## View Progress Timeline Ranges ## {#view-timelines-ranges}
351+
352+
[=View progress timelines=] define the following [=named timeline ranges=]:
353+
354+
<dl dfn-for="animation-timeline-range" dfn-type="value">
355+
<dt><dfn>cover</dfn>
356+
<dd>
357+
Represents the full range of the [=view progress timeline=]:
358+
* 0% progress represents the position at which
359+
the [=start=] [=border edge=] of the element’s [=principal box=]
360+
coincides with the [=end=] edge of its [=view progress visibility range=].
361+
* 100% progress represents the position at which
362+
the [=end=] [=border edge=] of the element’s [=principal box=]
363+
coincides with the [=start=] edge of its [=view progress visibility range=].
364+
365+
<dt><dfn>contain</dfn>
366+
<dd>
367+
Represents the range during which the [=principal box=]
368+
is either fully contained by, or fully covers,
369+
its [=view progress visibility range=] within the [=scrollport=].
370+
* 0% progress represents the earlier position at which:
371+
* the [=start=] [=border edge=] of the element’s [=principal box=]
372+
coincides with the [=start=] edge of its [=view progress visibility range=].
373+
* the [=end=] [=border edge=] of the element’s [=principal box=]
374+
coincides with the [=end=] edge of its [=view progress visibility range=].
375+
* 100% progress represents the later position at which:
376+
* the [=start=] [=border edge=] of the element’s [=principal box=]
377+
coincides with the [=start=] edge of its [=view progress visibility range=].
378+
* the [=end=] [=border edge=] of the element’s [=principal box=]
379+
coincides with the [=end=] edge of its [=view progress visibility range=].
380+
381+
<dt><dfn>entry</dfn>
382+
<dd>
383+
Represents the range during which the [=principal box=]
384+
is entering the [=view progress visibility range=].
385+
* 0% is equivalent to 0% of the ''animation-timeline-range/cover'' range.
386+
* 100% is equivalent to 0% of the ''animation-timeline-range/contain'' range.
387+
388+
ISSUE: Should this be ''entry'' or ''enter''?
389+
390+
<dt><dfn>exit</dfn>
391+
<dd>
392+
Represents the range during which the [=principal box=]
393+
is exiting the [=view progress visibility range=].
394+
* 0% is equivalent to 100% of the ''animation-timeline-range/contain'' range.
395+
* 100% is equivalent to 100% of the ''animation-timeline-range/cover'' range.
396+
</dl>
397+
398+
ISSUE: Insert diagrams.
399+
400+
In all cases, the [=writing mode=] used to resolve the [=start=] and [=end=] sides
401+
is the [=writing mode=] of the relevant [=scroll container=].
402+
350403
## Anonymous View Progress Timelines ## {#view-timelines-anonymous}
351404

352405
### The {{ViewTimeline}} Interface ### {#viewtimeline-interface}
@@ -602,3 +655,146 @@ spec: cssom-view-1; type: dfn;
602655
In such cases, the rendered scroll offset
603656
and the state of a scroll-driven animation
604657
may be inconsistent in the composited frame.
658+
659+
# Appendix A: Named Timeline Ranges # {#timeline-ranges}
660+
661+
ISSUE: This section should move to CSS-ANIMATIONS-2 and WEB-ANIMATIONS-2.
662+
663+
This specification introduces the concept of [=named timeline ranges=]
664+
to <a href="https://www.w3.org/TR/css-animations/">CSS Animations</a>
665+
and <a href="https://www.w3.org/TR/web-animations/">Web Animations</a>.
666+
667+
A <dfn export>named timeline range</dfn>
668+
is a named segment of an animation [=timeline=].
669+
The start of the segment is represented as 0% progress through the range;
670+
the end of the segment is represented as 100% progress through the range.
671+
Multiple [=named timeline ranges=] can be attached to a given [=timeline=],
672+
and multiple such ranges can overlap.
673+
For example, the ''animation-timeline/contain'' range of a [=view progress timeline=]
674+
overlaps with its ''animation-timeline/cover'' range.
675+
[=Named timeline ranges=] are represented by
676+
the <dfn><<timeline-range-name>></dfn> value type,
677+
which indicates a [=CSS identifier=] representing
678+
one of the predefined [=named timeline ranges=].
679+
680+
Note: In this specification, [=named timeline ranges=]
681+
must be defined to exist by a specification
682+
such as [[SCROLL-ANIMATIONS-1]].
683+
A future level may introduce APIs for authors to declare
684+
their own custom [=named timeline ranges=].
685+
686+
## Named Timeline Range Keyframe Selectors ## {#named-range-keyframes}
687+
688+
[=Named timeline range=] names and percentages
689+
can be used to attach keyframes
690+
to specific progress points within the [=named timeline range=].
691+
The CSS ''@keyframes'' rule is extended thus:
692+
693+
<pre class="prod">
694+
<<keyframe-selector>> = from | to | <<percentage>> | <<timeline-range-name>> <<percentage>>
695+
</pre>
696+
697+
where <<timeline-range-name> is the [=CSS identifier=]
698+
that represents a chosen predefined [=named timeline range=],
699+
and the <<percentage>> after it represents the percentage progress
700+
between the start and end of that [=named timeline range=].
701+
702+
Keyframes are attached to the specified point in the timeline.
703+
If the timeline does not have a corresponding [=named timeline range=],
704+
then any keyframes attached to points on that [=named timeline range=]
705+
are ignored.
706+
707+
## Attaching Animations to Timeline Ranges ## {#named-range-animation-declaration}
708+
709+
A set of animation keyframes can be attached
710+
in reference to [=named timeline ranges=]
711+
by adjusting the duration of the animation.
712+
713+
<pre class="propdef shorthand">
714+
Name: animation-delay, animation-range
715+
Value: [ <<'animation-delay-start'>> <<'animation-delay-end'>>? | <<timeline-range-name>> ]#
716+
</pre>
717+
718+
The 'animation-delay' and 'animation-range' properties
719+
are both [=shorthand property|shorthands=]
720+
that set 'animation-delay-start' and 'animation-delay-end'
721+
together in a single declaration.
722+
If the <<'animation-delay-end'>> value is omitted,
723+
it is set to zero.
724+
If a <<timeline-range-name>> alone is specified,
725+
'animation-delay-start' is set to that name plus ''0%''
726+
and 'animation-delay-end' is set to that name plus ''100%''.
727+
728+
<pre class="propdef">
729+
Name: animation-delay-start
730+
Value: [ <<time>> | <<timeline-range-name>> <<percentage>>
731+
Initial: 0s
732+
Applies to: all elements
733+
Inherited: no
734+
Percentages: relative to the specified [=named timeline range=]
735+
Computed value: list, each item either a duration or a timeline range and progress percentage
736+
Animatable: no
737+
</pre>
738+
739+
Defines a delay between the start of the animation
740+
and when it begins executing
741+
(i.e. when keyframes attached to 0% progress are mapped).
742+
743+
<dl dfn-for="animation-delay-start, animation-delay-end" dfn-type=value>
744+
<dt><dfn><<time>></dfn>
745+
<dd>
746+
Defines the delay as a duration. See [[CSS-ANIMATIONS-1]].
747+
<dt><dfn><<timeline-range-name>> <<percentage>></dfn>
748+
<dd>
749+
Calculates the delay as the difference between
750+
the start of the animation
751+
and the specified point on the [=timeline=].
752+
</dl>
753+
754+
<pre class="propdef">
755+
Name: animation-delay-end
756+
Value: [ <<time>> | <<timeline-range-name>> <<percentage>>
757+
Initial: 0s
758+
Applies to: all elements
759+
Inherited: no
760+
Percentages: relative to the specified [=named timeline range=]
761+
Computed value: list, each item either a duration or a timeline range and progress percentage
762+
Animatable: no
763+
</pre>
764+
765+
Defines a delay between the end of the animation
766+
and when it ends executing
767+
(i.e. when keyframes attached to 100% progress are mapped).
768+
Values are as for 'animation-delay-start',
769+
but calculating backwards from the end,
770+
i.e. a ''2s'' delay effectively shortens the animation duration,
771+
whereas ''-2s'' lengthens it.
772+
773+
## Reporting Timeline Range Progress: the ''getTime()'' method ## {#named-range-getTime}
774+
775+
Progress through named ranges is exposed on the {{AnimationTimeline}} object
776+
by the {{AnimationTimeline/getCurrentTime()}} method:
777+
778+
<pre class="idl">
779+
[Exposed=Window]
780+
interface AnimationTimeline {
781+
readonly attribute CSSNumberish? currentTime;
782+
CSSNumericValue? getCurrentTime(optional CSSOMString rangeName);
783+
};
784+
</pre>
785+
786+
<dl class=methods dfn-type=method dfn-for="AnimationTimeline">
787+
<dt><dfn>getCurrentTime(rangeName)</dfn>
788+
<dd>
789+
If a rangeName is provided,
790+
and is a valid [=named timeline range=] on this {{AnimationTimeline}},
791+
returns the percentage progress through that range.
792+
793+
If a rangeName is provided,
794+
and is not a valid [=named timeline range=] on this {{AnimationTimeline}},
795+
returns null.
796+
797+
If a rangeName is not provided,
798+
returns {{AnimationTimeline/currentTime}},
799+
representing any time-based value using milliseconds (''ms'').
800+
</dl>

0 commit comments

Comments
 (0)