FPWD: CSS Properties and Values API Level 1

CSS Properties and Values API Level 1

http://www.w3.org/TR/2016/WD-css-properties-values-api-1-20160607/

Abstract



This CSS module defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.

Status of the Document



This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a First Public Working Draft.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing list public-houdini@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css-properties-values-api” in the subject, preferably like this: “[css-properties-values-api] …summary of comment…”

This document was jointly produced by the CSS Working Group and the Technical Architecture Group.

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

This document is governed by the 1 September 2015 W3C Process Document.


Table of Contents 1 Introduction 2 Registering custom properties 2.1 The PropertyDescriptor dictionary 2.2 The registerProperty() function 2.3 Supported syntax strings 2.4 Calculation of Computed Values 3 Behavior of Custom Properties 3.1 Animation Behavior of Custom Properties 3.2 Conditional Rules 4 Examples 4.1 Example 1: Using custom properties to add animation behavior 5 Security Considerations 6 Privacy Considerations Conformance Document conventions Conformance classes Partial implementations Experimental implementations Non-experimental implementations Index Terms defined by this specification Terms defined by reference References Normative References Informative References IDL Index Issues Index1. Introduction CSS defines a comprehensive set of properties that can be manipulated in order to modify the layout, paint, or behaviour of a web document. However, web authors frequently wish to extend this set with additional properties. [css-variables] provides primitive means for defining user-controlledproperties, however these properties always take token lists as values, must always inherit, and can only impact document layout or paint by being re-incorporated into the value of other properties via a var() reference. This specification extends [css-variables], allowing the registration of properties that have a value type, an initial value, and a defined inheritance behaviour. This specification is complementary to [css-paint-api] and [css-layout-api], which allow custom properties to directly impact paint and layout behaviours respectively. 2. Registering custom properties dictionary PropertyDescriptor { required DOMString name; DOMString syntax = "*"; boolean inherits = false; DOMString initialValue; }; partial interface CSS { void registerProperty(PropertyDescriptor descriptor); void unregisterProperty(DOMString name); }; 2.1. The PropertyDescriptor dictionary A PropertyDescriptor dictionary represents author-specified configuration options for a custom property. PropertyDescriptor dictionaies contain the following members: name, of type DOMString The name of the custom property being defined. syntax, of type DOMString, defaulting to "*" A string representing how this custom property is parsed. inherits, of type boolean, defaulting to false True if this custom property should inherit down the DOM tree; False otherwise. initialValue, of type DOMString The initial value of this custom property. 2.2. The registerProperty() function The registerProperty(PropertyDescriptor descriptor) method registers a custom property according the to configuration options provided in descriptor. Attempting to register properties with a name that doesn’t correspond to the <custom-property-name> production must cause registerProperty() to throw a SyntaxError. The list of types supported in the syntax member are listed in §2.3 Supported syntax strings. Currently, only simple type references are supported. Attempting to register properties with a syntax that is not supported must cause registerProerty() to throw a SyntaxError. Note: for example, the syntax string could be "<length>" or "<number>". Note: in future levels we anticipate supporting more sophisticated parse strings, e.g. "<length> || <number>" Attempting to call registerProperty() with an initialValue that is not parseable using the provided syntax must cause it to throw a SyntaxError. If no initialValue is provided and the syntax is *, then a special initial value used. This initial value must be considered parseable by registerProperty() but invalid at computed value time. Initial values that are not computationally idempotent must also cause registerProperty() to throw a SyntaxError. For example, "3cm" is a computationally idempotent length, and hence valid as an initial value. However, "3em" is not (depending on the environment, 3em could compute to multiple different values). Additionally, "var(--foo)" is not computationally idempotent. define computtional idempotency. Is computational idempotency the right thing to do here? We could also just resolve any relative values once (against all the other initial values) and use that. OR! We could allow specified values and just fix our engines... <https://github.com/w3c/css-houdini-drafts/issues/121> When a custom property is registered with a given type, the process via which specified values for that property are turned into computed values is defined fully by the type selected, as described in §2.4 Calculation of Computed Values. If registerProperty() is called with a descriptor name that matches an already registered property, then an InvalidModificationError is thrown and the re-registration fails. Properties can be unregistered using unregisterProperty(DOMString name). If this function is called with a name that doesn’t match an existing property then a NotFoundError is thrown. Successful calls to both registerProperty() and unregisterProperty() change the set of registered properties. When th set of registered properties changes, previously syntactically invalid property values can become valid and vice versa. This can change the set of declared values which requires the cascade to be recomputed. By default, all custom property declarations that can be parsed as a sequence of tokens are valid. Hence, the result of this stylesheet: .thing { --my-color: green; --my-color: url("not-a-color"); color: var(--my-color); } is to set the color property of elements of class "thing" to "inherit". The second --my-color declaration overrides the first at parse time (both are valid), and the var reference in the color property is found to be invalid at computation time (because url("not-a-color") is not a color). At computation time the only available fallback is the default value, which in the case of color is "inherit". if we call: registerProperty({ name: "--my-color", syntax: "<color>" }); then the second --my-color declaration bcomes syntactically invalid, which means that the cascade uses the first declaration. The color therefore switches to green. 2.3. Supported syntax strings The following syntax strings are supported: "<length>" Any valid <length> value "<number>" <number> values "<percentage>" Any valid <percentage> value "<length-percentage>" Any valid <length> or <percentage> value, any valid <calc()> expression combining <length> and <percentage> components. "<color>" Any valid <color> value "<image>" Any valid <image> value "<url>" Any valid <url> value "<integer>" Any valid <integer> value "<angle>" Any valid <angle> value "<time>" Any valid <time> value "<resolution>" Any valid <resolution> value "<transform-function>" Any valie <transformfunction> value "<custom-ident>" Any valid <custom-ident> value Any string, the contents of which matches the <ident> production That identifier Any one of the preceding strings, followed by '+' A list of values of the type specified by the string Any combination of the preceding, separated by '|' Any value that matches one of the items in the combination, matched in specified order. "*" Any valid token stream Note: [css3-values] maintains a distinction between properties that accept only a length, and properties that accept both a length and a percentage, however the distinction doesn’t currently cleanly line up with the productions. Accordingly, this specification introduces the length-percentage production for the purpose of cleanly specifying this distinction. Regardless of the syntax specified, all custom properties will accept CSS-wide keywords as well as revert, and process these values appropriately. Note: This does not apply to the initalValue member of the PropertyDescriptor dictionary. For example, the following are all valid syntax strings. "<length>" accepts length values "<length> | <percentage>" accepts lengths, percentages, percentage calc expressions, and length calc expressions, but not calc expressions containing a combination of length and percentage values. "<length-percentage>" accepts all values that "<length> | <percentage>" would accept, as well as calc expresssions containing a combination of both length and percentage values. "big | bigger | BIGGER" accepts the ident "big", or the ident "bigger", or the ident "BIGGER". "<length>+" accepts a list of length values. 2.4. Calculation of Computed Values The syntax of a custom property fully determines how computed values are generated from specified values for that property. The CSS-wide keywords and revert generate computed values as described i [css3-values] and [css-cascade-4] respectively. Otherwise: For <length> values, the computed value is the absolute length expressed in pixels. For <length-percentage> values, the computed value is one of the following: if the specified value contains only length units, the computed value is the absolute length expressed in pixels. if the specified value contains only percentages, the computed value is a simple percentage. otherwise, the computed value is a calc expression containing an absolute length expressed in pixels, and a percentage value. For <custom-ident>, ident, <color>, <image>, <url>, <integer>, <angle>, <time>, <resolution>, <transform-function> or "*" values, the computed value is identical to the specified value. For <number> and <percentage> values which are not calc expressions, the computed value is identical to the specified value. Calc expressions that are <number> and <percentage> valuesget reduced during computation to simple numbers and percentages respectively. For values specified by a syntax string that include "|" clauses, the computed value is given by applying the calculation rules for the first clause that matches to the specified value. For list values, the computed value is a list of the computed values of the primitives in the list. 3. Behavior of Custom Properties 3.1. Animation Behavior of Custom Properties Note: As defined by [css3-animations] and [css3-transitions], it is possible to specify animations and transitions that reference custom properties. When referenced by animations and transitions, custom properties interpolate in a manner defined by their types. If the start and end of an interpolation have matching types, then they will interpolate as specified in [css3-animations]. Otherwise, the interpolation falls back to the default 50% flip described in [css3-animations]. Intermediate interpolated results of animations on custom properties must be able to geerate a token stream representing their value. We should ensure that this is standard across implementations to avoid interop issues. 3.2. Conditional Rules @supports rules and the supports(conditionText) method behave as specified in [css-variables]. Note: In other words, for the purpose of determining whether a value is supported by a given custom property, the type registered for the custom property is ignored and any value consisting of at least one token is considered valid. should @supports pay attention to type when considering custom properties? <https://github.com/w3c/css-houdini-drafts/issues/118> 4. Examples 4.1. Example 1: Using custom properties to add animation behavior <script> CSS.registerProperty({ name: "--stop-color", syntax: "<color>", inherits: false, initialValue: "rgba(0,0,0,0)" }); </script> <style> .button { --stop-color: red; background: linear-gradient(var(--stop-color), black); transition: --stop-color 1s; } .button:hove { --stop-color: green; } </style> 5. Security Considerations There are no known security issues introduced by these features. 6. Privacy Considerations There are no known privacy issues introduced by these features.ConformanceDocument conventions

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

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

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


This is an example of an informative example.

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

Note, this is an informative note.

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

Conformance to this specification is defined for three conformance classes:style sheet A CSS style sheet. renderer A UA that interprets the semantics of a style sheet and renders documents that use them. authoring tool A UA that writes a style sheet.

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

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

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

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

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.Non-experimental implementations

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

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

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.IndexTerms defined by this specificationinherits, in §2.1 initialValue, in §2.1 name, in §2.1 PropertyDescriptor (dictionary), in §2 definition of, in §2.1 registerProperty(descriptor), in §2.2 syntax, in §2.1 unregisterProperty(name), in §2.2Terms defined by reference[css-cascade-3] defines the following terms: cascade declared value [css-cascade-4] defines the following terms: revert [css-color-3] defines the following terms: <color> [css-conditional-3] defines the following terms: @supports supports(conditionText) [css-images-3] defines the following terms: <image> [css-transforms-1] defines the following terms: <transform-function> [css3-values] defines the following terms: <angle> <custom-ident> <integer> <length> &l;number> <percentage> <resolution> <time> <url> calc() css-wide keywords [css-variables] defines the following terms: <custom-property-name> [cssom-1] defines the following terms: CSS [mediaqueries-4] defines the following terms: <ident> [WebIDL-1] defines the following terms: DOMString InvalidModificationError NotFoundError SyntaxError booleanReferencesNormative References[CSS-CASCADE-3] Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 3. 19 May 2016. CR. URL: http://www.w3.org/TR/css-cascade-3/ [CSS-CASCADE-4] Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 14 January 2016. CR. URL: http://www.w3.org/TR/css-cascade-4/ [CSS-COLOR-3] CSS Color Module Level 3 URL: https://www.w3.org/TR/css3-color/ [CSS-CONDITIONAL-3] CSS Conditional Rules Module Level 3 URL: https://www.w3.org/TR/css3-conditional/ [CSS-IMAGES-3] CSS Image Values and Replaced Content Module Level 3 URL: https://www.w3.org/TR/css3-images/ [CSS-TRANSFORMS-1] Simon Frasr; et al. CSS Transforms Module Level 1. 26 November 2013. WD. URL: http://www.w3.org/TR/css-transforms-1/ [CSS-VARIABLES] Tab Atkins Jr.. CSS Custom Properties for Cascading Variables Module Level 1. 3 December 2015. CR. URL: http://www.w3.org/TR/css-variables-1/ [CSS3-ANIMATIONS] Dean Jackson; et al. CSS Animations. 19 February 2013. WD. URL: http://www.w3.org/TR/css3-animations/ [CSS3-VALUES] Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 11 June 2015. CR. URL: http://www.w3.org/TR/css-values/ [CSSOM-1] Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). 17 March 2016. WD. URL: http://www.w3.org/TR/cssom-1/ [MEDIAQUERIES-4] Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. 26 January 2016. WD. URL: http://www.w3.org/TR/mediaqueries-4/ [RFC2119] S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 [WebIDL-1] Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 8 March 2016. CR. URL: http://ww.w3.org/TR/WebIDL-1/Informative References[CSS-LAYOUT-API] CSS Layout API. [CSS-PAINT-API] CSS Painting API. [CSS3-TRANSITIONS] Dean Jackson; et al. CSS Transitions. 19 November 2013. WD. URL: http://www.w3.org/TR/css3-transitions/IDL Indexdictionary PropertyDescriptor { required DOMString name; DOMString syntax = "*"; boolean inherits = false; DOMString initialValue; }; partial interface CSS { void registerProperty(PropertyDescriptor descriptor); void unregisterProperty(DOMString name); };Issues Index

↵
<https://github.com/w3c/css-houdini-drafts/issues/121>↵
↵
<https://github.com/w3c/css-houdini-drafts/issues/118>↵#dictdef-propertydescriptorReferenced in: 2. Registering custom properties 2.1. The PropertyDescriptor dictionary (2) 2.3. Supported syntax strings#dom-propertydescriptor-nameReferenced in: 2. Registering custom properties 2.2. The registerProperty() function#dom-propertydescriptor-syntaxReferenced in: 2. Registering custom properties 2.2. The registerProperty() function (2) (3) (4)#dom-propertydescriptor-inheritsReferenced in: 2. Registering custom properties#dom-propertydescriptor-initialvalueReferenced in: 2. Registering custom properties 2.2. The registerProperty() function (2) 2.3. Supported syntax strings#dom-css-registerpropertyReferenced in: 2. Registering custom properties 2.2. The registerProperty() function (2) (3) (4) (5) (6) (7) (8)#dom-css-unregisterpropertyReferenced in: 2. Registering custom properties 2.2. The registerProperty() function