explico 0.7.0 → 0.11.0

package/src/reference/raw-floats-validate.ts

@@ -90,7 +90,7 @@ export function validateRawFloats(
         `${lesson.lessonId} has ${count} <Diagram> ${plural(count, 'component')} ` +
         `nested inside another component; ${count === 1 ? 'it is' : 'they are'} ` +
         `invisible to diagram numbering. Move it to the top level (or inside ` +
-        `<Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`,
+        `<Memo>/<ShortNote>/<Fold>), or wrap it in <Figure> to give it identity.`,
     );
   }
 

package/src/reference/raw-floats.mjs

@@ -7,7 +7,7 @@
  * - an Explico `<Diagram>` with no `id` (can't be referenced with
  *   `[[dia-…]]` even though it participates in diagram numbering);
  * - an Explico `<Diagram>` nested inside some other, non-transparent
- *   component (anything but `<Memo>`/`<ShortNote>`, or `<Table>`/`<Figure>`
+ *   component (anything but `<Memo>`/`<ShortNote>`/`<Fold>`, or `<Table>`/`<Figure>`
  *   which legitimately gives it identity) — invisible to
  *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
  *   reaches diagram numbering.

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

@@ -43,6 +43,21 @@
  * `data-default-open="true"|"false"` on the wrapper — `CollapsibleSections.astro`
  * only wraps headings carrying `data-collapsible` and never needs to know
  * about the config or the marker syntax itself.
+ *
+ * A second kind of marker cards the whole section — heading and body — in a
+ * tier from `surfaces.css` (docs/plans/titles-and-containers.md Part 2):
+ * `[card]` is the accent tier, `[card=meta]` the meta tier. It becomes
+ * `data-card="accent"|"meta"` on the wrapper, which `CollapsibleSections.astro`
+ * reads the same way. A heading may carry one marker of each kind, in either
+ * order (`### Explore the range [collapsed] [card]`).
+ *
+ * A lesson's top-level headings arrive here already carrying their `id` and,
+ * when the course shows section numbers, `data-sec-number="1.1.2"` — both put
+ * on the mdast node by `remark-notation.mjs` from the manifest (`sections.mjs`
+ * decides them), so a `[[sec-…]]` reference and the heading it points at read
+ * one table. `global.css` renders the number; this plugin leaves both alone.
+ * A heading that arrives without an id (one inside a component) still gets
+ * Astro's slug, renamed only if it would repeat an id given upstream.
  */
 
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
@@ -76,25 +91,72 @@ function headingText(node) {
 // `[collapsed]` with no link/reference definition of that name is just
 // literal text in both dialects. Deliberately not a general attribute syntax
 // (e.g. `{#id .class}`) — this codebase has no remark-attr-style plugin, and
-// three purpose-built tokens are enough for what an author needs to say
-// about a heading here.
-const COLLAPSIBLE_MARKER = /\s*\[(collapsible|collapsed|no-collapsible)\]\s*$/i;
+// 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;
+
+const CARD_TIER = { card: 'accent', 'card=meta': 'meta' };
 
-function stripCollapsibleMarker(headingNode) {
+/**
+ * A heading's source text without its trailing markers: what the reader sees,
+ * and what the manifest slugs the heading's anchor from (`sections.mjs`) — so
+ * `### Explore the range [card]` is anchored `#explore-the-range`.
+ */
+export function stripHeadingMarker(text) {
+  let rest = String(text);
+  for (let match = HEADING_MARKER.exec(rest); match; match = HEADING_MARKER.exec(rest)) {
+    rest = rest.slice(0, match.index);
+  }
+  return rest;
+}
+
+/**
+ * The card tier a heading's trailing markers ask for, read from its source
+ * text: `'accent'` for `[card]`, `'meta'` for `[card=meta]`, `null` for
+ * neither. The outline reads it (`sections.mjs`): a meta section is
+ * logistics, so it is not numbered. With both, the one written last wins, as
+ * in `stripMarkers`.
+ */
+export function headingCardTier(text) {
+  let rest = String(text);
+  let tier = null;
+  for (let match = HEADING_MARKER.exec(rest); match; match = HEADING_MARKER.exec(rest)) {
+    const marker = match[1].toLowerCase();
+    if (marker in CARD_TIER) tier ??= CARD_TIER[marker];
+    rest = rest.slice(0, match.index);
+  }
+  return tier;
+}
+
+/**
+ * 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.
+ */
+function stripMarkers(headingNode) {
+  const found = { collapse: null, card: null };
   const children = headingNode.children;
   for (let index = children.length - 1; index >= 0; index--) {
     const node = children[index];
-    if (node.type !== 'text') return null; // trailing non-text node: no marker
-    const match = COLLAPSIBLE_MARKER.exec(node.value);
+    if (node.type !== 'text') break; // trailing non-text node: no more markers
+    const match = HEADING_MARKER.exec(node.value);
     if (match) {
+      const marker = match[1].toLowerCase();
+      if (marker in CARD_TIER) found.card ??= CARD_TIER[marker];
+      else found.collapse ??= marker;
       node.value = node.value.slice(0, match.index);
       if (!node.value) children.splice(index, 1);
-      return match[1].toLowerCase();
+      else index += 1; // look at the same node again: markers can stack
+      continue;
     }
-    if (node.value.trim()) return null; // real trailing text, no marker present
+    if (node.value.trim()) break; // real trailing text, no marker present
     // trailing whitespace-only text node: keep looking further back
   }
-  return null;
+  const last = children.at(-1);
+  if ((found.collapse || found.card) && last?.type === 'text') {
+    last.value = last.value.trimEnd();
+  }
+  return found;
 }
 
 /**
@@ -172,14 +234,20 @@ export default function rehypeHeadingAnchors(options = {}) {
   const assignHeadingIds = rehypeHeadingIds();
 
   return function transform(tree, file) {
-    // A marker must be stripped *before* `rehypeHeadingIds` runs — otherwise
+    // 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
     // title). `collapsibleHeadings` records each heading node's *resolved*
-    // decision, since the marker text is gone by the time the main wrapping
-    // walk below runs.
+    // decision and `cardHeadings` its card tier, since the marker text is
+    // gone by the time the main wrapping walk below runs.
     const collapsibleHeadings = new WeakMap();
-    const stripMarkers = (node) => {
+    const cardHeadings = new WeakMap();
+    // Every heading in document order, and the ones whose id was given
+    // upstream (a lesson's top-level headings, from the manifest; the
+    // generated "References").
+    const headings = [];
+    const given = new Set();
+    const readMarkers = (node) => {
       if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
         return;
       }
@@ -189,19 +257,48 @@ export default function rehypeHeadingAnchors(options = {}) {
           typeof child.tagName === 'string' &&
           HEADING_TAG.test(child.tagName)
         ) {
-          const marker = stripCollapsibleMarker(child);
+          const markers = stripMarkers(child);
           collapsibleHeadings.set(
             child,
-            resolveCollapsible(marker, child.tagName, defaultCollapsible),
+            resolveCollapsible(markers.collapse, child.tagName, defaultCollapsible),
           );
+          if (markers.card) cardHeadings.set(child, markers.card);
+          headings.push(child);
+          const id = child.properties?.id;
+          if (typeof id === 'string' && id.length > 0) given.add(child);
         }
-        stripMarkers(child);
+        readMarkers(child);
       }
     };
-    stripMarkers(tree);
+    readMarkers(tree);
 
     assignHeadingIds(tree, file);
 
+    // Astro's slugger never saw the ids given upstream, so a heading inside a
+    // component that shares a top-level heading's text would get the same
+    // id. The upstream one keeps it (a `[[sec-…]]` points there); this one
+    // takes the next free `-n`, as the slugger itself would have. The second
+    // `assignHeadingIds` only rebuilds `file.data.astro.headings` from the
+    // ids as they now stand.
+    if (given.size > 0) {
+      const taken = new Set([...given].map((heading) => heading.properties.id));
+      let renamed = false;
+      for (const heading of headings) {
+        const id = heading.properties?.id;
+        if (given.has(heading) || typeof id !== 'string') continue;
+        let unique = id;
+        for (let suffix = 1; taken.has(unique); suffix += 1) {
+          unique = `${id}-${suffix}`;
+        }
+        if (unique !== id) {
+          heading.properties.id = unique;
+          renamed = true;
+        }
+        taken.add(unique);
+      }
+      if (renamed) assignHeadingIds(tree, file);
+    }
+
     const walk = (node) => {
       if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
         return;
@@ -223,6 +320,7 @@ export default function rehypeHeadingAnchors(options = {}) {
         ) {
           const id = child.properties.id;
           const decision = collapsibleHeadings.get(child) ?? { collapsible: false };
+          const card = cardHeadings.get(child);
           const label = `Section titled “${headingText(child)}”`;
           node.children[index] = {
             type: 'element',
@@ -235,6 +333,7 @@ export default function rehypeHeadingAnchors(options = {}) {
                     'data-default-open': String(decision.defaultOpen),
                   }
                 : {}),
+              ...(card ? { 'data-card': card } : {}),
             },
             children: [child, anchorLink(id, label)],
           };

package/src/reference/rehype-table-header-labels.mjs

@@ -32,6 +32,8 @@
  * author typed them or `remark-notation.mjs` auto-inserted them).
  */
 
+import { decorationOfEntry } from './math-glyphs.mjs';
+
 // Mirrors `gloss.ts`'s exported `formulaExplainKeys` regex. Not imported:
 // this file is a plain `.mjs` reference module, copied verbatim into `dist/`
 // by `scripts/copy-assets.mjs`, never touched by the tsup build that
@@ -108,12 +110,28 @@ export function explainKeysIn(sources) {
  * more than one (a ratio like `\mathrm{KE}/m`, explain-wrapped on both
  * sides). `undefined` when nothing resolved, so the caller leaves the
  * header exactly as it was rather than inserting an empty/placeholder label.
+ *
+ * An operator entry (`latex: \hat{}`, rule N22) wraps the symbol it
+ * decorates, so its key comes just before that symbol's: the two read as one
+ * phrase, `"Estimate of regression coefficient"`. The symbol's units are
+ * dropped there, since the operator may change them (a time derivative does).
  */
 export function composeHeaderLabel(keys, notationResolved) {
-  const parts = keys
+  const entries = keys
     .map((key) => notationResolved[key])
-    .filter((entry) => entry && typeof entry.label === 'string')
-    .map((entry) => (entry.units ? `${entry.label} (${entry.units})` : entry.label));
+    .filter((entry) => entry && typeof entry.label === 'string');
+  const parts = [];
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    const operand = entries[index + 1];
+    if (operand && decorationOfEntry(entry.notation) !== undefined) {
+      const name = operand.label.charAt(0).toLowerCase() + operand.label.slice(1);
+      parts.push(`${entry.label} of ${name}`);
+      index += 1;
+      continue;
+    }
+    parts.push(entry.units ? `${entry.label} (${entry.units})` : entry.label);
+  }
   return parts.length > 0 ? parts.join(' / ') : undefined;
 }
 

package/src/reference/remark-asides.mjs

@@ -0,0 +1,180 @@
+/**
+ * Starlight asides in an explico course (docs/plans/titles-and-containers.md
+ * Q10):
+ *
+ *   :::note[Optional title]{icon="heart"}
+ *   Body Markdown.
+ *   :::
+ *
+ * **Why explico renders them.** Starlight turns these directives into asides
+ * only for files under its own `src/content/docs/` (or a
+ * `markdown.processedDirs` entry). An explico course keeps its lessons in
+ * `content/docs/`, and adding that directory to `processedDirs` would also
+ * run Starlight's heading-link pass over headings `rehype-heading-anchors.mjs`
+ * has already wrapped, giving every heading two anchors. So this pass turns
+ * each `:::note` / `:::tip` / `:::caution` / `:::danger` into Starlight's own
+ * `<Aside>` component (importing it into the page): Starlight still draws the
+ * aside, its translated default title, its icon per type, and its check that
+ * a named icon exists. `surfaces.css` gives it the aside tier's look.
+ *
+ * A `.md` lesson has no JSX, so there the aside is written out as the same
+ * markup with no icon — Starlight's icon set is not a public export.
+ *
+ * **An empty icon drops it.** Starlight reads `icon=""` as "the type's
+ * default", so an author has no way to say "none". Here `:::note{icon=""}`
+ * and `<Aside icon="">` lose the attribute and are wrapped in
+ * `<div class="ex-aside-no-icon">`, which `surfaces.css` keys the icon's
+ * removal on.
+ *
+ * Runs last in the course's `remarkPlugins`, after `remarkNotation` has
+ * resolved the `[[…]]` references inside an aside's body. Starlight appends its
+ * own plugins after the course's, so if a course's lessons do sit under
+ * Starlight's path, its aside pass finds nothing left to convert.
+ */
+
+const ASIDE_TYPES = new Set(['note', 'tip', 'caution', 'danger']);
+const DEFAULT_TITLES = { note: 'Note', tip: 'Tip', caution: 'Caution', danger: 'Danger' };
+export const NO_ICON_CLASS = 'ex-aside-no-icon';
+export const ASIDE_COMPONENT = 'ExplicoStarlightAside';
+
+function textOf(node) {
+  if (typeof node?.value === 'string') return node.value;
+  return (node?.children ?? []).map(textOf).join('');
+}
+
+function isAsideDirective(node) {
+  return node?.type === 'containerDirective' && ASIDE_TYPES.has(node.name);
+}
+
+function isEmptyIconComponent(node) {
+  return (
+    node?.type === 'mdxJsxFlowElement' &&
+    node.name === 'Aside' &&
+    (node.attributes ?? []).some(
+      (attribute) =>
+        attribute?.type === 'mdxJsxAttribute' &&
+        attribute.name === 'icon' &&
+        attribute.value === '',
+    )
+  );
+}
+
+function noIconWrapper(node) {
+  return {
+    type: 'explicoAsideNoIcon',
+    data: { hName: 'div', hProperties: { className: [NO_ICON_CLASS] } },
+    children: [node],
+  };
+}
+
+/** The directive's `[label]` paragraph, removed from its body. */
+function takeLabel(node) {
+  const first = node.children?.[0];
+  if (first?.type === 'paragraph' && first.data?.directiveLabel) {
+    node.children.splice(0, 1);
+    return first.children;
+  }
+  return null;
+}
+
+function asComponent(node) {
+  const type = node.name;
+  const icon = node.attributes?.icon;
+  const label = takeLabel(node);
+  const attributes = [{ type: 'mdxJsxAttribute', name: 'type', value: type }];
+  if (label) {
+    attributes.push({ type: 'mdxJsxAttribute', name: 'title', value: label.map(textOf).join('') });
+  }
+  if (icon) attributes.push({ type: 'mdxJsxAttribute', name: 'icon', value: icon });
+  const aside = {
+    type: 'mdxJsxFlowElement',
+    name: ASIDE_COMPONENT,
+    attributes,
+    children: node.children,
+    position: node.position,
+  };
+  return icon === '' ? noIconWrapper(aside) : aside;
+}
+
+function asMarkup(node) {
+  const type = node.name;
+  const label = takeLabel(node);
+  const title = label ?? [{ type: 'text', value: DEFAULT_TITLES[type] }];
+  return {
+    type: 'explicoAside',
+    data: {
+      hName: 'aside',
+      hProperties: {
+        ariaLabel: label ? label.map(textOf).join('') : DEFAULT_TITLES[type],
+        className: ['starlight-aside', `starlight-aside--${type}`],
+      },
+    },
+    position: node.position,
+    children: [
+      {
+        type: 'paragraph',
+        data: { hProperties: { className: ['starlight-aside__title'], ariaHidden: 'true' } },
+        children: title,
+      },
+      {
+        type: 'explicoAsideContent',
+        data: { hName: 'div', hProperties: { className: ['starlight-aside__content'] } },
+        children: node.children,
+      },
+    ],
+  };
+}
+
+/** `import { Aside as ExplicoStarlightAside } from '@astrojs/starlight/components';` */
+function asideImport() {
+  const source = '@astrojs/starlight/components';
+  return {
+    type: 'mdxjsEsm',
+    value: `import { Aside as ${ASIDE_COMPONENT} } from '${source}';`,
+    data: {
+      estree: {
+        type: 'Program',
+        sourceType: 'module',
+        body: [
+          {
+            type: 'ImportDeclaration',
+            specifiers: [
+              {
+                type: 'ImportSpecifier',
+                imported: { type: 'Identifier', name: 'Aside' },
+                local: { type: 'Identifier', name: ASIDE_COMPONENT },
+              },
+            ],
+            source: { type: 'Literal', value: source, raw: `'${source}'` },
+            attributes: [],
+          },
+        ],
+      },
+    },
+  };
+}
+
+export default function remarkAsides() {
+  return function transform(tree, file) {
+    const mdx = !/\.md$/i.test(String(file?.path ?? ''));
+    let used = false;
+    const walk = (node) => {
+      if (!Array.isArray(node?.children)) return;
+      node.children.forEach((child, index) => {
+        walk(child); // an aside may hold another
+        if (isAsideDirective(child)) {
+          node.children[index] = mdx ? asComponent(child) : asMarkup(child);
+          used ||= mdx;
+        } else if (isEmptyIconComponent(child)) {
+          child.attributes = child.attributes.filter(
+            (attribute) =>
+              !(attribute?.type === 'mdxJsxAttribute' && attribute.name === 'icon'),
+          );
+          node.children[index] = noIconWrapper(child);
+        }
+      });
+    };
+    walk(tree);
+    if (used) tree.children.unshift(asideImport());
+  };
+}

package/src/reference/remark-memo.mjs

@@ -5,11 +5,16 @@
  *
  *   The complete calculation is recorded in [[memo-derivation]].
  *
- *   <Memo id="derivation" title="Derivation" description="The algebra.">
+ *   <Memo id="derivation" caption="The algebra behind the result." short="Derivation">
  *   Several paragraphs, equations, tables, or figures.
  *
  *   </Memo>
  *
+ * A memo is named like every float (docs/plans/titles-and-containers.md Part
+ * 3): a required `caption`, shown on its bar and in its preview, and an
+ * optional `short` caption. Its marker is a superscript letter — `ᵃ`, `ᵇ`, …
+ * numbered per page — so it never reads as a citation's `[1]` (decision Q7).
+ *
  * MDX normally rejects this before remark transforms run: an inline JSX node
  * cannot contain block Markdown. The attacher therefore wraps remark-parse's
  * parser and tags each memo before parsing. Legacy inline placements are still
@@ -118,6 +123,25 @@ export function preprocessMemos(source) {
   return output;
 }
 
+/** The per-page memo letter: 1 → `a`, 26 → `z`, 27 → `aa`, … */
+export function memoLetter(number) {
+  let n = Number(number);
+  let letters = '';
+  while (n > 0) {
+    n -= 1;
+    letters = String.fromCharCode(97 + (n % 26)) + letters;
+    n = Math.floor(n / 26);
+  }
+  return letters;
+}
+
+// Name props a memo no longer takes, with the fix each error gives.
+const REMOVED_PROPS = {
+  title:
+    'a memo is named by its `caption` (shown on its bar and in its preview) and an optional `short` caption; move a short title to `short`.',
+  description: 'fold it into `caption`, which is shown on the bar and in the preview.',
+};
+
 function fail(file, message, node) {
   if (typeof file?.fail === 'function') file.fail(message, node);
   const location = file?.path ? `${file.path}: ` : '';
@@ -152,7 +176,7 @@ function markerNode(memo) {
     children: [
       {
         type: 'text',
-        value: memo.label ?? `[${memo.number}]`,
+        value: memo.label ?? memo.number,
       },
     ],
     data: {
@@ -163,9 +187,9 @@ function markerNode(memo) {
         'aria-controls': memo.anchorId,
         'aria-expanded': 'false',
         'aria-label': memo.label
-          ? `${memo.label}: ${memo.title}`
-          : `Memo ${memo.number}: ${memo.title}`,
-        title: memo.title,
+          ? `${memo.label}: ${memo.name}`
+          : `Memo ${memo.number}: ${memo.name}`,
+        title: memo.name,
       },
     },
   };
@@ -227,7 +251,7 @@ function rewriteMemoReferences(node, memos, file) {
 }
 
 /**
- * Number memo blocks from one on every page and resolve same-page
+ * Letter memo blocks from `a` on every page and resolve same-page
  * `[[memo-id]]` references. Numbering is intentionally page-local.
  *
  * @this {any}
@@ -295,9 +319,14 @@ export default function remarkMemo() {
         fail(file, '<Memo> did not become a block-level MDX element.', node);
       }
 
+      for (const [prop, fix] of Object.entries(REMOVED_PROPS)) {
+        if (mdxAttributesNamed(node, prop).length > 0) {
+          fail(file, `<Memo> has no \`${prop}\` prop: ${fix}`, node);
+        }
+      }
       const id = literalAttribute(node, 'id', file);
-      const title = literalAttribute(node, 'title', file);
-      literalAttribute(node, 'description', file);
+      const caption = literalAttribute(node, 'caption', file);
+      const short = literalAttribute(node, 'short', file, { optional: true });
       const label = literalAttribute(node, 'label', file, { optional: true });
       if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
         fail(
@@ -312,18 +341,20 @@ export default function remarkMemo() {
       seenIds.add(id);
 
       number += 1;
+      const letter = memoLetter(number);
       const anchorId = `memo-${id}`;
       removeMdxAttribute(node, BLOCK_ATTRIBUTE);
       injectMdxStringAttributes(node, {
-        number: String(number),
+        number: letter,
         anchorId,
       });
 
       const memo = {
         id,
-        title,
+        // What the marker's tooltip and accessible name call it.
+        name: short ?? caption,
         label,
-        number: String(number),
+        number: letter,
         anchorId,
       };
       memos.set(id, memo);