explico 0.13.1 → 0.15.0

package/src/reference/deck-source.ts

@@ -0,0 +1,273 @@
+/**
+ * A deck's source read as frames (`docs/authoring/deck.md`, rule D1): `##`
+ * opens a section, which is a divider frame of its own; `###` is a frame,
+ * whose title is the heading; a frame's body runs from its heading to the next
+ * `##` or `###`. Pure — the manifest, the deck rules (`decks-validate.ts`),
+ * the `content` CLI and the tests read a deck through this one reader, so a
+ * frame is the same frame for all of them.
+ *
+ * A heading inside a component or a code block is not an outline heading
+ * (`scanOutlineBlocks`), so a `###` inside `<Notes>` never starts a frame.
+ */
+import { stripFencedCode } from './equations.mjs';
+import { headingChapter, headingMorphs } from './rehype-heading-anchors.mjs';
+import { scanOutlineBlocks, scanSectionHeadings } from './sections.mjs';
+
+/** A step mark, `<Pause />`, with the props of a driven figure or a spotlight. */
+export 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[];
+}
+
+export interface DeckRecall {
+  readonly index: number;
+  /** As written: `eq-range`, `fig-projectile-trajectory`, `tab-…`, `dia-…`. */
+  readonly ref?: string;
+}
+
+export interface DeckFloatTag {
+  readonly index: number;
+  readonly name: 'Figure' | 'Table' | 'Diagram' | 'CompactExamples' | 'AssessmentSet';
+  readonly id?: string;
+}
+
+export interface DeckMath {
+  readonly index: number;
+  readonly latex: string;
+}
+
+export 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;
+}
+
+export 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;
+  }[];
+}
+
+const FLOAT_NAMES = ['Figure', 'Table', 'Diagram', 'CompactExamples', 'AssessmentSet'] as const;
+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 = new Set(['control', 'from', 'to', 'seconds', 'highlight']);
+
+/** A component tag's string props, by name. */
+export function tagProps(source: string): Map<string, string> {
+  const props = new Map<string, string>();
+  for (const match of source.matchAll(PROP)) {
+    props.set(match[1] ?? '', match[2] ?? match[3] ?? '');
+  }
+  return props;
+}
+
+/** `text` with every match of `pattern` blanked to spaces, newlines kept. */
+function blankMatches(text: string, pattern: RegExp): string {
+  return text.replace(pattern, (match) => match.replace(/[^\n]/g, ' '));
+}
+
+/** The words a frame shows: its prose, without math, tags, comments, citations or notes. */
+export function visibleWords(text: string): number {
+  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;
+}
+
+/** List items in a frame's own text (not its notes). */
+function bulletCount(text: string): number {
+  return (text.replace(NOTES_BLOCK, ' ').match(/^[ \t]*(?:[-*+]|\d+[.)])[ \t]+\S/gm) ?? []).length;
+}
+
+/**
+ * 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.
+ */
+export function readDeckSource(
+  body: string,
+  options: { readonly labelFor?: (key: string) => string | undefined } = {},
+): DeckSource {
+  const source = String(body);
+  const blocks = scanOutlineBlocks(source) as Array<
+    | { kind: 'heading'; level: number; text: string; index: number }
+    | { kind: 'element'; name: string; index: number }
+    | { kind: 'content'; index: number }
+  >;
+  const headings = scanSectionHeadings(source, { labelFor: options.labelFor }) as Array<{
+    level: number;
+    text: string;
+    slug: string;
+  }>;
+  // Code is not frame text: tags and math are looked for with it blanked.
+  const scanText = stripFencedCode(source);
+
+  const deepHeadings: { index: number; level: number; text: string }[] = [];
+  const loose: { index: number; where: 'before' | 'section' }[] = [];
+  const starts: { index: number; level: 2 | 3; heading: (typeof headings)[number]; lineEnd: number }[] = [];
+  let headingCursor = -1;
+  let current: 2 | 3 | undefined;
+  for (const block of blocks) {
+    if (block.kind === 'heading') {
+      headingCursor += 1;
+      const heading = headings[headingCursor];
+      if (heading === undefined) 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 === undefined) loose.push({ index: block.index, where: 'before' });
+    else if (current === 2) loose.push({ index: block.index, where: 'section' });
+  }
+
+  const frames: DeckFrameSource[] = [];
+  const misplacedMarkers: { index: number; marker: 'chapter' | 'morph'; title: string }[] = [];
+  let section: string | undefined;
+  let sectionChapter: string | undefined;
+  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: number | undefined) => 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) ?? undefined;
+    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 !== undefined) {
+      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 === undefined ? {} : { chapter: sectionChapter }),
+      index: start.index,
+      end,
+      ...(start.level === 3 && section !== undefined ? { section } : {}),
+      body: frameBody,
+      bodyIndex,
+      pauses: [...withoutNotes.matchAll(PAUSE_TAG)].map((match) => {
+        const props = tagProps(match[1] ?? '');
+        const value = (name: string) => props.get(name);
+        return {
+          index: at(match.index),
+          ...(value('control') === undefined ? {} : { control: value('control') }),
+          ...(value('from') === undefined ? {} : { from: value('from') }),
+          ...(value('to') === undefined ? {} : { to: value('to') }),
+          ...(value('seconds') === undefined ? {} : { seconds: value('seconds') }),
+          ...(value('highlight') === undefined ? {} : { 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 === undefined ? {} : { ref }) };
+      }),
+      floats: [...withoutNotes.matchAll(FLOAT_TAG)].map((match) => {
+        const id = tagProps(match[2] ?? '').get('id');
+        return {
+          index: at(match.index),
+          name: match[1] as DeckFloatTag['name'],
+          ...(id === undefined ? {} : { 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 };
+}
+
+/** The frame an offset of the deck body falls in, if any. */
+export function frameAt(source: DeckSource, index: number): DeckFrameSource | undefined {
+  return source.frames.find((frame) => index >= frame.index && index < frame.end);
+}