diff --git a/css-animations-2/Overview.bs b/css-animations-2/Overview.bs index 8b0bf8ad919..d4fb16e51c0 100644 --- a/css-animations-2/Overview.bs +++ b/css-animations-2/Overview.bs @@ -189,7 +189,7 @@ is elem. animation is disassociated from
 elem.style.animation = 'spin 1s';
 let animation = elem.getAnimations()[0]; // animation's owning element is elem
-elem.style.animation = ''; // animation no longer has an owning element
+elem.style.animation = ""; // animation no longer has an owning element
 
Note that although the owning element is often equal to the @@ -704,79 +704,241 @@ When multiple 'animation-*' properties are set simultaneously, so e.g. a change to 'animation-play-state' applies to the simultaneously-applied timeline specified in 'animation-timeline'. -## The 'animation' shorthand property ## {#animation-shorthand} - -The 'animation' shorthand property syntax is as follows: - -<single-animation> = <<'animation-duration'>> || <> || <<'animation-delay'>> || <> || <> || <> || <> || [ none | <> ] || <> - -

-Declaring Animation Triggers

- - 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' properties - are [=reset-only sub-properties=] of the 'animation' [=shorthand=]. -## The 'animation-trigger-behavior' property ## {#animation-trigger-behavior} +

+The 'animation-trigger' property

-The 'animation-trigger-behavior' property specifies the [=animation trigger behavior=] -of the [=animation trigger=]. - -
-Name: animation-trigger-behavior
-Value: <>#
-Initial: once
+
+Name: animation-trigger
+Value: [ none | [ <> <>+ ]+ ]#
+Initial: none
 Applies to: all elements
 Inherited: no
 Percentages: N/A
-Computed value: list, each item a keyword as specified
+Computed value: as specified
 Animation type: not animatable
 Canonical order: per grammar
 
-<single-animation-trigger-behavior> = once | repeat | alternate | state +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=]. + + : [ <> <>+ ]+ + :: + The corresponding animation is a [=triggered animation=], + responding to the triggers named by each <>, + and responding by taking the action named by the corresponding <>. + (See [[#trigger-scope]] for how <>s are resolved to [=triggers=].) + + How many <>s a trigger accepts, + and what exactly activates them, + is determined by the type of the trigger. + ([=Event triggers=] only take a single <>, + while [=timeline triggers=] can take one or two.) + 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 <> is specified multiple times, + all but the last have no effect. +
+ +The possible <> values, +and what effect they have in each animation state: + + + + + +
KeywordExtra Effectinitialplayingpausedfinished +
none— +
play{{play()}}{{play()}}{{play()}} +
play-forwardsset playback rate to positive{{play()}}{{play()}}{{play()}} +
play-backwardsset playback rate to negative{{play()}}{{play()}}{{play()}} +
pause{{pause()}}— +
resetset progress to 0{{pause()}}{{pause()}}{{pause()}} +
replayset progress to 0{{play()}}{{play()}}{{play()}} +
+ If there is an "effect", + it happens regardless of the current state, + before the state-specific action +
-The values of 'animation-trigger-behavior' have the following meaning -for an [=animation trigger=] that enters its [=animation trigger/active interval|active interval=]: -
-
once -
- The animation is triggered and played once and only once. +## The 'animation' shorthand property ## {#animation-shorthand} -
repeat -
- 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. +The 'animation' shorthand property syntax is as follows: -
alternate -
- 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. +<single-animation> = <<'animation-duration'>> || <> || <<'animation-delay'>> || <> || <> || <> || <> || [ none | <> ] || <> -
state -
- 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. -
+

+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). + +This is a simplified and streamlined version +of what can be achieved with the Web Animations API in Javascript, +allowing simple, common interaction patterns +to be created and managed purely in CSS. + +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, + without actually driving the animation with the scroll progress.) + +* [=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 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, +for some specific purpose +(currently, just 'animation-trigger'). +A trigger-using element specifies what trigger(s) it's listening to, +and what actions +(currently, just <>s) +to do in response to that activation. + +Note: This design for [=triggers=], +and the way they're associated with [=triggered animations=] and <>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. + + +

+Trigger Scope/Resolution

+ +All [=triggers=] are document-global by default, +similar to [=anchor names=]. + +If a single element attempts to define multiple [=triggers=] of different types +with the same name, +it only exposes one of them, +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. + +If multiple elements define [=triggers=] with the same name, +the [=trigger=] defined by the later element in [=tree order=] is used. + +Note: This behavior will be improved by a trigger-scope property, +not yet defined, +letting you define triggers that are only visible to subtrees +and references that only search in that subtree +(just like 'anchor-scope'). + +

+Timeline Triggers

+ +A timeline trigger is a [=trigger=] +which is activated when some [=timeline=] +enters the trigger's enter range, +or leaves the trigger's exit 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 "untriggered". +While it's "untriggered", +the associated [=timeline=] entering (or starting in) the trigger's [=enter range=] +performs an associated enter action +and switches the [=trigger state=] to "triggered"; +while it's "triggered", +the associated timeline leaving the trigger's [=exit range=] +performs an associated exit action +and switches the [=trigger state=] to "untriggered". + +Note: By default, the [=exit range=] is the same as the [=enter range=]; +even when manually specified, +the [=exit range=] is always a superset of the [=enter range=]. +The two ranges allow, for example, +an 'animation-trigger' to start an animation +when an element is scrolled close the center of the screen +(using a [=view progress timeline=] with a relatively small window as the [=enter range=]), +but not stop it until the element is fully off-screen +(using ''animation-timeline-range/cover'' as the [=exit range=]). + +Issue: I think it's WebAnim2 that needs to define +that exit ranges are interpreted +as the bounding range of the [=enter range=] +and what's specified for the [=exit 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 [=enter action=] +and the second is the trigger's [=exit action=]; +if only one is specified, the first is the trigger's [=enter 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=]. + + +

+Naming the Trigger: the 'timeline-trigger-name' property

+ +
+Name: timeline-trigger-name
+Value: none | <>#
+Initial: none
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: as specified
+Canonical order: per grammar
+Animation type: not animatable
+
+ +If ''timeline-trigger-name/none'' is specified, +the element does not define any [=timeline triggers=]. -The behavior of each value is defined in [[web-animations-2#trigger-behaviors]]. +If the same <> appears multiple times in the list, +only the last one defines a [=timeline trigger=]; +the preceding ones have no effect. -## The 'animation-trigger-timeline' property ## {#animation-trigger-timeline} -The 'animation-trigger-timeline' property specifies the timeline -of the animation’s associated [=animation trigger=]. +

+Linking a Timeline: the 'timeline-trigger-source' property

-Name: animation-trigger-timeline
+Name: timeline-trigger-source
 Value: <>#
 Initial: auto
 Applies to: all elements
@@ -793,200 +955,212 @@ Canonical order: per grammar
 Animation Type: not animatable
 
-The values of 'animation-trigger-timeline' have the same meaning as those of 'animation-timeline'. +The 'timeline-trigger-source' property +specifies the [=timeline trigger's=] associated [=timeline=]. +Values have the same meaning as those of 'animation-timeline', +except that ''timeline-trigger-source/none'' +instead causes the corresponding entry in the [=coordinated value list=] +to not define a [=timeline trigger=]. -Issue: Probably a trigger with timeline "none" is under-specified here. Need to clarify what it means. - -## The 'animation-trigger-range' property ## {#animation-trigger-range} +

+The Enter Range: the 'timeline-trigger-range' property

-  Name: animation-trigger-range
-  Value: [ <<'animation-trigger-range-start'>> <<'animation-trigger-range-end'>>? ]#
+Name: timeline-trigger-range
+Value: [ <<'animation-trigger-range-start'>> <<'animation-trigger-range-end'>>? ]#
 
-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=]. +The 'timeline-trigger-range' property is a [=shorthand property=] +that sets 'timeline-trigger-range-start' and 'timeline-trigger-range-end' +together in a single declaration. 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 behavior of 'timeline-trigger-range' is defined in [[web-animations-2#trigger-ranges]]. -## The 'animation-trigger-range-start' property ## {#animation-trigger-range-start} +Issue: Need to rewrite WebAnim2 to use the term "enter range".
-  Name: animation-trigger-range-start
-  Value: [ normal | <> | <> <>? ]#
-  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
+Name: timeline-trigger-range-start, timeline-trigger-range-end
+Value: [ normal | <> | <> <>? ]#
+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
 
-The 'animation-trigger-range-start' property specifies the start of the [=animation trigger=]’s -associated [=default range=]. +The 'timeline-trigger-range-start' and 'timeline-trigger-range-end' properties +specify the [=timeline trigger=]’s associated [=timeline trigger/enter range=]. +Values have the same meaning as 'animation-range-start' and 'animation-range-end'. -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} +

+The Exit Range: the 'timeline-trigger-exit-range' property

-
-  Name: animation-trigger-range-end
-  Value: [ normal | <> | <> <>? ]#
-  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
+
+Name: timeline-trigger-exit-range
+Value: [ <<'animation-trigger-exit-range-start'>> <<'animation-trigger-exit-range-end'>>? ]#
 
-The 'animation-trigger-range-end' property specifies the end of the [=animation trigger=]’s -associated [=default range=]. +The 'timeline-trigger-exit-range' property is a [=shorthand property=] +that sets 'timeline-trigger-exit-range-start' and 'timeline-trigger-exit-range-end' +together in a single declaration. +It has the same syntax as the 'animation-range' property. + +The behavior of 'timeline-trigger-exit-range' is defined in [[web-animations-2#trigger-ranges]]. + + +
+Name: timeline-trigger-exit-range-start, timeline-trigger-exit-range-end
+Value: [ auto | normal | <> | <> <>? ]#
+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
+
-The values of 'animation-trigger-range-end' have the same meaning as those of 'animation-range-end'. +The 'timeline-trigger-exit-range-start' and 'timeline-trigger-exit-range-end' properties +specify the [=timeline trigger=]’s associated [=timeline trigger/exit range=]. +Values have the same meaning as 'animation-range-start' and 'animation-range-end', +with the following addition: + +
+ : auto + :: + The start (for 'timeline-trigger-exit-range-start') + or end (for 'timeline-trigger-exit-range-end') + is equal to the start/end of the [=timeline trigger's=] [=enter range=]. +
-## The 'animation-trigger-exit-range' property ## {#animation-trigger-exit-range} +

+The 'timeline-trigger' Shorthand

-  Name: animation-trigger-exit-range
-  Value: [ <<'animation-trigger-exit-range-start'>> <<'animation-trigger-exit-range-end'>>? ]#
+Name: timeline-trigger
+Value: none | [ <<'timeline-trigger-name'>> <<'timeline-trigger-source'>> <<'timeline-trigger-range'>> [ '/' <<'timeline-trigger-exit-range'>> ]? ]#
 
-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 ''animation-trigger-exit-range-start/auto'' keyword. +The 'timeline-trigger' [=shorthand property=] +sets all of 'timeline-trigger-name', +'timeline-trigger-source', +'timeline-trigger-range', +and optionally 'timeline-trigger-exit-range' +at once. -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. +A value of none +is equivalent to ''none none normal''. -The behavior of 'animation-trigger-exit-range' is further defined in [[web-animations-2#trigger-ranges]]. +Note: Due to significant potentially ambiguities in the syntax +('timeline-trigger-name' vs [=timeline=] names in 'timeline-trigger-source'; +[=enter ranges=] vs [=exit ranges=]), +this shorthand's values must be given in the specified order, +rather than being settable in any order as is more common. -## The 'animation-trigger-exit-range-start' property ## {#animation-trigger-exit-range-start} +Issue: I think we need the ''/'' to disambiguate the two ranges? -
-  Name: animation-trigger-exit-range-start
-  Value: [ auto | normal | <> | <> <>? ]#
-  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
-
-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: - -
-
auto -
- The start of the trigger’s [=exit range=] - is equal to the start of its [=default range=]. - -
normal -
- 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. - -
<> -
- The [=exit range=] starts - at the specified point on the [=timeline=] - measuring from the start of the timeline. - -
<> <>? -
- The [=exit range=] starts - at the specified point on the [=timeline=] - measuring from the start of the specified [=named timeline range=]. - If the <> is omitted, - it defaults to 0%. -
-## The 'animation-trigger-exit-range-end' property ## {#animation-trigger-exit-range-end} +

+Event Triggers

-
-  Name: animation-trigger-exit-range-end
-  Value: [ auto | normal | <> | <> <>? ]#
-  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
-
+An event trigger is a [=trigger=] +which is activated when certain {{Event}}s are fired at the element. +It is defined on an element with the 'event-trigger' shorthand property, +or its longhands. -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: - -
-
auto -
- The end of the trigger’s [=exit range=] - is equal to the end of its [=default range=]. - -
normal -
- 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. - -
<> -
- The [=exit range=] ends - at the specified point on the [=timeline=] - measuring from the start of the timeline. - -
<> <>? -
- The [=exit range=] ends - at the specified point on the [=timeline=] - measuring from the start of the specified [=named timeline range=]. - If the <> is omitted, - it defaults to 100%. -
+An [=event trigger=] only has a single action associated with it, +which it performs every time the trigger is activated. -## The 'animation-trigger' property ## {#animation-trigger} +An element can define multiple [=event triggers=], +using the same {{Event}}s 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 'animation-trigger' property is a [=shorthand property|shorthand=] -that sets 'animation-trigger-behavior', '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. -
-Name: animation-trigger
-Value: <>#
-Initial: see individual properties
+

+Naming the Trigger: the 'event-trigger-name' property

+ +
+Name: event-trigger-name
+Value: none | <>#
+Initial: none
 Applies to: all elements
 Inherited: no
 Percentages: N/A
-Computed value: see individual properties
+Computed value: as specified
 Canonical order: per grammar
-Animation Type: not animatable
+Animation type: not animatable
+
+ +If ''event-trigger-name/none'' is specified, +the element does not define any [=event triggers=]. + +If the same <> appears multiple times in the list, +only the last one defines a [=event trigger=]; +the preceding ones have no effect. + +

+Linking an Event: the 'event-trigger-source' property

+ +
+Name: event-trigger-source
+Value: [ none | <>+ ]#
+Initial: none
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: as specified
+Animation type: not animatable
 
+The 'event-trigger-source' property +specifies what event or events activate the [=event trigger=]. +
-<single-animation-trigger> = <> || [ none | auto | [ [ <> | <> | <> ] [ normal | <> | <> <>? ]{0,4} ] ]
+<> = activate | click | touch | dblclick | keypress(<>) | ...
 
+Whenever any of the specified {{Event}}s are fired +with this element as its {{Event/target}}, +the [=event target=] activates. + +Issue: Figure out the full set of events we want to handle. + +Issue: 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. + + +

+The 'event-trigger' Shorthand

+ +
+Name: event-trigger
+Value: none | [ <<'event-trigger-name'>> <<'event-trigger-source'>> ]#
+Initial: none
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: as specified
+Animation type: not animatable
+
+ +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''. + + + + # Animation Events # {#events} ## Event dispatch ## {#event-dispatch}