Rewrite append() to be on Infra terms. Rename the weirdly-named algorithm.

Author: tabatkins

css-typed-om/Overview.bs

@@ -84,6 +84,7 @@ spec:infra;
     type: dfn;
         text: list
         text: code point
+        text: string
 </pre>
 
 Introduction {#intro}
@@ -242,25 +243,22 @@ probably in an appendix.
     that have transitioned from being [=single-valued=] to [=list-valued=].
     To ensure that code written at a time when a property was [=single-valued=]
     does not break when it becomes [=list-valued=] in the future,
-    the {{CSSPropertyMap}} is a <b>multi-map</b>;
+    the {{StylePropertyMap}} is a <b>multi-map</b>;
     it stores <em>list</em> of values for each key,
     but allows you to interact with it as if there was only a single value for each key as well.
 
-    This means that multiple values for a single property in a {{CSSPropertyMap}}
+    This means that multiple values for a single property in a {{StylePropertyMap}}
     do not represent multiple successive definition of that property's value;
     instead, they represent multiple comma-separated sub-values in a single property value,
     like each "layer" in a 'background-image' property.
 </div>
 
-The <dfn method for=StylePropertyMap>append(DOMString <var>property</var>,
-(CSSStyleValue or DOMString)... <var>values</var>)</dfn> method, when invoked, must
-[=append to a StylePropertyMap=] with property <var>property</var> and values <var>values</var>.
-
 <div algorithm>
-    To <dfn>append to a StylePropertyMap</dfn> given a <var>property</var> and a list of
-    <var>values</var>, run these steps:
+    The <dfn method for=StylePropertyMap>append(|property|, ...|values|)</dfn> method,
+    when called on a {{StylePropertyMap}} |this|,
+    must perform the following steps:
 
-    1. If |property| does not start with two dashes (U+002D HYPHEN),
+    1. If |property| is not a [=custom property name string=],
         let |property| be |property| [=ASCII lowercased=].
 
     2. If |property| is not a [=supported property name=],
@@ -269,17 +267,20 @@ The <dfn method for=StylePropertyMap>append(DOMString <var>property</var>,
     3. If |property| is not a [=list-valued property=],
         [=throw=] a {{TypeError}} and exit this algorithm.
 
-    4. If {{StylePropertyMap}}’s [=contained properties map=] contains an entry for |property|,
-        let |entry| be that entry.
-        Otherwise, create a new entry for |property| with an empty list,
-        add it to the [=contained properties map=],
-        and let |entry| be the newly-created entry.
+    4. Let |props| be |this|’s [=contained properties map=].
 
-    5. Let |values to append| be the empty list.
+    5. If |props|[|property|] does not [=map/exist=],
+        [=map/set=] |props|[|property|] to an empty [=list=].
 
-    6. For each |value| in |values| if the <a>algorithm that coerces |value| into an appropriate type for a given property</a> does not throw an error, append the returned object to |values to append|.
+    6. Let |temp values| be an empty [=list=].
 
-    7. Append |values to append| to the end of |entry|’s list.
+    7. For each |value| in |values|,
+        [=normalize a style value=] with |property| and |value|,
+        and [=list/append=] the returned value to |temp values|.
+
+    <!-- Using a temp list so that nothing gets mutated if normalizing ends up throwing an error. -->
+
+    8. [=list/Append=] the entries of |temp values| to |props|[|property|].
 </div>
 
 <div algorithm>
@@ -296,17 +297,20 @@ The <dfn method for=StylePropertyMap>append(DOMString <var>property</var>,
 </div>
 
 <div algorithm>
-    This section describes the <dfn>algorithm that coerces value into an appropriate type for a given property</dfn>, or fails and throws a {{TypeError}}:
-        : If |value| is a {{CSSStyleValue}},
-        :: If |value| does not match the grammar of a [=list-valued property iteration=] of |property|,
-            [=throw=] a {{TypeError}} and exit this algorithm.
-            Otherwise, return the |value|.
-        : If |value| is a {{DOMString}},
-        ::    [=Parse a CSSStyleValue=] with property |property| and value |value| and return the resulting |value|.
-            If the result is null,
-            [=throw=] a {{TypeError}} and exit this algorithm.
-            Otherwise, append each [=list-valued property iteration=] in the result to a |values to append| object
-            and return |values to append|.
+    To <dfn export>normalize a style value</dfn>,
+    given a [=string=] |property|
+    and a [=string=] or {{CSSStyleValue}} |value|:
+
+    : If |value| is a {{CSSStyleValue}},
+    :: If |value| does not match the grammar of a [=list-valued property iteration=] of |property|,
+        [=throw=] a {{TypeError}} and exit this algorithm.
+        Otherwise, return the |value|.
+
+    : If |value| is a {{DOMString}},
+    ::  [=Parse a CSSStyleValue=] with property |property|, value |value|, and |parseMultiple| set to `false`,
+        and return the result.
+
+        Note: This can throw a {{TypeError}} instead.
 </div>
 
 <div algorithm>
@@ -415,6 +419,13 @@ the [=contained properties map=]. This list of properties is sorted in the follo
 
 [=computed StylePropertyMap=], [=declared StylePropertyMap=] and [=inline StylePropertyMap=] are all live objects: the attributes and methods on these objects must operate on the actual underlying data, not a snapshot of the data.
 
+A [=string=] is a <dfn>custom property name string</dfn>
+if it starts with two dashes (U+002D HYPHEN-MINUS), like <code>--foo</code>.
+(This corresponds to the <<custom-property-name>> production,
+but applies to [=strings=],
+rather than [=identifiers=];
+it can be used without invoking the CSS parser.)
+
 Issue(148): add detailed descriptions of the rest of the methods on {{StylePropertyMap}}
 
 Issue(268): stringification