[css-animations-2] Rewrite keyframe processing to re-use (rather than re-define) the cascade.

Also structure it better editorially.

Author: fantasai

css-animations-2/Overview.bs

@@ -258,133 +258,102 @@ from its <a>owning element</a> always causes it to enter (or remain) in the
 <a>idle play state</a>.
 
 <h2 id="keyframes">
-Declaring Keyframes</h2>
+Assembling Keyframes</h2>
+
+<h3 id="keyframe-rules">
+Declaring Keyframes: the ''@keyframes'' rule</h3>
+
+See [[css-animations-1#keyframes]].
 
 <h3 id="keyframe-processing">
 Processing Keyframes</h3>
 
-For a given target (pseudo-)element, |element|, an animation name, |name|,
-and the position of the animation in |element|'s 'animation-name' list,
-|position|,
-[=keyframe=] objects are generated as follows:
-
-1.   Let |default timing function| be
-     the timing function at position |position|
-     of the [=resolved value=] of the 'animation-timing-function' for |element|,
-     repeating the list as necessary as described in
-     [[CSS-ANIMATIONS-1#animation-name]].
-
-1.   Let |default composite| be ''replace''.
-
-1.   Find the last ''@keyframes'' at-rule in document order
-     with <<keyframes-name>> matching |name|.
-
-     If there is no ''@keyframes'' at-rule
-     with <<keyframes-name>> matching |name|,
-     abort this procedure.
-     In this case no animation is generated,
-     and any existing animation matching |name| is canceled.
-
-1.   Let |keyframes| be an empty sequence of [=keyframe=] objects.
-
-1.   Let |animated properties| be an empty set of longhand CSS property names.
-
-1.   Perform a stable sort of the keyframe blocks in the ''@keyframes'' rule
-     by the offset specified in the keyframe selector,
-     and iterate over the result in reverse
-     applying the following steps:
-
-     1.   Let |keyframe offset| be the value of the keyframe selector
-          converted to a value in the range 0 &le; |keyframe offset| &le; 1.
-
-     1.   Let |keyframe timing function| be the value of
-          the last valid declaration of 'animation-timing-function'
-          specified on the keyframe block, or,
-          if there is no such valid declaration, |default timing function|.
-
-     1.   Let |keyframe composite| be the value of
-          the last valid declaration of 'animation-composition'
-          specified on the keyframe block, or,
-          if there is no such valid declaration, |default composite|.
-
-     1.   After converting |keyframe timing function| to its canonical form
-          (e.g. such that ''step-end'' becomes ''steps(1, end)'')
-          let |keyframe| refer to the existing keyframe in |keyframes| with
-          matching keyframe offset, timing function and composite, if any.
-
-          If there is no such existing keyframe,
-          let |keyframe| be a new empty keyframe with
-          offset, |keyframe offset|,
-          timing function, |keyframe timing function|,
-          composite, |keyframe composite|,
-          and prepend it to |keyframes|.
-
-     1.   Iterate over all declarations in the keyframe block and
-          add them to |keyframe| such that:
-
-          *     Each shorthand property is expanded to its longhand
-                subproperties.
-
-          *     All logical properties are converted to their
-                [[css-writing-modes-4#logical-to-physical|equivalent physical properties]].
-
-          *     For any expanded physical longhand properties that appear more
-                than once,
-                only the last declaration in source order is added.
-
-                Note, since multiple keyframe blocks may specify the same
-                |keyframe offset|,
-                and since this algorithm iterates over these blocks in reverse,
-                this implies that if any properties are encountered that
-                have already added at this same |keyframe offset|,
-                they should be skipped.
-
-     1.   Add each property name that was added to |keyframe|
-          to |animated properties|.
-
-1.   If there is no keyframe in |keyframes| with offset 0,
-     or if amongst the keyframes in |keyframes| with offset 0
-     not all of the properties in |animated properties| are present,
-
-     1.   Let |initial keyframe| be the [=keyframe=] in |keyframes|
-          with offset 0, timing function |default timing function|
-          and composite |default composite|.
-
-          If there is no such keyframe,
-          let |initial keyframe| be a new empty keyframe with offset 0,
-          timing function |default timing function|,
-          composite |default composite,
-          and add it to |keyframes| after the last keyframe with offset 0.
-
-     1.   For each property in |animated properties| that is not present
-          in some other keyframe with offset 0,
-          add the [=computed value=] of that property for |element|
-          to the keyframe.
-
-1.   Similarly, if there is no keyframe in |keyframes| with offset 1,
-     or if amongst the keyframes in |keyframes| with offset 1
-     not all of the properties in |animated properties| are present,
-
-     1.   Let |final keyframe| be the [=keyframe=] in |keyframes|
-          with offset 1, timing function |default timing function|
-          and composite |default composite|.
-
-          If there is no such keyframe,
-          let |final keyframe| be a new empty keyframe with offset 1,
-          timing function |default timing function|
-          and composite |default composite|,
-          and add it to |keyframes| after the last keyframe with offset 1.
-
-     1.   For each property in |animated properties| that is not present
-          in some other keyframe with offset 1,
-          add the [=computed value=] of that property for |element|
-          to the keyframe.
-
-Issue: The above procedure requires iterating over keyframe blocks in reverse.
-It could be rewritten so this is not required but that will likely change
-the behavior for some edge cases.
-We should verify what current implementations do and possible remove the
-requirement to iterate in reverse.
+For each animation effect defined by the <var>N</var>th item
+in the [=coordinated value list=] of the 'animation-*' properties
+on target (pseudo-)element |element|,
+its associated [=keyframes=] are generated as follows:
+
+1.  <strong>Set Defaults:</strong>
+
+    *   Let |default timing function| be the corresponding [=computed value=]
+        of 'animation-timing-function' on |element|.
+
+    *   Let |default composite| be ''replace''.
+
+    *   Let |keyframes| be an empty sequence of [=keyframe=] objects,
+        each possessing a
+        |keyframe offset|,
+        |keyframe timing function|,
+        |keyframe composite|,
+        and |keyframe values|.
+
+    *   Let |animated properties| be an empty set of CSS property names.
+
+1.  <strong>Collect Declared Keyframes:</strong>
+    1.  Find the last ''@keyframes'' at-rule in document order
+        with <<keyframes-name>> matching
+        the corresponding 'animation-name' value |name|.
+
+        If there is no ''@keyframes'' at-rule
+        with <<keyframes-name>> matching |name|
+        (or if |name| is ''animation-name/none''),
+        abort this procedure.
+        In this case no animation is generated,
+        and any existing animation matching |name| is canceled.
+
+    1.  Perform a stable sort on all [=keyframe blocks=] in the ''@keyframes'' rule
+        by their specified <<keyframe-selector>>
+        (treating ''@keyframe/from'' as ''0%'' and ''@keyframe/to'' as ''100%'').
+
+    1.  Group together all [=keyframe blocks=]
+        that share the same [=specified value|specified=] <<keyframe-selector>>
+        (treating ''@keyframe/from'' as ''0%'' and ''@keyframe/to'' as ''100%''),
+        last declared 'animation-timing-function' [=computed value=]
+        (defaulting to |default timing function| if there is no such declaration),
+        and last declared 'animation-composition' [=computed value=]
+        (defaulting to |default composite| if there is no such declaration).
+
+    1.  For each such group of matching [=keyframe blocks=],
+        ordered by their earliest [=keyframe block=] in the sorted order:
+
+            1.  [=Cascade=] together all of its [=declaration blocks=]
+                such that for each CSS property
+                (except those that are “not animatable”, which must be ignored)
+                the last declaration among all its [=keyframe blocks=]
+                takes precedence.
+                [[CSS-CASCADE-4]]
+
+                Note: The [=cascade=] will
+                expand [=shorthand properties=] into their [=sub-properties=]
+                and map together corresponding property pairs in each [=logical property group=]
+                according to the |element|’s [=computed value|computed=] [=writing mode=].
+
+            1.  Append to |keyframes| a new empty [=keyframe=] |keyframe|
+                with the group’s |keyframe offset|,
+                |keyframe timing function|,
+                and |keyframe composite|.
+                Give its |keyframe values|
+                the set of [=declared values=] resulting from this cascade.
+
+            1.  Add each property name that was added to its |keyframe properties|
+                to |animated properties|.
+
+1.  <strong>Generate Initial and Final Frames:</strong>
+
+    1.  Create two new [=keyframes=], |initial keyframe| and |final keyframe|,
+        assigning each |default timing function| as its |keyframe timing function|
+        and |default composite| as its |keyframe composite|.
+
+    1.  Give |initial keyframe| a |keyframe offset| of zero (''0%'')
+        and prepend it to |keyframes|;
+        give |final keyframe| a |keyframe offset| of one (''100%'')
+        and append it to |keyframes|.
+
+    1.  Add to the |keyframe properties| of |initial keyframe| and |final keyframe|
+        the [=computed value=] on |element|
+        of each property in |animated properties|
+        that is not already assigned to a [=keyframe=] in |keyframes|
+        that has a matching |keyframe offset|.
 
 <h2 id="animation-definition">
 Declaring Animations</h2>