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

ydaniv · 2024-03-25T08:52:09Z

Adding initial draft for Animation Triggers and the animation-trigger property as resolved in #8942 (comment).

I cleared all the issues and fleshed out the gist of it.

flackr

Thanks for getting this started! I think some of the low level details of how an animation trigger affects the animation probably belong in web-animations-1 with the css-animations spec setting properties by which you set up those triggers declaratively. You should also of course be able to set the same properties from the web-animations api.

css-animations-2/Overview.bs

flackr · 2024-04-05T20:03:22Z

css-animations-2/Overview.bs

+An <dfn export>animation trigger</dfn> is used to control the playback
+of its associated [=animation=] for time-driven animations.
+[=Animation triggers=] follow the same [[web-animations-1#hierarchical|hierarchy]]
+as animations and are associated with a [=timeline=] and an [=animation trigger effect|effect=].


This makes it sound like animation triggers are separate things from animations, but I suspect we should say that as a part of updating the current time of animations we evaluate whether a trigger condition has been reached and apply a stateful change to the animation.

Sounds good. I'll work on that

flackr · 2024-04-05T20:04:23Z

css-animations-2/Overview.bs

+[=Animation triggers=] follow the same [[web-animations-1#hierarchical|hierarchy]]
+as animations and are associated with a [=timeline=] and an [=animation trigger effect|effect=].
+
+Issue: Should there be any effect of triggers on scroll-driven animations?


I suspect triggers on scroll-driven animations should "just work". E.g. they could play / stop the animation when the trigger condition occurs / finishes.

How does each type affects a scroll-driven animation?
Furthermore, what could be the actual use-case for this? Perhaps one that I can think of now is if we have a hover-timeline in the future and we want to enable/disable it on different scroll positions. Is that what you mean?

flackr · 2024-04-05T20:09:44Z

css-animations-2/Overview.bs

+  ::
+
+    <dl class=switch>
+      : If |effect| is inside its [=active interval=],


I think defining a trigger in terms of an internal animation effect's time might be overkill. E.g. I think we could define this simply in terms of the animation timeline's time with respect to the specified range

I struggled with that quite a bit. Eventually it worked out once I defined the same hierarchy as animations', and defined a special state for the effect. I'll try simplifying this further.

flackr · 2024-04-05T20:12:30Z

css-animations-2/Overview.bs

+
+Issue: Should there be any effect of triggers on scroll-driven animations?
+
+##  Animation Trigger Effects ## {#trigger-effects}


I think the internal control of how triggers work probably belongs in web-animations where we define things like how an updated time updates corresponding animations: https://drafts.csswg.org/web-animations-1/#update-animations-and-send-events

We should also be able to set up animation triggers from javascript.

OK, sure. We didn't discuss the WAAPI part of triggers in the issue, should I try fleshing that too in this PR? Or you're just stating this as a reason for this change?

birtles · 2024-04-16T06:16:16Z

@ydaniv Thanks for doing this. I started going through it today but I was a little confused about the hierarchy of components from the Web Animations API point-of-view. It sounds like we have the following parts:

Animation trigger timeline (currently a DocumentTimeline but possibly scroll-driven timelines too)
Animation trigger
Animation trigger effect
Animation

What is the relationship between them? Do the Animation trigger and Animation share an effect? Is the Animation trigger connected directory to the Animation trigger effect or only via the Animation? Is the Animation attached to the Animation trigger timeline or just the Animation trigger?

Sorry, I'm probably being really daft here but I couldn't grasp how the pieces fit together.

Defining some of these primitives as Web Animations constructs like @flackr suggested might help clarify how they fit together.

ydaniv · 2024-04-16T19:37:04Z

@birtles thanks for reviewing!

The intention of the hierarchy was mostly to simplify the spec, by having triggers follow animations as in:
For animations: timeline -> animation -> effect
For triggers: timeline -> trigger -> effect
And since effects are attached to attachment ranges, have trigger follow the same mechanism.

The idea was that they don't share anything, just follow the same structure, and the trigger simply affects the animation's playback according to its properties and state.

But, as @flackr mentioned, it's still too confusing and too complex, so I'll try and rewrite this without the effect part, and only with a trigger attached to a timeline and a range.

I've tried defining the constructs first in the initial draft. I'll move those into the Web Animations spec as suggested, and try to organize them together again in a simpler way.

birtles · 2024-04-17T05:37:21Z

The intention of the hierarchy was mostly to simplify the spec, by having triggers follow animations as in:
For animations: timeline -> animation -> effect
For triggers: timeline -> trigger -> effect
And since effects are attached to attachment ranges, have trigger follow the same mechanism.

The idea was that they don't share anything, just follow the same structure, and the trigger simply affects the animation's playback according to its properties and state.

Makes sense!

But, as @flackr mentioned, it's still too confusing and too complex, so I'll try and rewrite this without the effect part, and only with a trigger attached to a timeline and a range.

Ok, I'll look forward to seeing what you come up with!

Removed dfn of animation trigger effect

ydaniv · 2024-04-17T11:21:29Z

@flackr @birtles I've just pushed changes, I think I've covered all the comments, thanks!

birtles · 2024-04-18T01:31:48Z

web-animations-1/Overview.bs

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


I still don't quite get the hierarchy here. This suggests an animation effect is associated with a trigger but previous we said a trigger is associated with an animation. Which is it?

Right, the relation here should be indirect via the animation. The trigger is associated to the animation. The required behavior of the animation is to "hold its effect in a 'just before playing' state". I'll try to fix that.

Done, I think it's better now.

ydaniv · 2024-05-01T20:57:44Z

kind ping @birtles @flackr, ready for another review.

birtles · 2024-05-03T02:23:38Z

kind ping @birtles flackr, ready for another review.

@ydaniv Sorry for the delay--currently on parental leave. Just a few meta points:

I think this should be part of Web Animations level 2. Level 1 is basically done except for fixing existing issues (most notably the commitStyles changes we agreed to but I've yet to edit in).
I think we need to define the API parts for triggers?
We probably need to review all the descriptions about timelines and animations to make sure it accounts for triggers. (e.g. the sentence "Updating the current time of any animations associated with the timeline." should probably refer to triggers too?)

ydaniv · 2024-05-03T14:53:02Z

Thanks @birtles!

currently on parental leave

Congrats ^_^!

I think this should be part of Web Animations level 2.

Ok, I also wondered about that, but @flackr wrote Web Animations 1, and some things I needed to update were actually there, so not sure whether this was intentional or not.

I think we need to define the API parts for triggers?

You mean the DOM interfaces, as in here?

We probably need to review all the descriptions about timelines and animations to make sure it accounts for triggers. (e.g. the sentence "Updating the current time of any animations associated with the timeline." should probably refer to triggers too?)

I've added this text to that section:

Updating the [=animation trigger state=] of any [=animation trigger=]
[=associated with a timeline|associated with=] the timeline.

Shouldn't this cover it? I think basically comes down to checking triggers state on timeline's current time update.

birtles · 2024-05-04T02:43:06Z

currently on parental leave

Congrats ^_^!

Thanks!

I think this should be part of Web Animations level 2.

Ok, I also wondered about that, but @flackr wrote Web Animations 1, and some things I needed to update were actually there, so not sure whether this was intentional or not.

Yeah, that would be good to know. My understanding is it should be level 2 but maybe @flackr has some ideas about that.

I think we need to define the API parts for triggers?

You mean the DOM interfaces, as in here?

I was thinking about the Web Animations DOM interfaces. Just like we have the Animation interface I assume we'll have an AnimationTrigger interface?

That also makes me wonder how authors would expect to be able to inspect these from script. Is there some way to fetch the triggers in a document? Or the trigger driving a particular Animation?

We probably need to review all the descriptions about timelines and animations to make sure it accounts for triggers. (e.g. the sentence "Updating the current time of any animations associated with the timeline." should probably refer to triggers too?)

I've added this text to that section:

Updating the [=animation trigger state=] of any [=animation trigger=]
[=associated with a timeline|associated with=] the timeline.

Shouldn't this cover it? I think basically comes down to checking triggers state on timeline's current time update.

Yeah, I was thinking that we need to review the whole section to check for other references that need to be updated like the sentence I mentioned and other definitions like this one:

An animation effect, effect, is associated with a timeline, timeline, if effect is associated with an animation which, in turn, is associated with timeline.

Presumably that needs to be updated to include triggers too?

This is a pretty fundamental change to the whole timing hierarchy so we need to be careful about it. I wonder if it would be better to introduce an abstract concept that covers both animations and animation triggers like "timeline subscribers" or somesuch.

ydaniv · 2024-05-05T16:39:55Z

I was thinking about the Web Animations DOM interfaces. Just like we have the Animation interface I assume we'll have an AnimationTrigger interface?

I opened an issue with a rough proposal here.
I could add that in already, as an initial proposal for API. I thought to wait with that for a later PR, since we only resolved on adding an initial draft and going with it back to the group for approval.

That also makes me wonder how authors would expect to be able to inspect these from script. Is there some way to fetch the triggers in a document? Or the trigger driving a particular Animation?

I missed that part, I guess I could add that in. Regarding additional APIs, like getting all triggers from document, I guess we could always add these later on demand?

Yeah, I was thinking that we need to review the whole section to check for other references that need to be updated like the sentence I mentioned and other definitions like this one:

An animation effect, effect, is associated with a timeline, timeline, if effect is associated with an animation which, in turn, is associated with timeline.

Presumably that needs to be updated to include triggers too?

I checked everything and didn't find anything else. I think since triggers only affect playback state and are associated with a timeline, it should be enough to check/update their state according to the timeline, since the trigger's spec describes what to do on state change.

This is a pretty fundamental change to the whole timing hierarchy so we need to be careful about it. I wonder if it would be better to introduce an abstract concept that covers both animations and animation triggers like "timeline subscribers" or somesuch.

Agreed. I tried simplifying it on the last change.

flackr · 2024-05-10T14:05:25Z

Ok, I also wondered about that, but @flackr wrote Web Animations 1, and some things I needed to update were actually there, so not sure whether this was intentional or not.

Yeah, that would be good to know. My understanding is it should be level 2 but maybe @flackr has some ideas about that.

Sorry if I created some confusion here. I was mostly getting at that the concepts that need updating are in the web-animations-1 spec, but of course additions to the spec should go in web-animations-2.

flackr

Sorry for the delay on the review. Thanks for putting this together!

flackr · 2024-05-13T15:45:26Z

css-animations-2/Overview.bs

+Canonical order: per grammar
+</pre>
+
+<span class=prod><dfn>&lt;single-animation-trigger-type></dfn> = once | repeat | alternate | state</span>


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?

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.

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

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.

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

Done

flackr · 2024-05-13T15:49:05Z

css-animations-2/Overview.bs

+Animation Type: not animatable
+</pre>
+
+Issue: Probably a trigger with timeline "none" is under-specified here. Need to clarify what it means.


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?

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.

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.

flackr · 2024-05-13T17:07:47Z

css-animations-2/Overview.bs

+    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.


If this spec doesn't explain how they work but only mentions the relevant properties, it should point to the section in the web-animations-2 spec which explains what animation triggers are and how they work. E.g. this could be as simple as having "animation triggers" link to the section in web animations, similar to how the animation composition property points to the web-animations definition of what a composite operation is.

That said, it's not uncommon to have a plain English explanation for what it means with the details and algorithms left to web-animations. E.g. to take a random property the definition of animation-fill-mode explains what it does without going into the specific algorithmic details that are in the web-animations spec.

I like both. I guess I'll refactor the text a bit and add a link.

flackr · 2024-05-14T19:25:48Z

web-animations-1/Overview.bs

@@ -772,6 +772,9 @@ Animation Frames {#animation-frame-loop}
          * Updating the [=animation/current time=] of any [=animations=]
              [=associated with a timeline|associated with=] the timeline.

+          * Updating the [=animation trigger state=] of any [=animation trigger=]
+              [=associated with a timeline|associated with=] the timeline.


This can move to web-animations-2 right? Also I think this needs to happen before updating the times of animations so that we can set their start time and know to make their effects active if they've been triggered.

Well the animation-frame-loop definition exists only here, and I had to only add this one bullet. So what would be the proper way to add it to web-animations-2? Should I add just this delta somehow? Another way?

Regarding order, yes, I'll pull it up to happen before updating animations.

Yeah, we'd add a delta for this section to the ewb-animations-2 spec.

flackr · 2024-05-14T20:27:05Z

web-animations-2/Overview.bs

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


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.

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.

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.

flackr · 2024-05-14T20:40:07Z

web-animations-2/Overview.bs

+
+### Animation Trigger Ranges ### {#trigger-ranges}
+
+An [=animation trigger=] has at least one [=animation attachment range|range=],


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.

Sounds good, I'll try adding that.

flackr · 2024-05-14T20:41:48Z

web-animations-2/Overview.bs

+
+    The ''inverse'' behavior is [=reverse an animation|reversing=] the associated animation.
+
+  <dt><dfn>state</dfn>


I wonder if something like play-pause would be clearer.

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

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 :-).

Moved the delta of animation-frame-loop from web-animations-1 to web-animations-2

… to false

ydaniv · 2024-06-06T20:17:47Z

@flackr finished addressing all comments from last review

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

133f6e0

ydaniv added the css-animations-2 label Mar 25, 2024

ydaniv requested review from flackr and birtles March 25, 2024 09:09

ydaniv added 3 commits March 26, 2024 00:23

Fixed syntax of single-animation-trigger + some link fixes

f3a49ba

More fixes to links and defs

cbd4f07

More fixes to links and defs

9f6464a

ydaniv marked this pull request as ready for review March 28, 2024 11:57

flackr reviewed Apr 5, 2024

View reviewed changes

Move all definitions to web-animations-1;

912426a

Removed dfn of animation trigger effect

birtles reviewed Apr 18, 2024

View reviewed changes

Fixed idle state definition for animation trigger state

9ae1a13

Moved all new definitions from web-animations-1 to web-animations-2

f1d2e89

flackr requested changes May 14, 2024

View reviewed changes

ydaniv added 5 commits June 2, 2024 22:57

Added a description to each property of animation-trigger;

e55e476

Moved the delta of animation-frame-loop from web-animations-1 to web-animations-2

Fixed some syntax errors

a0e90fe

Added an issue about timeline becoming idle and did-trigger resetting…

361f5d9

… to false

Define animation trigger active interval

efa38c7

Merge from main

085618e


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

		## Animation Trigger Effects ## {#trigger-effects}

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


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

		An [=animation trigger=] has at least one [=animation attachment range\|range=],


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

		<dt><dfn>state</dfn>

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

Are you sure you want to change the base?

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

Conversation

ydaniv commented Mar 25, 2024 • edited

flackr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

birtles commented Apr 16, 2024

ydaniv commented Apr 16, 2024

birtles commented Apr 17, 2024

ydaniv commented Apr 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ydaniv commented May 1, 2024

birtles commented May 3, 2024

ydaniv commented May 3, 2024

birtles commented May 4, 2024

ydaniv commented May 5, 2024

flackr commented May 10, 2024

flackr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ydaniv commented Jun 6, 2024

ydaniv commented Mar 25, 2024 •

edited