CSS Typed OM Level 1

1. Introduction

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 specified CSSLengthValue can’t be treated as a number without first explicitly casting it to a CSSSimpleLength, as calc expressions and keywords are also valid lengths.

2. `CSSStyleValue` objects

interface CSSStyleValue {
  attribute DOMString cssText;
  static (CSSStyleValue or sequence<CSSStyleValue>)? parse(DOMString property, DOMString cssText);
};

CSSStyleValue objects are the base class of all CSS Values accessible via the Typed OM API. Unsupported values are also represented as CSSStyleValue objects.

The cssText attribute provides a normalized representation (see §6 CSSStyleValue normalization) of the value contained by a CSSStyleValue object.

The parse(DOMString property, DOMString cssText) method attempts to parse cssText as a valid CSSStyleValue or sequence<CSSStyleValue> for property, returning null on failure.

2.1. `CSSTokenStreamValue` objects

interface CSSTokenStreamValue : CSSStyleValue {
  iterable<(DOMString or CSSVariableReferenceValue)>;
};

interface CSSVariableReferenceValue {
  attribute DOMString variable;
  attribute CSSTokenStreamValue fallback;
};

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

3. The `StylePropertyMap`

interface StylePropertyMapReadOnly {
  CSSStyleValue? get(DOMString property);
  sequence<CSSStyleValue> getAll(DOMString property);
  boolean has(DOMString property);
  iterable<DOMString, (CSSStyleValue or sequence<CSSStyleValue> or DOMString)>;
  sequence<DOMString> getProperties();
  stringifier;
};

interface StylePropertyMap : StylePropertyMapReadOnly {
  void append(DOMString property, (CSSStyleValue or DOMString)... values);
  void delete(DOMString property);
  void set(DOMString property, (CSSStyleValue or DOMString)... values);
};

A StylePropertyMapReadOnly object has an associated property model, which is a list of property - sequence<CSSStyleValue> pairs. This list is initialized differently depending on where the CSSStyleValue is used (see §3.1 Computed StylePropertyMapReadOnly objects, §3.2 Specified StylePropertyMap objects, and §3.3 Inline StylePropertyMap objects).

The sequence of CSSStyleValues 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 get() and/or set() for those properties.

When invoked, the append(DOMString property (CSSStyleValue or DOMString)... values) method follows the following steps:

first need to check whether the property is a valid property. <https://github.com/w3c/css-houdini-drafts/issues/143>

if property is not list-valued

throw a TypeError
if the property model has no entry for property

initialize an empty sequence in the property model for property
for each value in values, if value is a CSSStyleValue, and its type is a type that property can’t accept

throw a TypeError
for each value in values, if value is a DOMString

set value to the result of invoking parse(), providing property and value as inputs.
if any value in values is null

throw a TypeError

else

concatenate values onto the end of the entry in the property model

should refactor out value type-checking, as it’ll be needed by the rest of the setters too <https://github.com/w3c/css-houdini-drafts/issues/145>

need a robust description of what "a type that property can’t accept" means. <https://github.com/w3c/css-houdini-drafts/issues/147>

add detailed descriptions of the rest of the methods on StylePropertyMap <https://github.com/w3c/css-houdini-drafts/issues/148>

describe that these are not live objects <https://github.com/w3c/css-houdini-drafts/issues/149>

3.1. Computed `StylePropertyMapReadOnly` objects

partial interface Window {
  StylePropertyMapReadOnly getComputedStyleMap(Element element, optional DOMString? pseudoElt);
};

Computed StylePropertyMap objects represent the computed style of an Element or pseudo element, and are accessed by calling the getComputedStyleMap(Element, optional DOMString?) 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 getComputedStyleMap represents computed style, not resolved style. In this regard it provides different values than those in objects returned by getComputedStyle.

3.2. Specified `StylePropertyMap` objects

partial interface CSSStyleRule {
  [SameObject] readonly attribute StylePropertyMap styleMap;
};

Specified StylePropertyMap objects represent style property-value pairs embedded in a style rule, and are accessed via the styleMap attribute of CSSStyleRule objects.

When constructed, the property model for specified 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.

3.3. Inline `StylePropertyMap` objects

partial interface Element {
  [SameObject] readonly attribute StylePropertyMap styleMap;
};

Inline StylePropertyMap objects represent inline style declarations attached directly to Elements. They are accessed via the styleMap 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.

4. `CSSStyleValue` subclasses

4.1. `CSSKeywordValue` objects

[Constructor(DOMString)]
interface CSSKeywordValue : CSSStyleValue {
  attribute DOMString keywordValue;
};

CSSKeywordValue objects represent CSSStyleValues that are keywords. The constructor for CSSKeywordValue should check that they contain valid CSS, but they do not check whether the contained string is a valid keyword for a particular property. Property setters are required to enforce keyword validity.

4.2. `CSSNumberValue` objects

[Constructor(double), Constructor(DOMString cssText)]
interface CSSNumberValue : CSSStyleValue {
  attribute double value;
};

CSSNumberValue objects represent values for simple number-valued properties like z-index or opacity.

CSSNumberValue objects are not range-restricted. Any valid number can be represented by a CSSNumberValue, and that value will not be clamped, rounded, or rejected when set on a specified StylePropertyMap or inline StylePropertyMap. Instead, clamping and/or rounding will occur during computation of style.

The following code is valid

myElement.styleMap.set("opacity", new CSSNumberValue(3));
myElement.styleMap.set("z-index", new CSSNumberValue(15.4));

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

var computedStyle = getComputedStyleMap(myElement);
var opacity = computedStyle.get("opacity");
var zIndex = computedStyle.get("z-index");

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).

where does a description of parsing values go? For example, where do we indicate that calc(4 + 8) will create a CSSNumberValue with a value of 12? <https://github.com/w3c/css-houdini-drafts/issues/140>

4.3. `CSSLengthValue` objects

enum LengthType {
  "px", "percent",
  "em", "ex", "ch", "rem",
  "vw", "vh", "vmin", "vmax",
  "cm", "mm", "q", "in", "pc", "pt"
};

dictionary CSSCalcDictionary {
  double px;
  double percent;
  double em;
  double ex;
  double ch;
  double rem;
  double vw;
  double vh;
  double vmin;
  double vmax;
  double cm;
  double mm;
  double q;
  double in;
  double pc;
  double pt;
};

interface CSSLengthValue : CSSStyleValue {
  CSSLengthValue add(CSSLengthValue value);
  CSSLengthValue subtract(CSSLengthValue value);
  CSSLengthValue multiply(double value);
  CSSLengthValue divide(double value);
  static CSSLengthValue from(DOMString cssText);
  static CSSLengthValue from(double value, LengthType type);
  static CSSLengthValue from(CSSCalcDictionary dictionary);
};

[Constructor(DOMString cssText),
 Constructor(CSSLengthValue),
 Constructor(CSSCalcDictionary)
]
interface CSSCalcLength : CSSLengthValue {
  attribute double? px;
  attribute double? percent;
  attribute double? em;
  attribute double? ex;
  attribute double? ch;
  attribute double? rem;
  attribute double? vw;
  attribute double? vh;
  attribute double? vmin;
  attribute double? vmax;
  attribute double? cm;
  attribute double? mm;
  attribute double? q;
  attribute double? in;
  attribute double? pc;
  attribute double? pt;
};

// lengths that are *just* keywords don’t become CSSSimpleLengths or CSSCalcLengths.
// Instead they are represented as CSSKeywordValue objects.
[Constructor(DOMString cssText),
 Constructor(CSSLengthValue),
 Constructor(double value, LengthType type)]
interface CSSSimpleLength : CSSLengthValue {
  attribute double value;
  readonly attribute LengthType type;
};

CSSLengthValue objects represent lengths:

CSSSimpleLength objects represent lengths that contain a single unit type (for example "42px").
CSSCalcLength objects represent lengths that contain multiple units (for example "calc(56em + 10%)").

CSSLengthValue objects are not range-restricted. Any valid combination of primitive lengths can be represented by a CSSLengthValue, that value will be accepted unaltered when set on a specified StylePropertyMap or inline StylePropertyMap. Instead, clamping and/or rounding will occur during computation of style.

Note that lengths which incorporate variable references will instead be represented as CSSTokenStreamValue objects, and keywords as CSSKeywordValue objects.

The following methods are defined for CSSLengthValue objects:

add(CSSLengthValue value): Adds the provided value to the length represented by the object, and returns the result as a new CSSLengthValue. This will construct a CSSSimpleLength or CSSCalcLength depending on whether the result can be expressed in terms of a single unit.
subtract(CSSLengthValue value): Subtracts the provided value from the length represented by the object, and returns the result as a new CSSLengthValue. This will construct a CSSSimpleLength or CSSCalcLength depending on whether the result can be expressed in terms of a single unit.
multiply(double value): Multiplies the length represented by the object by the provided value, and returns the result as a new CSSLengthValue. This will construct a CSSSimpleLength if the object is a CSSSimpleLength, or a CSSCalcLength if the object is a CSSCalcLength.
divide(double value): Divides the length represented by the object by the provided value, and returns the result as a new CSSLengthValue. This will construct a CSSSimpleLength if the object is a CSSSimpleLength, or a CSSCalcLength if the object is a CSSCalcLength. The function will throw a RangeError when the value given is 0.
from(DOMString cssText): Parses the provided cssText as a length value. Will return a CSSSimpleLength when possible, or a CSSCalcLength otherwise. The function will throw a SyntaxError, when the DOMString it is passed doesn’t represent a valid length.
from(double value, LengthType type): Constructs a CSSSimpleLength with the given value and unit type.
from(CSSCalcDictionary dictionary): Constructs a CSSCalcLength with units and values as defined by the provided dictionary.

4.4. `CSSAngleValue` objects

enum CSSAngleUnit {
  "deg", "rad", "grad", "turn"
};

[Constructor(double value, CSSAngleUnit unit)]
interface CSSAngleValue : CSSStyleValue {
  readonly attribute double degrees;
  readonly attribute double radians;
  readonly attribute double gradians;
  readonly attribute double turns;
};

CSSAngleValue objects represent CSS angles. Once constructed, a CSSAngleValue provides attributes that reflect the size of the angle in each of the CSS angle units represented by the CSSAngleUnit enum.

4.5. `CSSTransformValue` objects

[Constructor(),
 Constructor(sequence<CSSTransformComponent> transforms)]
interface CSSTransformValue : CSSStyleValue {
  iterable<CSSTransformComponent>;
  readonly attribute boolean is2D;
  readonly attribute DOMMatrixReadOnly matrix;
};

interface CSSTransformComponent {
  readonly attribute DOMString cssText;
  readonly attribute boolean is2D;
  readonly attribute DOMMatrixReadOnly matrix;
};

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

[Constructor(double degrees),
 Constructor(CSSAngleValue angle),
 Constructor(double degrees, double x, double y, double z),
 Constructor(CSSAngleValue angle, double x, double y, double z)]
interface CSSRotation : CSSTransformComponent {
  readonly attribute double angle;
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double z;
};

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

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

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

[Constructor(DOMMatrixReadOnly matrix)]
interface CSSMatrix : CSSTransformComponent {
};

CSSTransformValue objects represent values for the transform property. A CSSTransformValue represents a list of CSSTransformComponents.

CSSTransformComponent objects have the following properties:

The is2D attribute is true if the component represents a 2D transform function, and false otherwise. The transform function which the component represents is stored in string form in the cssText attribute.

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 & z values of 0 could be:

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

When a CSSRotation is constructed with a double (as opposed to a CSSAngleValue), the angle is taken to be in degrees.

The following two CSSRotations are equivalent:

CSSRotation(angle);
CSSRotation(CSSAngleValue(angle, "deg"));

When a CSSTransformValue is read from a StylePropertyMap, each CSSTransformComponent will maintain the relevant transform function in its cssText attribute. However, newly constructed CSSTransformValues will always generate cssText according to the following rules:

CSSSkew will always serialize to skew(ax, ay)
CSSPerspective will always serialize to perspective(length)
CSSTranslation, CSSRotation, and CSSScale each have two constructors. In each case, the constructor with fewer arguments constructs a CSSTransformComponent for which is2D will be true, with cssText employing the 2D version of the relevant transform function (translate, rotate, scale). The constructor with more arguments constructs a CSSTransformComponent for which is2D will be false, with cssText employing the 3D version of the relevant transform function (translate3d, rotate3d, scale3d).
CSSMatrix objects are constructed around a DOMMatrixReadOnly, and well serialize to a matrix function if the contained DOMMatrixReadOnly's is2D attribute is false, and a matrix3d function otherwise.

is2D is true if the is2D attribute of every CSSTransformComponent referenced by the CSSTransformValue returns true, and false otherwise.

4.6. `CSSPositionValue` objects

[Constructor(CSSLengthValue x, CSSLengthValue y)]
interface CSSPositionValue : CSSStyleValue {
  readonly attribute CSSLengthValue x;
  readonly attribute CSSLengthValue y;
};

CSSPositionValue objects represent values for properties that take <position> productions, for example background-position.

The x attribute contains the position offset from the left edge of the container, expressed as a length.

The y attribute contains the position offset from the top edge of the container, expressed as a length.

Note that <position> productions accept a complicated combination of keywords and values. When specified as such in a stylesheet or via the untyped CSSOM, the cssText attribute will contain the specified string. However, this string is normalized as two Lengths into the x and y values of the CSSStyleValue object.

New CSSPositionValue objects can only be constructed via pairs of lengths, and will only return the direct serialization of these lengths in the cssText attribute.

For example, the following style sheet:

.example {
  background-position: center bottom 10px;
}

Will produce the following behavior:

// "center bottom 10px"
document.querySelector('.example').styleMap.get('background-position').cssText;

// 50% - as a CSSSimpleLength
document.querySelector('.example').styleMap.get('background-position').x;

// calc(100% - 10px) - as a CSSCalcLength
document.querySelector('.example').styleMap.get('background-position').y;

4.7. `CSSResourceValue` objects

enum CSSResourceState {"unloaded", "loading", "loaded", "error"};

interface CSSResourceValue {
  readonly attribute CSSResourceState state;
};

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 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

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.

4.8. `CSSImageValue` objects

interface CSSImageValue : CSSResourceValue {
  readonly attribute double intrinsicWidth;
  readonly attribute double intrinsicHeight;
};

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

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 state loaded.

If state is unloaded, loading, or error, then intrinsicWidth and intrinsicHeight are 0. Otherwise, the attributes are set to the intrinsic width and height of the referenced image.

Does the loading lifecycle need to be described here?

CSSURLImageValue objects represent CSSImageValues that match the <url> production. For these objects, the url attribute contains the URL that references the image.

4.9. `CSSFontFaceValue` objects

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

CSSFontFaceValue objects represent font faces that can be used to render text. As font data may need to be fetched from a remote source, CSSFontFaceValue is a subclass of CSSResourceValue.

5. Mapping of properties to accepted types

This section provides a table of which types of CSSStyleValue a given property can accept. Note that most, but not all properties take CSSKeywordValue. Shorthand properties and values are not supported.

Property	Allowable `CSSStyleValue` types
align-content	`CSSKeywordValue`
align-items	`CSSKeywordValue`
align-self	`CSSKeywordValue`
alignment-baseline	`CSSKeywordValue`
all	`CSSKeywordValue`
animation-delay	TimeValue \| `CSSKeywordValue`
animation-direction	`CSSKeywordValue`
animation-fill-mode	`CSSKeywordValue`
animation-iteration-count	`CSSNumberValue` \| `CSSKeywordValue`
animation-name	CustomIdentValue \| `CSSKeywordValue`
animation-play-state	`CSSKeywordValue`
animation-timing-function	TransitionTimingFunctionValue \| `CSSKeywordValue`
appearance	`CSSKeywordValue`
background-attachment	`CSSKeywordValue`
background-blend-mode	`CSSKeywordValue`
background-clip	`CSSKeywordValue`
background-color	ColorValue \| `CSSKeywordValue`
background-image	`CSSImageValue`
background-origin	`CSSKeywordValue`
background-position	`CSSPositionValue` \| `CSSKeywordValue`
background-repeat	`CSSKeywordValue`
background-size	PairValue<`CSSLengthValue`> (or SizeValue?)\| `CSSKeywordValue`
baseline-shift	`CSSLengthValue` \| `CSSKeywordValue`
border-boundary	`CSSKeywordValue`
border-collapse	`CSSKeywordValue`
border-color	ColorValue \| `CSSKeywordValue`
border-top-color border-right-color border-bottom-color border-left-color	ColorValue \| `CSSKeywordValue`
border-image-outset	FourValues<`CSSLengthValue`\|`CSSNumberValue`>
border-image-repeat	PairValue<`CSSKeywordValue`>
border-image-slice	BorderImageSliceValue
border-image-source	`CSSImageValue`
border-image-width	FourValues<`CSSLengthValue`\|`CSSNumberValue`\|`CSSKeywordValue`>
border-top-style border-right-style border-bottom-style border-left-style	`CSSKeywordValue`
border-top-right-radius border-bottom-right-radius border-bottom-left-radius border-top-left-radius	PairValue<`CSSLengthValue`> \| `CSSKeywordValue`
border-top-width border-right-width border-bottom-width border-left-width	`CSSLengthValue` \| `CSSKeywordValue`
bottom	`CSSLengthValue` \| `CSSKeywordValue`
caption-side	`CSSKeywordValue`
clear	`CSSKeywordValue`
clip	ShapeValue \| `CSSKeywordValue`
color	ColorValue \| `CSSKeywordValue`
content	StringValue \| URIValue \| CounterValue \| AttrValue \| `CSSKeywordValue`
counter-increment counter-reset	CounterValue \| `CSSKeywordValue`
cue-after cue-before	URIValue \| `CSSKeywordValue`
cursor	URIValue \| `CSSKeywordValue`
direction	`CSSKeywordValue`
display	`CSSKeywordValue`
empty-cells	`CSSKeywordValue`
float	`CSSKeywordValue`
font-family	`CSSKeywordValue`
font-size	`CSSLengthValue` \| `CSSKeywordValue`
font-style	`CSSKeywordValue`
font-variant	`CSSKeywordValue`
font-weight	FontWeightValue \| `CSSKeywordValue`
height	`CSSLengthValue` \| `CSSKeywordValue`
left	`CSSLengthValue` \| `CSSKeywordValue`
letter-spacing	`CSSLengthValue` \| `CSSKeywordValue`
line-height	`CSSNumberValue` \| `CSSLengthValue` \| `CSSKeywordValue`
list-style-image	`CSSImageValue`
list-style-position	`CSSKeywordValue`
list-style-type	`CSSKeywordValue`
margin-top margin-right margin-bottom margin-left	`CSSLengthValue` \| `CSSKeywordValue`
max-height max-width min-height min-width	`CSSLengthValue` \| `CSSKeywordValue`
orphans	`CSSNumberValue` \| `CSSKeywordValue`
outline-color	ColorValue \| `CSSKeywordValue`
outline-style	`CSSKeywordValue`
outline-width	`CSSLengthValue` \| `CSSKeywordValue`
overflow	`CSSKeywordValue`
padding-top padding-right padding-bottom padding-left	`CSSLengthValue` \| `CSSKeywordValue`
page-break-after page-break-before	`CSSKeywordValue`
page-break-inside	`CSSKeywordValue`
pause-after pause-before	TimeValue \| PercentageValue \| `CSSKeywordValue`
pitch-range	`CSSNumberValue` \| `CSSKeywordValue`
pitch	FrequencyValue \| `CSSKeywordValue`
play-during	PlayDuringValue \| `CSSKeywordValue`
position	`CSSKeywordValue`
quotes	PairValue<StringValue> \| `CSSKeywordValue`
richness	`CSSNumberValue` \| `CSSKeywordValue`
right	`CSSLengthValue` \| `CSSKeywordValue`
speak-header	`CSSKeywordValue`
speak-numeral	`CSSKeywordValue`
speak-punctuation	`CSSKeywordValue`
speak	`CSSKeywordValue`
speech-rate	`CSSNumberValue` \| `CSSKeywordValue`
stress	`CSSNumberValue` \| `CSSKeywordValue`
table-layout	`CSSKeywordValue`
text-align	`CSSKeywordValue`
text-decoration	`CSSKeywordValue`
text-indent	`CSSLengthValue` \| `CSSKeywordValue`
text-transform	`CSSKeywordValue`
top	`CSSLengthValue` \| `CSSKeywordValue`
unicode-bidi	`CSSKeywordValue`
vertical-align	`CSSLengthValue` \| `CSSKeywordValue`
visibility	`CSSKeywordValue`
voice-family	VoiceValue \| `CSSKeywordValue`
volume	`CSSNumberValue` \| PercentageValue \| `CSSKeywordValue`
white-space	`CSSKeywordValue`
widows	`CSSNumberValue` \| `CSSKeywordValue`
width	`CSSLengthValue` \| `CSSKeywordValue`
word-spacing	`CSSLengthValue` \| `CSSKeywordValue`
z-index	`CSSNumberValue` \| `CSSKeywordValue`

Spec up ColorValue <https://github.com/w3c/css-houdini-drafts/issues/159>

6. `CSSStyleValue` normalization

This section describes how normalized CSSStyleValue objects are constructed from CSS DOMString values.

Strings are normalized by resulting CSSStyleValue subclass. To determine which subclass to use, the CSS property that the string is a value for is used to look up the table in §5 Mapping of properties to accepted types. The normalization procedure defined by each of the CSSStyleValue subclasses listed for that property in turn, falling back to the next subclass in the list if the current one fails to normalize.

If all listed subclasses fail, then the value is normalized as a raw CSSStyleValue, with the cssText attribute set to the input value.

6.1. `CSSTokenStreamValue` normalization

Values which contain custom property references are tokenized then split into runs of tokens separated by custom property references.

The token runs are serialized, while each custom property reference is represented by a CSSVariableReferenceValue.

The string "calc(42px + var(--foo, 15em) + var(--bar, var(--far) + 15px))" is converted into a CSSTokenStreamValue that contains a sequence with:

the string "calc(42px + "
a CSSVariableReferenceValue with:
- variable "--foo"
- fallback a CSSTokenStreamValue with a single-valued sequence containing " 15em"
the string " + "
a CSSVariableReferenceValue with:
- variable "--bar"
- fallback a CSSTokenStreamValue with a sequence containing:
  - the string " "
  - a CSSVariableReferenceValue with
    - variable "--far"
    - fallback undefined
  - the string " + 15px"
the string ")"

6.2. `CSSKeywordValue` normalization

If the provided value can tokenize as an <ident-token>, then a CSSKeywordValue is constructed with the provided value as the keywordValue attribute.