Markup/styles for MDN and CanIUse panels changed

[tabatkins]

Hey all, recently I rejiggered the HTML and some of the styling for MDN and CanIUse panels. Y'all turn off Bikeshed's version of the styles and self-host identical ones, so the panels are slightly wonky now; you probably want to update your own versions.

You can find the changes at speced/bikeshed@d96c4ef#diff-1bb46e08457d4fd8605fd7523a0f43a30cba7888c4a38361df1ee74df8e5f132 and speced/bikeshed@d96c4ef#diff-c9d4a7b710464529076203003bf832d3e67b1f6bf4cf900ddb78d4b94c56d464.

[domenic]

Hmm, am I reading right that these now require JavaScript to work?

[tabatkins]

Ah yes, I unified the positioning code for them and CanIUse panels to rely on a quick JS pass to give them positions. Most importantly, this was done to avoid the overlapping that was trivial to trigger before. It also happens to make the markup insertion vastly simpler and more reliable; I no longer have to root around to try and find a nearby sibling or ancestor that can validly hold the element.

(But this'll change again once Anchor Positioning is shipped; I can then switch to using that in static CSS, with the JS pass as a backup for downlevel browsers.)

Edit: Actually I'll still run some JS to fixup overlaps anyway, but the majority of the positioning will work as intended without JS.

[domenic]

I think this is also being applied to <dfn> panels, leading to them looking squashed:

Note that we don't use caniuse panels.

There's also some script that's been inserted into the page, which is doing a bunch of console.log()s of numbers on load.

I spent some time looking at this but I'm pretty discouraged. The resulting markup is different enough from what we output in HTML that unified styles no longer work. And it seems like it's going to be quite difficult to continue with our strategy of externalizing shared resources in this way, since Bikeshed is making changes here.

Fundamentally we've gotten ourselves into a bad place by: (a) having to maintain the HTML build tools ourselves, while attempting to keep feature parity with Bikeshed; (b) not having a stable "API" that both tools can share. We'd been assuming the outputted HTML for panels was such an API, but it seems that's not true.

I see the following options:

1. Turn off Bikeshed-generated dfn panels entirely. Generate them in JS for both HTML (as it is currently) and Bikeshed specs (as we used to do before Bikeshed added support), using shared scripts/styles.

2. Fork HTML and Bikeshed-generated dfn panels into separate paths. Let Bikeshed put stuff inline in every spec.

3. Fork HTML and Bikeshed-generated dfn panels into separate paths. Do a one-time copy to externalize the Bikeshed styles and scripts, and remember to keep updating them whenever Bikeshed changes.

4. Attempt to align HTML's outputs and Bikeshed's outputs, probably for both dfn panels and MDN. Use externalized shared stylesheets, and introduce a new externalized script. (Possibly replacing standard-mdn-annos.js.)

(1) gives us more full control, which is helpful to avoid these problems going forward. But it doesn't solve MDN annotations. Admittedly those are a lesser issue.

(2) or (3) reduce maintenance burden so that we're fighting Bikeshed less, at the cost of a worse user experience. (JS running on load and resize; potentially extra bytes in every download instead of shared/cached.)

(4) is a decent bit of work of work now, and sets us up for continued work in the future when Bikeshed makes more changes here.

I'm currently leaning toward (1), plus (3) for MDN panels only.

[domenic]

/cc @andreubotella who worked on this previously in whatwg/whatwg.org#343 and related PRs.

[tabatkins]

I recommend either 1 or 2. I'd prefer 2 to reduce the amount of UI forking WHATWG does relative to W3C specs, but if y'all really prefer 1 I'm okay with that; it will at least avoid breaking you when we update something, at the cost of forked development meaning one or the other will lag when upgrades occur. We're doing more fiddling with the panels right now, and so 3/4 will continue requiring (significant!) edits, which is pretty bad for both of us.

In particular, we're moving dfn panel generation to JS; the HTML for the dfn panels is a significant chunk of the whole spec's weight, but tons of it is simple repeated structure. Shipping a much more compact JSON structure and hydrating it on load looks to offer significant savings (haven't measured it yet, tho).

JS running on load/resize isn't significant for users. The panels don't affect overall layout, so there's no jitter; at worst you won't get a panel if you click on something in the first fraction of a second the page loads in. The resize positioning is similarly minimal, and the benefits of avoiding overlapped panels (which are simply unusable currently, when it happens) is significant. The scripts themselves are very small as well, well within the saved bytes from switching to a JSON blob.

[tabatkins]

Okay, I'm ready now to cut a new Bikeshed release, with the new dfn panel generation code. (And some other features that motivate a new release sooner rather than later.) If I do so, tho, it'll break WHATWG's dfn panels as well. So we need to resolve to go with one of these options.

[tabatkins]

Okay, when pinged about this Domenic said he didn't have any time to work on this this quarter and then stopped responding to me, so I've gone ahead and done a minimal fix to the boilerplates to avoid breaking WHATWG specs. The styling is not ideal right now, since dfn panels are getting styled both by Bikeshed and by the whatwg standard.css file, but it's acceptable.

This unblocks the Bikeshed release, so 3.11.22 is live now.