explico 0.4.0 → 0.5.0

package/dist/reference/page-notation.js

@@ -0,0 +1,171 @@
+import {
+  formulaExplainKeys,
+  formulaGlyphScope
+} from "./gloss.js";
+import { resolveReferenceId } from "./references.js";
+const dependenciesByLocals = /* @__PURE__ */ new WeakMap();
+function registerPageNotationDependencies(locals, keys, context) {
+  let byKey = dependenciesByLocals.get(locals);
+  if (!byKey) {
+    byKey = /* @__PURE__ */ new Map();
+    dependenciesByLocals.set(locals, byKey);
+  }
+  for (const key of keys) {
+    let contexts = byKey.get(key);
+    if (!contexts) {
+      contexts = /* @__PURE__ */ new Set();
+      byKey.set(key, contexts);
+    }
+    contexts.add(context);
+  }
+}
+function pageNotationDependencies(locals) {
+  const byKey = dependenciesByLocals.get(locals);
+  if (!byKey) return [];
+  return [...byKey].flatMap(
+    ([key, contexts]) => [...contexts].map((context) => ({ key, context }))
+  ).sort(
+    (left, right) => left.key.localeCompare(right.key) || left.context.localeCompare(right.context)
+  );
+}
+function routeIdFromLocals(locals) {
+  const id = locals.starlightRoute?.entry?.id;
+  return typeof id === "string" ? id : void 0;
+}
+function notationKeysInMathNodes(nodes) {
+  const keys = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    const candidate = node;
+    const key = candidate.properties?.["data-notation-key"];
+    if (key) keys.add(key);
+    for (const child of candidate.children ?? []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return [...keys].sort();
+}
+function manifestDefinition(definition, cardsByKey) {
+  return {
+    id: definition.id,
+    key: definition.key,
+    scope: definition.kind === "shared" ? "shared" : "local",
+    notation: definition.notation,
+    label: definition.label,
+    summary: definition.summary,
+    editorialStatus: definition.status,
+    seeAlso: [...definition.seeAlso],
+    glosses: [...definition.glosses],
+    formulaScope: formulaGlyphScope({
+      key: definition.key,
+      notation: definition.notation,
+      glosses: definition.glosses,
+      cardsByKey,
+      ...definition.formula === void 0 ? {} : { formula: definition.formula }
+    }),
+    ...definition.units === void 0 ? {} : { units: definition.units },
+    ...definition.formula === void 0 ? {} : { formula: definition.formula }
+  };
+}
+function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
+  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  if (!lesson) return [];
+  const definitionsById = new Map(
+    manifest.notation.definitions.map((definition) => [definition.id, definition])
+  );
+  const availableIds = new Set(definitionsById.keys());
+  const ids = new Set(lesson.notation.definitionIds);
+  const contextsByKey = /* @__PURE__ */ new Map();
+  for (const dependency of dependencies) {
+    let contexts = contextsByKey.get(dependency.key);
+    if (!contexts) {
+      contexts = /* @__PURE__ */ new Set();
+      contextsByKey.set(dependency.key, contexts);
+    }
+    contexts.add(dependency.context);
+    const definitionId = resolveReferenceId(
+      dependency.key,
+      { kind: "page", lessonId },
+      availableIds
+    );
+    if (!definitionId) {
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": ${dependency.context} emitted data-notation-key="${dependency.key}", but that key is not defined in this lesson or the shared notation registry.`
+      );
+    }
+    ids.add(definitionId);
+  }
+  const pending = [...ids];
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (!id) continue;
+    const definition = definitionsById.get(id);
+    for (const reference of definition?.resolvedReferences ?? []) {
+      if (ids.has(reference.definitionId)) continue;
+      ids.add(reference.definitionId);
+      pending.push(reference.definitionId);
+    }
+    for (const key of formulaExplainKeys(definition?.formula ?? "")) {
+      if (!definition) continue;
+      const formulaDependencyId = resolveReferenceId(
+        key,
+        definition.scope,
+        availableIds
+      );
+      if (!formulaDependencyId || ids.has(formulaDependencyId)) continue;
+      ids.add(formulaDependencyId);
+      pending.push(formulaDependencyId);
+    }
+  }
+  const definitionIdByKey = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    const definition = definitionsById.get(id);
+    if (!definition) continue;
+    const previous = definitionIdByKey.get(definition.key);
+    if (previous && previous !== id) {
+      const context = [...contextsByKey.get(definition.key) ?? []].join(", ");
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": key "${definition.key}" would have two meanings (${previous} and ${id})` + (context ? ` after ${context} emitted it.` : ".")
+      );
+    }
+    definitionIdByKey.set(definition.key, id);
+  }
+  const cardsByKey = /* @__PURE__ */ new Map();
+  for (const definition of manifest.notation.definitions) {
+    if (definition.kind !== "shared") continue;
+    cardsByKey.set(definition.key, {
+      key: definition.key,
+      notation: definition.notation
+    });
+  }
+  const existingById = new Map(
+    lesson.notation.definitions.map((definition) => [definition.id, definition])
+  );
+  return [...ids].sort().flatMap((id) => {
+    const existing = existingById.get(id);
+    if (existing) return [existing];
+    const definition = definitionsById.get(id);
+    return definition ? [manifestDefinition(definition, cardsByKey)] : [];
+  });
+}
+function missingNotationPayloadKeys(html) {
+  const attributeValues = (name) => {
+    const values = /* @__PURE__ */ new Set();
+    const pattern = new RegExp(`${name}=(?:"([^"]+)"|'([^']+)')`, "g");
+    for (const match of html.matchAll(pattern)) {
+      const value = match[1] ?? match[2];
+      if (value) values.add(value);
+    }
+    return values;
+  };
+  const triggers = attributeValues("data-notation-key");
+  const entries = attributeValues("data-notation-entry");
+  return [...triggers].filter((key) => !entries.has(key)).sort();
+}
+export {
+  missingNotationPayloadKeys,
+  notationDefinitionsForRenderedPage,
+  notationKeysInMathNodes,
+  pageNotationDependencies,
+  registerPageNotationDependencies,
+  routeIdFromLocals
+};

package/dist/reference/raw-floats-validate.d.ts

@@ -0,0 +1,18 @@
+/** Diagnostics for raw/unwrapped floats — see `raw-floats.mjs`. */
+type RawFloatDiagnosticCode = 'raw-table-markdown' | 'raw-table-html' | 'diagram-unkeyed' | 'diagram-nested';
+interface RawFloatDiagnostic {
+    readonly code: RawFloatDiagnosticCode;
+    readonly severity: 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+}
+interface RawFloatLessonInput {
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly file: string;
+    readonly body: string;
+}
+declare function validateRawFloats(lessons: readonly RawFloatLessonInput[]): readonly RawFloatDiagnostic[];
+
+export { type RawFloatDiagnostic, type RawFloatDiagnosticCode, type RawFloatLessonInput, validateRawFloats };

package/dist/reference/raw-floats-validate.js

@@ -0,0 +1,53 @@
+import { scanRawFloats } from "./raw-floats.mjs";
+function plural(count, noun) {
+  return count === 1 ? noun : `${noun}s`;
+}
+function validateRawFloats(lessons) {
+  const diagnostics = [];
+  const push = (lesson, code, count, message) => {
+    if (count === 0) return;
+    diagnostics.push({
+      code,
+      severity: "warning",
+      message: message(count),
+      file: lesson.file,
+      lessonId: lesson.lessonId
+    });
+  };
+  for (const lesson of [...lessons].sort(
+    (a, b) => a.lessonId.localeCompare(b.lessonId)
+  )) {
+    const found = scanRawFloats(lesson.body);
+    push(
+      lesson,
+      "raw-table-markdown",
+      found.markdownTableCount,
+      (count) => `${lesson.lessonId} has ${count} raw Markdown ${plural(count, "table")} not wrapped in <Table>; ${count === 1 ? "it has" : "they have"} no stable number and cannot be referenced with [[tab-\u2026]]. Wrap it in <Table id="\u2026">\u2026</Table> to give it one.`
+    );
+    push(
+      lesson,
+      "raw-table-html",
+      found.htmlTableCount,
+      (count) => `${lesson.lessonId} has ${count} raw HTML <table> ${plural(count, "element")} not wrapped in <Table>; ${count === 1 ? "it has" : "they have"} no stable number and cannot be referenced with [[tab-\u2026]]. Wrap it in <Table id="\u2026">\u2026</Table> to give it one.`
+    );
+    push(
+      lesson,
+      "diagram-unkeyed",
+      found.unkeyedDiagramCount,
+      (count) => `${lesson.lessonId} has ${count} <Diagram> ${plural(count, "component")} with no id; ${count === 1 ? "it" : "they"} cannot be referenced with [[dia-\u2026]]. Add an id to give it a stable reference.`
+    );
+    push(
+      lesson,
+      "diagram-nested",
+      found.nestedDiagramCount,
+      (count) => `${lesson.lessonId} has ${count} <Diagram> ${plural(count, "component")} nested inside another component; ${count === 1 ? "it is" : "they are"} invisible to diagram numbering. Move it to the top level (or inside <Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`
+    );
+  }
+  diagnostics.sort(
+    (a, b) => a.code.localeCompare(b.code) || (a.lessonId ?? "").localeCompare(b.lessonId ?? "")
+  );
+  return diagnostics;
+}
+export {
+  validateRawFloats
+};

package/dist/reference/raw-floats.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Counts of raw/unwrapped content in one lesson body. See the module doc for
+ * what each count means and why `<Diagram>` needs the extra visible/nested
+ * split that raw tables don't.
+ */
+export function scanRawFloats(markdown: any): {
+    markdownTableCount: number;
+    htmlTableCount: number;
+    nestedDiagramCount: number;
+    unkeyedDiagramCount: number;
+};
+/** The mdast equivalent of `scanRawFloats` — same counts, plus the nodes. */
+export function collectRawFloats(tree: any): {
+    markdownTableNodes: any[];
+    htmlTableNodes: any[];
+    nestedDiagramNodes: any[];
+    unkeyedDiagramNodes: any[];
+};

package/dist/reference/raw-floats.mjs

@@ -0,0 +1,129 @@
+/**
+ * Detection for content invisible to keyed-float validation:
+ *
+ * - a raw Markdown pipe table or raw HTML `<table>` that was never wrapped in
+ *   `<Table>`/`<Figure>`, so it can never get a stable number or be
+ *   referenced with `[[tab-…]]`;
+ * - an Explico `<Diagram>` with no `id` (can't be referenced with
+ *   `[[dia-…]]` even though it participates in diagram numbering);
+ * - an Explico `<Diagram>` nested inside some other, non-transparent
+ *   component (anything but `<Memo>`/`<ShortNote>`, or `<Table>`/`<Figure>`
+ *   which legitimately gives it identity) — invisible to
+ *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
+ *   reaches diagram numbering.
+ *
+ * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
+ * and is not flagged; nesting inside anything else (`<CompactExample>`,
+ * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
+ * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
+ * transparent scan does.
+ *
+ * `scanRawFloats` (raw Markdown, for the manifest builder) and
+ * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
+ * — `tests/notation/raw-floats.test.ts` checks that, the same contract
+ * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
+
+/** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
+function blankFloatWrappers(text) {
+  return text.replace(
+    /<(Table|Figure)\b(?:\s[^>]*)?>[\s\S]*?<\/\1\s*>/g,
+    (block) => block.replace(/[^\n]/g, ' '),
+  );
+}
+
+/** Line index of every GFM pipe-table header + delimiter-row pair. */
+function findMarkdownTableStarts(text) {
+  const lines = text.split('\n');
+  const delimiterRow =
+    /^[ \t]{0,3}\|?[ \t]*:?-+:?[ \t]*(\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/;
+  const hits = [];
+  for (let index = 0; index < lines.length - 1; index++) {
+    const header = lines[index];
+    const delimiter = lines[index + 1];
+    if (!header.includes('|')) continue;
+    if (!delimiter.includes('-') || !delimiterRow.test(delimiter)) continue;
+    hits.push(index);
+  }
+  return hits;
+}
+
+function findHtmlTableTags(text) {
+  return [...text.matchAll(/<table\b/gi)];
+}
+
+function findDiagramTags(text) {
+  return [...text.matchAll(/<Diagram\b/g)];
+}
+
+/**
+ * Counts of raw/unwrapped content in one lesson body. See the module doc for
+ * what each count means and why `<Diagram>` needs the extra visible/nested
+ * split that raw tables don't.
+ */
+export function scanRawFloats(markdown) {
+  const codeStripped = stripFencedCode(String(markdown));
+  const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+
+  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
+  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+
+  const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
+  const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
+  const nestedDiagramCount = Math.max(
+    0,
+    diagramsOutsideWrappers - visibleDiagrams.length,
+  );
+  const unkeyedDiagramCount = visibleDiagrams.filter(
+    (diagram) => diagram.key == null,
+  ).length;
+
+  return {
+    markdownTableCount,
+    htmlTableCount,
+    nestedDiagramCount,
+    unkeyedDiagramCount,
+  };
+}
+
+/** The mdast equivalent of `scanRawFloats` — same counts, plus the nodes. */
+export function collectRawFloats(tree) {
+  const markdownTableNodes = [];
+  const htmlTableNodes = [];
+  const allDiagramNodes = [];
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Table' || node.name === 'Figure')
+    ) {
+      return; // legitimately wrapped — don't descend
+    }
+    if (node.type === 'table') markdownTableNodes.push(node);
+    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+      htmlTableNodes.push(node);
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
+      allDiagramNodes.push(node);
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) walk(child);
+    }
+  };
+  walk(tree);
+
+  const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
+  const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));
+  const nestedDiagramNodes = allDiagramNodes.filter(
+    (node) => !visibleNodes.has(node),
+  );
+  const unkeyedDiagramNodes = visibleDiagrams
+    .filter((diagram) => diagram.key == null)
+    .map((diagram) => diagram.node);
+
+  return { markdownTableNodes, htmlTableNodes, nestedDiagramNodes, unkeyedDiagramNodes };
+}

package/dist/reference/rehype-heading-anchors.d.mts

@@ -1 +1 @@
-export default function rehypeHeadingAnchors(): (tree: any, file: any) => void;
+export default function rehypeHeadingAnchors(options?: {}): (tree: any, file: any) => void;

package/dist/reference/rehype-heading-anchors.mjs

@@ -22,6 +22,27 @@
  * idempotent (only assigns a missing `id`, and rebuilds `file.data.astro.headings`
  * from an unchanged document order), so this plugin runs it first and Astro's
  * later pass becomes a no-op for these headings.
+ *
+ * Collapsibility (docs/plans/collapsible-disclosure.md Part 3) has a
+ * site-wide default — `defaultCollapsible: { sections, subsections }`, an
+ * option to this plugin (see `astro.config.mjs`), each of `{ collapsible,
+ * defaultOpen }` — plus a per-heading marker an author can append to
+ * override it for one heading:
+ *
+ *   - `[collapsible]` — collapsible, starts open, regardless of the default.
+ *   - `[collapsed]` — collapsible, starts *closed*, regardless of the default.
+ *   - `[no-collapsible]` — never collapsible, regardless of the default.
+ *   - no marker — falls back to the site default for this heading's rank:
+ *     `sections` governs `h2`, `subsections` governs `h3`-`h6`. `collapsible`
+ *     decides whether it's wrapped at all; `defaultOpen` decides its initial
+ *     state when it is (ignored, like the rest of the category, when
+ *     `collapsible` is `false`).
+ *
+ * The marker is stripped from the rendered text and the *resolved* decision
+ * (not the raw marker) becomes `data-collapsible="true"` +
+ * `data-default-open="true"|"false"` on the wrapper — `CollapsibleSections.astro`
+ * only wraps headings carrying `data-collapsible` and never needs to know
+ * about the config or the marker syntax itself.
  */
 
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
@@ -47,6 +68,50 @@ function headingText(node) {
   return text.replace(/\s+/g, ' ').trim();
 }
 
+// A heading's marker, e.g. `## Some title [collapsed]`, stripped from the
+// rendered text. Square brackets, not curly braces (`{collapsed}`) — every
+// lesson here is authored as `.mdx`, where `{...}` is a JS expression
+// container (MDX tries to evaluate `collapsed` as a variable and the build
+// fails), not literal text the way it is in plain Markdown. An unmatched
+// `[collapsed]` with no link/reference definition of that name is just
+// literal text in both dialects. Deliberately not a general attribute syntax
+// (e.g. `{#id .class}`) — this codebase has no remark-attr-style plugin, and
+// three purpose-built tokens are enough for what an author needs to say
+// about a heading here.
+const COLLAPSIBLE_MARKER = /\s*\[(collapsible|collapsed|no-collapsible)\]\s*$/i;
+
+function stripCollapsibleMarker(headingNode) {
+  const children = headingNode.children;
+  for (let index = children.length - 1; index >= 0; index--) {
+    const node = children[index];
+    if (node.type !== 'text') return null; // trailing non-text node: no marker
+    const match = COLLAPSIBLE_MARKER.exec(node.value);
+    if (match) {
+      node.value = node.value.slice(0, match.index);
+      if (!node.value) children.splice(index, 1);
+      return match[1].toLowerCase();
+    }
+    if (node.value.trim()) return null; // real trailing text, no marker present
+    // trailing whitespace-only text node: keep looking further back
+  }
+  return null;
+}
+
+/**
+ * Resolve a heading's marker (or lack of one) plus the site-wide default for
+ * its rank into a final `{ collapsible, defaultOpen }` decision.
+ */
+function resolveCollapsible(marker, tagName, defaultCollapsible) {
+  if (marker === 'no-collapsible') return { collapsible: false };
+  if (marker === 'collapsed') return { collapsible: true, defaultOpen: false };
+  if (marker === 'collapsible') return { collapsible: true, defaultOpen: true };
+  const rankDefault =
+    tagName === 'h2' ? defaultCollapsible.sections : defaultCollapsible.subsections;
+  return rankDefault.collapsible
+    ? { collapsible: true, defaultOpen: rankDefault.defaultOpen }
+    : { collapsible: false };
+}
+
 function isHeadingWrapper(node) {
   const className = node?.properties?.className;
   return (
@@ -97,10 +162,44 @@ function anchorLink(id, label) {
   };
 }
 
-export default function rehypeHeadingAnchors() {
+const RANK_DEFAULT = { collapsible: false, defaultOpen: true };
+
+export default function rehypeHeadingAnchors(options = {}) {
+  const defaultCollapsible = {
+    sections: { ...RANK_DEFAULT, ...options.defaultCollapsible?.sections },
+    subsections: { ...RANK_DEFAULT, ...options.defaultCollapsible?.subsections },
+  };
   const assignHeadingIds = rehypeHeadingIds();
 
   return function transform(tree, file) {
+    // A marker must be stripped *before* `rehypeHeadingIds` runs — otherwise
+    // the generated slug is built from text that still contains it (e.g.
+    // `two-ways-to-name-the-same-point-collapsed` instead of the clean
+    // title). `collapsibleHeadings` records each heading node's *resolved*
+    // decision, since the marker text is gone by the time the main wrapping
+    // walk below runs.
+    const collapsibleHeadings = new WeakMap();
+    const stripMarkers = (node) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      for (const child of node.children) {
+        if (
+          child?.type === 'element' &&
+          typeof child.tagName === 'string' &&
+          HEADING_TAG.test(child.tagName)
+        ) {
+          const marker = stripCollapsibleMarker(child);
+          collapsibleHeadings.set(
+            child,
+            resolveCollapsible(marker, child.tagName, defaultCollapsible),
+          );
+        }
+        stripMarkers(child);
+      }
+    };
+    stripMarkers(tree);
+
     assignHeadingIds(tree, file);
 
     const walk = (node) => {
@@ -123,12 +222,19 @@ export default function rehypeHeadingAnchors() {
           child.properties.id.length > 0
         ) {
           const id = child.properties.id;
+          const decision = collapsibleHeadings.get(child) ?? { collapsible: false };
           const label = `Section titled “${headingText(child)}”`;
           node.children[index] = {
             type: 'element',
             tagName: 'div',
             properties: {
               className: ['sl-heading-wrapper', `level-${child.tagName}`],
+              ...(decision.collapsible
+                ? {
+                    'data-collapsible': 'true',
+                    'data-default-open': String(decision.defaultOpen),
+                  }
+                : {}),
             },
             children: [child, anchorLink(id, label)],
           };

package/dist/reference/rehype-table-header-labels.d.mts

@@ -0,0 +1,26 @@
+/**
+ * Whether `node` already has real, visible text a screen reader would read
+ * as this `<th>`'s accessible name — anything outside a `.katex` subtree. A
+ * `.katex` span is treated as opaque here on purpose: its `.katex-mathml`
+ * child holds the MathML `<math>` axe won't read, and its `.katex-html`
+ * child is `aria-hidden="true"`, so neither counts either way — a header
+ * that already carries a descriptive word (`Launch speed $\text{(m/s)}$`)
+ * sees that word as a normal text-node sibling and is left alone.
+ */
+export function hasVisibleText(node: any): any;
+/** Every `application/x-tex` annotation's raw source inside `node`, in order. */
+export function collectMathSource(node: any, out?: any[]): any[];
+/** Every `\explain{key}{…}` key named across one or more LaTeX sources, in order, deduped. */
+export function explainKeysIn(sources: any): string[];
+/**
+ * `"Label (units)"` per key, joined with `" / "` for a header that binds
+ * more than one (a ratio like `\mathrm{KE}/m`, explain-wrapped on both
+ * sides). `undefined` when nothing resolved, so the caller leaves the
+ * header exactly as it was rather than inserting an empty/placeholder label.
+ */
+export function composeHeaderLabel(keys: any, notationResolved: any): any;
+/**
+ * See the module doc above. No plugin options — everything it needs is
+ * already on `file.data.notationResolved` by the time it runs.
+ */
+export default function rehypeTableHeaderLabels(): (tree: any, file: any) => void;