explico 0.13.1 → 0.15.0

package/src/reference/registry.ts

@@ -3,8 +3,10 @@ import {
   compareSourceSpans,
   isNotationKey,
   localDefinitionId,
+  pageScopeLessonIds,
   RESERVED_KEY_PREFIXES,
   reservedKeyPrefix,
+  resolvePageReferenceId,
   resolveReferenceId,
   sharedDefinitionId,
 } from './references';
@@ -14,7 +16,6 @@ import type {
   LocalNotationDefinitionRecord,
   NotationBacklink,
   NotationDefinitionRecord,
-  NotationDefinitionScope,
   NotationDiagnostic,
   NotationLessonInput,
   NotationPageBundle,
@@ -124,16 +125,16 @@ export function buildNotationRegistry(
   const directReferences = new Map<string, ResolvedNotationReference[]>();
   for (const lesson of lessons.values()) {
     const resolved: ResolvedNotationReference[] = [];
-    const scope: NotationDefinitionScope = {
-      kind: 'page',
-      lessonId: lesson.lessonId,
-    };
+    // A deck resolves in its lessons' scopes: a deck beside its chapter in
+    // the chapter's, whose `notation.local` entries are the lesson's; a
+    // part's deck in its chapters', the first to define a key binding it.
+    const scopes = pageScopeLessonIds(lesson);
 
     for (const reference of sortedReferences(lesson.references)) {
       if (!validatePageReferenceKey(reference, lesson, diagnostics)) continue;
-      const definitionId = resolveReferenceId(
+      const definitionId = resolvePageReferenceId(
         reference.key,
-        scope,
+        scopes,
         availableDefinitionIds,
       );
       if (definitionId === undefined) {
@@ -203,19 +204,45 @@ export function buildNotationRegistry(
   const reachableDefinitions = new Set<string>();
 
   for (const lesson of lessons.values()) {
-    const references = directReferences.get(lesson.lessonId) ?? [];
+    // A deck shows its lessons' symbols: its bundle holds what its chapters
+    // name as well as what it names itself. A key is bound as the deck
+    // binds it, then as the first of its chapters does.
+    const scopes = pageScopeLessonIds(lesson);
+    const references = [
+      ...(directReferences.get(lesson.lessonId) ?? []),
+      // A chapter's reference, bound as this page binds its key: on a part's
+      // deck, a key two of its chapters define is the first one's.
+      ...scopes
+        .filter((lessonId) => lessonId !== lesson.lessonId)
+        .flatMap((lessonId) => directReferences.get(lessonId) ?? [])
+        .flatMap((reference) => {
+          const definitionId = resolvePageReferenceId(reference.key, scopes, availableDefinitionIds);
+          return definitionId === undefined ? [] : [{ ...reference, definitionId }];
+        }),
+    ];
     const directIds = new Set(
       references.map((reference) => reference.definitionId),
     );
+    // Every local entry in scope seeds the bundle, the first of a key only.
+    const scopedLocalIds: string[] = [];
+    const scopedLocalKeys = new Set<string>();
+    for (const lessonId of scopes) {
+      for (const id of localIdsByLesson.get(lessonId) ?? []) {
+        const key = definitions.get(id)?.input.key;
+        if (key === undefined || scopedLocalKeys.has(key)) continue;
+        scopedLocalKeys.add(key);
+        scopedLocalIds.push(id);
+      }
+    }
     const definitionIds = transitiveClosure(
-      new Set([...directIds, ...(localIdsByLesson.get(lesson.lessonId) ?? [])]),
+      new Set([...directIds, ...scopedLocalIds]),
       edgeIndex,
     );
     for (const id of definitionIds) reachableDefinitions.add(id);
 
     const bindingByKey = new Map<string, string>();
     for (const reference of references) {
-      bindingByKey.set(reference.key, reference.definitionId);
+      if (!bindingByKey.has(reference.key)) bindingByKey.set(reference.key, reference.definitionId);
     }
 
     bundles.push({
@@ -231,7 +258,10 @@ export function buildNotationRegistry(
       definitionIds,
     });
 
-    for (const definitionId of definitionIds) {
+    // A deck shows its chapters' symbols again: the glossary names each
+    // chapter once, not its slides, or its part's, as a page of its own.
+    const isDeck = lesson.scopeLessonIds !== undefined;
+    for (const definitionId of isDeck ? [] : definitionIds) {
       const definition = definitions.get(definitionId);
       if (definition === undefined) continue;
       backlinks.push({

package/src/reference/rehype-deck.mjs

@@ -0,0 +1,286 @@
+/**
+ * The rehype half of a deck page (`<lesson>.deck.mdx`, docs/authoring/deck.md):
+ * the page's flow becomes its frames. `rehype-heading-anchors.mjs` hands a
+ * deck page here (`remark-notation.mjs` marks one with `file.data.explicoDeck`),
+ * so a course wires nothing new.
+ *
+ * Each `##` (a section's divider) and `###` (a frame) heading, stamped with
+ * its frame number by the remark half (`deck-remark.mjs`), opens a
+ *
+ *   <section class="deck-frame" id="slide-N" data-frame="N" data-kind="frame"
+ *            data-frame-id="3f9a0c1e77b2"         what it shows (`ManifestDeckFrame.id`)
+ *            role="group" aria-roledescription="slide" aria-label="N of T">
+ *     <div class="deck-stage">             the frame's box on the page
+ *     <div class="deck-canvas">            the fixed canvas the course's ratio sets, scaled to it
+ *       <h3 class="deck-frame__title">…</h3>
+ *       <div class="deck-frame__body">…</div>   its steps: `.deck-step[data-step]`
+ *       <div class="deck-legend">…</div>        the symbols it introduces
+ *       <div class="deck-frame__foot">…</div>   section and frame number
+ *     </div>
+ *     <aside class="deck-notes">…</aside>       the speaker's notes, outside the canvas
+ *   </section>
+ *
+ * `<Pause />` splits a frame's body into steps; its props (`control`, `from`,
+ * `to`, `seconds`; `highlight`) ride on the step for the page's controller
+ * (`components/deck/deck-controller.ts`). Two lists a step boundary splits
+ * become one list whose later items are the step.
+ */
+import { stripMarkers } from './rehype-heading-anchors.mjs';
+
+const HEADING = /^h[1-6]$/;
+
+/** A hast property by its attribute name, in either the attribute or the property spelling. */
+function prop(node, name) {
+  const properties = node?.properties ?? {};
+  if (properties[name] !== undefined) return properties[name];
+  const camel = name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+  return properties[camel];
+}
+
+function classes(node) {
+  const value = prop(node, 'className') ?? prop(node, 'class');
+  if (Array.isArray(value)) return value.map(String);
+  return typeof value === 'string' ? value.split(/\s+/) : [];
+}
+
+function element(tagName, properties, children = []) {
+  return { type: 'element', tagName, properties, children };
+}
+
+function isWhitespace(node) {
+  return node?.type === 'text' && !String(node.value ?? '').trim();
+}
+
+function isJsx(node, name) {
+  return (node?.type === 'mdxJsxFlowElement' || node?.type === 'mdxJsxTextElement') && node.name === name;
+}
+
+function jsxAttributes(node) {
+  const values = {};
+  for (const attribute of node?.attributes ?? []) {
+    if (attribute?.type === 'mdxJsxAttribute' && typeof attribute.value === 'string') {
+      values[attribute.name] = attribute.value;
+    }
+  }
+  return values;
+}
+
+function textOf(node) {
+  if (!node) return '';
+  if (node.type === 'text') return String(node.value ?? '');
+  if (classes(node).includes('katex-mathml') || node.tagName === 'annotation') return '';
+  return (node.children ?? []).map(textOf).join('');
+}
+
+/** A heading the remark half stamped, and what kind of frame it opens. */
+function frameKindOf(node) {
+  if (node?.type !== 'element' || !HEADING.test(node.tagName)) return undefined;
+  const kind = prop(node, 'data-deck-kind');
+  if (kind === 'section' || kind === 'frame') return kind;
+  if (node.tagName === 'h2' && prop(node, 'id') === 'references') return 'references';
+  return undefined;
+}
+
+function isGeneratedFrame(node) {
+  return node?.type === 'element' && node.tagName === 'section' && classes(node).includes('deck-frame');
+}
+
+/** A step's data attributes, from its `<Pause>` props. */
+function stepProperties(step, pause) {
+  const properties = { 'data-step': String(step) };
+  for (const name of ['control', 'from', 'to', 'seconds', 'highlight']) {
+    if (pause[name] !== undefined) properties[`data-step-${name}`] = pause[name];
+  }
+  return properties;
+}
+
+/** A frame's content in steps: what follows the k-th `<Pause />` is step k + 1. */
+function stepped(content) {
+  const groups = [{ step: 1, pause: {}, nodes: [] }];
+  for (const node of content) {
+    if (isJsx(node, 'Pause')) {
+      groups.push({ step: groups.length + 1, pause: jsxAttributes(node), nodes: [] });
+      continue;
+    }
+    groups.at(-1).nodes.push(node);
+  }
+  const out = [...groups[0].nodes];
+  const lastElement = () => [...out].reverse().find((node) => node.type === 'element');
+  for (const group of groups.slice(1)) {
+    const properties = stepProperties(group.step, group.pause);
+    const nodes = group.nodes.filter((node) => !isWhitespace(node));
+    const [first, ...rest] = nodes;
+    const previous = lastElement();
+    // Two lists the step mark splits are one list: its later items are the step.
+    if (
+      first?.type === 'element' &&
+      (first.tagName === 'ul' || first.tagName === 'ol') &&
+      previous?.tagName === first.tagName
+    ) {
+      let marked = false;
+      for (const item of first.children ?? []) {
+        if (item.type !== 'element') continue;
+        item.properties = {
+          ...item.properties,
+          className: [...classes(item), 'deck-step'],
+          ...(marked ? { 'data-step': String(group.step) } : properties),
+        };
+        marked = true;
+      }
+      previous.children.push(...(first.children ?? []));
+      if (rest.length > 0) out.push(element('div', { className: ['deck-step'], 'data-step': String(group.step) }, rest));
+      continue;
+    }
+    // A step with nothing to show still drives its figure or lights its symbol.
+    out.push(element('div', { className: ['deck-step'], ...properties }, nodes));
+  }
+  return out;
+}
+
+function frameShell({ number, kind, id, frameId, chapter, extra = {}, canvas, notes = [] }) {
+  return element(
+    'section',
+    {
+      className: ['deck-frame', `deck-frame--${kind}`],
+      id: `slide-${number}`,
+      'data-frame': String(number),
+      ...(frameId ? { 'data-frame-id': frameId } : {}),
+      ...(chapter ? { 'data-chapter': chapter } : {}),
+      'data-kind': kind,
+      role: 'group',
+      'aria-roledescription': 'slide',
+      ...(id ? { 'data-frame-anchor': id } : {}),
+      ...extra,
+    },
+    // The stage takes the frame's size on the page; the canvas inside it is
+    // laid out at the course's canvas size and scaled to the stage, so a frame
+    // looks the same at every width (`docs/diagram-scaling.md`).
+    [element('div', { className: ['deck-stage'] }, [element('div', { className: ['deck-canvas'] }, canvas)]), ...notes],
+  );
+}
+
+function foot(number, sectionTitle) {
+  return element('div', { className: ['deck-frame__foot'], 'aria-hidden': 'true' }, [
+    ...(sectionTitle ? [element('span', { className: ['deck-frame__section'] }, [{ type: 'text', value: sectionTitle }])] : []),
+    element('span', { className: ['deck-frame__number'] }, [{ type: 'text', value: String(number) }]),
+  ]);
+}
+
+/**
+ * Turn a deck page's flow into its frames, in place. `deck` is
+ * `file.data.explicoDeck`: the ratio, the canvas, who sees the notes, each
+ * frame's id and, on a part's deck, each frame's chapter.
+ */
+export function frameDeck(tree, deck) {
+  const esm = [];
+  const frames = [];
+  let current;
+  let sectionTitle;
+  let lastNumber = 0;
+  const frameIdOf = (number) => deck.frameIds?.[number - 1];
+  const chapterOf = (number) => deck.frameChapters?.[number - 1] ?? undefined;
+
+  const close = () => {
+    if (!current) return;
+    const { heading, kind, body } = current;
+    current = undefined;
+    const markers = stripMarkers(heading);
+    const stamped = Number(prop(heading, 'data-deck-frame'));
+    const number = Number.isFinite(stamped) && stamped > 0 ? stamped : lastNumber + 1;
+    lastNumber = number;
+    const id = prop(heading, 'id');
+    heading.properties = {
+      ...heading.properties,
+      className: [...classes(heading), 'deck-frame__title'],
+    };
+    for (const name of ['data-deck-frame', 'data-deck-kind', 'data-deck-steps', 'data-deck-morph']) {
+      delete heading.properties[name];
+      delete heading.properties[name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())];
+    }
+    if (kind === 'section') {
+      sectionTitle = textOf(heading).trim();
+      frames.push(frameShell({ number, kind, id, frameId: frameIdOf(number), chapter: chapterOf(number), canvas: [heading, foot(number)] }));
+      return;
+    }
+    const notes = [];
+    const legend = [];
+    const content = [];
+    for (const node of body) {
+      if (isJsx(node, 'Notes')) {
+        // A landmark each, so each needs a name of its own (axe: landmark-unique).
+        notes.push(element('aside', { className: ['deck-notes'], 'aria-label': `Speaker notes for slide ${number}` }, node.children ?? []));
+      } else if (node?.type === 'element' && classes(node).includes('deck-legend')) {
+        legend.push(node);
+      } else {
+        content.push(node);
+      }
+    }
+    const steps = content.filter((node) => isJsx(node, 'Pause')).length + 1;
+    frames.push(
+      frameShell({
+        number,
+        kind,
+        id,
+        frameId: frameIdOf(number),
+        chapter: chapterOf(number),
+        extra: {
+          'data-steps': String(steps),
+          ...(markers.morph || prop(heading, 'data-deck-morph') !== undefined ? { 'data-morph': '' } : {}),
+        },
+        canvas: [
+          heading,
+          element('div', { className: ['deck-frame__body'] }, kind === 'frame' ? stepped(content) : content),
+          ...legend,
+          foot(number, kind === 'frame' ? sectionTitle : undefined),
+        ],
+        notes: deck.notes === 'off' ? [] : notes,
+      }),
+    );
+  };
+
+  for (const node of tree.children ?? []) {
+    if (node?.type === 'mdxjsEsm') {
+      esm.push(node);
+      continue;
+    }
+    if (isGeneratedFrame(node)) {
+      close();
+      const number = Number(prop(node, 'data-deck-frame')) || lastNumber + 1;
+      lastNumber = number;
+      const kind = prop(node, 'data-deck-kind') ?? 'frame';
+      frames.push(frameShell({ number, kind, frameId: frameIdOf(number), chapter: chapterOf(number), canvas: [...(node.children ?? []), foot(number)] }));
+      continue;
+    }
+    const kind = frameKindOf(node);
+    if (kind) {
+      close();
+      current = { heading: node, kind, body: [] };
+      continue;
+    }
+    if (current) current.body.push(node);
+    else if (!isWhitespace(node)) frames.push(node);
+  }
+  close();
+
+  const total = frames.filter((node) => isGeneratedFrame(node)).length;
+  for (const frame of frames) {
+    if (!isGeneratedFrame(frame)) continue;
+    frame.properties['aria-label'] = `${frame.properties['data-frame']} of ${total}`;
+  }
+  const canvas = deck.canvas ?? { width: 1280, height: 720 };
+  tree.children = [
+    ...esm,
+    element(
+      'div',
+      {
+        className: ['deck'],
+        'data-deck': deck.slug ?? '',
+        'data-aspect': deck.aspectRatio ?? '16:9',
+        'data-notes': deck.notes ?? 'reader',
+        'data-frames': String(total),
+        style: `--deck-canvas-width: ${canvas.width}px; --deck-canvas-height: ${canvas.height}px;`,
+      },
+      frames,
+    ),
+  ];
+}

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

@@ -60,6 +60,7 @@
  * Astro's slug, renamed only if it would repeat an id given upstream.
  */
 
+import { frameDeck } from './rehype-deck.mjs';
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
 
 const HEADING_TAG = /^h([1-6])$/;
@@ -103,7 +104,12 @@ function headingText(node) {
 // (e.g. `{#id .class}`) — this codebase has no remark-attr-style plugin, and
 // a handful of purpose-built tokens are enough for what an author needs to
 // say about a heading here.
-const HEADING_MARKER = /\s*\[(collapsible|collapsed|no-collapsible|card|card=meta)\]\s*$/i;
+// `[morph]` and `[chapter: <slug>]` are a deck's: on a frame title `[morph]`
+// asks for the frame to morph from the one before it, and on a part's deck a
+// section's `[chapter: <slug>]` names the chapter it covers
+// (`docs/authoring/deck.md`); a chapter ignores both.
+const HEADING_MARKER = /\s*\[(collapsible|collapsed|no-collapsible|card|card=meta|morph|chapter:[^\]]*)\]\s*$/i;
+const CHAPTER_MARKER = /^chapter:\s*(.*?)\s*$/i;
 
 const CARD_TIER = { card: 'accent', 'card=meta': 'meta' };
 
@@ -138,13 +144,39 @@ export function headingCardTier(text) {
   return tier;
 }
 
+/** True when a heading's source text carries the deck's `[morph]` marker. */
+export function headingMorphs(text) {
+  let rest = String(text);
+  for (let match = HEADING_MARKER.exec(rest); match; match = HEADING_MARKER.exec(rest)) {
+    if (match[1].toLowerCase() === 'morph') return true;
+    rest = rest.slice(0, match.index);
+  }
+  return false;
+}
+
+/**
+ * The chapter a part deck's section names, `## Title [chapter: <slug>]`, as
+ * written, or `null` without the marker. With two, the one written last wins.
+ */
+export function headingChapter(text) {
+  let rest = String(text);
+  for (let match = HEADING_MARKER.exec(rest); match; match = HEADING_MARKER.exec(rest)) {
+    const chapter = CHAPTER_MARKER.exec(match[1]);
+    if (chapter) return chapter[1];
+    rest = rest.slice(0, match.index);
+  }
+  return null;
+}
+
 /**
  * Strip every trailing marker off a hast heading and report them as
- * `{ collapse, card }` — the collapse marker and the card tier, each `null`
- * when absent. With two of one kind, the one written last wins.
+ * `{ collapse, card, morph, chapter }` — the collapse marker and the card
+ * tier, each `null` when absent, whether a deck frame morphs, and the chapter
+ * a deck's section names (`null` without one). With two of one kind, the one
+ * written last wins.
  */
-function stripMarkers(headingNode) {
-  const found = { collapse: null, card: null };
+export function stripMarkers(headingNode) {
+  const found = { collapse: null, card: null, morph: false, chapter: null };
   const children = headingNode.children;
   for (let index = children.length - 1; index >= 0; index--) {
     const node = children[index];
@@ -152,7 +184,10 @@ function stripMarkers(headingNode) {
     const match = HEADING_MARKER.exec(node.value);
     if (match) {
       const marker = match[1].toLowerCase();
+      const chapter = CHAPTER_MARKER.exec(match[1]);
       if (marker in CARD_TIER) found.card ??= CARD_TIER[marker];
+      else if (marker === 'morph') found.morph = true;
+      else if (chapter) found.chapter ??= chapter[1];
       else found.collapse ??= marker;
       node.value = node.value.slice(0, match.index);
       if (!node.value) children.splice(index, 1);
@@ -163,7 +198,7 @@ function stripMarkers(headingNode) {
     // trailing whitespace-only text node: keep looking further back
   }
   const last = children.at(-1);
-  if ((found.collapse || found.card) && last?.type === 'text') {
+  if ((found.collapse || found.card || found.morph || found.chapter !== null) && last?.type === 'text') {
     last.value = last.value.trimEnd();
   }
   return found;
@@ -244,6 +279,13 @@ export default function rehypeHeadingAnchors(options = {}) {
   const assignHeadingIds = rehypeHeadingIds();
 
   return function transform(tree, file) {
+    // A deck's page is its frames (`rehype-deck.mjs`): its headings are frame
+    // titles, anchored by the manifest, never collapsible sections.
+    if (file?.data?.explicoDeck) {
+      frameDeck(tree, file.data.explicoDeck);
+      assignHeadingIds(tree, file);
+      return;
+    }
     // Markers 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