|
1 | 1 | # CSS definitions of the web platform |
2 | 2 |
|
3 | | -This package contains CSS property definitions scraped from the latest versions of web platform specifications in [webref](https://github.com/w3c/webref), with fixes applied to ensure ([almost](#guarantees)) all CSS value definitions can be parsed with [CSSTree](https://github.com/csstree/csstree). |
| 3 | +This package contains a consolidated list of CSS features defined across specs, scraped from the latest versions of web platform specifications in [webref](https://github.com/w3c/webref). Fixes are applied to ensure that [guarantees](#guarantees) hold, including the ability to parse syntaxes associated with CSS features with [CSSTree](https://github.com/csstree/csstree). |
| 4 | + |
| 5 | +**Important:** If you're migrating from version 6, see the [changelog](CHANGELOG.md) for "How to upgrade" considerations. |
4 | 6 |
|
5 | 7 | # API |
6 | 8 |
|
7 | | -The async `listAll()` method resolves with an object where the keys are spec shortnames, and the values are the data for that spec. Example: |
| 9 | +The async `listAll()` method resolves with an object that contains lists of features grouped by feature type: `atrules`, `functions`, `properties`, `selectors` and `types`. Example: |
8 | 10 |
|
9 | 11 | ```js |
10 | 12 | const css = require('@webref/css'); |
11 | 13 |
|
12 | | -const parsedFiles = await css.listAll(); |
13 | | -for (const [shortname, data] of Object.entries(parsedFiles)) { |
14 | | - // do something with the json object |
| 14 | +const { atrules, functions, properties, selectors, types } = await css.listAll(); |
| 15 | + |
| 16 | +for (const feature of functions) { |
| 17 | + // do something with the object that describes the CSS function |
15 | 18 | } |
16 | 19 | ``` |
17 | 20 |
|
18 | | -CSS fragments that appear in the objects, in other words the contents of the `properties[].value`, `properties[].newValues`, `atrules[].value`, `atrules[].descriptors[].value`, `selectors[].value` and `values[].value` properties can be parsed with the [CSSTree Value Definition Syntax parser](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md#value-definition-syntax). Example: |
| 21 | +Each CSS feature is described by: |
| 22 | +- a `name` key that contains the name of the feature |
| 23 | +- an `href` key that contains the URL (with a fragment) of the CSS spec that defines the feature |
| 24 | + |
| 25 | +Many CSS features also have a `value` key that describes the syntax of the feature, as defined in the spec. This syntax can be parsed with the [CSSTree Value Definition Syntax parser](https://github.com/csstree/csstree/blob/master/docs/definition-syntax.md#value-definition-syntax). Example: |
19 | 26 |
|
20 | 27 | ```js |
21 | 28 | const css = require('@webref/css'); |
22 | 29 | const { definitionSyntax } = require('css-tree'); |
23 | 30 |
|
24 | | -const parsedFiles = await css.listAll(); |
25 | | -for (const [shortname, data] of Object.entries(parsedFiles)) { |
26 | | - for (const property of data.properties) { |
27 | | - if (property.value) { |
28 | | - try { |
29 | | - const ast = definitionSyntax.parse(property.value); |
30 | | - // do something with the ast |
31 | | - } |
32 | | - catch { |
33 | | - // one of the few value definitions that cannot yet be parsed by CSSTree |
34 | | - } |
35 | | - } |
| 31 | +const { properties } = await css.listAll(); |
| 32 | +for (const property of properties) { |
| 33 | + if (!property.value) { |
| 34 | + continue; |
36 | 35 | } |
| 36 | + const ast = definitionSyntax.parse(property.value); |
| 37 | + // do something with the abstract syntax tree |
37 | 38 | } |
38 | 39 | ``` |
39 | 40 |
|
| 41 | +Additional keys may be set depending on the type of the CSS feature. For example: |
| 42 | + |
| 43 | +- At-rules have a `descriptors` key that contains the list of descriptors defined for the given at-rule. |
| 44 | +- Functions and types that are scoped to a property or other feature have a `for` key that contains the name of the scoping property or other feature. |
| 45 | +- Properties have a `styleDeclaration` key that contains the list of IDL attribute names that the property generates. A number of other keys may be set to describe the property's initial value, animation type and other parameters. |
| 46 | + |
| 47 | +Additional notes: |
| 48 | +- Type names are enclosed in `<>`. For example: `<frequency-percentage>`. |
| 49 | +- When a feature is defined across different levels in the same spec series, the definition from the latest level is used. |
| 50 | +- When a property is extended with new values in different specs, `href` links to the base definition and `value` is the union (using `|`) of the syntaxes of the base and extended definitions. |
| 51 | +- When new descriptors are defined for an at-rule in different specs, `descriptors` contains the merged list of known descriptors. |
| 52 | +- When specs define the syntax of an at-rule in terms of `<declaration-list>` or `<declaration-rule-list>`, the `value` key contains an "expanded" syntax that leverages the syntax of the at-rule's descriptors. |
| 53 | + |
40 | 54 | # Guarantees |
41 | 55 |
|
42 | 56 | The following guarantees are provided by this package: |
43 | | -- All values in CSS files can be parsed by the version of [CSSTree](https://github.com/csstree/csstree) used in `peerDependencies` in `package.json`. |
44 | | -- No duplicate definitions of entries in CSS files provided that CSS extracts of [delta specs](https://github.com/w3c/browser-specs/#seriescomposition) are not taken into account (such extracts end with `-n.json`, where `n` is a level number). The term "entries" includes CSS properties, at-rules, selectors, types and functions. Please note that specs may still extend entries defined elsewhere (to define new values for CSS properties, or new selectors for at-rules). |
45 | | -- CSS extracts contain a base definition of all CSS properties that get extended by other CSS property definitions (those for which `newValues` is set). |
46 | | -- All entries in CSS files that do not extend a base definition link back to their actual definition in the spec. In other words, all entries under `properties[]`, `properties[].values[]`, `selectors[]`, `atrules[]` and `values[]` have an `href` key that contains an absolute URL with fragment, except properties that that have a `newValues` key, at-rules that neither have a `prose` nor a `value` key, and definitions of a [delta spec](https://github.com/w3c/browser-specs/#seriescomposition) that completely override a definition in a previous level. |
| 57 | +- All syntax values (the `value` keys) can be parsed by the version of [CSSTree](https://github.com/csstree/csstree) set in `peerDependencies` in `package.json`. |
| 58 | +- Feature names (the `name` keys) are unique per type provided that the `for` key is also taken into account for functions and types. |
| 59 | +- All features have an `href` key that targets the CSS spec that defines the feature. When the feature is extended across CSS specs, this URL targets the base definition. |
| 60 | + |
| 61 | +*Note:* there is no guarantee that functions, properties and types referenced by other constructs actually exist. The grammar is known to be incomplete. |
0 commit comments