[web-animations-1] Specify how to compute property values

When it comes to the term "computed value", the spec is currently
very confused. It appears to be making several references to
"the" computed value (as in [1]), when in reality the intention is
(I believe) to apply the *process* that calculates the computed
value ([1]) to the value specified (locally) in the keyframe. This
process is not described in a reusable way anywhere (I think), so I've
added the algorithm "compute a property value" for this. I'm using
the term "property value", since it's already extensively used in this
spec. Possibly it would be more suited for css-cascade, but I'm
proposing it for this spec until we need it somewhere else.

In general I want to maintain a clear distinction between when we
mean the actual computed value [1], and when we mean some value that
has undergone the "compute a property value" process. Hence, I think
we should avoid referring to a value that has undergone the
"compute a property value" process as "a" computed value, as it's
too easily confused with *the* computed value.

I've included some text and an examples that hopefully clarify
the expected interpolation behavior a little bit. It seemed somewhat
natural to place this in the "Computing property values" section,
since resolving dependencies is part of the process when computing
values.

[1] https://drafts.csswg.org/css-cascade/#computed

Author: Anders Hartvoll Ruud

web-animations-1/Overview.bs

@@ -3297,13 +3297,49 @@ If the <a>keyframe-specific composite operation</a> for a <a>keyframe</a>
 is not set, the <a>composite operation</a> specified for the
 <a>keyframe effect</a> as a whole is used for values specified in that keyframe.
 
+### Computing property values ### {#computing-property-values}
+
+<div algorithm>
+To <dfn>compute a property value</dfn> given a property <var>property</var>,
+a value <var>value</var>, and an {{Element}} <var>element</var>:
+resolve <var>value</var> according to the "Computed Value" line of the
+<var>property</var>'s definition table, using the <a>computed values</a> of
+<var>element</var> as the context for resolving dependencies, and return the
+result.
+
+  Note: The <a>computed values</a> on <var>element</var> are not affected by
+  this algorithm.
+
+This algorithm implies that property values specified in keyframes can
+establish order dependencies. When <a>computing a property value</a>, the
+<a>computed values</a> of dependencies held by <var>value</var> must be
+calculated <em>first</em>.
+
+<div class="example">
+<pre class="lang-javascript">
+var animation = elem.animate([{ fontSize: '10px', width: '10em' },
+                              { fontSize: '20px', width: '20em' }], 1000);
+animation.currentTime = 500;
+console.log(getComputedStyle(elem).fontSize); // Should be 15px
+console.log(getComputedStyle(elem).width); // Should be 225px
+</pre>
+In this example, in order to <a>compute a property value</a> for
+<code>10em</code>, we must know the <a>computed value</a> of
+'font-size' on the <a>target element</a>, which in turn is determined
+by the <a>effect value</a> for 'font-size', which in turn requires that we
+compute property values for 'font-size'. Hence, computing property
+values are subject to ordering constraints.
+</div>
+
+</div>
+
 ### Calculating computed keyframes ### {#calculating-computed-keyframes}
 
 Before calculating the <a>effect value</a> of a <a>keyframe effect</a>,
-the property values specified on its <a>keyframes</a> are resolved to
-<a>computed values</a>, and the offset to use for any keyframes with a null
-<a>keyframe offset</a> is computed. The result of resolving these values is
-a set of <dfn>computed keyframes</dfn>.
+the property values on its <a>keyframes</a> are
+<a href="#computing-property-values">computed</a>, and the offset to use for any
+keyframes with a null <a>keyframe offset</a> is computed. The result of
+resolving these values is a set of <dfn>computed keyframes</dfn>.
 
 The calculated <a>keyframe offsets</a> of a set of <a>keyframe</a> that
 includes suitable values for each null <a>keyframe offset</a> are referred
@@ -3367,24 +3403,25 @@ an <a>effect target</a> for which computed property values can be calculated.
     1.  Add a new empty <a>keyframe</a>, <var>computed keyframe</var>, to
         <var>computed keyframes</var>.
 
-    1.  For each property specified in <var>keyframe</var>, calculate the
-        computed value specified on <var>keyframe</var> using the <a>effect
-        target</a> as the context for computing values and add the
-        corresponding property and computed value to <var>computed
-        keyframe</var>.
-        For shorthand properties, add the equivalent longhand properties.
-        For logical properties [[!CSS-LOGICAL-1]], add the [=equivalent physical
-        properties=] [[!CSS-WRITING-MODES-4]] based on the computed value of
-        'writing-mode' and/or 'direction' for the <a>effect target</a>.
+    1.  For each property specified in <var>keyframe</var>:
+        -   <a>Compute a property value</a> using the value specified on
+            <var>keyframe</var> as the value, and the <a>target element</a> as
+            the element; then add the property and resulting value to
+            <var>computed keyframe</var>.
+        -   For shorthand properties, add the equivalent longhand properties.
+        -   For logical properties [[!CSS-LOGICAL-1]], add the [=equivalent physical
+            properties=] [[!CSS-WRITING-MODES-4]] based on the computed value of
+            'writing-mode' and/or 'direction' for the <a>effect target</a>.
 
         For example, if <var>keyframe</var> has a value of &lsquo;12pt&rsquo;
-        for the 'border-width' property, the user agent may produce a computed
-        value of &lsquo;16px&rsquo; for each of the longhand properties:
+        for the 'border-width' property, the user agent may
+        <a>compute a property value</a>
+        of &lsquo;16px&rsquo; for each of the longhand properties:
         'border-bottom-width', 'border-left-width', 'border-right-width', and
         'border-top-width'.
         As a result, <var>computed keyframe</var> would <em>not</em> have a
         value for the 'border-width' property, but would instead include
-        each of the longhand properties, and each with the computed value,
+        each of the longhand properties, and each with the value
         &lsquo;16px&rsquo;.
 
         If conflicts arise when expanding shorthand properties or replacing
@@ -3568,6 +3605,19 @@ Note: this procedure permits overlapping <a>keyframes</a>.
     or equal to 1 is the value of the first <a>keyframe</a> or the last
     <a>keyframe</a> in <var>keyframes</var> respectively.
 
+<div class="note">
+    Note that <a>computed keyframes</a> are "live": user-agents must behave
+    as if they are recreated every time the <a>effect value</a> is calculated.
+
+    For example, if there is an ongoing transition on the 'font-size' property
+    from <code>10px</code> to <code>20px</code>, a property value specified as
+    <code>1em</code> in a <a>keyframe</a> would during
+    <a href="#calculating-computed-keyframes">keyframe computation</a>
+    resolve against the <a>computed value</a> in the range
+    [<code>10px</code>, <code>20px</code>] produced by the transition on
+    'font-size'.
+</div>
+
 <div class="issue">
     In the presence of certain timing functions, the input iteration
     progress to an animation effect is not limited to the range [0, 1].