[css-animations-2] Separate trigger concept from trigger instance. Define that event triggers can be defined to have enter/exit pairs, like timelines.

Author: tabatkins

css-animations-2/Overview.bs

@@ -743,8 +743,8 @@ Its values are:
         How many <<animation-action>>s a trigger accepts,
         and what exactly activates them,
         is determined by the type of the trigger.
-        <span class=note>([=Event triggers=] only take a single <<animation-action>>,
-        while [=timeline triggers=] can take one or two.)</span>
+        <span class=note>([=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.)</span>
         Specifying the wrong number of actions
         (too many or too few)
         is valid syntactically,
@@ -785,6 +785,18 @@ The 'animation' shorthand property syntax is as follows:
 
 <span class=prod><dfn>&lt;single-animation></dfn> = <<'animation-duration'>> || <<easing-function>> || <<'animation-delay'>> || <<single-animation-iteration-count>> || <<single-animation-direction>> || <<single-animation-fill-mode>> || <<single-animation-play-state>> || [ none | <<keyframes-name>> ] || <<single-animation-timeline>></span>
 
+
+<!-- Big Text: triggers
+
+█████▌ ████▌  ████  ███▌   ███▌  █████▌ ████▌   ███▌
+  █▌   █▌  █▌  ▐▌  █▌  █▌ █▌  █▌ █▌     █▌  █▌ █▌  █▌
+  █▌   █▌  █▌  ▐▌  █▌     █▌     █▌     █▌  █▌ █▌
+  █▌   ████▌   ▐▌  █▌ ██▌ █▌ ██▌ ████   ████▌   ███▌
+  █▌   █▌▐█    ▐▌  █▌  █▌ █▌  █▌ █▌     █▌▐█       █▌
+  █▌   █▌ ▐█   ▐▌  █▌  █▌ █▌  █▌ █▌     █▌ ▐█  █▌  █▌
+  █▌   █▌  █▌ ████  ███▌   ███▌  █████▌ █▌  █▌  ███▌
+-->
+
 <h2 id="animation-triggers">
 Triggers</h2>
 
@@ -819,14 +831,13 @@ A trigger can define multiple "types" of activation.
 (For example, [=timeline triggers=] can do different things on entry and exit.)
 
 A [=trigger=] is <em>used</em> 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 <<animation-action>>s)
-to do in response to that activation.
-
-Note: This design for [=triggers=],
+creating a <dfn export for=CSS>trigger instance</dfn> 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 <em>other</em> purposes in the future.
@@ -857,6 +868,17 @@ letting you define triggers that are only visible to subtrees
 and references that only search in that subtree
 (just like 'anchor-scope').
 
+<!-- Big Text: timeline
+
+█████▌ ████ █     █ █████▌ █▌    ████ █    █▌ █████▌
+  █▌    ▐▌  ██   ██ █▌     █▌     ▐▌  █▌   █▌ █▌
+  █▌    ▐▌  █▌█ █▐█ █▌     █▌     ▐▌  ██▌  █▌ █▌
+  █▌    ▐▌  █▌ █ ▐█ ████   █▌     ▐▌  █▌▐█ █▌ ████
+  █▌    ▐▌  █▌   ▐█ █▌     █▌     ▐▌  █▌  ██▌ █▌
+  █▌    ▐▌  █▌   ▐█ █▌     █▌     ▐▌  █▌   █▌ █▌
+  █▌   ████ █▌   ▐█ █████▌ █████ ████ █▌   ▐▌ █████▌
+-->
+
 <h3 id="timeline-triggers">
 Timeline Triggers</h3>
 
@@ -867,16 +889,16 @@ or leaves the trigger's <dfn export for="timeline trigger">exit range</dfn>.
 It is defined on an element with the 'timeline-trigger' shorthand property,
 or its longhands.
 
-A [=timeline trigger=] has a binary <dfn export for="timeline trigger">trigger state</dfn> associated with it;
+A [=timeline trigger=] [=trigger instance=] has a binary <dfn export for="timeline trigger">trigger state</dfn> 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 <dfn export for="timeline trigger">enter action</dfn>
-and switches the [=trigger state=] to "triggered";
+and switches the [=timeline trigger/trigger state=] to "triggered";
 while it's "triggered",
 the associated timeline <em>leaving</em> the trigger's [=exit range=]
 performs an associated <dfn export for="timeline trigger">exit action</dfn>
-and switches the [=trigger state=] to "untriggered".
+and switches the [=timeline-trigger/trigger state=] to "untriggered".
 
 Note: By default, the [=exit range=] is the same as the [=enter range=];
 even when manually specified,
@@ -1062,6 +1084,16 @@ rather than being settable in any order as is more common.
 Issue: I think we need the ''/'' to disambiguate the two ranges?
 
 
+<!-- Big Text: event
+
+█████▌ █▌   █▌ █████▌ █    █▌ █████▌
+█▌     █▌   █▌ █▌     █▌   █▌   █▌
+█▌     █▌   █▌ █▌     ██▌  █▌   █▌
+████   ▐▌   █  ████   █▌▐█ █▌   █▌
+█▌      █  ▐▌  █▌     █▌  ██▌   █▌
+█▌      ▐▌ █   █▌     █▌   █▌   █▌
+█████▌   ▐█    █████▌ █▌   ▐▌   █▌
+-->
 
 <h3 id="event-triggers">
 Event Triggers</h3>
@@ -1071,8 +1103,39 @@ 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.
 
-An [=event trigger=] only has a single action associated with it,
-which it performs every time the trigger is activated.
+An [=event trigger=] can be defined as either stateless or stateful:
+
+* If stateless, it has a single set of <dfn for="event trigger" lt="enter event">enter events</dfn>
+    that activate it.
+* If stateful, it has two sets of events, its [=enter events=]
+    and another set of <dfn for="event trigger" lt="exit event">exit events</dfn>.
+
+[=Event triggers=] are activated when one of its associated {{Event}}s are fired on the page
+with the trigger-defining element as its {{Event/target}}.
+If it's stateful,
+then its [=trigger instance=] has a binary <dfn export for="event trigger">trigger state</dfn>
+associated with it,
+initially "untriggered":
+while "untriggered", it only activates when the [=event trigger=] receives one of its [=enter events=],
+performing an associated <dfn export for="event trigger">enter action</dfn>
+and switching its [=event trigger/trigger state=] to "triggered";
+while "triggered", it only activates when it receives one of its [=exit events=],
+performing an associated <dfn export for="event trigger">exit action</dfn>
+and switching its [=event trigger/trigger state=] back to "untriggered".
+
+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 [=event trigger/enter action=],
+and the second, if provided, is its [=event trigger/exit action=];
+if the second is not provided,
+the [=event trigger/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 {{Event}}s or different ones.
@@ -1082,6 +1145,11 @@ 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=].
 
+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.
+
 
 <h4 id="event-trigger-name">
 Naming the Trigger: the 'event-trigger-name' property</h4>
@@ -1110,7 +1178,7 @@ Linking an Event: the 'event-trigger-source' property</h4>
 
 <pre class=propdef>
 Name: event-trigger-source
-Value: [ none | <<event-trigger-event>>+ ]#
+Value: [ none | <<event-trigger-event>>+ [ / <<event-trigger-event>>+ ]? ]#
 Initial: none
 Applies to: all elements
 Inherited: no
@@ -1121,22 +1189,32 @@ Animation type: not animatable
 
 The 'event-trigger-source' property
 specifies what event or events activate the [=event trigger=].
+Its values are:
+
+<dl dfn-type=value dfn-for=event-trigger-source>
+    : <dfn>none</dfn>
+    :: The corresponding entry in the [=coordinated value list=] does not define a trigger.
+
+    : <dfn><<event-trigger-event>>+ [ / <<event-trigger-event>>+ ]?</dfn>
+    :: 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=].
+</dl>
 
 <pre class=prod>
 <dfn><<event-trigger-event>></dfn> = activate | click | touch | dblclick | keypress(<<string>>) | ...
 </pre>
 
-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.
-
 
 <h4 id="event-trigger-shorthand">
 The 'event-trigger' Shorthand</h4>