explico 0.1.1 → 0.3.0

package/src/components/diagram/Diagram.astro

@@ -0,0 +1,317 @@
+---
+/**
+ * A small directed diagram whose node math is checked and explained exactly
+ * like lesson body math (Dagre for build-time layout, no runtime layout
+ * library shipped; KaTeX through the same trust boundary as everywhere
+ * else).
+ *
+ * Each node is plain `text`, a `formula` (raw LaTeX resolved against
+ * `scope` — the same page glyph table `NotationFormula` uses), or both. A
+ * formula's every symbol must resolve: an unresolved glyph fails the build
+ * with the offending node id, the same severity the completeness gate gives
+ * lesson body math — this component exists specifically so diagram math is
+ * never a silent exception to that rule.
+ *
+ * The rendered symbols carry the same `data-notation-key` markers as prose
+ * and equations, so they become working hover/pin triggers with **no new
+ * client script**: `NotationLayer`'s trigger scan already queries the whole
+ * document, not just its own subtree.
+ *
+ * Box sizes are a generous estimate (`reference/diagram-layout.ts`) unless a
+ * node gives an explicit `width`/`height` — there is no DOM at build time to
+ * measure a real render against.
+ */
+import { estimateBoxSize, layoutDiagram } from '../../reference/diagram-layout';
+import { renderNotationFormula } from '../notation/render-notation-math';
+import type { SafeMathNode as SafeMathNodeType } from '../notation/render-notation-math';
+import SafeMathNode from '../notation/SafeMathNode.astro';
+import type { GlyphScopeEntry } from '../../reference/gloss';
+
+export interface DiagramNode {
+  readonly id: string;
+  /** Plain prose caption, e.g. "Decompose velocity". */
+  readonly text?: string;
+  /** Raw LaTeX, resolved against `scope` before rendering. */
+  readonly formula?: string;
+  /** Overrides the size estimate — use for a label the heuristic gets wrong. */
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface DiagramEdge {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface Props {
+  /** Unique on the page — namespaces the arrowhead marker id. */
+  id: string;
+  /** Visible caption; also the diagram's accessible name. */
+  label: string;
+  nodes: readonly DiagramNode[];
+  edges: readonly DiagramEdge[];
+  /** Glyph scope `formula` resolves against — omit if no node uses `formula`. */
+  scope?: readonly GlyphScopeEntry[];
+  direction?: 'TB' | 'LR';
+  /**
+   * Prose text alternative for the SVG. When omitted, the fallback is
+   * generated from the node labels and the edge chain — readable, but a
+   * hand-written sentence usually reads better for a screen-reader user.
+   */
+  description?: string;
+}
+
+const {
+  id,
+  label,
+  nodes,
+  edges,
+  scope = [],
+  direction = 'TB',
+  description,
+} = Astro.props;
+
+const idPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+if (!idPattern.test(id)) {
+  throw new Error(`Unsafe Diagram id: ${id}`);
+}
+if (nodes.length === 0) {
+  throw new Error(`Diagram "${id}" has no nodes.`);
+}
+
+interface RenderedNode extends DiagramNode {
+  readonly mathNodes?: readonly SafeMathNodeType[];
+}
+
+const rendered: RenderedNode[] = nodes.map((node) => {
+  if (!node.text && !node.formula) {
+    throw new Error(`Diagram "${id}" node "${node.id}" has neither text nor formula.`);
+  }
+  if (!node.formula) return { ...node };
+
+  const { nodes: mathNodes, unresolved, degraded } = renderNotationFormula(
+    node.formula,
+    scope,
+  );
+  if (degraded) {
+    throw new Error(
+      `Diagram "${id}" node "${node.id}" formula "${node.formula}" could not be ` +
+        `bound to the notation scope: the LaTeX did not parse, or a bare glyph is ` +
+        `the base of more than one page symbol. Wrap each symbol in ` +
+        `\\explain{key}{latex}, or brace a subscripted base (write {v_0}^{2}, not ` +
+        `v_0^{2}), so every glyph resolves — a diagram formula is never allowed to ` +
+        `render as silent, unexplained math.`,
+    );
+  }
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Diagram "${id}" node "${node.id}" formula uses undefined notation ${unresolved
+        .map((token) => `"${token}"`)
+        .join(', ')}. Introduce the symbol with [[key]], define it in notation.local, ` +
+        `or pass it in the diagram's scope.`,
+    );
+  }
+  return { ...node, mathNodes };
+});
+
+const sized = rendered.map((node) => ({
+  node,
+  box:
+    node.width && node.height
+      ? { width: node.width, height: node.height }
+      : estimateBoxSize(
+          node.formula ?? node.text ?? node.id,
+          node.formula ? 'formula' : 'text',
+        ),
+}));
+
+const layout = layoutDiagram(
+  sized.map(({ node, box }) => ({ id: node.id, width: box.width, height: box.height })),
+  edges.map((edge) => ({ from: edge.from, to: edge.to })),
+  { direction },
+);
+
+const nodeById = new Map(rendered.map((node) => [node.id, node]));
+const laidOutById = new Map(layout.nodes.map((node) => [node.id, node]));
+const markerId = `diagram-arrow-${id}`;
+
+/** A node's human label for the text fallback — never the internal id. */
+function fallbackLabel(nodeId: string): string {
+  const node = nodeById.get(nodeId);
+  return node?.text ?? node?.formula ?? nodeId;
+}
+
+function pathFrom(points: readonly { x: number; y: number }[]): string {
+  if (points.length === 0) return '';
+  const [first, ...rest] = points;
+  return `M ${first!.x} ${first!.y} ` + rest.map((point) => `L ${point.x} ${point.y}`).join(' ');
+}
+---
+
+<figure class="diagram" id={`diagram-${id}`}>
+  <figcaption id={`${id}-caption`}>{label}</figcaption>
+  <div class="diagram-scroll" tabindex="0" role="group" aria-labelledby={`${id}-caption`}>
+  <svg
+    viewBox={`0 0 ${layout.width} ${layout.height}`}
+    width={layout.width}
+    height={layout.height}
+  >
+    <defs>
+      <marker
+        id={markerId}
+        viewBox="0 0 10 10"
+        refX="9"
+        refY="5"
+        markerWidth="7"
+        markerHeight="7"
+        orient="auto-start-reverse"
+      >
+        <path d="M 0 0 L 10 5 L 0 10 z" class="diagram-arrowhead" />
+      </marker>
+    </defs>
+
+    {
+      layout.edges.map((edge) => (
+        <path
+          d={pathFrom(edge.points)}
+          class="diagram-edge"
+          marker-end={`url(#${markerId})`}
+        />
+      ))
+    }
+
+    {
+      layout.nodes.map((position) => {
+        const node = nodeById.get(position.id)!;
+        return (
+          <g transform={`translate(${position.x}, ${position.y})`} class="diagram-node">
+            <rect width={position.width} height={position.height} rx="8" ry="8" />
+            <foreignObject width={position.width} height={position.height}>
+              <div xmlns="http://www.w3.org/1999/xhtml" class="diagram-node-content">
+                {node.text && <span class="diagram-node-text">{node.text}</span>}
+                {node.mathNodes && (
+                  <span class="diagram-node-formula notation-math">
+                    {node.mathNodes.map((mathNode) => (
+                      <SafeMathNode node={mathNode} />
+                    ))}
+                  </span>
+                )}
+              </div>
+            </foreignObject>
+          </g>
+        );
+      })
+    }
+  </svg>
+  </div>
+
+  <details class="diagram-fallback">
+    <summary>Diagram description</summary>
+    {
+      description ? (
+        <p>{description}</p>
+      ) : (
+        <Fragment>
+          <ol>
+            {rendered.map((node) => (
+              <li>{fallbackLabel(node.id)}</li>
+            ))}
+          </ol>
+          {edges.length > 0 && (
+            <p class="diagram-fallback-flow">
+              {edges.map((edge, index) => (
+                <Fragment>
+                  {index > 0 && '; '}
+                  {fallbackLabel(edge.from)} → {fallbackLabel(edge.to)}
+                </Fragment>
+              ))}
+            </p>
+          )}
+        </Fragment>
+      )
+    }
+  </details>
+</figure>
+
+<style>
+  @layer starlight.components {
+    .diagram {
+      margin: 1.5rem 0;
+    }
+
+    .diagram figcaption {
+      margin-block-end: 0.5rem;
+      font-weight: 600;
+    }
+
+    /* A wide graph scrolls inside its own box rather than shrinking to
+       illegibility — the same tradeoff `.notation-formula-math` makes for a
+       wide equation. `tabindex` on the scroller is the accessibility half of
+       that: a scrollable region a keyboard user cannot reach is unreachable
+       content, not just an awkward one. */
+    .diagram-scroll {
+      overflow-x: auto;
+      padding-block: 0.15rem;
+    }
+
+    .diagram-scroll:focus-visible {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    .diagram svg {
+      display: block;
+      overflow: visible;
+    }
+
+    .diagram-node rect {
+      fill: var(--sl-color-gray-7);
+      stroke: var(--sl-color-gray-5);
+      stroke-width: 1;
+    }
+
+    .diagram-node-content {
+      display: flex;
+      height: 100%;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 0.15rem;
+      padding: 0.2rem 0.5rem;
+      color: var(--sl-color-text);
+      font-family: var(--sl-font);
+      font-size: 0.85rem;
+      line-height: 1.25;
+      text-align: center;
+    }
+
+    .diagram-node-formula :global(.katex) {
+      font-size: 1em;
+    }
+
+    .diagram-edge {
+      fill: none;
+      stroke: var(--sl-color-gray-4);
+      stroke-width: 1.5;
+    }
+
+    .diagram-arrowhead {
+      fill: var(--sl-color-gray-4);
+    }
+
+    .diagram-fallback {
+      margin-block-start: 0.5rem;
+      color: var(--sl-color-gray-3);
+      font-size: var(--sl-text-sm);
+    }
+
+    .diagram-fallback ol,
+    .diagram-fallback p {
+      margin: 0.35rem 0 0;
+    }
+
+    .diagram-fallback ol {
+      padding-inline-start: 1.25rem;
+    }
+  }
+</style>

package/src/components/examples/CompactExamples.astro

@@ -161,7 +161,7 @@ const {
       this.dataset.enhanced = 'true';
       const instanceId = `compact-examples-${CompactExamplesElement.nextId++}`;
       const tablist = document.createElement('div');
-      tablist.className = 'compact-examples__tabs';
+      tablist.className = 'compact-examples__tabs not-content';
       tablist.setAttribute('role', 'tablist');
       tablist.setAttribute(
         'aria-label',

package/src/components/figure/Figure.astro

@@ -0,0 +1,104 @@
+---
+/**
+ * A referenceable figure (F-tables-figures) — static image, inline SVG, a
+ * `Diagram`, or a hydrated React lab — numbered and anchored the same way
+ * `<Table>` is; see `Table.astro` for the full identity model, which this
+ * mirrors exactly (separate counter, same `[[fig-<id>]]` / cross-page
+ * reference grammar, `number`/`anchorId` computed by `remark-notation.mjs`).
+ *
+ * `previewable` (default `true`) controls what the hover-preview card
+ * (`FloatRefLayer.astro`) shows for a `[[fig-<id>]]` reference elsewhere in
+ * the prose: `true` clones this figure's visual into the card alongside its
+ * caption; `false` shows the caption and number only. Set it `false` for
+ * interactive content — a hydrated `client:*` island cloned into a floating
+ * card would be an inert, non-hydrated, id-colliding duplicate, not a
+ * working preview.
+ */
+export interface Props {
+  /** Stable key, e.g. `id="projectile-trajectory"`. Omit for a positional-only figure. */
+  id?: string;
+  /** Visible caption, shown below the figure and in the hover-preview card. */
+  caption: string;
+  /** `false` for interactive content the hover-preview must not clone. */
+  previewable?: boolean;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  number?: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+const { id, caption, previewable = true, number, anchorId } = Astro.props;
+
+if (typeof caption !== 'string' || !caption.trim()) {
+  throw new Error('Figure requires a non-empty `caption` prop.');
+}
+if (!number || !anchorId) {
+  throw new Error(
+    'Figure is missing its computed `number`/`anchorId` — this page must run remark-notation with a `figures` cross-page table configured (see astro.config.mjs).',
+  );
+}
+---
+
+<figure
+  class="keyed-figure"
+  id={anchorId}
+  data-fig-number={number}
+  data-fig-key={id}
+  data-fig-previewable={String(previewable)}
+>
+  <div class="keyed-figure__body">
+    <slot />
+  </div>
+  <figcaption class="keyed-figure__caption">
+    <a
+      class="keyed-figure__number"
+      href={`#${anchorId}`}
+      aria-label={`Figure ${number}`}>Figure {number}</a
+    >
+    <span class="keyed-figure__caption-text">{caption}</span>
+  </figcaption>
+</figure>
+
+<style>
+  .keyed-figure {
+    margin-block: 1.5rem;
+    padding: 0;
+  }
+
+  .keyed-figure__body {
+    overflow-x: auto;
+  }
+
+  .keyed-figure__caption {
+    margin-block-start: 0.5rem;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+
+  .keyed-figure__number {
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+  }
+
+  .keyed-figure__number:hover,
+  .keyed-figure__number:focus-visible {
+    text-decoration: underline;
+  }
+
+  .keyed-figure__number:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  .keyed-figure__caption-text::before {
+    content: ' — ';
+  }
+
+  @media print {
+    .keyed-figure__number {
+      color: inherit;
+    }
+  }
+</style>

package/src/components/hover-panel.ts

@@ -21,6 +21,8 @@ export interface HoverPanelState {
 export interface HoverPanelConfig {
   /** The `<aside data-hover-panel>` element. */
   panel: HTMLElement;
+  /** Exclusivity group (see the `activeSurface` note below `HoverPanelState`). */
+  groupId: string;
   /**
    * Element used only to locate the enclosing article column for the
    * horizontal clamp. Defaults to the panel itself.
@@ -49,6 +51,36 @@ function closestElement(node: EventTarget | null, selector: string) {
   return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
 }
 
+/**
+ * The notation layer and the citation layer each own their explanations —
+ * the notation layer through its own popup stack (`./popup-stack.ts`), the
+ * citation layer through this module's `createHoverPanel`. Neither knows the
+ * other exists, so a pinned citation and an open notation popup — or the
+ * reverse — can each be individually correct and still land on top of each
+ * other, or on top of the equation the other one is explaining. Rather than
+ * teach every positioning calculation about every other surface that might
+ * exist, the two are mutually exclusive *groups*: opening the first popup in
+ * one group closes whatever the other group had open. Within a group,
+ * surfaces manage their own overlap (the citation panel is a singleton; the
+ * notation stack positions its own popups against each other). A pin is not
+ * exempt — the reader's attention already moved to the other group.
+ */
+let activeSurface: {
+  readonly groupId: string;
+  readonly close: () => void;
+} | null = null;
+
+export function claimActiveSurface(groupId: string, close: () => void): void {
+  if (activeSurface && activeSurface.groupId !== groupId) {
+    activeSurface.close();
+  }
+  activeSurface = { groupId, close };
+}
+
+export function releaseActiveSurface(groupId: string): void {
+  if (activeSurface?.groupId === groupId) activeSurface = null;
+}
+
 export function createHoverPanel(config: HoverPanelConfig) {
   const { panel } = config;
   if (panel.dataset.hoverPanelReady === 'true') return;
@@ -145,6 +177,8 @@ export function createHoverPanel(config: HoverPanelConfig) {
     if (!key) return;
     if (config.render(anchor, key) === false) return;
 
+    claimActiveSurface(config.groupId, forceClose);
+
     activeKey = key;
     activeAnchor = anchor;
     config.onShow?.(key, anchor);
@@ -161,9 +195,23 @@ export function createHoverPanel(config: HoverPanelConfig) {
     activeAnchor = null;
     panel.hidden = true;
     config.onClose?.();
+    releaseActiveSurface(config.groupId);
     sync();
   };
 
+  // A plain `close()` deliberately leaves `pinned` set — a stray pointerout or
+  // focusout elsewhere on the page must not kill a pin the reader placed on
+  // purpose, and `restorePinnedOrClose` below relies on `pinned` surviving a
+  // transient close to bring the panel back. Being displaced by a DIFFERENT
+  // panel taking over (`claimActivePanel`) is not transient, though: without
+  // clearing the pin here, the very next stray blur anywhere on the page finds
+  // `pinned` still truthy and restores this panel — undoing the takeover a
+  // frame later and fighting the other panel for the screen.
+  const forceClose = () => {
+    pinned = null;
+    close();
+  };
+
   const restorePinnedOrClose = () => {
     window.requestAnimationFrame(() => {
       const focused = config.triggerFrom(document.activeElement);
@@ -235,11 +283,29 @@ export function createHoverPanel(config: HoverPanelConfig) {
     }
 
     const trigger = config.triggerFrom(event.target);
-    if (!trigger || trigger.closest('a')) return;
-    const key = config.keyFor(trigger);
-    if (!key) return;
-    event.preventDefault();
-    togglePin(key, trigger);
+    if (trigger && !trigger.closest('a')) {
+      const key = config.keyFor(trigger);
+      if (key) {
+        event.preventDefault();
+        togglePin(key, trigger);
+        return;
+      }
+    }
+    if (trigger) return; // a real link trigger: let it navigate.
+
+    // Anywhere else inside the panel collapses it, same as the corner "×" —
+    // its own body is never a trigger, so a click there can only mean "I'm
+    // done with this." A real link (e.g. "Open source link") is excluded so
+    // it still navigates instead of being swallowed.
+    if (
+      !panel.hidden &&
+      event.target instanceof Node &&
+      panel.contains(event.target) &&
+      !closestElement(event.target, 'a')
+    ) {
+      pinned = null;
+      close();
+    }
   });
 
   document.addEventListener('pointerdown', (event) => {

package/src/components/notation/NotationFormula.astro

@@ -0,0 +1,154 @@
+---
+/**
+ * A notation entry's rigorous `formula`, rendered with every glyph bound to a
+ * key so the reader can point at any symbol in it and get an explanation
+ * (D15).
+ *
+ * The formula resolves against the **entry-scoped** table from
+ * `reference/gloss.ts` — the entry, its `glosses:`, and any card the formula
+ * names with `\explain{key}{latex}` — not the registry-wide table a card's
+ * body math uses.
+ *
+ * The gloss list under the formula is not decoration: a gloss has no card of
+ * its own, so this list is where its name lives with JavaScript off. The hover
+ * panel is enhancement layered over content that already reads.
+ */
+import NotationMath from './NotationMath.astro';
+import SafeMathNode from './SafeMathNode.astro';
+import { renderNotationFormula } from './render-notation-math';
+import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
+
+export interface Props {
+  formula: string;
+  scope: readonly GlyphScopeEntry[];
+  glosses?: readonly ResolvedGloss[];
+  /** Heading for the gloss list; omitted renders the list unlabelled. */
+  glossLabel?: string;
+  /** The owning entry's display label, used to name the scrollable region. */
+  entryLabel?: string;
+}
+
+const {
+  formula,
+  scope,
+  glosses = [],
+  glossLabel = 'Symbols',
+  entryLabel,
+} = Astro.props;
+const { nodes } = renderNotationFormula(formula, scope);
+---
+
+<div class="notation-formula-block">
+  <div
+    class="notation-formula-math"
+    data-notation-formula
+    role="group"
+    aria-label={entryLabel ? `${entryLabel} formula` : 'Formula'}
+    tabindex="0"
+  >
+    <span class="notation-math">
+      {nodes.map((node) => <SafeMathNode node={node} />)}
+    </span>
+  </div>
+
+  {
+    glosses.length > 0 && (
+      <dl class="notation-gloss-list" data-notation-gloss-list>
+        {glossLabel && <dt class="notation-gloss-label">{glossLabel}</dt>}
+        {glosses.map((gloss) => (
+          <dd class="notation-gloss" data-notation-gloss={gloss.key}>
+            <span
+              class="notation-gloss-symbol"
+              data-notation-symbol-trigger
+              data-notation-key={gloss.key}
+            >
+              <NotationMath class="notation-symbol" latex={gloss.notation} />
+            </span>
+            <span class="notation-gloss-name">{gloss.label}</span>
+            {gloss.units && (
+              <span class="notation-gloss-units">({gloss.units})</span>
+            )}
+          </dd>
+        ))}
+      </dl>
+    )
+  }
+</div>
+
+<style>
+  @layer starlight.components {
+    .notation-formula-block {
+      display: grid;
+      gap: 0.5rem;
+    }
+
+    /* A wide equation scrolls inside its own box, which makes the box a
+       scrollable region — and a scrollable region a keyboard user cannot reach
+       is unreachable content, not just an awkward one. `tabindex` on the
+       container is the fix; this is its focus ring. */
+    .notation-formula-math {
+      overflow-x: auto;
+      padding-block: 0.15rem;
+      color: var(--sl-color-text);
+    }
+
+    .notation-formula-math:focus-visible {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    .notation-gloss-list {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: baseline;
+      gap: 0.25rem 1rem;
+      margin: 0;
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-sm);
+    }
+
+    .notation-gloss-label {
+      margin: 0;
+      color: var(--sl-color-gray-3);
+      font-weight: 600;
+    }
+
+    .notation-gloss {
+      display: flex;
+      align-items: baseline;
+      gap: 0.35rem;
+      margin: 0;
+    }
+
+    .notation-gloss-symbol {
+      border-radius: 0.16em;
+      color: var(--sl-color-accent-high);
+      cursor: help;
+    }
+
+    .notation-gloss-symbol:hover,
+    .notation-gloss-symbol:global(.is-notation-active) {
+      background: var(--sl-color-accent-low);
+      box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
+    }
+
+    .notation-gloss-name::before {
+      content: '— ';
+      color: var(--sl-color-gray-3);
+    }
+
+    .notation-gloss-units {
+      color: var(--sl-color-gray-3);
+    }
+
+    @media (forced-colors: active) {
+      .notation-gloss-symbol:hover,
+      .notation-gloss-symbol:global(.is-notation-active) {
+        outline: 2px solid Highlight;
+        color: HighlightText;
+        background: Highlight;
+        box-shadow: none;
+      }
+    }
+  }
+</style>