[web-animations] Use 'auto' for unspecified keyframe-specific composite operations (#3001)

This fixes #3000.

Author: birtles

web-animations-1/Overview.bs

@@ -3269,13 +3269,13 @@ The <a>timing function</a> specified on the last keyframe in the
 list is never applied.
 
 Each <a>keyframe</a> may have a <dfn>keyframe-specific composite
-operation</dfn> that, if not null,  is applied to all values
-specified in that <a>keyframe</a>.
+operation</dfn> that, if set, is applied to all values specified in that
+<a>keyframe</a>.
 The possible operations and their meanings are identical to those defined
 for the <a>composite operation</a> associated with the <a>keyframe effect</a>
 as a whole in [[#effect-composition]].
 If the <a>keyframe-specific composite operation</a> for a <a>keyframe</a>
-is null, the <a>composite operation</a> specified for the
+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.
 
 <h4 id="calculating-computed-keyframes">Calculating computed keyframes</h4>
@@ -4669,10 +4669,10 @@ interface KeyframeEffect : AnimationEffect {
       dictionary ComputedKeyframe {
           // ... property-value pairs ...
           // i.e. DOMString propertyName
-          double?             offset = null;
-          double              computedOffset;
-          DOMString           easing = "linear";
-          CompositeOperation? composite = null;
+          double?                  offset = null;
+          double                   computedOffset;
+          DOMString                easing = "linear";
+          CompositeOperationOrAuto composite = "auto";
       };
       </pre>
 
@@ -4701,8 +4701,9 @@ interface KeyframeEffect : AnimationEffect {
       ::  The <a>keyframe-specific composite operation</a> used to combine the
           values specified in this keyframe with the <a>underlying value</a>.
 
-          This member will be <code>null</code> if the <a>composite
-          operation</a> specified on the <a>keyframe effect</a> is being used.
+          This member will be {{CompositeOperationOrAuto/auto}} if the
+          <a>composite operation</a> specified on the <a>keyframe effect</a> is
+          being used.
 
     </div>
 
@@ -4722,10 +4723,10 @@ interface KeyframeEffect : AnimationEffect {
 
             <pre class='idl'>
              dictionary BaseComputedKeyframe {
-                 double?             offset = null;
-                 double              computedOffset;
-                 DOMString           easing = "linear";
-                 CompositeOperation? composite = null;
+                 double?                  offset = null;
+                 double                   computedOffset;
+                 DOMString                easing = "linear";
+                 CompositeOperationOrAuto composite = "auto";
             };
             </pre>
 
@@ -4999,17 +5000,17 @@ WebIDL-like definition:
 dictionary Keyframe {
     // ... property-value pairs ...
     // i.e. DOMString propertyName
-    double?              offset = null;
-    DOMString            easing = "linear";
-    CompositeOperation?  composite = null;
+    double?                   offset = null;
+    DOMString                 easing = "linear";
+    CompositeOperationOrAuto  composite = "auto";
 };
 
 dictionary PropertyIndexedKeyframes {
     // ... property-value and property-valuelist pairs ...
     // i.e. (DOMString or sequence&amp;lt;DOMString&amp;gt;) propertyName
     (double? or sequence&lt;double?&gt;)                         offset = [];
     (DOMString or sequence&lt;DOMString&gt;)                     easing = [];
-    (CompositeOperation? or sequence&lt;CompositeOperation?&gt;) composite = [];
+    (CompositeOperationOrAuto or sequence&lt;CompositeOperationOrAuto&gt;) composite = [];
 };
 
 typedef (sequence&lt;Keyframe&gt; or PropertyIndexedKeyframes) KeyframeArgument;
@@ -5042,8 +5043,8 @@ The meaning and allowed values of each argument is as follows:
 ::  The <a>keyframe-specific composite operation</a> used to combine the values
     specified in this keyframe with the <a>underlying value</a>.
 
-    If <code>null</code>, the <a>composite operation</a> specified on the
-    <a>keyframe effect</a> will be used.
+    If {{CompositeOperationOrAuto/auto}}, the <a>composite operation</a>
+    specified on the <a>keyframe effect</a> will be used.
 
 
 Since this type cannot be expressed in WebIDL, its processing is defined in
@@ -5096,7 +5097,7 @@ otherwise, using the following procedure:
         dictionary BasePropertyIndexedKeyframe {
             (double? or sequence&lt;double?&gt;)                         offset = [];
             (DOMString or sequence&lt;DOMString&gt;)                     easing = [];
-            (CompositeOperation? or sequence&lt;CompositeOperation?&gt;) composite = [];
+            (CompositeOperationOrAuto or sequence&lt;CompositeOperationOrAuto&gt;) composite = [];
         };
         </pre>
 
@@ -5105,9 +5106,9 @@ otherwise, using the following procedure:
 
         <pre class='idl'>
         dictionary BaseKeyframe {
-            double?             offset = null;
-            DOMString           easing = "linear";
-            CompositeOperation? composite = null;
+            double?                  offset = null;
+            DOMString                easing = "linear";
+            CompositeOperationOrAuto composite = "auto";
         };
         </pre>
 
@@ -5330,11 +5331,11 @@ keyframes using the following procedure:
         1.  If the &ldquo;composite&rdquo; member of the <var>property-indexed
             keyframe</var> is <em>not</em> an empty sequence:
 
-            1.  Let <var>composite modes</var> be a sequence of <a>nullable</a>
-                <a>composite operations</a> assigned from the
+            1.  Let <var>composite modes</var> be a sequence of
+                {{CompositeOperationOrAuto}} values assigned from the
                 &ldquo;composite&rdquo; member of <var>property-indexed
                 keyframe</var>.
-                If that member is a single <a>nullable</a> <a>composite
+                If that member is a single {{CompositeOperationOrAuto}} value
                 operation</a>, let <var>composite modes</var> be a sequence of
                 length one, with the value of the &ldquo;composite&rdquo; as its
                 single item.
@@ -5345,7 +5346,8 @@ keyframes using the following procedure:
                 from the beginning of the list until <var>composite modes</var>
                 has as many items as <var>processed keyframes</var>.
 
-            1.  Assign each non-null value in <var>composite modes</var> to the
+            1.  Assign each value in <var>composite modes</var> that is not
+                {{CompositeOperationOrAuto/auto}} to the
                 <a>keyframe-specific composite operation</a> on the
                 <a>keyframe</a> with the corresponding position in
                 <var>processed keyframes</var> until the end of <var>processed
@@ -5435,7 +5437,8 @@ dictionary KeyframeEffectOptions : EffectTiming {
     animation with the <a>effect stack</a>, as specified by one
     of the <a>CompositeOperation</a> enumeration values.
     This is used for all <a>keyframes</a> that specify
-    a null <a>keyframe-specific composite operation</a>.
+    a {{CompositeOperationOrAuto/auto}} <a>keyframe-specific composite
+    operation</a>.
 
 </div>
 
@@ -5462,39 +5465,51 @@ enum IterationCompositeOperation {"replace", "accumulate"};
     subsequent iterations of an <a>animation effect</a> build
     on the final value of the previous iteration.
 
-<h3 id="the-compositeoperation-enumeration">The <code>CompositeOperation</code> enumeration</h3>
+<h3 id="the-compositeoperation-enumeration">The <code>CompositeOperation</code> and <code>CompositeOperationOrAuto</code> enumerations</h3>
 
-The possible values of an <a>animation effect</a>'s
+The possible values of an <a>keyframe effect</a>'s
 composition behavior are represented by the
 <dfn>CompositeOperation</dfn> enumeration.
 
 <pre class='idl'>
 enum CompositeOperation {"replace", "add", "accumulate"};
 </pre>
 
-:   <code>replace</code>
+:   <dfn enum-value for=CompositeOperation><dfn enum-value for=CompositeOperationOrAuto>replace</dfn></dfn>
 ::  Corresponds to the <a
     lt="composite operation replace">replace</a>
     <a>composite operation</a> value such that
     the <a>animation effect</a> overrides the <a>underlying value</a> it
     is combined with.
 
-:   <code>add</code>
+:   <dfn enum-value for=CompositeOperation><dfn enum-value for=CompositeOperationOrAuto>add</dfn></dfn>
 ::  Corresponds to the <a
     lt="composite operation add">add</a>
     <a>composite operation</a> value such that
     the <a>animation effect</a> is <a
     lt="animation addition">added</a> to the <a>underlying value</a>
     with which it is combined.
 
-:   <code>accumulate</code>
+:   <dfn enum-value for=CompositeOperation><dfn enum-value for=CompositeOperationOrAuto>accumulate</dfn></dfn>
 ::  Corresponds to the <a
     lt="composite operation accumulate">accumulate</a>
     <a>composite operation</a> value such that
     the <a>animation effect</a> is <a
     lt="animation accumulation">accumulated</a> on to the
     <a>underlying value</a>.
 
+The possible values of a [=keyframe=]'s composition behavior share the same
+values as the {{CompositeOperation}} enumeration along with the additional
+{{CompositeOperationOrAuto/auto}} value.
+
+<pre class='idl'>
+enum CompositeOperationOrAuto {"replace", "add", "accumulate", "auto"};
+</pre>
+
+:   <dfn enum-value for=CompositeOperationOrAuto>auto</dfn>
+::  Indicates that the [=composite operation=] of the associated [=keyframe
+    effect=] should be used.
+
 <h3 id="the-animatable-interface-mixin">The <code>Animatable</code> interface mixin</h3>
 
 Objects that may be the target of an {{KeyframeEffect}} object implement
@@ -5972,15 +5987,17 @@ The following changes have been made since the <a
     the attribute name used to specify keyframe offsets.
 *   Updated the procedure to <a>process a keyframes argument</a> to allow
     specifying <code>offset</code>, <code>composite</code> and multiple
-    <code>easing</code> values including allowing <code>null</code> values for
-    <code>composite</code>.
+    <code>easing</code> values including allowing
+    {{CompositeOperationOrAuto/auto}} values for <code>composite</code>.
 *   Changed the type of the
     {{KeyframeEffect/KeyframeEffect(target, keyframes,
     options)/target}} argument to the {{KeyframeEffect}} and
     (now obsolete) <code>KeyframeEffectReadOnly</code> constructors,
     and the {{KeyframeEffect/target}} member of these same interfaces,
     from <code>Animatable?</code> to <code>(Element or CSSPseudoElement)?</code>
     (<a href="https://github.com/w3c/web-animations/issues/186">#186</a>).
+*   Made unspecified [=composite operations=] on [=keyframes=] be represented by
+    {{CompositeOperationOrAuto/auto}} values.
 *   Dropped the <code>SharedKeyframeList</code> interface.
 *   Converted {{Animatable}} from a <code>[NoInterfaceObject]</code> interface
     to an [=interface mixin=].