8000 [css-animations-2] Specify the animation-trigger property by ydaniv · Pull Request #10128 · w3c/csswg-drafts · GitHub
[go: up one dir, main page]
Skip to content

[css-animations-2] Specify the animation-trigger property #10128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 23 commits into from
Jan 31, 2025
Merged

[css-animations-2] Specify the animation-trigger property #10128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
133f6e0
[css-animations-2] Specify the animation-trigger property
ydaniv Mar 25, 2024
f3a49ba
Fixed syntax of single-animation-trigger + some link fixes
ydaniv Mar 25, 2024
cbd4f07
More fixes to links and defs
ydaniv Mar 27, 2024
9f6464a
More fixes to links and defs
ydaniv Mar 28, 2024
912426a
Move all definitions to web-animations-1;
ydaniv Apr 17, 2024
9ae1a13
Fixed idle state definition for animation trigger state
ydaniv Apr 18, 2024
f1d2e89
Moved all new definitions from web-animations-1 to web-animations-2
ydaniv May 11, 2024
e55e476
Added a description to each property of animation-trigger;
ydaniv Jun 2, 2024
a0e90fe
Fixed some syntax errors
ydaniv Jun 6, 2024
361f5d9
Added an issue about timeline becoming idle and did-trigger resetting…
ydaniv Jun 6, 2024
efa38c7
Define animation trigger active interval
ydaniv Jun 6, 2024
085618e
Merge from main
ydaniv Jun 6, 2024
11e3138
Rewrite again according to review
ydaniv Jul 31, 2024
7777ac1
Added the AnimationTrigger interface;
ydaniv Aug 19, 2024
e3554e3
Update css-animations-2/Overview.bs
ydaniv Sep 29, 2024
cef7a04
Update css-animations-2/Overview.bs
ydaniv Sep 29, 2024
079135c
Update css-animations-2/Overview.bs
ydaniv Sep 29, 2024
65b0533
Removed reset of did trigger to false;
ydaniv Sep 29, 2024
5f2615b
Added missing attribute definition for animation trigger
ydaniv Nov 1, 2024
4109b39
Fixed the procedure of updating trigger state to be initially idle an…
ydaniv Nov 23, 2024
c8eb479
Add note to Animation Frames about running the updating animation tri…
ydaniv Nov 23, 2024
6a6bf45
Added algorythm for Setting a Trigger of an Animation;
ydaniv Jan 26, 2025
c74c5c3
Merge branch 'main' into animation-trigger
ydaniv Jan 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 279 additions & 0 deletions css-animations-2/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,13 @@ spec:web-animations-1; type:dfn;
text:start delay
text:target element
text:unresolved
spec:web-animations-2; type:dfn;
text:active interval; for:animation trigger
text:default range
text:exit range
spec:scroll-animations-1; type:dfn;
text:animation-range-start
text:animation-range-end
</pre>

<h2 id="delta">Delta specification</h2>
Expand Down Expand Up @@ -702,7 +709,279 @@ The 'animation' shorthand property syntax is as follows:

<span class=prod><dfn>&lt;single-animation></dfn> = <<'animation-duration'>> || <<easing-function>> || <<'animation-delay'>> || <<single-animation-iteration-count>> || <<single-animation-direction>> || <<single-animation-fill-mode>> || <<single-animation-play-state>> || [ none | <<keyframes-name>> ] || <<single-animation-timeline>></span>

<h2 id="animation-triggers">
Declaring Animation Triggers</h2>

Animation Triggers are defined using the 'animation-trigger-*' properties.
These list-valued properties,
which are all [=longhands=] of the 'animation-trigger' [=shorthand=],
form a [=coordinating list property group=]
with 'animation-name' as the [=coordinating list base property=]
and each item in the [=coordinated value list=]
defining the properties of a single animation trigger.

## The 'animation-trigger-type' property ## {#animation-trigger-type}

The 'animation-trigger-type' property specifies the [=animation trigger type=]
of the [=animation trigger=].

<pre class='propdef'>
Name: animation-trigger-type
Value: <<single-animation-trigger-type>>#
Initial: once
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item a keyword as specified
Animation type: not animatable
Canonical order: per grammar
</pre>

<span class=prod><dfn>&lt;single-animation-trigger-type></dfn> = once | repeat | alternate | state</span>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a description of what each property value means. Also we probably need a none value on this property to represent the default case right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was pondering all the none/normal/auto options, and I think we currently don't need them, since the initial value is once, with a timeline value of auto, which I think is exactly what we have today.
We could also add an issue on that, in case it needs an approval from the group.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The definition of the values is done here.
Should I add here another description? More user/less implementor facing?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was pondering all the none/normal/auto options, and I think we currently don't need them, since the initial value is once, with a timeline value of auto, which I think is exactly what we have today.

Yeah, I like having the default values basically explain the triggering behavior we get today and adding the ability to modify it. It makes it feel like less of an added on property and more just part of the standard animation infrastructure.

We could also add an issue on that, in case it needs an approval from the group.

I think this can be part of the general review when it's all written up.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a description of what each property value means.

Done


The values of 'animation-trigger-type' have the following meaning
for an [=animation trigger=] that enters its [=animation trigger/active interval|active interval=]:

<dl dfn-type=value dfn-for=animation-trigger-type>
<dt><dfn>once</dfn>
<dd>
The animation is triggered and played once and only once.

<dt><dfn>repeat</dfn>
<dd>
The animation is played from the beginning each time it is triggered.
When the trigger’s [=animation trigger/active interval=] is exited the animation is reset.

<dt><dfn>alternate</dfn>
<dd>
The animation is played forwards, according to its [=playback direction=], each time it is triggered.
When the trigger’s [=animation trigger/active interval=] is exited the animation is reversed.

<dt><dfn>state</dfn>
<dd>
The animation is triggered and played once.
When the trigger’s [=animation trigger/active interval=] is exited the animation is paused.
When the trigger’s [=animation trigger/active interval=] is re-entered the animation is resumed.
</dl>

The behavior of each value is defined in [[web-animations-2#trigger-types]].

## The 'animation-trigger-timeline' property ## {#animation-trigger-timeline}

The 'animation-trigger-timeline' property specifies the <a>timeline</a>
of the animation’s associated [=animation trigger=].

<pre class='propdef'>
Name: animation-trigger-timeline
Value: <<single-animation-timeline>>#
Initial: auto
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item either
the keyword ''single-animation-timeline/none'',
the keyword ''single-animation-timeline/auto'',
a case-sensitive [=css identifier=],
a computed ''scroll()'' function,
or
a computed ''view()'' function
Canonical order: per grammar
Animation Type: not animatable
</pre>

The values of 'animation-trigger-timeline' have the same meaning as those of 'animation-timeline'.

Issue: Probably a trigger with timeline "none" is under-specified here. Need to clarify what it means.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if the default timeline is the document timeline set up in a way such that the "trigger" is always active explaining the normal behavior of animations? You could imagine then using this as a way to coordinate starting an animation after some length of time, e.g. animation-trigger-range: 10s. Admittedly this has some overlap with animation-delay, but unlike animation delay could use absolute times since page load or other events I suppose?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I remember we considered this in a previous issue specifically on syncing animations, but we said there that this will be the stuff that will eventually be done via GroupEffects. That said, if you see some way of changing the definition here and keeping this more open for later extensions I'm all for it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but unlike animation delay could use absolute times since page load or other events I suppose?

I feel like we'll still the pseudo-selector you suggested in #8175, for example, to defer until DOM and assets are loaded. This is pretty common.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should remove the none state, I'm not sure what it even means and the initial value is auto so it's not clear what you'd use none for. With the initial value auto, as you've said it has the same meaning as values of animation-timeline and as such would map to the document timeline. I think we should try to go with this model as it explains the existing behavior.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, but none here is part of the single-animation-timeline syntax. Should we remove it just here? Or entirely?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see.. I suppose suppose we can keep it and I guess the animation would never start?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I guess it resets state back to idle.


## The 'animation-trigger-range' property ## {#animation-trigger-range}

<pre class="propdef shorthand">
Name: animation-trigger-range
Value: [ <<'animation-trigger-range-start'>> <<'animation-trigger-range-end'>>? ]#
</pre>

The 'animation-trigger-range' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-range-start' and 'animation-trigger-range-end'
together in a single declaration,
specifying the [=animation trigger=]’s associated [=default range=].
It has the same syntax as the 'animation-range' property.

The behavior of 'animation-trigger-range' is defined in [[web-animations-2#trigger-ranges]].

## The 'animation-trigger-range-start' property ## {#animation-trigger-range-start}

<pre class="propdef">
Name: animation-trigger-range-start
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-range-start/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-range-start' property specifies the start of the [=animation trigger=]’s
associated [=default range=].

The values of 'animation-trigger-range-start' have the same meaning as those of 'animation-range-start'.

## The 'animation-trigger-range-end' property ## {#animation-trigger-range-end}

<pre class="propdef">
Name: animation-trigger-range-end
Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: normal
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-range-end/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-range-end' property specifies the end of the [=animation trigger=]’s
associated [=default range=].

The values of 'animation-trigger-range-end' have the same meaning as those of 'animation-range-end'.

## The 'animation-trigger-exit-range' property ## {#animation-trigger-exit-range}

<pre class="propdef shorthand">
Name: animation-trigger-exit-range
Value: [ <<'animation-trigger-exit-range-start'>> <<'animation-trigger-exit-range-end'>>? ]#
</pre>

The 'animation-trigger-exit-range' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-exit-range-start' and 'animation-trigger-exit-range-end'
together in a single declaration,
specifying the [=animation trigger=]’s associated [=exit range=].
It has the same syntax as the 'animation-range' property, with the addition of the ''auto'' keyword.

The [=exit range=] replaces the [=default range=] once the [=animation trigger=]’s
[=animation trigger/active interval|active interval=] is entered,
and redefines the extent of the [=animation trigger=]’s [=animation trigger/active interval|active interval=].
It is used to extend the [=default range=], for example,
in cases where exiting the [=animation trigger/active interval|active interval=]
may create a visual jump that needs to be avoided.

The behavior of 'animation-trigger-exit-range' is further defined in [[web-animations-2#trigger-ranges]].

## The 'animation-trigger-exit-range-start' property ## {#animation-trigger-exit-range-start}

<pre class="propdef">
Name: animation-trigger-exit-range-start
Value: [ auto | normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: auto
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-exit-range-start/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-exit-range-start' property specifies the start of the [=animation trigger=]’s
associated [=exit range=].

The values of 'animation-trigger-exit-range-start' have the following meaning:

<dl dfn-for="animation-trigger-exit-range-start" dfn-type=value>
<dt><dfn>auto</dfn>
<dd>
The start of the trigger’s [=exit range=]
is equal to the start of its [=default range=].

<dt><dfn>normal</dfn>
<dd>
The start of the trigger’s [=exit range=]
is the start of its associated [=timeline=];
the start of the trigger’s [=animation trigger/active interval|active interval=]
is determined as normal.

<dt><dfn><<length-percentage>></dfn>
<dd>
The [=exit range=] starts
at the specified point on the [=timeline=]
measuring from the start of the timeline.

<dt><dfn><<timeline-range-name>> <<length-percentage>>?</dfn>
<dd>
The [=exit range=] starts
at the specified point on the [=timeline=]
measuring from the start of the specified [=named timeline range=].
If the <<length-percentage>> is omitted,
it defaults to 0%.
</dl>

## The 'animation-trigger-exit-range-end' property ## {#animation-trigger-exit-range-end}

<pre class="propdef">
Name: animation-trigger-exit-range-end
Value: [ auto | normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
Initial: auto
Applies to: all elements
Inherited: no
Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
Computed value: list, each item either the keyword ''animation-trigger-exit-range-end/normal'' or a timeline range and progress percentage
Animation type: not animatable
</pre>

The 'animation-trigger-exit-range-end' property specifies the end of the [=animation trigger=]’s
associated [=exit range=].

The values of 'animation-trigger-exit-range-start' have the following meaning:

<dl dfn-for="animation-trigger-exit-range-end" dfn-type=value>
<dt><dfn>auto</dfn>
<dd>
The end of the trigger’s [=exit range=]
is equal to the end of its [=default range=].

<dt><dfn>normal</dfn>
<dd>
The end of the trigger’s [=exit range=]
is the end of its associated [=timeline=];
the end of the trigger’s [=animation trigger/active interval|active interval=]
is determined as normal.

<dt><dfn><<length-percentage>></dfn>
<dd>
The [=exit range=] ends
at the specified point on the [=timeline=]
measuring from the start of the timeline.

<dt><dfn><<timeline-range-name>> <<length-percentage>>?</dfn>
<dd>
The [=exit range=] ends
at the specified point on the [=timeline=]
measuring from the start of the specified [=named timeline range=].
If the <<length-percentage>> is omitted,
it defaults to 100%.
</dl>

## The 'animation-trigger' property ## {#animation-trigger}

The 'animation-trigger' property is a [=shorthand property|shorthand=]
that sets 'animation-trigger-type', 'animation-trigger-timeline',
'animation-trigger-range-start', 'animation-trigger-range-end',
'animation-trigger-exit-range-start', and 'animation-trigger-exit-range-end'
together in a single declaration,
specifying the [=animation trigger=] for an animation.

<pre class='propdef'>
Name: animation-trigger
Value: <<single-animation-trigger>>#
Initial: see individual properties
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: see individual properties
Canonical order: per grammar
Animation Type: not animatable
</pre>

<pre class=prod>
<dfn>&lt;single-animation-trigger></dfn> = <<single-animation-trigger-type>> || [ none | auto | [ [ <<dashed-ident>> | <<scroll()>> | <<view()>> ] [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]{0,4} ] ]
</pre>

# Animation Events # {#events}

Expand Down
Loading
0