Overview.bs

<pre class='metadata'>
Title:  CSS Typed OM Level 1
Status: ED
Group: houdini
ED: https://drafts.css-houdini.org/css-typed-om-1/
TR: https://www.w3.org/TR/css-typed-om-1/
Previous Version: https://www.w3.org/TR/2016/WD-css-typed-om-1-20160607/
Shortname: css-typed-om
Level: 1
Abstract: Converting CSSOM value strings into meaningfully typed JavaScript representations and back can incur a significant performance overhead. This specification exposes CSS values as typed JavaScript objects to facilitate their performant manipulation.
Editor: Shane Stephens, shanestephens@google.com, w3cid 47691
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Naina Raisinghani, Google, nainar@google.com, w3cid 100915
Repository: w3c/css-houdini-drafts
Inline Github Issues: title
Ignored Vars: type, unit
Ignored Terms: Drawable, paint image definition, list-valued property, list-valued property iteration, parse a CSSStyleValue, values to iterate over, CSS
Markup Shorthands: markdown yes
</pre>

<style>
/* Put nice boxes around each algorithm. */
[data-algorithm]:not(.heading) {
  padding: .5em;
  border: thin solid #ddd; border-radius: .5em;
  margin: .5em calc(-0.5em - 1px);
}
[data-algorithm]:not(.heading) > :first-child {
  margin-top: 0;
}
[data-algorithm]:not(.heading) > :last-child {
  margin-bottom: 0;
}
[data-algorithm] [data-algorithm] {
    margin: 1em 0;
}
</style>

<pre class=anchors>
urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn; spec: ecma-262
    text: RangeError; url: native-error-types-used-in-this-standard-rangeerror
</pre>

<pre class=link-defaults>
spec:dom; type:interface;
    text:Document
    text:Element;
spec:css-color-3; type:property; text:color;
spec:css-speech-1; type:property;
    text:cue-after;
    text:cue-before;
    text:pause-after;
    text:pause-before;
    text:speak;
    text:voice-family;
spec:css21; type:property;
    text:max-height;
    text:max-width;
    text:min-height;
    text:min-width;
spec:css-tables-3; type:property;
    text:border-collapse;
    text:caption-side;
    text:empty-cells;
    text:table-layout;
spec:css-position-3; type:value; for:left; text:auto;
spec:css-transforms-1;
    type:type;
        text:<transform-list>;
        text:<transform-function>;
    type:property;
        text:transform;
        text:backface-visibility;
        text:perspective;
        text:perspective-origin;
        text:transform-origin;
        text:transform-style;
spec:css-syntax-3;
    type:dfn; text:identifier
spec:css-values-4;
    type:type; text:<position>
    type:value; text:in
spec:infra;
    type: dfn;
        text: list
        text: code point
</pre>

Introduction {#intro}
=====================

Converting CSSOM value strings into meaningfully typed JavaScript representations and
back can incur a significant performance overhead. This specification exposes CSS values
as typed JavaScript objects to facilitate their performant manipulation.

The API exposed by this specification is designed for performance rather than ergonomics.
Some particular considerations:
*   retrieved JavaScript representations of CSS values are not mutable - instead updates
        must explicitly be set using the API.
*   objects are organized for consistency rather than ease of access. For example, even
        though lengths are often numeric pixel values, a declared {{CSSNumericValue}} can't be
        treated as a number without first explicitly casting it to a {{CSSUnitValue}}, as calc
        expressions and keywords are also valid lengths.

<!--
 ██████   ██████   ██████   ██████  ████████ ██    ██ ██       ████████ ██     ██    ███    ██       ██     ██ ████████
██    ██ ██    ██ ██    ██ ██    ██    ██     ██  ██  ██       ██       ██     ██   ██ ██   ██       ██     ██ ██
██       ██       ██       ██          ██      ████   ██       ██       ██     ██  ██   ██  ██       ██     ██ ██
██        ██████   ██████   ██████     ██       ██    ██       ██████   ██     ██ ██     ██ ██       ██     ██ ██████
██             ██       ██       ██    ██       ██    ██       ██        ██   ██  █████████ ██       ██     ██ ██
██    ██ ██    ██ ██    ██ ██    ██    ██       ██    ██       ██         ██ ██   ██     ██ ██       ██     ██ ██
 ██████   ██████   ██████   ██████     ██       ██    ████████ ████████    ███    ██     ██ ████████  ███████  ████████
-->

{{CSSStyleValue}} objects {#stylevalue-objects}
============================================

<pre class='idl'>
interface CSSStyleValue {
    stringifier;
    static CSSStyleValue? parse(DOMString property, DOMString cssText);
    static sequence&lt;CSSStyleValue>? parseAll(DOMString property, DOMString cssText);
};
</pre>

{{CSSStyleValue}} objects are the base class of all CSS Values accessible via the Typed OM API.
Values that can't yet be directly supported by a {{CSSStyleValue}} subclass
are also represented as {{CSSStyleValue}} objects.

The <a for="CSSStyleValue">stringification behavior</a> of {{CSSStyleValue}} objects is to
return a normalized representation
(see [[#stylevalue-normalization]])
of the value the {{CSSStyleValue}} object represents.

The <dfn method for=CSSStyleValue>parse(DOMString <var>property</var>, DOMString <var>cssText</var>)</dfn>,
when invoked, must [=parse a CSSStyleValue=] with property <var>property</var>, cssText <var>cssText</var>,
and parseMultiple set to false.

The <dfn method for=CSSStyleValue>parseAll(DOMString <var>property</var>, DOMString <var>cssText</var>)</dfn>,
when invoked, must [=parse a CSSStyleValue=] with property <var>property</var>, cssText <var>cssText</var>,
and parseMultiple set to true.

<div algorithm="parse a CSSStyleValue">
    To <dfn>parse a CSSStyleValue</dfn> given a <var>property</var>, <var>cssText</var>, and a
    <var>parseMultiple</var> flag, run these steps:

    1. Attempt to parse |property| as an <<ident>>.
        If this fails,
        [=throw=] a {{SyntaxError}} and exit this algorithm.
        Otherwise, let |property| be the parsed result.
        If |property| does not start with two dashes (U+002D HYPHEN),
        let |property| be |property| [=ASCII lowercased=].

    2. If |property| is not a [=supported property name=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    3. Attempt to <a lt="parse something according to a CSS grammar">parse</a> |cssText| according to |property|’s grammar.
        If this fails,
        [=throw=] a {{SyntaxError}} and exit this algorithm.
        Otherwise,
        let |value| be the parsed result.

    4. If |property| is a [=list-valued property=], and |parseMultiple| is true,
        subdivide |value| into a list of {{CSSStyleValue}} objects,
        each representing one [=list-valued property iteration=],
        and let |value| be the result. Return |value| as a sequence of
        {{CSSStyleValue}} objects.

    5. If |property| is a [=list-valued property=], and |parseMultiple| is false
        subdivide |value| into a list of {{CSSStyleValue}} objects,
        each representing one [=list-valued property iteration=],
        and let |value| be the first entry in this list.

    6. return a {{CSSStyleValue}} representing |value|.

</div>

Issue(305): appropriate failure indicators for this algorithm

<!--
 ██████  ████████ ██    ██ ██       ████████ ██     ██    ███    ████████
██    ██    ██     ██  ██  ██       ██       ███   ███   ██ ██   ██     ██
██          ██      ████   ██       ██       ████ ████  ██   ██  ██     ██
 ██████     ██       ██    ██       ██████   ██ ███ ██ ██     ██ ████████
      ██    ██       ██    ██       ██       ██     ██ █████████ ██
██    ██    ██       ██    ██       ██       ██     ██ ██     ██ ██
 ██████     ██       ██    ████████ ████████ ██     ██ ██     ██ ██
-->

The {{StylePropertyMap}} {#the-stylepropertymap}
================================================

<pre class='idl'>
interface StylePropertyMapReadOnly {
    CSSStyleValue? get(DOMString property);
    sequence&lt;CSSStyleValue> getAll(DOMString property);
    boolean has(DOMString property);
    iterable&lt;DOMString, (CSSStyleValue or sequence&lt;CSSStyleValue>)>;
    sequence&lt;DOMString> getProperties();
    stringifier;
};

callback UpdateFunction = CSSStyleValue (CSSStyleValue oldValue);

interface StylePropertyMap : StylePropertyMapReadOnly {
    void append(DOMString property, (CSSStyleValue or DOMString)... values);
    void delete(DOMString property);
    void set(DOMString property, (CSSStyleValue or DOMString)... values);
    void update(DOMString property, UpdateFunction updateFunction);
};
</pre>

A {{StylePropertyMapReadOnly}} object has an associated <dfn>property model</dfn>,
which is a list of property - sequence&lt;{{CSSStyleValue}}> pairs. This list
is initialized differently depending on where the {{CSSStyleValue}} is used
(see
[[#computed-stylepropertymapreadonly-objects]],
[[#declared-stylepropertymap-objects]], and
[[#inline-stylepropertymap-objects]]).

All properties stored on the [=property model=] in {{StylePropertyMapReadOnly}} are [=ASCII case-insensitive=] within the ASCII range (i.e., [a-z] and [A-Z] are equivalent).

<div class='note'>
The sequence of {{CSSStyleValue}}s associated with a property do
not represent multiple successive definitions of that property's value.
Instead, sequences represent values associated with list-valued properties.

This approach allows single-valued properties to become list-valued in the
future without breaking code that relies on calling
{{StylePropertyMapReadOnly/get()}} and/or
{{StylePropertyMap/set()}} for those properties.
</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:

    1. If |property| does not start with two dashes (U+002D HYPHEN),
        let |property| be |property| [=ASCII lowercased=].

    2. If |property| is not a [=supported property name=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    3. If |property| is not a [=list-valued property=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    4. If {{StylePropertyMap}}’s [=property model=] 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 [=property model=],
        and let |entry| be the newly-created entry.

    5. Let |values to append| be the 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|.

    7. Append |values to append| to the end of |entry|’s list.
</div>

<div algorithm>
    To <dfn>delete a StylePropertyMap</dfn> given a <var>property</var> and a list of
    <var>values</var>, run these steps:

    1. If |property| does not start with two dashes (U+002D HYPHEN),
        let |property| be |property| [=ASCII lowercased=].

    2. If |property| is not a [=supported property name=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    3. If {{StylePropertyMap}}’s [=property model=] contains an entry for |property|,
        remove that entry from the [=property model=].
</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|.
</div>

<div algorithm>
    To <dfn>get a value from a StylePropertyMap</dfn>, run these steps:

    1. If |property| does not start with two dashes (U+002D HYPHEN),
        let |property| be |property| [=ASCII lowercased=].

    2. If |property| is not a [=supported property name=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    3. If {{StylePropertyMap}}’s [=property model=] contains an entry for |property|,
        return the first value found in that entry.

    4. Else, return `null`.
</div>

<div algorithm>
    To <dfn>check if StylePropertyMap has a property</dfn>, run these steps:

    1. Run the algorithm to [=get a value from a StylePropertyMap=] with property <var>property</var>,
        1. If the algoritm returns a {{CSSStyleValue}} return true.

        2. If the algorithm returns `null` return false.

</div>


<div algorithm>
    To <dfn>set a value on a StylePropertyMap</dfn>, run these steps:

    1. If |property| does not start with two dashes (U+002D HYPHEN),
        let |property| be |property| [=ASCII lowercased=].

    2. If |property| is not a [=supported property name=],
        [=throw=] a {{TypeError}} and exit this algorithm.

    3. If {{StylePropertyMap}}’s [=property model=] contains an entry for |property|,
        let |entry| be that entry.
        Otherwise, exit the algorithm.

    4. Empty the list of |values| currently stored on the |entry|.

    5. Let |values to set| be an empty list.

    6. For each |value| in |values| if the [=algorithm that coerces value into an appropriate type for a given property=] does not throw an error, append the returned object to |values to set|.

    7. Set |values to set| to be |entry|’s list.
</div>

The <dfn method for=StylePropertyMap>update(DOMString <var>property</var>,
UpdateFunction <var>updateFunction</var>)</dfn> method, when invoked, must
[=update a value in a StylePropertyMap=] with property name
<var>property</var>, update function <var>updateFunction</var>, and property
map set to the object this method was invoked on .

<div algorithm>
    To <dfn>update a value in a StylePropertyMap</dfn> given a <var>property
    name</var>, <var>update function</var>, and <var>property map</var>, run these
    steps:

    1.  Let <var>old value</var> be the result of running the algorithm to
        [=get a value from a StylePropertyMap=] with property name <var>property
        name</var> and property map <var>property map</var>.

    2.  Let <var>new value</var> be the return value given by [=invoking=] the callback
        <var>update function</var> with a single input of <var>old value</var>.

    3.  Run the algorithm to [=set a value on a StylePropertyMap=] with property name <var>property name</var>,
        value <var>new value</var>, and property map <var>property map</var>.

</div>

The <dfn method for=StylePropertyMap>getProperties()</dfn> method returns all of the properties listed in
the [=property model=]. This list of properties is sorted in the following manner:

*   normal properties are sorted alphabetically.
*   custom properties are sorted by increasing code point order.
*   custom properties are sorted after normal properties.

[=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.

Issue(148): add detailed descriptions of the rest of the methods on {{StylePropertyMap}}

Issue(268): stringification

Issue(276): interaction with custom properties

Issue(310): consider using properties in addition to get/set

Computed {{StylePropertyMapReadOnly}} objects {#computed-stylepropertymapreadonly-objects}
--------------------------------------------------------------------------

<pre class='idl'>
partial interface Element {
    StylePropertyMapReadOnly computedStyleMap();
};
</pre>

<dfn>Computed StylePropertyMap</dfn> objects represent the computed style of an
{{Element}} or pseudo element, and are accessed by calling the
{{Element/computedStyleMap()}} method.

When constructed, the [=property model=] for [=computed StylePropertyMap=]
objects is initialized to contain an entry for every valid CSS property supported by the User Agent.

Note: The StylePropertyMap returned by computedStyleMap represents computed style,
            not resolved style. In this regard it provides different values than those
            in objects returned by getComputedStyle.

Declared {{StylePropertyMap}} objects {#declared-stylepropertymap-objects}
----------------------------------------------------------------------------

<pre class='idl'>
partial interface CSSStyleRule {
    [SameObject] readonly attribute StylePropertyMap attributeStyleMap;
};
</pre>

<dfn>Declared StylePropertyMap</dfn> objects represent style property-value pairs embedded
in a style rule, and are accessed via the <dfn attribute for=CSSStyleRule>attributeStyleMap</dfn>
attribute of {{CSSStyleRule}} objects.

When constructed, the [=property model=] for [=declared StylePropertyMap=]
objects is initialized to contain
an entry for each property that is paired with at least one valid value inside the
{{CSSStyleRule}} that the object represents. The value for a given property is
the last valid value provided by the {{CSSStyleRule}} object.


Inline {{StylePropertyMap}} objects {#inline-stylepropertymap-objects}
----------------------------------------------------------------------

<pre class='idl'>
partial interface Element {
    [SameObject] readonly attribute StylePropertyMap attributeStyleMap;
};
</pre>

<dfn>Inline StylePropertyMap</dfn> objects represent inline style declarations attached
directly to {{Element}}s. They are accessed via the <dfn attribute for=Element>attributeStyleMap</dfn>
attribute of {{Element}} objects.

When constructed, the [=property model=] for [=inline StylePropertyMap=] objects
is initialized to contain an
entry for each property that is paired with at least one valid value in the string
representing the style attribute for the Element that the object is associated with.
The value for a given property is the last valid value provided in the string.

{{CSSStyleValue}} subclasses {#stylevalue-subclasses}
==================================================

<!--
██     ██ ██    ██ ████████     ███    ████████   ██████  ████████ ████████
██     ██ ███   ██ ██     ██   ██ ██   ██     ██ ██    ██ ██       ██     ██
██     ██ ████  ██ ██     ██  ██   ██  ██     ██ ██       ██       ██     ██
██     ██ ██ ██ ██ ████████  ██     ██ ████████   ██████  ██████   ██     ██
██     ██ ██  ████ ██        █████████ ██   ██         ██ ██       ██     ██
██     ██ ██   ███ ██        ██     ██ ██    ██  ██    ██ ██       ██     ██
 ███████  ██    ██ ██        ██     ██ ██     ██  ██████  ████████ ████████
-->

{{CSSUnparsedValue}} objects {#unparsedvalue-objects}
----------------------------------------------

<pre class='idl'>
[Constructor((DOMString or CSSVariableReferenceValue)... members)]
interface CSSUnparsedValue : CSSStyleValue {
    iterable<(DOMString or CSSVariableReferenceValue)>;
    readonly attribute unsigned long length;
    getter (DOMString or CSSVariableReferenceValue) (unsigned long index);
};

interface CSSVariableReferenceValue {
    attribute DOMString variable;
    attribute CSSUnparsedValue? fallback;
};
</pre>

Issue(239): Is this the best representation for this object?

{{CSSUnparsedValue}} objects represent values that reference custom properties.
They represent a list of string fragments and variable references.

They have a <dfn attribute for=CSSUnparsedValue>\[[tokens]]</dfn> internal slot,
which is a [=list=] of alternating {{DOMString}} and {{CSSVariableReferenceValue}} objects.
This list is the object's [=values to iterate over=].

The <dfn attribute for=CSSUnparsedValue>length</dfn> attribute indicates how many string fragments and variable references are contained within the {{CSSUnparsedValue}}.

The <dfn for=CSSUnparsedValue>indexed getter</dfn> retrieves the string fragment or variable reference at the provided index.

<!--
██    ██ ████████ ██    ██ ██      ██  ███████  ████████  ████████
██   ██  ██        ██  ██  ██  ██  ██ ██     ██ ██     ██ ██     ██
██  ██   ██         ████   ██  ██  ██ ██     ██ ██     ██ ██     ██
█████    ██████      ██    ██  ██  ██ ██     ██ ████████  ██     ██
██  ██   ██          ██    ██  ██  ██ ██     ██ ██   ██   ██     ██
██   ██  ██          ██    ██  ██  ██ ██     ██ ██    ██  ██     ██
██    ██ ████████    ██     ███  ███   ███████  ██     ██ ████████
-->

{{CSSKeywordValue}} objects {#keywordvalue-objects}
---------------------------------------------------

{{CSSKeywordValue}} objects represent CSS keywords and other [=identifiers=].

<pre class='idl'>
[Constructor(DOMString value)]
interface CSSKeywordValue : CSSStyleValue {
    attribute DOMString value;
    stringifier;
};
</pre>

<div algorithm>
    The <dfn constructor for=CSSKeywordValue>CSSKeywordValue(|value|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. Return a new {{CSSKeywordValue}}
        with its {{CSSKeywordValue/value}} internal slot
        set to |value|.
</div>

<div algorithm="CSSKeywordValue stringification behavior">
    The <dfn for=CSSKeywordValue>stringification behavior</dfn> of a {{CSSKeywordValue}} |this| is:

    1. Let |token| be an <<ident-token>>
        with its value set to |this|’s {{CSSKeywordValue/value}} internal slot.

    2. Return the serialization of |token|.
</div>

Any place that accepts a {{CSSKeywordValue}}
also accepts a raw {{DOMString}},
by using the following typedef and algorithm:

<pre class=idl>
typedef (DOMString or CSSKeywordValue) CSSKeywordish;
</pre>

<div algorithm>
    To <dfn export>rectify a keywordish value</dfn> |val|,
    perform the following steps:

    1. If |val| is a {{CSSKeywordValue}},
        return |val|.

    2. If |val| is a {{DOMString}},
        return a new {{CSSKeywordValue}}
        with its {{CSSKeywordValue/value}} internal slot
        set to |val|.
</div>


<!--
██    ██ ██     ██ ██     ██ ████████ ████████  ████  ██████
███   ██ ██     ██ ███   ███ ██       ██     ██  ██  ██    ██
████  ██ ██     ██ ████ ████ ██       ██     ██  ██  ██
██ ██ ██ ██     ██ ██ ███ ██ ██████   ████████   ██  ██
██  ████ ██     ██ ██     ██ ██       ██   ██    ██  ██
██   ███ ██     ██ ██     ██ ██       ██    ██   ██  ██    ██
██    ██  ███████  ██     ██ ████████ ██     ██ ████  ██████
-->


Numeric Values: {#numeric-objects}
----------------------------------

{{CSSNumericValue}} objects represent CSS values that are numeric in nature
(<<number>>s, <<percentage>>s, <<dimension>>s).

* {{CSSUnitValue}} objects represent values that contain a single unit type
    (for example "42px").
* {{CSSMathValue}} objects represent math expressions,
    which can contain more than one value/unit
    (for example "calc(56em + 10%)").

{{CSSNumericValue}} objects are not range-restricted.
Any valid numeric value can be represented by a {{CSSNumericValue}},
and that value will not be clamped, rounded, or rejected
when set on a [=declared StylePropertyMap=] or [=inline StylePropertyMap=].
Instead, clamping and/or rounding will occur during computation of style.

<div class='example'>
    The following code is valid

    <pre class=lang-js>
        myElement.attributeStyleMap.set("opacity", CSS.number(3));
        myElement.attributeStyleMap.set("z-index", CSS.number(15.4));

        console.log(myElement.attributeStyleMap.get("opacity").value); // 3
        console.log(myElement.attributeStyleMap.get("z-index").value); // 15.4

        var computedStyle = myElement.computedStyleMap();
        var opacity = computedStyle.get("opacity");
        var zIndex = computedStyle.get("z-index");
    </pre>

    After execution, the value of `opacity` is `1` ('opacity' is range-restricted),
    and the value of `zIndex` is `15` ('z-index' is rounded to an integer value).
</div>

Note: "Numeric values" which incorporate variable references
will instead be represented as {{CSSUnparsedValue}} objects,
and keywords as {{CSSKeywordValue}} objects.

Any place that accepts a {{CSSNumericValue}}
also accepts a raw {{double}},
by using the following typedef and algorithm:

<pre class=idl>
typedef (double or CSSNumericValue) CSSNumberish;
</pre>

<div algorithm>
    To <dfn export lt="rectify a numberish value | rectifying a numberish value">rectify a numberish value</dfn> |num|,
    perform the following steps:

    1. If |num| is a {{CSSNumericValue}},
        return |num|.

    2. If |num| is a {{double}},
        return a new {{CSSUnitValue}}
        with its {{CSSUnitValue/value}} internal slot set to |num|
        and its {{CSSUnitValue/unit}} internal slot set to "number".
</div>


### Common Numeric Operations, and the {{CSSNumericValue}} Superclass ### {#numeric-value}

All numeric CSS values
(<<number>>s, <<percentage>>s, and <<dimension>>s)
are represented by subclasses of the {{CSSNumericValue}} interface.

<xmp class=idl>
    interface CSSNumericValue : CSSStyleValue {
        CSSNumericValue add(CSSNumberish... values);
        CSSNumericValue sub(CSSNumberish... values);
        CSSNumericValue mul(CSSNumberish... values);
        CSSNumericValue div(CSSNumberish... values);
        CSSNumericValue min(CSSNumberish... values);
        CSSNumericValue max(CSSNumberish... values);

        boolean equals(CSSNumberish... value);

        CSSNumericValue to(DOMString unit);
        CSSMathSum toSum(DOMString... units);
        // ??? type();

        static CSSNumericValue parse(DOMString cssText);
    };
</xmp>

Issue: Figure out how we want to represent the type of an expression in JS,
and define the type() method accordingly.

The methods on the {{CSSNumericValue}} superclass
represent operations that all numeric values can perform.

The following are the arithmetic operations you can perform on dimensions:

<div algorithm="CSSNumericValue.add()">
    The <dfn for=CSSNumericValue method>add(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. If |this| is a {{CSSMathSum}} object,
        [=list/prepend=] the [=list/items=] in |this|’s {{CSSMathSum/values}} internal slot
        to |values|.
        Otherwise,
        prepend |this| to |values|.

    3. If all of the [=list/items=] in |values| are {{CSSUnitValue}}s
        and have the same {{CSSUnitValue/unit}},
        return a new {{CSSUnitValue}}
        whose {{CSSUnitValue/unit}} internal slot is set to |this|’s {{CSSUnitValue/unit}} internal slot,
        and {{CSSUnitValue/value}} internal slot is set to the sum of
        the {{CSSUnitValue/value}} internal slots
        of the [=list/items=] in |values|.

    4. Let |type| be the result of [=adding=] the [=types=] of every [=list/item=] in |values|.
        If |type| is failure,
        [=throw=] a {{TypeError}}.

    5. Return a new {{CSSMathSum}} object
        whose {{CSSMathSum/values}} internal slot
        is set to |values|.
</div>

<div algorithm="CSSNumericValue.sub()">
    The <dfn for=CSSNumericValue method>sub(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=],
        then [=CSSMath/negating=] the value.

    2. Return the result of calling the {{CSSNumericValue/add()}} internal algorithm
        with |this| and |values|.
</div>

<div algorithm>
    To <dfn noexport for=CSSMath>negate</dfn> a {{CSSNumericValue}} |this|:

    1. If |this| is a {{CSSMathNegate}} object,
        return |this|’s {{CSSMathNegate/value}} internal slot.

    2. If |this| is a {{CSSUnitValue}} object,
        return a new {{CSSUnitValue}}
        with the same {{CSSUnitValue/unit}} internal slot as |this|,
        and a {{CSSUnitValue/value}} internal slot set to the negation of |this|’s.

    2. Otherwise,
        return a new {{CSSMathNegate}} object
        whose {{CSSMathNegate/value}} internal slot
        is set to |this|.
</div>

<div algorithm="CSSNumericValue.mul()">
    The <dfn for=CSSNumericValue method>mul(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. If |this| is a {{CSSMathProduct}} object,
        [=list/prepend=] the [=list/items=] in |this|’s {{CSSMathProduct/values}} internal slot
        to |values|.
        Otherwise,
        prepend |this| to |values|.

    3. Let |type| be the result of [=multiplying=] the [=types=] of every [=list/item=] in |values|.
        If |type| is failure,
        [=throw=] a {{TypeError}}.

    5. Return a new {{CSSMathProduct}} object
        whose {{CSSMathProduct/values}} internal slot
        is set to |values|.
</div>

<div algorithm="CSSNumericValue.div()">
    The <dfn for=CSSNumericValue method>div(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=],
        then [=CSSMath/inverting=] the value.

    2. Return the result of calling the {{CSSNumericValue/mul()}} internal algorithm
        with |this| and |values|.
</div>

<div algorithm>
    To <dfn noexport for=CSSMath>invert</dfn> a {{CSSNumericValue}} |this|:

    1. If |this| is a {{CSSMathInvert}} object,
        return |this|’s {{CSSMathInvert/value}} internal slot.

    2. Otherwise,
        return a new {{CSSMathInvert}} object
        whose {{CSSMathInvert/value}} internal slot
        is set to |this|.
</div>

<div algorithm="CSSNumericValue.min()">
    The <dfn for=CSSNumericValue method>min(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. If |this| is a {{CSSMathMin}} object,
        [=list/prepend=] the [=list/items=] in |this|’s {{CSSMathMin/values}} internal slot
        to |values|.
        Otherwise,
        prepend |this| to |values|.

    3. Let |type| be the result of [=adding=] the [=types=] of every [=list/item=] in |values|.
        If |type| is failure,
        [=throw=] a {{TypeError}}.

    4. Return a new {{CSSMathMin}} object
        whose {{CSSMathMin/values}} internal slot
        is set to |values|.
</div>

<div algorithm="CSSNumericValue.max()">
    The <dfn for=CSSNumericValue method>max(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. If |this| is a {{CSSMathMax}} object,
        [=list/prepend=] the [=list/items=] in |this|’s {{CSSMathMax/values}} internal slot
        to |values|.
        Otherwise,
        prepend |this| to |values|.

    3. Let |type| be the result of [=adding=] the [=types=] of every [=list/item=] in |values|.
        If |type| is failure,
        [=throw=] a {{TypeError}}.

    4. Return a new {{CSSMathMax}} object
        whose {{CSSMathMax/values}} internal slot
        is set to |values|.
</div>

<div algorithm="CSSNumericValue.equals(value)">
    The <dfn for=CSSNumericValue method>equals(...|values|)</dfn> method,
    when called on a {{CSSNumericValue}} |this|,
    must perform the following steps:

    1. Replace each [=list/item=] of |values|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. Let |thisAndValues| be |this| prepended to |values|.

    3. If all |item|s of |thisAndValues| do not belong to the same class return false. Example: all items in |thisAndValues| must be {{CSSUnitValue}}.

    4. If all |item|s in |thisAndValues| are {{CSSUnitValue}s and have the same {{CSSUnitValue/unit}} and {{CSSUnitValue/value}} return true.

    5. If all |item|s in |thisAndValues| are {{CSSMathValue}}s :
        1. If |thisAndValues| are all either {{CSSMathSum}}, {{CSSMathProduct}}, {{CSSMathMin}} or {{CSSMathMax}}, iterate over the {{CSSNumericArray}}s on |thisAndValues|,
            1. For each {{CSSNumericValue}} in each of the {{CSSNumericArray}}s go back to step 1 to check that the {{CSSUnitValue}}s on all items in |thisAndValues| are equal.
        2. If |thisAndValues| are all either {{CSSMathNegate}} or {{CSSMathInvert}}:
            1. Go back to step 1 to check that the {{CSSUnitValue}} on all items in |thisAndValues| are equal.
</div>


<div algorithm="CSSNumericValue.to()">
    The <dfn method for=CSSNumericValue>to(|unit|)</dfn> method converts an existing {{CSSNumericValue}} |this|
    into another one with the specified |unit|,
    if possible.
    When called, it must perform the following steps:

    1. Let |type| be the result of [=creating a type=] from |unit|.
        If |type| is failure,
        [=throw=] a {{SyntaxError}}.

    2. Let |sum| be the result of [=creating a sum value=] from |this|.
        If |sum| is failure,
        [=throw=] a {{TypeError}}.

    3. If |sum| has more than one [=list/item=],
        [=throw=] a {{TypeError}}.
        Otherwise, let |item| be the result of [=create a CSSUnitValue from a sum value item|creating a CSSUnitValue=]
        from the sole [=list/item=] in |sum|,
        then [=convert a CSSUnitValue|converting=] it to |unit|.
        If |item| is failure,
        [=throw=] a {{TypeError}}.

    4. Return |item|.
</div>

<div algorithm>
    When asked to <dfn export>create a CSSUnitValue from a sum value item</dfn> |item|,
    perform the following steps:

    1. If |item| has more than one [=map/entry=] in its [=sum value/unit map=],
        return failure.

    2. If |item| has no [=map/entries=] in its [=sum value/unit map=],
        return a new {{CSSUnitValue}}
        whose {{CSSUnitValue/unit}} internal slot
        is set to "number",
        and whose {{CSSUnitValue/value}} internal slot
        is set to |item|’s [=sum value/value=].

    3. Otherwise, |item| has a single [=map/entry=] in its [=sum value/unit map=].
        If that [=map/entry’s=] [=map/value=] is anything other than `1`,
        return failure.

    4. Otherwise, return a new {{CSSUnitValue}}
        whose {{CSSUnitValue/unit}} internal slot
        is set to that [=map/entry’s=] [=map/key=],
        and whose {{CSSUnitValue/value}} internal slot
        is set to |item|’s [=sum value/value=].
</div>

<div algorithm="CSSNumericValue.toSum()">
    The <dfn method for=CSSNumericValue>toSum(...|units|)</dfn> method converts an existing {{CSSNumericValue}} |this|
    into a {{CSSMathSum}} of only {{CSSUnitValue}}s with the specified units,
    if possible.
    (It's like {{CSSNumericValue/to()}},
    but allows the result to have multiple units in it.)
    If called without any units,
    it just simplifies |this| into a minimal sum of {{CSSUnitValue}}s.

    When called, it must perform the following steps:

    1. [=list/For each=] |unit| in |units|,
        if the result of [=creating a type=] from |unit| is failure,
        [=throw=] a {{SyntaxError}}.

    2. Let |sum| be the result of [=creating a sum value=] from |this|.
        If |sum| is failure,
        [=throw=] a {{TypeError}}.

    3. Let |values| be the result of [=create a CSSUnitValue from a sum value item|creating a CSSUnitValue=]
        [=list/for each=] [=list/item=] in |sum|.
        If any [=list/item=] of |values| is failure,
        [=throw=] a {{TypeError}}.

    4. If |units| is [=list/empty=],
        sort |values| in [=code point=] order according to the {{CSSUnitValue/unit}} internal slot of its [=list/items=],
        then return a new {{CSSMathSum}} object
        whose {{CSSMathSum/values}} internal slot is set to |values|.


    5. Otherwise,
        let |result| initially be an empty [=list=].
        [=list/For each=] |unit| in |units|:

        1. Let |temp| initially be a new {{CSSUnitValue}}
            whose {{CSSUnitValue/unit}} internal slot
            is set to |unit|
            and whose {{CSSUnitValue/value}} internal slot
            is set to `0`.

        2. [=list/For each=] |value| in |values|:

            1. Let |value unit| be |value|’s {{CSSUnitValue/unit}} internal slot.

            2. If |value unit| is a [=compatible unit=] with |unit|,
                then:

                1.[=convert a CSSUnitValue|convert=] |value| to |unit|.
                2. Increment |temp|’s {{CSSUnitValue/value}} internal slot
                    by the value of |value|’s {{CSSUnitValue/value}} internal slot.
                3. [=list/Remove=] |value| from |values|.

        3. [=list/Append=] |temp| to |result|.

    6. If |values| is not [=list/empty=],
        [=throw=] a {{TypeError}}.
        <span class=note>|this| had units that you didn't ask for.</span>

    7. Return a new {{CSSMathSum}} object
        whose {{CSSMathSum/values}} internal slot
        is set to |result|.
</div>

<div algorithm="sum value">
    A <dfn>sum value</dfn>
    is an abstract representation of a {{CSSNumericValue}}
    as a sum of numbers with (possibly complex) units.
    Not all {{CSSNumericValue}}s can be expressed as a [=sum value=].

    A [=sum value=] is a [=list=].
    Each entry in the list is a [=tuple=] of a <dfn for="sum value">value</dfn>,
    which is a number,
    and a <dfn for="sum value">unit map</dfn>,
    which is a [=ordered map|map=] of units (strings) to powers (integers).

    <div class=example>
        Here are a few examples of CSS values,
        and their equivalent [=sum values=]:

        * ''1px'' becomes `«(1, «["px" → 1]»)»`
        * ''calc(1px + 1in)'' becomes `«(97, «["px" → 1]»)»`
            (because ''in'' and ''px'' are [=compatible units=],
            and ''px'' is the [=canonical unit=] for them)
        * ''calc(1px + 2em)'' becomes `«(1, «["px" → 1]»), (2, «["em" → 1]»)»`
        * ''calc(1px + 2%)'' becomes `«(1, «["px" → 1]»), (2, «["percent" → 1]»)»`
            (percentages are allowed to add to other units,
            but aren't resolved into another unit,
            like they are in a [=type=])
        * ''calc(1px * 2em)'' becomes `«(2, «["em" → 1, "px" → 1]»)»`
        * ''calc(1px + 1deg)'' can't be represented as a [=sum value=]
            because it's an invalid computation
        * ''calc(1px * 1deg)'' becomes `«(2, «["deg" → 1, "px" → 1]»)»`
    </div>

    To <dfn lt="create a sum value|creating a sum value">create a sum value</dfn> from a {{CSSNumericValue}} |this|,
    the steps differ based on |this|’s class:

    <dl class=switch>
        : {{CSSUnitValue}}
        ::
            <div algorithm="sum value from CSSUnitValue">
                1. Let |unit| be the value of |this|’s {{CSSUnitValue/unit}} internal slot,
                    and |value| be the value of |this|’s {{CSSUnitValue/value}} internal slot.
                2. If |unit| is a member of a set of [=compatible units=],
                    and is not the set's [=canonical unit=],
                    multiply |value| by the conversion ratio between |unit| and the [=canonical unit=],
                    and change |unit| to the [=canonical unit=].
                3. If |unit| is `"number"`,
                    return «(|value|, «[ ]»)».
                3. Otherwise, return <code>«(|value|, «[|unit| → 1]»)»</code>.
            </div>

        : {{CSSMathSum}}
        ::
            <div algorithm="sum value from CSSMathSum">
                1. Let |values| initially be an empty list.

                2. [=list/For each=] |item| in <var ignore>this</var>’s {{CSSMathSum/values}} internal slot:

                    1. Let |value| be the result of [=creating a sum value=] from |item|.
                        If |value| is failure,
                        return failure.

                    2. [=list/For each=] |subvalue| of |value|:

                        1. If |values| already contains an [=list/item=]
                            with the same [=sum value/unit map=] as |subvalue|,
                            increment that [=list/item=]’s [=sum value/value=]
                            by the [=sum value/value=] of |subvalue|.

                        2. Otherwise, [=list/append=] |subvalue| to |values|.

                3. [=create a type from a unit map|Create a type=]
                    from the [=sum value/unit map=]
                    of each [=list/item=] of |values|,
                    and [=add=] all the types together.
                    If the result is failure,
                    return failure.

                4. Return |values|.
            </div>

        : {{CSSMathNegate}}
        ::
            <div algorithm="sum value from CSSMathNegate">
                1. Let |values| be the result of [=creating a sum value=]
                    from <var ignore>this</var>’s {{CSSMathNegate/value}} internal slot.

                2. If |values| is failure,
                    return failure.

                3. Negate the [=sum value/value=] of each [=list/item=] of |values|.

                4. Return |values|.
            </div>

        : {{CSSMathProduct}}
        ::
            <div algorithm="sum value from CSSMathProduct">
                1. Let |values| initially be the [=sum value=] «(1, «[ ]»)».
                    (I.e. what you'd get from ''1''.)

                2. [=list/For each=] |item| in <var ignore>this</var>’s {{CSSMathProduct/values}} internal slot:

                    1. Let |new values| be the result of [=creating a sum value=] from |item|.
                        Let |temp| initially be an empty [=list=].

                    2. If |new values| is failure,
                        return failure.

                    3. [=list/For each=] |item1| in |values|:

                        1. [=list/For each=] |item2| in |new values|:

                            1. Let |item| be a [=tuple=] with its [=sum value/value=]
                                set to the product of the [=sum value/values=] of |item1| and |item2|,
                                and its [=sum value/unit map=]
                                set to the union of the [=sum value/unit maps=] of |item1| and |item2|,
                                with all [=map/entries=] with a zero value removed.

                            2. Append |item| to |temp|.

                    4. Set |values| to |temp|.

                3. Return |values|.
            </div>

        : {{CSSMathInvert}}
        ::
            <div algorithm="sum value from CSSMathInvert">
                1. Let |values| be the result of [=creating a sum value=]
                    from <var ignore>this</var>’s {{CSSMathInvert/value}} internal slot.

                2. If |values| is failure,
                    return failure.

                3. If the length of [=values=] is more than one,
                    return failure.

                3. Invert (find the reciprocal of) the [=sum value/value=] of the [=list/item=] in |values|,
                    and negate the [=map/value=] of each [=map/entry=] in its [=sum value/unit map=].

                4. Return |values|.
            </div>

        : {{CSSMathMin}}
        ::
            <div algorithm="sum value from CSSMathMin">
                1. Let |args| be the result of [=creating a sum value=]
                    [=list/for each=] [=list/item=] in <var ignore>this</var>’s {{CSSMathMin/values}} internal slot.

                2. If any [=list/item=] of |args| is failure,
                    or has a length greater than one,
                    return failure.

                3. If not all of the [=sum value/unit maps=] among the [=list/items=] of |args| are identical,
                    return failure.

                4. Return the [=list/item=] of |args| whose sole [=list/item=] has the smallest [=sum value/value=].
            </div>

        : {{CSSMathMax}}
        ::
            <div algorithm="sum value from CSSMathMax">
                1. Let |args| be the result of [=creating a sum value=]
                    [=list/for each=] [=list/item=] in <var ignore>this</var>’s {{CSSMathMax/values}} internal slot.

                2. If any [=list/item=] of |args| is failure,
                    or has a length greater than one,
                    return failure.

                3. If not all of the [=sum value/unit maps=] among the [=list/items=] of |args| are identical,
                    return failure.

                4. Return the [=list/item=] of |args| whose sole [=list/item=] has the largest [=sum value/value=].
            </div>
    </dl>

    <div algorithm>
        To <dfn>create a type from a unit map</dfn> |unit map|:

        1. Let |types| be an initially empty [=list=].

        2. [=map/For each=] |unit| → |power| in |unit map|:

            1. Let |type| be the result of [=creating a type=] from |unit|.
            2. Set |type|’s sole [=map/value=] to |power|.
            3. [=list/Append=] |type| to |types|.

        3. Return the result of [=multiplying=] all the [=list/items=] of |types|.
    </div>
</div>

The {{CSSNumericValue/parse()}} method allows a {{CSSNumericValue}}
to be constructed directly from a string containing CSS.
Note that this is a static method,
existing directly on the {{CSSNumericValue}} interface object,
rather than on {{CSSNumericValue}} instances.

<div algorithm="CSSNumericValue.parse(cssText)">
    The <dfn method for=CSSNumericValue>parse(|cssText|)</dfn> method,
    when called,
    must perform the following steps:

    1. [=Parse a component value=] from |cssText|
        and let |result| be the result.
        If |result| is a syntax error,
        [=throw=] a {{SyntaxError}}
        and abort this algorithm.

    2. If |result| is not a <<number-token>>, <<percentage-token>>, <<dimension-token>>,
        or a <<calc()>>,
        [=throw=] a {{SyntaxError}}
        and abort this algorithm.

    3. [=Normalize a numeric value=] |result|,
        and return the result.
</div>

<!--
████████ ██    ██ ████████  ████████  ██████
   ██     ██  ██  ██     ██ ██       ██    ██
   ██      ████   ██     ██ ██       ██
   ██       ██    ████████  ██████    ██████
   ██       ██    ██        ██             ██
   ██       ██    ██        ██       ██    ██
   ██       ██    ██        ████████  ██████
-->

### Numeric Value Typing ### {#numeric-typing}

Each {{CSSNumericValue}} has an associated <dfn for=CSSNumericValue>type</dfn>,
which is a [=ordered map|map=] of [=base types=] to integers,
and an associated [=percent hint=].
The <dfn for=CSSNumericValue lt="base type">base types</dfn> are
"length",
"angle",
"time",
"frequency",
"resolution",
"flex",
and "percent".
The ordering of a [=type=]’s entries always matches this [=base type=] ordering.
The <dfn for=CSSNumericValue>percent hint</dfn>
is either null or a [=base type=] other than "percent".

<div algorithm>
    To <dfn lt="create a type|creating a type">create a type</dfn> from a string |unit|,
    follow the appropriate branch of the following:

    <dl class=switch>
        : |unit| is "number"
        :: Return «[ ]» (empty map)
        : |unit| is "percent"
        :: Return «[ "percent" → 1 ]»
        : |unit| is a <<length>> unit
        :: Return «[ "length" → 1 ]»
        : |unit| is an <<angle>> unit
        :: Return «[ "angle" → 1 ]»
        : |unit| is a <<time>> unit
        :: Return «[ "time" → 1 ]»
        : |unit| is a <<frequency>> unit
        :: Return «[ "frequency" → 1 ]»
        : |unit| is a <<resolution>> unit
        :: Return «[ "resolution" → 1 ]»
        : |unit| is a <<flex>> unit
        :: Return «[ "flex" → 1 ]»
        : anything else
        :: Return failure.
    </dl>

    In all cases, the associated [=percent hint=] is null.
</div>

<div algorithm>
    To <dfn local-lt="add | addition">add two types</dfn> |type1| and |type2|,
    perform the following steps:

    1. Replace |type1| with a fresh copy of |type1|,
        and |type2| with a fresh copy of |type2|.
        Let |finalType| be a new [=type=]
        with an initially empty [=ordered map=]
        and an initially null [=percent hint=].

    2.
        <dl class=switch>
            : If both |type1| and |type2| have non-null [=percent hints=]
                with different values
            :: The types can't be added.
                Return failure.

            : If |type1| has a non-null [=percent hint=] |hint| and |type2| doesn't
            :: [=Apply the percent hint=] |hint| to |type2|.

                Vice versa if |type2| has a non-null [=percent hint=] and |type1| doesn't.

            : Otherwise
            :: Continue to the next step.
        </dl>


    3.
        <dl class=switch>
            : If all the [=map/entries=] of |type1| with non-zero values
                are [=map/contained=] in |type2| with the same value,
                and vice-versa
            :: Copy all of |type1|’s [=map/entries=] to |finalType|,
                and then copy all of |type2|’s [=map/entries=] to |finalType|
                that |finalType| doesn't already [=map/contain=].
                Set |finalType|’s [=percent hint=] to |type1|’s [=percent hint=].
                Return |finalType|.

            : If |type1| and/or |type2| [=map/contain=] "percent" with a non-zero value,
                and |type1| and/or |type2| [=map/contain=] a key *other than* "percent" with a non-zero value
            :: For each [=base type=] other than "percent" |hint|:

                1. Provisionally [=apply the percent hint=] |hint| to both |type1| and |type2|.

                2. If, afterwards, all the [=map/entries=] of |type1| with non-zero values
                    are [=map/contained=] in |type2| with the same value,
                    and vice versa,
                    then copy all of |type1|’s [=map/entries=] to |finalType|,
                    and then copy all of |type2|’s [=map/entries=] to |finalType|
                    that |finalType| doesn't already [=map/contain=].
                    Set |finalType|’s [=percent hint=] to |hint|.
                    Return |finalType|.

                3. Otherwise, revert |type1| and |type2| to their state at the start of this loop.

                If the loop finishes without returning |finalType|,
                then the types can't be added.
                Return failure.

                Note: You can shortcut this in some cases
                by just checking the sum of all the [=map/values=]
                of |type1| vs |type2|.
                If the sums are different,
                the types can't be added.

            : Otherwise
            :: The types can't be added.
                Return failure.
        </dl>
</div>

<div algorithm>
    To <dfn>apply the percent hint</dfn> |hint| to a |type|,
    perform the following steps:

    1. If |type| doesn't [=map/contain=] |hint|, set |type|[|hint|] to 0.
    2. If |type| [=map/contains=] "percent", add |type|["percent"] to |type|[|hint|],
        then set |type|["percent"] to 0.
    4. Set |type|’s [=percent hint=] to |hint|.
</div>

<div algorithm>
    To <dfn for=CSSNumericValue local-lt="multiply | multiplication">multiply two types</dfn> |type1| and |type2|,
    perform the following steps:

    1. Replace |type1| with a fresh copy of |type1|,
        and |type2| with a fresh copy of |type2|.
        Let |finalType| be a new [=type=]
        with an initially empty [=ordered map=]
        and an initially null [=percent hint=].

    2. If both |type1| and |type2| have non-null [=percent hints=]
        with different values,
        the types can't be multiplied.
        Return failure.

    3. If |type1| has a non-null [=percent hint=] |hint| and |type2| doesn't,
        [=apply the percent hint=] |hint| to |type2|.

        Vice versa if |type2| has a non-null [=percent hint=] and |type1| doesn't.

    4. Copy all of |type1|’s [=map/entries=] to |finalType|,
        then [=map/for each=] |baseType| → |power| of |type2|:

        1. If |finalType|[|baseType|] [=map/exists=],
            increment its value by |power|.
        2. Otherwise, set |finalType|[|baseType|] to |power|.

        Set |finalType|’s [=percent hint=] to |type1|’s [=percent hint=].

    5. Return |finalType|.
</div>

A [=type=] is said to <dfn for=CSSNumericValue>match</dfn> a CSS production in some circumstances:

* A [=type=] matches <<length>>
    if its only non-zero [=map/entry=] is «[ "length" → 1 ]»
    and its [=percent hint=] is null.
    Similarly for <<angle>>, <<time>>, <<frequency>>, <<resolution>>, and <<flex>>.
* A [=type=] matches <<percentage>>
    if its only non-zero [=map/entry=] is «[ "percent" → 1 ]».
* A [=type=] matches <<length-percentage>>
    if its only non-zero [=map/entry=] is either «[ "length" → 1 ]» or «[ "percentage" → 1 ]»
    Same for <<angle-percentage>>, <<time-percentage>>, etc.
* A [=type=] matches <<number>>
    if it has no non-zero [=map/entries=]
    and its [=percent hint=] is null.
* A [=type=] matches <<number-percentage>>
    if it has no non-zero [=map/entries=],
    or its only non-zero [=map/entry=] is «[ "percentage" → 1 ]».

Many specifications use ''[ <<length>> | <<percentage>> ]''
instead of ''<<length-percentage>>'' in their grammar,
and specify in prose that the <<length>> and <<percentage>> can be combined.
For the purposes of [=matching=],
these cases should be treated as <<length-percentage>>.
Similarly for <<angle-percentage>>, etc.

Note: [=Types=] form a semi-group under both addition
and a monoid under multiplication
(with the multiplicative identity being «[ ]» with a null [=percent hint=]),
meaning that they're associative and commutative.
Thus the spec can, for example,
[=add=] an unbounded number of types together unambiguously,
rather than having to manually [=add=] them pair-wise.



<!--
██     ██ ██    ██ ████ ████████
██     ██ ███   ██  ██     ██
██     ██ ████  ██  ██     ██
██     ██ ██ ██ ██  ██     ██
██     ██ ██  ████  ██     ██
██     ██ ██   ███  ██     ██
 ███████  ██    ██ ████    ██
-->

### Value + Unit: {{CSSUnitValue}} objects ### {#simple-numeric}

Numeric values that can be expressed as a single unit
(or a naked number or percentage)
are represented as {{CSSUnitValue}}s.

<div class=example>
    For example, the value ''5px'' in a stylesheet
    will be represented by a {{CSSUnitValue}}
    with its `value` attribute set to `5`
    and its `unit` attribute set to `"px"`.

    Similarly, the value ''10'' in a stylesheet
    will be represented by a {{CSSUnitValue}}
    with its `value` attribute set to `10`
    and its `unit` attribute set to `"number"`.
</div>

<xmp class=idl>
    [Constructor(double value, DOMString unit)]
    interface CSSUnitValue : CSSNumericValue {
        attribute double value;
        attribute DOMString unit;
        readonly attribute DOMString type;
    };
</xmp>

<div algorithm="CSSUnitValue constructor(value, unit)">
    The <dfn constructor for=CSSUnitValue>CSSUnitValue(|value|, |unit|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. If [=creating a type=] from |unit| returns failure,
        [=throw=] a {{SyntaxError}}
        and abort this algorithm.

    2. Return a new {{CSSUnitValue}}
        with its {{CSSUnitValue/value}} internal slot set to |value|
        and its {{CSSUnitValue/unit}} set to |unit|.
</div>

<div algorithm="CSSUnitValue.unit">
    The <dfn attribute for=CSSUnitValue>unit</dfn> attribute of a {{CSSUnitValue}} |this| must,
    on setting a value |unit|,
    perform the following steps:

    1. If [=creating a type=] from |unit| returns failure,,
        [=throw=] a {{TypeError}}.

    2. Otherwise,
        set |this|’s {{CSSUnitValue/unit}} internal slot to |unit|.

    On reading,
    it must return the value of |this|’s {{CSSUnitValue/unit}} internal slot.
</div>

<div algorithm>
    The <dfn>[=type=] of a {{CSSUnitValue}}</dfn>
    is the result of [=creating a type=] from its {{CSSUnitValue/unit}} internal slot.
</div>

<div algorithm>
    To <dfn export>create a CSSUnitValue from a string</dfn> |str|,
    return a new {{CSSUnitValue}} object
    with its {{CSSUnitValue/value}} internal slot
    set to the numeric portion of |str| parsed into a number,
    and its {{CSSUnitValue/unit}} internal slot
    set to the unit portion of |str|,
    or "number" or "percent" if |str| is a plain number or percent.

    <div class=example>
        For example, [=create a CSSUnitValue from a string|creating a CSSUnitValue=] from ''5px''
        creates an object equivalent to
        <code>new CSSUnitValue(5, "px")</code>.
    </div>
</div>

<div algorithm>
    To <dfn export>convert a CSSUnitValue</dfn> |this| to a unit |unit|,
    perform the following steps:

    1. Let |old unit| be the value of |this|’s {{CSSUnitValue/unit}} internal slot,
        and |old value| be the value of |this|’s {{CSSUnitValue/value}} internal slot.

    2. If |old unit| and |unit| are not [=compatible units=],
        return failure.

    3. Return a new {{CSSUnitValue}}
        whose {{CSSUnitValue/unit}} internal slot
        is set to |unit|,
        and whose {{CSSUnitValue/value}} internal slot
        is set to |old value| multiplied by
        the conversation ratio between |old unit| and |unit|.
</div>



<!--
 ██████     ███    ██        ██████    ███ ███
██    ██   ██ ██   ██       ██    ██  ██     ██
██        ██   ██  ██       ██       ██       ██
██       ██     ██ ██       ██       ██       ██
██       █████████ ██       ██       ██       ██
██    ██ ██     ██ ██       ██    ██  ██     ██
 ██████  ██     ██ ████████  ██████    ███ ███
-->

### Complex Numeric Values: {{CSSMathValue}} objects ### {#complex-numeric}

Numeric values that are more complicated than a single value+unit
are represented by a tree of {{CSSMathValue}} subclasses,
eventually terminating in {{CSSUnitValue}} objects at the leaf nodes.
The ''calc()'', ''min()'', and ''max()'' functions in CSS
are represented in this way.

<div class=example>
    For example,
    the CSS value ''calc(1em + 5px)''
    will be represented by a {{CSSMathSum}}
    like <code>CSSMathSum(CSS.em(1), CSS.px(5))</code>.

    A more complex expression,
    like ''calc(1em + 5px * 2)'',
    will be represented by a nested structure
    like <code>CSSMathSum(CSS.em(1), CSSMathProduct(CSS.px(5), 2))</code>.
</div>

<xmp class=idl>
interface CSSMathValue : CSSNumericValue {
    readonly attribute CSSMathOperator operator;
    readonly attribute DOMString type;
};

[Constructor(CSSNumberish... args)]
interface CSSMathSum : CSSMathValue {
    attribute CSSNumericArray values;
};

[Constructor(CSSNumberish... args)]
interface CSSMathProduct : CSSMathValue {
    attribute CSSNumericArray values;
};

[Constructor(CSSNumberish arg)]
interface CSSMathNegate : CSSMathValue {
    attribute CSSNumericValue value;
};

[Constructor(CSSNumberish arg)]
interface CSSMathInvert : CSSMathValue {
    attribute CSSNumericValue value;
};

[Constructor(CSSNumberish... args)]
interface CSSMathMin : CSSMathValue {
    attribute CSSNumericArray values;
};

[Constructor(CSSNumberish... args)]
interface CSSMathMax : CSSMathValue {
    attribute CSSNumericArray values;
};

interface CSSNumericArray {}; // See issue below

enum CSSMathOperator {
    "sum",
    "product",
    "negate",
    "invert",
    "min",
    "max",
};
</xmp>

Issue: {{CSSNumericArray}} will be an Array-like
restricted to containing CSSNumericValue objects.
This is dependent on [WebIDL#345](https://github.com/heycam/webidl/issues/345) getting resolved properly.

Note: CSSMathValue, being a pure superclass,
cannot be directly constructed.
It exists solely to host the common attributes
of all the "math" operations.

<div algorithm="CSSMathValue.operator">
    The <dfn attribute for="CSSMathValue, CSSMathSum, CSSMathProduct, CSSMathMin, CSSMathMax, CSSMathNegate, CSSMathInvert">operator</dfn> attribute
    of a {{CSSMathValue}} |this| must,
    on getting,
    return the following string,
    depending on the interface of |this|:

    <dl class=switch>
        : {{CSSMathSum}}
        :: <code>"sum"</code>

        : {{CSSMathProduct}}
        :: <code>"product"</code>

        : {{CSSMathMin}}
        :: <code>"min"</code>

        : {{CSSMathMax}}
        :: <code>"max"</code>

        : {{CSSMathNegate}}
        :: <code>"negate"</code>

        : {{CSSMathInvert}}
        :: <code>"invert"</code>
    </dl>

    Note: These are all instances of the {{CSSMathOperator}} enum.
</div>

<div algorithm="CSSMathSum(...args)">
    The <dfn constructor for="CSSMathSum">CSSMathSum(...|args|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. Replace each [=list/item=] of |args|
        with the result of [=rectifying a numberish value=] for the [=list/item=].

    2. If |args| [=list/is empty=],
        [=throw=] a {{SyntaxError}}.

    3. Let |type| be the result of [=adding=] the [=types=] of all the [=list/items=] of |args|.
        If |type| is failure,
        [=throw=] a {{TypeError}}.

    4. Return a new {{CSSMathSum}}
        whose {{CSSMathSum/values}} internal slot
        is set to |args|.

    The <dfn constructor for="CSSMathMin">CSSMathMin(...|args|)</dfn>
    and <dfn constructor for="CSSMathMax">CSSMathMax(...|args|)</dfn> constructors
    are defined identically to the above,
    except that in the last step
    they return a new {{CSSMathMin}} or {{CSSMathMax}} object,
    respectively.

    The <dfn constructor for="CSSMathProduct">CSSMathProduct(...|args|)</dfn> constructor
    is defined identically to the above,
    except that in step 3 it [=multiplies=] the types instead of [=adding=],
    and in the last step
    it returns a {{CSSMathProduct}}.
</div>

<div algorithm="CSSMathNegate(arg)">
    The <dfn constructor for="CSSMathNegate">CSSMathNegate(|arg|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. Replace |arg|
        with the result of [=rectifying a numberish value=] for |arg|.

    1. Return a new {{CSSMathNegate}}
        whose {{CSSMathNegate/value}} internal slot
        is set to |arg|.

    The <dfn constructor for="CSSMathInvert">CSSMathInvert(|arg|)</dfn> constructor
    is defined identically to the above,
    except that in the last step
    it returns a new {{CSSMathInvert}} object.
</div>

<div algorithm>
    The <dfn>[=type=] of a CSSMathValue</dfn>
    depends on its class:

    <dl class=switch>
        : {{CSSMathSum}}
        : {{CSSMathMin}}
        : {{CSSMathMax}}
        :: The [=type=] is the result of [=adding=] the [=types=]
            of each of the [=list/items=] in its {{CSSMathSum/values}} internal slot.

        : {{CSSMathProduct}}
        :: The [=type=] is the result of [=multiplying=] the [=types=]
            of each of the [=list/items=] in its {{CSSMathProduct/values}} internal slot.

        : {{CSSMathNegate}}
        : {{CSSMathInvert}}
        :: The [=type=] is the same as the [=type=] of its {{CSSMathNegate/value}} internal slot,
            but with all [=map/values=] negated.
    </dl>
</div>


<!--
██    ██ ██     ██ ██     ██        ██████   ██████   ██████
███   ██ ██     ██ ███   ███       ██    ██ ██    ██ ██    ██
████  ██ ██     ██ ████ ████       ██       ██       ██
██ ██ ██ ██     ██ ██ ███ ██       ██        ██████   ██████
██  ████ ██     ██ ██     ██       ██             ██       ██
██   ███ ██     ██ ██     ██       ██    ██ ██    ██ ██    ██
██    ██  ███████  ██     ██        ██████   ██████   ██████
-->

### Numeric Factory Functions ### {#numeric-factory}

The following factory functions can be used
to create new numeric values much less verbosely
than using the constructors directly.

<xmp class=idl>
partial namespace CSS {
    CSSUnitValue number(double value);
    CSSUnitValue percent(double value);

    // <length>
    CSSUnitValue em(double value);
    CSSUnitValue ex(double value);
    CSSUnitValue ch(double value);
    CSSUnitValue ic(double value);
    CSSUnitValue rem(double value);
    CSSUnitValue lh(double value);
    CSSUnitValue rlh(double value);
    CSSUnitValue vw(double value);
    CSSUnitValue vh(double value);
    CSSUnitValue vi(double value);
    CSSUnitValue vb(double value);
    CSSUnitValue vmin(double value);
    CSSUnitValue vmax(double value);
    CSSUnitValue cm(double value);
    CSSUnitValue mm(double value);
    CSSUnitValue q(double value);
    CSSUnitValue in(double value);
    CSSUnitValue pt(double value);
    CSSUnitValue pc(double value);
    CSSUnitValue px(double value);

    // <angle>
    CSSUnitValue deg(double value);
    CSSUnitValue grad(double value);
    CSSUnitValue rad(double value);
    CSSUnitValue turn(double value);

    // <time>
    CSSUnitValue s(double value);
    CSSUnitValue ms(double value);

    // <frequency>
    CSSUnitValue Hz(double value);
    CSSUnitValue kHz(double value);

    // <resolution>
    CSSUnitValue dpi(double value);
    CSSUnitValue dpcm(double value);
    CSSUnitValue dppx(double value);

    // <flex>
    CSSUnitValue fr(double value);
};
</xmp>

<div algorithm="CSS.numeric">
    All of the above methods must,
    when called with a double |value|,
    return a new {{CSSUnitValue}}
    whose {{CSSUnitValue/value}} internal slot
    is set to |value|
    and whose {{CSSUnitValue/unit}} internal slot
    is set to the name of the method as defined here.

    Note: The unit used does not depend on the *current* name of the function,
    if it's stored in another variable;
    `let foo = CSS.px; let val = foo(5);` does not return a `{value: 5, unit: "foo"}` {{CSSUnitValue}}.
    The above talk about names is just a shorthand
    to avoid defining the unit individually for all ~20 functions.
</div>

<div class=example>
    For example, rather than creating a new {{CSSPositionValue}} with code like:

    <pre class=lang-js>
        let pos = new CSSPositionValue(
            new CSSUnitValue(5, "px"),
            new CSSUnitValue(10, "px"));
    </pre>

    One can instead write:

    <pre class=lang-js>
        let pos = new CSSPositionValue(CSS.px(5), CSS.px(10));
    </pre>
</div>

<!--
████████ ████████     ███    ██    ██  ██████  ████████  ███████  ████████  ██     ██
   ██    ██     ██   ██ ██   ███   ██ ██    ██ ██       ██     ██ ██     ██ ███   ███
   ██    ██     ██  ██   ██  ████  ██ ██       ██       ██     ██ ██     ██ ████ ████
   ██    ████████  ██     ██ ██ ██ ██  ██████  ██████   ██     ██ ████████  ██ ███ ██
   ██    ██   ██   █████████ ██  ████       ██ ██       ██     ██ ██   ██   ██     ██
   ██    ██    ██  ██     ██ ██   ███ ██    ██ ██       ██     ██ ██    ██  ██     ██
   ██    ██     ██ ██     ██ ██    ██  ██████  ██        ███████  ██     ██ ██     ██
-->

{{CSSTransformValue}} objects {#transformvalue-objects}
-------------------------------------------------------

{{CSSTransformValue}} objects represent <<transform-list>> values,
used by the 'transform' property.
They "contain" one or more {{CSSTransformComponent}}s,
which represent individual <<transform-function>> values.

<xmp class='idl'>
[Constructor(optional sequence<CSSTransformComponent> transforms)]
interface CSSTransformValue : CSSStyleValue {
    /*arraylike<CSSTransformComponent>;*/
    readonly attribute boolean is2D;
    DOMMatrix toMatrix();
};
</xmp>

Issue: Assuming the resolution of <a href="https://github.com/heycam/webidl/issues/345">WebIDL#345</a>
produces an "arraylike" declaration.

A {{CSSTransformValue}}’s [=values to iterate over=]
is a [=list=] of {{CSSTransformComponent}}s.

<div algorithm>
    The <dfn constructor for=CSSTransformValue>CSSTransformValue(|transforms|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. Return a new {{CSSTransformValue}} whose [=values to iterate over=] is |transforms|.
</div>

<div algorithm="CSSTransformValue.is2D">
    The <dfn attribute for=CSSTransformValue>is2D</dfn> attribute of a {{CSSTransformValue}} |this| must,
    on getting,
    return `true` if,
    [=list/for each=] |func| in |this|’s [=values to iterate over=],
    the |func|’s {{CSSTransformComponent/is2D}} attribute would return `true`;
    otherwise,
    the attribute returns `false`.
</div>

<div algorithm="CSSTransformValue.toMatrix()">
    The <dfn method for=CSSTransformValue>toMatrix()</dfn> method of a {{CSSTransformValue}} |this| must,
    when called,
    perform the following steps:

    1. Let |matrix| be a 4x4 matrix,
        initially set to the identity matrix.
        Let |is2D| be a boolean initially set to `true`.

    2. [=list/For each=] |func| in |this|’s [=values to iterate over=]:

        1. Let |funcMatrix| be |func|’s equivalent 4x4 transform matrix,
            as defined in [[css-transforms-1#mathematical-description]].

            As the entries of such a matrix are defined relative to the ''px'' unit,
            if any <<length>>s in |func| involved in generating the matrix
            are not [=compatible units=] with ''px'',
            [=throw=] a {{TypeError}}.
        2. Set |matrix| to the result of multiplying |matrix|
            and |funcMatrix|.
        3. If |func|’s {{CSSTransformComponent/is2D}} internal slot is `false`,
            set |is2D| to `false`.

    3. Return a new {{DOMMatrix}}
        representing |matrix|,
        and with its internal [=matrix/is 2D=] flag set to |is2D|.
</div>


<xmp class=idl>
    interface CSSTransformComponent {
        stringifier;
        attribute boolean is2D;
    };

    [Constructor(CSSNumericValue x, CSSNumericValue y, optional CSSNumericValue z)]
    interface CSSTranslation : CSSTransformComponent {
        attribute CSSNumericValue x;
        attribute CSSNumericValue y;
        attribute CSSNumericValue z;
    };

    [Constructor(CSSNumericValue angle),
     Constructor(CSSNumberish x, CSSNumberish y, CSSNumberish z, CSSNumericValue angle)]
    interface CSSRotation : CSSTransformComponent {
        attribute CSSNumberish x;
        attribute CSSNumberish y;
        attribute CSSNumberish z;
        attribute CSSNumericValue angle;
    };

    [Constructor(CSSNumberish x, CSSNumberish y, optional CSSNumberish z)]
    interface CSSScale : CSSTransformComponent {
        attribute CSSNumberish x;
        attribute CSSNumberish y;
        attribute CSSNumberish z;
    };

    [Constructor(CSSNumericValue ax, CSSNumericValue ay)]
    interface CSSSkew : CSSTransformComponent {
        attribute CSSNumericValue ax;
        attribute CSSNumericValue ay;
    };

    [Constructor(CSSNumericValue length)]
    interface CSSPerspective : CSSTransformComponent {
        attribute CSSNumericValue length;
    };

    [Constructor(DOMMatrixReadOnly matrix, optional CSSMatrixComponentOptions options)]
    interface CSSMatrixComponent : CSSTransformComponent {
        attribute DOMMatrix matrix;
    };

    dictionary CSSMatrixComponentOptions {
        boolean is2D;
    };
</xmp>

<div algorithm="CSSTransformComponent.is2D">
    The <dfn attribute for=CSSTransformComponent>is2D</dfn> attribute
    indicates whether the transform is 2D or 3D.
    When it's `true`,
    the attributes of the transform that are relevant to 3D transforms
    (such as the {{CSSTranslation/z|CSSTranslation.z}} attribute)
    simply have no effect on the transform they represent.

    Note: This affects the serialization of the object,
    and concepts such as the object's "equivalent 4x4 matrix".
</div>

<details class=note>
    <summary>{{CSSTransformComponent/is2D}} Design Considerations</summary>

    For legacy reasons,
    2D and 3D transforms are distinct,
    even if they have identical effects;
    a ''translateZ(0px)'' has observable effects on a page,
    even tho it's defined to be an identity transform,
    as the UA activates some 3D-based optimizations for the element.

    There were several possible ways to reflect this--
    nullable 3D-related attributes,
    separate 2D and 3D interfaces,
    etc--
    but we chose the current design
    (an author-flippable switch that dictates the behavior)
    because it allows authors to,
    in most circumstances,
    operate on transforms without having to care whether they're 2D or 3D,
    but also prevents "accidentally" flipping a 2D transform into becoming 3D.
</details>

<div algorithm="CSSTranslation()">
    The <dfn constructor for=CSSTranslation>CSSTranslation(|x|, |y|, |z|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. If |x|, |y|, or |z| (if passed)
        don't match <<length-percentage>>,
        [=throw=] a {{TypeError}}.

    2. Let |this| be a new {{CSSTranslation}} object,
        with its {{CSSTranslation/x}} and {{CSSTranslation/y}} internal slots
        set to |x| and |y|.

    3. If |z| was passed,
        set |this|’s {{CSSTranslation/z}} internal slot
        to |z|,
        and set |this|’s {{CSSTransformComponent/is2D}} internal slot
        to `false`.

    4. If |z| was not passed,
        set |this|’s {{CSSTranslation/z}} internal slot
        to [=create a CSSUnitValue from a string|new unit value=] of ''0px'',
        and set |this|’s {{CSSTransformComponent/is2D}} internal slot
        to `true`.

    5. Return |this|.
</div>

<div algorithm="CSSRotation(angle)">
    The <dfn constructor for=CSSRotation>CSSRotation(|angle|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. If |angle| doesn't match <<angle>>,
        [=throw=] a {{TypeError}}.

    2. Return a new {{CSSRotation}}
        with its {{CSSRotation/angle}} internal slot
        set to |angle|,
        its {{CSSRotation/x}} and {{CSSRotation/y}} internal slots
        set to [=create a CSSUnitValue from a string|new unit values=] of ''0'',
        its {{CSSRotation/z}} internal slot
        set to a [=create a CSSUnitValue from a string|new unit value=] of ''1'',
        and its {{CSSTransformComponent/is2D}} internal slot set to `true`.
</div>

<div algorithm="CSSRotation(x, y, z, angle)">
    The <dfn constructor for=CSSRotation>CSSRotation(|x|, |y|, |z|, |angle|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. If |angle| doesn't match <<angle>>,
        [=throw=] a {{TypeError}}.

    2. Let |x|, |y|, and |z|
        be replaced by the result of [=rectifying a numberish value=].

    3. If |x|, |y|, or |z|
        don't match <<number>>,
        [=throw=] a {{TypeError}}.

    4. Return a new {{CSSRotation}}
        with its {{CSSRotation/angle}} internal slot
        set to |angle|,
        its {{CSSRotation/x}}, {{CSSRotation/y}}, {{CSSRotation/z}} internal slots set to |x|, |y|, and |z|,
        and its {{CSSTransformComponent/is2D}} internal slot set to `false`.
</div>

<div algorithm="CSSScale()">
    The <dfn constructor for=CSSScale>CSSScale(|x|, |y|, |z|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. Let |x|, |y|, and |z| (if passed)
        be replaced by the result of [=rectifying a numberish value=].

    2. If |x|, |y|, or |z| (if passed)
        don't match <<number>>,
        [=throw=] a {{TypeError}}.

    3. Let |this| be a new {{CSSScale}} object,
        with its {{CSSScale/x}} and {{CSSScale/y}} internal slots
        set to |x| and |y|.

    4. If |z| was passed,
        set |this|’s {{CSSScale/z}} internal slot to |z|,
        and set |this|’s {{CSSTransformComponent/is2D}} internal slot to `false`.

    5. If |z| was not passed,
        set |this|’s {{CSSScale/z}} internal slot
        to a [=create a CSSUnitValue from a string|new unit value=] of ''1'',
        and set |this|’s {{CSSTransformComponent/is2D}} internal slot to `true`.

    6. Return |this|.
</div>

<div algorithm="CSSSkew()">
    The <dfn constructor for=CSSSkew>CSSSkew(|ax|, |ay|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. If |ax| or |ay| do not match <<angle>>,
        [=throw=] a {{TypeError}}.

    2. Return a new {{CSSSkew}} object
        with its {{CSSSkew/ax}} and {{CSSSkew/ay}} internal slots
        set to |ax| and |ay|,
        and its {{CSSTransformComponent/is2D}} internal slot set to `true`.
</div>

<div algorithm="CSSSkew.is2D">
    The <dfn attribute for=CSSSkew>is2D</dfn> attribute of a {{CSSSkew}} object must,
    on setting,
    do nothing.

    Note: ''skew()'' functions always represent 2D transforms.
</div>

<div algorithm="CSSPerspective()">
    The <dfn constructor for=CSSPerspective>CSSPerspective(|length|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. If |length| does not match <<length>>,
        [=throw=] a {{TypeError}}.

    2. Return a new {{CSSPerspective}} object
        with its {{CSSPerspective/length}} internal slot
        set to |length|,
        and its {{CSSTransformComponent/is2D}} internal slot set to `false`.
</div>

<div algorithm="CSSPerspective.is2D">
    The <dfn attribute for=CSSPerspective>is2D</dfn> attribute of a {{CSSPerspective}} object must,
    on setting,
    do nothing.

    Note: ''perspective()'' functions always represent 3D transforms.
</div>

<div algorithm="CSSMatrixComponent()">
    The <dfn constructor for=CSSMatrixComponent>CSSMatrixComponent(|matrix|, |options|)</dfn> constructor must,
    when invoked,
    perform the following steps:

    1. Let |this| be a new {{CSSMatrixComponent}} object
        with its {{CSSMatrixComponent/matrix}} internal slot
        set to |matrix|.

    2. If |options| was passed
        and has a {{CSSMatrixComponentOptions}} field,
        set |this|’s {{CSSTransformValue/is2D}} internal slot
        to the value of that field.

    3. Otherwise,
        set |this|’s {{CSSTransformValue/is2D}} internal slot
        to the value of |matrix|’s {{DOMMatrixReadOnly/is2D}} internal slot.

    4. Return |this|.
</div>

<div class=note>
    Each {{CSSTransformComponent}} can correspond to
    one of a number of underlying transform functions.
    For example, a {{CSSTranslation}}
    with an x value of ''10px''
    and y &amp; z values of ''0px'' could represent any of the following:

    * translate(10px)
    * translate(10px, 0)
    * translateX(10px)
    * translate3d(10px, 0, 0)

    When stringified, however,
    it will always print out either ''translate(10px, 0px)'' or ''translate3d(10px, 0px, 0px)'',
    depending on whether its {{CSSTransformComponent/is2D}} internal slot
    is `true` or `false`,
    respectively.
</div>

<!--
████████   ███████   ██████  ████ ████████ ████  ███████  ██    ██
██     ██ ██     ██ ██    ██  ██     ██     ██  ██     ██ ███   ██
██     ██ ██     ██ ██        ██     ██     ██  ██     ██ ████  ██
████████  ██     ██  ██████   ██     ██     ██  ██     ██ ██ ██ ██
██        ██     ██       ██  ██     ██     ██  ██     ██ ██  ████
██        ██     ██ ██    ██  ██     ██     ██  ██     ██ ██   ███
██         ███████   ██████  ████    ██    ████  ███████  ██    ██
-->

{{CSSPositionValue}} objects {#positionvalue-objects}
--------------------------------------------------

{{CSSPositionValue}} objects represent <<position>> values,
used by properties such as 'object-position'.

<pre class='idl'>
[Constructor(CSSNumericValue x, CSSNumericValue y)]
interface CSSPositionValue : CSSStyleValue {
    attribute CSSNumericValue x;
    attribute CSSNumericValue y;
};
</pre>

The {{CSSPositionValue/x}} attribute expresses the offset from the left edge of the container.
{{CSSPositionValue/y}} expressions the offset from the top edge of the container.

<div algorithm>
    The <dfn constructor for=CSSPositionValue>CSSPositionValue(|x|, |y|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. If |x| or |y| doesn't match <<length-percentage>>,
        [=throw=] a {{TypeError}}.

    2. Otherwise, return a new {{CSSPositionValue}}
        whose {{CSSPositionValue/x}} internal slot is set to |x|,
        and whose {{CSSPositionValue/y}} internal slot is set to |y|.
</div>

<div algorithm="CSSPositionValue.x">
    The <dfn attribute for=CSSPositionValue>x</dfn> and <dfn attribute for=CSSPositionValue>y</dfn> attribute of a {{CSSPositionValue}} |this| must,
    on setting a value |value|,
    perform the following steps:

    1. If |value| doesn't match <<length-percentage>>,
        [=throw=] a {{TypeError}}.

    2. Otherwise, set |this|’s {{CSSPositionValue/x}} or {{CSSPositionValue/y}} internal slot,
        as appropriate,
        to |value|.

    On reading, the attributes must return the value of the {{CSSPositionValue/x}} or {{CSSPositionValue/y}} internal slot,
        as appropriate.
</div>

<div class='example'>
    <<position>> values accept a complicated combination of keywords and values,
    but in the Typed OM are always simplified to just two offsets.
    For example, the following style sheet:

    <pre class='lang-css'>
    .example {
        object-position: center bottom 10px;
    }
    </pre>

    Will produce the following behavior:

    <pre class='lang-javascript'>
    let map = document.querySelector('.example').attributeStyleMap;

    map.get('object-position').x;
    // CSS.percent(50)

    map.get('object-position').y;
    // CSSMathSum(CSS.percent(100), CSS.px(-10))
    </pre>
</div>

<!--
████████  ████████  ██████   ███████  ██     ██ ████████   ██████  ████████
██     ██ ██       ██    ██ ██     ██ ██     ██ ██     ██ ██    ██ ██
██     ██ ██       ██       ██     ██ ██     ██ ██     ██ ██       ██
████████  ██████    ██████  ██     ██ ██     ██ ████████  ██       ██████
██   ██   ██             ██ ██     ██ ██     ██ ██   ██   ██       ██
██    ██  ██       ██    ██ ██     ██ ██     ██ ██    ██  ██    ██ ██
██     ██ ████████  ██████   ███████   ███████  ██     ██  ██████  ████████
-->

{{CSSResourceValue}} objects {#resourcevalue-objects}
-----------------------------------------------------

<pre class='idl'>
enum CSSResourceState {"unloaded", "loading", "loaded", "error"};

interface CSSResourceValue : CSSStyleValue {
    readonly attribute CSSResourceState state;
};

</pre>

{{CSSResourceValue}} objects represent CSS values that may require an asynchronous network fetch
before being usable.

A {{CSSResourceValue}} is in one of the following states, as reflected in the value of the
{{CSSResourceValue/state}} attribute:

:   "unloaded"
::  The resource is not ready and is not actively being fetched
:   "loading"
::  The resource is not ready, but is in the process of being fetched
:   "loaded"
::  The resource is ready for rendering
:   "error"
::  The resource can't be fetched, or the fetched resource is invalid

<div class='example'>
For example, images that match the <<url>> production can be used immediately, but will not result
in a visual change until the image data is fetched. {{CSSResourceValue}} objects represent this by
providing values that track loaded state via the {{CSSResourceState}} enum.
</div>

Issue(186): CSSResourceValues constructed within Worklets should be "unloaded".

<!--
████ ██     ██    ███     ██████   ████████
 ██  ███   ███   ██ ██   ██    ██  ██
 ██  ████ ████  ██   ██  ██        ██
 ██  ██ ███ ██ ██     ██ ██   ████ ██████
 ██  ██     ██ █████████ ██    ██  ██
 ██  ██     ██ ██     ██ ██    ██  ██
████ ██     ██ ██     ██  ██████   ████████
-->

{{CSSImageValue}} objects {#imagevalue-objects}
-----------------------------------------------

<pre class='idl'>
interface CSSImageValue : CSSResourceValue {
    readonly attribute double? intrinsicWidth;
    readonly attribute double? intrinsicHeight;
    readonly attribute double? intrinsicRatio;
};

[Constructor(USVString url)]
interface CSSURLImageValue : CSSImageValue {
    readonly attribute USVString url;
};

</pre>

{{CSSImageValue}} objects represent values for properties that take <<image>> productions,
for example 'background-image', 'list-style-image', and 'border-image-source'.

{{CSSImageValue}} objects that do not require network data (for example linear and radial gradients)
are initialized with {{CSSResourceValue/state}} "loaded".

If the {{CSSImageValue}}'s {{CSSResourceValue/state}} is "loaded",
and the resource has an intrinsic width, height, or aspect ratio,
then {{CSSImageValue/intrinsicWidth}}, {{CSSImageValue/intrinsicHeight}}, and {{CSSImageValue/intrinsicRatio}} must reflect the resource's corresponding value.
In all other cases, the attributes must be <code>null</code>.

Issue: Does the loading lifecycle need to be described here?

{{CSSURLImageValue}} objects represent {{CSSImageValue}}s that match the <<url>> production. For these
objects, the {{CSSURLImageValue/url}} attribute contains the URL that references the image.

<div algorithm>
    The <dfn constructor for=CSSURLImageValue>CSSURLImageValue(|url|)</dfn> constructor must,
    when called,
    perform the following steps:

    1. If the |url| passed into the constructor doesn't correctly
        parse as a <<url>>, throw a {{TypeError}} and exit this algorithm.
    2. Else, return a new {{CSSURLImageValue}}
        with its {{CSSURLImageValue/url}} internal slot
        set to |url|.
</div>


<!--
████████  ███████  ██    ██ ████████ ████████    ███     ██████  ████████
██       ██     ██ ███   ██    ██    ██         ██ ██   ██    ██ ██
██       ██     ██ ████  ██    ██    ██        ██   ██  ██       ██
██████   ██     ██ ██ ██ ██    ██    ██████   ██     ██ ██       ██████
██       ██     ██ ██  ████    ██    ██       █████████ ██       ██
██       ██     ██ ██   ███    ██    ██       ██     ██ ██    ██ ██
██        ███████  ██    ██    ██    ██       ██     ██  ██████  ████████
-->

{{CSSFontFaceValue}} objects {#fontfacevalue-objects}
-----------------------------------------------------

<pre class='idl'>

[Constructor(DOMString fontFamilyName)]
interface CSSFontFaceValue : CSSResourceValue {
    readonly attribute DOMString fontFamilyName;
};

</pre>

Issue(293): Add a src?

{{CSSFontFaceValue}} objects are opaque representations of the contents of
@font-face rules. They are used to pass font information into [=paint image definition=]s,
via [=custom properties=].

As font data may need to be fetched from a remote source, {{CSSFontFaceValue}} is a subclass
of {{CSSResourceValue}}.

Issue(159): Spec up ColorValue

<!--
 ██████   ██████   ██████                ██           ███████  ██     ██
██    ██ ██    ██ ██    ██                ██         ██     ██ ███   ███
██       ██       ██                       ██        ██     ██ ████ ████
██        ██████   ██████        ███████    ██       ██     ██ ██ ███ ██
██             ██       ██                 ██        ██     ██ ██     ██
██    ██ ██    ██ ██    ██                ██         ██     ██ ██     ██
 ██████   ██████   ██████                ██           ███████  ██     ██
-->

{{CSSStyleValue}} normalization {#stylevalue-normalization}
===========================================================

This section describes how Typed OM objects are constructed from CSS values.

If a property's grammar is more complex than one of the types listed here,
it produces a raw {{CSSStyleValue}},
with a <a for=CSSStyleValue>stringification behavior</a>
that produces the CSSOM serialization of the property.

Issue: Better to define a full table of properties and what types they normalize to.

Issue: Per F2F, "CSSOM serialization" isn't well-defined/interoperable enough.
We instead need to strictly define the serialization of every property.
This should be done according to CSSOM principlies, tho
(generally, shortest possible value).

Raw CSS tokens: properties with ''var()'' references {#normalize-tokens}
--------------------------------------------------

Regardless of what the property's grammar is otherwise,
a property value with an un-substituted ''var()'' reference
is represented as a [=list=] of [=component values=],
which becomes a {{CSSUnparsedValue}} in the Typed OM.

<div algorithm>
    To <dfn export>normalize a list of component values</dfn>
    from a |list|:

    1. Replace all ''var()'' references in |list|
        with {{CSSVariableReferenceValue}} objects,
        as described in [[#normalize-var]].
    2. Replace each remaining maximal subsequence of [=component values=] in |list|
        with a single string of their concatenated serializations.
    3. Return a new {{CSSUnparsedValue}}
        whose {{CSSUnparsedValue/[[tokens]]}} slot is set to |list|.
</div>

<div class='example'>
The string "calc(42px + var(--foo, 15em) + var(--bar, var(--far) + 15px))"
is converted into a {{CSSUnparsedValue}} that contains a sequence with:

    * the string "calc(42px + "
    * a {{CSSVariableReferenceValue}} with:
        * {{CSSVariableReferenceValue/variable}} "--foo"
        * {{CSSVariableReferenceValue/fallback}} a
            {{CSSUnparsedValue}} with a single-valued sequence containing " 15em"
    * the string " + "
    * a {{CSSVariableReferenceValue}} with:
        * {{CSSVariableReferenceValue/variable}} "--bar"
        * {{CSSVariableReferenceValue/fallback}} a {{CSSUnparsedValue}}
            with a sequence containing:
            * the string " "
            * a {{CSSVariableReferenceValue}} with
                * {{CSSVariableReferenceValue/variable}} "--far"
                * {{CSSVariableReferenceValue/fallback}} null
            * the string " + 15px"
    * the string ")"
</div>

''var()'' References {#normalize-var}
-------------------------------------

''var()'' references become {{CSSVariableReferenceValue}}s in the Typed OM.

<div algorithm>
    To <dfn export>normalize a ''var()'' reference</dfn> |var|:

    1. Let |object| be a new {{CSSVariableReferenceValue}}.

    2. Set |object|’s {{CSSVariableReferenceValue/variable}} internal slot
        to the serialization of the <<custom-ident>> providing the variable name.

    3. If |var| has a fallback value,
        set |object|’s {{CSSVariableReferenceValue/fallback}} internal slot
        to the result of [=normalize a list of component values|normalizing the fallback's component values=].
        Otherwise,
        set it to `null`.

    4. Return |object|.
</div>

[=Identifier=] Values {#normalize-ident}
-----------------------------------

CSS [=identifiers=] become {{CSSKeywordValue}}s in the Typed OM.

<div algorithm>
    To <dfn export>normalize an [=identifier=]</dfn> |ident|:

    1. Return a new {{CSSKeywordValue}}
        with its {{CSSKeywordValue/value}} internal slot
        set to the serialization of |ident|.
</div>

<<number>>, <<percentage>>, and <<dimension>> values {#normalize-numeric}
-------------------------------------------------------------------------

CSS <<number>>, <<percentage>>, and <<dimension>> values become {{CSSNumericValue}}s in the Typed OM.

<div algorithm>
    To <dfn export>normalize a numeric value</dfn> |num|:

    1. If |num| is a ''calc()'', ''min()'', or ''max()'' expression,
        [=normalize a math expression=] from |num|
        and return the result.

    2. If |num| is the unitless value ''0'' and |num| is a <<dimension>>,
        return a new {{CSSUnitValue}}
        with its {{CSSUnitValue/value}} internal slot
        set to 0,
        and its {{CSSUnitValue/unit}} internal slot
        set to "px".

    3. Return a new {{CSSUnitValue}}
        with its {{CSSUnitValue/value}} internal slot
        set to the numeric value of |num|,
        and its {{CSSUnitValue/unit}} internal slot
        set to "number" if |num| is a <<number>>,
        "percent" if |num| is a <<percentage>>,
        and |num|’s unit if |num| is a <<dimension>>.
</div>

<div algorithm>
    To <dfn for=CSSMath export local-lt="normalize">normalize a math expression</dfn> |num|:

    1. If |num| is a ''min()'' or ''max()'' expression:
        1. Let |values| be the result of [=CSSMath/normalizing=]
            the arguments to the expression,
            treating each argument as if it were the contents of a ''calc()'' expression.

        2. Return a new {{CSSMathMin}} or {{CSSMathMax}} object, respectively,
            with its {{CSSMathMin/values}} internal slot
            set to |values|.

    2. Assert: Otherwise, |num| is a ''calc()''.

    3. Turn |num|’s argument
        into an expression tree
        using standard PEMDAS precedence rules,
        with the following exceptions/clarification:

        * Treat subtraction as instead being addition,
            with the RHS argument instead wrapped in a special "negate" node.
        * Treat division as instead being multiplication,
            with the RHS argument instead wrapped in a special "invert" node.
        * Addition and multiplication are N-ary;
            each node can have any number of arguments.
        * If an expression has only a single value in it,
            and no operation,
            treat it as an addition node with the single argument.

    4. Recursively transform the expression tree into objects,
        as follows:

        <dl class=switch>
            : addition node
            :: becomes a new {{CSSMathSum}} object,
                with its {{CSSMathSum/values}} internal slot
                set to its list of arguments
            : multiplication node
            :: becomes a new {{CSSMathProduct}} object,
                with its {{CSSMathProduct/values}} internal slot
                set to its list of arguments
            : negate node
            :: becomes a new {{CSSMathNegate}} object,
                with its {{CSSMathNegate/value}} internal slot
                set to its argument
            : invert node
            :: becomes a new {{CSSMathInvert}} object,
                with its {{CSSMathInvert/value}} internal slot
                set to its argument
            : leaf node
            :: normalized as appropriate
        </dl>

    <div class=example>
        For example, ''calc(1px - 2 * 3em)''
        produces the structure:

        <pre>
            CSSMathSum(
                CSS.px(1),
                CSSMathNegate(
                    CSSMathProduct(
                        2,
                        CSS.em(3)
                    )
                )
            )
        </pre>
    </div>

    Note: The value computation process may transform different units into identical ones,
    simplifying the resulting expression.
    For example, ''calc(1px + 2em)'' as a specified value
    results in a <nobr><code>CSSMathSum(CSS.px(1), CSS.em(2))</code></nobr>,
    but as a computed value will give <nobr><code>CSS.px(33)</code></nobr> or similar
    (depending on the value of an ''em'' in that context).
</div>


<<transform-list>> and <<transform-function>> values {#transformvalue-normalization}
------------------------------------------------------------------------------------

CSS <<transform-list>> values become {{CSSTransformValue}}s in the Typed OM,
while CSS <<transform-function>> values become {{CSSTransformComponent}}s.

<div algorithm>
    To <dfn export>normalize a <<transform-list>></dfn> |list|:

    1. Return a new {{CSSTransformValue}}
        whose [=values to iterate over=]
        are the result of mapping the [=normalize a &lt;transform-function>=] algorithm
        over |list|.
</div>

<div algorithm>
    To <dfn export>normalize a <<transform-function>></dfn> |func|,
    perform the appropriate set of steps below,
    based on |func|:

    <dl class=switch>
        : ''matrix()''
        : ''matrix3d()''
        ::
            1. Return a new {{CSSMatrixComponent}} object,
                whose {{CSSMatrixComponent/matrix}} internal slot
                is set to a 4x4 matrix representing the same information
                as |func|,
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `true` if |func| is ''matrix()'',
                and `false` otherwise.

        : ''translate()''
        : ''translateX()''
        : ''translateY()''
        : ''translate3d()''
        : ''translateZ()''
        ::
            1. Return a new {{CSSTranslation}} object,
                whose {{CSSTranslation/x}}, {{CSSTranslation/y}}, and {{CSSTranslation/z}} internal slots
                are set to the [=normalize a numeric value|normalization=] of the specified x/y/z offsets,
                or the [=normalize a numeric value|normalization=] of ''0px'' if not specified in |func|,
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `true` if |func| is ''translate()'', ''translateX()'', or ''translateY()'',
                and `false` otherwise.

        : ''scale()''
        : ''scaleX()''
        : ''scaleY()''
        : ''scale3d()''
        : ''scaleZ()''
        ::
            1. Return a new {{CSSScale}} object,
                whose {{CSSScale/x}}, {{CSSScale/y}}, and {{CSSScale/z}} internal slots
                are set to the specified x/y/z scales,
                or to ''1'' if not specified in |func|
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `true` if |func| is ''scale()'', ''scaleX()'', or ''scaleY()'',
                and `false` otherwise.

        : ''rotate()''
        : ''rotate3d()''
        : ''rotateX()''
        : ''rotateY()''
        : ''rotateZ()''
        ::
            1. Return a new {{CSSRotation}} object,
                whose {{CSSRotation/angle}} internal slot
                is set to the [=normalize a numeric value|normalization=] of the specified angle,
                and whose {{CSSRotation/x}}, {{CSSRotation/y}}, and {{CSSRotation/z}} internal slots
                are set to the specified rotation axis coordinates,
                or the implicit axis coordinates if not specified in |func|
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `true` if |func| is ''rotate()'',
                and `false` otherwise.

        : ''skew()''
        : ''skewX()''
        : ''skewY()''
        ::
            1. Return a new {{CSSSkew}} object,
                whose {{CSSSkew/ax}} and {{CSSSkew/ay}} internal slots
                are set to the [=normalize a numeric value|normalization=] of the specified x and y angles,
                or the [=normalize a numeric value|normalization=] of ''0deg'' if not specified in |func|,
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `true`.

        : ''perspective()''
        ::
            1. Return a new {{CSSPerspective}} object,
                whose {{CSSPerspective/length}} internal slot
                is set to the [=normalize a numeric value|normalization=] of the specified length
                and whose {{CSSTransformComponent/is2D}} internal slot
                is `false`.
    </dl>
</div>

{{CSSPositionValue}} normalization {#positionvalue-normalization}
-----------------------------------------------------------------

If the provided value matches the <<position>> production, then a {{CSSPositionValue}} is constructed
with <var>x</var> and <var>y</var> components determined via the following process. If this process, or
any sub-process referenced by this process fails, then normalization as a whole fails.

1.  Initialize both <var>x</var> and <var>y</var> to a {{CSSNumericValue}} value representing 50%.
1.  If the provided value is a single keyword, length, percentage, or calc expression, then follow
        the procedure outlined in [[#from-single-keyword]] with <var>value</var> given
        by the provided value and a horizontal <var>bias</var>.
1.  Otherwise, if the provided value consists of a combination of two keywords, then:

        1.  follow the procedure outlined in [[#from-single-keyword]] with <var>value</var> given by the
                first keyword and an auto <var>bias</var>.
        1.  if <var>bias</var> is horizontal, set it to vertical. Otherwise, set it to horizontal.
        1.  follow the procedure again with <var>value</var> given by the second keyword, using the existing <var>bias</var>.

1.  Otherwise, if the provided value consists of a combination of two keywords, lengths, percentages, and
        calc expressions, then follow the procedure outlined in [[#from-single-keyword]] with
        <var>value</var> given by the first part of the provided value and a horizontal <var>bias</var>, then follow the
        procedure again with <var>value</var> given by the second part of the provided value and a vertical <var>bias</var>.
1.  Otherwise:

        1.  if the provided value starts with a keyword followed by a length, percentage, or calc expression, then follow
                the procedure outlined in [[#from-keyword-and-length]] with <var>keyword</var> set to the
                keyword, <var>length</var> set to the length, percentage, or calc expression, and auto <var>bias</var>.
        1.  otherwise, follow the procedure outlined in [[#from-single-keyword]] with <var>value</var>
                set to the first component of the provided value and an auto <var>bias</var>.
        1.  if <var>bias</var> is horizontal, set it to vertical. Otherwise, set it to horizontal.
        1.  if the remainder of the provided value is a single keyword, length, percentage or calc expression, follow
                the procedure outlined in
                [[#from-single-keyword]] with <var>value</var> set to the keyword and the existing
                <var>bias</var>.
        1.  otherwise, if the remainder of the provided value consists of a keyword followed by a length, percentage or
                calc expression, follow the procedure outlined in [[#from-keyword-and-length]] with
                <var>keyword</var> set to the keyword, <var>length</var> set to the length, percentage, or calc expression, and
                the existing <var>bias</var>.
        1.  Otherwise, the process fails.

<h4 id='from-single-keyword'>Determining <var>x</var> or <var>y</var> from a single value</h4>

The following process sets a value for either <var>x</var> or <var>y</var>, depending on an input <var>value</var>
and <var>bias</var>. The process also updates <var>bias</var> based on the <var>value</var>.

1.  If <var>value</var> is the keyword "left" and <var>bias</var> is not vertical, then set <var>x</var> to a
        {{CSSNumericValue}} value representing 0% and <var>bias</var> to horizontal and exit this process.
1.  If <var>value</var> is the keyword "right" and <var>bias</var> is not vertical, then set <var>x</var> to a
        {{CSSNumericValue}} value representing 100% and <var>bias</var> to horizontal and exit this process.
1.  If <var>value</var> is the keyword "top" and <var>bias</var> is not horizontal, then set <var>y</var> to a
        {{CSSNumericValue}} value representing 0% and <var>bias</var> to vertical and exit this process.
1.  If <var>value</var> is the keyword "bottom" and <var>bias</var> is not horizontal, then set <var>y</var> to a
        {{CSSNumericValue}} value representing 100% and <var>bias</var> to vertical and exit this process.
1.  If <var>value</var> matches the <<length-percentage>> production, then set <var>norm</var> to the result of
        [=normalize a numeric value|normalizing |value| as a numeric value=]. If <var>bias</var> is vertical,
        set <var>y</var> to <var>norm</var>, otherwise set <var>x</var> to <var>norm</var> and <var>bias</var> to
        horizontal. Exit this process.
1.  If <var>value</var> is not the keyword "center", then this process fails.

<h4 id='from-keyword-and-length'>Determining <var>x</var> or <var>y</var> from a keyword and a length</h4>

The following process sets a value for either <var>x</var> or<var>y</var>, depending on an input <var>keyword</var>,
<var>length</var>, and <var>bias</var>. The process also updates <var>bias</var> based on the <var>keyword</var> and
<var>length</var>.

1.  follow the procedure outlined in [[#from-single-keyword]] with <var>value</var> given by
        <var>keyword</var>, using the provided <var>bias</var>
1.  let <var>adjustment</var> be the result of
    [=normalize a numeric value|normalizing |length| as a numeric value=].
1.  If the keyword is "right" or "bottom", let <var>adjustment</var> be the result of subtracting
        <var>adjustment</var> from a zero length.
1.  amend <var>x</var> (if <var>bias</var> is horizontal) or <var>y</var> (if <var>bias</var> is vertical) by
        adding <var>adjustment</var> to it.

{{CSSResourceValue}} normalization {#resourcevalue-normalization}
--------------------------------------------------------------

Resource references are normalized by determining whether the reference is invalid
(in which case {{CSSResourceValue/state}} is set to ''error'') or
requires network data (in which case {{CSSResourceValue/state}}
is set to ''loading''). If data is not required and the reference is valid then
{{CSSResourceValue/state}} is set to ''loaded''.

If {{CSSResourceValue/state}} is set to ''loading'' then the image
reference is reevaluated once the pending data becomes available, according to the
same rules referenced above.

Normalization does not fail for {{CSSResourceValue}} objects.

<div class='example'>
The string 'url(''bike.png'')' is converted into a {{CSSURLImageValue}} with {{CSSResourceValue/state}} set to ''unloaded'' and the {{CSSURLImageValue/url}} set to ''https://drafts.css-houdini.org/css-typed-om/bike.png''. The {{CSSImageValue/intrinsicWidth}}, {{CSSImageValue/intrinsicHeight}} and {{CSSImageValue/intrinsicRatio}} are all set to null.
</div>

<!--
 ██████  ████████ ████████  ████    ███    ██       ████ ████████    ███    ████████ ████  ███████  ██    ██
██    ██ ██       ██     ██  ██    ██ ██   ██        ██       ██    ██ ██      ██     ██  ██     ██ ███   ██
██       ██       ██     ██  ██   ██   ██  ██        ██      ██    ██   ██     ██     ██  ██     ██ ████  ██
 ██████  ██████   ████████   ██  ██     ██ ██        ██     ██    ██     ██    ██     ██  ██     ██ ██ ██ ██
      ██ ██       ██   ██    ██  █████████ ██        ██    ██     █████████    ██     ██  ██     ██ ██  ████
██    ██ ██       ██    ██   ██  ██     ██ ██        ██   ██      ██     ██    ██     ██  ██     ██ ██   ███
 ██████  ████████ ██     ██ ████ ██     ██ ████████ ████ ████████ ██     ██    ██    ████  ███████  ██    ██
-->

{{CSSStyleValue}} Serialization {#stylevalue-serialization}
===========================================================

The way that a {{CSSStyleValue}} serializes is dependent on how the value was constructed.

:   if the value was constructed from a DOMString
::  the serialization is the DOMString from which the value was constructed.
:   otherwise, if the value was constructed using an IDL constructor
::  the serialization is specified in the sections below.
:   otherwise, if the value was extracted from the CSSOM
::  the serialization is specified in [[#cssom-serialization]] below.

<div class='example'>

For example:

<pre class='lang-javascript'>
var length1 = CSSNumericValue.from("42.0px");
length1.toString(); // "42.0px"

var length2 = CSSNumericValue.from(42.0, "px");
length2.toString(); // "42px";

element.style.width = "42.0px";
var length3 = element.attributeStyleMap.get('width');
length3.toString(); // "42px";
</pre>

</div>

{{CSSUnparsedValue}} Serialization {#unparsedvalue-serialization}
-----------------------------------------------------------------

{{CSSUnparsedValue}} objects are serialized by first serializing each
{{CSSVariableReferenceValue}}, then concatenating the contained DOMStrings and
{{CSSVariableReferenceValue}} serializations in order.

{{CSSVariableReferenceValue}} objects are serialized by the following process:
1.  the fallback {{CSSUnparsedValue}} is serialized
2.  if the fallback serialization is the empty string, then the
    {{CSSVariableReferenceValue}} serializes as "var(" + variable + ")"
3.  otherwise, the {{CSSVariableReferenceValue}} serializes as
    "var(" + variable + "," + fallback serialization + ")"

{{CSSKeywordValue}} Serialization {#keywordvalue-serialization}
---------------------------------------------------------------

{{CSSKeywordValue}} objects are serialized to their contained
{{CSSKeywordValue/value}} attribute.

{{CSSUnitValue}} Serialization {#numericvalue-serialization}
--------------------------------------------------------------

If their {{CSSUnitValue/unit}} is "number",
{{CSSUnitValue}} objects are serialized
to the string representation of their {{CSSUnitValue/value}}.

Otherwise, if their {{CSSUnitValue/unit}} is "percent",
{{CSSUnitValue}} objects are serialized
to the string representation of their {{CSSUnitValue/value}}
followed by the character U+0025 PERCENTAGE SIGN (%).

Otherwise,
{{CSSUnitValue}} objects are serialized
to the string representation of their {{CSSUnitValue/value}}
followed by their {{CSSUnitValue/unit}}.

{{CSSMathValue}} Serialization {#calc-serialization}
---------------------------------------------------------

{{CSSMathValue}} objects are serialized into a ''calc()'' expression

Issue: TODO

{{CSSTransformValue}} Serialization {#transformvalue-serialization}
-------------------------------------------------------------------

{{CSSTransformValue}} objects are serialized by generating a space-separated list
of serializations of the contained {{CSSTransformComponent}} objects.

{{CSSTransformComponent}} objects are serialized according to the following rules:

*   For all objects except {{CSSMatrixComponent}} objects, the serialization
    is defined by the object constructors.
*   When there are multiple constructors for a {{CSSMatrixComponent}} object, then
    if the {{CSSTransformComponent/is2D}} attribute is set to true,
    then the relevant constructor is the constructor with fewer arguments; otherwise
    the relevant constructor is the constructor with more arguments.
*   Each serialization is represented by a function
*   The function's name is a lowercase version of the component object type,
    without the CSS prefix
*   The function's arguments are a comma-separated list that matches the
    arguments to the relevant constructor. The values of the arguments are given
    by the attributes contained in the {{CSSTransformComponent}}.
*   {{CSSNumericValue}} attributes serialize using the rules above.
    Doubles serialize to their string representation.
*   {{CSSMatrixComponent}} objects serialize to a list of 6 components if
    {{CSSTransformComponent/is2D}} is set, or 12 components otherwise.
    Component order and format is given by [[CSS-TRANSFORMS-1]].

{{CSSPositionValue}} Serialization {#positionvalue-serialization}
-----------------------------------------------------------------

{{CSSPositionValue}} objects are serialized by:
*   serializing the {{CSSPositionValue/x}} attribute according to
    the rules for {{CSSNumericValue}} objects above.
*   serializing the {{CSSPositionValue/y}} attribute according to
    the rules for {{CSSNumericValue}} objects above.
*   returning the concatenation of the two serializations (x before y), separated
    by a space.

{{CSSURLImageValue}} Serialization {#urlimagevalue-serialization}
-----------------------------------------------------------

{{CSSURLImageValue}} objects are serialized to the string given by
"url(" + {{CSSURLImageValue/url}} + ")".

{{CSSFontFaceValue}} Serialization {#fontfacevalue-serialization}
-----------------------------------------------------------------

{{CSSFontFaceValue}} objects are serialized to the value of their contained
{{CSSFontFaceValue/fontFamilyName}}.

Serialization from CSSOM Values {#cssom-serialization}
------------------------------------------------------

{{CSSStyleValue}} objects produced by the user agent from values in the CSSOM,
rather than directly constructed by the author,
are serialized according to the following rules,
depending on the property they came from:

: 'background-color'
::
    1. If the value is the ''currentcolor'' keyword,
        return "currentcolor".
    2. Otherwise, return the result of serializing the <<color>> value.

: 'border-color'
::
    1. If the value is the ''currentcolor'' keyword,
        return "currentcolor".
    2. Otherwise, return the result of serializing the <<color>> value.

: 'border-image'
::
    1. Let |values| initially be the empty [=list=].
    2. If 'border-image-source' is not ''border-image-source/none'',
        serialize 'border-image-source' and append it to |values|.
    3. If 'border-image-slice' does not specify ''100%'' for all sides and omits the ''border-image-slice/fill'' keyword,
        serialize 'border-image-slice' and append it to |values|.
    4. If 'border-image-width' does not specify ''1'' for all sides,
        append "/ " (U+002F FORWARD SLASH followed by U+0020 SPACE)
        to the result of serializing 'border-image-width' and append it to |values|.
    5. If 'border-image-outset' does not specify ''0'' for all sides:
        1. If the previous 'border-image-width' step did not append anything to |values|,
            let |prefix| be <nobr>"// "</nobr>
            (two U+002F FORWARD SLASH characters followed by U+0020 SPACE);
            otherwise let |prefix| be <nobr>"/ "</nobr>
            (U+002F FORWARD SLASH followed by U+0020 SPACE)
        2. Append |prefix|
            to the result of serializing 'border-image-outset'
            and append it to |values|.
    6. If 'border-image-repeat' is not ''border-image-repeat/stretch'' in both axises,
        serialize 'border-image-repeat' and append it to |values|.
    7. If |values| is [=list/empty=],
        append "none" to |values|.
    8. Return the result of concatenating all the items in |values|,
        separated by " " (U+0020 SPACE).

: 'bottom'
::
    1. If the value is the ''auto'' keyword,
        return "auto".
    2. If the value is of type <<length>>,
        return the result of serializing the <<length>> value.
    3. Otherwise, return the result of serializing the <<percentage>> value.

: 'color'
::
    1. If the value is the ''currentcolor'' keyword,
        return "currentcolor".
    2. Otherwise, return the result of serializing the <<color>> value.

: 'left'
::
    1. If the value is the ''auto'' keyword,
        return "auto".
    2. If the value is of type <<length>>,
        return the result of serializing the <<length>> value.
    3. Otherwise, return the result of serializing the <<percentage>> value.

: 'position'
::
    1. Return the serialization of 'position'.

: 'right'
::
    1. If the value is the ''auto'' keyword,
        return "auto".
    2. If the value is of type <<length>>,
        return the result of serializing the <<length>> value.
    3. Otherwise, return the result of serializing the <<percentage>> value.

: 'top'
::
    1. If the value is the ''auto'' keyword,
        return "auto".
    2. If the value is of type <<length>>,
        return the result of serializing the <<length>> value.
    3. Otherwise, return the result of serializing the <<percentage>> value.


Security Considerations {#security-considerations}
==================================================

There are no known security issues introduced by these features.

Privacy Considerations {#privacy-considerations}
==================================================

There are no known privacy issues introduced by these features.

<!--
 ██████   ███████  ██     ██ ████████  ██     ██ ████████ ████████ ████████
██    ██ ██     ██ ███   ███ ██     ██ ██     ██    ██    ██       ██     ██
██       ██     ██ ████ ████ ██     ██ ██     ██    ██    ██       ██     ██
██       ██     ██ ██ ███ ██ ████████  ██     ██    ██    ██████   ██     ██
██       ██     ██ ██     ██ ██        ██     ██    ██    ██       ██     ██
██    ██ ██     ██ ██     ██ ██        ██     ██    ██    ██       ██     ██
 ██████   ███████  ██     ██ ██         ███████     ██    ████████ ████████
-->

Appendix A: Computed {{CSSStyleValue}} objects {#computed-stylevalue-objects}
=============================================================================

This appendix describes the restrictions on {{CSSStyleValue}} objects that
appear as computed values (i.e. as a value stored on computed
{{StylePropertyMapReadOnly}} objects).

Computed {{CSSUnparsedValue}} objects {#computed-unparsedvalue-objects}
-----------------------------------------------------------------------------

A property with a declared {{CSSUnparsedValue}} value will not
compute to a {{CSSUnparsedValue}}. Instead, after custom property references
are resolved, the {{CSSStyleValue}} subclass appropriate to the property will be
used.

<div class='example'>
For example, a style rule containing:

<pre class='style'>
width: calc(var(--foo) + 10%);
</pre>

Will represent a declared width as an {{CSSUnparsedValue}}, but if this value
is the winning value during computation for a given element then that element's
computed width will be represented by a {{CSSNumericValue}} object (assuming
that --foo resolves to a valid substitution).
</div>

Often there will be no {{CSSStyleValue}} subclass appropriate - for example when a custom property
contains a reference to another custom property. In these cases, a {{CSSStyleValue}}
is used directly to represent a value of unknown type.

<div class='example'>

For example, a style rule containing:

<pre class='style'>
--foo: var(--bar) black;
</pre>

Will represent a declared value for --foo as a {{CSSUnparsedValue}}, and if
this value is the winning declaration for --foo during computation for a given
element, then that element's will have a computed value for --foo that is
represented by a {{CSSStyleValue}}.
</div>

Computed {{CSSKeywordValue}} objects {#computed-keywordvalue-objects}
---------------------------------------------------------------------

During computation, {{CSSKeywordValue}} objects are either as specified (e.g. ''auto''
values for lengths that participate in layout) or resolved to a relevant value
and renormalized (e.g. the color ''red'').

Computed {{CSSUnitValue}} objects {#computed-numericvalue-objects}
---------------------------------------------------------------------

During computation, {{CSSUnitValue}} objects
are range-restricted or rounded as appropriate to the relevant property,
but otherwise as specified.

Computed {{CSSMathValue}} objects {#computed-calc-objects}
-----------------------------------------------------------------

During computation, {{CSSMathValue}} objects are reduced accordingly:

Issue: TODO

Computed {{CSSTransformValue}} objects {#computed-transformvalue-objects}
-------------------------------------------------------------------------

During computation, any {{CSSNumericValue}} objects referenced by a {{CSSTransformComponent}}
(e.g. the {{CSSTranslation/x}} attribute of a {{CSSTranslation}}) are
computed according to [[#computed-numericvalue-objects]], but the
{{CSSTransformValue}} object is otherwise as specified.

Computed {{CSSPositionValue}} objects {#computed-positionvalue-objects}
-----------------------------------------------------------------------

During computation, both the {{CSSPositionValue/x}} and
{{CSSPositionValue/y}} components of a {{CSSPositionValue}} are
computed according to [[#computed-numericvalue-objects]].

Computed {{CSSImageValue}} objects {#computed-imagevalue-objects}
-----------------------------------------------------------------

Computed {{CSSImageValue}} objects are as specified.

Computed {{CSSFontFaceValue}} objects {#computed-fontfacevalue-objects}
---------------------------------------------------------------

Computed {{CSSFontFaceValue}} objects are as specified.