[web-animation-2] Making currentTime and startTime CSSNumerish (w3c#6479)

The animation attributes currentTime and startTime were nullable doubles and represented times in units of milliseconds. These units do not align well with progress based animations where it is more natural to work in percentages.

With this change, progress based animations expect and report times as percentages. When setting current or start time, the value may be expressed as a double with implicit units of milliseconds, or as a CSSNumericValue with duration units ('s' or 'ms') when the animation is associated with a time based timeline.

Co-authored-by: Kevin Ellis <kevers@chromium.org>

Author: kevers-google

web-animations-2/Overview.bs

@@ -171,11 +171,11 @@ Add:
 > 1.  If the [=iteration duration=] is auto, then perform the following steps.
 >     *   Set [=start delay=] and [=end delay=] to 0, as it is not
 >         possible to mix time and proportions.
->         
+>
 >         Note: Future versions may allow these properties to be assigned
 >         percentages, at which point the delays are only to be ignored if
 >         their values are expressed as times and not as percentages.
->         
+>
 >     Otherwise:
 >          1. Let <var>total time</var> be equal to |end time|
 >          1. Set [=start delay=] to be the result of evaluating
@@ -256,7 +256,7 @@ follows:
 
                     :   If |previous play state| is 'paused':
 
-                    :: If |previous progress| is resolved:
+                    ::  If |previous progress| is resolved:
 
                         1.  Set the flag |reset current time on resume| to true.
                         1.  Set [=start time=] to unresolved.
@@ -338,6 +338,36 @@ descendant effects and custom effects such that the first condition is:
 >     effect</a> or executing any <a>custom effects</a> associated with an
 >     <a>animation effect</a>.
 
+<h4 id='validating-a-css-numberish-time'>Validating a CSSNumberish time</h4>
+
+The procedure to <dfn>validate a CSSNumberish time</dfn> for an input
+value of <var>time</var> is based on the first condition that matches:
+
+<dl class="switch">
+
+    :   If <em>all</em> of the following conditions are true:
+
+        *   The animation is associated with a [=progress-based timeline=], and
+        *   <var>time</var> is not a CSSNumeric value with percent units:
+
+    ::  <a>throw</a> a <span class="exceptionname">TypeError</span>.
+    ::  return false;
+
+    :   If <em>all</em> of the following conditions are true:
+
+        *   The animation is not associated with a [=progress-based timeline=],
+            and
+        *   <var>time</var> is a CSSNumericValue, and
+        *   the units of time are not <a type lt="<time>">duration units</a>:
+
+    ::  <a>throw</a> a <span class="exceptionname">TypeError</span>.
+    ::  return false.
+
+    :   Oterwise
+    ::  return true.
+
+</dl>
+
 
 <h4 id='setting-the-current-time-of-an-animation'>Setting the current time of an
 Animation</h4>
@@ -357,31 +387,39 @@ an animation, <var>animation</var>, to <var>seek time</var> is as follows:
 
     1.   Abort these steps.
 
-1.  Update either <var>animation</var>'s <a>hold time</a> or
-    [=start time=] as follows:
+    1.  Let <var>valid seek time</var> be the result of running the
+        [=validate a CSSNumberish time=] procedure with <var>seek time</var>
+        as the input.
 
-    <dl class="switch">
+    1.  If <var>valid seek time</var> is false, abort this procedure.
 
-        :   If <em>any</em> of the following conditions are true:
+    1.  Update either <var>animation</var>'s <a>hold time</a> or
+        [=start time=] as follows:
 
-            *   <var>animation</var>'s <a>hold time</a> is
-                <a lt="unresolved">resolved</a>, or
-            *   <var>animation</var>'s [=start time=]
-                is <a lt="unresolved">unresolved</a>, or
-            *   <var>animation</var> has no associated <a>timeline</a> or the
-                associated <a>timeline</a> is
-                <a lt="inactive timeline">inactive</a>, or
-            *   <var>animation</var>'s [=playback rate=] is 0,
+        <dl class="switch">
 
-        ::  Set <var>animation</var>'s <a>hold time</a> to <var>seek time</var>.
+            :   If <em>any</em> of the following conditions are true:
 
-        :   Otherwise,
-        ::  Set <var>animation</var>'s [=start time=] to the result of evaluating
-            <code>|timeline time| - (|seek time| / [=playback rate=])</code>
-            where <var>timeline time</var> is the current <a>time value</a>
-            of <a>timeline</a> associated with <var>animation</var>.
+                *   <var>animation</var>'s <a>hold time</a> is
+                    <a lt="unresolved">resolved</a>, or
+                *   <var>animation</var>'s [=start time=]
+                    is <a lt="unresolved">unresolved</a>, or
+                *   <var>animation</var> has no associated <a>timeline</a> or
+                    the associated <a>timeline</a> is
+                    <a lt="inactive timeline">inactive</a>, or
+                *   <var>animation</var>'s [=playback rate=] is 0,
 
-    </dl>
+            ::  Set <var>animation</var>'s <a>hold time</a> to
+                <var>seek time</var>.
+
+            :   Otherwise,
+            ::  Set <var>animation</var>'s [=start time=] to the result of
+                evaluating
+                <code>|timeline time| - (|seek time| / [=playback rate=])</code>
+                where <var>timeline time</var> is the current <a>time value</a>
+                of <a>timeline</a> associated with <var>animation</var>.
+
+        </dl>
 
 1.  If <var>animation</var> has no associated <a>timeline</a> or the associated
     <a>timeline</a> is <a lt="inactive timeline">inactive</a>,
@@ -423,6 +461,12 @@ The procedure to <dfn>set the start time</dfn>
 of <a>animation</a>, <var>animation</var>, to <var>new start time</var>,
 is as follows:
 
+1.  Let <var>valid start time</var> be the result of running the
+    [=validate a CSSNumberish time=] procedure with
+    <var>new start time</var> as the input.
+
+1.  If <var>valid start time</var> is false, abort this procedure.
+
 1.  Let <var>timeline time</var> be the current <a>time value</a> of the
     <a>timeline</a> that <var>animation</var> is associated with.
     If there is no <a>timeline</a> associated with <var>animation</var> or the
@@ -2018,6 +2062,44 @@ partial interface AnimationTimeline {
 
 </div>
 
+<h3 id="the-animation-interface">The <code>Animation</code> interface</h3>
+
+Update the startTime and currentTime of the Animation interface as follows:
+
+<pre class="idl">
+[Exposed=Window]
+partial interface Animation : EventTarget {
+    attribute CSSNumberish?       startTime;
+    attribute CSSNumberish?       currentTime;
+};
+</pre>
+
+Replace [=start time=] and [=current time=] attribute descriptions with:
+
+<div class='attributes'>
+
+:   <dfn attribute for=Animation>startTime</dfn>
+::  Update the description as:
+
+    > The [=start time=] of this animation. When associated with a
+    > [=progress-based timeline=], [=start time=] must be returned as a
+    > {{CSSNumericValue}} with percent units. Otherwise [=start time=] must be
+    > returned as a double value, representing the time in units of
+    > milliseconds. Setting this attribute updates the [=start time=] using the
+    > procedure to <a>set the start time</a> of this object to the new value.
+
+:   <dfn attribute for=Animation>currentTime</dfn>
+::  update the description as:
+
+    > The <a>current time</a> of this animation. When associated with a
+    > [=progress-based timeline=], <a>current time</a> must be returned as a
+    > {{CSSNumericValue}}. with percent units. Otherwise <a>current time</a>
+    > must be returned as a double value, representing the time in units of
+    > milliseconds. Setting this attribute follows the procedure to
+    > <a>set the current time</a> of this object to the new value.
+
+</div>
+
 <h3 id="the-animationeffect-interface">The <code>AnimationEffect</code> interface</h3>
 
 <pre class='idl'>