explico 0.8.0 → 0.11.0

package/src/components/figure/figure-state.ts

@@ -0,0 +1,58 @@
+/**
+ * The live end of a figure's caption line (docs/plans/figures-and-short-captions.md,
+ * decisions 3 and 8). A lab states the case its plot shows after the long
+ * caption — "Shown for v₀ = 20 m/s and θ = 30°: range 35.3 m." — in
+ * `span.float-caption__state[data-figure-state]` (`FloatCaption.astro`). That
+ * span sits outside `.float-caption__text`, so every reader of the long
+ * caption (a preview card, a fold's bar, the list of figures) still reads the
+ * caption alone, and it prints with the caption.
+ *
+ * A lab passes its clause as runs of text, never HTML: a string is plain
+ * text, `{ text, italic: true }` an italic run (a symbol), `{ sub }` a
+ * subscript. There is no `aria-live`: the controls already announce their
+ * values.
+ */
+
+export type FigureStateRun =
+  | string
+  | { readonly text: string; readonly italic?: boolean }
+  | { readonly sub: string };
+
+type NodeFactory = Pick<Document, 'createElement' | 'createTextNode'>;
+
+/** The nodes for `runs`, made by `doc`. Markup in a run stays text. */
+export function figureStateNodes(
+  runs: readonly FigureStateRun[],
+  doc: NodeFactory,
+): Node[] {
+  return runs.map((run) => {
+    if (typeof run === 'string') return doc.createTextNode(run);
+    if ('sub' in run) {
+      const sub = doc.createElement('sub');
+      sub.textContent = run.sub;
+      return sub;
+    }
+    if (!run.italic) return doc.createTextNode(run.text);
+    const italic = doc.createElement('i');
+    italic.textContent = run.text;
+    return italic;
+  });
+}
+
+/**
+ * Write the case a lab shows at the end of its figure's caption line. `from`
+ * is any element inside the `<Figure>` — the lab's own root. An empty list
+ * clears the clause. Returns whether it found the figure's caption.
+ */
+export function setFigureState(from: Element, runs: readonly FigureStateRun[]): boolean {
+  const state = from
+    .closest('figure.keyed-figure')
+    ?.querySelector<HTMLElement>(':scope > figcaption > [data-figure-state]');
+  if (!state) return false;
+  // A slider drag writes on every tick; leave the line alone when nothing changed.
+  const key = JSON.stringify(runs);
+  if (state.dataset.figureStateKey === key) return true;
+  state.dataset.figureStateKey = key;
+  state.replaceChildren(...figureStateNodes(runs, state.ownerDocument));
+  return true;
+}

package/src/components/figure/figure-tools.ts

@@ -0,0 +1,87 @@
+/**
+ * The fold of a lab's tools (docs/plans/figures-and-short-captions.md,
+ * decisions 3–6). A `<Figure>` with a `tools` slot renders it after the
+ * caption line, in a tray inside a `<details>` (so persistence, find-in-page
+ * and print-as-shown keep working on it). The fold button ⌃ / ⌄ at the end
+ * of the caption line drives it; folded, a "Hidden here: 2 sliders, 1
+ * equation" line under the caption says what is gone, and unfolds it on a
+ * click. Only the tools fold: the picture and the caption always show.
+ *
+ * `describeHiddenTools` is split from the DOM walk so the wording is
+ * unit-testable, as `../starlight/section-summary.ts` does for sections.
+ */
+import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
+
+export interface ToolCounts {
+  readonly sliders: number;
+  readonly menus: number;
+  readonly equations: number;
+}
+
+const LABELS: readonly (readonly [keyof ToolCounts, string, string])[] = [
+  ['sliders', 'slider', 'sliders'],
+  ['menus', 'menu', 'menus'],
+  ['equations', 'equation', 'equations'],
+];
+
+/** `"Hidden here: 2 sliders, 1 equation"`, or `"Hidden here: the controls"`. */
+export function describeHiddenTools(counts: ToolCounts): string {
+  const parts = LABELS.filter(([key]) => counts[key] > 0).map(
+    ([key, singular, plural]) => `${counts[key]} ${counts[key] === 1 ? singular : plural}`,
+  );
+  return `Hidden here: ${parts.length > 0 ? parts.join(', ') : 'the controls'}`;
+}
+
+export function countTools(tray: ParentNode): ToolCounts {
+  return {
+    sliders: tray.querySelectorAll('input[type="range"]').length,
+    menus: tray.querySelectorAll('select').length,
+    equations: tray.querySelectorAll('.katex-display').length,
+  };
+}
+
+/**
+ * Wire one figure's tools: its fold button, its "Hidden here" line and the
+ * reader's remembered choice (`figure-tools:<figure id>`, per page). The
+ * button and the line follow every change to the `<details>`, whoever makes
+ * it — a click, the browser's find-in-page, a restore.
+ */
+export function wireFigureTools(figure: HTMLElement): void {
+  const details = figure.querySelector<HTMLDetailsElement>(
+    ':scope > details.keyed-figure__tools-fold',
+  );
+  const toggle = figure.querySelector<HTMLButtonElement>(
+    ':scope > figcaption [data-figure-tools-toggle]',
+  );
+  const stub = figure.querySelector<HTMLButtonElement>(
+    ':scope > [data-figure-tools-stub]',
+  );
+  if (!details || !toggle || !stub || !figure.id) return;
+
+  // The SSR `open` attribute carries the first-visit state (`defaultOpen`,
+  // else the course's `disclosure.figures`); read it before anything moves it.
+  const defaultOpen = details.open;
+  if (details.dataset.rememberState === 'true') {
+    wirePersistedDetails(details, `figure-tools:${figure.id}`, defaultOpen);
+  }
+
+  const name = figure.dataset.figNumber ? `Figure ${figure.dataset.figNumber}` : 'this figure';
+  const sync = () => {
+    const open = details.open;
+    toggle.setAttribute('aria-expanded', String(open));
+    toggle.setAttribute('aria-label', `${open ? 'Hide' : 'Show'} the controls of ${name}`);
+    toggle.title = open ? 'Hide the controls' : 'Show the controls';
+    if (!open) stub.textContent = describeHiddenTools(countTools(details));
+    stub.hidden = open;
+  };
+
+  toggle.addEventListener('click', () => {
+    details.open = !details.open;
+  });
+  stub.addEventListener('click', () => {
+    details.open = true;
+    toggle.focus({ preventScroll: true });
+  });
+  details.addEventListener('toggle', sync);
+  sync();
+}

package/src/components/float-name.ts

@@ -0,0 +1,101 @@
+/**
+ * A numbered float's reader-facing name: its kind word and number, then its
+ * short caption when it has one — "Diagram 2.1.1 Steps of the range
+ * derivation" (docs/plans/figures-and-short-captions.md, decisions 9 and 11).
+ * A `<Fold>`'s bar names the floats inside it this way.
+ *
+ * A float carries both halves on its root element, as `data-<kind>-number`
+ * and `data-<kind>-short` (`Figure.astro`, `Table.astro`, `Diagram.astro`);
+ * nothing else in the page carries those attributes.
+ */
+
+export type FloatKind = 'fig' | 'tab' | 'dia';
+
+export const FLOAT_KIND_WORDS: Readonly<Record<FloatKind, string>> = {
+  fig: 'Figure',
+  tab: 'Table',
+  dia: 'Diagram',
+};
+
+export interface NamedFloat {
+  readonly kind: FloatKind;
+  readonly number: string;
+  readonly short?: string;
+  /** Its anchor (`fig-…`, `tab-…`, `dia-…`), when the scan found one. */
+  readonly anchorId?: string;
+}
+
+/** `Figure 2.1.1 Projectile trajectory explorer`, or `Figure 2.1.1` with no short caption. */
+export function floatName(float: NamedFloat): string {
+  const label = `${FLOAT_KIND_WORDS[float.kind]} ${float.number}`;
+  return float.short ? `${label} ${float.short}` : label;
+}
+
+/**
+ * The bold title that opens a caption line when the float has a short
+ * caption (docs/plans/figures-and-short-captions.md, decision 9.1): the
+ * short caption with a closing period, unless it already ends in one — the
+ * journal-legend style, "Fig. 1 | Title. Description".
+ */
+export function captionTitle(short: string): string {
+  const title = short.trim();
+  return /[.!?…:;]$/u.test(title) ? title : `${title}.`;
+}
+
+/**
+ * A numbered float's name, read off its root element in the page — the same
+ * `data-<kind>-number` / `data-<kind>-short` pair `floatsInHtml` reads from
+ * markup. `null` for an element that is no numbered float.
+ */
+export function floatOf(element: Element): NamedFloat | null {
+  for (const kind of ['fig', 'tab', 'dia'] as const) {
+    const number = element.getAttribute(`data-${kind}-number`);
+    if (!number) continue;
+    const short = element.getAttribute(`data-${kind}-short`) ?? undefined;
+    return {
+      kind,
+      number,
+      ...(short ? { short } : {}),
+      ...(element.id ? { anchorId: element.id } : {}),
+    };
+  }
+  return null;
+}
+
+/** Astro writes `&` and `"` in an attribute value as numeric references. */
+function decodeAttribute(value: string): string {
+  return value
+    .replace(/&#(\d+);/g, (_, code: string) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([\da-f]+);/gi, (_, code: string) =>
+      String.fromCodePoint(Number.parseInt(code, 16)),
+    )
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+/**
+ * Every numbered float in rendered HTML, in document order — for a build-time
+ * component that renders its slot first (`<Fold>`). Reads the start tags
+ * only: attribute values are double-quoted, with `"` escaped, so a tag ends
+ * at the first `>` outside one.
+ */
+export function floatsInHtml(html: string): NamedFloat[] {
+  const floats: NamedFloat[] = [];
+  for (const tag of html.matchAll(/<[A-Za-z][\w-]*((?:\s+[^\s"'>/=]+(?:="[^"]*")?)*)\s*\/?>/g)) {
+    const attributes = tag[1] ?? '';
+    const number = /\sdata-(fig|tab|dia)-number="([^"]*)"/.exec(attributes);
+    if (!number?.[2]) continue;
+    const kind = number[1] as FloatKind;
+    const short = new RegExp(`\\sdata-${kind}-short="([^"]*)"`).exec(attributes)?.[1];
+    const anchorId = /\sid="([^"]*)"/.exec(attributes)?.[1];
+    floats.push({
+      kind,
+      number: decodeAttribute(number[2]),
+      ...(short ? { short: decodeAttribute(short) } : {}),
+      ...(anchorId ? { anchorId: decodeAttribute(anchorId) } : {}),
+    });
+  }
+  return floats;
+}

package/src/components/fold/Fold.astro

@@ -0,0 +1,125 @@
+---
+/**
+ * `<Fold>` — collapsible content with no heading, number or marker
+ * (docs/plans/figures-and-short-captions.md, decision 11). A stretch of the
+ * lesson a reader can fold away: a diagram, a figure, a table, a few
+ * paragraphs. A float never folds by itself (decision 1), so outside a
+ * collapsible section this is how one becomes fully collapsible.
+ *
+ * It folds the way a memo does (`../memo/Memo.astro`): it is a section of its
+ * own that `CollapsibleSections.astro` folds, with the section chevron, the
+ * hover peek, the "Hidden here: …" line, the reader's remembered choice, the
+ * reveal on a deep link and print-as-shown. It is none of a memo's other
+ * things: no marker or letter in the text, no `[[…]]` key, no aside frame —
+ * it is the plain tier, like the figure it holds. Its bar is an
+ * `<h6 role="none">` this component draws, so it is not in the outline, "On
+ * this page", the heading rules or the accessibility tree's headings, and
+ * takes no number. `data-section-contained` / `data-section-to-end` make it a
+ * section that never ends one around it (`../starlight/section-parts.ts`).
+ *
+ * The bar is the `label`, set at body-text size. Without one it names the
+ * numbered floats inside, "Diagram 2.1.1 Steps of the range derivation"
+ * (`../float-name.ts`), read from the rendered content; with neither it
+ * throws, as `fold-unnamed` reports at `validate:content`. A bar that names
+ * the floats (`data-names-floats`) is their name here: their caption lines
+ * drop the bold short-caption title that would repeat it, and a folded
+ * fold's "Hidden here" counts them. The floats keep their numbers: the
+ * numbering scans see through a fold (`TRANSPARENT_COMPONENTS`).
+ *
+ * First state: `defaultOpen`, else the course's `disclosure.folds` (closed by
+ * default); `rememberState` (default `true`) keeps the reader's choice, per
+ * page.
+ */
+import { courseDisclosure } from '../disclosure/course-disclosure';
+import { floatName, floatsInHtml } from '../float-name';
+import { foldId, foldSlug } from './fold-id';
+
+export interface Props {
+  /** The bar's text. Default: the numbers and short captions of the floats inside. */
+  label?: string;
+  /** State for a reader with nothing saved yet. Default: the course's `disclosure.folds`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
+}
+
+const { label, defaultOpen, rememberState = true } = Astro.props;
+
+if (label !== undefined && (typeof label !== 'string' || !label.trim())) {
+  throw new Error('<Fold> `label` must be a non-empty string when given.');
+}
+
+// Rendered first, to read the floats it holds; injected below unchanged.
+const content = await Astro.slots.render('default');
+const floats = floatsInHtml(content);
+const bar = label?.trim() || floats.map(floatName).join('; ');
+if (!bar) {
+  throw new Error(
+    '<Fold> has no `label` and no numbered <Figure>, <Table> or <Diagram> inside it, so its bar has nothing to name it by: give it a `label`, or fold a numbered float with it (fold-unnamed).',
+  );
+}
+
+const id = foldId(
+  Astro.locals,
+  label ? foldSlug(label) : (floats[0]?.anchorId ?? foldSlug(bar)),
+);
+
+const open = defaultOpen ?? (await courseDisclosure()).folds.defaultOpen;
+---
+
+<div class="fold" data-fold data-names-floats={label ? undefined : ''} data-section-contained>
+  <div
+    class="sl-heading-wrapper level-h6 fold__bar"
+    data-collapsible="true"
+    data-default-open={String(open)}
+    data-remember-state={String(rememberState)}
+    data-section-to-end
+    data-bar-names-floats={label ? undefined : ''}
+  >
+    <h6 id={id} class="fold__label" role="none">{bar}</h6>
+  </div>
+  <div class="fold__body"><Fragment set:html={content} /></div>
+</div>
+
+<style>
+  /* The plain tier (`surfaces.css`): no frame, no tint — only the section
+     machinery's chevron in the page gutter, and a semibold bar at the size
+     of the paragraphs it may fold, never smaller. The folding itself is the
+     section wrapper's (`CollapsibleSections.astro`, `global.css`). */
+  .fold {
+    margin-block: 1rem;
+  }
+
+  .fold > :global(*) {
+    margin-block: 0;
+  }
+
+  .fold__label {
+    margin: 0;
+    font-size: var(--sl-text-body);
+    font-weight: 600;
+    line-height: 1.5;
+    color: var(--sl-color-gray-2);
+    scroll-margin-block-start: 5rem;
+  }
+
+  /* One line box for the bar, also where a narrow screen sets the label
+     inline and wraps it; the gutter chevron centres on its first line
+     (`--sl-section-title-size` × `--sl-line-height-headings`). */
+  .fold :global(.fold__bar > .sl-section-collapsible > .sl-section-summary) {
+    --sl-section-title-size: var(--sl-text-body);
+    --sl-line-height-headings: 1.5;
+    line-height: 1.5;
+  }
+
+  .fold__body > :global(:first-child) {
+    margin-block-start: 0.5rem;
+  }
+
+  /* A bar that names the floats inside is their title: their caption lines
+     go without the bold short caption that would say it a second time
+     (`FloatCaption.astro`, `Table.astro`), open, peeking or printed. */
+  .fold[data-names-floats] :global(.float-caption__title) {
+    display: none;
+  }
+</style>

package/src/components/fold/fold-id.ts

@@ -0,0 +1,40 @@
+/**
+ * The id of a `<Fold>`'s bar (`Fold.astro`). It keys the reader's saved
+ * open/closed choice (`section:<id>`) and a `#fold-…` link, so it comes from
+ * what the fold holds rather than its position: the first float's anchor
+ * when the bar names floats (`fold-dia-range-derivation`), else the label
+ * (`fold-worked-derivation`), made unique on the page.
+ */
+
+const usedByPage = new WeakMap<object, Set<string>>();
+
+/** `"Steps of the derivation"` → `steps-of-the-derivation`. */
+export function foldSlug(text: string): string {
+  return (
+    text
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 60)
+      .replace(/-+$/, '') || 'content'
+  );
+}
+
+/**
+ * `fold-<base>`, with `-2`, `-3`, … when a fold earlier on the same page took
+ * it. `page` is any object unique to one page render — `Astro.locals`.
+ */
+export function foldId(page: object, base: string): string {
+  let used = usedByPage.get(page);
+  if (!used) {
+    used = new Set();
+    usedByPage.set(page, used);
+  }
+  const first = `fold-${base}`;
+  let id = first;
+  for (let n = 2; used.has(id); n++) id = `${first}-${n}`;
+  used.add(id);
+  return id;
+}