explico 0.7.0 → 0.11.0

package/src/components/starlight/AboutPanel.astro

@@ -12,6 +12,15 @@
  * It is a plain `<details>` disclosure: the browser gives keyboard toggle and
  * `aria-expanded` for free; the inline script only adds Escape-to-close and
  * outside-click-to-close.
+ *
+ * The panel also *publishes* the identity it displays: the `data-knowledge-*`
+ * and `data-engine-version` attributes carry the same values as the rendered
+ * text. A build check that wants to confirm the shipped page really carries the
+ * configured version would otherwise have to match the panel's prose and its
+ * `version · date` join, which pins a course's test to one version string and
+ * makes the check fail on every bump; a bare version substring is not even
+ * scoped to the panel, so the engine's own version elsewhere on the page can
+ * satisfy it. These attributes are exact, scoped, and stable across a bump.
  */
 import { loadManifest } from '../../compiler/manifest';
 
@@ -32,7 +41,13 @@ const knowledgeLine = knowledge.date
   : knowledge.version;
 ---
 
-<details class="about" data-about-panel>
+<details
+  class="about"
+  data-about-panel
+  data-knowledge-version={knowledge.version}
+  data-knowledge-date={knowledge.date}
+  data-engine-version={engine.version}
+>
   <summary
     class="about-toggle"
     aria-label={`About ${material.name}`}
@@ -47,7 +62,7 @@ const knowledgeLine = knowledge.date
     <dl class="about-facts">
       <div>
         <dt>Knowledge version</dt>
-        <dd>{knowledgeLine}</dd>
+        <dd data-knowledge-line>{knowledgeLine}</dd>
       </div>
       <div>
         <dt>Engine</dt>
@@ -164,11 +179,12 @@ const knowledgeLine = knowledge.date
       max-height: min(70vh, 34rem);
       overflow-y: auto;
       padding: 1rem;
-      border: 1px solid var(--sl-color-gray-5);
-      border-top: 0.25rem solid var(--sl-color-accent);
-      border-radius: 0.65rem;
+      /* Course logistics: the meta tier's surface, border and radius
+         (`surfaces.css`), plus the overlay shadow every floating card has. */
+      border: var(--ex-edge-border);
+      border-radius: var(--ex-radius-meta);
       color: var(--sl-color-text);
-      background: var(--sl-color-bg);
+      background: var(--ex-surface-tint-neutral);
       box-shadow: var(--sl-shadow-lg);
       font-size: var(--sl-text-xs);
       line-height: 1.5;

package/src/components/starlight/CollapsibleSections.astro

@@ -32,10 +32,15 @@
  * 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.
+ * is patched up. So the anchor stays a sibling of `<summary>` rather than a
+ * child — the same reason a float's caption line keeps its links outside any
+ * `<summary>` — reusing the existing `.sl-heading-wrapper` div as that
+ * sibling-holding container.
+ *
+ * A `<Memo>` and a `<Fold>` are folded here too: each bar is an `<h6>` in a
+ * heading wrapper of its own (`Memo.astro`, `Fold.astro`), with its default
+ * and its `rememberState` on the wrapper (`data-default-open`,
+ * `data-remember-state="false"` to keep the default on every visit).
  *
  * Headings are processed deepest-rank first (h6 before h2, etc.) so that by
  * the time a shallower heading's `sectionParts()` walk runs, any nested
@@ -69,6 +74,34 @@
  * 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.
  *
+ * **A closed section must look closed on every screen.** The chevron alone
+ * isn't enough: on wide screens it sits in the gutter left of the title, and
+ * on a phone there is no gutter — it used to render off-screen, leaving a
+ * collapsed section indistinguishable from a plain heading. So `<summary>`
+ * also carries two `aria-hidden` spans after the heading:
+ * `.sl-section-hint` — "(tap to expand)" / "(click to expand)", narrow or
+ * touch screens only, where `global.css` also moves the chevron into the
+ * title line — and `.sl-section-stub`, a "Hidden here: 2 paragraphs, 1
+ * equation" line (`./section-summary.ts`) on every screen. Both show only
+ * while the section isn't `open`, and both are part of the tap target. The
+ * heading brings its outline number along (`data-sec-number`, printed by
+ * `global.css`): a narrow screen hides it on an open section but shows it on a
+ * closed one, which is where it says what is folded away.
+ *
+ * **Print follows the screen** (`../disclosure/print-as-shown.ts`): an open
+ * section prints in full, a closed one as its title plus a "(content
+ * collapsed — full text: …)" note with the section's permalink.
+ *
+ * **Carded sections** (docs/plans/titles-and-containers.md Part 2): a
+ * wrapper with `data-card="accent"|"meta"` — a `[card]` / `[card=meta]`
+ * heading marker, or a knowledge check (`AssessmentSet.astro`) — has its whole
+ * section, heading and body, moved into one `div.ex-section-card` carrying
+ * that tier's class from `surfaces.css`. Same boundary, same deepest-first
+ * order: a card nested in a section reads as one sibling holding its heading,
+ * so the parent's walk still sees it. A section that is both collapsible and
+ * carded is collapsed first, then its titlebar — which by then holds the
+ * whole section — goes into the card.
+ *
  * 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
@@ -80,10 +113,14 @@
 
 <script>
   import { HEADINGS, sectionParts } from './section-parts';
+  import { collectHiddenContent, hiddenContentParts } from './section-summary';
   import {
     wirePersistedDetails,
     savePersistedOpenState,
   } from '../disclosure/persisted-disclosure';
+  import { installPrintAsShownFallback } from '../disclosure/print-as-shown';
+  import { CARD_CONSTANTS } from '../card-manager';
+  import { startTrip, type Trip } from '../card-travel';
 
   (() => {
     const root = document.querySelector('.sl-markdown-content');
@@ -91,6 +128,20 @@
 
     const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
 
+    // Every section peek the pointer is travelling from, fed by one listener.
+    const peekTrips = new Set<Trip>();
+    document.addEventListener(
+      'pointermove',
+      (event) => {
+        if (event.pointerType === 'touch') return;
+        for (const trip of [...peekTrips]) {
+          trip.move({ x: event.clientX, y: event.clientY });
+          if (!trip.active) peekTrips.delete(trip);
+        }
+      },
+      { passive: true },
+    );
+
     type State = 'closed' | 'peeking' | 'open';
 
     // A collapsed section's peek caps at 10em, measured in the body's own
@@ -176,20 +227,40 @@
       });
     };
 
-    for (const heading of Array.from(
+    const CARD_TIERS = new Set(['accent', 'meta']);
+
+    const cardSection = (heading: HTMLElement, tier: string) => {
+      const parts = sectionParts(heading);
+      const card = document.createElement('div');
+      card.className = `ex-section-card ex-tier-${tier}`;
+      parts[0].before(card);
+      card.append(...parts);
+    };
+
+    const sectionHeadings = Array.from(
       root.querySelectorAll<HTMLElement>(HEADINGS),
     )
-      .filter(
-        (heading) =>
+      .filter((heading) => {
+        const wrapper = heading.closest<HTMLElement>('.sl-heading-wrapper');
+        return (
           !!heading.id &&
-          heading.closest<HTMLElement>('.sl-heading-wrapper')?.dataset
-            .collapsible === 'true',
-      )
+          (wrapper?.dataset.collapsible === 'true' ||
+            CARD_TIERS.has(wrapper?.dataset.card ?? ''))
+        );
+      })
       // Deepest rank first — see the module comment above.
-      .sort((a, b) => Number(b.tagName[1]) - Number(a.tagName[1]))) {
+      .sort((a, b) => Number(b.tagName[1]) - Number(a.tagName[1]));
+
+    for (const heading of sectionHeadings) {
+      const wrapper = heading.closest<HTMLElement>('.sl-heading-wrapper')!;
+      if (wrapper.dataset.collapsible === 'true') makeCollapsible(heading, wrapper);
+      const tier = wrapper.dataset.card ?? '';
+      if (CARD_TIERS.has(tier)) cardSection(heading, tier);
+    }
+
+    function makeCollapsible(heading: HTMLElement, wrapper: HTMLElement) {
       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';
@@ -208,6 +279,43 @@
         ':scope > .sl-anchor-link',
       );
       summary.append(heading);
+
+      // What a *closed* section shows beyond its title (styles in
+      // `global.css`; see the module comment): a "(tap to expand)" hint on
+      // narrow/touch screens and a "Hidden here: …" line on every screen.
+      // Both are `aria-hidden` — the native `<details>` already announces
+      // "collapsed", and the heading alone stays the summary's name.
+      const hint = document.createElement('span');
+      hint.className = 'sl-section-hint';
+      hint.setAttribute('aria-hidden', 'true');
+      summary.append(hint);
+      // A `<Fold>` whose bar names its floats (`data-bar-names-floats`)
+      // counts them here rather than naming them twice.
+      const { counts, named } = collectHiddenContent(body, HEADINGS, {
+        nameFloats: wrapper.dataset.barNamesFloats === undefined,
+      });
+      const hiddenParts = hiddenContentParts(counts, named);
+      if (hiddenParts) {
+        // Outer span collapses as a grid row; the inner one clips the text.
+        const stub = document.createElement('span');
+        stub.className = 'sl-section-stub';
+        stub.setAttribute('aria-hidden', 'true');
+        const stubText = document.createElement('span');
+        stubText.append('Hidden here: ');
+        hiddenParts.forEach((part, index) => {
+          if (index > 0) stubText.append(', ');
+          if (typeof part === 'string') {
+            stubText.append(part);
+            return;
+          }
+          const number = document.createElement('b');
+          number.textContent = part.number;
+          stubText.append(number, ` ${part.short}`);
+        });
+        stub.append(stubText);
+        summary.append(stub);
+      }
+
       details.append(summary, body);
 
       // The anchor link stays put as `details`'s sibling inside `wrapper`
@@ -223,10 +331,17 @@
       // 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.
+      // `data-remember-state="false"` (a `<Memo rememberState={false}>`)
+      // keeps the default on every visit; everything else remembers.
       const defaultOpen = wrapper.dataset.defaultOpen !== 'false';
-      wirePersistedDetails(details, `section:${heading.id}`, defaultOpen);
-      details.dataset.state = (details.open ? 'open' : 'closed') satisfies State;
+      const remember = wrapper.dataset.rememberState !== 'false';
       const persistKey = `section:${heading.id}`;
+      if (remember) wirePersistedDetails(details, persistKey, defaultOpen);
+      else details.open = defaultOpen;
+      details.dataset.state = (details.open ? 'open' : 'closed') satisfies State;
+      const save = (open: boolean) => {
+        if (remember) savePersistedOpenState(persistKey, open);
+      };
 
       // A real (non-peek) commit: the only place a choice gets persisted —
       // via `savePersistedOpenState`, called *synchronously* with the
@@ -247,7 +362,7 @@
         const goingOpen = next === 'open';
         if (goingOpen) details.open = true; // render before animating/measuring
         details.dataset.state = next satisfies State;
-        savePersistedOpenState(persistKey, goingOpen);
+        save(goingOpen);
         growTo(body, goingOpen ? body.scrollHeight : 0, () => {
           details.open = goingOpen;
           if (goingOpen) body.style.maxHeight = '';
@@ -269,7 +384,7 @@
         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);
+        save(true);
         growTo(body, body.scrollHeight, () => {
           details.open = true;
           body.style.maxHeight = '';
@@ -291,33 +406,60 @@
         });
       };
 
-      // 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;
+      // The peek closes when the reader leaves both the title and the peeked
+      // body — not the moment the pointer steps off them, but on the
+      // explanation cards' terms (rules C2 and C12 of
+      // docs/plans/hover-card-consistency.md, `../card-travel.ts`): heading
+      // back toward the body keeps it, anything else closes it after the
+      // cards' grace. `:focus-visible`, not `:focus-within` — the same
+      // reasoning as `hover-preview.ts`: 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 graceTimer: ReturnType<typeof setTimeout> | null = null;
+      let ownTrip: Trip | null = null;
+      const exitUnlessWanted = () => {
+        if (!details.matches(':hover') && !summary.matches(':focus-visible')) {
+          exitPeek();
+        }
+      };
       const cancelLeave = () => {
-        if (leaveTimer !== null) {
-          window.cancelAnimationFrame(leaveTimer);
-          leaveTimer = null;
+        if (ownTrip) {
+          ownTrip.end();
+          peekTrips.delete(ownTrip);
+          ownTrip = null;
         }
+        if (graceTimer !== null) clearTimeout(graceTimer);
+        graceTimer = null;
       };
       const scheduleLeave = () => {
         cancelLeave();
-        leaveTimer = window.requestAnimationFrame(() => {
-          leaveTimer = null;
-          if (!details.matches(':hover') && !summary.matches(':focus-visible')) {
-            exitPeek();
-          }
+        graceTimer = setTimeout(() => {
+          graceTimer = null;
+          exitUnlessWanted();
+        }, CARD_CONSTANTS.travelGraceMs);
+      };
+      const travelFrom = (apex: { x: number; y: number }) => {
+        cancelLeave();
+        const trip = startTrip(apex, {
+          graceMs: CARD_CONSTANTS.travelGraceMs,
+          restMs: CARD_CONSTANTS.travelRestMs,
+          tripMaxMs: CARD_CONSTANTS.travelTripMaxMs,
+          cardBox: () => body.getBoundingClientRect(),
+          triggerBox: () => summary.getBoundingClientRect(),
+          onExit: () => {
+            if (ownTrip === trip) cancelLeave();
+            exitUnlessWanted();
+          },
         });
+        if (!trip.active) return;
+        ownTrip = trip;
+        peekTrips.add(trip);
       };
 
       summary.addEventListener('pointerenter', (event) => {
@@ -326,9 +468,16 @@
         enterPeek();
       });
       summary.addEventListener('focus', enterPeek);
+      details.addEventListener('pointerenter', (event) => {
+        if (event.pointerType !== 'touch') cancelLeave();
+      });
       details.addEventListener('pointerleave', (event) => {
         if (event.pointerType === 'touch') return;
-        scheduleLeave();
+        if (details.dataset.state === 'peeking') {
+          travelFrom({ x: event.clientX, y: event.clientY });
+        } else {
+          scheduleLeave();
+        }
       });
       details.addEventListener('focusout', scheduleLeave);
 
@@ -342,6 +491,20 @@
         else if (details.dataset.state === 'open') commitOpenOrClosed('closed');
         else commitOpenOrClosed('open');
       });
+
+      // The browser opens a closed `<details>` by itself to show a match of
+      // find-in-page or a fragment inside it. Every open this state machine
+      // makes sets `data-state` in the same task, so an open that finds it
+      // still `closed` is the browser's: follow it, as a real expand.
+      details.addEventListener('toggle', () => {
+        if (!details.open || details.dataset.state !== 'closed') return;
+        if (details.hasAttribute('data-explico-temporary-open')) return;
+        supersede.get(body)?.();
+        supersede.delete(body);
+        details.dataset.state = 'open' satisfies State;
+        body.style.removeProperty('max-height');
+        save(true);
+      });
     }
 
     // A closed native `<details>` doesn't just hide its non-`<summary>`
@@ -402,60 +565,11 @@
       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();
-    });
+    // Print follows the screen: a section the reader left open prints in
+    // full, a closed (or merely peeking) one prints its title plus a
+    // "(content collapsed …)" note. `LessonExportActions.astro` does this
+    // when the course has the print controller; this covers the browser's
+    // own print on a course without it.
+    installPrintAsShownFallback();
   })();
 </script>