[web-animations-1] Make commitStyles use an endpoint-inclusive active interval

Fixes w3c#5394.

Author: birtles

web-animations-1/Overview.bs

@@ -2801,6 +2801,11 @@ Animation effects {#animation-effects}
       <code>max(min(<a>start delay</a> + <a>active duration</a>,
                     <a for="animation effect">end time</a>), 0)</code>
 
+
+  Furthermore, an <dfn>endpoint-inclusive active interval</dfn> flag
+  may be specified when determining the phase.
+  If not specified, it is assumed to be false.
+
   An [=animation effect=] is in the
   <dfn export for="animation effect">before phase</dfn>
   if the animation effect's [=local time=]
@@ -2809,7 +2814,8 @@ Animation effects {#animation-effects}
 
   * the [=local time=] is less than the [=before-active boundary time=],
       <em>or</em>
-  * the [=animation direction=] is “backwards”
+  * the [=animation direction=] is “backwards”,
+      the [=endpoint-inclusive active interval=] flag is false,
       and the [=local time=] is equal to the [=before-active boundary time=].
 
   An [=animation effect=] is in the
@@ -2820,7 +2826,8 @@ Animation effects {#animation-effects}
 
   * the [=local time=] is greater than the [=active-after boundary time=],
       <em>or</em>
-  * the [=animation direction=] is “forwards”
+  * the [=animation direction=] is “forwards”,
+      the [=endpoint-inclusive active interval=] flag is false,
       and the [=local time=] is equal to the [=active-after boundary time=].
 
   An [=animation effect=] is in the
@@ -3001,34 +3008,24 @@ Animation effects {#animation-effects}
   </div>
 
   <div class=example>
-    Alternatively, the author can set the specified style
-    at the start of the animation and then animate <em>from</em>
-    the original value as illustrated below:
+    More conveniently, an {{Animation}}'s {{Animation/commitStyles}} method can
+    be used to produce the same effect.
 
     <pre highlight=javascript>
-      elem.style.transform = 'translateY(100px)';
-      elem.animate({ transform: 'none', offset: 0 }, 200);
+      elem.animate({ transform: 'translateY(100px)' }, 200).finished.then(() => {
+        elem.commitStyles();
+      });
     </pre>
   </div>
 
   <div class=example>
-    Complex effects involving layering many animations on top of one another
-    could require temporary use of forwards fill modes
-    to capture the final value of an animation before canceling it.
-    For example:
+    Alternatively, the author can set the specified style
+    at the start of the animation and then animate <em>from</em>
+    the original value as illustrated below:
 
     <pre highlight=javascript>
-      elem.addEventListener('click', async evt => {
-        const animation = elem.animate(
-          { transform: \`translate(${evt.clientX}px, ${evt.clientY}px)\` },
-          { duration: 800, fill: 'forwards' }
-        );
-        await animation.finished;
-        // commitStyles will record the style up to and including \`animation\` and
-        // update elem's specified style with the result.
-        animation.commitStyles();
-        animation.cancel();
-      });
+      elem.style.transform = 'translateY(100px)';
+      elem.animate({ transform: 'none', offset: 0 }, 200);
     </pre>
   </div>
 
@@ -4890,6 +4887,28 @@ The {{Animation}} interface {#the-animation-interface}
       calling this method <em>does</em> trigger a [=style change event=]
       (see [[#model-liveness]]).
 
+      <div class=note>
+
+        In order to simplify the common case
+        of persisting a completed animation,
+        the procedure to [=commit computed styles=]
+        uses endpoint-*inclusive* timing (see [[#interval-timing]])
+        when determining the phase of the animation
+        (see [[#animation-effect-phases-and-states]]).
+
+        As a result, the following code will persist
+        the `transform: translateY(100px)` style in specified style
+        despite not having a
+        [=fill mode=] of [=fill mode/forwards=] or [=fill mode/both=].
+
+        <pre highlight=javascript>
+          elem.animate({ transform: 'translateY(100px)' }, 200).finished.then(() => {
+            elem.commitStyles();
+          });
+        </pre>
+
+      </div>
+
       <div class=note>
 
         Since the procedure to [=commit computed styles=]
@@ -4986,7 +5005,11 @@ The {{Animation}} interface {#the-animation-interface}
             1. Let |effect value| be the result of calculating
                 the result of |partialEffectStack| for |property|
                 using |target|'s computed style
-                (see [[#calculating-the-result-of-an-effect-stack]]).
+                (see [[#calculating-the-result-of-an-effect-stack]]) and
+                setting the [=endpoint-inclusive active interval=] flag
+                to true
+                when calculating the animation effect phase
+                (see [[#animation-effect-phases-and-states]]).
 
             1. [=Set a CSS declaration=] of |property| for |effect value|
                 in |inline style|.