explico 0.4.0 → 0.5.0

package/src/reference/remark-short-note.mjs

@@ -0,0 +1,237 @@
+/**
+ * Remark adapter for reveal-in-place short notes.
+ *
+ * A `<ShortNote>` may sit inside a sentence while its body contains block
+ * Markdown. Before mdast parsing, the adapter extracts that body and leaves an
+ * ordinary inline link placeholder behind. After parsing, it inserts the real
+ * flow component immediately after the intact paragraph. The browser enhancer
+ * can then split/rejoin that paragraph only while the note is open, preserving
+ * valid and genuinely inline collapsed markup.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { KEYED_FLOAT_KEY_PATTERN } from './keyed-jsx-floats.mjs';
+import {
+  injectMdxStringAttributes,
+  mdxAttributesNamed,
+  removeMdxAttribute,
+} from './mdx-attributes.mjs';
+
+const BLOCK_ATTRIBUTE = 'data-explico-short-note-block';
+const BLOCKS_DATA = 'explicoShortNoteBlocks';
+const MARKER_URL_PREFIX = '#explico-internal-short-note-marker-';
+const ATTRIBUTE_SOURCE = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const SHORT_NOTE_PAIR = new RegExp(
+  String.raw`<ShortNote\b(${ATTRIBUTE_SOURCE})>([\s\S]*?)<\/ShortNote\s*>`,
+  'g',
+);
+
+function maskBlock(block) {
+  return block.replace(/[^\n]/g, ' ');
+}
+
+function searchableSource(source) {
+  return stripFencedCode(source)
+    .replace(/<!--[\s\S]*?-->/g, maskBlock)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, maskBlock);
+}
+
+function extractShortNotes(source) {
+  const input = String(source);
+  const searchable = searchableSource(input);
+  const matches = [...searchable.matchAll(SHORT_NOTE_PAIR)];
+  if (matches.length === 0) return { source: input, notes: [] };
+
+  const notes = [];
+  let cursor = 0;
+  let output = '';
+  for (let index = 0; index < matches.length; index++) {
+    const match = matches[index];
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+
+    const whole = match[0];
+    const maskedAttributes = match[1] ?? '';
+    const openLength = '<ShortNote'.length + maskedAttributes.length + 1;
+    const bodyStart = start + openLength;
+    const closeStart = start + whole.lastIndexOf('</ShortNote');
+    const searchableBody = searchable.slice(bodyStart, closeStart);
+    if (/<ShortNote\b/.test(searchableBody)) {
+      throw new Error('A <ShortNote> cannot be nested inside another <ShortNote>.');
+    }
+
+    notes.push({
+      token: String(index),
+      attributes: input.slice(start + '<ShortNote'.length, bodyStart - 1),
+      body: input.slice(bodyStart, closeStart),
+    });
+    output += input.slice(cursor, start);
+    output += `[short note](${MARKER_URL_PREFIX}${index})`;
+    cursor = start + whole.length;
+  }
+  output += input.slice(cursor);
+  return { source: output, notes };
+}
+
+/** Return the parseable source form, primarily for adapter tests. */
+export function preprocessShortNotes(source) {
+  return extractShortNotes(source).source;
+}
+
+function fail(file, message, node) {
+  if (typeof file?.fail === 'function') file.fail(message, node);
+  const location = file?.path ? `${file.path}: ` : '';
+  throw new Error(`${location}${message}`);
+}
+
+function literalAttribute(node, name, file) {
+  const matches = mdxAttributesNamed(node, name);
+  if (matches.length > 1) {
+    fail(file, `<ShortNote> has more than one \`${name}\` prop.`, node);
+  }
+  if (matches.length === 0) {
+    fail(file, `<ShortNote> requires a non-empty literal \`${name}\` prop.`, node);
+  }
+  const value = matches[0]?.value;
+  if (typeof value !== 'string' || !value.trim()) {
+    fail(
+      file,
+      `<ShortNote> \`${name}\` must be a non-empty literal string; expressions are not supported for inline note triggers.`,
+      matches[0] ?? node,
+    );
+  }
+  return value;
+}
+
+function markerNode(note) {
+  return {
+    type: 'link',
+    url: `#${note.anchorId}`,
+    children: [{ type: 'text', value: note.title }],
+    data: {
+      hProperties: {
+        className: ['short-note-marker'],
+        'data-short-note-key': note.id,
+        'aria-controls': note.anchorId,
+        'aria-expanded': 'false',
+        'aria-label': `${note.title}: ${note.description}`,
+        title: note.description,
+      },
+    },
+  };
+}
+
+function visit(node, callback, parent) {
+  if (!node || typeof node !== 'object') return;
+  callback(node, parent);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) visit(child, callback, node);
+}
+
+/** @this {any} */
+export default function remarkShortNote() {
+  const processor = this;
+  const parse = processor.parser;
+  if (typeof parse !== 'function') {
+    throw new Error(
+      'remarkShortNote must be registered after the Markdown parser (and after remark-mdx when configured explicitly).',
+    );
+  }
+
+  Reflect.set(processor, 'parser', (document, file) => {
+    const extracted = extractShortNotes(document);
+    const tree = parse(extracted.source, file);
+    if (extracted.notes.length === 0) return tree;
+
+    const blocks = extracted.notes.map((note) => {
+      const source = `<ShortNote ${BLOCK_ATTRIBUTE}="${note.token}"${note.attributes}>\n\n${note.body}\n\n</ShortNote>`;
+      const parsed = parse(source, file);
+      const block = parsed.children?.find((node) => node?.name === 'ShortNote');
+      if (!block) {
+        fail(file, 'Unable to parse the extracted <ShortNote> body.', parsed);
+      }
+      return block;
+    });
+    tree.data ??= {};
+    tree.data[BLOCKS_DATA] = blocks;
+    return tree;
+  });
+
+  return function transform(tree, file) {
+    const blocks = tree.data?.[BLOCKS_DATA] ?? [];
+    if (blocks.length === 0) return;
+
+    const markers = new Map();
+    const parents = new Map();
+    visit(tree, (node, parent) => {
+      if (parent) parents.set(node, parent);
+      if (
+        node.type === 'link' &&
+        typeof node.url === 'string' &&
+        node.url.startsWith(MARKER_URL_PREFIX)
+      ) {
+        const token = node.url.slice(MARKER_URL_PREFIX.length);
+        if (markers.has(token)) fail(file, 'Internal short-note marker collision.', node);
+        markers.set(token, { node, parent });
+      }
+    });
+
+    if (blocks.length !== markers.size) {
+      fail(file, 'Internal short-note marker/block pairing failed.', tree);
+    }
+
+    const seenIds = new Set();
+    const insertions = new Map();
+    for (const block of blocks) {
+      const token = literalAttribute(block, BLOCK_ATTRIBUTE, file);
+      const marker = markers.get(token);
+      if (!marker?.parent || marker.parent.type !== 'paragraph') {
+        fail(file, '<ShortNote> must be placed in ordinary prose.', marker?.node ?? block);
+      }
+      const container = parents.get(marker.parent);
+      if (!container || !Array.isArray(container.children)) {
+        fail(file, 'A <ShortNote> paragraph has no flow parent.', marker.parent);
+      }
+      if (block.type !== 'mdxJsxFlowElement') {
+        fail(file, '<ShortNote> did not become a block-level MDX element.', block);
+      }
+
+      const id = literalAttribute(block, 'id', file);
+      const title = literalAttribute(block, 'title', file);
+      const description = literalAttribute(block, 'description', file);
+      if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
+        fail(
+          file,
+          `Invalid <ShortNote id="${id}">; use lowercase letters/numbers separated by single hyphens.`,
+          block,
+        );
+      }
+      if (seenIds.has(id)) {
+        fail(file, `Duplicate <ShortNote id="${id}"> on this page.`, block);
+      }
+      seenIds.add(id);
+
+      const anchorId = `short-note-${id}`;
+      removeMdxAttribute(block, BLOCK_ATTRIBUTE);
+      injectMdxStringAttributes(block, { anchorId });
+
+      const markerIndex = marker.parent.children.indexOf(marker.node);
+      marker.parent.children[markerIndex] = markerNode({
+        id,
+        title,
+        description,
+        anchorId,
+      });
+
+      const existing = insertions.get(marker.parent) ?? { container, blocks: [] };
+      existing.blocks.push(block);
+      insertions.set(marker.parent, existing);
+    }
+
+    for (const [paragraph, insertion] of insertions) {
+      const paragraphIndex = insertion.container.children.indexOf(paragraph);
+      insertion.container.children.splice(paragraphIndex + 1, 0, ...insertion.blocks);
+    }
+    delete tree.data[BLOCKS_DATA];
+  };
+}

package/src/reference/types.ts

@@ -96,6 +96,22 @@ export interface NotationRegistryInput {
   readonly lessons: readonly NotationLessonInput[];
 }
 
+/**
+ * One entry in the abbreviations table (N14) — deliberately a lighter tier
+ * than {@link SharedNotationDefinitionInput}: a name resolution only, no
+ * `formula`, `units`, `alignment`, or `sources`. `abbr` is the canonical
+ * written form (`OLS`); `aliases` are other written forms of the same
+ * abbreviation (`w.r.t.` might alias `wrt`) that should resolve the same way.
+ */
+export interface AbbreviationDefinitionInput {
+  readonly key: string;
+  readonly abbr: string;
+  readonly expansion: string;
+  readonly aliases: readonly string[];
+  readonly domain?: string;
+  readonly source: SourceSpan;
+}
+
 export type NotationDiagnosticCode =
   | 'invalid-key'
   | 'duplicate-page'

package/src/reference/units-vocab.ts

@@ -123,6 +123,10 @@ export const UNITS_VOCAB: ReadonlySet<string> = new Set([
   'meters',
   'second',
   'seconds',
+  'kilogram',
+  'kilograms',
+  'joule',
+  'joules',
   'speed',
   'velocity',
   'acceleration',