diff --git a/css-properties-values-api/Overview.bs b/css-properties-values-api/Overview.bs index 73072816..7634ec0c 100644 --- a/css-properties-values-api/Overview.bs +++ b/css-properties-values-api/Overview.bs @@ -803,6 +803,99 @@ string. +CSSOM {#cssom} +============== + +{{CSSStyleDeclaration}} Behavior {#css-style-declaration-behavior} +------------------------------------------------------------------ + +The set a CSS declaration algorithm gains an additional constraint +for registered custom properties: + +* The target declaration must have a value that matches the registered + [=syntax descriptor|syntax=] of the property. + +This means that once a property is registered, it is not possible to use +{{setProperty()}} with a value that violates the registered syntax of the +property. + +Note: Registering a property with a particular syntax +does not invalidate already-specified values for the property +(that is, they're not thrown out at parse-time, +like invalid properties usually are), +even if those would violate the registered syntax. +The registration does prevent new invalid values from being set, +and affects how the custom property calculates its [=computed value=]. + +
+ For example, + in the following code snippet, + the ''--x'' property is set to a value + that doesn't match the later-registered syntax: + +
+		document.body.style.setProperty('--x', '10px');
+		CSS.registerProperty({
+			name: '--x',
+			syntax: '<color>',
+			initialValue: 'white',
+			inherits: false
+		});
+
+		// This still outputs "10px", as existing values aren't
+		// re-evaluated after a syntax is registered.
+		console.log(document.body.style.getPropertyValue('--x'));
+
+		// This silently fails, like any other property would
+		// when one attempts to set it to an invalid value.
+		document.body.style.setProperty('--x', '20px');
+
+		// Because ''--x'' is still set to "10px", which isn't
+		// a valid <>, it will be "[=invalid at computed-value time=]",
+		// falling back to the registered initial value of "white".
+		// 'background-color' will then receive that color and get
+		// set to "white".
+		document.body.style.backgroundColor = "var(--x)";
+	
+
+ +{{CSSStyleValue}} Reification {#css-style-value-reification} +------------------------------------------------------------ + +
+ To reify a registered custom property value given a + [=syntax descriptor=] |syntax|, run these steps: + + For specified values: + + 1. If the value is a <>, and |syntax| is not the + [=universal syntax descriptor=], attempt to [=CSS/parse=] + the value according to |syntax|. If this succeeds, [=reify=] + the result as if it were a computed value, and return that result. + 2. Otherwise, [=reify a list of component values=] from the value, and + return the result. + + For computed values: + + 1. If the value is a <>, <>, <>, <>, + <
+ + Examples {#examples} ====================