CSS Typed OM Level 1

Editor’s Draft,

This version:
https://drafts.css-houdini.org/css-typed-om-1/
Previous Versions:
https://www.w3.org/TR/2016/WD-css-typed-om-1-20160607/
Feedback:
public-houdini@w3.org with subject line “[css-typed-om] … message topic …” (archives)
Issue Tracking:
GitHub
Inline In Spec
Editors:
Tab Atkins-Bittner (Google)

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.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-typed-om” in the title, preferably like this: “[css-typed-om] …summary of comment…”. All issues and comments are archived.

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

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:

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:
  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 parse 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, subdivide value into a list of CSSStyleValue objects, each representing one list-valued property iteration, and let value be the result.

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

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);
};

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 Declared 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:
  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 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.

  7. Append values to append to the end of entry’s list.

To get a value from a StylePropertyMap, run these steps:

write this.

To set a value on a StylePropertyMap, run these steps:

write this.

The update(DOMString property, UpdateFunction updateFunction) method, when invoked, must update a value in a StylePropertyMap with property name property, update function updateFunction, and property map set to the object this method was invoked on .

To update a value in a StylePropertyMap given a property name, update function, and property map, run these steps:
  1. Let old value be the result of running the algorithm to get a value from a StylePropertyMap with property name property name and property map property map.

  2. Let new value be the return value given by invoking the callback update function with a single input of old value.

  3. Run the algorithm to set a value on a StylePropertyMap with property name property name, value new value, and property map property map.

The getProperties() method returns all of the properties listed in the property model. This list of properties is sorted in the following manner:

w3c/css-houdini-drafts/145[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) should refactor out value type-checking, as it’ll be needed by the rest of the setters too
w3c/css-houdini-drafts/147[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) need a robust description of what "a type that property can’t accept" means.
w3c/css-houdini-drafts/148[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) add detailed descriptions of the rest of the methods on StylePropertyMap
w3c/css-houdini-drafts/149[css-typed-om] Describe that StylePropertyMaps are not live objects

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() 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. Declared StylePropertyMap objects

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

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

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 {
  attribute DOMString variable;
  attribute CSSUnparsedValue? fallback;
};

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

They have a [[tokens]] internal slot, which is a list of alternating DOMString and CSSVariableReferenceValue objects. This list is the object’s values to iterate over.

4.2. CSSKeywordValue objects

CSSKeywordValue objects represent CSS keywords and other identifiers.

[Constructor(DOMString value)]
interface CSSKeywordValue : CSSStyleValue {
  attribute DOMString value;
};
The CSSKeywordValue(value) constructor must, when called, perform the following steps:
  1. Parse a component value from value, and let keyword be the result.

  2. If keyword is a syntax error, throw a SyntaxError.

  3. If keyword is anything but an identifier, throw a SyntaxError.

  4. Otherwise, return a new CSSKeywordValue with its value internal slot set to the serialization of keyword.

It’s intentional that this does a CSS parse, rather than just taking the string literally.

Goals are (1) allow .value to round-trip thru the constructor, and (2) allow .value to work when stitched directly into a string that’s then fed to CSS. #2 requires us to have .value contain the appropriate CSS escapes, and #1 then requires us to parse those escapes.

On the other hand, I think this conflicts with the most desirable handling of CSS strings; a CSSStringValue should take the value literally, I think. (Otherwise we have to do some weird things around quotes, I think.) Need to evaluate this holistically.

Possible solution: different behavior between .value and the stringifier.

The value attribute of a CSSKeywordValue this must, on setting a value value, perform the following steps:
  1. Parse a component value from value, and let keyword be the result.

  2. If keyword is a syntax error, throw a SyntaxError.

  3. If keyword is anything but an identifier, throw a SyntaxError.

  4. Otherwise, set this’s internal value slot to the serialization of keyword.

On reading, value must return the serialization of this’s internal value slot.

4.3. Numeric Values:

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

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.

The following code is valid
myElement.styleMap.set("opacity", CSS.number(3));
myElement.styleMap.set("z-index", CSS.number(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).

Note that "numeric values" which incorporate variable references will instead be represented as CSSUnparsedValue objects, and keywords as CSSKeywordValue objects.

4.3.1. Common Numeric Operations, and the CSSNumericValue Superclass

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

interface CSSNumericValue : CSSStyleValue {
  CSSNumericValue add(CSSNumericValue value);
  CSSNumericValue sub(CSSNumericValue value);
  CSSNumericValue mul(double value);
  CSSNumericValue div(double value);

  boolean equals(CSSNumericValue value);

  CSSNumericValue to(DOMString unit);

  static CSSNumericValue parse(DOMString cssText);
};

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:

The add(value) method, when called on a CSSNumericValue this, must perform the following steps:
  1. If this and value are both strongly typed, but to different types, throw a TypeError.

  2. If this and value are both CSSUnitValues: and have the same unit, return a new CSSUnitValue whose unit internal slot is set to this’s unit internal slot, and value internal slot set to the sum of this’s and value’s value internal slots.

  3. Otherwise:

    1. Let newEntries be a copy of this’s map entries.

    2. For each unitval in value’s map entries:

      1. If newEntries[unit] exists, set newEntries[unit] to newEntries[unit] plus val.

      2. Otherwise, set newEntries[unit] to val.

    3. Return a new CSSCalcValue whose map entries are newEntries.

The sub(value) method, when called on a CSSNumericValue this, must perform the following steps:
  1. If this and value are both strongly typed, but to different types, throw a TypeError.

  2. If this and value are both CSSUnitValues: and have the same unit, return a new CSSUnitValue whose unit internal slot is set to this’s unit internal slot, and value internal slot set to the difference of this’s and value’s value internal slots.

  3. Otherwise:

    1. Let newEntries be a copy of this’s map entries.

    2. For each unitval in value’s map entries:

      1. If newEntries[unit] exists, set newEntries[unit] to newEntries[unit] minus val.

      2. Otherwise, set newEntries[unit] to -val.

    3. Return a new CSSCalcValue whose map entries are newEntries.

The mul(value) method, when called on a CSSNumericValue this, must perform the following steps:
  1. If this is a CSSUnitValue, return a new CSSUnitValue whose unit internal slot is set to this’s unit internal slot, and value internal slot set to this’s value internal slot times value.

  2. Otherwise:

    1. Let newEntries be a copy of this’s map entries.

    2. For each unitval in newEntries, set newEntries[unit] to val times value.

    3. Return a new CSSCalcValue whose map entries are newEntries.

The div(value) method, when called on a CSSNumericValue this, must perform the following steps:
  1. If this is a CSSUnitValue, return a new CSSUnitValue whose unit internal slot is set to this’s unit internal slot, and value internal slot set to this’s value internal slot divided by value.

  2. Otherwise:

    1. Let newEntries be a copy of this’s map entries.

    2. For each unitval in newEntries, set newEntries[unit] to val divided by value.

    3. Return a new CSSCalcValue whose map entries are newEntries.

Define equals().
The to(unit) method converts an existing CSSNumericValue this into another one with the specified unit. When called, it must perform the following steps:
  1. If unit does not have a CSS type, throw a SyntaxError and abort this algorithm.

  2. If this is a CSSUnitValue and this’s unit internal slot and unit are compatible units, return a new CSSUnitValue with its unit internal slot set to unit and its value internal slot set to this’s value multiplied by the conversion ratio between the two units.

  3. If this is a CSSCalcValue:

    1. Let sum be 0.

    2. For each oldUnitvalue in this’s map entries:

      1. If oldUnit and unit are not compatible units, throw a TypeError.

      2. Increment sum by value times the conversion ratio between oldUnit and unit.

    3. Return a new CSSUnitValue with its unit internal slot set to unit and its value internal slot set to sum.

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

The parse(cssText) 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. If result is a <dimension-token>, <number-token>, or <percentage-token>, return a new CSSUnitValue object with its value internal slot set to the token’s value, and its value internal slot set to the token’s unit if it’s a <dimension-token>, or "number" if it’s a <number-token>, or "percentage" if it’s a <percentage-token>.

  4. If result is a <calc()>:

    1. Normalize the calc() argument into a sum of values with unique units calcEntries.

    2. Let newEntries be an empty ordered map.

    3. If calcEntries contains a <number> term, set newEntries["number"] to the value of that term.

    4. For each <dimension> term in calcEntries, ordered ASCII case-insensitive alphabetically by their unit, set newEntries[unit] to the term’s value.

    5. If calcEntries contains a <percentage> term, set newEntries["percentage"] to the value of that term.

    6. Return a new CSSCalcValue object with its map entries set to newEntries.

CSSNumericValues can be strongly typed or weakly typed to a type, or untyped.

A CSSUnitValue is weakly typed to its CSS type if that CSS type is "percent" or "number". It’s strongly typed to its CSS type otherwise. It’s never untyped.

A CSSCalcValue is strongly typed if its CSS type set contains a value other than "percent" or "number", to that value. It’s weakly typed if it’s not strongly typed, but its CSS type set is not empty. It’s untyped if its CSS type set is empty.

4.3.2. Value + Unit: CSSUnitValue objects

Numeric values that can be expressed as a single unit (or a naked number or percentage) are represented as CSSUnitValues.

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

[Constructor(double value, DOMString unit)]
  interface CSSUnitValue : CSSNumericValue {
      attribute double value;
      attribute DOMString unit;
      readonly attribute DOMString type;
  };
The CSSUnitValue(value, unit) constructor must, when called, perform the following steps:
  1. If unit does not have a CSS type, throw a SyntaxError and abort this algorithm.

  2. Return a new CSSUnitValue with its value internal slot set to value and its unit set to unit.

The unit attribute of a CSSUnitValue this must, on setting a value unit, perform the following steps:
  1. If unit does not have a CSS type, throw a TypeError.

  2. Otherwise, set this’s unit internal slot to unit.

On reading, it must return the value of this’s unit internal slot.

The type attribute of a CSSUnitValue this must, on reading, return the CSS type of this’s unit.
The CSS type of a string unit is:
unit is "number"

"number"

unit is "percent"

"percent"

unit is a <length> unit

"length"

unit is an <angle> unit

"angle"

unit is a <time> unit

"time"

unit is a <frequency> unit

"frequency"

unit is a <resolution> unit

"resolution"

unit is a <flex> unit

"flex"

anything else

the string does not have a CSS type

A CSSUnitValue matches a CSS type production, such as <number> or <length>, if its equivalent CSS value (with the same value and unit, or similar with "number" and "percent") matches that production.

4.3.3. Complex Numeric Values: CSSCalcValue objects

Numeric values that can only be expressed with a combination of units are represented as CSSCalcValue. This is a Map-like value, where each entry represents the value of one unit, and the object as a whole represents the sum of its units.

For example, the CSS value calc(1em + 5px) will be represented by a CSSCalcValue containing «[ "em" → 1, "px" → 5 ]» .
[Constructor(record<DOMString, double> recordValue)]
interface CSSCalcValue : CSSNumericValue {
    maplike<DOMString, double>;
    CSSCalcValue set(DOMString unit, double value);
    readonly attribute DOMString type;
};
The CSSCalcValue(recordValue) constructor must, when called, perform the following steps:
  1. Let strongType be initially null.

  2. For each unit → value of recordValue:

    1. If unit does not have a CSS type, throw a TypeError.

    2. If unit is a strong type, and strongType is null, let strongType be unit’s CSS type.

    3. If unit is a strong type, and strongType is not equal to that type, throw a TypeError.

  3. Return a new CSSCalcValue whose map entries are recordValue.

When IDL grows a map-iterator concept, add a constructor that takes one. It’s supremely awkward to handle one manually right now.

The set(unit, value) method, when called on a CSSCalcValue this, must perform the following steps:
  1. Let newType be the CSS type of unit. If unit does not have a CSS type, throw a TypeError.

  2. If this has no strong type, or if newType is "percent", "number", or equal to this’s strong type, set the key unit to the value value in this’s map entries, and return this.

  3. Otherwise, throw a TypeError.

The type attribute of a CSSCalcValue this must, on reading, must return the concatenation of the entries in this’s CSS type set, each separated by a U+002D HYPHEN-MINUS (-) character. If there are multiple entries, they must be concatenated in the order: strong type, "percent", "number".

Note: This implies that if the CSS type set is empty (because this is empty), this attribute returns the empty string.

The CSS type set of a CSSCalcValue this is an ordered set that contains the CSS types of every key contained in this’s map entries.

Note: The CSS type set will contain at most 3 entries; "percent", "number", and this CSSCalcValue’s strong type.

A CSSCalcValue has a strong type if its CSS type set contains a value other than "percent" or "number", equal to that other value.

A CSSCalcValue matches a CSS type production, such as <number> or <length-percentage>, if its equivalent CSS calc() value matches that production.

4.3.4. Numeric Factory Functions

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

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);
};
All of the above methods must, when called with a double value, return a new CSSUnitValue whose value internal slot is set to value and whose 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.

For example, rather than creating a new CSSPositionValue with code like:
let pos = new CSSPositionValue(
  new CSSUnitValue(5, "px"),
  new CSSUnitValue(10, "px"));

One can instead write:

let pos = new CSSPositionValue(CSS.px(5), CSS.px(10));

4.4. CSSTransformValue objects

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

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

This should be an Array-like, pending proper resolution of the GitHub issue.

A CSSTransformValue’s values to iterate over is a list of CSSTransformComponents.

The CSSTransformValue(transforms) constructor must, when called, perform the following steps:
  1. Return a new CSSTransformValue whose values to iterate over is transforms.

The is2D attribute of a CSSTransformValue this must, on getting, return true if, for each func in this’s values to iterate over, the func’s is2D attribute would return true; otherwise, the attribute returns false.
The matrix attribute of a CSSTransformValue this must, on getting, perform the following steps:
  1. Let matrix be a 4x4 matrix, initially set to the identity matrix.

  2. For each func in this’s values to iterate over, set matrix to the result of multiplying matrix and func’s equivalent 4x4 transform matrix.

  3. Return a new DOMMatrixReadOnly representing matrix.

interface CSSTransformComponent {
  readonly attribute DOMString cssText;
  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(double x, double y, double z, CSSNumericValue angle)]
interface CSSRotation : CSSTransformComponent {
  attribute double x;
  attribute double y;
  attribute double z;
  attribute CSSNumericValue angle;
};

[Constructor(double x, double y, optional double z)]
interface CSSScale : CSSTransformComponent {
  attribute double x;
  attribute double y;
  attribute double 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)]
interface CSSMatrixComponent : CSSTransformComponent {
  attribute DOMMatrix matrix;
};
Unless otherwise specified, all CSSTransformComponent subclass attributes that have a CSSNumericValue or DOMMatrix type must, on getting, return a new CSSNumericValue or DOMMatrix equivalent to the one stored in the corresponding internal slot.

Unless otherwise specified, they must, on setting, store a new CSSNumericValue or DOMMatrix equivalent to the value being set.

If a CSSTransformComponent’s is2D internal slot is true, the attributes in the following list must, on setting, do nothing; on getting, they must return the value specified in the following list:
CSSTranslation.z

A new CSSUnitValue representing 0px.

CSSRotation.x
CSSRotation.y

The number 0.

CSSRotation.z

The number 1.

CSSScale.z

The number 1.

is2D Design Considerations

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.

The CSSTranslation(x, y, z) constructor must, when invoked, perform the following steps:
  1. If x, y don’t match <length-percentage>, or z (if passed) doesn’t match <length-percentage>, throw a TypeError.

  2. Let this be a new CSSTranslation object, with its internal x and y slots set to new CSSNumericValue objects equivalent to x and y.

  3. If z was passed, set this’s z internal slot to a new CSSNumericValue object equivalent to z, and set this’s is2D internal slot to false.

  4. If z was not passed, set this’s z internal slot to a new CSSNumericValue object representing 0px, and set this’s is2D internal slot to true.

  5. Return this.

The CSSRotation(angle) 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 angle internal slot set to a new CSSNumericValue equivalent to angle, its x and y internal slots set to 0, its z internal slot set to 1, and its is2D internal slot set to true.

The CSSRotation(x, y, z, angle) 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 angle internal slot set to a new CSSNumericValue equivalent to angle, its x, y, z internal slots set to x, y, and z, and its is2D internal slot set to false.

The CSSScale(x, y, z) constructor must, when invoked, perform the following steps:
  1. Let this be a new CSSScale object, with its x and y internal slots set to x and y.

  2. If z was passed, set this’s z internal slot to z, and set this’s is2D internal slot to false.

  3. If z was not passed, set this’s z internal slot to 1, and set this’s is2D internal slot to true.

  4. Return this.

The CSSSkew(ax, ay) 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 ax and ay internal slots set to new CSSNumericValues equivalent to ax and ay, and its is2D internal slot set to true.

The is2D attribute of a CSSSkew object must, on setting, do nothing.

Note: skew() functions always represent 2D transforms.

The CSSPerspective(length) 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 length internal slot set to a new CSSNumericValue equivalent to length, and its is2D internal slot set to false.

The is2D attribute of a CSSPerspective object must, on setting, do nothing.

Note: perspective() functions always represent 3D transforms.

w3c/css-houdini-drafts/366[css-typed-om] What to do with a 2d CSSMatrixComponent set to a 3d DOMMatrix?
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 0px could represent any of the following:

4.5. CSSPositionValue objects

CSSPositionValue objects represent <position> values, used by properties such as background-position.

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

The x attribute expresses the offset from the left edge of the container. y expressions the offset from the top edge of the container.

The CSSPositionValue(x, y) 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 x internal slot is set to x, and whose y internal slot is set to y.

The x and y 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 x or y internal slot, as appropriate, to value.

On reading, the attributes must return the value of the x or y internal slot, as appropriate.

<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:
.example {
  background-position: center bottom 10px;
}

Will produce the following behavior:

let map = document.querySelector('.example').styleMap;

map.get('background-position').x;
// CSSUnitValue(50, "percent")

map.get('background-position').y;
// CSSCalcValue({percent: 100, px: -10})

4.6. 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.7. 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.8. CSSFontFaceValue objects

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

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.

w3c/css-houdini-drafts/159[css-typed-om] Spec up ColorValue

5. CSSStyleValue 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 its cssText set to the CSSOM serialization of the property.

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

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

5.1. Raw CSS tokens: properties with var() references

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.

To normalize a list of component values from a list:
  1. Replace all var() references in list with CSSVariableReferenceValue objects, as described in §5.2 var() References.

  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 [[tokens]] slot is set to list.

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

5.2. var() References

var() references become CSSVariableReferenceValues in the Typed OM.

To normalize a var() reference var:
  1. Let object be a new CSSVariableReferenceValue.

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

  3. If var has a fallback value, set object’s fallback internal slot to the result of normalizing the fallback’s component values. Otherwise, set it to null.

  4. Return object.

5.3. Identifier Values

CSS identifiers become CSSKeywordValues in the Typed OM.

To normalize an identifier ident:
  1. Return a new CSSKeywordValue with its value internal slot set to the serialization of ident.

5.4. <number>, <percentage>, and <dimension> values

CSS <number>, <percentage>, and <dimension> values become CSSUnitValues or CSSCalcValues in the Typed OM.

To normalize a numeric value num:
  1. If num is a calc() expression, normalize a calc() expression from num and return the result.

  2. Return a new CSSUnitValue with its value internal slot set to the numeric value of num, and its 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>.

To normalize a calc() expression num
  1. Simplify num into an equivalent summation of terms with unique units (preserving terms with a zero value).

  2. If num is a computed value and num contains only a single term, normalize a numeric value from that single term and return the result.

  3. Return a CSSCalcValue, whose map entries is an ordered map which contains, in order:

    1. If num contains a <number> term, the entry «[ "number" → val ]», where val is the value of that term.

    2. If num contains any <dimension> terms, the entries «[ unitval ]» for each term, where unit is the term’s unit and val is the term’s value, sorted in ASCII case-insensitive alphabetical order by their unit.

    3. If num contains a <percentage> term, the entry «[ "percent" → val ]», where val is the value of that term.

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 CSSCalcValue with «[ "em" → 2, "px" → 1 ]» , but as a computed value will give a CSSUnitValue something like {unit: "px", value: 33}.

5.5. <transform-list> and <transform-function> values

CSS <transform-list> values become CSSTransformValues in the Typed OM, while CSS <transform-function> values become CSSTransformComponents.

To normalize a <transform-list> list:
  1. Return a new CSSTransformValue whose values to iterate over are the result of mapping the normalize a <transform-function> algorithm over list.

To normalize a <transform-function> func, perform the appropriate set of steps below, based on func:
matrix()
matrix3d()
  1. Return a new CSSMatrixComponent object, whose matrix internal slot is set to a 4x4 matrix representing the same information as func, and whose is2D internal slot is true if func is matrix(), and false otherwise.

translate()
translateX()
translateY()
translate3d()
translateZ()
  1. Return a new CSSTranslation object, whose x, y, and z internal slots are set to the normalization of the specified x/y/z offsets, or the normalization of 0px if not specified in func, and whose 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 x, y, and z internal slots are set to the specified x/y/z scales, or to 1 if not specified in func and whose 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 angle internal slot is set to the normalization of the specified angle, and whose x, y, and z internal slots are set to the specified rotation axis coordinates, or the implicit axis coordinates if not specified in func and whose is2D internal slot is true if func is rotate(), and false otherwise.

skew()
skewX()
skewY()
  1. Return a new CSSSkew object, whose ax and ay internal slots are set to the normalization of the specified x and y angles, or the normalization of 0deg if not specified in func, and whose is2D internal slot is true.

perspective()
  1. Return a new CSSPerspective object, whose length internal slot is set to the normalization of the specified length and whose is2D internal slot is false.

5.6. CSSPositionValue normalization

If the provided value matches the <position> production, then a CSSPositionValue is constructed with x and y 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 x and y to a CSSNumericValue value representing 50%.

  2. If the provided value is a single keyword, length, percentage, or calc expression, then follow the procedure outlined in §5.6.1 Determining x or y from a single value with value given by the provided value and a horizontal bias.

  3. Otherwise, if the provided value consists of a combination of two keywords, then:

    1. follow the procedure outlined in §5.6.1 Determining x or y from a single value with value given by the first keyword and an auto bias.

    2. if bias is horizontal, set it to vertical. Otherwise, set it to horizontal.

    3. follow the procedure again with value given by the second keyword, using the existing bias.

  4. Otherwise, if the provided value consists of a combination of two keywords, lengths, percentages, and calc expressions, then follow the procedure outlined in §5.6.1 Determining x or y from a single value with value given by the first part of the provided value and a horizontal bias, then follow the procedure again with value given by the second part of the provided value and a vertical bias.

  5. Otherwise:

    1. if the provided value starts with a keyword followed by a length, percentage, or calc expression, then follow the procedure outlined in §5.6.2 Determining x or y from a keyword and a length with keyword set to the keyword, length set to the length, percentage, or calc expression, and auto bias.

    2. otherwise, follow the procedure outlined in §5.6.1 Determining x or y from a single value with value set to the first component of the provided value and an auto bias.

    3. if bias is horizontal, set it to vertical. Otherwise, set it to horizontal.

    4. if the remainder of the provided value is a single keyword, length, percentage or calc expression, follow the procedure outlined in §5.6.1 Determining x or y from a single value with value set to the keyword and the existing bias.

    5. 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 §5.6.2 Determining x or y from a keyword and a length with keyword set to the keyword, length set to the length, percentage, or calc expression, and the existing bias.

    6. Otherwise, the process fails.

5.6.1. Determining x or y from a single value

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

  1. If value is the keyword "left" and bias is not vertical, then set x to a CSSNumericValue value representing 0% and bias to horizontal and exit this process.

  2. If value is the keyword "right" and bias is not vertical, then set x to a CSSNumericValue value representing 100% and bias to horizontal and exit this process.

  3. If value is the keyword "top" and bias is not horizontal, then set y to a CSSNumericValue value representing 0% and bias to vertical and exit this process.

  4. If value is the keyword "bottom" and bias is not horizontal, then set y to a CSSNumericValue value representing 100% and bias to vertical and exit this process.

  5. If value matches the <length-percentage> production, then set norm to the result of normalizing |value| as a numeric value. If bias is vertical, set y to norm, otherwise set x to norm and bias to horizontal. Exit this process.

  6. If value is not the keyword "center", then this process fails.

5.6.2. Determining x or y from a keyword and a length

The following process sets a value for either x ory, depending on an input keyword, length, and bias. The process also updates bias based on the keyword and length.

  1. follow the procedure outlined in §5.6.1 Determining x or y from a single value with value given by keyword, using the provided bias

  2. let adjustment be the result of normalizing |length| as a numeric value.

  3. If the keyword is "right" or "bottom", let adjustment be the result of subtracting adjustment from a zero length.

  4. amend x (if bias is horizontal) or y (if bias is vertical) by adding adjustment to it.

5.7. CSSResourceValue normalization

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

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

The string 'url(bike.png)' is converted into a CSSURLImageValue with state set to unloaded and the url set to bike.png. The intrinsicWidth, intrinsicHeight and intrinsicRatio are all set to null.

6. CSSStyleValue 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 matches the CSSOM serialization of the corresponding value.

For example:

var length1 = CSSNumericValue.from("42.0px");
length1.cssText; // "42.0px"

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

element.style.width = "42.0px";
var length3 = element.styleMap.get('width');
length3.cssText; // "42px";

6.1. CSSUnparsedValue 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 + ")"

6.2. CSSKeywordValue Serialization

CSSKeywordValue objects are serialized to their contained value attribute.

6.3. CSSUnitValue Serialization

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

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

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

6.4. CSSCalcValue Serialization

CSSCalcValue objects are serialized into a calc() expression, per the rules in CSS Values 3 §8.1.5 Serialization, treating the object as a summation of all the non-null values it contains.

6.5. CSSTransformValue 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:

6.6. CSSPositionValue Serialization

CSSPositionValue objects are serialized by:

6.7. CSSURLImageValue Serialization

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

6.8. CSSFontFaceValue Serialization

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

7. Security Considerations

There are no known security issues introduced by these features.

8. Privacy Considerations

There are no known privacy issues introduced by these features.

Appendix A: Computed CSSStyleValue 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

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.

For example, a style rule containing:
width: calc(var(--foo) + 10%);

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

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.

For example, a style rule containing:

--foo: var(--bar) black;

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.

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

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

Computed CSSCalcValue objects

During computation, CSSCalcValue objects are reduced accordingly:

  1. All non-number, non-percent values are absolutized into the canonical unit for the object’s associated type.

  2. If the objects contains exactly one of (the canonical unit, a percent value, a number) with a present, non-zero value, then the computed value is an equivalent computed CSSUnitValue.

  3. Otherwise, it’s a CSSCalcValue containing the canonical unit, percent value, and number, if those are present and non-zero, and all other fields are null.

Computed CSSTransformValue objects

During computation, any CSSNumericValue objects referenced by a CSSTransformComponent (e.g. the x attribute of a CSSTranslation) are computed according to Computed CSSUnitValue objects, but the CSSTransformValue object is otherwise as specified.

Computed CSSPositionValue objects

During computation, both the x and y components of a CSSPositionValue are computed according to Computed CSSUnitValue objects.

Computed CSSImageValue objects

Computed CSSImageValue objects are as specified.

Computed CSSFontFaceValue objects

Computed CSSFontFaceValue objects are as specified.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BACKGROUNDS-3]
CSS Backgrounds and Borders Module Level 3 URL: https://www.w3.org/TR/css3-background/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. URL: https://www.w3.org/TR/css-cascade-4/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. URL: https://www.w3.org/TR/css-color-4/
[CSS-GRID-1]
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Grid Layout Module Level 1. URL: https://www.w3.org/TR/css-grid-1/
[CSS-IMAGES-3]
CSS Image Values and Replaced Content Module Level 3 URL: https://www.w3.org/TR/css3-images/
[CSS-LISTS-3]
Tab Atkins Jr.. CSS Lists and Counters Module Level 3. URL: https://www.w3.org/TR/css-lists-3/
[CSS-POSITION-3]
Rossen Atanassov; Arron Eicholz. CSS Positioned Layout Module Level 3. URL: https://www.w3.org/TR/css-position-3/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. URL: https://www.w3.org/TR/css-syntax-3/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. URL: https://www.w3.org/TR/css-transforms-1/
[CSS-TRANSFORMS-2]
CSS Transforms Module Level 2 URL: https://drafts.csswg.org/css-transforms-2/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. URL: https://www.w3.org/TR/css-values-3/
[CSS-VARIABLES-1]
Tab Atkins Jr.. CSS Custom Properties for Cascading Variables Module Level 1. URL: https://www.w3.org/TR/css-variables-1/
[CSSOM-1]
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). URL: https://www.w3.org/TR/cssom-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GEOMETRY-1]
Simon Pieters; Dirk Schulze; Rik Cabanier. Geometry Interfaces Module Level 1. URL: https://www.w3.org/TR/geometry-1/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://www.w3.org/TR/WebIDL-1/

IDL Index

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

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

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);
};

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

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

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

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

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

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

interface CSSNumericValue : CSSStyleValue {
  CSSNumericValue add(CSSNumericValue value);
  CSSNumericValue sub(CSSNumericValue value);
  CSSNumericValue mul(double value);
  CSSNumericValue div(double value);

  boolean equals(CSSNumericValue value);

  CSSNumericValue to(DOMString unit);

  static CSSNumericValue parse(DOMString cssText);
};

[Constructor(double value, DOMString unit)]
  interface CSSUnitValue : CSSNumericValue {
      attribute double value;
      attribute DOMString unit;
      readonly attribute DOMString type;
  };

[Constructor(record<DOMString, double> recordValue)]
interface CSSCalcValue : CSSNumericValue {
    maplike<DOMString, double>;
    CSSCalcValue set(DOMString unit, double value);
    readonly attribute DOMString type;
};

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);
};

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

interface CSSTransformComponent {
  readonly attribute DOMString cssText;
  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(double x, double y, double z, CSSNumericValue angle)]
interface CSSRotation : CSSTransformComponent {
  attribute double x;
  attribute double y;
  attribute double z;
  attribute CSSNumericValue angle;
};

[Constructor(double x, double y, optional double z)]
interface CSSScale : CSSTransformComponent {
  attribute double x;
  attribute double y;
  attribute double 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)]
interface CSSMatrixComponent : CSSTransformComponent {
  attribute DOMMatrix matrix;
};

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

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

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


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


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


Issues Index

write this.
write this.
w3c/css-houdini-drafts/145[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) should refactor out value type-checking, as it’ll be needed by the rest of the setters too
w3c/css-houdini-drafts/147[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) need a robust description of what "a type that property can’t accept" means.
w3c/css-houdini-drafts/148[css-typed-om] When invoking the append(DOMString property (StyleValue or sequence<StyleValue> or DOMString) value) add detailed descriptions of the rest of the methods on StylePropertyMap
w3c/css-houdini-drafts/149[css-typed-om] Describe that StylePropertyMaps are not live objects
It’s intentional that this does a CSS parse, rather than just taking the string literally.

Goals are (1) allow .value to round-trip thru the constructor, and (2) allow .value to work when stitched directly into a string that’s then fed to CSS. #2 requires us to have .value contain the appropriate CSS escapes, and #1 then requires us to parse those escapes.

On the other hand, I think this conflicts with the most desirable handling of CSS strings; a CSSStringValue should take the value literally, I think. (Otherwise we have to do some weird things around quotes, I think.) Need to evaluate this holistically.

Possible solution: different behavior between .value and the stringifier.

Define equals().
When IDL grows a map-iterator concept, add a constructor that takes one. It’s supremely awkward to handle one manually right now.
This should be an Array-like, pending proper resolution of the GitHub issue.
w3c/css-houdini-drafts/366[css-typed-om] What to do with a 2d CSSMatrixComponent set to a 3d DOMMatrix?
Does the loading lifecycle need to be described here?
w3c/css-houdini-drafts/159[css-typed-om] Spec up ColorValue
Better to define a full table of properties and what types they normalize to.
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).