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 {
  readonly 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. Values that can’t yet be directly supported by a CSSStyleValue subclass are also represented as CSSStyleValue objects.

The cssText attribute, on getting, returns a normalized representation (see §5 CSSStyleValue normalization) of the value the CSSStyleValue object represents.

The parse(DOMString property, DOMString cssText), when invoked, must run these steps:

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 converted to ASCII lowercase.
If property is not a supported property name, throw a TypeError and exit this algorithm.
Attempt to parse cssText according to property’s grammar. If this fails, throw a SyntaxError and exit this algorithm. Otherwise, let value be the parsed result.
If property is a list-valued property, subdivide value into a list of CSSStyleValue objects, each representing one list-valued property iteration, and let value be the result.
Return a CSSStyleValue representing value.

3. The `StylePropertyMap`

interface StylePropertyMapReadOnly {
  CSSStyleValue? get(DOMString property);
  sequence<CSSStyleValue> getAll(DOMString property);
  boolean has(DOMString property);
  iterable<DOMString, (CSSStyleValue or sequence<CSSStyleValue>)>;
  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.

The append(DOMString property (CSSStyleValue or DOMString)... values) method, when invoked, must run these steps:

If property does not start with two dashes (U+002D HYPHEN), let property be property converted to ASCII lowercase.
If property is not a supported property name, throw a TypeError and exit this algorithm.
If property is not a list-valued property, throw a TypeError and exit this algorithm.
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.
Let values to append be the empty list.
For each value in values:

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, append value to the end of values to append.

If value is a DOMString,

Parse a CSSStyleValue with property property and value value. If the result is null, throw a TypeError and exit this algorithm. Otherwise, append each list-valued property iteration in the result to the end of values to append.
Append values to append to the end of entry’s list.

The getProperties() 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.

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. `CSSUnparsedValue` objects

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

interface CSSVariableReferenceValue {
  readonly attribute DOMString variable;
  readonly attribute CSSUnparsedValue fallback;
};

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

4.2. `CSSKeywordValue` objects

[Constructor(DOMString)]
interface CSSKeywordValue : CSSStyleValue {
  readonly 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.3. `CSSNumberValue` objects

[Constructor(double), Constructor(DOMString cssText)]
interface CSSNumberValue : CSSStyleValue {
  readonly 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).

4.4. `CSSLengthValue` objects

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

dictionary CSSLengthCalcDictionary {
  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(optional CSSLengthCalcDictionary dictionary);
};

[Constructor(DOMString cssText),
 Constructor(CSSLengthValue),
 Constructor(CSSLengthCalcDictionary)
]
interface CSSCalcLength : CSSLengthValue {
  readonly attribute double? px;
  readonly attribute double? percent;
  readonly attribute double? em;
  readonly attribute double? ex;
  readonly attribute double? ch;
  readonly attribute double? rem;
  readonly attribute double? vw;
  readonly attribute double? vh;
  readonly attribute double? vmin;
  readonly attribute double? vmax;
  readonly attribute double? cm;
  readonly attribute double? mm;
  readonly attribute double? q;
  readonly attribute double? in;
  readonly attribute double? pc;
  readonly 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 {
  readonly 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 CSSUnparsedValue 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(CSSLengthCalcDictionary dictionary): Constructs a CSSCalcLength with units and values as defined by the provided dictionary.

4.5. `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.6. `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(CSSAngleValue angle),
 Constructor(double x, double y, double z, CSSAngleValue angle)]
interface CSSRotation : CSSTransformComponent {
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double z;
  readonly attribute CSSAngleValue angle;
};

[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(CSSAngleValue ax, CSSAngleValue ay)]
interface CSSSkew : CSSTransformComponent {
  readonly attribute CSSAngleValue ax;
  readonly attribute CSSAngleValue ay;
};

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

[Constructor(DOMMatrixReadOnly matrix)]
interface CSSMatrixComponent : 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 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).
CSSMatrixComponent 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.7. `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.8. `CSSResourceValue` objects

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

interface CSSResourceValue : CSSStyleValue {
  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.9. `CSSImageValue` objects

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

[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 the CSSImageValue's state is "loaded", and the resource has an intrinsic width, height, or aspect ratio, then intrinsicWidth, intrinsicHeight, and intrinsicRatio must reflect the resource’s corresponding value. In all other cases, the attributes must be null.

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.10. `CSSFontFaceValue` objects

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

CSSFontFaceValue objects are opaque representations of the contents of @font-face rules. They are used to pass font information into paint image definitions, via custom properties.

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

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

5. `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 REPLACEME. 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.

5.1. `CSSUnparsedValue` 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 CSSUnparsedValue that contains a sequence with:

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

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