feat(css-syntax): migrate to @webref/css 7 #317

argl · 2025-09-18T11:35:40Z

Description

This implements the usage of data from webref-css version 7.x. That version only provides a consolidated version of the data, so we can get rid of the brittle logic around selecting a CSS level we show. The editorial responsibility therefore lies with the maintainers of webref-css.

This is the basis of our CSS formal syntax rendering.

Motivation

Upstream major version change.

Additional details

Webref-css changelog
Diff of the document changes induced by this PR: 255 changes

`<color>` example formal syntax

Before

After

There are numerous additions to this in the v7 data, namely the correct introduction of light-dark() (which we document on the page) and device-cmyk() (which is not implemented by any browser by time of writing).

Since the specification titles are no more included with the webref data, titles are pulled in from the browser-specs data package.

Related issues and pull requests

Fixes #304

argl · 2025-09-22T14:21:45Z

Waiting for a decision from content for the copy, style and placement for a formal syntax disclaimer.

argl · 2025-10-02T11:53:36Z

Content decision is done, a PR adding the necessary translated text fragments is under review.

Cargo.lock

crates/css-syntax-types/src/lib.rs

caugner · 2025-10-07T11:12:42Z

crates/css-syntax-types/src/lib.rs


 #[derive(Clone, Debug, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
 pub struct AtRule {


Given that all these types share some fields, could these be extracted to a common base type, to ensure consistency?

Since there is no classic inheritance in rust, and we are bound to the JSON-structure of the webref data, we cannot use a straight composition pattern (tying together shared attributes in a common sub-struct). Other ways to do inheritance (traits, enums) are also not helping with clarity here. I think the current structs are not overwhelmingly large and changes are comparatively few.

Have you considered struct flattening?

Yes, but I decided against it. For consistency we would have to change a lot of structs that are outside the scope of this change. I would recommend to do that in a separate PR if really needed.

crates/css-syntax-types/src/lib.rs

crates/rari-deps/src/webref_css.rs

crates/rari-types/src/settings.rs

crates/rari-doc/src/templ/templs/csssyntax.rs

crates/rari-deps/src/webref_css.rs

caugner

Second pass.

crates/rari-deps/src/webref_css.rs

caugner · 2025-10-07T21:15:08Z

crates/css-syntax-types/src/lib.rs


 #[derive(Clone, Debug, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
 pub struct AtRule {


Have you considered struct flattening?

caugner · 2025-10-07T21:21:24Z

crates/css-syntax-types/src/css.rs

+    }
+}
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct AtruleDescriptor {


Nit: Rename to AtRuleDescriptor for consistency.

Suggested change

pub struct AtruleDescriptor {

pub struct AtRuleDescriptor {

caugner · 2025-10-07T21:26:36Z

crates/css-syntax-types/src/interfaces.rs

+    }
+}
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+pub enum Interfacetype {


Suggested change

pub enum Interfacetype {

pub enum InterfaceType {

crates/css-syntax-types/src/utils.rs

caugner · 2025-10-07T21:46:11Z

crates/rari-deps/src/webref_css.rs

+    Ok(url_to_title)
 }

+fn url_to_title_map(base_path: &Path) -> Result<BTreeMap<String, String>, DepsError> {


Nit: Add a short comment with an example of what the resulting map contains. Also possibly rename to spec_url_to_title_map.

Suggested change

fn url_to_title_map(base_path: &Path) -> Result<BTreeMap<String, String>, DepsError> {

fn spec_url_to_title_map(base_path: &Path) -> Result<BTreeMap<String, String>, DepsError> {

crates/rari-deps/src/webref_css.rs

caugner · 2025-10-07T21:50:33Z

crates/rari-deps/src/webref_css.rs

+    let url_to_title = url_to_title_map(base_path)?;
+
+    // Process the CSS data with the URL-to-title map passed in.
+    if let Some(package_path) = get_package("@webref/css", &deps().webref_css, base_path)? {
+        let webref_css = transform(&package_path, &url_to_title)?;


Nit: Move url_to_title inside block.

Suggested change

let url_to_title = url_to_title_map(base_path)?;

// Process the CSS data with the URL-to-title map passed in.

if let Some(package_path) = get_package("@webref/css", &deps().webref_css, base_path)? {

let webref_css = transform(&package_path, &url_to_title)?;

// Process the CSS data with the URL-to-title map passed in.

if let Some(package_path) = get_package("@webref/css", &deps().webref_css, base_path)? {

let url_to_title = url_to_title_map(base_path)?;

let webref_css = transform(&package_path, &url_to_title)?;

crates/rari-deps/src/webref_css.rs

caugner · 2025-10-13T17:43:51Z

crates/css-syntax-types/src/utils.rs

+// // In order to use it with in a BtreeSet<SpecLink>, implement `PartialOrd` and `Ord`
+// impl PartialOrd for SpecLink {
+//     fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+//         Some(self.cmp(other))
+//     }
+// }

-impl Ord for SpecLink {
-    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
-        // First compare by title, then by URL if titles are equal
-        self.title
-            .cmp(&other.title)
-            .then_with(|| self.url.cmp(&other.url))
-    }
-}
+// impl Ord for SpecLink {
+//     fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+//         // First compare by title, then by URL if titles are equal
+//         self.title
+//             .cmp(&other.title)
+//             .then_with(|| self.url.cmp(&other.url))
+//     }
+// }


Nit: Can't we just remove?

Suggested change

// // In order to use it with in a BtreeSet<SpecLink>, implement `PartialOrd` and `Ord`

// impl PartialOrd for SpecLink {

// fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {

// Some(self.cmp(other))

// }

// }

impl Ord for SpecLink {

fn cmp(&self, other: &Self) -> std::cmp::Ordering {

// First compare by title, then by URL if titles are equal

self.title

.cmp(&other.title)

.then_with(|| self.url.cmp(&other.url))

}

}

// impl Ord for SpecLink {

// fn cmp(&self, other: &Self) -> std::cmp::Ordering {

// // First compare by title, then by URL if titles are equal

// self.title

// .cmp(&other.title)

// .then_with(|| self.url.cmp(&other.url))

// }

// }

Ah sorry, missed a file save there.

argl added 12 commits September 12, 2025 20:13

parse v7 webref css

a77e257

some renaming

7c6dfd5

better path composition

8d54b06

checks around <color> type with full css levels

0e40259

more refactoring

d4b7a9c

more refactoring

cc02d57

syntax unit tests

58091fe

Stable sorting of css reference links, unit test for at descriptor

55f1549

Merge branch 'main' into webref-css7-support

5f47f24

linter

b5e5f47

linter

2a6ef74

formal syntax prefix text

1668346

argl mentioned this pull request Sep 22, 2025

CSS rect() formal syntax is missing CSS Shapes syntax #196

Closed

argl added the needs content decision label Sep 22, 2025

argl added p1 We will address this soon and will provide capacity from our team for it in the next few releases. and removed needs content decision labels Sep 24, 2025

argl added 5 commits September 29, 2025 15:26

use new localized footer in formal syntax

d23fe5f

install rustfmt and clippy for linting action

18b8819

Merge branch 'main' into webref-css7-support

1b359d1

Merge branch 'main' into webref-css7-support

e59881b

fixed tests

d2f2e72

argl mentioned this pull request Sep 30, 2025

Formal syntax prefix copy mdn/content#41344

Merged

argl removed the p1 We will address this soon and will provide capacity from our team for it in the next few releases. label Oct 2, 2025

Merge branch 'main' into webref-css7-support

69e1d5c

argl marked this pull request as ready for review October 7, 2025 08:47

argl requested review from a team and mdn-bot as code owners October 7, 2025 08:47

argl requested a review from caugner October 7, 2025 08:49

caugner reviewed Oct 7, 2025

View reviewed changes

argl added 6 commits October 7, 2025 15:21

alphabetize struct fields

9fc0051

factor out url to title map generation

9105e75

removed debug line

6093489

simplify function result return value logic

ea5fdbe

refactor css-syntax-types into separate modules

5f04773

removed unused tracing dependency

2835148

argl requested a review from caugner October 7, 2025 15:17

caugner changed the title ~~chore(css): webref css version 7 support~~ feat(css-syntax): migrate to @webref/css 7 Oct 7, 2025

caugner reviewed Oct 7, 2025

View reviewed changes

Josh-Cena mentioned this pull request Oct 8, 2025

missing compatiblity for "column-span: <integer [1,∞]>" mdn/content#41436

Closed

argl added 8 commits October 9, 2025 11:59

pin webref-css to v7.x

e0ed59c

bail out of webfref parsing if expected data blocks are missing

3274d44

rename Css to WebrefCss

3131405

more renamings, derive ordering for SpecLink instead of implementing

0d8352c

formatting

b3fcedc

reanem and explain the url-to-title map

537795d

move spec_url_to_title_map call inside the block where it is needed

a2922e3

refactored write_formal_syntax* into combined render_formal_syntax

56dd814

argl requested a review from caugner October 9, 2025 15:36

caugner approved these changes Oct 13, 2025

View reviewed changes

argl added 2 commits October 14, 2025 11:52

removed commented code

327641b

Merge branch 'main' into webref-css7-support

5f85f9a

argl merged commit b011b7d into main Oct 14, 2025
5 checks passed

mdn-bot mentioned this pull request Oct 14, 2025

chore(main): release 0.1.53 #329

Merged

caugner deleted the webref-css7-support branch October 14, 2025 21:06

caugner mentioned this pull request Oct 16, 2025

chore(css-syntax): update ill cased links #331

Merged

	fn url_to_title_map(base_path: &Path) -> Result<BTreeMap<String, String>, DepsError> {
	fn spec_url_to_title_map(base_path: &Path) -> Result<BTreeMap<String, String>, DepsError> {

feat(css-syntax): migrate to @webref/css 7 #317

feat(css-syntax): migrate to @webref/css 7 #317

Uh oh!

Conversation

argl commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

<color> example formal syntax

Related issues and pull requests

Uh oh!

argl commented Sep 22, 2025

Uh oh!

argl commented Oct 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caugner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

argl commented Sep 18, 2025 •

edited

Loading

`<color>` example formal syntax