explico 0.4.0 → 0.6.0

package/src/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/src/reference/rehype-table-header-labels.mjs

@@ -0,0 +1,152 @@
+/**
+ * Auto-generated accessible name for a table header cell that is 100%
+ * KaTeX-rendered math (N9: a unit is typeset in `$…$` too, so a header like
+ * `$t\ \text{(s)}$` has no plain DOM text at all). axe-core's
+ * `empty-table-header` rule does not read `<math>` content when computing a
+ * `<th>`'s accessible name, so a sighted or MathML-aware reader sees the
+ * symbol fine while a screen reader hears nothing.
+ *
+ * This was first tried with a plain `aria-label` — wrong, confirmed by
+ * reading axe-core's own rule (`node_modules/axe-core/axe.js`): unlike most
+ * name-checking rules, `empty-table-header` only runs the `has-visible-text`
+ * check (`any: ['has-visible-text']`, no `aria-label`/`aria-labelledby`
+ * alternative in that list), which calls `subtreeText` — it wants real
+ * *content*, not just an accessible name. So this instead inserts a real
+ * `<span class="sr-only">` text node as a child of the `<th>`, using
+ * Starlight's own `.sr-only` utility (`clip: rect(0,0,0,0)`, not
+ * `display:none` — invisible to sighted readers, present in the
+ * accessibility tree, satisfying `subtreeText` the same way any other
+ * visually-hidden accessible label on this site already does, e.g.
+ * `rehype-heading-anchors.mjs`'s anchor labels).
+ *
+ * The label text is composed straight from the notation metadata already
+ * authored for the bound symbol(s): every `\explain{key}{…}` in the header's
+ * LaTeX source names a key, and `remark-notation.mjs` has already resolved
+ * every key used anywhere on the page into `file.data.notationResolved`
+ * (`{key: {label, units, ...}}`) by the time this plugin runs — nothing here
+ * re-derives notation scope.
+ *
+ * Runs after `rehypeKatex` (needs its rendered spans, specifically the
+ * `<annotation encoding="application/x-tex">` KaTeX always embeds with the
+ * exact source it was given, `\explain{}` calls included — whether the
+ * author typed them or `remark-notation.mjs` auto-inserted them).
+ */
+
+// Mirrors `gloss.ts`'s exported `formulaExplainKeys` regex. Not imported:
+// this file is a plain `.mjs` reference module, copied verbatim into `dist/`
+// by `scripts/copy-assets.mjs`, never touched by the tsup build that
+// compiles `gloss.ts` — no existing `.mjs` in this directory imports a `.ts`
+// sibling's compiled output, so this one doesn't start.
+const EXPLAIN_KEY = /\\explain\s*\{\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\}/g;
+
+function isKatexRoot(node) {
+  return (
+    node.type === 'element' &&
+    node.tagName === 'span' &&
+    Array.isArray(node.properties?.className) &&
+    node.properties.className.includes('katex')
+  );
+}
+
+/**
+ * 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) {
+  if (!node || typeof node !== 'object') return false;
+  if (node.type === 'text') {
+    return typeof node.value === 'string' && node.value.trim().length > 0;
+  }
+  if (node.type !== 'element') return false;
+  if (isKatexRoot(node)) return false;
+  return (node.children ?? []).some(hasVisibleText);
+}
+
+/** Every `application/x-tex` annotation's raw source inside `node`, in order. */
+export function collectMathSource(node, out = []) {
+  if (!node || typeof node !== 'object') return out;
+  if (
+    node.type === 'element' &&
+    node.tagName === 'annotation' &&
+    node.properties?.encoding === 'application/x-tex'
+  ) {
+    out.push(
+      (node.children ?? [])
+        .filter((child) => child.type === 'text')
+        .map((child) => child.value)
+        .join(''),
+    );
+  }
+  for (const child of node.children ?? []) collectMathSource(child, out);
+  return out;
+}
+
+/** Every `\explain{key}{…}` key named across one or more LaTeX sources, in order, deduped. */
+export function explainKeysIn(sources) {
+  const seen = new Set();
+  const keys = [];
+  for (const source of sources) {
+    EXPLAIN_KEY.lastIndex = 0;
+    let match;
+    while ((match = EXPLAIN_KEY.exec(source))) {
+      const key = match[1];
+      if (seen.has(key)) continue;
+      seen.add(key);
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+
+/**
+ * `"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, notationResolved) {
+  const parts = keys
+    .map((key) => notationResolved[key])
+    .filter((entry) => entry && typeof entry.label === 'string')
+    .map((entry) => (entry.units ? `${entry.label} (${entry.units})` : entry.label));
+  return parts.length > 0 ? parts.join(' / ') : undefined;
+}
+
+/** A visually-hidden text node — see the module doc for why this, not `aria-label`. */
+function srOnlySpan(label) {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: { className: ['sr-only'] },
+    children: [{ type: 'text', value: label }],
+  };
+}
+
+function labelTableHeaders(node, notationResolved) {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.type === 'element' && node.tagName === 'th' && !hasVisibleText(node)) {
+    const keys = explainKeysIn(collectMathSource(node));
+    const label = composeHeaderLabel(keys, notationResolved);
+    if (label) {
+      node.children = [srOnlySpan(label), ...(node.children ?? [])];
+    }
+  }
+
+  for (const child of node.children ?? []) labelTableHeaders(child, notationResolved);
+}
+
+/**
+ * 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() {
+  return function addTableHeaderLabels(tree, file) {
+    labelTableHeaders(tree, file?.data?.notationResolved ?? {});
+  };
+}

package/src/reference/remark-abbreviations.mjs

@@ -0,0 +1,174 @@
+/**
+ * Remark adapter for the abbreviations table (rule N14).
+ *
+ * Unlike citations, this has no authoring syntax of its own — N14 already
+ * requires every abbreviation-shaped word in prose to either be universal or
+ * carry a `content/abbreviations/*.md` entry, so the literal written form
+ * (`abbr`, or one of its `aliases`) is itself the trigger. This plugin scans
+ * ordinary prose for that literal text and wraps the **first** occurrence per
+ * document in a real link (`/glossary/#abbr-<key>`, so it still navigates
+ * with no JS) carrying the `data-abbr-key` an island script reads to render a
+ * hover/click card, exactly the way `remarkCitation` wraps `[@id]` markers.
+ * Later occurrences of the same term on the same page stay plain text, so a
+ * common short word isn't turned into a link everywhere it appears.
+ *
+ * Matches only ever come from the known table by construction, so unlike
+ * citation's `[@id]` there is no "unknown id" failure path here.
+ *
+ * `abbreviations` is either the compiled manifest's `abbreviations` array
+ * (`{key, abbr, expansion, aliases, domain?}` records) or a loader that
+ * returns it, supplied by the Astro config — same shape citation's `sources`
+ * option accepts, re-evaluated for every document transform.
+ */
+
+const PROSE_SKIP_TYPES = new Set([
+  'code',
+  'definition',
+  'html',
+  'image',
+  'imageReference',
+  'inlineCode',
+  'link',
+  'linkReference',
+  'math',
+  'mdxFlowExpression',
+  'mdxTextExpression',
+  'mdxjsEsm',
+  'toml',
+  'yaml',
+]);
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// A dotted form (`w.r.t.`) ends in `.`, where a trailing `\b` is unreliable —
+// the same reason `gate-abbreviations.ts`'s own `DOTTED_ABBR` regex has no
+// trailing boundary either. Only add the trailing boundary when the form
+// actually ends in a word character.
+function endsWithWordChar(text) {
+  return /\w$/.test(text);
+}
+
+/**
+ * One case-sensitive alternation regex from every entry's `abbr` + `aliases`,
+ * longest-first so a shorter alias that is a prefix of a longer one (`e.g`
+ * vs. `e.g.`) never wins the match. Also returns the exact-text → key lookup
+ * the matched alternative resolves to.
+ */
+function buildMatcher(entries) {
+  const alternatives = [];
+  const keyByMatch = new Map();
+
+  for (const entry of entries) {
+    const key = entry?.key;
+    if (typeof key !== 'string' || key.length === 0) continue;
+
+    const forms = [entry.abbr, ...(Array.isArray(entry.aliases) ? entry.aliases : [])];
+    for (const form of forms) {
+      if (typeof form !== 'string' || form.length === 0) continue;
+      if (keyByMatch.has(form)) continue;
+      keyByMatch.set(form, key);
+      alternatives.push(form);
+    }
+  }
+
+  if (alternatives.length === 0) return { regex: null, keyByMatch };
+
+  alternatives.sort((a, b) => b.length - a.length);
+  const pattern = alternatives
+    .map(
+      (form) =>
+        `\\b${escapeRegExp(form)}${endsWithWordChar(form) ? '\\b' : ''}`,
+    )
+    .join('|');
+
+  return { regex: new RegExp(pattern, 'g'), keyByMatch };
+}
+
+function hrefFor(key, base) {
+  return `${base.replace(/\/$/, '')}/glossary/#abbr-${key}`;
+}
+
+function termNode(key, matchedText, base) {
+  return {
+    type: 'link',
+    url: hrefFor(key, base),
+    children: [{ type: 'text', value: matchedText }],
+    data: {
+      hProperties: {
+        className: ['abbreviation-term'],
+        'data-abbr-key': key,
+      },
+    },
+  };
+}
+
+/**
+ * @param {{ abbreviations?: readonly object[] | (() => readonly object[]), base?: string }} [options]
+ */
+export default function remarkAbbreviations(options = {}) {
+  return function transform(tree) {
+    const suppliedAbbreviations =
+      typeof options.abbreviations === 'function'
+        ? options.abbreviations()
+        : (options.abbreviations ?? []);
+    const base = options.base ?? '';
+
+    const { regex, keyByMatch } = buildMatcher(suppliedAbbreviations);
+    if (!regex) return;
+
+    // Fresh per file, same lifetime as citation's own `pairs` Map: only the
+    // first occurrence of a given key on this page gets wrapped.
+    const usedKeys = new Set();
+
+    const replaceText = (value) => {
+      regex.lastIndex = 0;
+      const output = [];
+      let cursor = 0;
+      let changed = false;
+      let match;
+
+      while ((match = regex.exec(value))) {
+        const key = keyByMatch.get(match[0]);
+        if (!key || usedKeys.has(key)) continue;
+
+        if (match.index > cursor) {
+          output.push({ type: 'text', value: value.slice(cursor, match.index) });
+        }
+        output.push(termNode(key, match[0], base));
+        usedKeys.add(key);
+        changed = true;
+        cursor = match.index + match[0].length;
+      }
+
+      if (!changed) return undefined;
+      if (cursor < value.length) {
+        output.push({ type: 'text', value: value.slice(cursor) });
+      }
+      return output;
+    };
+
+    const visit = (node, skipped) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      if (skipped || PROSE_SKIP_TYPES.has(node.type)) return;
+
+      for (let index = 0; index < node.children.length; index++) {
+        const child = node.children[index];
+        if (child?.type === 'text') {
+          const replacement = replaceText(String(child.value ?? ''));
+          if (replacement) {
+            node.children.splice(index, 1, ...replacement);
+            index += replacement.length - 1;
+          }
+          continue;
+        }
+        visit(child, false);
+      }
+    };
+
+    visit(tree, false);
+  };
+}