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=]. + +
+ 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)"; +