[web-animations-2][css-animations-2] animation-trigger CSS syntax

[DavMila]

In #12336, we resolved to use separate namespaces for different types of animation triggers, i.e. event-trigger-* and timeline-trigger-*. We still need to work out what properties/longhands exist within the namespaces.

The conversation continued in #12611 where the most recent suggestion uses a generic trigger() function and custom/higher-level action names that group the raw actions (option 1):

.event_source {
  event-trigger-name: --event-source;
  event-trigger-actions: --click-touch click touch --press-p keypress("p");
  /* the --event-source event trigger defined two named actions, --click-touch and --press-p. */
}
.event_target {
  animation: glow;
  animation-trigger: trigger(--event-source, --click-touch play-pause, --press-p play, keypress("r") reset);
  /* can refer to multiple trigger actions, either by "action name" or directly */
}

.timeline_source {
  timeline-trigger: --view-trigger view() contain;
}
.timeline_target {
  animation-trigger: trigger(--view-trigger, enter play-forwards, exit play-backwards);
}

A few alternatives we can consider are:

• option 2: Instead of a generic trigger() function, have animation-trigger use event() and timeline() functions which have different "signatures."

<single-animation-trigger>: event(<dashed ident>, <behavior>) | timeline(<dashed ident>, <entry behavior>, <exit behavior>);
animation-trigger: [ [ <single-animation-trigger>]+ ]#

For example:

.event_source { 
  event-trigger: --click-touch-trigger click touch, --dblclick-trigger dblclick;
}
.event_target {
  animation-trigger: event(--click-touch-trigger, play) event(--dblclick-trigger, pause);
}
.timeline_source {
  timeline-trigger: --timeline-trigger view contain;
}
.timeline_target {
  animation-trigger: timeline(--timeline-trigger, play-forwards, play-backwards);
}

option 3: Put the actions/behavior configurations within the event-trigger-* and timeline-trigger-* namespaces. This is the second alternative in flackr's suggestion from #12336.

Proposed Solution: Keep the generic trigger() function along with custom/higher-level action names (option 1).
Three important properties of option 1 are that:

• (a) it preserves the fact that timeline-trigger's "exit" and "enter" are paired,
• (b) it's flexible in that it allows actions to be specified on either the source or the target, and
• (c) by keeping behaviors in animation-trigger, event-trigger and timeline-trigger are conceptually reusable in a non-animation contexts.

Option 2 lacks the flexibility of (b). Option 3 lacks the flexibility (b) and the reusability of (c) (sort of).

@flackr @ydaniv @fantasai @szager-chromium @tabatkins , ptal, thanks.

[szager-chromium]

Isn't it problematic to end a production rule with ]# ]# ? How can you determine the affinity of commas?

[DavMila]

Isn't it problematic to end a production rule with ]# ]# ? How can you determine the affinity of commas?

I think it would be problematic. I've updated the grammars:

Old: animation-trigger: <single-animation-trigger> [<space> <single-animation-trigger>]# [, <single-animation-trigger> [<space> <single-animation-trigger>]# ]#

New: animation-trigger: [ [ <single-animation-trigger>]+ ]#

I'm not sure if it can be copy-pasted into spec yet but I was going for "comma separated list of space-separated lists", so I hope that's clear enough now.

[ydaniv]

I though about this a bit more, I also don't see any difference between allowing viewenter/viewleave events and allowing arbitrary enter/exit actions and/or multiple timeline triggers, or together with event triggers. Unless I'm missing something, this goes back to the same issues that @flackr said we want to prevent.

So if I understand this correctly, unless we solve multiple timelines' enter/leave events, we have to restrict triggers to either being a single timeline trigger, or multiple (or single) event triggers. And this leads us closer to option 2 in your (@DavMila) suggestions.
I also don't think we need to have 2 names scoped to an element to create a binding, but I see you already addressed that here, which is great.

---

However, one thing I want to regress to is the higher-level behaviors we started with, as in once, repeat, alternate, and state. I really don't think we have any valid use-cases for splitting those, or mix and matching stuff like reset and pause.
I strongly believe not starting with triggers simply playing an animation by default, and have a matching invert action, could be a bad design, even a footgun, especially when we're just starting with level 1 of this feature.
And I think we can start with a syntax that will allow later enhancement with the broken-down actions later if necessary.

---

So, with all the above in mind I think the syntax for the event-trigger shorthand becomes simply:

event-trigger: [ <dashed-ident> <type>+ ]#

And the timeline-trigger shorthand becomes:

timeline-trigger: [ <dashed-ident> <single-animation-timeline> [ <timeline-range-start> <timeline-range-end>? ]? [ / [ <timeline-range-start> <timeline-range-end>? ]? ]? ]#

And the animation-trigger shorthand becomes:

<event-trigger>: <dashed-ident>+ [ / <dashed-ident>+ ]?, <trigger-behavior>?
<timeline-trigger>: <dashed-ident>, <trigger-behavior>?
<single-animation-trigger>: event-trigger(<event-trigger>) | timeline-trigger(<timeline-trigger>)

animation-trigger: <single-animation-trigger>#

You can see that:

• event-trigger simply becomes a coordinated list of names and a space separated list of event types.
• timeline-trigger becomes a coordinated list of names, timelines, and ranges.
• animation-trigger becomes a coordinated list of a single function, either event or timeline.
• The timeline-trigger() function allows a single timeline trigger with enter/exit tied implicitly to same trigger, and hence to a single timeline, and can't be used with another event trigger - plus a behavior.
• The event-trigger() function allows a space separated list of entry triggers (at least one), and optionally a space separated list of exit (i.e. reverse/reset/pause) triggers - plus a behavior.

I think this proposal allows everything we wanted to allow for level 1 while avoiding the issues.
And I think it also allows us to later develop this in other directions.

[flackr]

So if I understand this correctly, unless we solve multiple timelines' enter/leave events, we have to restrict triggers to either being a single timeline trigger

The reason viewenter / viewleave made this difficult is if the developer specifies different ranges, viewleave could fire without ever firing viewenter, or viewenter could fire twice without firing viewleave. The intention of having a different leave range was to only get another enter effect if you fully leave the exit area.

With any of the approaches where we specify the enter and exit range on a named view timeline and then reference those events for that timeline, we can ensure that these events are paired for that timeline. If a developer chooses not to use those paired events that is fine, but at least we have made it easy to do the right thing.

TLDR, we do not have to restrict triggers to being a single timeline trigger, but we should make it possible/easy to create enter/leave triggering events that are correctly paired.

[flackr]

However, one thing I want to regress to is the higher-level behaviors we started with, as in once, repeat, alternate, and state. I really don't think we have any valid use-cases for splitting those, or mix and matching stuff like reset and pause.
I strongly believe not starting with triggers simply playing an animation by default, and have a matching invert action, could be a bad design, even a footgun, especially when we're just starting with level 1 of this feature.

We decided to split these into animation-specific actions specifically because event triggers are not paired, and so breaking the inverting part of the behaviors into actions allows for doing the same things with either event triggers or timeline triggers.

I think we've covered this previously, and as discussed at tpac, these behaviors can be achieved by having animation play state dependent actions:

1. once can be implemented with a play-once action that will only play the animation if it is paused.
2. repeat is a play action that plays the animation if it is paused or finished, and a corresponding reset or finish action on exit to immediately finish the animation.
3. alternate is a play-reversed action that will play the animation if it is in the paused state, and reverse it if it is finished.
4. state is a play action on entry, and a pause action on exit.

[flackr]

these behaviors can be achieved by having animation play state dependent actions

@tabatkins had even suggested we may want to consider these convenience keywords for defining a trigger action where a developer can specify what should happen in each play state to allow maximum configurability.

[ydaniv]

With any of the approaches where we specify the enter and exit range on a named view timeline and then reference those events for that timeline, we can ensure that these events are paired for that timeline. If a developer chooses not to use those paired events that is fine, but at least we have made it easy to do the right thing.

Ok, I recall now, thanks (:
So this isn't a hard constraint, right? More of a way to simplify using timelines?

So if I understand this correctly, unless we solve multiple timelines' enter/leave events, we have to restrict triggers to either being a single timeline trigger

The reason viewenter / viewleave made this difficult is if the developer specifies different ranges, viewleave could fire without ever firing viewenter, or viewenter could fire twice without firing viewleave. The intention of having a different leave range was to only get another enter effect if you fully leave the exit area.

I don't think, however, that this is a problem. Theoretically this should be just fine, if that is what the author intended. These events could be used just like any events.

We decided to split these into animation-specific actions specifically because event triggers are not paired, and so breaking the inverting part of the behaviors into actions allows for doing the same things with either event triggers or timeline triggers.

It's not about pairing of events, it's about the paired nature of animation triggers' behavior. At least that's how I see most usage of triggers, as having paired behaviors.
I think for this feature it's much more important for authors to be able to easily perform the OOTB 80% use-cases, than to have a lower level API layer. We already have these behaviors in #12611, just under different names.

I think we've covered this previously, and as discussed at tpac, these behaviors can be achieved by having animation play state dependent actions:

1. once can be implemented with a play-once action that will only play the animation if it is paused.
2. repeat is a play action that plays the animation if it is paused or finished, and a corresponding reset or finish action on exit to immediately finish the animation.
3. alternate is a play-reversed action that will play the animation if it is in the paused state, and reverse it if it is finished.
4. state is a play action on entry, and a pause action on exit.

We could do that. I was more leaning towards starting out with a more simple and easy to use, less error prone, less verbose syntax.

---

If we still consider the option 1 proposed above, there are still some valid concerns I've raised which I think are still not addressed:

1. It doesn't make sense to have to declare 2 idents in order to bind an animation to an event trigger, as in trigger(--foo, --bar play). If the action was global, as in declared via an at-rule, then it would make sense, but this is not the case, and both are scoped to same element. It should be enough to declare a name and a list of of event types, and bind that to a behavior.
2. It doesn't make sense to have to declare a specific enter and exit behavior on a timeline-trigger. If we we're already exposing this property as a very specific thing, it should be obvious it has an entry/exit events. This property should be as simple as specifying a name, a timeline, and ranges. And binding it on the animation with an action should just as simple as the case with events.

TL;DR if we do go with option 1 I still think there are some adjustments we need to to to the proposed syntax.
I have my proposal above, which is closer to option 2, but maybe we want some mixture of the two?

[DavMila]

1. It doesn't make sense to have to declare 2 idents in order to bind an animation to an event trigger, as in trigger(--foo, --bar play). If the action was global, as in declared via an at-rule, then it would make sense, but this is not the case, and both are scoped to same element. It should be enough to declare a name and a list of of event types, and bind that to a behavior.

An author wouldn't have to declare 2 idents. The higher-level names (--bar in your example) just create an easier way for an author to bind multiple events to a single behavior instead of having to specify multiple trigger() declarations or multiple parameters within a trigger() declaration.

2. It doesn't make sense to have to declare a specific enter and exit behavior on a timeline-trigger. If we we're already exposing this property as a very specific thing, it should be obvious it has an entry/exit events. This property should be as simple as specifying a name, a timeline, and ranges. And binding it on the animation with an action should just as simple as the case with events.

timeline-trigger does just specify a name, timeline, and ranges. It also does not specify behavior. Authors don't have to specify any event on timeline-trigger. behavior is specified on animation-trigger just like with event-trigger. Like @flackr described above, the granular "play-*" behaviors in this proposal cover the original set of use cases we were concerned with. They also provide additional flexibility for use cases like the one Tab and Elika point out in their original proposal where you want to "play on click, pause on exit" in which you are mixing and matching triggers of different types and don't necessarily want "play on enter" behavior on the timeline-trigger.

[ydaniv]

It doesn't make sense to have to declare 2 idents in order to bind an animation to an event trigger, as in trigger(--foo, --bar play). If the action was global, as in declared via an at-rule, then it would make sense, but this is not the case, and both are scoped to same element. It should be enough to declare a name and a list of of event types, and bind that to a behavior.

An author wouldn't have to declare 2 idents. The higher-level names (--bar in your example) just create an easier way for an author to bind multiple events to a single behavior instead of having to specify multiple trigger() declarations or multiple parameters within a trigger() declaration.

In the example in your proposal you have 2 names:

.event_target {
  animation-trigger: trigger(--event-source, --click-touch play-pause, --press-p play, keypress("r") reset);
}

These are 2 idents you need, like:--event-source and --click-touch.
I'm saying you only need one of them.

And you have 2 sub-properties: event-trigger-name and event-trigger-actions, which take an ident.
I propose to have a coordinated list of -name and -actions, where you only specify ident in -name and corresponding actions (or types, or whatever) in the -actions property.

Correspondingly, The trigger() function shouldn't take and extra first ident argument.

If you proposal does that then I don't see it written there 🤷