explico 0.4.0 → 0.5.0

package/src/components/starlight/CollapsibleSections.astro

@@ -0,0 +1,461 @@
+---
+/**
+ * Collapsible/persistent sections (docs/plans/collapsible-disclosure.md Part
+ * 3) — a runtime wrap over Starlight's static heading markup, the same
+ * progressive-enhancement approach `HeadingAnchorEnhancer.astro` and
+ * `KeyedFloatEnhancer.astro` already use, since `rehype-heading-anchors.mjs`
+ * doesn't nest a heading's following content under it at build time.
+ *
+ * **Authoring**: `rehype-heading-anchors.mjs` resolves each heading's
+ * collapsibility — a `[collapsible]`/`[collapsed]`/`[no-collapsible]` marker,
+ * or a site-wide default from `astro.config.mjs` when a heading has none —
+ * down to two plain attributes on the wrapper: `data-collapsible="true"` and
+ * `data-default-open="true"|"false"`. This component only ever reads those
+ * two; it knows nothing about markers, ranks, or site config. A heading
+ * without `data-collapsible` is left completely alone, exactly as if this
+ * component didn't exist — wrapping *every* heading (the site default for
+ * both `sections` and `subsections`) is a valid choice, but not the
+ * hardcoded one: most sections have no reason to hide, and wrapping one
+ * cascades width/font-size side effects into ordinary content (see the CSS
+ * overrides below and their comments for two that actually happened during
+ * development).
+ *
+ * For every opted-in heading, this wraps
+ * `[.sl-heading-wrapper, ...body-until-next-heading-of-equal-or-higher-rank]`
+ * (the same boundary `sectionParts()` in `./section-parts.ts` already finds
+ * for the deep-link flash) in a `<details class="sl-section-collapsible">`,
+ * with the body itself further wrapped in one `.sl-section-body` div — see
+ * below for why that inner wrapper exists.
+ *
+ * **Only the bare heading moves into `<summary>` — not its `.sl-anchor-link`
+ * copy-link icon.** Moving the whole `.sl-heading-wrapper` (heading + anchor
+ * together, matching how `rehype-heading-anchors` emits them) into
+ * `<summary>` breaks axe's `no-focusable-content` check — a `<summary>` must
+ * have no focusable descendants, full stop, no matter how its click handling
+ * is patched up. `Figure.astro` hit the same problem for its own title bar
+ * and solved it by keeping the anchor a sibling of `<summary>` rather than a
+ * child; this mirrors that, reusing the existing `.sl-heading-wrapper` div as
+ * that sibling-holding container.
+ *
+ * Headings are processed deepest-rank first (h6 before h2, etc.) so that by
+ * the time a shallower heading's `sectionParts()` walk runs, any nested
+ * child section is already wrapped in its own `<details>` and reads as one
+ * ordinary sibling — `sectionParts()`'s `querySelector(HEADINGS)` still finds
+ * the nested heading regardless of depth, so the rank check that stops the
+ * walk keeps working unchanged.
+ *
+ * **Three states, not two.** Besides `closed`/`open`, a collapsed section
+ * has a third `peeking` state entered on hover/focus: the *real* body content
+ * (not a clone — a clone couldn't stay in sync with anything interactive or
+ * later-hydrated inside it) renders at up to 10em tall, absolutely
+ * positioned so it overlays whatever comes next on the page without shifting
+ * it — then, if the reader clicks while peeking, it grows in place from
+ * that exact height to its full height, switching to normal flow so
+ * following content is pushed down in sync with the growth instead of
+ * jumping once the animation ends. A native closed `<details>`'s
+ * non-summary children can't be rendered at all (the HTML spec skips them
+ * outright, a rule no CSS can override — confirmed the hard way while
+ * building the print handling below), so `peeking` still has to force
+ * `details.open = true` to render anything; only `data-state` distinguishes
+ * a real expand from a peek. `wirePersistedDetails`'s own `toggle`-event
+ * listener is only fed a synthetic event on a genuine `open`/`closed`
+ * commit — never for a peek — so hovering never persists anything.
+ *
+ * Persistence goes through `../disclosure/persisted-disclosure` (keyed by
+ * heading `id` + page path, same convention as `Figure.astro`'s
+ * `figure:<id>` keys). This does *not* use `../disclosure/hover-preview`'s
+ * `attachHoverPeek` — that utility clones content into a single shared
+ * floating panel positioned near the trigger, built for a "reference card"
+ * feel; the peek here needs to be the real, in-place content, sized and
+ * positioned relative to its own section, animatable into a real expand.
+ *
+ * Wired only on lesson pages (see `LessonFooter.astro`), same gating as
+ * `HeadingAnchorEnhancer.astro`/`KeyedFloatEnhancer.astro` — and placed
+ * *before* `HeadingAnchorEnhancer` in that file so this component's own
+ * hashchange listener (which expands any collapsed ancestor section) runs
+ * before `HeadingAnchorEnhancer`'s flash/scroll listener, registered after
+ * it in document order.
+ */
+---
+
+<script>
+  import { HEADINGS, sectionParts } from './section-parts';
+  import {
+    wirePersistedDetails,
+    savePersistedOpenState,
+  } from '../disclosure/persisted-disclosure';
+
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    type State = 'closed' | 'peeking' | 'open';
+
+    // A collapsed section's peek caps at 10em, measured in the body's own
+    // font-size (reset to normal body text below, not the heading's larger
+    // size — see the CSS comment on `.sl-section-collapsible.sl-section-body`).
+    const peekMaxPx = (body: HTMLElement): number =>
+      (parseFloat(getComputedStyle(body).fontSize) || 16) * 10;
+
+    // A rapid state change (e.g. collapsing a section, then hovering it again
+    // before the collapse animation finishes) starts a *second* `growTo` on
+    // the same `body` while the first is still in flight. Without tracking
+    // this, the first animation's stale `finish()` still fires later (its
+    // `transitionend`/timeout don't know a newer call superseded them) and
+    // stomps on state a second, unrelated animation already moved on from —
+    // observed as a peek overlay that never closes after a collapse. Each
+    // `body` gets at most one live "cancel the previous run" callback.
+    const supersede = new WeakMap<HTMLElement, () => void>();
+
+    /**
+     * Animate `body`'s `max-height` from its current rendered height to
+     * `toPx`, calling `after` once the transition (or, with reduced motion,
+     * an immediate jump) finishes — unless a *later* `growTo` call on the
+     * same `body` supersedes this one first, in which case `after` never
+     * runs at all. Caller is responsible for anything that must happen
+     * *before* the animation starts (e.g. flipping `data-state` so
+     * `position` is already correct for the target state) — but not
+     * `overflow`: clipping to `hidden` for the animation's duration and
+     * clearing it again afterward (so the CSS class's own `overflow` value —
+     * `visible` for `open`, `auto` for `peeking` — takes back over) is
+     * entirely this function's job, every single call, so no call site can
+     * forget the cleanup half and leave a stray inline `overflow: hidden`
+     * behind (that exact bug once left a fully "open" section permanently
+     * clipped after a `peeking` animation elsewhere hadn't cleaned up after
+     * itself).
+     */
+    const growTo = (body: HTMLElement, toPx: number, after: () => void) => {
+      supersede.get(body)?.(); // cancel whatever this body was mid-animating
+      supersede.delete(body);
+
+      if (reduceMotion.matches) {
+        body.style.maxHeight = `${toPx}px`;
+        body.style.removeProperty('overflow');
+        after();
+        return;
+      }
+      const fromPx = body.getBoundingClientRect().height;
+      body.style.transition = 'none';
+      body.style.maxHeight = `${fromPx}px`;
+      body.style.overflow = 'hidden';
+      void body.offsetHeight; // force reflow so the jump above isn't animated
+      body.style.transition = '';
+
+      let done = false;
+      const cancel = () => {
+        if (done) return;
+        done = true;
+        window.clearTimeout(fallback);
+        body.removeEventListener('transitionend', onEnd);
+        body.style.removeProperty('overflow');
+      };
+      const finish = () => {
+        if (done) return;
+        cancel();
+        supersede.delete(body);
+        after();
+      };
+      const onEnd = (event: Event) => {
+        if (
+          event.target === body &&
+          (event as TransitionEvent).propertyName === 'max-height'
+        ) {
+          finish();
+        }
+      };
+      body.addEventListener('transitionend', onEnd);
+      // `fromPx === toPx` (nothing actually changes) never fires
+      // `transitionend` — this safety net still resolves `after`.
+      const fallback = window.setTimeout(finish, 260);
+      supersede.set(body, cancel);
+
+      requestAnimationFrame(() => {
+        body.style.maxHeight = `${toPx}px`;
+      });
+    };
+
+    for (const heading of Array.from(
+      root.querySelectorAll<HTMLElement>(HEADINGS),
+    )
+      .filter(
+        (heading) =>
+          !!heading.id &&
+          heading.closest<HTMLElement>('.sl-heading-wrapper')?.dataset
+            .collapsible === 'true',
+      )
+      // Deepest rank first — see the module comment above.
+      .sort((a, b) => Number(b.tagName[1]) - Number(a.tagName[1]))) {
+      const parts = sectionParts(heading);
+      const bodyParts = parts.slice(1);
+      const wrapper = heading.closest<HTMLElement>('.sl-heading-wrapper')!;
+
+      const details = document.createElement('details');
+      details.className = 'sl-section-collapsible';
+      details.dataset.state = 'closed' satisfies State;
+
+      const summary = document.createElement('summary');
+      summary.className = 'sl-section-summary';
+
+      const body = document.createElement('div');
+      body.className = 'sl-section-body';
+      for (const part of bodyParts) body.append(part);
+
+      // Capture the anchor link's position *before* moving the heading —
+      // once `heading` is gone, `wrapper`'s only remaining child is it.
+      const anchorLink = wrapper.querySelector<HTMLElement>(
+        ':scope > .sl-anchor-link',
+      );
+      summary.append(heading);
+      details.append(summary, body);
+
+      // The anchor link stays put as `details`'s sibling inside `wrapper`
+      // (see the module comment) — insert `details` right before it so
+      // heading/body content still comes first in DOM/tab order.
+      wrapper.classList.add('sl-section-titlebar');
+      if (anchorLink) wrapper.insertBefore(details, anchorLink);
+      else wrapper.append(details);
+
+      // `wirePersistedDetails` sets `details.open` *after* `details` is
+      // attached above, not before — deliberately never set `.open` on the
+      // still-detached element. At least one browser has been observed
+      // mis-computing a nested `<table>`'s intrinsic (auto-layout) width
+      // when a `<details>` is built pre-opened and inserted already-open,
+      // versus being opened only after attachment.
+      const defaultOpen = wrapper.dataset.defaultOpen !== 'false';
+      wirePersistedDetails(details, `section:${heading.id}`, defaultOpen);
+      details.dataset.state = (details.open ? 'open' : 'closed') satisfies State;
+      const persistKey = `section:${heading.id}`;
+
+      // A real (non-peek) commit: the only place a choice gets persisted —
+      // via `savePersistedOpenState`, called *synchronously* with the
+      // intended end state, not by waiting for the animation and reading
+      // back `details.open` (which has to stay `true` for the *entire*
+      // close animation — the browser refuses to render a closed
+      // `<details>`'s content at all, so an `open → closed` collapse can't
+      // flip the attribute to `false` until the shrink finishes — a
+      // deferred read-and-save would otherwise race a reader who navigates
+      // away mid-animation and save the wrong value). `data-state` flips to
+      // `next` *before* animating: for `closed`→`open` there's no prior
+      // `position: absolute` to transition out of, so timing doesn't
+      // matter; for `open`→`closed` the body stays `position: static`
+      // throughout (nothing to switch), so following content rises in step
+      // with the shrink. The one transition that *does* need mid-animation
+      // care — growing out of a peek — is `commitFromPeek` below, not this.
+      const commitOpenOrClosed = (next: 'open' | 'closed') => {
+        const goingOpen = next === 'open';
+        if (goingOpen) details.open = true; // render before animating/measuring
+        details.dataset.state = next satisfies State;
+        savePersistedOpenState(persistKey, goingOpen);
+        growTo(body, goingOpen ? body.scrollHeight : 0, () => {
+          details.open = goingOpen;
+          if (goingOpen) body.style.maxHeight = '';
+        });
+      };
+
+      // Promote an in-progress peek to a real, persisted expand — grown
+      // from the peek's *current* rendered height, not from zero. The
+      // `position: absolute` → `static` switch happens the instant before
+      // growing (with the peek height frozen as an explicit `max-height`
+      // first) so following content starts moving down from the exact
+      // moment the box re-enters normal flow, not after the growth
+      // animation completes.
+      const commitFromPeek = () => {
+        const peekPx = body.getBoundingClientRect().height;
+        body.style.transition = 'none';
+        body.style.maxHeight = `${peekPx}px`;
+        void body.offsetHeight; // reflow with the peek height frozen…
+        details.dataset.state = 'open' satisfies State; // …then re-enter flow at that same height
+        void body.offsetHeight; // reflow again before animating the grow
+        body.style.transition = '';
+        savePersistedOpenState(persistKey, true);
+        growTo(body, body.scrollHeight, () => {
+          details.open = true;
+          body.style.maxHeight = '';
+        });
+      };
+
+      const enterPeek = () => {
+        if (details.dataset.state !== 'closed') return;
+        details.open = true; // render — see the module comment
+        details.dataset.state = 'peeking' satisfies State;
+        growTo(body, Math.min(body.scrollHeight, peekMaxPx(body)), () => {});
+      };
+
+      const exitPeek = () => {
+        if (details.dataset.state !== 'peeking') return;
+        growTo(body, 0, () => {
+          details.dataset.state = 'closed' satisfies State;
+          details.open = false;
+        });
+      };
+
+      // Debounced leave, mirroring `FloatRefLayer.astro`'s `scheduleLeave`:
+      // a pointer move from the title into the peeked body itself must not
+      // close it. `:focus-visible`, not `:focus-within` — the same reasoning
+      // as `hover-preview.ts`'s own `scheduleLeave`: clicking `summary` to
+      // commit a peek (or to collapse an open section) leaves it focused as
+      // an ordinary side effect of the click, and that focus lingers
+      // (`:focus-within` stays true) long after the pointer has moved
+      // elsewhere — which, before this used `:focus-visible` instead, meant
+      // a peek entered right after such a click could never close on
+      // mouse-leave at all. `:focus-visible` is only true for
+      // keyboard/keyboard-equivalent focus, so a mouse click doesn't count,
+      // but a reader who actually tabbed here still keeps their peek open.
+      let leaveTimer: number | null = null;
+      const cancelLeave = () => {
+        if (leaveTimer !== null) {
+          window.cancelAnimationFrame(leaveTimer);
+          leaveTimer = null;
+        }
+      };
+      const scheduleLeave = () => {
+        cancelLeave();
+        leaveTimer = window.requestAnimationFrame(() => {
+          leaveTimer = null;
+          if (!details.matches(':hover') && !summary.matches(':focus-visible')) {
+            exitPeek();
+          }
+        });
+      };
+
+      summary.addEventListener('pointerenter', (event) => {
+        if (event.pointerType === 'touch') return;
+        cancelLeave();
+        enterPeek();
+      });
+      summary.addEventListener('focus', enterPeek);
+      details.addEventListener('pointerleave', (event) => {
+        if (event.pointerType === 'touch') return;
+        scheduleLeave();
+      });
+      details.addEventListener('focusout', scheduleLeave);
+
+      summary.addEventListener('click', (event) => {
+        // Fully own the open/close/peek state machine — never let the
+        // native toggle run (it only knows two states and would fight the
+        // grow-from-peek animation).
+        event.preventDefault();
+        cancelLeave();
+        if (details.dataset.state === 'peeking') commitFromPeek();
+        else if (details.dataset.state === 'open') commitOpenOrClosed('closed');
+        else commitOpenOrClosed('open');
+      });
+    }
+
+    // A closed native `<details>` doesn't just hide its non-`<summary>`
+    // children visually — the HTML spec skips rendering them outright, so a
+    // heading nested inside one isn't scrollable, focusable, or even present
+    // in layout until that ancestor opens. `includeSelf` controls whether the
+    // *targeted* heading's own section is forced open too, or left exactly
+    // as the reader last set it:
+    //  - a fresh navigation with a hash already in the URL (an external/
+    //    bookmarked deep link — see the initial call below, made once at
+    //    startup, not from a `hashchange` event) is a reader's only way in,
+    //    so it must fully open the destination, not just its ancestors.
+    //  - an in-page jump — clicking an "On this page" sidebar link, a
+    //    cross-reference, or a section's own permalink icon — is a reader
+    //    already on the page choosing to look *at* a title; forcing its
+    //    content open too would show content they may have deliberately
+    //    collapsed, without the animation or the following-content reflow a
+    //    real expand gets everywhere else. Only its ancestors (structurally
+    //    unavoidable) open; the target itself is just scrolled to and
+    //    flashed by `HeadingAnchorEnhancer`, same as an always-visible
+    //    heading gets.
+    const expandAncestors = (id: string, includeSelf: boolean) => {
+      if (!id) return;
+      const target = document.getElementById(id);
+      if (!target) return;
+      let details = target.closest<HTMLDetailsElement>(
+        '.sl-section-collapsible',
+      );
+      if (details && !includeSelf) {
+        details =
+          details.parentElement?.closest<HTMLDetailsElement>(
+            '.sl-section-collapsible',
+          ) ?? null;
+      }
+      while (details) {
+        if (details.dataset.state !== 'open') {
+          details.dataset.state = 'open' satisfies State;
+          details.open = true;
+          details.dispatchEvent(new Event('toggle'));
+        }
+        details =
+          details.parentElement?.closest<HTMLDetailsElement>(
+            '.sl-section-collapsible',
+          ) ?? null;
+      }
+    };
+
+    const currentHashId = (): string => {
+      try {
+        return decodeURIComponent(location.hash.slice(1));
+      } catch {
+        return location.hash.slice(1);
+      }
+    };
+
+    expandAncestors(currentHashId(), true);
+    window.addEventListener('hashchange', () => {
+      expandAncestors(currentHashId(), false);
+    });
+
+    // Print must always show every section, regardless of on-screen
+    // collapse state. Unlike ordinary hidden content, a closed native
+    // `<details>`'s non-summary children aren't just styled hidden — the
+    // HTML spec has the browser skip rendering them outright, a rule no
+    // amount of author CSS (`display`, `content-visibility`, `!important`)
+    // can override. Only the `open` *attribute* controls it, so this has to
+    // force every section's real `open`/`data-state` for print in JS and
+    // restore afterward. `beforeprint`/`afterprint` cover an actual print
+    // dialog; `matchMedia('print')`'s `change` event additionally covers
+    // tools (headless browsers, some print-preview UIs) that flip the media
+    // type without firing those events.
+    let savedState: { open: boolean; state: string }[] | null = null;
+
+    const expandAllForPrint = () => {
+      if (document.querySelector('[data-explico-print-controller]')) return;
+      if (savedState) return; // already expanded for a print in progress
+      const all = Array.from(
+        document.querySelectorAll<HTMLDetailsElement>(
+          '.sl-section-collapsible',
+        ),
+      );
+      savedState = all.map((d) => ({
+        open: d.open,
+        state: d.dataset.state ?? 'closed',
+      }));
+      for (const d of all) {
+        d.open = true;
+        d.dataset.state = 'open' satisfies State;
+        (d.querySelector<HTMLElement>(':scope > .sl-section-body') ??
+          undefined)?.style.removeProperty('max-height');
+      }
+    };
+
+    const restoreAfterPrint = () => {
+      if (!savedState) return;
+      const all = document.querySelectorAll<HTMLDetailsElement>(
+        '.sl-section-collapsible',
+      );
+      all.forEach((d, i) => {
+        const saved = savedState?.[i];
+        if (!saved) return;
+        d.open = saved.open;
+        d.dataset.state = saved.state;
+        d.querySelector<HTMLElement>(':scope > .sl-section-body')?.style
+          .removeProperty('max-height');
+      });
+      savedState = null;
+    };
+
+    window.addEventListener('beforeprint', expandAllForPrint);
+    window.addEventListener('afterprint', restoreAfterPrint);
+    window.matchMedia('print').addEventListener('change', (event) => {
+      if (event.matches) expandAllForPrint();
+      else restoreAfterPrint();
+    });
+  })();
+</script>