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 1 commit
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
Prev Previous commit
Next Next commit
Moved all new definitions from web-animations-1 to web-animations-2
  • Loading branch information
@ydaniv
ydaniv committed May 11, 2024
commit f1d2e8929f0190b7363aa6edaeec337efa55ccf9
1 change: 1 addition & 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,7 @@ spec:web-animations-1; type:dfn;
text:start delay
text:target element
text:unresolved
spec:web-animations-2; type:dfn;
text:default range
text:exit range
</pre>
Expand Down
138 changes: 1 addition & 137 deletions web-animations-1/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ Repository: w3c/csswg-drafts
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/web-animations

Ignored Terms: double, boolean, unsigned long, unrestricted double, (unrestricted double or DOMString)
Ignored Vars: did seek, synchronously notify, auto-rewind, did trigger
Ignored Vars: did seek, synchronously notify, auto-rewind
Markup Shorthands: markdown yes
Include Mdn Panels: no
</pre>
Expand Down Expand Up @@ -3540,142 +3540,6 @@ Calculating progress {#core-animation-effect-calculations}
The final output <dfn>iteration progress</dfn> of an [=animation effect=]
is simply its [=transformed progress=].

Animation Triggers {#triggers}
-----------------

### Overview ### {#triggers-overview}

An <dfn export>animation trigger</dfn> is used to control the playback
of its associated [=animation=] for time-driven animations.
Like animations, [=animation triggers=] are associated with a [=timeline=]
and are attached to an [=animation attachment range|attachment range=].

Issue: Should there be any effect of triggers on scroll-driven animations?

### Animation Trigger State ### {#trigger-state}

An [=animation trigger=] |trigger| with [=animation trigger type=] |type|
and an associated [=animation=] |animation|
has an internal <dfn export lt="animation trigger state">state</dfn> that can be one of the following:

<dl dfn-for="animation trigger state" dfn-type=value>
<dt><dfn>idle</dfn>
<dd>
The [=animation effect=] associated |animation| remains in
its [=animation effect/before phase=] and stays at zero [=animation/start time=].

<dt><dfn>primary</dfn>
<dd>
The ''primary'' effect defined by |type| is applied to |animation|.

<dt><dfn>inverse</dfn>
<dd>
The ''inverse'' effect defined by |type| is applied to |animation|.

</dl>

Issue: Do we need a formal resolution on the spec of the idle state?

The [=animation trigger state=] |state| of an [=animation trigger=] |trigger|
is controlled by the [=animation attachment range|attachment range=] it is attached to,
given a flag |did trigger|, as follows:

<dl class=switch>
: If |trigger|’s [=local time=] is [=unresolved=],
::
Then |state| is ''animation trigger state/idle'', and |did trigger| is set to false.

: Otherwise,
::

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
Then |state| is ''animation trigger state/primary'', and |did trigger| is set to true.

: Otherwise,
::

<dl class=switch>
: If |did trigger| flag is false,
::
Then |state| is ''animation trigger state/idle''.

: Otherwise,
::
|state| is ''animation trigger state/inverse''.

</dl>

</dl>

</dl>

### Animation Trigger Types ### {#trigger-types}

The behavior an [=animation trigger=] applies to its associated [=animation=]’s
playback is defined by its <dfn export>animation trigger type</dfn>,
which can be one of the following:

<dl dfn-type=value dfn-for='animation trigger type'>
<dt><dfn>once</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.

<dt><dfn>repeat</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.
The ''inverse'' behavior is resetting the [=animation trigger state=] back to ''animation trigger state/idle''.

<dt><dfn>alternate</dfn>
<dd>
<dl class=switch>
: if the |did trigger| flag is false,
::
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.

: Otherwise,
::
The ''primary'' behavior is [=reverse an animation|reversing=] the associated animation.

</dl>

The ''inverse'' behavior is [=reverse an animation|reversing=] the associated animation.

<dt><dfn>state</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering or resuming=] the associated animation.
The ''inverse'' behavior is [=pause an animation|pausing=] the associated animation.
</dl>

Issue: Need to bike-shed the name for type "state" type.

### Animation Trigger Ranges ### {#trigger-ranges}

An [=animation trigger=] has at least one [=animation attachment range|range=],
its <dfn>default range</dfn>, which defines its [=active interval=].
This range defines when the [=animation trigger|trigger=] is in its ''animation trigger state/primary'' state,
as specified in [[#trigger-state]].

An [=animation trigger=] may also have a second [=animation attachment range|range=],
the <dfn>exit range</dfn>. The [=exit range=] is used to replace [=default range=] and extend
the [=active interval=] of an [=animation trigger=] |trigger| as follows:

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
It’s attached to its [=exit range=].

: Otherwise,
::
It’s attached to its [=default range=].

</dl>

Issue: Should we specify that that exit range’s edges can only be equal to or greater than the default range’s edges?

Issue: Do we need to specify the process for determining the effective attachment range in the HTML Processing Model?


<!-- End of timing model -->

Expand Down
139 changes: 138 additions & 1 deletion web-animations-2/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Abstract: This specification defines a model for synchronization and
specifications will define declarative means for exposing these
features.
Ignored Vars: auto-rewind, current direction, index, 5CC0 initial progress,
timeline, new timeline, t, going forwards
timeline, new timeline, t, going forwards, did trigger
</pre>
<pre class="anchors">
urlPrefix: https://drafts.csswg.org/web-animations-1/; type: dfn; spec: web-animations-1
Expand Down Expand Up @@ -122,6 +122,7 @@ urlPrefix: https://drafts.csswg.org/web-animations-1/; type: dfn; spec: web-anim
text: play an animation
text: playback direction
text: pause an animation
text: reverse an animation
text: ready
text: set the timeline of an animation
text: simple iteration progress
Expand Down Expand Up @@ -2353,6 +2354,142 @@ Items sorted earlier are executed before those sorted later.

</ins>

Animation Triggers {#triggers}
-----------------

### Overview ### {#triggers-overview}

An <dfn export>animation trigger</dfn> is used to control the playback
of its associated [=animation=] for time-driven animations.
Like animations, [=animation triggers=] are associated with a [=timeline=]
and are attached to an [=animation attachment range|attachment range=].

Issue: Should there be any effect of triggers on scroll-driven animations?

### Animation Trigger State ### {#trigger-state}

An [=animation trigger=] |trigger| with [=animation trigger type=] |type|
and an associated [=animation=] |animation|
has an internal <dfn export lt="animation trigger state">state</dfn> that can be one of the following:

<dl dfn-for="animation trigger state" dfn-type=value>
<dt><dfn>idle</dfn>
<dd>
The [=animation effect=] associated |animation| remains in
its [=animation effect/before phase=] and stays at zero [=animation/start time=].

<dt><dfn>primary</dfn>
<dd>
The ''primary'' effect defined by |type| is applied to |animation|.
Copy link
Contributor

Choose a reason for hiding this comment

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

There's a bit of a mismatch between this and the text in css-animations-2 where the text for single-animation-trigger-type specifies when the effect is applied. The text above implies that the effect is applied continually while in the state, but the text in single-animation-trigger-type implies that the effect is applied at a discrete moment in time. If all of the effects are discrete then I think it would be simpler to have the effect explicitly only invoked when the trigger's state changes.

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've tried making that more explicit in the text, LMK if that's good


<dt><dfn>inverse</dfn>
<dd>
The ''inverse'' effect defined by |type| is applied to |animation|.

</dl>

Issue: Do we need a formal resolution on the spec of the idle state?

The [=animation trigger state=] |state| of an [=animation trigger=] |trigger|
is controlled by the [=animation attachment range|attachment range=] it is attached to,
given a flag |did trigger|, as follows:
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 you need to say something about how when the current time of the trigger timeline is changed, we run the following steps. We also need to say how did trigger is stored, it's probably state associated with the animation trigger? E.g. if i assign a new trigger to an animation i probably want to reset the animation trigger.

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've refactored the text below into an algorithm text


<dl class=switch>
: If |trigger|’s [=local time=] is [=unresolved=],
::
Then |state| is ''animation trigger state/idle'', and |did trigger| is set to false.
Copy link
Contributor

Choose a reason for hiding this comment

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

Wouldn't setting did trigger to false this reset once triggers anytime the timeline goes idle (e.g. anytime a ScrollTimeline's scroller becomes large enough that it doesn't scroll)? I think this is probably unexpected.

Note, it doesn't look like these links, e.g. ''animation trigger state/idle'' have linked to the definitions correctly.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Interesting! I'm not sure whether this is unexpected. I guess we should open another issue for that.

Regarding the links, I'll check and fix.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Wouldn't setting did trigger to false this reset once triggers anytime the timeline goes idle (e.g. anytime a ScrollTimeline's scroller becomes large enough that it doesn't scroll)? I think this is probably unexpected.

Gave this another thought. I think this should be expected, but definitely worth opening an issue and discuss this explicitly.

Note, it doesn't look like these links, e.g. ''animation trigger state/idle'' have linked to the definitions correctly.

Right, appears as though these aren't linked correctly, but I used the suggested syntax, so not sure what to do.

Copy link
Contributor

Choose a reason for hiding this comment

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

On re-reading this, I realized the did trigger flag actually says nothing about whether it will retrigger once animations, and the text the definition for once says:

The animation is triggered and played once and only once.

Which implies that once animations are not retriggered by this, which I think addresses my primary concern.

I was thinking about whether resizing the scroller / browser such that the area is no longer scrollable should be treated differently than exiting the exit range? My thinking is it shouldn't be any different. You by definition can't be in the exit range. With this in mind I'm not exactly sure what did trigger is trying to accomplish other than perhaps giving different behavior to being outside the active range to start, and going inactive. If this is the case, I think we should just consider the previous state rather than introduce this did trigger variable. E.g. if you're outside the active range and you have no previous state or your previous state was idle, you're still idle.

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 did trigger flag is used to differentiate between the initial idle state and the rest of the primary/inverse states going in/out of active interval. Mostly because you always want the initial state to be a non-triggered animation and the rest can be anything else defined by type: running/paused, played/reversed, etc.

I think it's OK for it to be reset on cases like timeline becoming inactive or if setting to a new trigger.
So not sure whether the once and only once is actually called for.


: Otherwise,
::

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
Then |state| is ''animation trigger state/primary'', and |did trigger| is set to true.

: Otherwise,
::

<dl class=switch>
: If |did trigger| flag is false,
::
Then |state| is ''animation trigger state/idle''.

: Otherwise,
::
|state| is ''animation trigger state/inverse''.

</dl>

</dl>

</dl>

### Animation Trigger Types ### {#trigger-types}

The behavior an [=animation trigger=] applies to its associated [=animation=]’s
playback is defined by its <dfn export>animation trigger type</dfn>,
which can be one of the following:

<dl dfn-type=value dfn-for='animat 6968 ion trigger type'>
<dt><dfn>once</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.
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 this needs to define how the behavior is only applied once. E.g. the suggested triggered state associated with an animation, initially false

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 think this is covered in the new state updating algo, 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 suppose if the type is once and did trigger is true it should suffice to indicate that the state should not change, right?


<dt><dfn>repeat</dfn>
<dd>
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.
The ''inverse'' behavior is resetting the [=animation trigger state=] back to ''animation trigger state/idle''.

<dt><dfn>alternate</dfn>
<dd>
<dl class=switch>
: if the |did trigger| flag is false,
::
The ''primary'' behavior is [=play an animation|triggering=] the associated animation.

: Otherwise,
::
The ''primary'' behavior is [=reverse an animation|reversing=] the associated animation.

</dl>

The ''inverse'' behavior is [=reverse an animation|reversing=] the associated animation.

<dt><dfn>state</dfn>
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 something like play-pause would be clearer.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's another option. The idea behind state was a reference to play-state.

Copy link
Contributor

Choose a reason for hiding this comment

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

Right, I could see play-state as an alternative. State feels too strange, I didn't have any idea what this meant until I read the description :-).

<dd>
The ''primary'' behavior is [=play an animation|triggering or resuming=] the associated animation.
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 it would be more consistent if state only changes the animation play state, i.e. the animation would be started in a paused state until the active trigger range is entered.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Like I mentioned above, the idea was that when coming from idle state the animation is not triggered yet, and then upon entering primary state with did trigger: false the animation is triggered, and then only played/paused from that point.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Looking again at idle state's definition, it's already stating how the animation starts:

The [=animation effect=] associated |animation| remains in
its [=animation effect/before phase=] and stays at zero [=animation/start time=].

So currently this is consistent across all types.
You think it will still be confusing for the pause/play behavior?

The ''inverse'' behavior is [=pause an animation|pausing=] the associated animation.
</dl>

Issue: Need to bike-shed the name for type "state" type.

### Animation Trigger Ranges ### {#trigger-ranges}

An [=animation trigger=] has at least one [=animation attachment range|range=],
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 define a new term for the trigger interval's active range, as the combination of the two ranges would probably be worth eventually having a diagram to illustrate.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sounds good, I'll try adding that.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

done

its <dfn>default range</dfn>, which defines its [=active interval=].
This range defines when the [=animation trigger|trigger=] is in its ''animation trigger state/primary'' state,
as specified in [[#trigger-state]].

An [=animation trigger=] may also have a second [=animation attachment range|range=],
the <dfn>exit range</dfn>. The [=exit range=] is used to replace [=default range=] and extend
the [=active interval=] of an [=animation trigger=] |trigger| as follows:

<dl class=switch>
: If |trigger| is inside its [=active interval=],
::
It’s attached to its [=exit range=].

: Otherwise,
::
It’s attached to its [=default range=].

</dl>

Issue: Should we specify that that exit range’s edges can only be equal to or greater than the default range’s edges?

Issue: Do we need to specify the process for determining the effective attachment range in the HTML Processing Model?

<!-- End of animation model -->

<h2 id="programming-interface">Programming interface</h2>
Expand Down
0