Missing syntax for several CSS types

[caugner]

Background

We have deprecated mdn-data, and recommend consumers to migrate to @webref/css, but it appears that mdn-data includes some data that is missing in webref. (See also: https://github.com/csstree/csstree/pull/355/files#r2585312764)

Problem

The following 115 types have no syntax in css.json:

https://drafts.csswg.org/css-animations-2/

• <animation-action>

https://drafts.csswg.org/css-box-4/

• <box>

https://drafts.csswg.org/css-cascade-6/

• <scope-end>
• <scope-start>

https://drafts.csswg.org/css-color-4/

• <deprecated-color>
• <hex-color>
• <named-color>
• <quirky-color>
• <system-color>

https://drafts.csswg.org/css-conditional-5/

• <boolean-condition>
• <scroll-state-feature>
• <size-feature>
• <style-feature-name>
• <style-feature-value>
• <supports-condition-name>

https://drafts.csswg.org/css-counter-styles-3/

• <counter-style-name>

https://drafts.csswg.org/css-extensions-1/

• <extension-name>

https://drafts.csswg.org/css-fonts-4/

• <font-src-list>
• <palette-identifier>
• <palette-mix()>

https://drafts.csswg.org/css-grid-2/

• <flex>

https://drafts.csswg.org/css-lists-3/

• <counter-name>

https://drafts.csswg.org/css-mixins-1/

• <dashed-function>

https://drafts.csswg.org/css-overflow-5/

• <scroll-button-direction>

https://drafts.csswg.org/css-page-3/

• <page-size>

https://drafts.csswg.org/css-shapes-1/

• <basic-shape>

https://drafts.csswg.org/css-speech-1/

• <age>
• <decibel>
• <gender>
• <semitones>

https://drafts.csswg.org/css-syntax-3/

• <(-token>
• <)-token>
• <CDC-token>
• <CDO-token>
• <[-token>
• <]-token>
• <any-value>
• <at-keyword-token>
• <at-rule-list>
• <bad-string-token>
• <bad-url-token>
• <block-contents>
• <colon-token>
• <comma-token>
• <dashndashdigit-ident>
• <declaration-list>
• <declaration-rule-list>
• <declaration-value>
• <delim-token>
• <dimension-token>
• <eof-token>
• <function-token>
• <hash-token>
• <ident-token>
• <n-dimension>
• <ndash-dimension>
• <ndashdigit-dimension>
• <ndashdigit-ident>
• <number-token>
• <percentage-token>
• <qualified-rule-list>
• <rule-list>
• <semicolon-token>
• <signed-integer>
• <signless-integer>
• <string-token>
• <unicode-range-token>
• <url-token>
• <whitespace-token>
• <{-token>
• <}-token>

https://drafts.csswg.org/css-transforms-2/

• <transform-function>

https://drafts.csswg.org/css-ui-4/

• <id>
• <outline-line-style>
• <target-name>
• <url-set>

https://drafts.csswg.org/css-values-4/

• <angle>
• <custom-ident>
• <dashed-ident>
• <dimension>
• <frequency>
• <ident>
• <integer>
• <length>
• <number>
• <percentage>
• <quirky-length>
• <resolution>
• <string>
• <time>
• <url-modifier>
• <zero>

https://drafts.csswg.org/css-values-5/

• <attr-unit>
• <segment-options>
• <size-keyword>
• <whole-value>

https://drafts.csswg.org/css-variables-2/

• <custom-property-name>

https://drafts.csswg.org/css2/

• <absolute-size>
• <border-style>
• <border-width>
• <bottom>
• <identifier>
• <left>
• <margin-width>
• <padding-width>
• <relative-size>
• <right>
• <shape>
• <top>
• <uri>

https://drafts.csswg.org/mediaqueries-5/

• <media-query-list>

https://drafts.csswg.org/pointer-animations-1/

• <timeline-range-center-subject>

https://drafts.csswg.org/scroll-animations-1/

• <timeline-range-name>

https://drafts.csswg.org/selectors-4/

• <forgiving-selector-list>

https://drafts.csswg.org/selectors-5/

• <level>

---

Generated by opening https://unpkg.com/@webref/css/css.json in Firefox, and running the following snippet in Firefox DevTools:

Object.entries(
  $json.data.types
    .filter((type) => !type.syntax)
    .map((type) => [
      type.href.split("#")[0],
      `- [\`<${type.name}>\`](${type.href})`,
    ])
    .toSorted()
    .reduce((map, [key, item]) => {
      map[key] ||= [];
      map[key].push(item);
      return map;
    }, {}),
)
  .map(([key, items]) => `### ${key}\n\n${items.join("\n")}`)
  .join("\n\n");

[frenic]

Same issue here. We also need these types to migrate from mdn-data to @webref/css for csstype.

[tidoust]

@caugner the list you compiled contains constructs that do not have a syntax either in mdn/data. For example, all <[something]-token> types. For a more specific analysis of differences between mdn/data and @webref/css, see Syntax mismatches between MDN data and Webref which I just re-generated. The most interesting bits are constructs that have "webref: unknown syntax", ~50 in total.

The reason why these constructs do not have a syntax in Webref is that the underlying specs do not define the syntax in a machine-readable way, sometimes on purpose. In other cases, specs could perhaps be improved over time (21 of the missing syntaxes are for selectors, whose syntax tends to be somewhat hidden in specs).

We'll look into adding a simple mechanism to patch the data and add missing syntaxes, leveraging the contents of mdn/data for these ~50 constructs.

By definition, these patches will have to be maintained manually. As noted in #1647 (which discusses this approach for <system-color> and <deprecated-color>), we're happy to coordinate the patches in Webref but we're likely going to do a poor job at maintaining the data ourselves. We're going to need help from people who actually need the data, to maintain the patches (or to push updates to the specs when that seems appropriate).

[tidoust]

We created a new patching mechanism to add missing syntaxes, see syntax-patches.js. That patch file already contains most of the syntaxes that were missing in Webref.

Syntaxes that are in mdn/data but are still not in Webref are for:

• @charset but I'm not sure the syntax means much as @charset is not a pure at-rule that follows a syntax, but rather a fake at-rule that expects a specific sequence of bytes.
• @starting-style
• <media-query-list> but I believe <media-query># is only an approximation as the spec says to parse a comma-separated list of component values, which is likely not an exact match for the # combinator. The <scroll-state-feature> and <size-feature> types are in the same category.
• <timeline-range-name>, tracked in Add CSS syntax patch for: <timeline-range-name> #1762.
• palette-mix() for font-palette, which simply shouldn't exist as a scoped function. This requires a fix in the crawler. Tracked in [CSS] Don't extract dfns that wrap a link to somewhere else reffy#1995
• 14 selectors. I need to review all seletors syntaxes in practice, specs tend not to define them formally.

[romainmenke]

Good to know about syntax-patches.js :). I am used to open issues upstream if the syntax seems incorrect. Going forward I will also check this file if I notice something.