explico 0.7.0 → 0.11.0

package/src/components/disclosure/hover-preview.ts

@@ -4,19 +4,21 @@
  * once the pointer/focus leaves. See `docs/plans/collapsible-disclosure.md`
  * Part 0.
  *
- * This is deliberately not built on `../hover-panel.ts`'s `createHoverPanel`
- * — that engine is a single *reference* card with pin/jump semantics and a
- * cross-group exclusivity arbiter (`claimActiveSurface`); a collapsed-content
- * peek has no pin state and doesn't need to coordinate with the
- * notation/citation/float-ref panel group. It does reuse that group's
- * `requestAnimationFrame`-scheduled leave check (see `scheduleLeave` in
- * `FloatRefLayer.astro`) so a pointer move from the trigger onto the peek
- * itself doesn't cause a flicker-close.
+ * This is deliberately not an explanation card (`../card-manager.ts`): a
+ * peek has no pin state — its content is one click from being expanded for
+ * real — and takes no part in the cards' hover chain. It shares only their
+ * travel zone (rules C2 and C12 of `docs/plans/hover-card-consistency.md`,
+ * `../card-travel.ts`): after the pointer leaves the trigger toward the peek,
+ * the peek stays open while the pointer is on its way, another peek trigger
+ * crossed on the way is held back, and anywhere else the peek closes after
+ * the cards' grace.
  *
  * One peek panel is created lazily and shared across every trigger wired
  * with `attachHoverPeek` — only one can be hovered at a time, so reusing a
  * single element avoids paying DOM-churn cost per hover.
  */
+import { CARD_CONSTANTS } from '../card-manager';
+import { startTrip, type Point, type Trip } from '../card-travel';
 
 export interface HoverPeekOptions {
   /**
@@ -35,17 +37,23 @@ export interface HoverPeekOptions {
 let panel: HTMLElement | null = null;
 let scroller: HTMLElement | null = null;
 let activeTrigger: HTMLElement | null = null;
-let leaveTimer: number | null = null;
+let trip: Trip | null = null;
+let graceTimer: ReturnType<typeof setTimeout> | null = null;
 let globalListenersReady = false;
+/** The pointer's last position: where it was when it left a trigger (see `../card-manager.ts`). */
+let lastPointer: Point | null = null;
+/** Each wired trigger's `show`, so resting on one mid-trip can switch to it. */
+const showFor = new WeakMap<HTMLElement, () => void>();
 
 function cancelLeave(): void {
-  if (leaveTimer !== null) {
-    window.cancelAnimationFrame(leaveTimer);
-    leaveTimer = null;
-  }
+  trip?.end();
+  trip = null;
+  if (graceTimer !== null) clearTimeout(graceTimer);
+  graceTimer = null;
 }
 
 function close(): void {
+  cancelLeave();
   if (!panel) return;
   panel.hidden = true;
   scroller?.replaceChildren();
@@ -63,26 +71,70 @@ export function closeHoverPeek(trigger: HTMLElement): void {
   if (activeTrigger === trigger) close();
 }
 
+function closeUnlessWanted(): void {
+  if (!activeTrigger || !panel) return;
+  // `:focus-visible`, not `=== document.activeElement` / `:focus`: the
+  // trigger is very often something like a `<summary>` that a *click* also
+  // focuses as a side effect (e.g. clicking it to toggle a `<details>`) — a
+  // plain focus check would then treat that leftover, non-keyboard focus as
+  // "still viewing it" forever, since nothing else ever takes focus to fire
+  // `blur`. `:focus-visible` is only true for focus a browser considers
+  // keyboard/keyboard-equivalent, so a mouse click doesn't leave the peek
+  // stuck open after the pointer leaves.
+  const stillActive =
+    activeTrigger.matches(':hover') ||
+    activeTrigger.matches(':focus-visible') ||
+    panel.matches(':hover') ||
+    panel.matches(':focus-within');
+  if (!stillActive) close();
+}
+
+/** The cards' grace: close after it unless the peek is wanted again by then. */
 function scheduleLeave(): void {
   cancelLeave();
-  leaveTimer = window.requestAnimationFrame(() => {
-    leaveTimer = null;
-    if (!activeTrigger || !panel) return;
-    // `:focus-visible`, not `=== document.activeElement` / `:focus`: the
-    // trigger is very often something like a `<summary>` that a *click*
-    // also focuses as a side effect (e.g. clicking it to toggle a
-    // `<details>`) — a plain focus check would then treat that leftover,
-    // non-keyboard focus as "still viewing it" forever, since nothing else
-    // ever takes focus to fire `blur`. `:focus-visible` is only true for
-    // focus a browser considers keyboard/keyboard-equivalent, so a mouse
-    // click doesn't leave the peek stuck open after the pointer leaves.
-    const stillActive =
-      activeTrigger.matches(':hover') ||
-      activeTrigger.matches(':focus-visible') ||
-      panel.matches(':hover') ||
-      panel.matches(':focus-within');
-    if (!stillActive) close();
+  graceTimer = setTimeout(() => {
+    graceTimer = null;
+    closeUnlessWanted();
+  }, CARD_CONSTANTS.travelGraceMs);
+}
+
+function peekTriggerAt(point: Point): HTMLElement | null {
+  return (
+    document
+      .elementFromPoint(point.x, point.y)
+      ?.closest<HTMLElement>('[data-hover-peek-wired="true"]') ?? null
+  );
+}
+
+/** The pointer left `trigger` at `apex`, perhaps on its way to the peek. */
+function travelFrom(trigger: HTMLElement, apex: Point): void {
+  cancelLeave();
+  let own: Trip | null = null;
+  const release = () => {
+    if (trip === own) trip = null;
+  };
+  own = startTrip(apex, {
+    graceMs: CARD_CONSTANTS.travelGraceMs,
+    restMs: CARD_CONSTANTS.travelRestMs,
+    tripMaxMs: CARD_CONSTANTS.travelTripMaxMs,
+    cardBox: () => (panel && !panel.hidden ? panel.getBoundingClientRect() : null),
+    triggerBox: () => (trigger.isConnected ? trigger.getBoundingClientRect() : null),
+    onExit: () => {
+      release();
+      closeUnlessWanted();
+    },
+    onLand: () => {
+      release();
+      scheduleLeave();
+    },
+    onRest: (point) => {
+      const other = peekTriggerAt(point);
+      if (!other || other === trigger) return;
+      cancelLeave();
+      showFor.get(other)?.();
+    },
   });
+  trip = own.active ? own : null;
 }
 
 function position(trigger: HTMLElement, target: HTMLElement): void {
@@ -138,7 +190,18 @@ function ensurePanel(): { panel: HTMLElement; scroller: HTMLElement } {
   document.body.append(panel);
 
   panel.addEventListener('pointerenter', cancelLeave);
-  panel.addEventListener('pointerleave', scheduleLeave);
+  panel.addEventListener('pointerleave', (event) => {
+    if (event.pointerType === 'touch') return;
+    // Straight back onto the trigger is the trigger's own business.
+    if (
+      activeTrigger &&
+      event.relatedTarget instanceof Node &&
+      activeTrigger.contains(event.relatedTarget)
+    ) {
+      return;
+    }
+    scheduleLeave();
+  });
 
   if (!globalListenersReady) {
     globalListenersReady = true;
@@ -152,6 +215,15 @@ function ensurePanel(): { panel: HTMLElement; scroller: HTMLElement } {
       const insidePanel = !!target && panel.contains(target);
       if (!insideTrigger && !insidePanel) close();
     });
+    document.addEventListener(
+      'pointermove',
+      (event) => {
+        if (event.pointerType === 'touch') return;
+        lastPointer = { x: event.clientX, y: event.clientY };
+        trip?.move(lastPointer);
+      },
+      { passive: true },
+    );
   }
 
   return { panel, scroller };
@@ -174,29 +246,37 @@ export function attachHoverPeek(
 
   const show = () => {
     const { panel: el, scroller: scrollEl } = ensurePanel();
-    if (activeTrigger === trigger) {
-      cancelLeave();
-      return;
-    }
+    cancelLeave();
+    if (activeTrigger === trigger) return;
     activeTrigger = trigger;
     el.setAttribute('aria-label', label);
     el.style.setProperty('--hover-peek-max-height', `${maxHeightEm}em`);
     scrollEl.replaceChildren(options.getContent());
     position(trigger, el);
   };
-
-  const leave = () => {
-    if (activeTrigger === trigger) scheduleLeave();
-  };
+  showFor.set(trigger, show);
 
   trigger.addEventListener('pointerenter', (event) => {
     if (event.pointerType === 'touch') return;
+    // Crossed on the way to another trigger's peek: held back.
+    if (
+      trip &&
+      activeTrigger !== trigger &&
+      trip.holds({ x: event.clientX, y: event.clientY })
+    ) {
+      return;
+    }
     show();
   });
   trigger.addEventListener('pointerleave', (event) => {
-    if (event.pointerType === 'touch') return;
-    leave();
+    if (event.pointerType === 'touch' || activeTrigger !== trigger) return;
+    if (panel && event.relatedTarget instanceof Node && panel.contains(event.relatedTarget)) {
+      return;
+    }
+    travelFrom(trigger, lastPointer ?? { x: event.clientX, y: event.clientY });
   });
   trigger.addEventListener('focus', show);
-  trigger.addEventListener('blur', leave);
+  trigger.addEventListener('blur', () => {
+    if (activeTrigger === trigger) scheduleLeave();
+  });
 }

package/src/components/disclosure/persisted-disclosure.ts

@@ -1,7 +1,7 @@
 /**
  * Shared open/closed persistence for a native `<details>` disclosure.
  *
- * Every collapsible built on top of this (figures, sections, tables) wants
+ * Every collapsible built on top of this (sections, the notation panel) wants
  * the same three behaviors: restore the reader's last choice before the
  * element paints, save reader-triggered native `toggle`s, and degrade to the
  * author's `defaultOpen` when nothing is saved yet or storage is unavailable.
@@ -10,8 +10,8 @@
  *
  * Storage goes through `PreferenceStore` only (never `localStorage`
  * directly — `tests/unit/seams.test.ts` enforces that boundary). The key is
- * scoped by `location.pathname` so the same figure/section/table `id` can
- * repeat across pages without one page's saved state leaking into another's.
+ * scoped by `location.pathname` so the same `id` can repeat across pages
+ * without one page's saved state leaking into another's.
  *
  * **Wiring**: call this from a plain top-level `<script>` in the consuming
  * Astro component — not from inside an `astro:page-load` listener — the same

package/src/components/disclosure/print-as-shown.ts

@@ -0,0 +1,252 @@
+/**
+ * **Print as shown.** A printed lesson keeps every reader-controlled
+ * disclosure in the state the reader left it on screen: an open section,
+ * memo, glossary, worked-example set, short note, or question prints its
+ * content; a closed one prints its title followed by a "(content collapsed —
+ * full text: <url>)" note, so a paper reader knows something was left out
+ * and where to read it. A figure or a diagram is not a disclosure: it always
+ * prints whole.
+ *
+ * Content hidden only to save screen space — overflowing table rows, the
+ * inactive tabs of an open worked-example set — was never the reader's
+ * choice to hide, and still prints in full (the global print stylesheet and
+ * `LessonExportActions.astro` handle those).
+ *
+ * A disclosure marked `data-print-omit` — a lab's tools (`Figure.astro`) —
+ * never prints, open or folded, and is left exactly as it is: no note, not
+ * opened for an export.
+ *
+ * Two callers share this module:
+ * - `LessonExportActions.astro`, the print controller a course gets with
+ *   `lessonExports.print`: `'as-shown'` for its print button and the
+ *   browser's own print, `'expanded'` for the Markdown export, which needs
+ *   every word regardless of screen state.
+ * - `installPrintAsShownFallback`, for a course without that controller, so
+ *   the browser's own print behaves the same way there.
+ *
+ * A closed native `<details>` never renders its body, whatever the author
+ * CSS says, so "as shown" mostly means *not* opening anything. What this
+ * does have to fix up is transient state: a section mid-hover-peek or
+ * mid-animation has `details.open === true` while reading as closed on
+ * screen, so its `data-state` — not `.open` — decides.
+ */
+
+export type DisclosureExportMode = 'as-shown' | 'expanded';
+
+export interface PrepareDisclosureOptions {
+  /** Absolute URL of this page, at `#anchorId` when one is given. */
+  noteHref(anchorId: string | undefined): string;
+}
+
+export interface PreparedDisclosures {
+  /** Put every disclosure back exactly as the reader left it and remove the notes. */
+  restore(): void;
+  /**
+   * Drop the temporary marker that keeps disclosure persistence from saving
+   * the prepare/restore toggles. Native `toggle` events are queued, so call
+   * this one task after `restore()`, not in the same one.
+   */
+  releaseMarkers(): void;
+}
+
+export const COLLAPSED_NOTE_CLASS = 'explico-collapsed-note';
+
+/**
+ * Whether a disclosure reads as open on screen. A component that animates
+ * its own open/close (a section) keeps `data-state` as the truth —
+ * `peeking` and a collapse still in flight both read as closed.
+ */
+export function isShownOpen(open: boolean, state: string | undefined): boolean {
+  return state === undefined ? open : state === 'open';
+}
+
+/** `https://host/path/#id` → `host/path/#id`: what a paper reader types. */
+export function displayUrl(href: string): string {
+  return href.replace(/^https?:\/\//u, '');
+}
+
+/** `id` values React's `useId` generates are not stable across builds. */
+function isStableId(id: string): boolean {
+  return /^[A-Za-z]/u.test(id);
+}
+
+/**
+ * The permalink a note points at: the disclosure's own anchor if it has
+ * one, otherwise the nearest enclosing one (a question's knowledge-check
+ * section, say). A collapsible section's anchor is its heading's id.
+ */
+function anchorIdFor(element: Element): string | undefined {
+  for (
+    let node: Element | null = element;
+    node && node.tagName !== 'MAIN';
+    node = node.parentElement
+  ) {
+    if (node.matches('details.sl-section-collapsible')) {
+      const heading = node.querySelector(':scope > summary > [id]');
+      if (heading && isStableId(heading.id)) return heading.id;
+    }
+    if (node.id && isStableId(node.id)) return node.id;
+  }
+  return undefined;
+}
+
+function createNote(href: string): HTMLElement {
+  const note = document.createElement('div');
+  note.className = COLLAPSED_NOTE_CLASS;
+  const link = document.createElement('a');
+  link.href = href;
+  link.textContent = displayUrl(href);
+  note.append('(content collapsed — full text: ', link, ')');
+  return note;
+}
+
+type SavedDetails = {
+  readonly element: HTMLDetailsElement;
+  readonly open: boolean;
+  readonly state: string | undefined;
+  readonly style: string | null;
+  readonly body: HTMLElement | null;
+  readonly bodyStyle: string | null;
+  readonly temporaryMarker: string | null;
+};
+
+export function prepareDisclosures(
+  mode: DisclosureExportMode,
+  options: PrepareDisclosureOptions,
+): PreparedDisclosures {
+  const main = document.querySelector('main');
+  const allDetails = main
+    ? Array.from(main.querySelectorAll<HTMLDetailsElement>('details:not([data-print-omit])'))
+    : [];
+
+  const saved: SavedDetails[] = allDetails.map((element) => {
+    const body = element.querySelector<HTMLElement>(':scope > .sl-section-body');
+    const record: SavedDetails = {
+      element,
+      open: element.open,
+      state: element.dataset.state,
+      style: element.getAttribute('style'),
+      body,
+      bodyStyle: body?.getAttribute('style') ?? null,
+      temporaryMarker: element.getAttribute('data-explico-temporary-open'),
+    };
+    const open =
+      mode === 'expanded' || isShownOpen(element.open, element.dataset.state);
+    element.dataset.explicoTemporaryOpen = mode;
+    element.open = open;
+    if (element.dataset.state !== undefined) {
+      element.dataset.state = open ? 'open' : 'closed';
+    }
+    // A peek or an open/close animation leaves an inline `max-height` (and a
+    // clipping `overflow`) behind; the printed box needs its natural height.
+    body?.style.removeProperty('max-height');
+    body?.style.removeProperty('overflow');
+    body?.style.removeProperty('transition');
+    return record;
+  });
+
+  const notes: HTMLElement[] = [];
+  if (main && mode === 'as-shown') {
+    // Only the outermost closed disclosure gets a note: anything nested in
+    // it is already out of the printed page along with it.
+    const insideClosed = (element: Element) =>
+      !!element.parentElement?.closest('details:not([open])');
+
+    for (const details of main.querySelectorAll('details:not([open]):not([data-print-omit])')) {
+      if (insideClosed(details)) continue;
+      const note = createNote(options.noteHref(anchorIdFor(details)));
+      details.after(note);
+      notes.push(note);
+    }
+    // Disclosures built on `hidden` rather than `<details>`.
+    for (const element of main.querySelectorAll(
+      ':is(.short-note, .assessment-panel)[hidden]',
+    )) {
+      if (insideClosed(element)) continue;
+      const note = createNote(options.noteHref(anchorIdFor(element)));
+      element.before(note);
+      notes.push(note);
+    }
+  }
+
+  return {
+    restore() {
+      for (const note of notes) note.remove();
+      for (const state of saved) {
+        state.element.open = state.open;
+        if (state.state === undefined) delete state.element.dataset.state;
+        else state.element.dataset.state = state.state;
+        if (state.style === null) state.element.removeAttribute('style');
+        else state.element.setAttribute('style', state.style);
+        if (state.body) {
+          if (state.bodyStyle === null) state.body.removeAttribute('style');
+          else state.body.setAttribute('style', state.bodyStyle);
+        }
+      }
+    },
+    releaseMarkers() {
+      for (const state of saved) {
+        if (state.temporaryMarker === null) {
+          state.element.removeAttribute('data-explico-temporary-open');
+        } else {
+          state.element.setAttribute(
+            'data-explico-temporary-open',
+            state.temporaryMarker,
+          );
+        }
+      }
+    },
+  };
+}
+
+/** This page's own URL (no canonical rewrite available) at `#anchorId`. */
+function pageHref(anchorId: string | undefined): string {
+  const url = new URL(location.href);
+  url.hash = anchorId ? `#${anchorId}` : '';
+  return url.href;
+}
+
+/**
+ * Print-as-shown for the browser's own print on a page without the print
+ * controller. Idempotent across every component that calls it — a flag on
+ * `<html>` rather than module state, since separately bundled scripts may
+ * each carry their own copy of this module.
+ */
+export function installPrintAsShownFallback(): void {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-explico-print-as-shown')) return;
+  root.setAttribute('data-explico-print-as-shown', '');
+
+  let prepared: PreparedDisclosures | null = null;
+  let pendingRelease: (() => void) | null = null;
+  const hasController = () =>
+    !!document.querySelector('[data-explico-print-controller]');
+
+  const enter = () => {
+    if (prepared || hasController()) return;
+    pendingRelease?.();
+    prepared = prepareDisclosures('as-shown', { noteHref: pageHref });
+  };
+  const leave = () => {
+    const done = prepared;
+    if (!done) return;
+    prepared = null;
+    done.restore();
+    const release = () => {
+      if (pendingRelease !== release) return;
+      done.releaseMarkers();
+      pendingRelease = null;
+    };
+    pendingRelease = release;
+    window.setTimeout(release, 0);
+  };
+
+  const printMedia = window.matchMedia('print');
+  printMedia.addEventListener('change', (event) => {
+    if (event.matches) enter();
+    else leave();
+  });
+  window.addEventListener('beforeprint', enter);
+  window.addEventListener('afterprint', leave);
+  if (printMedia.matches) enter();
+}

package/src/components/examples/CompactExample.astro

@@ -28,7 +28,9 @@ if (typeof label !== 'string' || !label.trim()) {
     margin-block-start: 0;
   }
 
-  .compact-example > :last-child {
+  /* `:global`: the last child is slotted MDX content, which a scoped
+     selector never matches — a closing display equation kept its margin. */
+  .compact-example > :global(:last-child) {
     margin-block-end: 0;
   }
 </style>