explico 0.13.1 → 0.14.0

package/dist/reference/deck-source.d.ts

@@ -0,0 +1,107 @@
+/** A step mark, `<Pause />`, with the props of a driven figure or a spotlight. */
+interface DeckPause {
+    /** Offset of the tag in the deck body. */
+    readonly index: number;
+    /** The label of the lab control a driven figure moves. */
+    readonly control?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly seconds?: string;
+    /** A notation key whose every occurrence on the frame lights up. */
+    readonly highlight?: string;
+    /** Any prop the deck grammar does not know, by name. */
+    readonly unknown: readonly string[];
+}
+interface DeckRecall {
+    readonly index: number;
+    /** As written: `eq-range`, `fig-projectile-trajectory`, `tab-…`, `dia-…`. */
+    readonly ref?: string;
+}
+interface DeckFloatTag {
+    readonly index: number;
+    readonly name: 'Figure' | 'Table' | 'Diagram' | 'CompactExamples' | 'AssessmentSet';
+    readonly id?: string;
+}
+interface DeckMath {
+    readonly index: number;
+    readonly latex: string;
+}
+interface DeckFrameSource {
+    /** `section`: a `##` divider frame; `frame`: a `###` frame. */
+    readonly kind: 'section' | 'frame';
+    /** What the reader sees: math as it reads, a `[[key]]` term as its label. */
+    readonly title: string;
+    /** The heading's anchor, as the page gives it. */
+    readonly slug: string;
+    /** `### Title [morph]`: the frame morphs from the one before it. */
+    readonly morph: boolean;
+    /**
+     * `## Title [chapter: <slug>]` on a part's deck: the chapter the section
+     * covers, as written (the chapter's name in the part's directory). A `###`
+     * frame carries its section's.
+     */
+    readonly chapter?: string;
+    /** Offset of the heading line in the deck body. */
+    readonly index: number;
+    /** Offset where the frame's body ends (the next frame's heading, or the end). */
+    readonly end: number;
+    /** The slug of the `##` section the frame is in, if any. */
+    readonly section?: string;
+    /** The frame's body source, after its heading line. */
+    readonly body: string;
+    /** Offset of {@link body} in the deck body. */
+    readonly bodyIndex: number;
+    readonly pauses: readonly DeckPause[];
+    /** Each `<Notes>…</Notes>` block's inner text. */
+    readonly notes: readonly {
+        readonly index: number;
+        readonly text: string;
+    }[];
+    readonly recalls: readonly DeckRecall[];
+    readonly floats: readonly DeckFloatTag[];
+    /** Display equations in the frame's own text (not its notes). */
+    readonly displayMath: readonly DeckMath[];
+    /** Words a reader sees on the frame: its prose, not its math, tags or notes. */
+    readonly words: number;
+    /** List items on the frame. */
+    readonly bullets: number;
+}
+interface DeckSource {
+    /** Every section divider and frame, in order. */
+    readonly frames: readonly DeckFrameSource[];
+    /** Headings a deck cannot hold: `#`, and `####` or deeper (rule D1). */
+    readonly deepHeadings: readonly {
+        readonly index: number;
+        readonly level: number;
+        readonly text: string;
+    }[];
+    /**
+     * Content that belongs to no frame (rule D1): before the first heading, or
+     * under a `##` before its first `###`.
+     */
+    readonly loose: readonly {
+        readonly index: number;
+        readonly where: 'before' | 'section';
+    }[];
+    /** A heading marker on the wrong level: `[chapter: …]` on a `###`, `[morph]` on a `##`. */
+    readonly misplacedMarkers: readonly {
+        readonly index: number;
+        readonly marker: 'chapter' | 'morph';
+        readonly title: string;
+    }[];
+}
+/** A component tag's string props, by name. */
+declare function tagProps(source: string): Map<string, string>;
+/** The words a frame shows: its prose, without math, tags, comments, citations or notes. */
+declare function visibleWords(text: string): number;
+/**
+ * Read a deck body as frames. `labelFor` names a `[[key]]` term in a heading
+ * as the reader sees it, as for a chapter's outline.
+ */
+declare function readDeckSource(body: string, options?: {
+    readonly labelFor?: (key: string) => string | undefined;
+}): DeckSource;
+/** The frame an offset of the deck body falls in, if any. */
+declare function frameAt(source: DeckSource, index: number): DeckFrameSource | undefined;
+
+export { type DeckFloatTag, type DeckFrameSource, type DeckMath, type DeckPause, type DeckRecall, type DeckSource, frameAt, readDeckSource, tagProps, visibleWords };

package/dist/reference/deck-source.js

@@ -0,0 +1,140 @@
+import { stripFencedCode } from "./equations.mjs";
+import { headingChapter, headingMorphs } from "./rehype-heading-anchors.mjs";
+import { scanOutlineBlocks, scanSectionHeadings } from "./sections.mjs";
+const FLOAT_NAMES = ["Figure", "Table", "Diagram", "CompactExamples", "AssessmentSet"];
+const FLOAT_TAG = new RegExp(`<(${FLOAT_NAMES.join("|")})\\b((?:"[^"]*"|'[^']*'|[^>"'])*)>`, "g");
+const PAUSE_TAG = /<Pause\b((?:"[^"]*"|'[^']*'|[^>"'])*)\/?>/g;
+const RECALL_TAG = /<Recall\b((?:"[^"]*"|'[^']*'|[^>"'])*)\/?>/g;
+const NOTES_BLOCK = /<Notes\s*>([\s\S]*?)<\/Notes\s*>/g;
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+const PROP = /([A-Za-z][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const PAUSE_PROPS = /* @__PURE__ */ new Set(["control", "from", "to", "seconds", "highlight"]);
+function tagProps(source) {
+  const props = /* @__PURE__ */ new Map();
+  for (const match of source.matchAll(PROP)) {
+    props.set(match[1] ?? "", match[2] ?? match[3] ?? "");
+  }
+  return props;
+}
+function blankMatches(text, pattern) {
+  return text.replace(pattern, (match) => match.replace(/[^\n]/g, " "));
+}
+function visibleWords(text) {
+  const prose = text.replace(NOTES_BLOCK, " ").replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/\$\$[\s\S]+?\$\$/g, " ").replace(/\$[^$\n]+\$/g, " ").replace(/\[@[^\]]*\]/g, " ").replace(/\[\[\s*[^\][]+?\s*\]\]/g, " term ").replace(/<\/?[A-Za-z][^>]*>/g, " ").replace(/^[ \t]*(?:import|export)\s.*$/gm, " ").replace(/[#>*_`|~-]/g, " ");
+  return (prose.match(/[\p{L}\p{N}][\p{L}\p{N}'’.-]*/gu) ?? []).length;
+}
+function bulletCount(text) {
+  return (text.replace(NOTES_BLOCK, " ").match(/^[ \t]*(?:[-*+]|\d+[.)])[ \t]+\S/gm) ?? []).length;
+}
+function readDeckSource(body, options = {}) {
+  const source = String(body);
+  const blocks = scanOutlineBlocks(source);
+  const headings = scanSectionHeadings(source, { labelFor: options.labelFor });
+  const scanText = stripFencedCode(source);
+  const deepHeadings = [];
+  const loose = [];
+  const starts = [];
+  let headingCursor = -1;
+  let current;
+  for (const block of blocks) {
+    if (block.kind === "heading") {
+      headingCursor += 1;
+      const heading = headings[headingCursor];
+      if (heading === void 0) continue;
+      if (block.level === 2 || block.level === 3) {
+        const lineEnd = source.indexOf("\n", block.index);
+        starts.push({
+          index: block.index,
+          level: block.level,
+          heading,
+          lineEnd: lineEnd === -1 ? source.length : lineEnd + 1
+        });
+        current = block.level;
+      } else {
+        deepHeadings.push({ index: block.index, level: block.level, text: heading.text });
+      }
+      continue;
+    }
+    if (current === void 0) loose.push({ index: block.index, where: "before" });
+    else if (current === 2) loose.push({ index: block.index, where: "section" });
+  }
+  const frames = [];
+  const misplacedMarkers = [];
+  let section;
+  let sectionChapter;
+  starts.forEach((start, position) => {
+    const end = starts[position + 1]?.index ?? source.length;
+    const bodyIndex = Math.min(start.lineEnd, end);
+    const frameBody = source.slice(bodyIndex, end);
+    const frameScan = scanText.slice(bodyIndex, end);
+    const withoutNotes = blankMatches(frameScan, NOTES_BLOCK);
+    const at = (offset) => bodyIndex + (offset ?? 0);
+    const headingText = source.slice(start.index, start.lineEnd).replace(/^[ \t]*#{1,6}[ \t]+/, "").trimEnd();
+    const morphs = headingMorphs(headingText);
+    const named = headingChapter(headingText) ?? void 0;
+    if (start.level === 2) {
+      section = start.heading.slug;
+      sectionChapter = named;
+      if (morphs) misplacedMarkers.push({ index: start.index, marker: "morph", title: start.heading.text });
+    } else if (named !== void 0) {
+      misplacedMarkers.push({ index: start.index, marker: "chapter", title: start.heading.text });
+    }
+    frames.push({
+      kind: start.level === 2 ? "section" : "frame",
+      title: start.heading.text,
+      slug: start.heading.slug,
+      morph: start.level === 3 && morphs,
+      ...sectionChapter === void 0 ? {} : { chapter: sectionChapter },
+      index: start.index,
+      end,
+      ...start.level === 3 && section !== void 0 ? { section } : {},
+      body: frameBody,
+      bodyIndex,
+      pauses: [...withoutNotes.matchAll(PAUSE_TAG)].map((match) => {
+        const props = tagProps(match[1] ?? "");
+        const value = (name) => props.get(name);
+        return {
+          index: at(match.index),
+          ...value("control") === void 0 ? {} : { control: value("control") },
+          ...value("from") === void 0 ? {} : { from: value("from") },
+          ...value("to") === void 0 ? {} : { to: value("to") },
+          ...value("seconds") === void 0 ? {} : { seconds: value("seconds") },
+          ...value("highlight") === void 0 ? {} : { highlight: value("highlight") },
+          unknown: [...props.keys()].filter((name) => !PAUSE_PROPS.has(name))
+        };
+      }),
+      notes: [...frameScan.matchAll(NOTES_BLOCK)].map((match) => ({
+        index: at(match.index),
+        text: match[1] ?? ""
+      })),
+      recalls: [...withoutNotes.matchAll(RECALL_TAG)].map((match) => {
+        const ref = tagProps(match[1] ?? "").get("ref");
+        return { index: at(match.index), ...ref === void 0 ? {} : { ref } };
+      }),
+      floats: [...withoutNotes.matchAll(FLOAT_TAG)].map((match) => {
+        const id = tagProps(match[2] ?? "").get("id");
+        return {
+          index: at(match.index),
+          name: match[1],
+          ...id === void 0 ? {} : { id }
+        };
+      }),
+      displayMath: [...withoutNotes.matchAll(DISPLAY_MATH)].map((match) => ({
+        index: at(match.index),
+        latex: match[1] ?? ""
+      })),
+      words: start.level === 3 ? visibleWords(withoutNotes) : 0,
+      bullets: start.level === 3 ? bulletCount(withoutNotes) : 0
+    });
+  });
+  return { frames, deepHeadings, loose, misplacedMarkers };
+}
+function frameAt(source, index) {
+  return source.frames.find((frame) => index >= frame.index && index < frame.end);
+}
+export {
+  frameAt,
+  readDeckSource,
+  tagProps,
+  visibleWords
+};

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

@@ -0,0 +1,133 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { DeckSource } from './deck-source.js';
+import './types.js';
+
+/**
+ * The deck rules (`docs/authoring/deck.md`): the `D` area and the `decks`
+ * invariant, over each deck read as frames (`deck-source.ts`). One pass per
+ * deck; the manifest runs it and drops the codes of a rule the course turned
+ * off, as for every gate.
+ *
+ * What it cannot see is the rendered fit of a frame (rule D2's
+ * `frame-overflow`), which the build measures in a browser after Astro has
+ * built the deck.
+ */
+
+/**
+ * What a chapter numbers, by kind: each key with its number, and an
+ * equation's LaTeX (for rule D8's retyped check). What a deck may recall.
+ */
+interface ChapterFloats {
+    readonly equations: ReadonlyMap<string, {
+        readonly number: string;
+        readonly latex?: string;
+    }>;
+    readonly figures: ReadonlyMap<string, string>;
+    readonly tables: ReadonlyMap<string, string>;
+    readonly diagrams: ReadonlyMap<string, string>;
+}
+/** A part, as its deck's rules see it (`<part>/index.deck.mdx`). */
+interface PartDeckFacts {
+    /** The part's directory: `motion`. */
+    readonly dir: string;
+    /**
+     * The part's chapters in reading order: each by its name in the part's
+     * directory (what `[chapter: <name>]` writes), with its lesson slug and
+     * what it numbers.
+     */
+    readonly chapters: readonly {
+        readonly name: string;
+        readonly slug: string;
+        readonly floats: ChapterFloats;
+    }[];
+    /** The part's lessons that are only slides, by name: they have no chapter to cover. */
+    readonly slidesFirst?: readonly string[];
+}
+/** One deck, as the manifest hands it to the rules. */
+interface DeckValidationInput {
+    /** Repository-relative path of the deck file. */
+    readonly file: string;
+    /** The deck's page id (`motion.range.slides`, the lesson's own, or a part's `motion.slides`). */
+    readonly pageId: string;
+    /** True when the lesson has a chapter beside the deck. */
+    readonly hasChapter: boolean;
+    /** True when the deck sits in a part's directory, as a lesson does. */
+    readonly inPart: boolean;
+    readonly body: string;
+    /** 1-based file line the body starts on. */
+    readonly bodyLine: number;
+    /** The deck file's frontmatter. */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly source: DeckSource;
+    /** What the deck may recall from its chapter, by kind. */
+    readonly chapter?: ChapterFloats;
+    /** A part's deck: its part, whose chapters its sections may cover. */
+    readonly part?: PartDeckFacts;
+    /** Per frame of {@link source}, the notation keys it shows for the first time in the deck. */
+    readonly newSymbols?: readonly (readonly string[])[];
+}
+/** One chapter a part deck's section covers. */
+interface CoveredChapter {
+    readonly name: string;
+    readonly slug: string;
+    readonly floats: ChapterFloats;
+    /** The section's place in {@link DeckSource.frames}: its divider. */
+    readonly position: number;
+}
+/** What a part's deck recalls, and from where (`resolvePartRecalls`). */
+interface PartRecalls {
+    /** The chapters its sections cover, in deck order, each once. */
+    readonly covered: readonly CoveredChapter[];
+    /** Each frame's chapter, by its place in {@link DeckSource.frames}: its section's, when that names one of the part. */
+    readonly frameChapters: readonly (CoveredChapter | undefined)[];
+    /** The chapter each recalled float is the chapter's own, by its ref (`eq-range`). */
+    readonly chapterOf: ReadonlyMap<string, CoveredChapter>;
+    /** Why a recall names nothing, by its offset in the deck body. */
+    readonly problems: ReadonlyMap<number, string>;
+}
+/** The number a chapter gives the float `ref` names (`eq-range`, `fig-…`), if it numbers one. */
+declare function chapterNumberOf(ref: string, floats: ChapterFloats | undefined): string | undefined;
+/**
+ * The chapters a part deck's sections cover: each a `## Title [chapter:
+ * <name>]` whose name is one of `chapters`, in deck order and once (a
+ * repeat is the same chapter), with the place of its divider in
+ * `source.frames`; and each frame's chapter, its section's. The divider's
+ * frame number is that place plus 2, after the title frame.
+ */
+declare function coveredSections(source: DeckSource, chapters: ReadonlySet<string>): {
+    readonly covered: readonly {
+        readonly name: string;
+        readonly position: number;
+    }[];
+    readonly frameChapters: readonly (string | undefined)[];
+};
+/**
+ * Where each recall of a part's deck comes from. A section that names a
+ * chapter covers it; a recall is the float of the chapter its section
+ * covers when that chapter numbers it, and otherwise of the one other
+ * covered chapter that does. Two that do, with neither the section's own,
+ * or a ref one frame recalls from one chapter and another from a second,
+ * name no float of their own: a deck page holds one float per anchor.
+ */
+declare function resolvePartRecalls(source: DeckSource, part: PartDeckFacts): PartRecalls;
+interface DeckRuleSettings {
+    /** D2 */
+    readonly maxWords: number;
+    readonly maxBullets: number;
+    /** D5 */
+    readonly maxTitleLength: number;
+    /** D6 */
+    readonly maxSteps: number;
+    /** D9 */
+    readonly maxNewSymbols: number;
+}
+declare const DECK_RULE_DEFAULTS: DeckRuleSettings;
+/**
+ * A display equation's LaTeX as rule D8 compares it: no `\label` or
+ * `\caption`, each `\explain{key}{body}` as its body, no spacing commands, no
+ * `\left` / `\right`, no whitespace.
+ */
+declare function comparableLatex(latex: string): string;
+declare function validateDecks(decks: readonly DeckValidationInput[], settings?: DeckRuleSettings): MathGateDiagnostic[];
+
+export { type ChapterFloats, type CoveredChapter, DECK_RULE_DEFAULTS, type DeckRuleSettings, type DeckValidationInput, type PartDeckFacts, type PartRecalls, chapterNumberOf, comparableLatex, coveredSections, resolvePartRecalls, validateDecks };