1. Introduction
CSS stylesheets are parsed into abstract UA-internal data structures, the underlying values of CSS, which various specification algorithms manipulate.
Underlying values can’t be directly manipulated, as they are implementation-dependent; UAs have to agree on how to interpret the underlying values, but the values themselves are purposely left undefined so that UAs can store and manipulate CSS in whatever way is most efficient for them.
Previously, the only way to read or write to the underlying values
was via strings—
This specification introduces a new way to interact with underlying values, by representing them with specialized JS objects that can be manipulated and understood more easily and more reliably than string parsing/concatenation. This new approach is both easier for authors (for example, numeric values are reflected with actual JS numbers, and have unit-aware mathematical operations defined for them) and in many cases are more performant, as values can be directly manipulated and then cheaply translated back into underlying values without having to build and then parse strings of CSS.
2. CSSStyleValue
objects
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceCSSStyleValue
{ stringifier; [Exposed=Window] static CSSStyleValue parse(USVStringproperty
, USVStringcssText
); [Exposed=Window] static sequence<CSSStyleValue> parseAll(USVStringproperty
, USVStringcssText
); };
CSSStyleValue
objects are the base class of all CSS values accessible via the Typed OM API.
The stringification behavior of CSSStyleValue
objects
is defined in §6 CSSStyleValue Serialization.
The parse(property, cssText)
method,
when invoked,
must parse a CSSStyleValue with property property, cssText cssText, and parseMultiple set to false,
and return the result.
The parseAll(property, cssText)
,
when invoked,
must parse a CSSStyleValue with property property, cssText cssText, and parseMultiple set to true,
and return the result.
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
Attempt to parse cssText according to property’s grammar. If this fails, throw a
TypeError
. Otherwise, let whole value be the parsed result. -
Subdivide into iterations whole value, according to property, and let values be the result.
-
For each value in values, replace it with the result of reifying value for property.
-
If parseMultiple is false, return values[0]. Otherwise, return values.
-
If property is a single-valued property, return a list containing whole value.
-
Otherwise, divide whole value into individual iterations, as appropriate for property, and return a list containing the iterations in order.
<foo>#
term in the grammar),
but some legacy properties (such as counter-reset)
don’t separate their iterations with commas.
It’s expected to be rigorously defined in the future, but at the moment is explicitly a "you know what we mean" thing.
2.1. Direct CSSStyleValue
Objects
Values that can’t yet be directly supported by a more specialized CSSStyleValue
subclass
are instead represented as CSSStyleValue
objects.
Each CSSStyleValue
object is associated with a particular CSS property,
via its [[associatedProperty]]
internal slot,
and a particular, immutable, underlying value.
These objects are said to "represent" the particular underlying value they were reified from,
such that if they are set back into a stylesheet for the same property,
they reproduce an equivalent underlying value.
These CSSStyleValue
objects are only considered valid for the property that they were parsed for.
This is enforced by CSSStyleValue
objects having a [[associatedProperty]]
internal slot,
which is either null
(the default)
or a string specifying a property name.
Note: This slot is checked by StylePropertyMap
.set()
/append()
3. The StylePropertyMap
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceStylePropertyMapReadOnly
{ iterable<USVString, sequence<CSSStyleValue>>; any get(USVStringproperty
); /* 'any' means (undefined or CSSStyleValue) here, see https://github.com/heycam/webidl/issues/60 */ sequence<CSSStyleValue> getAll(USVStringproperty
); boolean has(USVStringproperty
); readonly attribute unsigned longsize
; }; [Exposed=Window] interfaceStylePropertyMap
: StylePropertyMapReadOnly { void set(USVStringproperty
, (CSSStyleValue or USVString)...values
); void append(USVStringproperty
, (CSSStyleValue or USVString)...values
); void delete(USVStringproperty
); void clear(); };
StylePropertyMap
is an alternate way to represent a CSS declaration block as an object
(when fetched via the [cssom], CSS declaration blocks are instead represented as CSSStyleDeclaration
objects.)
StylePropertyMapReadOnly
object
has a [[declarations]]
internal slot,
which is a map reflecting the CSS declaration block's declarations.
Note: The declarations are not yet defined using [infra] terminology, but for the purpose of this spec it’s assumed to be a map whose keys are strings (representing property names) and whose values are underlying values for those properties.
Unless otherwise stated,
the initial ordering of the [[declarations]]
internal slot
is based on the key of each entry:
-
Standardized properties (not custom properties or vendor-prefixed properties), ASCII-lowercased and then sorted in increasing code-point order.
-
Vendor-prefixed/experimental properties (those whose name starts with a single dash), ASCII-lowercased and then sorted in increasing code-point order.
-
Custom properties, sorted in increasing code-point order. (These are never lower-cased; they are preserved exactly as written.)
StylePropertyMapReadOnly
object this are obtained as follows:
-
Let declarations be this’s
[[declarations]]
slot. -
Let value pairs be an empty list.
-
For each prop → value in declarations:
-
Let iterations be the result of dividing into iterations value.
-
Reify each item of iterations, and let objects be the result.
-
Append prop/objects to value pairs.
-
-
Return value pairs.
Some CSS properties are list-valued properties, such as background-image or animation; their value is a list of parallel grammar terms, almost always comma-separated (the only exceptions are certain legacy properties like counter-reset), indicating multiple distinct "values" interpreted in the same way. Other properties, such as color, are single-valued properties; they take only a single (possibly complex) value.
StylePropertyMap
is a multi-map;
it stores list of values for each key,
but allows you to interact with it as if there was only a single value for each key as well.
This means that multiple values for a single property in a StylePropertyMap
do not represent multiple successive definition of that property’s value;
instead, they represent multiple comma-separated sub-values in a single property value,
like each "layer" in a background-image property.
get(property)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
Let props be the value of this’s
[[declarations]]
internal slot. -
If props[property] exists, subdivide into iterations props[property], then reify the first item of the result and return it.
Otherwise, return
undefined
.
getAll(property)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
Let props be the value of this’s
[[declarations]]
internal slot. -
If props[property] exists, subdivide into iterations props[property], then reify each item of the result, and return the list.
Otherwise, return an empty list.
has(property)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
Let props be the value of this’s
[[declarations]]
internal slot. -
If props[property] exists, return
true
. Otherwise, returnfalse
.
size
attribute,
on getting from a StylePropertyMap
this,
must perform the following steps:
-
Return the size of the value of this’s
[[declarations]]
internal slot.
set(property, ...values)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a [valid CSS property, throw a
TypeError
. -
If property is a single-valued property and values has more than one item, throw a
TypeError
. -
If any of the items in values have a non-null
[[associatedProperty]]
internal slot, and that slot’s value is anything other than property, throw aTypeError
. -
If the size of values is two or more, and one or more of the items are a
CSSUnparsedValue
orCSSVariableReferenceValue
object, throw aTypeError
.Note: When a property is set via string-based APIs, the presence of var() in a property prevents the entire thing from being interpreted. In other words, everything besides the var() is a plain component value, not a meaningful type. This step’s restriction preserves the same semantics in the Typed OM.
-
Let props be the value of this’s
[[declarations]]
internal slot. -
Let values to set be an empty list.
-
For each value in values, create an underlying value for property and value, and append the result to values to set.
-
Set props[property] to values to set.
Note: The property is deleted then added back so that it gets put at the end of the ordered map, which gives the expected behavior in the face of shorthand properties.
append(property, ...values)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
If property is not a list-valued property, throw a
TypeError
. -
If any of the items in values have a non-null
[[associatedProperty]]
internal slot, and that slot’s value is anything other than property, throw aTypeError
. -
If any of the items in values are a
CSSUnparsedValue
orCSSVariableReferenceValue
object, throw aTypeError
.Note: When a property is set via string-based APIs, the presence of var() in a property prevents the entire thing from being interpreted. In other words, everything besides the var() is a plain component value, not a meaningful type. This step’s restriction preserves the same semantics in the Typed OM.
-
Let props be the value of this’s
[[declarations]]
internal slot. -
If props[property] does not exist, set props[property] to an empty list.
-
If props[property] contains a var() reference, throw a
TypeError
. -
Let temp values be an empty list.
-
For each value in values, create an underlying value with property and value, and append the returned value to temp values.
-
Append the entries of temp values to props[property].
delete(property)
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
If property is not a custom property name string, set property to property ASCII lowercased.
-
If property is not a valid CSS property, throw a
TypeError
. -
If this’s
[[declarations]]
internal slot contains property, remove it.
clear()
method,
when called on a StylePropertyMap
this,
must perform the following steps:
-
Remove all of the declarations in this’s
[[declarations]]
internal slot.
CSSStyleValue
value:
- If value is a direct
CSSStyleValue
, -
Return value’s associated value.
- If value is a
CSSStyleValue
subclass, -
If value does not match the grammar of a list-valued property iteration of property, throw a
TypeError
.If any component of property’s CSS grammar has a limited numeric range, and the corresponding part of value is a
CSSUnitValue
that is outside of that range, replace that value with the result of wrapping it in a freshCSSMathSum
whosevalues
internal slot contains only that part of value.Return the value.
- If value is a
USVString
, -
Parse a CSSStyleValue with property property, cssText value, and parseMultiple set to
false
, and return the result.Note: This can throw a
TypeError
instead.
CSSStyleValue
is said to match a CSS production based on the following rules:
-
A
CSSKeywordValue
always matches <ident>. -
A
CSSTransformValue
always matches <transform-list>. -
A
CSSPositionValue
always matches <position>. -
A
CSSNumericValue
matches what its type matches. -
A
CSSURLImageValue
always matches <url>. -
Any subclass of
CSSImageValue
always matches <image>.
A string is a custom property name string if it starts with two dashes (U+002D HYPHEN-MINUS), like --foo
.
(This corresponds to the <custom-property-name> production,
but applies to strings,
rather than identifiers;
it can be used without invoking the CSS parser.)
A string is a valid CSS property if it is a custom property name string, or is a CSS property name recognized by the user agent.
3.1. Computed StylePropertyMapReadOnly
objects
partial interface Element { [SameObject] StylePropertyMapReadOnly computedStyleMap(); };
Computed StylePropertyMap objects
represent the computed values of an Element
,
and are accessed by calling the computedStyleMap()
method.
Every Element
has a [[computedStyleMapCache]]
internal slot,
initially set to null
,
which caches the result of the computedStyleMap()
method
when it is first called.
computedStyleMap()
method must,
when called on an Element
this,
perform the following steps:
-
If this’s
[[computedStyleMapCache]]
internal slot is set tonull
, set its value to a newStylePropertyMapReadOnly
object, whose[[declarations]]
internal slot are the name and computed value of every longhand CSS property supported by the User Agent, every registered custom property, and every non-registered custom property which is not set to its initial value on this, in the standard order.The computed values in the
[[declarations]]
of this object must remain up-to-date, changing as style resolution changes the properties on this and how they’re computed.Note: In practice, since the values are "hidden" behind a
.get()
method call, UAs can delay computing anything until a given property is actually requested. -
Return this’s
[[computedStyleMapCache]]
internal slot.
Note: like Window.getComputedStyle()
,
this method can expose information from stylesheets with the origin-clean flag unset.
Note: The StylePropertyMapReadOnly
returned by this method represents the actual computed values,
not the resolved value concept used by Window.getComputedStyle()
.
It can thus return different values than Window.getComputedStyle()
for some properties (such as width).
Note: Per WG resolution,
pseudo-element styles are intended to be obtainable
by adding this method to the new PseudoElement
interface
(rather than using a pseudoElt
argument like Window.getComputedStyle()
does).
3.2. Declared & Inline StylePropertyMap
objects
partial interface CSSStyleRule { [SameObject] readonly attribute StylePropertyMap styleMap; }; partial interface ElementCSSInlineStyle { [SameObject] readonly attribute StylePropertyMap attributeStyleMap; };
Declared StylePropertyMap objects
represent style property-value pairs embedded in a style rule or inline style,
and are accessed via the styleMap
attribute of CSSStyleRule
objects,
or the attributeStyleMap
attribute
of objects implementing the ElementCSSInlineStyle
interface
(such as Element
s).
When constructed, the [[declarations]]
internal slot for declared StylePropertyMap objects
is initialized to contain an entry
for each property with a valid value inside the CSSStyleRule
or inline style
that the object represents,
in the same order as the CSSStyleRule
or inline style.
4. CSSStyleValue
subclasses
4.1. CSSUnparsedValue
objects
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet),Constructor
(sequence<CSSUnparsedSegment>members
)] interfaceCSSUnparsedValue
: CSSStyleValue { iterable<CSSUnparsedSegment>; readonly attribute unsigned long length; getter CSSUnparsedSegment (unsigned longindex
); setter CSSUnparsedSegment (unsigned longindex
, CSSUnparsedSegmentval
); }; typedef (USVString or CSSVariableReferenceValue)CSSUnparsedSegment
; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(USVStringvariable
, optional CSSUnparsedValue?fallback
= null)] interfaceCSSVariableReferenceValue
{ attribute USVString variable; readonly attribute CSSUnparsedValue?fallback
; };
CSSUnparsedValue
objects represent property values that reference custom properties.
They are comprised of a list of string fragments and variable references.
They have a [[tokens]]
internal slot,
which is a list of USVString
s and CSSVariableReferenceValue
objects.
This list is the object’s values to iterate over.
The length
attribute returns the size of the [[tokens]]
internal slot.
CSSUnparsedValue
this are the integers greater than or equal to 0,
and less than the size of this’s [[tokens]]
internal slot.
To determine the value of an indexed property of a CSSUnparsedValue
this and an index n,
let tokens be this’s [[tokens]]
internal slot,
and return tokens[n].
To set the value of an existing indexed property of a CSSUnparsedValue
this,
an index n,
and a value new value,
let tokens be this’s [[tokens]]
internal slot,
and set tokens[n] to new value.
To set the value of a new indexed property of a CSSUnparsedValue
this,
an index n,
and a value new value,
let tokens be this’s [[tokens]]
internal slot.
If n is not equal to the size of tokens, throw a RangeError
.
Otherwise, append new value to tokens.
variable
attribute
of a CSSVariableReferenceValue
this must return its variable
internal slot.
The variable
attribute
of a CSSVariableReferenceValue
this must, on setting a
variable variable, perform the following steps:
-
If variable is not a custom property name string, throw a
TypeError
. -
Otherwise, set this’s
variable
internal slot to variable.
CSSVariableReferenceValue(variable, fallback)
constructor must,
when called,
perform the following steps:
-
If variable is not a custom property name string, throw a
TypeError
. -
Return a new
CSSVariableReferenceValue
with itsvariable
internal slot set to variable and itsfallback
internal slot set to fallback.
4.2. CSSKeywordValue
objects
CSSKeywordValue
objects represent CSS keywords and other identifiers.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(USVStringvalue
)] interfaceCSSKeywordValue
: CSSStyleValue { attribute USVString value; };
CSSKeywordValue(value)
constructor must,
when called,
perform the following steps:
-
Otherwise, return a new
CSSKeywordValue
with itsvalue
internal slot set to value.
Any place that accepts a CSSKeywordValue
also accepts a raw USVString
,
by using the following typedef and algorithm:
value
attribute of a CSSKeywordValue
this must,
on setting a value value,
perform the following steps:
4.3. Numeric Values:
CSSNumericValue
objects represent CSS values that are numeric in nature
(<number>s, <percentage>s, <dimension>s).
There are two interfaces that inherit from CSSNumericValue
:
-
CSSUnitValue
objects represent values that contain a single unit type (for example "42px"). -
CSSMathValue
objects represent math expressions, which can contain more than one value/unit (for example "calc(56em + 10%)").
CSSNumericValue
objects are not range-restricted.
Any valid numeric value can be represented by a CSSNumericValue
,
and that value will not be clamped, rounded, or rejected
when set on a declared StylePropertyMap.
Instead, clamping and/or rounding will occur during computation of style.
myElement.attributeStyleMap.set("opacity", CSS.number(3)); myElement.attributeStyleMap.set("z-index", CSS.number(15.4)); console.log(myElement.attributeStyleMap.get("opacity").value); // 3 console.log(myElement.attributeStyleMap.get("z-index").value); // 15.4 var computedStyle = myElement.computedStyleMap(); var opacity = computedStyle.get("opacity"); var zIndex = computedStyle.get("z-index");
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: "Numeric values" which incorporate variable references
will instead be represented as CSSUnparsedValue
objects,
and keywords as CSSKeywordValue
objects.
Any place that accepts a CSSNumericValue
also accepts a raw double
,
by using the following typedef and algorithm:
typedef (double or CSSNumericValue) CSSNumberish
;
-
If num is a
CSSNumericValue
, return num. -
If num is a
double
, return a newCSSUnitValue
with itsvalue
internal slot set to num and itsunit
internal slot set to "number".
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.
enumCSSNumericBaseType
{"length"
,"angle"
,"time"
,"frequency"
,"resolution"
,"flex"
,"percent"
, }; dictionaryCSSNumericType
{ longlength
; longangle
; longtime
; longfrequency
; longresolution
; longflex
; longpercent
; CSSNumericBaseTypepercentHint
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceCSSNumericValue
: CSSStyleValue { CSSNumericValue add(CSSNumberish...values
); CSSNumericValue sub(CSSNumberish...values
); CSSNumericValue mul(CSSNumberish...values
); CSSNumericValue div(CSSNumberish...values
); CSSNumericValue min(CSSNumberish...values
); CSSNumericValue max(CSSNumberish...values
); boolean equals(CSSNumberish...value
); CSSUnitValue to(USVStringunit
); CSSMathSum toSum(USVString...units
); CSSNumericType type(); [Exposed=Window] static CSSNumericValue parse(USVStringcssText
); };
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:
add(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item.
-
If this is a
CSSMathSum
object, prepend the items in this’svalues
internal slot to values. Otherwise, prepend this to values. -
If all of the items in values are
CSSUnitValue
s and have the sameunit
, return a newCSSUnitValue
whoseunit
internal slot is set to this’sunit
internal slot, andvalue
internal slot is set to the sum of thevalue
internal slots of the items in values. This addition must be done "left to right" - if values is « 1, 2, 3, 4 », the result must be (((1 + 2) + 3) + 4). (This detail is necessary to ensure interoperability in the presence of floating-point arithmetic.) -
Let type be the result of adding the types of every item in values. If type is failure, throw a
TypeError
. -
Return a new
CSSMathSum
object whosevalues
internal slot is set to values.
sub(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item, then negating the value.
-
Return the result of calling the
add()
internal algorithm with this and values.
CSSNumericValue
this:
-
If this is a
CSSMathNegate
object, return this’svalue
internal slot. -
If this is a
CSSUnitValue
object, return a newCSSUnitValue
with the sameunit
internal slot as this, and avalue
internal slot set to the negation of this’s. -
Otherwise, return a new
CSSMathNegate
object whosevalue
internal slot is set to this.
mul(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item.
-
If this is a
CSSMathProduct
object, prepend the items in this’svalues
internal slot to values. Otherwise, prepend this to values. -
If all of the items in values are
CSSUnitValue
s withunit
internal slot set to "number", return a newCSSUnitValue
whoseunit
internal slot is set to "number", andvalue
internal slot is set to the product of thevalue
internal slots of the items in values.This multiplication must be done "left to right" - if values is « 1, 2, 3, 4 », the result must be (((1 × 2) × 3) × 4). (This detail is necessary to ensure interoperability in the presence of floating-point arithmetic.)
-
If all of the items in values are
CSSUnitValue
s withunit
internal slot set to "number" except one which is set to unit, return a newCSSUnitValue
whoseunit
internal slot is set to unit, andvalue
internal slot is set to the product of thevalue
internal slots of the items in values.This multiplication must be done "left to right" - if values is « 1, 2, 3, 4 », the result must be (((1 × 2) × 3) × 4).
-
Let type be the result of multiplying the types of every item in values. If type is failure, throw a
TypeError
. -
Return a new
CSSMathProduct
object whosevalues
internal slot is set to values.
div(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item, then inverting the value.
-
Return the result of calling the
mul()
internal algorithm with this and values.
CSSNumericValue
this:
-
If this is a
CSSMathInvert
object, return this’svalue
internal slot. -
If this is a
CSSUnitValue
object withunit
internal slot set to "number":-
If this’s
value
internal slot is set to 0 or -0, throw aRangeError
. -
Else return a new
CSSUnitValue
with theunit
internal slot set to "number", and avalue
internal slot set to 1 divided by this’s {CSSUnitValue/value}} internal slot.
-
-
Otherwise, return a new
CSSMathInvert
object whosevalue
internal slot is set to this.
min(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item.
-
If this is a
CSSMathMin
object, prepend the items in this’svalues
internal slot to values. Otherwise, prepend this to values. -
If all of the items in values are
CSSUnitValue
s and have the sameunit
, return a newCSSUnitValue
whoseunit
internal slot is set to this’sunit
internal slot, andvalue
internal slot is set to the minimum of thevalue
internal slots of the items in values. -
Let type be the result of adding the types of every item in values. If type is failure, throw a
TypeError
. -
Return a new
CSSMathMin
object whosevalues
internal slot is set to values.
max(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item.
-
If this is a
CSSMathMax
object, prepend the items in this’svalues
internal slot to values. Otherwise, prepend this to values. -
If all of the items in values are
CSSUnitValue
s and have the sameunit
, return a newCSSUnitValue
whoseunit
internal slot is set to this’sunit
internal slot, andvalue
internal slot is set to the maximum of thevalue
internal slots of the items in values. -
Let type be the result of adding the types of every item in values. If type is failure, throw a
TypeError
. -
Return a new
CSSMathMax
object whosevalues
internal slot is set to values.
equals(...values)
method,
when called on a CSSNumericValue
this,
must perform the following steps:
-
Replace each item of values with the result of rectifying a numberish value for the item.
-
For each item in values, if the item is not an equal numeric value to this, return
false
. -
Return
true
.
CSSMathSum(CSS.px(1), CSS.px(2))
is not equal to CSSMathSum(CSS.px(2), CSS.px(1))
.
This precise notion is used because it allows structural equality to be tested for very quickly; if we were to use a slower and more forgiving notion of equality, such as allowing the arguments to match in any order, we’d probably want to go all the way and perform other simplifications, like considering 96px to be equal to 1in; this looser notion of equality might be added in the future.
CSSNumericValue
s value1 and value2 are equal numeric values,
perform the following steps:
-
If value1 and value2 are not members of the same interface, return
false
. -
If value1 and value2 are both
CSSUnitValue
s, returntrue
if they have equalunit
andvalue
internal slots, orfalse
otherwise. -
If value1 and value2 are both
CSSMathSum
s,CSSMathProduct
s,CSSMathMin
s, orCSSMathMax
s: -
Assert: value1 and value2 are both
CSSMathNegate
s orCSSMathInvert
s. -
Return whether value1’s
value
and value2’svalue
are equal numeric values.
to(unit)
method converts an existing CSSNumericValue
this into another one with the specified unit,
if possible.
When called, it must perform the following steps:
-
Let type be the result of creating a type from unit. If type is failure, throw a
SyntaxError
. -
Let sum be the result of creating a sum value from this. If sum is failure, throw a
TypeError
. -
If sum has more than one item, throw a
TypeError
. Otherwise, let item be the result of creating a CSSUnitValue from the sole item in sum, then converting it to unit. If item is failure, throw aTypeError
. -
Return item.
-
If item has more than one entry in its unit map, return failure.
-
If item has no entries in its unit map, return a new
CSSUnitValue
whoseunit
internal slot is set to "number", and whosevalue
internal slot is set to item’s value. -
Otherwise, item has a single entry in its unit map. If that entry’s value is anything other than
1
, return failure. -
Otherwise, return a new
CSSUnitValue
whoseunit
internal slot is set to that entry’s key, and whosevalue
internal slot is set to item’s value.
toSum(...units)
method converts an existing CSSNumericValue
this into a CSSMathSum
of only CSSUnitValue
s with the specified units,
if possible.
(It’s like to()
,
but allows the result to have multiple units in it.)
If called without any units,
it just simplifies this into a minimal sum of CSSUnitValue
s.
When called, it must perform the following steps:
-
For each unit in units, if the result of creating a type from unit is failure, throw a
SyntaxError
. -
Let sum be the result of creating a sum value from this. If sum is failure, throw a
TypeError
. -
Let values be the result of creating a CSSUnitValue for each item in sum. If any item of values is failure, throw a
TypeError
. -
If units is empty, sort values in code point order according to the
unit
internal slot of its items, then return a newCSSMathSum
object whosevalues
internal slot is set to values. -
Otherwise, let result initially be an empty list. For each unit in units:
-
Let temp initially be a new
CSSUnitValue
whoseunit
internal slot is set to unit and whosevalue
internal slot is set to0
. -
For each value in values:
-
Append temp to result.
-
-
If values is not empty, throw a
TypeError
. this had units that you didn’t ask for. -
Return a new
CSSMathSum
object whosevalues
internal slot is set to result.
type()
method
returns a representation of the type of this.
When called, it must perform the following steps:
-
Let result be a new
CSSNumericType
. -
For each baseType → power in the type of this,
-
If power is not 0, set result[baseType] to power.
-
-
If the percent hint of this is not null,
-
Set
percentHint
to the percent hint of this.
-
-
Return result.
CSSNumericValue
as a sum of numbers with (possibly complex) units.
Not all CSSNumericValue
s can be expressed as a sum value.
A sum value is a list. Each entry in the list is a tuple of a value, which is a number, and a unit map, which is a map of units (strings) to powers (integers).
-
1px becomes
«(1, «["px" → 1]»)»
-
calc(1px + 1in) becomes
«(97, «["px" → 1]»)»
(because in and px are compatible units, and px is the canonical unit for them) -
calc(1px + 2em) becomes
«(1, «["px" → 1]»), (2, «["em" → 1]»)»
-
calc(1px + 2%) becomes
«(1, «["px" → 1]»), (2, «["percent" → 1]»)»
(percentages are allowed to add to other units, but aren’t resolved into another unit, like they are in a type) -
calc(1px * 2em) becomes
«(2, «["em" → 1, "px" → 1]»)»
-
calc(1px + 1deg) can’t be represented as a sum value because it’s an invalid computation
-
calc(1px * 2deg) becomes
«(2, «["deg" → 1, "px" → 1]»)»
To create a sum value from a CSSNumericValue
this,
the steps differ based on this’s class:
CSSUnitValue
-
-
Let unit be the value of this’s
unit
internal slot, and value be the value of this’svalue
internal slot. -
If unit is a member of a set of compatible units, and is not the set’s canonical unit, multiply value by the conversion ratio between unit and the canonical unit, and change unit to the canonical unit.
-
If unit is
"number"
, return «(value, «[ ]»)». -
Otherwise, return
«(value, «[unit → 1]»)»
.
-
CSSMathSum
-
-
Let values initially be an empty list.
-
Create a type from the unit map of each item of values, and add all the types together. If the result is failure, return failure.
-
Return values.
-
CSSMathNegate
-
-
Let values be the result of creating a sum value from this’s
value
internal slot. -
If values is failure, return failure.
-
Return values.
-
CSSMathProduct
-
-
Let values initially be the sum value «(1, «[ ]»)». (I.e. what you’d get from 1.)
-
For each item in this’s
values
internal slot:-
Let new values be the result of creating a sum value from item. Let temp initially be an empty list.
-
If new values is failure, return failure.
-
For each item1 in values:
-
Set values to temp.
-
-
Return values.
-
CSSMathInvert
-
-
Let values be the result of creating a sum value from this’s
value
internal slot. -
If values is failure, return failure.
-
If the length of values is more than one, return failure.
-
Invert (find the reciprocal of) the value of the item in values, and negate the value of each entry in its unit map.
-
Return values.
-
CSSMathMin
-
-
Let args be the result of creating a sum value for each item in this’s
values
internal slot. -
If any item of args is failure, or has a length greater than one, return failure.
-
If not all of the unit maps among the items of args are identical, return failure.
-
Return the item of args whose sole item has the smallest value.
-
CSSMathMax
-
-
Let args be the result of creating a sum value for each item in this’s
values
internal slot. -
If any item of args is failure, or has a length greater than one, return failure.
-
If not all of the unit maps among the items of args are identical, return failure.
-
Return the item of args whose sole item has the largest value.
-
-
Let types be an initially empty list.
-
For each unit → power in unit map:
-
Let type be the result of creating a type from unit.
-
Set type’s sole value to power.
-
Append type to types.
-
-
Return the result of multiplying all the items of types.
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.
parse(cssText)
method,
when called,
must perform the following steps:
-
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. -
If result is not a <number-token>, <percentage-token>, <dimension-token>, or a math function, throw a
SyntaxError
and abort this algorithm. -
Reify a numeric value result, and return the result.
4.3.2. Numeric Value Typing
Each CSSNumericValue
has an associated type,
which is a map of base types to integers,
and an associated percent hint.
The base types are
"length",
"angle",
"time",
"frequency",
"resolution",
"flex",
and "percent".
The ordering of a type’s entries always matches this base type ordering.
The percent hint is either null or a base type other than "percent".
- unit is "number"
-
Return «[ ]» (empty map)
- unit is "percent"
-
Return «[ "percent" → 1 ]»
- unit is a <length> unit
-
Return «[ "length" → 1 ]»
- unit is an <angle> unit
-
Return «[ "angle" → 1 ]»
- unit is a <time> unit
-
Return «[ "time" → 1 ]»
- unit is a <frequency> unit
-
Return «[ "frequency" → 1 ]»
- unit is a <resolution> unit
-
Return «[ "resolution" → 1 ]»
- unit is a <flex> unit
-
Return «[ "flex" → 1 ]»
- anything else
-
Return failure.
In all cases, the associated percent hint is null.
-
Replace type1 with a fresh copy of type1, and type2 with a fresh copy of type2. Let finalType be a new type with an initially empty ordered map and an initially null percent hint.
-
- If both type1 and type2 have non-null percent hints with different values
-
The types can’t be added. Return failure.
- If type1 has a non-null percent hint hint and type2 doesn’t
-
Apply the percent hint hint to type2.
Vice versa if type2 has a non-null percent hint and type1 doesn’t.
- Otherwise
-
Continue to the next step.
-
- If all the entries of type1 with non-zero values are contained in type2 with the same value, and vice-versa
-
Copy all of type1’s entries to finalType, and then copy all of type2’s entries to finalType that finalType doesn’t already contain. Set finalType’s percent hint to type1’s percent hint. Return finalType.
- If type1 and/or type2 contain "percent" with a non-zero value, and type1 and/or type2 contain a key other than "percent" with a non-zero value
-
For each base type other than "percent" hint:
-
Provisionally apply the percent hint hint to both type1 and type2.
-
If, afterwards, all the entries of type1 with non-zero values are contained in type2 with the same value, and vice versa, then copy all of type1’s entries to finalType, and then copy all of type2’s entries to finalType that finalType doesn’t already contain. Set finalType’s percent hint to hint. Return finalType.
-
Otherwise, revert type1 and type2 to their state at the start of this loop.
If the loop finishes without returning finalType, then the types can’t be added. Return failure.
Note: You can shortcut this in some cases by just checking the sum of all the values of type1 vs type2. If the sums are different, the types can’t be added.
-
- Otherwise
-
The types can’t be added. Return failure.
-
If type doesn’t contain hint, set type[hint] to 0.
-
If type contains "percent", add type["percent"] to type[hint], then set type["percent"] to 0.
-
Set type’s percent hint to hint.
-
Replace type1 with a fresh copy of type1, and type2 with a fresh copy of type2. Let finalType be a new type with an initially empty ordered map and an initially null percent hint.
-
If both type1 and type2 have non-null percent hints with different values, the types can’t be multiplied. Return failure.
-
If type1 has a non-null percent hint hint and type2 doesn’t, apply the percent hint hint to type2.
Vice versa if type2 has a non-null percent hint and type1 doesn’t.
-
Copy all of type1’s entries to finalType, then for each baseType → power of type2:
-
If finalType[baseType] exists, increment its value by power.
-
Otherwise, set finalType[baseType] to power.
Set finalType’s percent hint to type1’s percent hint.
-
-
Return finalType.
A type is said to match a CSS production in some circumstances:
-
A type matches <length> if its only non-zero entry is «[ "length" → 1 ]» and its percent hint is null. Similarly for <angle>, <time>, <frequency>, <resolution>, and <flex>.
-
A type matches <percentage> if its only non-zero entry is «[ "percent" → 1 ]».
-
A type matches <length-percentage> if its only non-zero entry is either «[ "length" → 1 ]» or «[ "percentage" → 1 ]» Same for <angle-percentage>, <time-percentage>, etc.
-
A type matches <number> if it has no non-zero entries and its percent hint is null.
-
A type matches <number-percentage> if it has no non-zero entries, or its only non-zero entry is «[ "percentage" → 1 ]».
Many specifications use ''[ <length> | <percentage> ]'' instead of ''<length-percentage>'' in their grammar, and specify in prose that the <length> and <percentage> can be combined. For the purposes of matching, these cases should be treated as <length-percentage>. Similarly for <angle-percentage>, etc.
Note: Types form a semi-group under both addition and a monoid under multiplication (with the multiplicative identity being «[ ]» with a null percent hint), meaning that they’re associative and commutative. Thus the spec can, for example, add an unbounded number of types together unambiguously, rather than having to manually add them pair-wise.
4.3.3. Value + Unit: CSSUnitValue
objects
Numeric values that can be expressed as a single unit
(or a naked number or percentage)
are represented as CSSUnitValue
s.
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"
.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(doublevalue
, USVStringunit
)] interfaceCSSUnitValue
: CSSNumericValue { attribute doublevalue
; readonly attribute USVStringunit
; };
CSSUnitValue(value, unit)
constructor must,
when called,
perform the following steps:
-
If creating a type from unit returns failure, throw a
TypeError
and abort this algorithm. -
Return a new
CSSUnitValue
with itsvalue
internal slot set to value and itsunit
set to unit.
CSSUnitValue
object
with its value
internal slot
set to num,
and its unit
internal slot
set to unit.
(5, "px")
creates an object equivalent to new CSSUnitValue(5, "px")
. Note: This is a spec-internal algorithm, meant simply to make it easier to create unit values in algorithms when needed.
-
Let old unit be the value of this’s
unit
internal slot, and old value be the value of this’svalue
internal slot. -
If old unit and unit are not compatible units, return failure.
-
Return a new
CSSUnitValue
whoseunit
internal slot is set to unit, and whosevalue
internal slot is set to old value multiplied by the conversation ratio between old unit and unit.
4.3.4. Complex Numeric Values: CSSMathValue
objects
Numeric values that are more complicated than a single value+unit
are represented by a tree of CSSMathValue
subclasses,
eventually terminating in CSSUnitValue
objects at the leaf nodes.
The calc(), min(), and max() functions in CSS
are represented in this way.
CSSMathSum
like CSSMathSum(CSS.em(1), CSS.px(5))
.
A more complex expression,
like calc(1em + 5px * 2),
will be represented by a nested structure
like CSSMathSum(CSS.em(1), CSSMathProduct(CSS.px(5), 2))
.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceCSSMathValue
: CSSNumericValue { readonly attribute CSSMathOperator operator; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberish...args
)] interfaceCSSMathSum
: CSSMathValue { readonly attribute CSSNumericArrayvalues
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberish...args
)] interfaceCSSMathProduct
: CSSMathValue { readonly attribute CSSNumericArrayvalues
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberisharg
)] interfaceCSSMathNegate
: CSSMathValue { readonly attribute CSSNumericValuevalue
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberisharg
)] interfaceCSSMathInvert
: CSSMathValue { readonly attribute CSSNumericValuevalue
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberish...args
)] interfaceCSSMathMin
: CSSMathValue { readonly attribute CSSNumericArrayvalues
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberish...args
)] interfaceCSSMathMax
: CSSMathValue { readonly attribute CSSNumericArrayvalues
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceCSSNumericArray
{ iterable<CSSNumericValue>; readonly attribute unsigned long length; getter CSSNumericValue (unsigned longindex
); }; enumCSSMathOperator
{"sum"
,"product"
,"negate"
,"invert"
,"min"
,"max"
, };
Note: CSSMathValue, being a pure superclass, cannot be directly constructed. It exists solely to host the common attributes of all the "math" operations.
operator
attribute
of a CSSMathValue
this must,
on getting,
return the following string,
depending on the interface of this:
CSSMathSum
-
"sum"
CSSMathProduct
-
"product"
CSSMathMin
-
"min"
CSSMathMax
-
"max"
CSSMathNegate
-
"negate"
CSSMathInvert
-
"invert"
Note: These are all instances of the CSSMathOperator
enum.
CSSMathSum(...args)
constructor must,
when called,
perform the following steps:
-
Replace each item of args with the result of rectifying a numberish value for the item.
-
If args is empty, throw a
SyntaxError
. -
Let type be the result of adding the types of all the items of args. If type is failure, throw a
TypeError
. -
Return a new
CSSMathSum
whosevalues
internal slot is set to args.
The CSSMathMin(...args)
and CSSMathMax(...args)
constructors
are defined identically to the above,
except that in the last step
they return a new CSSMathMin
or CSSMathMax
object,
respectively.
The CSSMathProduct(...args)
constructor
is defined identically to the above,
except that in step 3 it multiplies the types instead of adding,
and in the last step
it returns a CSSMathProduct
.
CSSMathNegate(arg)
constructor must,
when called,
perform the following steps:
-
Replace arg with the result of rectifying a numberish value for arg.
-
Return a new
CSSMathNegate
whosevalue
internal slot is set to arg.
The CSSMathInvert(arg)
constructor
is defined identically to the above,
except that in the last step
it returns a new CSSMathInvert
object.
CSSMathSum
CSSMathMin
CSSMathMax
-
The type is the result of adding the types of each of the items in its
values
internal slot. CSSMathProduct
-
The type is the result of multiplying the types of each of the items in its
values
internal slot. CSSMathNegate
-
The type is the same as the type of its
value
internal slot. CSSMathInvert
-
The type is the same as the type of its
value
internal slot, but with all values negated.
The length
attribute of CSSNumericArray
indicates how many CSSNumericValue
s are contained within the CSSNumericArray
.
The indexed getter of CSSNumericArray
retrieves the CSSNumericValue
at the provided index.
4.3.5. 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 { CSSUnitValuenumber
(doublevalue
); CSSUnitValuepercent
(doublevalue
); // <length> CSSUnitValueem
(doublevalue
); CSSUnitValueex
(doublevalue
); CSSUnitValuech
(doublevalue
); CSSUnitValueic
(doublevalue
); CSSUnitValuerem
(doublevalue
); CSSUnitValuelh
(doublevalue
); CSSUnitValuerlh
(doublevalue
); CSSUnitValuevw
(doublevalue
); CSSUnitValuevh
(doublevalue
); CSSUnitValuevi
(doublevalue
); CSSUnitValuevb
(doublevalue
); CSSUnitValuevmin
(doublevalue
); CSSUnitValuevmax
(doublevalue
); CSSUnitValuecm
(doublevalue
); CSSUnitValuemm
(doublevalue
); CSSUnitValueQ
(doublevalue
); CSSUnitValuein
(doublevalue
); CSSUnitValuept
(doublevalue
); CSSUnitValuepc
(doublevalue
); CSSUnitValuepx
(doublevalue
); // <angle> CSSUnitValuedeg
(doublevalue
); CSSUnitValuegrad
(doublevalue
); CSSUnitValuerad
(doublevalue
); CSSUnitValueturn
(doublevalue
); // <time> CSSUnitValues
(doublevalue
); CSSUnitValuems
(doublevalue
); // <frequency> CSSUnitValueHz
(doublevalue
); CSSUnitValuekHz
(doublevalue
); // <resolution> CSSUnitValuedpi
(doublevalue
); CSSUnitValuedpcm
(doublevalue
); CSSUnitValuedppx
(doublevalue
); // <flex> CSSUnitValuefr
(doublevalue
); };
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.
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 CSSTransformComponent
s,
which represent individual <transform-function> values.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(sequence<CSSTransformComponent>transforms
)] interfaceCSSTransformValue
: CSSStyleValue { iterable<CSSTransformComponent>; readonly attribute unsigned long length; getter CSSTransformComponent (unsigned longindex
); setter CSSTransformComponent (unsigned longindex
, CSSTransformComponentval
); readonly attribute boolean is2D; DOMMatrix toMatrix(); };
A CSSTransformValue
’s values to iterate over is a list of CSSTransformComponent
s.
CSSTransformValue(transforms)
constructor must,
when called,
perform the following steps:
-
Return a new
CSSTransformValue
whose values to iterate over is transforms.
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
. toMatrix()
method of a CSSTransformValue
this must,
when called,
perform the following steps:
-
Let matrix be a new
DOMMatrix
, initialized to the identity matrix, with itsis2D
internal slot set totrue
. -
For each func in this’s values to iterate over:
-
Let funcMatrix be the
DOMMatrix
returned by callingtoMatrix()
on func. -
Set matrix to the result of multiplying matrix and the matrix represented by funcMatrix.
-
-
Return matrix.
The length
attribute indicates how many transform components are contained within the CSSTransformValue
.
They have a [[values]]
internal slot,
which is a list of CSSTransformComponent
objects.
This list is the object’s values to iterate over.
CSSTransformValue
this are the integers greater than or equal to 0,
and less than the size of this’s [[values]]
internal slot.
To determine the value of an indexed property of a CSSTransformValue
this and an index n,
let values be this’s [[values]]
internal slot,
and return values[n].
To set the value of an existing indexed property of a CSSTransformValue
this,
an index n,
and a value new value,
let values be this’s [[values]]
internal slot,
and set values[n] to new value.
To set the value of a new indexed property of a CSSTransformValue
this,
an index n,
and a value new value,
let values be this’s [[values]]
internal slot.
If n is not equal to the size of values, throw a RangeError
.
Otherwise, append new value to values.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)] interfaceCSSTransformComponent
{ stringifier; attribute boolean is2D; DOMMatrix toMatrix(); }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValuex
, CSSNumericValuey
, optional CSSNumericValuez
)] interfaceCSSTranslate
: CSSTransformComponent { attribute CSSNumericValuex
; attribute CSSNumericValuey
; attribute CSSNumericValuez
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValueangle
), Constructor(CSSNumberishx
, CSSNumberishy
, CSSNumberishz
, CSSNumericValueangle
)] interfaceCSSRotate
: CSSTransformComponent { attribute CSSNumberish x; attribute CSSNumberish y; attribute CSSNumberish z; attribute CSSNumericValueangle
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumberishx
, CSSNumberishy
, optional CSSNumberishz
)] interfaceCSSScale
: CSSTransformComponent { attribute CSSNumberish x; attribute CSSNumberish y; attribute CSSNumberish z; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValueax
, CSSNumericValueay
)] interfaceCSSSkew
: CSSTransformComponent { attribute CSSNumericValueax
; attribute CSSNumericValueay
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValueax
)] interfaceCSSSkewX
: CSSTransformComponent { attribute CSSNumericValueax
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValueay
)] interfaceCSSSkewY
: CSSTransformComponent { attribute CSSNumericValueay
; }; /* Note that skew(x,y) is *not* the same as skewX(x) skewY(y), thus the separate interfaces for all three. */ [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValuelength
)] interfaceCSSPerspective
: CSSTransformComponent { attribute CSSNumericValuelength
; }; [Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(DOMMatrixReadOnlymatrix
, optional CSSMatrixComponentOptionsoptions
)] interfaceCSSMatrixComponent
: CSSTransformComponent { attribute DOMMatrixmatrix
; }; dictionaryCSSMatrixComponentOptions
{ booleanis2D
; };
is2D
attribute
indicates whether the transform is 2D or 3D.
When it’s true
,
the attributes of the transform that are relevant to 3D transforms
(such as the CSSTranslate.z
attribute)
simply have no effect on the transform they represent.
Note: This affects the serialization of the object, and concepts such as the object’s "equivalent 4x4 matrix".
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—
toMatrix()
method of a CSSTransformComponent
this must,
when called,
perform the following steps:
-
Let matrix be a new
DOMMatrix
object, initialized to this’s equivalent 4x4 transform matrix, as defined in CSS Transforms 1 §15 Mathematical Description of Transform Functions, and with itsis2D
internal slot set to the same value as this’sis2D
internal slot.Note: Recall that the
is2D
flag affects what transform, and thus what equivalent matrix, aCSSTransformComponent
represents.As the entries of such a matrix are defined relative to the px unit, if any <length>s in this involved in generating the matrix are not compatible units with px (such as relative lengths or percentages), throw a
TypeError
. -
Return matrix.
CSSTranslate(x, y, z)
constructor must,
when invoked,
perform the following steps:
-
If x or y don’t match <length-percentage>, throw a
TypeError
. -
If z was passed, but doesn’t match <length>, throw a
TypeError
. -
Let this be a new
CSSTranslate
object, with itsx
andy
internal slots set to x and y. -
If z was passed, set this’s
z
internal slot to z, and set this’sis2D
internal slot tofalse
. -
If z was not passed, set this’s
z
internal slot to new unit value of(0, "px")
, and set this’sis2D
internal slot totrue
. -
Return this.
CSSRotate(angle)
constructor must,
when invoked,
perform the following steps:
CSSRotate(x, y, z, angle)
constructor must,
when invoked,
perform the following steps:
x
, y
, and z
attributes must,
on setting to a new value val, rectify a numberish value from val and set the corresponding internal slot to the result of that. CSSScale(x, y, z)
constructor must,
when invoked,
perform the following steps:
-
Let x, y, and z (if passed) be replaced by the result of rectifying a numberish value.
-
If x, y, or z (if passed) don’t match <number>, throw a
TypeError
. -
Let this be a new
CSSScale
object, with itsx
andy
internal slots set to x and y. -
If z was passed, set this’s
z
internal slot to z, and set this’sis2D
internal slot tofalse
. -
If z was not passed, set this’s
z
internal slot to a new unit value of(1, "number")
, and set this’sis2D
internal slot totrue
. -
Return this.
x
, y
, and z
attributes must,
on setting to a new value val, rectify a numberish value from val and set the corresponding internal slot to the result of that. CSSSkew(ax, ay)
constructor must,
when invoked,
perform the following steps:
CSSSkewX(ax)
constructor must,
when invoked,
perform the following steps:
CSSSkewY(ay)
constructor must,
when invoked,
perform the following steps:
is2D
attribute
of a CSSSkew
, CSSSkewX
, or CSSSkewY
object must,
on setting,
do nothing.
Note: skew(), skewX(), and skewY() functions always represent 2D transforms.
CSSPerspective(length)
constructor must,
when invoked,
perform the following steps:
is2D
attribute of a CSSPerspective
object must,
on setting,
do nothing.
Note: perspective() functions always represent 3D transforms.
CSSMatrixComponent(matrix, options)
constructor must,
when invoked,
perform the following steps:
CSSTransformComponent
can correspond to
one of a number of underlying transform functions.
For example, a CSSTranslate
with an x value of 10px and y & z values of 0px could represent any of the following:
-
translate(10px)
-
translate(10px, 0)
-
translateX(10px)
-
translate3d(10px, 0, 0)
When stringified, however,
it will always print out either translate(10px, 0px) or translate3d(10px, 0px, 0px),
depending on whether its is2D
internal slot
is true
or false
,
respectively.
4.5. CSSPositionValue
objects
CSSPositionValue
objects represent <position> values,
used by properties such as object-position.
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet), Constructor(CSSNumericValuex
, CSSNumericValuey
)] interfaceCSSPositionValue
: CSSStyleValue { attribute CSSNumericValue x; attribute CSSNumericValue y; };
The x
attribute expresses the offset from the left edge of the container; y
expresses the offset from the top edge of the container.
CSSPositionValue(x, y)
constructor must,
when called,
perform the following steps:
-
If x or y doesn’t match <length-percentage>, throw a
TypeError
. -
Otherwise, return a new
CSSPositionValue
whosex
internal slot is set to x, and whosey
internal slot is set to y.
x
and y
attribute of a CSSPositionValue
this must,
on setting a value value,
perform the following steps:
-
If value doesn’t match <length-percentage>, throw a
TypeError
. -
Otherwise, set this’s
x
ory
internal slot, as appropriate, to value.
On reading, the attributes must return the value of the x
or y
internal slot,
as appropriate.
.example { object-position: center bottom 10px; }
Will produce the following behavior:
let map = document.querySelector('.example').computedStyleMap(); map.get('object-position').x; // CSS.percent(50) map.get('object-position').y; // CSSMathSum(CSS.percent(100), CSS.px(-10))
4.6. CSSImageValue
objects
[Exposed=(Window, Worker, PaintWorklet, LayoutWorklet)]
interface CSSImageValue
: CSSStyleValue {
};
CSSImageValue
objects represent values for properties that take <image> productions,
for example background-image, list-style-image, and border-image-source.
Note: This object is intentionally opaque, and exposes no details of what kind of image it contains, or any aspect of the image. This is because having something to represent images is necessary for Custom Paint, but there are sufficient complexities in getting URL-handling and loading specified firmly that it’s not realistically possible to specify in the timeline of this specification. This will be expanded on in future levels.
If a CSSImageValue
object represents an <image> that involves a URL
(such as url() or image()),
the handling of such values is identical to how CSS currently handles them.
In particular, resolving relative URLs or fragment URLs
has the same behavior as in normal CSS.
style
element or style
attribute).
This resolution doesn’t happen eagerly at parse-time,
but at some currently-unspecified point during value computation.
Thus, if an element’s style is set to background-image: url(foo);, and that specified value is extracted via the Typed OM and then set on an element in a different document, both the source and destination elements will resolve the URL differently, as they provide different base URLs.
On the other hand,
if the extracted value was a computed value (from computedStyleMap()
),
then it would already be resolved to an absolute URL,
and thus would act identically no matter where you later set it to.
(Unless it was a fragment URL,
which CSS treats differently and never fully resolves,
so it always resolves against the current document.)
5. CSSStyleValue
Reification
This section describes how Typed OM objects are constructed from underlying values, a process called reification.
The following list defines the reification behavior for every single property in CSS, for both specified and computed values.
If an underlying value is from a list-valued property,
this list defines how to reify a single iteration of the property;
multiple iterations are reflected by returning multiple values from StylePropertyMap
.getAll()
.
If an underlying value contains a var() reference, then it is reified by reifying a list of component values, regardless of what property it is for.
- unregistered custom properties
-
For both specified and computed values, reify a list of component values from the value, and return the result.
- registered custom properties [css-properties-values-api-1]
- align-content
- align-items
-
For both specified and computed values:
-
If the value is normal or stretch, reify an identifier from the value and return the result.
-
If the value is baseline or first baseline,, reify an identifier "baseline" and return the result.
-
If the value is a <self-position> with no <overflow-position>, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- align-self
-
For both specified and computed values:
-
If the value is auto, normal, or stretch, reify an identifier from the value and return the result.
-
If the value is baseline or first baseline,, reify an identifier "baseline" and return the result.
-
If the value is a <self-position> with no <overflow-position>, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- alignment-baseline
-
For both specified and computed values, reify an identifier from the value and return the result.
- all
-
For both specified and computed values, reify an identifier from the value and return the result.
- animation-composition
-
For both specified and computed values, reify an identifier from the value and return the result.
- appearance
-
For both specified and computed values, reify an identifier from the value and return the result.
- azimuth
-
- For specified values:
-
-
If the value is an <angle>, reify a numeric value from the value and return the result.
-
If the value is a single keyword, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- For computed values:
-
Reify a numeric value from the angle and return the result.
- backdrop-filter
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- backface-visibility
-
For both specified and computed values, reify an identifier from the value and return the result.
- background
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - background-attachment
-
For both specified and computed values, reify an identifier from the value and return the result.
- background-blend-mode
-
For both specified and computed values, reify an identifier from the value and return the result.
- background-clip
-
For both specified and computed values, reify an identifier from the value and return the result.
- background-color
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - background-image
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
If the value is a url() function, reify a url from the value and return the result.
-
Otherwise, reify an image from the value and return the result.
-
- background-image-transform
-
For both specified and computed values, reify an identifier from the value and return the result.
- background-position
-
For both specified and computed values, reify a position from the value and return the result.
- background-repeat
-
For both specified and computed values:
-
If the value is a single keyword, or the same keyword repeated twice, reify an identifier from the keyword and return the result.
-
If the value is repeat no-repeat, reify an identifier "repeat-x" and return the result.
-
If the value is no-repeat repeat, reify an identifier "repeat-y" and return the result.
-
Otherwise, reify to a
CSSStyleValue
and return the result.
-
- baseline-shift
-
For both specified and computed values:
-
If the value is sub or super, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- block-size
-
Same as for width
- block-step
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - block-step-align
-
For both specified and computed values, reify an identifier from the value and return the result.
- block-step-insert
-
For both specified and computed values, reify an identifier from the value and return the result.
- block-step-round
-
For both specified and computed values, reify an identifier from the value and return the result.
- block-step-size
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- bookmark-label
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - bookmark-level
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- bookmark-state
-
For both specified and computed values, reify an identifier from the value and return the result.
- border
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-block
-
Same as border-block-start
- border-block-color
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-block-end
-
Same as border-block-start
- border-block-end-color
-
Same as border-top-color
- border-block-end-style
-
Same as border-top-style
- border-block-end-width
-
Same as border-top-width
- border-block-start
-
Same as border-top
- border-block-start-color
-
Same as border-top-color
- border-block-start-style
-
Same as border-top-style
- border-block-start-width
-
Same as border-top-width
- border-block-style
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-block-width
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-bottom
-
Same as border-top
- border-bottom-color
-
Same as border-top-color
- border-bottom-style
-
Same as border-top-style
- border-bottom-width
-
Same as border-top-width
- border-boundary
-
For both specified and computed values, reify an identifier from the value and return the result.
- border-collapse
-
For both specified and computed values, reify an identifier from the value and return the result.
- border-color
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-image-transform
-
For both specified and computed values, reify an identifier from the value and return the result.
- border-inline
- border-inline-color
- border-inline-end
- border-inline-end-color
- border-inline-end-style
- border-inline-end-width
- border-inline-start
- border-inline-start-color
- border-inline-start-style
- border-inline-start-width
- border-inline-style
- border-inline-width
- border-left
-
Same as border-top
- border-left-color
-
Same as border-top-color
- border-left-style
-
Same as border-top-style
- border-left-width
-
Same as border-top-width
- border-radius
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-right
-
Same as border-top
- border-right-color
-
Same as border-top-color
- border-right-style
-
Same as border-top-style
- border-right-width
-
Same as border-top-width
- border-spacing
- border-style
- border-top
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - border-top-color
-
For both specified and computed values:
-
If the value is currentcolor, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- border-top-style
-
For both specified and computed values, reify an identifier from the value and return the result.
- border-top-width
-
For both specified and computed values:
-
If the value is a <length>, reify a numeric value from the value and return the result.
-
Otherwise, reify an identifier from the value and return the result.
-
- border-width
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - bottom
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- box-decoration-break
- box-sizing
-
For both specified and computed values, reify an identifier from the value and return the result.
- box-snap
- break-after
- break-before
- break-inside
- caption-side
- caret
- caret-color
-
For both specified and computed values:
-
If the value is currentcolor, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- caret-shape
- clear
-
For both specified and computed values, reify an identifier from the value and return the result.
- clip
- clip-path
- clip-rule
- color
-
For both specified and computed values:
-
If the value is currentcolor, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- color-adjust
- color-interpolation
- color-rendering
- column-gap
- column-span
- contain
- content
- continue
- copy-into
- counter-increment
- counter-reset
- counter-set
- cue
- cue-after
- cue-before
- cursor
- cx
- cy
- d
- direction
-
For both specified and computed values, reify an identifier from the value and return the result.
- display
-
For both specified and computed values, reify an identifier from the value and return the result.
- dominant-baseline
- elevation
- empty-cells
-
For both specified and computed values, reify an identifier from the value and return the result.
- fill
- fill-break
- fill-color
- fill-image
- fill-opacity
- fill-origin
- fill-position
- fill-repeat
- fill-rule
- fill-size
- 'filter-margin-top, filter-margin-right, filter-margin-bottom, filter-margin-left'
- flex
- flex-basis
- flex-direction
- flex-flow
- flex-grow
- flex-shrink
- flex-wrap
- float
-
For both specified and computed values, reify an identifier from the value and return the result.
- float-defer
- font
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - font-family
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - font-language-override
-
For both specified and computed values:
-
If the value is normal, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- font-max-size
-
For both specified and computed values:
-
If the value is an <absolute-size>, <relative-size> or infinity, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- font-min-size
-
Same as font-size
- font-optical-sizing
-
For both specified and computed values, reify an identifier from the value and return the result.
- font-palette
-
For both specified and computed values:
-
If the value is normal, light or dark, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- font-presentation
-
For both specified and computed values, reify an identifier from the value and return the result.
- font-size
-
For both specified and computed values:
-
If the value is an <absolute-size> or <relative-size>, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- font-size-adjust
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- font-stretch
-
For both specified and computed values:
-
If the value is a <percentage>, reify a numeric value from the value and return the result.
-
Otherwise, reify an identifier from the value and return the result.
-
- font-style
-
For both specified and computed values, reify an identifier from the value and return the result.
- font-synthesis
-
For both specified and computed values:
-
If the value is none, weight, style or small-caps, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- font-variant
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - font-variant-alternates
-
For both specified and computed values:
-
If the value is none or historical-forms, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- font-variant-emoji
-
For both specified and computed values, reify an identifier from the value and return the result.
- font-variation-settings
-
For both specified and computed values:
-
If the value is normal, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- font-weight
-
For both specified and computed values:
-
If the value is a <number>, reify a numeric value from the value and return the result.
-
Otherwise, reify an identifier from the value
-
- gap
- globalcompositeoperation
- glyph-orientation-vertical
- grid
- grid-area
- grid-auto-columns
- grid-auto-flow
- grid-auto-rows
- grid-column
- grid-column-end
- grid-column-gap
- grid-column-start
- grid-gap
- grid-row
- grid-row-end
- grid-row-gap
- grid-row-start
- grid-template
- grid-template-areas
- grid-template-columns
- grid-template-rows
- height
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
If the value is a <length> or <percentage>, reify a numeric value from the value and return the result.
-
- image-rendering
- image-resolution
- initial-letter
- initial-letter-align
- initial-letter-wrap
- inline-size
- inset
- inset-block
- inset-block-end
- inset-block-start
- inset-inline
- inset-inline-end
- inset-inline-start
- isolation
- justify-content
- justify-items
- justify-self
- left
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- letter-spacing
- line-grid
- line-height
-
For both specified and computed values:
-
If the value is normal, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- line-height-step
- line-snap
- list-style
- list-style-image
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
If the value is a url() function, reify a url from the value and return the result.
-
Otherwise, reify an image from the value and return the result.
-
- list-style-position
-
For both specified and computed values, reify an identifier from the value and return the result.
- list-style-type
- margin
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - margin-block
- margin-block-end
- margin-block-start
- margin-bottom
-
Same as margin-top
- margin-inline
- margin-inline-end
- margin-inline-start
- margin-left
-
Same as margin-top
- margin-right
-
Same as margin-top
- margin-top
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- marker
- marker-end
- marker-mid
- marker-side
- marker-start
- mask
- mask-border
- mask-border-mode
- mask-border-outset
- mask-border-repeat
- mask-border-slice
- mask-border-source
- mask-border-width
- mask-clip
- mask-composite
- mask-image
-
For both specified and computed values:
-
If the value is none, reify an identifier from the value and return the result.
-
Otherwise, reify an image from the value and return the result.
-
- mask-mode
- mask-origin
- mask-position
- mask-repeat
- mask-size
- mask-type
- max-block-size
- max-height
- max-inline-size
- max-lines
- max-width
- min-block-size
- min-height
- min-inline-size
- min-width
- mix-blend-mode
- nav-down
- nav-left
- nav-right
- nav-up
- object-fit
- offset
- offset-after
- offset-anchor
- offset-before
- offset-distance
- offset-end
- offset-path
- offset-position
- offset-rotate
- offset-start
- opacity
-
For both specified and computed values, reify a numeric value from the value and return the result.
- order
- orphans
- outline
- outline-color
-
For both specified and computed values:
-
If the value is currentcolor, reify an identifier from the value and return the result.
-
Otherwise, reify as a
CSSStyleValue
and return the result.
-
- outline-offset
- outline-style
-
For both specified and computed values, reify an identifier from the value and return the result.
- outline-width
- overflow
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - overflow-anchor
-
For both specified and computed values, reify an identifier from the value and return the result.
- overflow-x
-
For both specified and computed values, reify an identifier from the value and return the result.
- overflow-y
-
For both specified and computed values, reify an identifier from the value and return the result.
- padding
-
For both specified and computed values, reify as a
CSSStyleValue
and return the result. - padding-block
- padding-block-end
- padding-block-start
- padding-bottom
-
Same as padding-top
- padding-inline
- padding-inline-end
- padding-inline-start
- padding-left
-
Same as padding-top
- padding-right
-
Same as padding-top
- padding-top
-
For both specified and computed values, reify a numeric value from the value and return the result.
- page
- page-break-after
- page-break-before
- page-break-inside
- paint-order
- pause
- pause-after
- pause-before
- perspective
- perspective-origin
- pitch
- pitch-range
- place-content
- place-items
- place-self
- play-during
- pointer-events
- position
-
For both specified and computed values, reify an identifier from the value and return the result.
- presentation-level
- quotes
- r
- region-fragment
- resize
-
For both specified and computed values, reify an identifier from the value and return the result.
- rest
- rest-after
- rest-before
- richness
- right
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- rotate
- row-gap
- ruby-align
- ruby-merge
- ruby-position
- rx
- ry
- scale
- scroll-behavior
- scroll-margin
- scroll-margin-block
- scroll-margin-block-end
- scroll-margin-block-start
- scroll-margin-bottom
- scroll-margin-inline
- scroll-margin-inline-end
- scroll-margin-inline-start
- scroll-margin-left
- scroll-margin-right
- scroll-margin-top
- scroll-padding
- scroll-padding-block
- scroll-padding-block-end
- scroll-padding-block-start
- scroll-padding-bottom
- scroll-padding-inline
- scroll-padding-inline-end
- scroll-padding-inline-start
- scroll-padding-left
- scroll-padding-right
- scroll-padding-top
- scroll-snap-align
- scroll-snap-stop
- scroll-snap-type
- scrollbar-3dlight-color
- scrollbar-arrow-color
- scrollbar-base-color
- scrollbar-darkshadow-color
- scrollbar-face-color
- scrollbar-gutter
- scrollbar-highlight-color
- scrollbar-shadow-color
- scrollbar-track-color
- shape-inside
- shape-margin
- shape-padding
- shape-rendering
- shape-subtract
- size
- solid-color
- solid-opacity
- speak
- speak-as
- speak-header
- speak-numeral
- speak-punctuation
- speech-rate
- stop-color
- stop-opacity
- stress
- stroke
- stroke-align
- stroke-break
- stroke-color
- stroke-dash-corner
- stroke-dash-justify
- stroke-dasharray
- stroke-dashoffset
- stroke-image
- stroke-linecap
- stroke-linejoin
- stroke-miterlimit
- stroke-opacity
- stroke-origin
- stroke-position
- stroke-repeat
- stroke-size
- stroke-width
- table-layout
- text-align
-
For both specified and computed values, reify an identifier from the value and return the result.
- text-anchor
- text-combine-upright
- text-decoration
- text-decoration-fill
- text-decoration-skip
- text-decoration-skip-ink
- text-decoration-stroke
- text-decoration-width
- text-emphasis-skip
- text-indent
- text-orientation
- text-overflow
- text-rendering
- text-size-adjust
- text-transform
-
For both specified and computed values, reify an identifier from the value and return the result.
- text-underline-offset
- top
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- transform-style
- transition
- transition-delay
- transition-duration
- transition-property
- transition-timing-function
- translate
- unicode-bidi
- user-select
- vector-effect
- vertical-align
-
For both specified and computed values:
-
If the value is baseline, reify an identifier from the value and return the result.
-
Otherwise, reify a numeric value from the value and return the result.
-
- visibility
-
For both specified and computed values, reify an identifier from the value and return the result.
- voice-balance
- voice-duration
- voice-family
- voice-pitch
- voice-range
- voice-rate
- voice-stress
- voice-volume
- volume
- white-space
-
For both specified and computed values, reify an identifier from the value and return the result.
- widows
- width
-
For both specified and computed values:
-
If the value is auto, reify an identifier from the value and return the result.
-
If the value is a <length> or <percentage>, reify a numeric value from the value and return the result.
-
- will-change
- word-spacing
- writing-mode
- x
- y
- z-index
5.1. Unrepresentable Values
Not all underlying values are simple enough to be reified with the current set of CSSStyleValue
subclasses.
When this is the case,
the property is reified as a CSSStyleValue.
-
Return a new
CSSStyleValue
object representing value whose[[associatedProperty]]
internal slot is set to property.
5.2. 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.
-
Replace all var() references in list with
CSSVariableReferenceValue
objects, as described in §5.3 var() References. -
Replace each remaining maximal subsequence of component values in list with a single string of their concatenated serializations.
-
Return a new
CSSUnparsedValue
whose[[tokens]]
slot is set to list.
CSSUnparsedValue
that contains a sequence with:
-
the string "calc(42px + "
-
a
CSSVariableReferenceValue
with:-
variable
"--foo" -
fallback
aCSSUnparsedValue
with a single-valued sequence containing " 15em"
-
-
the string " + "
-
a
CSSVariableReferenceValue
with:-
variable
"--bar" -
fallback
aCSSUnparsedValue
with a sequence containing:-
the string " "
-
a
CSSVariableReferenceValue
with -
the string " + 15px"
-
-
-
the string ")"
5.3. var() References
var() references become CSSVariableReferenceValue
s in the Typed OM.
-
Let object be a new
CSSVariableReferenceValue
. -
Set object’s
variable
internal slot to the serialization of the <custom-ident> providing the variable name. -
If var has a fallback value, set object’s
fallback
internal slot to the result of reifying the fallback’s component values. Otherwise, set it tonull
. -
Return object.
5.4. Identifier Values
CSS identifiers become CSSKeywordValue
s in the Typed OM.
-
Return a new
CSSKeywordValue
with itsvalue
internal slot set to the serialization of ident.
5.5. <number>, <percentage>, and <dimension> values
CSS <number>, <percentage>, and <dimension> values become CSSNumericValue
s in the Typed OM.
-
If num is a calc(), min(), or max() expression, reify a math expression from num and return the result.
-
If num is the unitless value 0 and num is a <dimension>, return a new
CSSUnitValue
with itsvalue
internal slot set to 0, and itsunit
internal slot set to "px". -
Return a new
CSSUnitValue
with itsvalue
internal slot set to the numeric value of num, and itsunit
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>.
-
If num is a min() or max() expression:
-
Let values be the result of reifying the arguments to the expression, treating each argument as if it were the contents of a calc() expression.
-
Return a new
CSSMathMin
orCSSMathMax
object, respectively, with itsvalues
internal slot set to values.
-
-
Assert: Otherwise, num is a calc().
-
Turn num’s argument into an expression tree using standard PEMDAS precedence rules, with the following exceptions/clarification:
-
Treat subtraction as instead being addition, with the RHS argument instead wrapped in a special "negate" node.
-
Treat division as instead being multiplication, with the RHS argument instead wrapped in a special "invert" node.
-
Addition and multiplication are N-ary; each node can have any number of arguments.
-
If an expression has only a single value in it, and no operation, treat it as an addition node with the single argument.
-
-
Recursively transform the expression tree into objects, as follows:
- addition node
-
becomes a new
CSSMathSum
object, with itsvalues
internal slot set to its list of arguments - multiplication node
-
becomes a new
CSSMathProduct
object, with itsvalues
internal slot set to its list of arguments - negate node
-
becomes a new
CSSMathNegate
object, with itsvalue
internal slot set to its argument - invert node
-
becomes a new
CSSMathInvert
object, with itsvalue
internal slot set to its argument - leaf node
-
reified as appropriate
CSSMathSum( CSS.px(1), CSSMathNegate( CSSMathProduct( 2, CSS.em(3) ) ) )
CSSMathSum( CSS.px(1), CSS.px(2), CSS.px(3) )
but calc(calc(1px + 2px) + 3px) produces the structure:
CSSMathSum( CSSMathSum( CSS.px(1), CSS.px(2) ), CSS.px(3) )
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 CSSMathSum(CSS.px(1), CSS.em(2))
,
but as a computed value will give CSS.px(33)
or similar
(depending on the value of an em in that context).
5.6. <transform-list> and <transform-function> values
CSS <transform-list> values become CSSTransformValue
s in the Typed OM,
while CSS <transform-function> values become CSSTransformComponent
s.
-
Return a new
CSSTransformValue
whose values to iterate over are the result of mapping the reify a <transform-function> algorithm over list.
- matrix()
- matrix3d()
-
-
Return a new
CSSMatrixComponent
object, whosematrix
internal slot is set to a 4x4 matrix representing the same information as func, and whoseis2D
internal slot istrue
if func is matrix(), andfalse
otherwise.
-
- translate()
- translateX()
- translateY()
- translate3d()
- translateZ()
- translateX()
-
-
Return a new
CSSTranslate
object, whosex
,y
, andz
internal slots are set to the reification of the specified x/y/z offsets, or the reification of 0px if not specified in func, and whoseis2D
internal slot istrue
if func is translate(), translateX(), or translateY(), andfalse
otherwise.
-
- scale()
- scaleX()
- scaleY()
- scale3d()
- scaleZ()
- scaleX()
- rotate()
- rotate3d()
- rotateX()
- rotateY()
- rotateZ()
- rotate3d()
-
-
Return a new
CSSRotate
object, whoseangle
internal slot is set to the reification of the specified angle, and whosex
,y
, andz
internal slots are set to the specified rotation axis coordinates, or the implicit axis coordinates if not specified in func and whoseis2D
internal slot istrue
if func is rotate(), andfalse
otherwise.
-
- skew()
-
-
Return a new
CSSSkew
object, whoseax
anday
internal slots are set to the reification of the specified x and y angles, or the reification of 0deg if not specified in func, and whoseis2D
internal slot istrue
.
-
- skewX()
-
-
Return a new
CSSSkewX
object, whoseax
internal slot is set to the reification of the specified x angle, or the reification of 0deg if not specified in func, and whoseis2D
internal slot istrue
.
-
- skewY()
-
-
Return a new
CSSSkewY
object, whoseay
internal slot is set to the reification of the specified y angle, or the reification of 0deg if not specified in func, and whoseis2D
internal slot istrue
.
-
- perspective()
-
-
Return a new
CSSPerspective
object, whoselength
internal slot is set to the reification of the specified length and whoseis2D
internal slot isfalse
.
-
5.7. <position> Values
CSS <position> values become CSSPositionValue
s in the Typed OM, with x and y components determined via the following process. If this process, or any sub-process referenced by this
process fails, then reification as a whole fails.
-
Initialize both x and y to a
CSSNumericValue
value representing 50%. -
If the provided value is a single keyword, length, percentage, or calc expression, then follow the procedure outlined in §5.7.1 Determining x or y from a single value with value given by the provided value and an auto bias.
-
Otherwise, if the provided value consists of a combination of two keywords, then:
-
follow the procedure outlined in §5.7.1 Determining x or y from a single value with value given by the first keyword and an auto bias.
-
if bias is horizontal, set it to vertical. Otherwise, set it to horizontal.
-
follow the procedure again with value given by the second keyword, using the existing bias.
-
-
Otherwise, if the provided value consists of a combination of two keywords, lengths, percentages, and calc expressions, then follow the procedure outlined in §5.7.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.
-
Otherwise:
-
if the provided value starts with a keyword followed by a length, percentage, or calc expression, then follow the procedure outlined in §5.7.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.
-
otherwise, follow the procedure outlined in §5.7.1 Determining x or y from a single value with value set to the first component of the provided value and an auto bias.
-
if bias is horizontal, set it to vertical. Otherwise, set it to horizontal.
-
if the remainder of the provided value is a single keyword, length, percentage or calc expression, follow the procedure outlined in §5.7.1 Determining x or y from a single value with value set to the keyword and the existing bias.
-
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.7.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.
-
Otherwise, the process fails.
-
5.7.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.
-
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. -
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. -
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. -
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. -
If value matches the <length-percentage> production, then set norm to the result of reifying |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.
-
If value is not the keyword "center", then this process fails.
5.7.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.
-
Follow the procedure outlined in §5.7.1 Determining x or y from a single value with value given by keyword, using the provided bias
-
Let adjustment be the result of reifying |length| as a numeric value.
-
If the keyword is "right" or "bottom", let adjustment be the result of subtracting adjustment from a zero length.
-
Amend x (if bias is horizontal) or y (if bias is vertical) by adding adjustment to it.
5.8. <url> (and subtype) Values
Resource references are reified 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.
Reification can not fail for CSSResourceValue
objects.
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 USVString
-
the serialization is the USVString from which the value was constructed.
- otherwise, if the value was constructed using an IDL constructor
-
the serialization is specified in the sections below.
- otherwise, if the value was extracted from the CSSOM
-
the serialization is specified in §6.8 Serialization from CSSOM Values below.
For example:
var length1 = CSSNumericValue.parse("42.0px"); length1.toString(); // "42.0px" var length2 = CSS.px(42.0); length2.toString(); // "42px"; element.style.width = "42.0px"; var length3 = element.attributeStyleMap.get('width'); length3.toString(); // "42px";
6.1. CSSUnparsedValue
Serialization
CSSUnparsedValue
this:
-
Let s initially be the empty string.
-
For each item in this’s
[[tokens]]
internal slot:-
If item is a
USVString
, append it to s. -
Otherwise, item is a
CSSVariableReferenceValue
. Serialize it, then append the result to s.
-
-
Return s.
CSSVariableReferenceValue
this:
6.2. CSSKeywordValue
Serialization
6.3. CSSUnitValue
Serialization
CSSUnitValue
this:
-
Set s to the result of serializing a <number> from value, per CSS Object Model (CSSOM) §serializing-css-values.
-
If unit is "number", return s.
-
Otherwise, if unit is "percentage", append "%" to s, then return s.
-
Otherwise, append unit to s, then return s.
6.4. CSSMathValue
Serialization
CSSMathValue
this,
with additional flags nested, a boolean (defaulting to false if unspecified),
and paren-less, a boolean (defaulting to false if unspecified):
-
Let s initially be the empty string.
-
If this is a
CSSMathMin
orCSSMathMax
: -
Otherwise, if this is a
CSSMathSum
:-
If paren-less is true, continue to the next step; otherwise, if nested is true, append "(" to s; otherwise, append "calc(" to s.
-
Serialize the first item in this’s
values
internal slot with nested set to true, and append the result to s. -
For each arg in this’s
values
internal slot beyond the first:-
If arg is a
CSSMathNegate
, append " - " to s, then serialize arg’svalue
internal slot with nested set to true, and append the result to s. -
Otherwise, append " + " to s, then serialize arg with nested set to true, and append the result to s.
-
-
If paren-less is false, append ")" to s,
-
Return s.
-
-
Otherwise, if this is a
CSSMathNegate
:-
If paren-less is true, continue to the next step; otherwise, if nested is true, append "(" to s; otherwise, append "calc(" to s.
-
Append "-" to s.
-
Serialize this’s
value
internal slot with nested set to true, and append the result to s. -
If paren-less is false, append ")" to s,
-
Return s.
-
-
Otherwise, if this is a
CSSMathProduct
:-
If paren-less is true, continue to the next step; otherwise, if nested is true, append "(" to s; otherwise, append "calc(" to s.
-
Serialize the first item in this’s
values
internal slot with nested set to true, and append the result to s. -
For each arg in this’s
values
internal slot beyond the first:-
If arg is a
CSSMathInvert
, append " / " to s, then serialize arg’svalue
internal slot with nested set to true, and append the result to s. -
Otherwise, append " * " to s, then serialize arg with nested set to true, and append the result to s.
-
-
If paren-less is false, append ")" to s,
-
Return s.
-
-
Otherwise, if this is a
CSSMathInvert
:-
If paren-less is true, continue to the next step; otherwise, if nested is true, append "(" to s; otherwise, append "calc(" to s.
-
Append "1 / " to s.
-
Serialize this’s
value
internal slot with nested set to true, and append the result to s. -
If paren-less is false, append ")" to s,
-
Return s.
-
6.5. CSSTransformValue
and CSSTransformComponent
Serialization
CSSTransformValue
this:
-
Return the result of serializing each item in this’s values to iterate over, then concatenating them separated by " ".
CSSTranslate
this:
CSSRotate
this:
-
Let s initially be the empty string.
-
If this’s
is2D
internal slot isfalse
:-
Append "rotate3d(" to s.
-
Serialize this’s
x
internal slot, and append it to s. -
Append ", " to s.
-
Serialize this’s
y
internal slot, and append it to s. -
Append ", " to s.
-
Serialize this’s
z
internal slot, and append it to s. -
Append "," to s.
-
Serialize this’s
angle
internal slot, and append it to s. -
Append ")" to s, and return s.
-
-
Otherwise:
-
Append "rotate(" to s.
-
Serialize this’s
angle
internal slot, and append it to s. -
Append ")" to s, and return s.
-
CSSScale
this:
-
Let s initially be the empty string.
-
If this’s
is2D
internal slot isfalse
: -
Otherwise:
-
Append "scale(" to s.
-
Serialize this’s
x
internal slot, and append it to s. -
If this’s
x
andy
internal slots are equal numeric values, append ")" to s and return s. -
Otherwise, append ", " to s.
-
Serialize this’s
y
internal slot, and append it to s. -
Append ")" to s, and return s.
-
CSSSkew
this:
-
Let s initially be "skew(".
-
Serialize this’s
ax
internal slot, and append it to s. -
If this’s
ay
internal slot is aCSSUnitValue
with avalue
of0
, then append ")" to s and return s. -
Otherwise, append ", " to s.
-
Serialize this’s
ay
internal slot, and append it to s. -
Append ")" to s, and return s.
CSSSkewX
this:
-
Let s initially be "skewX(".
-
Serialize this’s
ax
internal slot, and append it to s. -
Append ")" to s, and return s.
CSSSkewY
this:
-
Let s initially be "skewY(".
-
Serialize this’s
ay
internal slot, and append it to s. -
Append ")" to s, and return s.
CSSPerspective
this:
-
Let s initially be "perspective(".
-
Serialize this’s
length
internal slot, and append it to s. -
Append ")" to s, and return s.
6.6. CSSPositionValue
Serialization
CSSPositionValue
objects are serialized by:
-
serializing the
x
attribute according to the rules forCSSNumericValue
objects above. -
serializing the
y
attribute according to the rules forCSSNumericValue
objects above. -
returning the concatenation of the two serializations (x before y), separated by a space.
6.7. CSSURLImageValue
Serialization
CSSURLImageValue
objects are serialized to the string given by
'url("' + url
+ '")'.
6.8. Serialization from CSSOM Values
CSSStyleValue
objects produced by the user agent from values in the CSSOM,
rather than directly constructed by the author,
are serialized according to the following rules,
depending on the property they came from:
- background-color
-
-
If the value is the currentcolor keyword, return "currentcolor".
-
Otherwise, return the result of serializing the <color> value.
-
- border-color
-
-
If the value is the currentcolor keyword, return "currentcolor".
-
Otherwise, return the result of serializing the <color> value.
-
- border-image
-
-
Let values initially be the empty list.
-
If border-image-source is not none, serialize border-image-source and append it to values.
-
If border-image-slice does not specify 100% for all sides and omits the fill keyword, serialize border-image-slice and append it to values.
-
If border-image-width does not specify 1 for all sides, append "/ " (U+002F FORWARD SLASH followed by U+0020 SPACE) to the result of serializing border-image-width and append it to values.
-
If border-image-outset does not specify 0 for all sides:
-
If the previous border-image-width step did not append anything to values, let prefix be "// " (two U+002F FORWARD SLASH characters followed by U+0020 SPACE); otherwise let prefix be "/ " (U+002F FORWARD SLASH followed by U+0020 SPACE)
-
Append prefix to the result of serializing border-image-outset and append it to values.
-
-
If border-image-repeat is not stretch in both axises, serialize border-image-repeat and append it to values.
-
If values is empty, append "none" to values.
-
Return the result of concatenating all the items in values, separated by " " (U+0020 SPACE).
-
- bottom
-
-
If the value is the auto keyword, return "auto".
-
If the value is of type <length>, return the result of serializing the <length> value.
-
Otherwise, return the result of serializing the <percentage> value.
-
- color
-
-
If the value is the currentcolor keyword, return "currentcolor".
-
Otherwise, return the result of serializing the <color> value.
-
- left
-
-
If the value is the auto keyword, return "auto".
-
If the value is of type <length>, return the result of serializing the <length> value.
-
Otherwise, return the result of serializing the <percentage> value.
-
- opacity
-
-
If the value is of type <number>, return the result of serializing the <number> value.
-
Otherwise, return the result of serializing the <percentage> value.
-
- right
-
-
If the value is the auto keyword, return "auto".
-
If the value is of type <length>, return the result of serializing the <length> value.
-
Otherwise, return the result of serializing the <percentage> value.
-
- top
-
-
If the value is the auto keyword, return "auto".
-
If the value is of type <length>, return the result of serializing the <length> value.
-
Otherwise, return the result of serializing the <percentage> value.
-
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.