Animation Triggers

1. Introduction

This specification defines mechanisms for affecting an animation’s playback based on various user interactions invoking a specified trigger. By specifying a trigger for an animation, that animation becomes a triggered animation, making its playback start delayed until that trigger occurs. These triggers can be certain Events defined in [DOM], or timeline based, such as view progress timelines. [SCROLL-ANIMATIONS-1]

This module provides both an imperative API building on the Web Animations API as well as a declarative API building on CSS Animations. [CSS-ANIMATIONS-2] [WEB-ANIMATIONS-1]

1.1. Relationship to other specifications

Web Animations [WEB-ANIMATIONS-1] defines an abstract conceptual model for animations on the Web platform, with elements of the model including animations and timelines, and associated programming interfaces. This specification extends the Web Animations model by defining triggered animation and allowing to perform playback control functions on them using triggers.

This specification introduces both programming interfaces for interacting with these concepts, as well as CSS properties that apply these concepts to CSS Animations [CSS-ANIMATIONS-2]. To the extent the behavior of these CSS properties is described in terms of the programming interfaces, User Agents that do not support scripting may still conform to this specification by implementing the CSS features to behave as if the underlying programming interfaces were in place.

This specification uses the timeline and ranges concept introduced in the Scroll-Driven Animations module [SCROLL-ANIMATIONS-1] for specifying progress-based timelines and animations.

Like most operations in CSS besides selector matching, features in this specification operate over the flattened element tree.

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Triggers

While CSS animations are, by default, automatically run as soon as the appropriate animation values have been set on an element, the animation-trigger property allows the animation’s start to be delayed until an appropriate trigger occurs, and even paused, restarted, or reset by triggers (making it a triggered animation).

Currently, two types of triggers are defined:

• timeline triggers, managed by the timeline-trigger properties, which allow animations to be triggered by entering or leaving certain timeline ranges. (Usually, view progress timelines, so an animation can be started when an element comes on-screen.)

• event triggers, managed by the event-trigger properties, which allow animations to be triggered by certain user-interaction events, such as clicking an element or pressing certain keys.

A trigger is defined on some specific triggering element. All triggers have a trigger name, and the specific type of trigger dictates how and when it’s activated. A trigger can define multiple "types" of activation. (For example, timeline triggers can do different things on entry and exit.)

A trigger is used on potentially any element, creating a trigger instance on the element. (For example, animation-trigger associates a trigger instance with a specific animation on the element.) The trigger-using element specifies what actions to take when the trigger activates.

Note: This design for triggers and trigger instances, and the way they’re associated with triggered animations and <animation-action>s, is intentionally somewhat generic, intended to support using triggers for other purposes in the future. For now, though, triggered animations are the only user of this feature.

If a single element attempts to define multiple triggers of different types with the same trigger name, it only exposes one of the triggers, with event triggers winning over timeline triggers.

Note: This order is completely arbitrary (based on alphabetic order of the concept name), as this is just an error case.

2.1. Trigger Name Scoping: the trigger-scope property

Trigger names are global by default, usable by other elements regardless of their position. (Though they are tree-scoped names, so have interactions with shadow roots). If multiple elements define triggers with the same trigger name, the trigger defined by the later element in tree order is used.

The trigger-scope property can limit the scope of a name to a subtree of the document, so elements outside won’t see the chosen trigger name, and elements inside will only see the version of the trigger name defined inside the scope.

This property scopes trigger names to the subtree of the matching element. Its values are:

none

No changes in trigger name scope.

all

Specifies that all trigger names defined by this element or its descendants—​whose scope is not already limited by a descendant using trigger-scope—​to be in scope only for this element’s flat tree descendants; and limits descendants to only match trigger names to triggers within this subtree.

This value only affects trigger names in the same tree scope, as if it were a strictly matched tree-scoped name. (That is, trigger-scope: all acts identically to trigger-scope: --foo, --bar, ..., listing all relevant trigger names.)

<dashed-ident>

Specifies that a matching trigger name defined by this element or its descendants—​whose scope is not already limited by a descendant using trigger-scope—​to be in scope only for this element’s flat tree descendants; and limits descendants to only match these trigger names to triggers within this subtree.

The <dashed-ident> represents a strictly matched tree-scoped name, i.e. it can only match against trigger names in the same shadow tree.[CSS-SCOPING-1]

2.2. Timeline Triggers

A timeline trigger is a trigger which is activated when some timeline enters the trigger’s activation range, or leaves the trigger’s active range. It is defined on an element with the timeline-trigger shorthand property, or its longhands.

A timeline trigger has a binary trigger state associated with it; it is initially "inactive". While it’s "inactive", the associated timeline entering (or starting in) the trigger’s activation range performs an associated entry action and switches the trigger state to "active"; while it’s "active", the associated timeline leaving the trigger’s active range performs an associated exit action and switches the trigger state to "inactive".

Note: By default, the active range is the same as the activation range; even when manually specified, the active range is always a superset of the activation range. The two ranges allow, for example, an animation-trigger to start an animation when an element is scrolled close to the center of the screen (using a view progress timeline with a relatively small window as the activation range), but not stop it until the element is fully off-screen (using cover as the active range).

A timeline trigger can have one or two actions associated with it when used as a trigger on an element (such as by animation-trigger). If two are specified, the first is the trigger’s entry action and the second is the trigger’s exit action; if only one is specified, the first is the trigger’s entry action and its exit action is to do nothing.

An element can define multiple timeline triggers, using the same timeline (potentially with different ranges) or different ones. The set of timeline-trigger longhands form a coordinating list property group, with timeline-trigger-name as the coordinating list base property, and each item in the coordinated value list defining the properties of a single timeline trigger.

2.2.1. Naming the Trigger: the timeline-trigger-name property

If none is specified, the element does not define any timeline triggers.

If the same <dashed-ident> appears multiple times in the list, only the last one defines a timeline trigger; the preceding ones have no effect.

2.2.2. Linking a Timeline: the timeline-trigger-source property

The timeline-trigger-source property specifies the timeline trigger’s associated timeline. Values have the same meaning as those of animation-timeline, except that none instead causes the corresponding entry in the coordinated value list to not define a timeline trigger.

2.2.3. The Activation Range: the timeline-trigger-activation-range property

The timeline-trigger-activation-range property is a shorthand property that sets timeline-trigger-activation-range-start and timeline-trigger-activation-range-end together in a single declaration. It has the same syntax as the animation-range property.

The behavior of timeline-trigger-activation-range is defined in Web Animations 2 § 3.6.5 Animation Trigger Ranges.

The timeline-trigger-activation-range-start and timeline-trigger-activation-range-end properties specify the timeline trigger’s associated activation range. Values have the same meaning as animation-range-start and animation-range-end.

2.2.4. The Active Range: the timeline-trigger-active-range property

The timeline-trigger-active-range property is a shorthand property that sets timeline-trigger-active-range-start and timeline-trigger-active-range-end together in a single declaration. It has the same syntax as the animation-range property.

The behavior of timeline-trigger-active-range is defined in Web Animations 2 § 3.6.5 Animation Trigger Ranges.

The timeline-trigger-active-range-start and timeline-trigger-active-range-end properties specify the timeline trigger’s associated active range. Values have the same meaning as animation-range-start and animation-range-end, with the following addition:

auto

The start (for timeline-trigger-active-range-start) or end (for timeline-trigger-active-range-end) is equal to the start/end of the timeline trigger’s activation range.

2.2.5. The timeline-trigger Shorthand

The timeline-trigger shorthand property sets all of timeline-trigger-name, timeline-trigger-source, timeline-trigger-activation-range, and optionally timeline-trigger-active-range at once.

A value of none is equivalent to none none normal.

Note: Due to significant potential ambiguities in the syntax (timeline-trigger-name vs timeline names in timeline-trigger-source; activation ranges vs active ranges), this shorthand’s values must be given in the specified order, rather than being settable in any order as is more common.

2.3. Event Triggers

An event trigger is a trigger which is activated when certain Events are fired at the element. It is defined on an element with the event-trigger shorthand property, or its longhands.

An event trigger can be defined as either stateless or stateful:

• If stateless, it has a single set of enter events that activate it.

• If stateful, it has two sets of events, its enter events and another set of exit events.

Event triggers are activated when one of its associated Events are fired on the page with the trigger-defining element as its target. If it’s stateful, it has a binary trigger state associated with it, initially "inactive": while "inactive", it only activates when the defining element receives one of its enter events, performing an associated enter action and switching its trigger state to "active"; while "active", it only deactivates when it receives one of its exit events, performing an associated exit action and switching its trigger state back to "inactive".

A stateless event trigger must be given exactly one action for its trigger instance. A stateful one can be given one or two: the first is its enter action, and the second, if provided, is its exit action; if the second is not provided, the exit action is to do nothing.

Note: A stateful and stateless event trigger act differently even if you only assign a single action; a single-action stateful event trigger will effectively "turn off" until it receives one of its exit events, ignoring any of the enter events after the first, while a stateless one will repeatedly trigger for every enter event.

An element can define multiple event triggers, using the same Events or different ones. The set of event-trigger longhands form a coordinating list property group, with event-trigger-name as the coordinating list base property, and each item in the coordinated value list defining the properties of a single event trigger.

The proposal I drew this text from specified that it only cares if the element is the target of the event. We probably want to allow for bubbling and/or capturing, possibly as an opt in/out.

2.3.1. Naming the Trigger: the event-trigger-name property

If none is specified, the element does not define any event triggers.

If the same <dashed-ident> appears multiple times in the list, only the last one defines an event trigger; the preceding ones have no effect.

2.3.2. Linking an Event: the event-trigger-source property

The event-trigger-source property specifies what event or events activate the event trigger. Its values are:

none

The corresponding entry in the coordinated value list does not define a trigger.

<event-trigger-event>+ [ / <event-trigger-event>+ ]?

Defines what event(s) the event trigger responds to.

If a / is used in the value, the event trigger is stateful; the set of events before the / are the event trigger’s enter events, while those after the / are the exit events. (The same events can occur in both sets.)

Otherwise, the event trigger is stateless, and the provided events are its enter events.

<event-trigger-event> = activate | interest | click | touch | dblclick | keypress(<string>) | ...

Figure out the full set of events we want to handle.

2.3.3. The event-trigger Shorthand

The event-trigger shorthand property sets both event-trigger-name and event-trigger-source at once.

A value of none is equivalent to none none.

2.3.4. The animation-trigger property

The animation-trigger property specifies whether the animation is a triggered animation, and if it is, what trigger it responds to and what actions it takes in response. animation-trigger is a reset-only sub-property of the animation shorthand. Its values are:

none

The corresponding animation is not a triggered animation.

[ <dashed-ident> <animation-action>+ ]+

The corresponding animation is a triggered animation, responding to the triggers named by each <dashed-ident>, and responding by taking the action named by the corresponding <animation-action>. (See § 2.1 Trigger Name Scoping: the trigger-scope property for how <dashed-ident>s are resolved to triggers.)

How many <animation-action>s a trigger accepts, and what exactly activates them, is determined by the type of the trigger. (Event triggers take one and possibly an optional second, depending on whether they’re stateless or stateful; timeline triggers take one and optionally a second.) Specifying the wrong number of actions (too many or too few) is valid syntactically, but causes the trigger to have no effect.

If multiple triggers occur simultaneously, they take effect in the order specified.

If the same <dashed-ident> is specified multiple times, all but the last have no effect.

The possible <animation-action> values, and what effect they have in each animation state:

3. Privacy Considerations

There are no known privacy impacts of the features in this specification.

4. Security Considerations

There are no known security impacts of the features in this specification.