explico 0.11.1 → 0.13.0

package/dist/reference/sections-validate.js

@@ -1,18 +1,23 @@
 import { lessonLine } from "./gate-prose-notation.js";
-import { parseSectionRef } from "./sections.mjs";
+import { parseSectionRef, scanOutlineBlocks } from "./sections.mjs";
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
 function withoutCode(text) {
   const blank = (block) => block.replace(/[^\n]/g, " ");
   return text.replace(/```[\s\S]*?```/g, blank).replace(/~~~[\s\S]*?~~~/g, blank).replace(/`[^`\n]*`/g, blank);
 }
-function unresolved(ref, lessonExists) {
+function unresolved(ref, lessonExists, pages) {
   const written = ref.lesson ? `[[${ref.lesson}#sec-${ref.key}]]` : `[[sec-${ref.key}]]`;
+  const page = ref.lesson?.replace(/\/index$/, "");
+  if (page !== void 0 && !lessonExists && pages.has(page)) {
+    return `${written} names ${page}, a page that is not a chapter: a section reference reaches a chapter's top-level headings only (rule S10). Link the heading with a Markdown link instead, [its words](/${page}/#${ref.key}).`;
+  }
   if (ref.lesson && !lessonExists) {
     return `${written} names lesson ${ref.lesson}, which does not exist.`;
   }
   return `${written} names no heading: ${ref.lesson ? `lesson ${ref.lesson}` : "this lesson"} has no top-level heading anchored #${ref.key}. A heading's anchor is its text in lowercase with spaces as hyphens and punctuation dropped: \`## Two ways to name the same point\` is \`[[sec-two-ways-to-name-the-same-point]]\`.`;
 }
-function validateSectionRefs(lessons) {
+function validateSectionRefs(lessons, pageSlugs = []) {
+  const pages = new Set(pageSlugs.map((slug) => slug.replace(/\/index$/, "")));
   const headingsByLesson = new Map(
     lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)])
   );
@@ -30,12 +35,34 @@ function validateSectionRefs(lessons) {
         file: lesson.file,
         line: lessonLine(lesson, match.index ?? 0),
         token: match[0],
-        message: unresolved(ref, headings !== void 0)
+        message: unresolved(ref, headings !== void 0, pages)
       });
     }
   }
   return diagnostics;
 }
+function validateHeadingAnchors(lessons) {
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const offsets = scanOutlineBlocks(lesson.body).filter((block) => block.kind === "heading").map((block) => block.index);
+    lesson.headings.forEach((heading, index) => {
+      const owner = lesson.anchors.get(heading.slug);
+      if (owner === void 0) return;
+      const advice = heading.slug === "references" ? "Rename the heading, or drop it: the References section is generated from the page\u2019s citations." : `Rename the heading, or give ${owner} another id.`;
+      diagnostics.push({
+        context: "structure",
+        code: "heading-anchor-collision",
+        severity: "error",
+        file: lesson.file,
+        line: lessonLine(lesson, offsets[index] ?? 0),
+        token: heading.text,
+        message: `The heading "${heading.text}" gets the anchor #${heading.slug}, which ${owner} already has on this page, so a link to either lands on the first. ${advice}`
+      });
+    });
+  }
+  return diagnostics;
+}
 export {
+  validateHeadingAnchors,
   validateSectionRefs
 };

package/dist/reference/sections.d.mts

@@ -20,13 +20,26 @@ export function sectionNumbers(levels: any, { prefix, depth, unnumbered }?: {
     unnumbered?: never[] | undefined;
 }): any;
 /**
- * The text a heading's source renders as, near enough to slug it the way
- * Astro would: markup goes, the words stay. Inline code and math keep their
- * source (math renders as KaTeX, whose text is no use as a slug); a notation
- * term keeps its key; a link keeps its text; an image, a citation and an MDX
- * expression contribute nothing; the authoring marker is dropped.
+ * The text a heading's source slugs as, near enough to the way Astro would:
+ * math as it reads, a notation term its key. A heading's anchor is made from
+ * it, so a plain heading keeps the id it always had; math reads as it renders
+ * (`mathSlugText`), so `## The range $\explain{motion.range}{R}$` is
+ * `#the-range-r` and not `#the-range-explainmotionranger`.
  */
 export function headingPlainText(source: any): string;
+/**
+ * The text a reader sees for a math span: KaTeX's MathML without the LaTeX
+ * annotation, so `$\explain{motion.range}{R}$` reads `R` and `$v_0$` reads
+ * `v0`. Falls back to the source when KaTeX cannot render it.
+ */
+export function mathPlainText(latex: any): any;
+/**
+ * The text a reader sees for a heading: math as it reads (`mathPlainText`)
+ * and a `[[key]]` term as its label, from `labelFor` (the page's notation),
+ * else as its key. "On this page", an unnumbered section's quoted title and a
+ * copied link name use it; the anchor is `headingPlainText`'s.
+ */
+export function headingDisplayText(source: any, { labelFor }?: {}): string;
 /**
  * Anchors for a page's headings, in order, from Astro's own `rehypeHeadingIds`
  * run over their plain text: the same slugger with the same duplicate
@@ -36,9 +49,14 @@ export function slugHeadings(texts: any): any;
 /**
  * Every top-level heading of a lesson body in document order, as the
  * manifest records it: `{ level, text, slug, number? }`. `prefix` is the
- * chapter's `‹part›.‹chapter›`; without one nothing is numbered.
+ * chapter's `‹part›.‹chapter›`; without one nothing is numbered. `text` is
+ * what a reader sees (`headingDisplayText`, with `labelFor` naming a
+ * `[[key]]` term); the `slug` is made from `headingPlainText`.
+ * `math: true` marks a heading with inline math, whose text Astro's own
+ * heading list garbles (`LayoutPageSidebar.astro` relabels it).
  */
 export function scanSectionHeadings(markdown: any, options?: {}): {
+    math?: boolean | undefined;
     number?: any;
     level: number;
     text: string;

package/dist/reference/sections.mjs

@@ -27,6 +27,8 @@
  */
 
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import katex from 'katex';
+import { createNotationKatexOptions } from './katex-options.mjs';
 import { headingCardTier, stripHeadingMarker } from './rehype-heading-anchors.mjs';
 
 /** The deepest heading level numbered when a course sets nothing (`####`). */
@@ -113,19 +115,18 @@ const ATX_HEADING = /^[ \t]{0,3}(#{1,6})(?:[ \t]+([^\n]*?))?(?:[ \t]+#+)?[ \t]*$
 const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
 
 /**
- * The text a heading's source renders as, near enough to slug it the way
- * Astro would: markup goes, the words stay. Inline code and math keep their
- * source (math renders as KaTeX, whose text is no use as a slug); a notation
- * term keeps its key; a link keeps its text; an image, a citation and an MDX
+ * A heading source's text, with `math` and `term` deciding what a `$…$` span
+ * and a `[[key]]` contribute. Markup goes, the words stay; inline code keeps
+ * its source; a link keeps its text; an image, a citation and an MDX
  * expression contribute nothing; the authoring marker is dropped.
  */
-export function headingPlainText(source) {
+function headingText(source, { math, term }) {
   const literals = [];
   const keep = (value) => `\u0000${literals.push(value) - 1}\u0000`;
   let text = stripHeadingMarker(source ?? '')
     .replace(/(`+)([\s\S]*?[^`])\1(?!`)/g, (_, _ticks, code) => keep(code.trim()))
-    .replace(/\$([^$\n]+)\$/g, (_, latex) => keep(latex.trim()))
-    .replace(/\[\[\s*([^\][]+?)\s*\]\]/g, (_, key) => keep(key))
+    .replace(/\$([^$\n]+)\$/g, (_, latex) => keep(math(latex.trim())))
+    .replace(/\[\[\s*([^\][]+?)\s*\]\]/g, (_, key) => keep(term(key)))
     .replace(/\[@[^\]]*\]/g, '')
     .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
     .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
@@ -138,17 +139,84 @@ export function headingPlainText(source) {
     .replace(/(^|[^\w])_(?=\S)([\s\S]*?\S)_(?!\w)/g, '$1$2')
     .replace(/~~(?=\S)([\s\S]*?\S)~~/g, '$1')
     .replace(/\\([!-/:-@[-`{-~])/g, '$1')
-    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => {
-      if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
-      const code = name[1] === 'x' || name[1] === 'X'
-        ? Number.parseInt(name.slice(2), 16)
-        : Number.parseInt(name.slice(1), 10);
-      return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
-    });
+    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => decodeEntity(entity, name));
   text = text.replace(/\u0000(\d+)\u0000/g, (_, index) => literals[Number(index)]);
   return text.replace(/\s+/g, ' ').trim();
 }
 
+function decodeEntity(entity, name) {
+  if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
+  const code = name[1] === 'x' || name[1] === 'X'
+    ? Number.parseInt(name.slice(2), 16)
+    : Number.parseInt(name.slice(1), 10);
+  return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
+}
+
+/**
+ * The text a heading's source slugs as, near enough to the way Astro would:
+ * math as it reads, a notation term its key. A heading's anchor is made from
+ * it, so a plain heading keeps the id it always had; math reads as it renders
+ * (`mathSlugText`), so `## The range $\explain{motion.range}{R}$` is
+ * `#the-range-r` and not `#the-range-explainmotionranger`.
+ */
+export function headingPlainText(source) {
+  return headingText(source, { math: mathSlugText, term: (key) => key });
+}
+
+/** A Greek letter as LaTeX names it, for a slug that stays in ASCII. */
+const GREEK_NAMES = {
+  α: 'alpha', β: 'beta', γ: 'gamma', δ: 'delta', ε: 'epsilon', ϵ: 'epsilon', ζ: 'zeta', η: 'eta',
+  θ: 'theta', ϑ: 'theta', ι: 'iota', κ: 'kappa', λ: 'lambda', μ: 'mu', ν: 'nu', ξ: 'xi', ο: 'omicron',
+  π: 'pi', ϖ: 'pi', ρ: 'rho', ϱ: 'rho', σ: 'sigma', ς: 'sigma', τ: 'tau', υ: 'upsilon', φ: 'phi',
+  ϕ: 'phi', χ: 'chi', ψ: 'psi', ω: 'omega', Γ: 'Gamma', Δ: 'Delta', Θ: 'Theta', Λ: 'Lambda',
+  Ξ: 'Xi', Π: 'Pi', Σ: 'Sigma', Υ: 'Upsilon', Φ: 'Phi', Ψ: 'Psi', Ω: 'Omega',
+};
+
+/**
+ * The text a heading's math slugs as: what it reads, each Greek letter spelled
+ * as LaTeX names it. `$e^{\lambda\cos(u)}$` reads `eλcos(u)` and slugs as
+ * `elambdacosu`, the anchor its source always gave it; what changes is the
+ * markup that never shows (`\explain{motion.range}{R}` is `R`).
+ */
+function mathSlugText(latex) {
+  return mathPlainText(latex).replace(/[\u0370-\u03FF]/g, (char) => GREEK_NAMES[char] ?? char);
+}
+
+/**
+ * The text a reader sees for a math span: KaTeX's MathML without the LaTeX
+ * annotation, so `$\explain{motion.range}{R}$` reads `R` and `$v_0$` reads
+ * `v0`. Falls back to the source when KaTeX cannot render it.
+ */
+export function mathPlainText(latex) {
+  let markup;
+  try {
+    markup = katex.renderToString(latex, createNotationKatexOptions());
+  } catch {
+    return latex;
+  }
+  const mathml = /<math[\s\S]*?<\/math>/.exec(markup)?.[0] ?? '';
+  return mathml
+    .replace(/<annotation[\s\S]*?<\/annotation>/g, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => decodeEntity(entity, name))
+    .replace(/[\u200b\u2061-\u2064]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * The text a reader sees for a heading: math as it reads (`mathPlainText`)
+ * and a `[[key]]` term as its label, from `labelFor` (the page's notation),
+ * else as its key. "On this page", an unnumbered section's quoted title and a
+ * copied link name use it; the anchor is `headingPlainText`'s.
+ */
+export function headingDisplayText(source, { labelFor } = {}) {
+  return headingText(source, {
+    math: mathPlainText,
+    term: (key) => labelFor?.(key) ?? key,
+  });
+}
+
 /**
  * Anchors for a page's headings, in order, from Astro's own `rehypeHeadingIds`
  * run over their plain text: the same slugger with the same duplicate
@@ -171,18 +239,24 @@ export function slugHeadings(texts) {
 /**
  * Every top-level heading of a lesson body in document order, as the
  * manifest records it: `{ level, text, slug, number? }`. `prefix` is the
- * chapter's `‹part›.‹chapter›`; without one nothing is numbered.
+ * chapter's `‹part›.‹chapter›`; without one nothing is numbered. `text` is
+ * what a reader sees (`headingDisplayText`, with `labelFor` naming a
+ * `[[key]]` term); the `slug` is made from `headingPlainText`.
+ * `math: true` marks a heading with inline math, whose text Astro's own
+ * heading list garbles (`LayoutPageSidebar.astro` relabels it).
  */
 export function scanSectionHeadings(markdown, options = {}) {
   const found = [];
   for (const match of outlineSource(markdown).matchAll(ATX_HEADING)) {
     found.push({
       level: match[1].length,
-      text: headingPlainText(match[2] ?? ''),
+      slugText: headingPlainText(match[2] ?? ''),
+      text: headingDisplayText(match[2] ?? '', options),
+      math: /\$[^$\n]+\$/.test(stripHeadingMarker(match[2] ?? '')),
       meta: headingCardTier(match[2] ?? '') === 'meta',
     });
   }
-  const slugs = slugHeadings(found.map((heading) => heading.text));
+  const slugs = slugHeadings(found.map((heading) => heading.slugText));
   const numbers = sectionNumbers(
     found.map((heading) => heading.level),
     { ...options, unnumbered: found.map((heading) => heading.meta) },
@@ -192,6 +266,7 @@ export function scanSectionHeadings(markdown, options = {}) {
     text: heading.text,
     slug: slugs[index],
     ...(numbers[index] === undefined ? {} : { number: numbers[index] }),
+    ...(heading.math ? { math: true } : {}),
   }));
 }
 

package/dist/reference/tables-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
 
-type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused' | 'tab-removed-prop';
+type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused' | 'tab-removed-prop' | 'tab-unread-prop' | 'tab-several-tables';
 interface TableDiagnostic {
     readonly code: TableDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/tables-validate.js

@@ -2,11 +2,34 @@ import {
   validateKeyedFloats
 } from "./keyed-float-validate.js";
 function validateTables(lessons) {
-  return validateKeyedFloats(lessons, {
+  const validation = validateKeyedFloats(lessons, {
     tagName: "Table",
     prefix: "tab",
     noun: "table"
   });
+  const several = lessons.flatMap(severalTables);
+  return several.length === 0 ? validation : { ...validation, diagnostics: [...validation.diagnostics, ...several] };
+}
+const DELIMITER_ROW = /^[ \t]*\|?(?:[ \t]*:?-+:?[ \t]*\|)+(?:[ \t]*:?-+:?[ \t]*)?$/gm;
+function severalTables(lesson) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  const body = lesson.body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const found = [];
+  for (const table of body.matchAll(/<Table\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?<!\/)>([\s\S]*?)<\/Table>/g)) {
+    const inner = table[2] ?? "";
+    const count = (inner.match(DELIMITER_ROW)?.length ?? 0) + (inner.match(/<table\b/g)?.length ?? 0);
+    if (count < 2) continue;
+    const key = /\bid\s*=\s*["']([^"']*)["']/.exec(table[1] ?? "")?.[1];
+    found.push({
+      code: "tab-several-tables",
+      severity: "error",
+      message: `${lesson.lessonId} has a <Table${key ? ` id="${key}"` : ""}> holding ${count} tables: a <Table> holds one, with one number and one caption, and every export keeps only the first. Give each table its own <Table id>, or join them into one.`,
+      file: lesson.file,
+      lessonId: lesson.lessonId,
+      ...key ? { key } : {}
+    });
+  }
+  return found;
 }
 export {
   validateTables

package/dist/reference/text-measure.d.ts

@@ -0,0 +1,10 @@
+/** The advance of `text` at `fontPx`, in px, rounded up to a whole pixel. */
+declare function textWidth(text: string, fontPx: number): number;
+/**
+ * Break `text` into lines no wider than `maxWidth` px, greedily at spaces,
+ * the way a browser wraps it. A word wider than `maxWidth` keeps a line of its
+ * own (the caller widens the box to it); a space never ends or starts a line.
+ */
+declare function wrapText(text: string, maxWidth: number, fontPx: number): string[];
+
+export { textWidth, wrapText };

package/dist/reference/text-measure.js

@@ -0,0 +1,41 @@
+import { UNITS_PER_EM, WIDTH_BLOCKS } from "./text-widths.js";
+const WIDTHS = /* @__PURE__ */ new Map();
+for (const [first, widths] of WIDTH_BLOCKS) {
+  widths.forEach((width, offset) => {
+    if (width >= 0) WIDTHS.set(first + offset, width / UNITS_PER_EM);
+  });
+}
+const FALLBACK_EM = 1;
+const COMBINING_MARK = new RegExp("\\p{M}", "u");
+function advanceEm(char) {
+  if (COMBINING_MARK.test(char)) return 0;
+  return WIDTHS.get(char.codePointAt(0) ?? 0) ?? FALLBACK_EM;
+}
+function textWidth(text, fontPx) {
+  let em = 0;
+  for (const char of text) em += advanceEm(char);
+  return Math.ceil(em * fontPx - 1e-6);
+}
+function wrapText(text, maxWidth, fontPx) {
+  const words = text.trim().split(/[ \t\r\n]+/u).filter(Boolean);
+  const space = textWidth(" ", fontPx);
+  const lines = [];
+  let line = "";
+  let lineWidth = 0;
+  for (const word of words) {
+    const wordWidth = textWidth(word, fontPx);
+    if (line && lineWidth + space + wordWidth > maxWidth) {
+      lines.push(line);
+      line = "";
+      lineWidth = 0;
+    }
+    line = line ? `${line} ${word}` : word;
+    lineWidth = lineWidth ? lineWidth + space + wordWidth : wordWidth;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+export {
+  textWidth,
+  wrapText
+};

package/dist/reference/text-widths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Advance widths of DejaVu Sans (Version 2.37), in font units.
+ * Generated by `scripts/gen-text-widths.mjs` — do not edit by hand.
+ * `-1` marks a code point the font has no glyph for.
+ */
+declare const UNITS_PER_EM = 2048;
+/** `[first code point, widths of it and the code points after it]`. */
+declare const WIDTH_BLOCKS: readonly (readonly [number, readonly number[]])[];
+
+export { UNITS_PER_EM, WIDTH_BLOCKS };