diff --git a/css-animations-2/Overview.bs b/css-animations-2/Overview.bs index 669625767cab..ddff6928e65a 100644 --- a/css-animations-2/Overview.bs +++ b/css-animations-2/Overview.bs @@ -68,6 +68,13 @@ spec:web-animations-1; type:dfn; text:start delay text:target element text:unresolved +spec:web-animations-2; type:dfn; + text:active interval; for:animation trigger + text:default range + text:exit range +spec:scroll-animations-1; type:dfn; + text:animation-range-start + text:animation-range-end

Delta specification

@@ -702,7 +709,279 @@ 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-type' property ## {#animation-trigger-type} + +The 'animation-trigger-type' property specifies the [=animation trigger type=] +of the [=animation trigger=]. + +
+Name: animation-trigger-type
+Value: <>#
+Initial: once
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: list, each item a keyword as specified
+Animation type: not animatable
+Canonical order: per grammar
+
+ +<single-animation-trigger-type> = once | repeat | alternate | state + +The values of 'animation-trigger-type' 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. + +
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. + +
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. + +
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. +
+ +The behavior of each value is defined in [[web-animations-2#trigger-types]]. + +## The 'animation-trigger-timeline' property ## {#animation-trigger-timeline} + +The 'animation-trigger-timeline' property specifies the timeline +of the animation’s associated [=animation trigger=]. + +
+Name: animation-trigger-timeline
+Value: <>#
+Initial: auto
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: list, each item either
+  the keyword ''single-animation-timeline/none'',
+  the keyword ''single-animation-timeline/auto'',
+  a case-sensitive [=css identifier=],
+  a computed ''scroll()'' function,
+  or
+  a computed ''view()'' function
+Canonical order: per grammar
+Animation Type: not animatable
+
+ +The values of 'animation-trigger-timeline' have the same meaning as those of 'animation-timeline'. + +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} + +
+  Name: animation-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=]. +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 'animation-trigger-range-start' property ## {#animation-trigger-range-start} + +
+  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
+
+ +The 'animation-trigger-range-start' property specifies the start of the [=animation trigger=]’s +associated [=default range=]. + +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} + +
+  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
+
+ +The 'animation-trigger-range-end' property specifies the end of the [=animation trigger=]’s +associated [=default range=]. + +The values of 'animation-trigger-range-end' have the same meaning as those of 'animation-range-end'. + +## The 'animation-trigger-exit-range' property ## {#animation-trigger-exit-range} + +
+  Name: animation-trigger-exit-range
+  Value: [ <<'animation-trigger-exit-range-start'>> <<'animation-trigger-exit-range-end'>>? ]#
+
+ +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 ''auto'' keyword. + +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. + +The behavior of 'animation-trigger-exit-range' is further defined in [[web-animations-2#trigger-ranges]]. + +## The 'animation-trigger-exit-range-start' property ## {#animation-trigger-exit-range-start} + +
+  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} + +
+  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
+
+ +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%. +
+ +## The 'animation-trigger' property ## {#animation-trigger} + +The 'animation-trigger' property is a [=shorthand property|shorthand=] +that sets 'animation-trigger-type', '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
+Applies to: all elements
+Inherited: no
+Percentages: N/A
+Computed value: see individual properties
+Canonical order: per grammar
+Animation Type: not animatable
+
+ +
+<single-animation-trigger> = <> || [ none | auto | [ [ <> | <> | <> ] [ normal | <> | <> <>? ]{0,4} ] ]
+
# Animation Events # {#events} diff --git a/web-animations-2/Overview.bs b/web-animations-2/Overview.bs index bf406db0f074..10d2b174d1c4 100644 --- a/web-animations-2/Overview.bs +++ b/web-animations-2/Overview.bs @@ -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, initial progress, - timeline, new timeline, t, going forwards + timeline, new timeline, t, going forwards, did trigger
 urlPrefix: https://drafts.csswg.org/web-animations-1/; type: dfn; spec: web-animations-1
@@ -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
@@ -133,6 +134,7 @@ urlPrefix: https://drafts.csswg.org/web-animations-1/; type: dfn; spec: web-anim
     text: update the timing properties of an animation effect
     text: unresolved
     text: update an animation's finished state
+    text: default document timeline
 urlPrefix: https://webidl.spec.whatwg.org/; type: dfn; spec: webidl
     text: resolve a promise; url: resolve
 urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn; spec: ecma-262
@@ -221,6 +223,13 @@ Add:
 > case, the timeline is a progress-based
 > timeline, and its [=timeline duration=] is 100%.
 
+

Animation Frames

+ +Update the note on the first step of the algorithm by adding the following bullet: + +> * Updating the [=animation trigger state|state=] of [=animation triggers=] +> by running the [=updating animation trigger state=] procedure. +

Animations

Append: @@ -2353,6 +2362,204 @@ Items sorted earlier are executed before those sorted later. +Animation Triggers {#triggers} +----------------- + +### Overview ### {#triggers-overview} + +An animation trigger 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 Types ### {#trigger-types} + +The behavior an [=animation trigger=] applies to its associated [=animation=]’s +playback is defined by its animation trigger type, and +depending on its [=animation trigger state|state=] can apply one of two +distinct behavior types: ''primary'' or ''inverse''. +Given an internal |did trigger| flag, the values of [=animation trigger type=] +can be one of the following: + +
+
once +
+ The ''primary'' behavior is [=play an animation|triggering=] the associated animation. + +
repeat +
+ The ''primary'' behavior is [=play an animation|triggering=] the associated animation. + The ''inverse'' behavior is resetting the associated [=animation effect=] back to + its [=animation effect/before phase=] and its associated animation’s [=animation/start time=] to zero. + +
alternate +
+
+ : 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. + +
+ + The ''inverse'' behavior is [=reverse an animation|reversing=] the associated animation. + +
state +
+ The ''primary'' behavior is [=play an animation|triggering or resuming=] the associated animation. + The ''inverse'' behavior is [=pause an animation|pausing=] the associated animation. +
+ +Issue: Need to bike-shed the name for type "state" type. + +Issue: Do we need a proper definition for "behavior types primary/inverse"? + +### Animation Trigger State ### {#trigger-state} + +An [=animation trigger=] |trigger| with [=animation trigger type=] |type| +and an associated [=animation=] |animation| +has an internal state which +controls the applied behavior type. This state has discrete values +which can be one of the following: + +
+
idle +
+ The [=animation effect=] associated |animation| remains in + its [=animation effect/before phase=] and stays at zero [=animation/start time=]. + +
primary +
+ When switched to this value the ''primary'' behavior type defined by |type| is applied to |animation|. + +
inverse +
+ When switched to this value the ''inverse'' behavior type defined by |type| is applied to |animation|. + +
+ +Issue: Do we need a formal resolution on the spec of the idle state? + +### Animation Trigger Active Interval ### {#trigger-active-interval} + +Each [=animation trigger=] defines an active interval +and only one such interval. This interval is the segment of the timeline’s progress +during which the trigger’s [=animation trigger state|state=] is set to ''primary''. + +### Animation Trigger Ranges ### {#trigger-ranges} + +An [=animation trigger=] has two [=animation attachment range|ranges=], +the default range and the exit range. +The [=exit range=] is used to replace [=default range=] and extend +the [=animation trigger/active interval|active interval=]. + +Issue: Should we specify that that exit range’s edges can only be equal to or greater than the default range’s edges? + +Depending on its most recent [=animation trigger state|state=] |state|, the +[=animation trigger/active interval|active interval=] is defined as follows: + +
+ : If |state| is ''animation trigger state/primary'', + :: + Then |interval| is set to [=exit range=]. + + : Otherwise, + :: + |interval| is [=default range=]. + +
+ +### Setting a Trigger of an Animation ### {#setting-animation-trigger} + +
+ The procedure of setting a trigger of an animation |animation|, + to |new trigger|, is as follows: + + 1. Let |old trigger| be the current [=animation trigger=] of |animation|, if any. + + 1. If |new trigger| is the same object as |old trigger|, abort this procedure. + + 1. Let the [=animation trigger|trigger=] of |animation| be |new trigger|. + + 1. Run the procedure to [=updating animation trigger state=] for |trigger|. +
+ +### Setting the timeline of an Animation Trigger ### {#setting-trigger-timeline} + +
+ The procedure of setting timeline of animation trigger |trigger|, + to |new timeline| which may be null, is as follows: + + 1. Let |old timeline| be the current [=timeline=] of |trigger|, if any. + + 1. If |new timeline| is the same object as |old timeline|, abort this procedure. + + 1. Let the [=timeline=] of |trigger| be |new timeline|. + + 1. Run the procedure to [=updating animation trigger state=] for |trigger|. +
+ +### Updating Animation Trigger State ### {#updating-trigger-state} + +
+ The procedure of updating animation trigger state |state| + of an [=animation trigger=] |trigger|, + with a given a flag |did trigger|, and an [=animation trigger type=] |type|, + is as follows: + + 1. Let |did trigger| be a boolean flag that is initially false. + + 1. Let |state| be the current [=animation trigger state|state=] + of |trigger| that is initially ''animation trigger state/idle''. + + 1. Set |state| as follows: +
+ : If |trigger|’s [=local time=] is [=unresolved=], + :: + Then abort this procedure. + + : Otherwise, + :: + +
+ : If |type| is ''animation trigger type/once'' and |did trigger| flag is true, + :: + Then abort this procedure. + + : Otherwise, + :: + +
+ : If |trigger| is inside its [=animation trigger/active interval|active interval=], + :: + 1. Set |state| to ''animation trigger state/primary''. + 1. Set |did trigger| to true. + + : Otherwise, + :: + +
+ : If |did trigger| flag is true, + :: + Set |state| to ''animation trigger state/inverse''. + +
+ +
+ +
+ +
+ +
+ +Issue: Should it be the correct/expected behavior for the "did trigger" flag to reset to false if the timeline becomes idle again? +

Programming interface

@@ -2432,6 +2639,7 @@ rangeStart, rangeEnd, and overallProgress as follows: partial interface Animation { attribute CSSNumberish? startTime; attribute CSSNumberish? currentTime; + attribute AnimationTrigger? trigger; attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart; attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd; readonly attribute double? overallProgress; @@ -2483,6 +2691,11 @@ Add: > : overallProgress > :: Specifies the [=animation/overallProgress=] of the animation as a proportion of its > [=associated effect end=]. +> +> : trigger +> :: Specifies the animation’s associated [=animation trigger=]. +> Setting the attribute follows the same rules as the KeyframeAnimationOption +> trigger.

The AnimationEffect interface

@@ -3267,6 +3480,24 @@ with which it is associated is updated. The Animatable interface mixin {#the-animatable-interface-mixin} ---------------------------------------- +The {{Animatable}} mixin interface +is modified to add the following members: + +
+ + : Animation animate(|keyframes|, |options|) + :: Amend step 6 of the procedure as follows: + + 6. If |options| is a {{KeyframeAnimationOptions}} object, + let |trigger| be the trigger member of |options| + or, if trigger member of |options| is missing, + a newly created {{AnimationTrigger}} with an empty + {{AnimationTriggerOptions}} dictionary as its options. + + 7. Run the procedure to [=setting a trigger of an animation=] for |animation| + with the |auto-rewind| flag set to true. + The {{KeyframeAnimationOptions}} dictionary interface is modified to add the following members: @@ -3279,6 +3510,7 @@ dictionary TimelineRangeOffset { partial dictionary KeyframeAnimationOptions { (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart = "normal"; (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd = "normal"; + AnimationTrigger? trigger; };
@@ -3303,6 +3535,10 @@ partial dictionary KeyframeAnimationOptions { a {{CSSNumericValue}} is interpreted as a {{TimelineRangeOffset}} with that {{TimelineRangeOffset/offset}} and a null {{TimelineRangeOffset/rangeName}}. +: trigger +:: If present, specifies the animation’s associated [=animation trigger=] + by running the procedure of [=setting a trigger of an animation=]. + Passing a {{CSSKeywordValue}} with a {{CSSKeywordValue/value}} other than "normal" @@ -3366,6 +3602,168 @@ Update the type for the AnimationPlaybackEventInit members. +

The AnimationTrigger interface

+ +
+[Exposed=Window]
+interface AnimationTrigger {
+  constructor(optional AnimationTriggerOptions options = {});
+  attribute AnimationTimeline timeline;
+  attribute AnimationTriggerType type;
+  attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart = "normal";
+  attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd = "normal";
+  attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeStart = "auto";
+  attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeEnd = "auto";
+};
+
+ +
+ : AnimationTrigger(|options|) + :: + Creates a new {{AnimationTrigger}} object using the following procedure: + + 1. Create a new {{AnimationTrigger}} object, |trigger|. + + 1. Let |type| be the {{AnimationTriggerOptions/type}} property. + + 1. Let |timeline| be the {{AnimationTriggerOptions/timeline}} property. + + 1. Let |range start| be the {{AnimationTriggerOptions/rangeStart}} property. + + 1. Let |range end| be the {{AnimationTriggerOptions/rangeEnd}} property. + + 1. Set [=default range=] of |trigger| using |range start| and |range end|, + following the same rules as the KeyframeAnimationOption + rangeStart and + rangeEnd respectively. + + 1. Let |exit range start| be the {{AnimationTriggerOptions/exitRangeStart}} property. + + 1. Let |exit range end| be the {{AnimationTriggerOptions/exitRangeEnd}} property. + + 1. Set [=exit range=] of |trigger| using |exit range start| and |exit range end|, + following the same rules above for [=default range=], unless they are set to + "auto", in which case they are set to their corresponding side + of the [=default range=]. + + 1. Run the procedure for [=setting timeline of animation trigger=] + on |trigger| passing |timeline| as the new timeline. + +
+ + : options + :: Configuration parameters for the newly-created trigger. + +
+ +
+ +
+ + : timeline + :: + Returns the [=timeline=] for this trigger + or `null` if this timeline is [=inactive timeline|inactive=]. + + : type + :: + Returns the [=animation trigger type|type=] of this trigger. + + : rangeStart + :: + Returns the [=default range=]’s start of this trigger. + + : rangeEnd + :: + Returns the [=default range=]’s end of this trigger. + + : exitRangeStart + :: + Returns the [=exit range=]’s start of this trigger. + + : exitRangeEnd + :: + Returns the [=exit range=]’s end of this trigger. + +
+ +

The AnimationTriggerOptions dictionary

+ +
+dictionary AnimationTriggerOptions {
+  AnimationTimeline? timeline;
+  AnimationTriggerType? type = "once";
+  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString)? rangeStart = "normal";
+  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString)? rangeEnd = "normal";
+  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString)? exitRangeStart = "auto";
+  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString)? exitRangeEnd = "auto";
+};
+
+ +
+ + : timeline + :: + The timeline to which the trigger is associated. + If not specified, the trigger is associated with [=default document timeline=]. + + : type + :: + The type of trigger to create. + If not specified, the trigger is of type ''animation trigger type/once''. + + : rangeStart + :: + The start of the trigger’s [=default range=]. + If not specified, the [=default range=]’s start is set to "normal". + + : rangeEnd + :: + The end of the trigger’s [=default range=]. + If not specified, the [=default range=]’s end is set to "normal". + + : exitRangeStart + :: + The start of the trigger’s [=exit range=]. + If not specified, the [=exit range=]’s start is set to "auto". + + : exitRangeEnd + :: + The end of the trigger’s [=exit range=]. + If not specified, the [=exit range=]’s end is set to "auto". + +
+ +

The AnimationTriggerType enumeration

+ +
+enum AnimationTriggerType { "once", "repeat", "alternate", "state" };
+
+ +
+ + : once + :: + Type ''animation trigger type/once''. + + : repeat + :: + Type ''animation trigger type/repeat''. + + : alternate + :: + Type ''animation trigger type/alternate''. + + : state + :: + Type ''animation trigger type/state''. + +
+

Model liveness

This section is non-normative