feat(api): collapsible package groups with remembered state and a roll animation

Each Tier 2 group on /api/ is now a <details>, open by default, and a visitor's
collapsed groups come back on their next visit. "Older versions" gets the same
roll, having just gained the same hover.

Four things about this were not obvious and are worth recording.

THE HEADING STAYS MARKDOWN. [[toc]] is built by markdown-it-table-of-contents from
the markdown AST, not from the DOM, so an <h3> written by hand inside the
<details> would have vanished from the "On this page" sidebar with nothing failing.
Keeping `### {{ group.group }}` on its own line with blank lines around it works
because markdown-it ends an HTML block at a blank line — verified across four
arrangements before committing to one, and verified again in the built page: the
same four ids (`data-%26-events` and friends) and the same four sidebar entries.

THE HEADING GOES IN THE SUMMARY, not the body, so a collapsed group is still a
visible anchor target when its sidebar link is clicked.

THE CLASS IS .api-pkg-group, NOT .api-group. `.api-group` was already taken by the
symbol-kind labels in the API reference sidebar ("Classes", "Enumerations"), whose
rule is uppercase, letter-spaced, muted 12.5px — and it inherited into every
heading, package name and blurb in the section.

THE STATE SCRIPT IS INLINE AND PARSER-BLOCKING. It must run after the <details>
exist and before they paint; site.js is `defer`, and this page is long enough that
first paint lands well before parsing ends, so a remembered-closed group would
flash open. Two further details: Chrome fires `toggle` when a <details open> is
INSERTED, not only when its state changes, so a naive handler wrote to storage on
every page load including a first visit — now it skips a write that would not change
the value and never creates the key just to record "nothing is closed". And `toggle`
does not bubble, so the listener is in the capture phase.

The roll is driven by hand because <details> cannot animate: the body is not
rendered while closed, so there is nothing to transition from, and the browser flips
the state on click leaving nothing to animate out. Opening sets `open` first and
grows the body from zero; closing animates down and only then clears `open`. Height,
padding and margin all animate, or the spacing would remain at zero height. Respects
prefers-reduced-motion by standing aside and letting <details> behave natively.

Also corrects a wrong assumption I had committed a rule for: a closed <details> does
NOT need help hiding a body that sets `display: flex`. Forcing
`display: flex !important` on a closed group leaves it still unpainted and still not
hit-testable — it keeps a layout box, so getBoundingClientRect reports a height, and
that measurement is what makes it look visible when it is not.

All four site checks pass; sitemap-api.xml unchanged at 274 URLs.

Author: Mikhus

src/_data/apiPackages.js

@@ -16,10 +16,18 @@ const { shippedGroups, TAGS } = require('../../scripts/lib/api-packages');
 // and is the real repository, so do not "correct" this to follow npm.
 const repoOf = (name) => `https://github.com/imqueue/${name}`;
 
+// Stable key for remembering a group's collapsed state in localStorage, derived
+// from the name rather than configured so a new group needs nothing extra. Renaming
+// a group changes its id and so resets that group to open, which is the right
+// default for what is effectively a new section.
+const idOf = (group) =>
+  group.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+
 module.exports = () => ({
-  // [{ group, packages: [{ name, scoped, url, repo, blurb, tags: [{ label, exclusive }] }] }]
+  // [{ group, id, packages: [{ name, scoped, url, repo, blurb, tags: [{ label, exclusive }] }] }]
   groups: shippedGroups().map(({ group, packages }) => ({
     group,
+    id: idOf(group),
     packages: packages.map(p => ({
       name: p.name,
       scoped: `@imqueue/${p.name}`,

src/_shared/css/prose.css

@@ -86,10 +86,47 @@
 .prose .api-older summary::-webkit-details-marker { display: none; }
 .prose .api-older summary::before { content: "▸"; color: var(--muted); margin-right: 8px; display: inline-block; }
 .prose .api-older[open] summary::before { content: "▾"; }
+/* See the note on .api-pkg-group: `open` is held for the length of a roll-up, so the
+   marker is flipped from the roll state instead of from `open`. */
+.prose .api-older[data-rolling="close"] summary::before { content: "▸"; }
 .prose .api-older-body { padding: 0 18px 16px; display: flex; flex-direction: column; gap: 10px; font-family: var(--font-mono); font-size: 14.5px; }
 .prose .api-older-body a { color: var(--accent); margin-right: 10px; }
 .prose .api-older-pkg { color: var(--muted); margin-right: 10px; }
 
+/* Each Tier 2 group is collapsible, open by default, state remembered per visitor.
+   Deliberately NOT boxed like .api-older: the group heading is a structural heading
+   in the page outline, and giving it a surface and a border would make four sections
+   read as four cards and flatten the hierarchy the headings exist to create. So the
+   only affordances are the marker, the pointer and the accent on hover — the same
+   accent token as everything else here.
+
+   NOT `.api-group`: that name is already taken, by the symbol-kind labels in the API
+   reference sidebar ("Classes", "Enumerations") a few rules below. Reusing it made
+   every heading, name and blurb inside these groups inherit that rule's uppercase,
+   letter-spacing and muted 12.5px. Hence `.api-pkg-group`, matching the
+   .api-pkg-list / .api-pkg-link family it belongs to. */
+.prose .api-pkg-group { margin: 0; }
+/* The h3's own `margin: 30px 0 10px` moves to the summary, so the vertical rhythm
+   is byte-for-byte what it was before these became <details> — a flex row would not
+   collapse the heading's block margins with its neighbours, and zeroing them without
+   restating them here would jam each group against the list above it. */
+.prose .api-pkg-group > summary { cursor: pointer; list-style: none; display: flex; align-items: baseline; gap: 8px; margin: 30px 0 10px; }
+.prose .api-pkg-group > summary::-webkit-details-marker { display: none; }
+.prose .api-pkg-group > summary::before { content: "▸"; color: var(--muted); font-family: var(--font-mono); font-size: 14px; transition: color .15s ease; }
+.prose .api-pkg-group[open] > summary::before { content: "▾"; }
+/* `open` stays set for the length of a roll-up so the list has something to animate
+   out, which would otherwise hold the marker at ▾ until the movement finished. This
+   flips it on the first frame instead, where the click expects it. */
+.prose .api-pkg-group[data-rolling="close"] > summary::before { content: "▸"; }
+.prose .api-pkg-group > summary h3 { margin: 0; }
+.prose .api-pkg-group > summary:hover h3, .prose .api-pkg-group > summary:hover::before { color: var(--accent); }
+/* No rule is needed to hide the list while the group is closed. A closed <details>
+   skips painting and hit-testing its non-summary children even when they carry an
+   explicit `display` — checked by forcing `display: flex !important` on a closed
+   group, where the list still did not paint and elementFromPoint still returned the
+   container behind it. It does keep a layout box, so getBoundingClientRect reports a
+   height for it; that measurement is what makes it look visible when it is not. */
+
 /* Tier 2 groups on /api/ — one flat list per group, tags as chips on the entry.
    Deliberately lighter than .api-ref-card: the two spine cards stay the visual
    anchor of the section, and 14 cards of equal weight would flatten that. */

src/org/api/index.md

@@ -114,18 +114,167 @@ Browse the complete generated reference for the latest release — every class,
 
      Only `shipped` packages appear. A `planned` package has no pages yet, so
      listing it would ship a 404 and fail check:links. There are no archived
-     versions to list for any of these: Tier 2 is `latest` only. -->
+     versions to list for any of these: Tier 2 is `latest` only.
+
+     Each group is a <details>, open by default, and its state is remembered per
+     visitor. Two details of the markup are load-bearing:
+
+       * The `### heading` stays MARKDOWN, on its own line with blank lines around
+         it. markdown-it ends an HTML block at a blank line, so the heading is still
+         parsed as a heading and still reaches [[toc]] — which is generated from the
+         markdown AST, not the DOM, so an HTML <h3> written by hand would silently
+         vanish from the "On this page" sidebar.
+       * The heading goes in the <summary>, not the body, so a collapsed group is
+         still a visible anchor target when its sidebar link is clicked. -->
 {%- for group in apiPackages.groups %}
+<details class="api-pkg-group" open data-api-group="{{ group.id }}">
+<summary>
 
 ### {{ group.group }}
 
+</summary>
+
 <ul class="api-pkg-list">
 {%- for pkg in group.packages %}
 <li class="api-pkg"><a class="api-pkg-link" href="{{ pkg.url }}"><span class="api-pkg-name">{{ pkg.scoped | escape }}</span>{% if pkg.tags.size > 0 %} <span class="api-pkg-tags">{% for tag in pkg.tags %}<span class="topic-chip topic-chip--flat"{% if tag.exclusive %} title="Exclusive — pick at most one package carrying this tag"{% endif %}>{{ tag.label | escape }}</span>{% endfor %}</span>{% endif %}{% if apiVersions[pkg.name].latest %}<span class="api-ref-ver api-pkg-ver">v{{ apiVersions[pkg.name].latest }}</span>{% endif %}<span class="api-pkg-blurb">{{ pkg.blurb | escape }}</span></a></li>
 {%- endfor %}
 </ul>
+
+</details>
 {%- endfor %}
 
+<!-- Collapsed-group state, inline and parser-blocking ON PURPOSE.
+     It has to run after these <details> exist and before they paint. site.js is
+     `defer`, so it runs only after the whole document is parsed — and this page is
+     long enough that first paint happens well before that, which would flash every
+     remembered-closed group open. head.html's no-FOUC theme script has the mirror
+     problem: it runs early but the elements do not exist yet.
+     Storing the CLOSED ids (not the open ones) is what makes a group added by a
+     later wave default to open without touching stored state. -->
+<script>
+(function () {
+  var KEY = 'imqueue-api-groups';
+  var groups = [].slice.call(document.querySelectorAll('.api-pkg-group[data-api-group]'));
+  var stored;
+
+  try { stored = JSON.parse(localStorage.getItem(KEY)); } catch (e) { stored = null; }
+  var shut = stored || [];
+
+  groups.forEach(function (el) {
+    if (shut.indexOf(el.getAttribute('data-api-group')) !== -1) {
+      el.removeAttribute('open');
+    }
+  });
+
+  // Derived from the DOM on every change rather than patched incrementally: that
+  // cannot produce a duplicate or a stale id, and it does not care in which order
+  // the events arrive — which matters, because they are not all user-driven.
+  function state() {
+    return JSON.stringify(groups.filter(function (el) { return !el.open; })
+      .map(function (el) { return el.getAttribute('data-api-group'); }));
+  }
+
+  // `toggle` does not bubble, so listen in the capture phase — that still reaches a
+  // non-bubbling event on the way down, and needs one listener rather than one per
+  // group.
+  //
+  // Chrome fires `toggle` when a <details open> is INSERTED, not only when its state
+  // changes, so simply loading this page queues one event per group before anyone has
+  // clicked anything. Writing unconditionally therefore wrote to storage on every
+  // visit, including a first visit — hence the two guards below: skip when the value
+  // has not changed, and never create the key just to record "nothing is closed".
+  document.addEventListener('toggle', function (e) {
+    var el = e.target;
+
+    if (!el.classList || !el.classList.contains('api-pkg-group')) { return; }
+
+    try {
+      var next = state();
+
+      if (next === '[]' && localStorage.getItem(KEY) === null) { return; }
+      if (next !== localStorage.getItem(KEY)) { localStorage.setItem(KEY, next); }
+    } catch (e2) {}
+  }, true);
+
+  // ---- roll down / roll up ------------------------------------------------
+  // <details> cannot be animated natively: the body is not rendered at all while
+  // the element is closed, so there is no height to transition from or to. The
+  // browser also flips the state the instant the summary is clicked, which leaves
+  // nothing on screen to animate out.
+  //
+  // So the open flag is driven by hand. Opening sets it first and animates the
+  // list up from zero; closing animates down and only then clears it, which is
+  // what keeps the content visible for the length of the roll-up.
+  var DURATION = 200;
+  var reduced = window.matchMedia
+    ? window.matchMedia('(prefers-reduced-motion: reduce)')
+    : { matches: false };
+
+  // Both disclosures on this page roll: the package groups and the "Older versions"
+  // list above them. Each needs its body named, because the element that grows is the
+  // one whose height is animated — a <details> has no single "content" child to find
+  // generically.
+  var ROLLS = [
+    { group: '.api-pkg-group', body: '.api-pkg-list' },
+    { group: '.api-older', body: '.api-older-body' },
+  ];
+
+  function roll(el, body) {
+    var summary = el.querySelector('summary');
+
+    if (!summary || !body || !body.animate) { return; }
+
+    summary.addEventListener('click', function (e) {
+      // Honour the OS setting by doing nothing and letting <details> behave
+      // natively — the state still changes, just without the movement.
+      if (reduced.matches) { return; }
+      // Ignore a click that lands mid-roll rather than queueing or reversing it.
+      if (el.hasAttribute('data-rolling')) { e.preventDefault(); return; }
+
+      e.preventDefault();
+      var opening = !el.open;
+
+      // The value, not just the presence, so the marker can flip at the start of a
+      // roll-up instead of waiting for `open` to clear at the end of it.
+      el.setAttribute('data-rolling', opening ? 'open' : 'close');
+
+      if (opening) { el.open = true; }
+
+      // Measured while open, so the target is the real laid-out height rather than
+      // a guess. Padding and margin ride along with it, or a body that has either
+      // would leave its spacing behind at zero height.
+      var box = getComputedStyle(body);
+      var end = {
+        height: body.scrollHeight + 'px',
+        marginBottom: box.marginBottom,
+        paddingTop: box.paddingTop,
+        paddingBottom: box.paddingBottom,
+        opacity: 1,
+      };
+      var start = { height: '0px', marginBottom: '0px', paddingTop: '0px', paddingBottom: '0px', opacity: 0 };
+      var frames = opening ? [start, end] : [end, start];
+
+      body.style.overflow = 'hidden';
+
+      var anim = body.animate(frames, { duration: DURATION, easing: 'ease' });
+
+      anim.onfinish = anim.oncancel = function () {
+        body.style.overflow = '';
+        // Only now, so the body was on screen for the whole roll-up.
+        if (!opening) { el.open = false; }
+        el.removeAttribute('data-rolling');
+      };
+    });
+  }
+
+  ROLLS.forEach(function (kind) {
+    [].forEach.call(document.querySelectorAll(kind.group), function (el) {
+      roll(el, el.querySelector(kind.body));
+    });
+  });
+})();
+</script>
+
 {% include "api/intro.md" %}
 {% include "api/rpc.md" %}
 {% include "api/mq.md" %}