explico 0.7.0 → 0.11.0

package/src/reference/keyed-jsx-floats.mjs

@@ -11,8 +11,9 @@
  * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`/`dia-`.
  *
  * Only top-level occurrences count, exactly like `collectDisplayEquations`,
- * except that `<Memo>` is transparent: a float in a memo remains a side-note
- * in the lesson's reading order. A keyed float nested inside a
+ * except that the `TRANSPARENT_COMPONENTS` (`<Memo>`, `<ShortNote>`,
+ * `<Fold>`) are see-through: a float in a memo or a fold stays in the
+ * lesson's reading order. A keyed float nested inside a
  * `<CompactExample>` (or any other component) is illustrative, not part of the
  * official sequence.
  *
@@ -26,6 +27,7 @@ import {
   resolveNumbering,
   stripFencedCode,
   stripJsxComponents,
+  TRANSPARENT_COMPONENTS,
 } from './equations.mjs';
 
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
@@ -37,10 +39,11 @@ function floatNumber(section, index) {
 }
 
 /**
- * The visible number for one float. With a `prefix` (the part's ordinal) the
- * scheme is `‹part›.‹offset + indexInLesson›` and `##` headings are ignored;
- * without it, the legacy `##`-section scheme. Mirrors `displayEquationNumber`
- * in `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
+ * The visible number for one float. With a `prefix` (`‹part›.‹chapter›`, or
+ * the part alone under `numbering.floats: "part"`) the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme. Mirrors `displayEquationNumber` in
+ * `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
  * advances the `<Figure>` or `<Diagram>` sequence — so `offset` is per kind too.
  */
 function keyedFloatNumber({
@@ -79,22 +82,60 @@ function readIdAttribute(attributesSource) {
   return match ? match[2] : undefined;
 }
 
+/**
+ * A literal string attribute (`name="…"` / `name='…'`) of a JSX opening tag's
+ * attribute source, trimmed; `null` when absent, empty, or an expression.
+ */
+function readStringAttribute(attributesSource, name) {
+  const match = new RegExp(
+    String.raw`(?:^|\s)${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`,
+  ).exec(attributesSource);
+  const value = (match?.[1] ?? match?.[2])?.trim();
+  return value ? value : null;
+}
+
+/** Every prop name a JSX opening tag's attribute source sets (`name=`). */
+function attributeNames(attributesSource) {
+  const bare = attributesSource.replace(
+    /"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}/g,
+    ' ',
+  );
+  return [...bare.matchAll(/(?:^|\s)([A-Za-z_][\w:.-]*)\s*=/g)].map(
+    (match) => match[1],
+  );
+}
+
+/** A literal string value of an mdast JSX attribute, trimmed, else `null`. */
+function mdxStringAttribute(node, name) {
+  const attribute = (node.attributes ?? []).find(
+    (candidate) =>
+      candidate?.type === 'mdxJsxAttribute' && candidate.name === name,
+  );
+  const value =
+    typeof attribute?.value === 'string' ? attribute.value.trim() : '';
+  return value ? value : null;
+}
+
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
- * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
- * this kind of float in earlier lessons of that part) the number is
- * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * `scanEquationLabels`: every top-level `<TagName …>` in appearance order,
+ * with its literal `short` / `caption` (the caption pair every float takes;
+ * `null` when absent or an expression) and `props`, the names of every prop
+ * the tag sets, for `keyed-float-validate.ts`'s removed-prop check.
+ * With `numbering` (`{ prefix, offset }` — the lesson's float-number prefix
+ * and the count of this kind of float before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
  * headings advance a section counter. Other JSX components' bodies are blanked
  * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
  * text inside an unrelated component) is never counted.
  */
 export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), tagName, [
-    'Memo',
-    'ShortNote',
-  ]);
+  const text = stripJsxComponents(
+    stripFencedCode(markdown),
+    tagName,
+    TRANSPARENT_COMPONENTS,
+  );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
@@ -102,8 +143,16 @@ export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
     tokens.push({ kind: 'section', index: match.index });
   }
   for (const match of text.matchAll(opening)) {
-    const key = readIdAttribute(match[1] ?? '');
-    tokens.push({ kind: 'float', index: match.index, key: key ?? null });
+    const attributes = match[1] ?? '';
+    const key = readIdAttribute(attributes);
+    tokens.push({
+      kind: 'float',
+      index: match.index,
+      key: key ?? null,
+      short: readStringAttribute(attributes, 'short'),
+      caption: readStringAttribute(attributes, 'caption'),
+      props: attributeNames(attributes),
+    });
   }
   tokens.sort((a, b) => a.index - b.index);
 
@@ -128,6 +177,9 @@ export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
         indexInSection,
         indexInLesson,
       }),
+      short: token.short,
+      caption: token.caption,
+      props: token.props,
       section,
       indexInSection,
     });
@@ -145,7 +197,7 @@ export function countKeyedJsxFloats(markdown, { tagName }) {
 
 /**
  * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through `<Memo>` bodies) in document order, advancing the
+ * children (and through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
  * section counter on every top-level depth-2 heading and emitting a record for
  * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
  * `collectDisplayEquations`. `numbering` is threaded the same way as in
@@ -171,6 +223,8 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
         typeof idAttribute?.value === 'string' ? idAttribute.value : undefined;
       floats.push({
         key: key ?? null,
+        short: mdxStringAttribute(node, 'short'),
+        caption: mdxStringAttribute(node, 'caption'),
         number: keyedFloatNumber({
           prefix,
           offset,
@@ -186,8 +240,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
     }
     if (
       node.type === 'mdxJsxFlowElement' &&
-      node.name !== 'Memo' &&
-      node.name !== 'ShortNote'
+      !TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       return;
     }
@@ -207,7 +260,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
       collectFromDetail(node);
     } else if (
       node.type === 'mdxJsxFlowElement' &&
-      (node.name === 'Memo' || node.name === 'ShortNote')
+      TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       collectFromDetail(node);
     }

package/src/reference/knowledge-checks-validate.ts

@@ -12,7 +12,7 @@ export interface KnowledgeCheckLessonInput {
   readonly file: string;
   readonly body: string;
   readonly assessmentIds: readonly string[];
-  readonly numbering?: { readonly prefix: number; readonly offset: number };
+  readonly numbering?: { readonly prefix: number | string; readonly offset: number };
 }
 
 export interface KnowledgeCheckLabelRecord {

package/src/reference/knowledge-checks.mjs

@@ -28,12 +28,17 @@ export function knowledgeCheckAnchorId(key) {
 
 /**
  * Number an ordered assessment-id list. With manifest placement, the number
- * is `part.offset + index`; without it, the list remains usefully page-local.
+ * is `‹prefix›.‹offset + index›` — `prefix` is `‹part›.‹chapter›`, or the part
+ * alone under `numbering.floats: "part"`; without it, the list remains
+ * usefully page-local.
  */
 export function collectKnowledgeChecks(assessmentIds, numbering) {
-  const prefix = Number.isInteger(numbering?.prefix) && numbering.prefix > 0
-    ? numbering.prefix
-    : undefined;
+  const rawPrefix = numbering?.prefix;
+  const prefix =
+    (Number.isInteger(rawPrefix) && rawPrefix > 0) ||
+    (typeof rawPrefix === 'string' && /^\d+(?:\.\d+)*$/.test(rawPrefix))
+      ? rawPrefix
+      : undefined;
   const offset = Number.isInteger(numbering?.offset) && numbering.offset >= 0
     ? numbering.offset
     : 0;

package/src/reference/lab-math-slot.ts

@@ -0,0 +1,36 @@
+/**
+ * The half of lab math an interactive island needs in the browser: the shape
+ * of a compiled template and its slot placeholder. It imports nothing, so an
+ * island that uses it stays clear of the KaTeX build chain behind
+ * `render-lab-math.ts`, which is server-only (`katex-delimiters.mjs` reads
+ * KaTeX's bundle from disk).
+ */
+
+export interface RenderedLabMath {
+  /** KaTeX HTML+MathML with `data-notation-key` and `data-lab-slot` spans. */
+  readonly html: string;
+  /** Slot names, in template order, the island must supply at runtime. */
+  readonly slots: readonly string[];
+  /** Notation keys the template resolved to, for diagnostics. */
+  readonly keys: readonly string[];
+  /**
+   * Plain, copyable LaTeX — every explained glyph resolved to its bare
+   * symbol, every `\slot{name}{…}` replaced by `slotPlaceholder(name)` — so
+   * the island can substitute each slot's *current* live value in and keep
+   * `[data-notation-formula]`'s `data-latex` accurate as the reader drags a
+   * control, the same "click the equation to copy it" gesture a static
+   * lesson or glossary equation gets (`NotationLayer.astro`).
+   */
+  readonly plainLatexTemplate: string;
+}
+
+/**
+ * A slot's placeholder inside `plainLatexTemplate` — distinct from the
+ * numeric sentinel `render-lab-math.ts` uses internally (that one only has to
+ * survive a single notation-binding pass at build time; this one is the
+ * stable, name-keyed token an island substitutes with a live value at
+ * runtime, so it's exported for that purpose).
+ */
+export function slotPlaceholder(name: string): string {
+  return `⟦${name}⟧`;
+}