CSS definitions of the web platform

This package contains CSS property definitions scraped from the latest versions of web platform specifications in webref, with fixes applied to ensure (almost) all CSS value definitions can be parsed with CSSTree.

API

The async listAll() method resolves with an object where the keys are spec shortnames, and the values are the data for that spec. Example:

const css = require('@webref/css');

const parsedFiles = await css.listAll();
for (const [shortname, data] of Object.entries(parsedFiles)) {
  // do something with the json object
}

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. Example:

const css = require('@webref/css');
const { definitionSyntax } = require('css-tree');

const parsedFiles = await css.listAll();
for (const [shortname, data] of Object.entries(parsedFiles)) {
  for (const property of data.properties) {
    if (property.value) {
      try {
        const ast = definitionSyntax.parse(property.value);
        // do something with the ast
      }
      catch {
        // one of the few value definitions that cannot yet be parsed by CSSTree
      }
    }
  }
}

Guarantees

The following guarantees are provided by this package:

• All values in CSS files can be parsed by the version of CSSTree used in peerDependencies in package.json.
• No duplicate definitions of CSS properties provided that CSS extracts of delta specs are not taken into account (such extracts end with -n.json, where n is a level number).
• CSS extracts contain a base definition of all CSS properties that get extended by other CSS property definitions (those for which newValues is set).
• 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 that completely override a definition in a previous level.

Changelog

This file documents breaking changes introduced in major releases of the @webref/css NPM package.

Webref adheres to Semantic Versioning, applied to data. A new major version is released whenever a breaking change is made to the data structure.

v6.0.0 - 2022-11-28

Major re-write of CSS extracts listed in the package, following the release of Reffy v11.0.0

Breaking changes

• Arrays are now used throughout instead of indexed objects.
• Function names are no longer enclosed in < and > because they are not defined in specs with these characters (as opposed to types). Beware though, references to functions in value syntax do use enclosing < and > characters.
• The property valuespaces at the root level is now named values. An array is used there as well. The values property lists both function and type definitions that are not namespaced to anything in particular (it used to also contain namespaced definitions).

Added

• Selectors are now reported under a selectors property at the root level.
• Possible values that some definition may take are now reported under a values property directly within the definition.
• Functions and types that are namespaced to some other definition are included in the list of values of that definition.
• Anomalies detected in the spec are now reported under a warnings property at the root of the extract. Four types of anomalies are reported:
  1. Missing definition: when a production rule was found but when the spec does not include a corresponding <dfn> (or when that <dfn> does not have a data-dfn-type attribute that identifies a CSS construct)
  2. Duplicate definition: when the spec defines the same term twice.
  3. Unmergeable definition: when the spec defines the same property twice and both definitions cannot be merged.
  4. Dangling value: when the spec defines a CSS "value" definition (value, function or type) for something and that something cannot be found in the spec
• To distinguish between function, type and value definitions listed in a values property, definitions that appear in a values property have a type property.

Additional notes

• Only namespaced values associated with a definition are listed under its values property. Non-namespaced values are not. For instance, <quote> is not listed as a value of the <content-list> type, even though its value syntax references it. This is to avoid duplicating constructs in the extracts.
• Values are only listed under the deepest definition to which they apply. For instance, open-quote is only listed as a value of <quote> but neither as a value of the <content-list> type that references <quote> nor as a value of the content property that references <content-list>. This is also to avoid duplicating constructs in the extracts.
• Some of the extracts contain things that may look weird at first, but that is "by design". For instance, CSS Will change defines a <custom-ident> value construct whose actual value is the <custom-ident> type construct defined in CSS Values. Having both a namespaced value and a non-namespaced <type> is somewhat common in CSS specs.