[animation-triggers-1] Update AnimationTrigger specification

animation-triggers-1/Overview.bs

@@ -26,6 +26,10 @@ Markup Shorthands: markdown yes
 <pre class=link-defaults>
 spec:infra; type:dfn; text:user agent
 spec:dom; type:dfn; for:/; text:shadow root
+spec:web-animations-1; type:dfn;
+	text:pause an animation
+	text:animation effect
+	text:fill mode
 </pre>
 
 <pre class=anchors>
@@ -106,7 +110,126 @@ urlPrefix: https://www.w3.org/TR/web-animations-1/; type: dfn
   █▌   █▌  █▌ ████  ███▌   ███▌  █████▌ █▌  █▌  ███▌
 -->
 
-# Triggers # {#triggers}
+# Animation Triggers # {#triggers}
+-----------------
+
+## Overview ## {#triggers-overview}
+
+An <dfn export>animation trigger</dfn> can be used to control the playback
+of [=animations=] associated with the trigger.
+
+Each [=animation trigger=] maintains the following fields internally:
+
+1. an <dfn lt="animation trigger active" export>active</dfn> flag, which is initially false,
+
+1. a <dfn lt="animation trigger invokes deactivation" export>invokes deactivation</dfn> flag,
+	which is initially false, and,
+
+1. a set of [=animations=], <dfn lt="animation trigger animation set" export>animations set</dfn>,
+	which is initially empty.
+
+Each [=animation trigger=] associates each [=animation=] in its
+[=animation trigger animation set|animations set=] with two <<animation-action>>s. One action is
+associated with [=invoke activation|activation=] and the other is associated with
+[=invoke deactivation|deactivation=].
+
+## Invoking Activation & Deactivation ## {#animation-trigger-activation-deactivation}
+
+When asked to <dfn lt="invoke activation">invoke activation</dfn> given a [=trigger=] <var>trigger</var>,
+the user agent should perfrom the following steps:
+
+	1. If |trigger|'s [=animation trigger active|active=] flag is true, abort these steps.
+
+	1. Set |trigger|'s [=animation trigger active|active=] flag to true.
+
+	1. For each [=animation=] <var>animation</var> in |trigger|'s [=animation trigger animation set|animations set=],
+		1. Run the steps to <a>perform activation</a> with |trigger| as trigger and |animation| as animation.
+
+	1. If |trigger|'s [=animation trigger invokes deactivation|invokes deactivation=] flag is false,
+		set |trigger|'s [=animation trigger active|active=] flag to false.
+
+When asked to <dfn perform activation on an animation export>perform activation</dfn> given a
+[=animation trigger|trigger=] <var>trigger</var> and an [=animation=] <var>animation</var>, the user
+agent should perform these steps:
+
+	1. Let <var>action</var> be the <<animation-action>> which |trigger| associates with
+			[=invoke activation|activation=] for |animation|.
+
+		1. Perform the steps corresponding to |action| in the <<animation-action>> table on |animation|.
+
+When asked to <dfn lt="invoke deactivation">invoke deactivation</dfn> given a [=trigger=] <var>trigger</var>,
+the user agent should perfrom the following steps:
+
+	1. If |trigger|'s [=animation trigger active|active=] flag is false, abort these steps.
+
+	1.  Set |trigger|'s [=animation trigger active|active=] flag to false.
+
+	1.  For each [=animation=] <var>animation</var> in |trigger|'s [=animation trigger animation set|animations set=],
+		1. Run the steps to <a>perform deactivation</a> with |trigger| as trigger and |animation| as animation.
+
+When asked to <dfn perform deactivation on an animation export>perform deactivation</dfn> given a
+[=animation trigger|trigger=] <var>trigger</var> and an [=animation=] <var>animation</var>, the user
+agent should perform these steps:
+
+	1. Let <var>action</var> be the <<animation-action>> which |trigger| associates with
+			[=invoke deactivation|deactivation=] for |animation|.
+
+		1. Perform the steps corresponding to |action| in the <<animation-action>> table on |animation|.
+
+Issue: Should there be any effect of triggers on scroll-driven animations?
+
+## Attaching an Animation to an AnimationTrigger ## {#animation-trigger-attach-animation}
+
+When asked to <dfn lt="attach an animation to a trigger" export>attach an animation to a trigger</dfn> given an [=animation trigger=]
+<var>trigger</var>, an [=animation=] <var>animation</var>, an {{AnimationTriggerAction}} <var>activateAction</var>
+and an {{AnimationTriggerAction}} <var>deactivateAction</var>, run the following steps:
+
+	1. If |animation| is currently attached to another [=animation trigger=],
+		<a>throw</a> a <span class=exceptionname>NotSupportedError</span>.
+
+	1. If |deactivateAction| is not given, set |deactivateAction| to {{AnimationTriggerAction/none}}.
+
+	1. Let <var>activationAction</var> be the <<animation-action>> that corresponds to |activateAction|.
+
+	1. Let <var>deactivationAction</var> be the <<animation-action>> that corresponds to |deactivateAction|.
+
+	1. If the [=animation/play state=] of |animation| is [=play state/idle=],
+		1. Run the steps to [=pause an animation=] on |animation|.
+
+	1. Let <var>currentActivationAction</var> be the <<animation-action>> which |trigger| associates
+			with [=invoke activation|activation=] for |animation|
+			or ''<animation-action>/none'' if |animation| was not previously in |trigger|'s
+			[=animation trigger animation set|animations set=].
+
+	1. Add |animation| to |trigger|'s [=animation trigger animation set|animations set=].
+
+	1. Set the <<animation-action>> which |trigger| associates with its [=invoke activation|activation=] for |animation| to |activationAction|.
+
+	1. Set the <<animation-action>> which |trigger| associates with its [=invoke deactivation|deactivation=] for |animation| to |deactivationAction|.
+
+	1. If |trigger|'s [=animation trigger active|active=] flag is true,
+
+		1. If |currentActivationAction| is not the same as |activationAction|,
+			1. Run the steps to <a>perform activation</a> with |trigger| as trigger and |animation| as animation.
+
+	NOTE: Attaching multiple triggers to an animation is not supported currently but will eventually be
+	supported.
+
+	NOTE: When pausing the animation in step 5, the user agent should also set a boundary-exclusive flag
+	on |animation| and its [=animation effect=]. However, that flag is not yet implemented. Setting the
+	boundary-exclusive flag allows authors control over the "pre-triggered" visual state of a triggered
+	animation by making its visual state depend on its [=/fill mode=].
+
+	ISSUE: We react to post-activation attachment, but not post-deactivation. Perhaps we should react to
+	both or neither.
+
+When asked to <dfn lt="detach an animation from a trigger" export>detach an animation from a trigger</dfn>
+given an [=animation trigger=] <var>trigger</var>, an [=animation=] <var>animation</var>,
+run the following steps:
+
+	1. Remove |animation| from |trigger|'s [=animation trigger animation set|animation set=].
+
+## Triggers Declared By CSS ## {#css-animation-triggers}
 
 	While CSS animations are, by default,
 	automatically run as soon as the appropriate 'animation' values have been set on an element,
@@ -628,6 +751,109 @@ urlPrefix: https://www.w3.org/TR/web-animations-1/; type: dfn
 		</caption>
 	</table>
 
+<h2 id="programming-interface">Programming interface</h2>
+
+<h3 id="the-animationtrigger-interface">The <code>AnimationTrigger</code> interface</h3>
+
+<xmp class=idl>
+[Exposed=Window]
+interface AnimationTrigger {
+	undefined addAnimation(Animation animation, AnimationTriggerAction activateAction, optional AnimationTriggerAction deactivateAction);
+	undefined removeAnimation(Animation animation);
+	sequence<Animation> getAnimations();
+};
+</xmp>
+
+<wpt>
+	interfaces/TimelineTrigger/constructor.html
+</wpt>
+
+### The {{AnimationTriggerAction}} enumeration ### {#the-animationtriggeraction-enumeration}
+
+<xmp class=idl>
+enum AnimationTriggerAction {
+	"play",
+	"pause",
+	"reset",
+	"play-once",
+	"play-forwards",
+	"play-backwards",
+	"replay",
+	"none"
+};
+</xmp>
+
+<dl dfn-type=enum-value dfn-for="AnimationTriggerAction">
+	: <dfn>play</dfn>
+	::  Corresponds to ''<animation-action>/play''.
+	: <dfn>pause</dfn>
+	::  Corresponds to ''<animation-action>/pause''.
+	: <dfn>reset</dfn>
+	::  Corresponds to ''<animation-action>/reset''.
+	: <dfn>play-once</dfn>
+	::  Corresponds to ''<animation-action>/play-once''.
+	: <dfn>play-forwards</dfn>
+	::  Corresponds to ''<animation-action>/play-forwards''.
+	: <dfn>play-backwards</dfn>
+	::  Corresponds to ''<animation-action>/play-backwards''.
+	: <dfn>replay</dfn>
+	::  Corresponds to ''<animation-action>/replay''.
+	: <dfn>none</dfn>
+	::  Corresponds to ''<animation-action>/none''.
+</dl>
+
+<div dfn-type=method class=methods
+	dfn-for="AnimationTrigger">
+
+: <dfn lt="addAnimation(Animation animation, AnimationTriggerAction activateAction, optional AnimationTriggerAction deactivateAction)">undefined addAnimation(|animation|, |activateAction|, |deactivateAction|)</dfn>
+::
+	Perform the following steps:
+
+	1. Let |trigger| be the object the method was called on.
+
+	2. Run the steps to [=attach an animation to a trigger=] with |trigger| as the |trigger| argument,
+		|animation| as the |animation| argument, |activateAction| as the |activateAction| argument,
+		and |deactivateAction| as the |deactivateAction| argument.
+
+	<div dfn-type=argument class=parameters
+		dfn-for="AnimationTrigger/addAnimation(animation, activateBehavior, deactivateBehavior)">
+
+		: <dfn>animation</dfn>
+		::
+			The [=animation=] to attach to the trigger.
+
+		: <dfn>activateAction</dfn>
+		::
+			The {{AnimationTriggerAction}} corresponding to the <<animation-action>> which is intended for the
+			trigger to associate with [=invoke activation|activation=]
+			for {{AnimationTrigger/addAnimation(animation, activateBehavior, deactivateBehavior)/animation}}.
+
+		: <dfn>deactivateAction</dfn>
+		::
+			The {{AnimationTriggerAction}} corresponding to the <<animation-action>> which is intended the trigger
+			to associate with [=invoke deactivation|deactivation=]
+			for {{AnimationTrigger/addAnimation(animation, activateBehavior, deactivateBehavior)/animation}}.
+
+	</div>
+
+	: <dfn lt="removeAnimation(animation)">undefined removeAnimation(|animation|)</dfn>
+	::
+		1. Let |trigger| be the object on which this method was called.
+
+		1. Run the steps to [=detach an animation from a trigger=] with |trigger| as the |trigger|
+			argument and |animation| as the |animation| argument.
+
+	<div dfn-type=argument class=parameters
+		dfn-for="AnimationTrigger/removeAnimation(animation)">
+
+		: <dfn>animation</dfn>
+		::
+			The animation to disassociate from the trigger.
+
+	</div>
+
+	</div>
+
 # Privacy Considerations # {#privacy-considerations}
 
 	There are no known privacy impacts of the features in this specification.