Skip to content

Commit

Permalink
[scroll-animations-1] Define named view timeline phases and their usa…
Browse files Browse the repository at this point in the history 
…ge. #7044
  • Loading branch information
@fantasai
fantasai committed Sep 15, 2022
1 parent 3f5b834 commit 2152a23
Showing 1 changed file with 196 additions and 0 deletions.
196 changes: 196 additions & 0 deletions scroll-animations-1/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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>>

This comment has been minimized.

Sign in to view

Copy link
@cdoublev

cdoublev Sep 20, 2022 •
edited
Loading

Collaborator

Can you please add the range notation to <percentage>, as defined in CSS Animations? Values less than 0% or higher than 100% are invalid and cause their <keyframe-block> to be ignored.

w3c/webref now extracts this value definition instead of the one from CSS Animations, which means (for me) that related tests are now failing.

Aside: the <<timeline-range-name> below is missing a >.
</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>

0 comments on commit 2152a23

Please sign in to comment.