Skip to content

Build MDN annotation panels from data on first open - #506

Open
zcorpan wants to merge 7 commits into
mainfrom
mdn-anno-hydration
Open

zcorpan wants to merge 7 commits into
mainfrom
mdn-anno-hydration

Conversation

@zcorpan

@zcorpan zcorpan commented Aug 31, 2026

Copy link
Copy Markdown
Member

wattsi now emits an MDN annotation panel as a <details> carrying a compact "data-mdn" attribute instead of a pre-built, CSS-hidden support table, which takes ~58k elements and ~1.8MB of markup out of the HTML Standard. This builds the table from that attribute the first time a panel is opened.

<details> handles the disclosure itself, so there is no toggle left to do. Hydration hangs off a capture-phase click on the summary, which arrives before the browser opens the panel so it never flashes empty, with "toggle" as the catch-all for a panel opened some other way (find-in-page, a fragment navigation into it). "toggle" doesn't bubble, hence capture. "beforetoggle" would be the tidier hook, but Chrome doesn't fire it for <details> yet.

The CSS additions are the <details> half of the same block, kept identical to Bikeshed's mdn-anno.css because Bikeshed's specs load this stylesheet too and already emit <details>. Nothing is removed: archived commit snapshots load this stylesheet at runtime and can never be rebuilt, so the .wrapped and .mdn-anno-btn rules have to stay indefinitely. Same reason the script has to keep understanding every data-mdn version it has ever shipped.

Verified against a spec build: all 1060 panels hydrate to the DOM the old markup had, modulo the wording now taken from Bikeshed. A legacy panel plus its inline toggleStatus still expands correctly under the new stylesheet, and a Bikeshed panel shows no computed-style change at all. Also checked that an unknown trailing cell is ignored, that truncated cells drop their rows without leaving dangling separators, that reopening a panel doesn't duplicate its body, and that an unknown version leaves the panel empty with a console warning.


This is step 1 of whatwg/wattsi#169

Generated by Claude.

wattsi now emits an MDN annotation panel as a <details> carrying a compact
"data-mdn" attribute instead of a pre-built, CSS-hidden support table, which
takes ~58k elements and ~1.8MB of markup out of the HTML Standard. This
builds the table from that attribute the first time a panel is opened.

<details> handles the disclosure itself, so there is no toggle left to do.
Hydration hangs off a capture-phase click on the summary, which arrives
before the browser opens the panel so it never flashes empty, with "toggle"
as the catch-all for a panel opened some other way (find-in-page, a fragment
navigation into it). "toggle" doesn't bubble, hence capture. "beforetoggle"
would be the tidier hook, but Chrome doesn't fire it for <details> yet.

The CSS additions are the <details> half of the same block, kept identical
to Bikeshed's mdn-anno.css because Bikeshed's specs load this stylesheet too
and already emit <details>. Nothing is removed: archived commit snapshots
load this stylesheet at runtime and can never be rebuilt, so the .wrapped
and .mdn-anno-btn rules have to stay indefinitely. Same reason the script
has to keep understanding every data-mdn version it has ever shipped.

Verified against a spec build: all 1060 panels hydrate to the DOM the old
markup had, modulo the wording now taken from Bikeshed. A legacy panel plus
its inline toggleStatus still expands correctly under the new stylesheet,
and a Bikeshed panel shows no computed-style change at all. Also checked
that an unknown trailing cell is ignored, that truncated cells drop their
rows without leaving dangling separators, that reopening a panel doesn't
duplicate its body, and that an unknown version leaves the panel empty with
a console warning.
@zcorpan zcorpan mentioned this pull request Aug 31, 2026
7 tasks done
@zcorpan
zcorpan requested a review from tabatkins September 1, 2026 21:26
`data-mdn` now carries the article's path below `/docs/` rather than below
`/docs/Web/`, since a few articles are `/docs/Glossary/` or `/docs/Learn/`
pages. The label drops the area and the category as before.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
zcorpan and others added 2 commits September 24, 2026 14:07
`.mdn-anno > .feature`'s 20px clears the floated `.mdn-anno-btn`, and a
`<summary>` isn't floated. Matching `summary +` leaves the archived snapshots'
button clearing as it was. Bikeshed has the same dead space and its own copy of
this stylesheet to fix it in: speced/bikeshed#3325.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
zcorpan and others added 3 commits September 24, 2026 16:15
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Bikeshed uses 6px too as of speced/bikeshed#3324.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant