feat(macros/CSSSyntax): support at-rules and at-rule descriptors

[wbamberg]

Summary

Support at-rules and at-rule descriptors in the formal syntax.

Problem

When we switched to use webref for formal syntax, we dropped support for at-rules and at-rule descriptors. This restores it as promised in #4656 (comment).

Solution

There are a few code changes here:

• the getNameAndSyntax() function is the entry point to the bit of this macro that interfaces with webref, and is basically a switch on the different page types. I've extended it to support the additional cases of css-at-rule and css-at-rule-descriptor
• I've added new functions, getAtRuleSyntax() and getAtRuleDescriptorSyntax(), to fetch the syntax for these things
• very minor refactoring of a bit of shared code out of getPropertySyntax() and into a new function getSpecsForItem()
• moved getPropertySyntax() so it lives alongside these other getXYZSyntax() functions, before getNameAndSyntax()

We need somehow to map at-rule descriptors onto their at-rule, which I'm doing here by assuming that at-rule descriptors always appear under their at-rule in the page hierarchy. This is a safe assumption now and we're not planning to break it AFAIK. If we did want to make this system independent of page hierarchy we could have a front matter key for at-rule descriptors, pointing to their at-rule.

Screenshots

At-rule and at-rule descriptor pages now get syntax-highlighted.

Before

@Property:

@counter-style/pad:

After

@Property:

@counter-style/pad:

How did you test this change?

To test this:

1. check out this branch: https://github.com/wbamberg/content/tree/add-at-rule-descriptor-formal-syntax , which updates all relevant at-rule and at-rule descriptor pages to use csssyntax,
2. point your CONTENT_ROOT at this branch
3. run yarn dev
4. visit the pages:

at-rules:
/web/css/@viewport
/web/css/@import
/web/css/@supports
/web/css/@keyframes
/web/css/@document
/web/css/@property
/web/css/@color-profile
/web/css/@namespace
/web/css/@scroll-timeline
/web/css/@font-feature-values
/web/css/@layer
/web/css/@charset
/web/css/@page
/web/css/@media
/web/css/@font-face
/web/css/@font-face

at-rule descriptors:
/web/css/@property/initial-value
/web/css/@property/inherits
/web/css/@property/syntax
/web/css/@page/size
/web/css/@font-face/line-gap-override
/web/css/@font-face/size-adjust
/web/css/@font-face/font-variation-settings
/web/css/@font-face/font-stretch
/web/css/@font-face/ascent-override
/web/css/@font-face/descent-override
/web/css/@font-face/font-variant
/web/css/@font-face/unicode-range
/web/css/@font-face/font-weight
/web/css/@font-face/font-display
/web/css/@font-face/font-style
/web/css/@font-face/font-family
/web/css/@font-face/src
/web/css/@counter-style/fallback
/web/css/@counter-style/prefix
/web/css/@counter-style/negative
/web/css/@counter-style/suffix
/web/css/@counter-style/pad
/web/css/@counter-style/system
/web/css/@counter-style/symbols
/web/css/@counter-style/additive-symbols
/web/css/@counter-style/range
/web/css/@counter-style/speak-as

Note that in a few of these case I haven't updated the page to use csssyntax, but I don't think any of these are the macro's fault:

• /web/css/@font-face/src - here the spec says "see prose" where there should be syntax. If this can't be fixed upstream we will need to hardcode it.
• A few cases are nonstandard/deprecated/removed, and should either hardcode the syntax or (more likely) delete the pages:
  • /web/css/@viewport
  • /web/css/@document
  • /web/css/@scroll-timeline
  • /web/css/@font-face/font-variant
• /web/css/@charset: formal syntax isn't listed in webref. I think this might be an upstream problem, but if we can't fix it there we will hardcode the syntax.

We can check for regressions by visiting some other pages, as below.

CSS properties

http://localhost:3000/en-US/docs/Web/CSS/animation-duration
http://localhost:3000/en-US/docs/Web/CSS/background-clip#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/background#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/border-block-style#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/border-color#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/border-right#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/box-sizing#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/column-rule-color#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/color#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/clip-path#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/flex#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/filter#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/font-synthesis#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/font-variant#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/grid-auto-rows#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/grid-area#formal_syntax

CSS functions

http://localhost:3000/en-US/docs/Web/css/cross-fade#formal_syntax
http://localhost:3000/en-US/docs/Web/css/sign#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/transform-function/translateY#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/min#formal_syntax

CSS types

http://localhost:3000/en-US/docs/Web/CSS/alpha-value#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/angle-percentage#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/color_value#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/display-box#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/frequency-percentage#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/gradient#formal_syntax
http://localhost:3000/en-US/docs/Web/CSS/image#formal_syntax

[caugner]

@wbamberg Does this need to land together with the content PR, or could we merge this before?

[wbamberg]

@wbamberg Does this need to land together with the content PR, or could we merge this before?

No (unless I've messed up and regressed behavior with the other page types! but I have checked this and it seemed fine) we should be able to merge this first, then update the content to use it.