fix(css-syntax): always link <type> references in formal syntax#685
fix(css-syntax): always link <type> references in formal syntax#685caugner wants to merge 1 commit into
<type> references in formal syntax#685Conversation
|
@Josh-Cena @Rumyra Can you please take a look at the screenshots above and let me know if that makes sense? Basically, linking to types unconditionally adds 7 links in the above example. (I think it's fine.) |
|
5f5287b was deployed to: https://rari-pr685.review.mdn.allizom.net/ |
In formal-syntax boxes, `<type>` references whose definitions are expanded inline below previously rendered without a link, on the assumption that the inline expansion made navigation redundant. This left occurrences like `<calc-keyword>` inside `calc()` looking inconsistent with sibling `<type>` refs that *do* link out. Instead of linking every body occurrence (which produces 4+ identical links on pages like `calc()`), link the expansion *heading*: the `<calc-keyword> = …` line itself becomes an anchored link to the type's Reference page. One link per expanded type, placed at its definition site. - Adds `SyntaxLine::heading_url`, populated by `get_constituent_syntaxes` for Type/Function/Property/AtRule constituents (`None` for the top-level syntax, whose heading is the current page). - `SyntaxRenderer::render` wraps the heading name in `<a>` when `heading_url` is set. - Updated snapshot expectations in `test_render_node` and `test_render_function_scoped`. Fixes #165
2f32afe to
aeb111a
Compare
<type> references in formal syntax<type> references in formal syntax
|
Does the red squiggly mean "broken"? Is the intention that this page should be eventually written (which I doubt will; a lot of these types are strictly internal and purely for spec convenience)? |
|
In Rari a broken link is just a link where we know that the target does not exist, so the link rendering is replaced by a placeholder element. How that element is styled is up to Fred, and currently these are displayed with squiggly underline. |
|
Per my understanding, there are far more types in the CSS spec than we'd like to document; most of them are only ever used once or twice as an intermediate form that composes with other stuff. So:
|
One important question is where it should be linked:
Otherwise it is absolutely possible to only link where a page exists, but that is a slightly different issue as #165 where links on expanded attributes are currently missing. |

Description
Always wrap
<type>references in formal-syntax boxes with a link to the correspondingReference/Values/{slug}page, even when the type's definition is also expanded inline as a constituent.Motivation
Previously, types whose definitions were expanded in the same syntax box (e.g.
<calc-keyword>insidecalc(),<length-percentage>insidepadding) were rendered without a link, on the assumption that the inline expansion made navigation redundant. This produced inconsistent UX with sibling<type>refs that do get linked.Additional details
self.constituents.contains(node)short-circuit in theNode::Typebranch ofSyntaxRenderer::render_node; only the existingskip()cases (color,gradient) remain unlinked.test_render_nodeandtest_render_function_scoped.SyntaxRenderer::constituentsfield and theConstituentwrapper struct.Related issues and pull requests
Fixes #165.