explico 0.2.0 → 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/notation/render-notation-math.ts

@@ -250,6 +250,14 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
  * by the `formula` completeness gate (Tier 3) and by the CI test that holds
  * the corpus at zero. A scope error degrades all the way to today's behaviour,
  * an inert but correct equation.
+ *
+ * `unresolved` lists glyphs that are simply not in `scope`. `degraded` is a
+ * coarser, separate signal: it is `true` when resolution *threw* — an ambiguous
+ * bare base glyph, LaTeX that did not parse, a marker KaTeX or the sanitizer
+ * rejected — so the returned `nodes` fell back to the raw formula and carry no
+ * (or only literal `\explain`) markers. A caller that cannot tolerate silent,
+ * unmarked math (the `Diagram` component) turns `degraded` into a build error;
+ * `NotationFormula` keeps the inert-but-correct fallback.
  */
 export function renderNotationFormula(
   formula: string,
@@ -257,22 +265,25 @@ export function renderNotationFormula(
 ): {
   readonly nodes: readonly SafeMathNode[];
   readonly unresolved: readonly string[];
+  readonly degraded: boolean;
 } {
   let bound = formula;
   let unresolved: string[] = [];
+  let degraded = false;
   try {
     const result = resolveMathGlyphs(formula, [...scope]);
     bound = result.latex;
     unresolved = result.unresolved.map(({ token }: { token: string }) => token);
   } catch {
     bound = formula;
+    degraded = true;
   }
 
   try {
-    return { nodes: renderNotationMath(bound), unresolved };
+    return { nodes: renderNotationMath(bound), unresolved, degraded };
   } catch {
     // A marker that KaTeX or the sanitizer rejects must not cost the reader
     // the equation itself.
-    return { nodes: renderNotationMath(formula), unresolved };
+    return { nodes: renderNotationMath(formula), unresolved, degraded: true };
   }
 }