explico 0.4.0 → 0.6.0

package/src/reference/remark-memo.mjs

@@ -0,0 +1,339 @@
+/**
+ * Remark adapter for substantial, referenceable memo disclosures.
+ *
+ * Authors place a memo as a normal flow block and cite it from earlier prose:
+ *
+ *   The complete calculation is recorded in [[memo-derivation]].
+ *
+ *   <Memo id="derivation" title="Derivation" description="The algebra.">
+ *   Several paragraphs, equations, tables, or figures.
+ *
+ *   </Memo>
+ *
+ * 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
+ * split into a temporary marker plus a flow `<Memo>`; standalone blocks do not
+ * emit a marker at their authored location. The transformer resolves every
+ * `[[memo-id]]` to a numbered link and injects the memo's per-page number and
+ * anchor into the real component. Temporary attributes never reach output.
+ */
+
+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-memo-block';
+const MARKER_URL_PREFIX = '#explico-internal-memo-marker-';
+const MEMO_REFERENCE_PATTERN =
+  /\[\[\s*memo-([a-z0-9]+(?:-[a-z0-9]+)*)\s*\]\]/g;
+
+/** A same-page memo reference payload, e.g. `memo-full-derivation`. */
+export function parseMemoRef(raw) {
+  const match = /^memo-([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(String(raw).trim());
+  return match ? { key: match[1] } : undefined;
+}
+
+// An MDX attribute may be a quoted string, a brace expression (including one
+// level of nested braces), or ordinary unquoted source. Required memo props are
+// validated as literal strings after parsing; this breadth is for preserving
+// unrelated props such as `rememberState={condition}` intact.
+const ATTRIBUTE_SOURCE = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const MEMO_PAIR = new RegExp(
+  String.raw`<Memo\b(${ATTRIBUTE_SOURCE})>([\s\S]*?)<\/Memo\s*>`,
+  'g',
+);
+
+function maskBlock(block) {
+  return block.replace(/[^\n]/g, ' ');
+}
+
+/** Protect examples/comments whose literal `<Memo>` text is not authoring. */
+function searchableMemoSource(source) {
+  return stripFencedCode(source)
+    .replace(/<!--[\s\S]*?-->/g, maskBlock)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, maskBlock);
+}
+
+function isStandaloneBlock(source, start, end) {
+  const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+  const followingNewline = source.indexOf('\n', end);
+  const lineEnd = followingNewline === -1 ? source.length : followingNewline;
+  return (
+    source.slice(lineStart, start).trim().length === 0 &&
+    source.slice(end, lineEnd).trim().length === 0
+  );
+}
+
+/**
+ * Turn otherwise-unparseable inline/block memo syntax into ordinary MDX while
+ * retaining author attributes and body source verbatim.
+ */
+export function preprocessMemos(source) {
+  const input = String(source);
+  const searchable = searchableMemoSource(input);
+  const matches = [...searchable.matchAll(MEMO_PAIR)];
+  if (matches.length === 0) return input;
+
+  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 = '<Memo'.length + maskedAttributes.length + 1;
+    const closeOffset = whole.lastIndexOf('</Memo');
+    const bodyStart = start + openLength;
+    const closeStart = start + closeOffset;
+    const attributes = input.slice(start + '<Memo'.length, bodyStart - 1);
+    const body = input.slice(bodyStart, closeStart);
+    const searchableBody = searchable.slice(bodyStart, closeStart);
+    if (/<Memo\b/.test(searchableBody)) {
+      throw new Error('A <Memo> cannot be nested inside another <Memo>.');
+    }
+
+    const closingTag = input.slice(closeStart, start + whole.length);
+    const end = start + whole.length;
+    output += input.slice(cursor, start);
+    if (isStandaloneBlock(input, start, end)) {
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}`;
+    } else {
+      output += `[memo](${MARKER_URL_PREFIX}${index})\n\n`;
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}\n\n`;
+    }
+    cursor = end;
+  }
+  output += input.slice(cursor);
+  return output;
+}
+
+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, { optional = false } = {}) {
+  const matches = mdxAttributesNamed(node, name);
+  if (matches.length > 1) {
+    fail(file, `<Memo> has more than one \`${name}\` prop.`, node);
+  }
+  if (matches.length === 0) {
+    if (optional) return undefined;
+    fail(file, `<Memo> requires a non-empty literal \`${name}\` prop.`, node);
+  }
+  const value = matches[0]?.value;
+  if (typeof value !== 'string' || !value.trim()) {
+    const qualifier = optional ? 'when provided' : '';
+    fail(
+      file,
+      `<Memo> \`${name}\` must be a non-empty literal string${qualifier ? ` ${qualifier}` : ''}; expressions are not supported for build-time memo markers.`,
+      matches[0] ?? node,
+    );
+  }
+  return value;
+}
+
+function markerNode(memo) {
+  const link = {
+    type: 'link',
+    url: `#${memo.anchorId}`,
+    children: [
+      {
+        type: 'text',
+        value: memo.label ?? `[${memo.number}]`,
+      },
+    ],
+    data: {
+      hProperties: {
+        className: ['memo-marker'],
+        'data-memo-key': memo.id,
+        'data-memo-number': memo.number,
+        'aria-controls': memo.anchorId,
+        'aria-expanded': 'false',
+        'aria-label': memo.label
+          ? `${memo.label}: ${memo.title}`
+          : `Memo ${memo.number}: ${memo.title}`,
+        title: memo.title,
+      },
+    },
+  };
+  if (memo.label) return link;
+  return {
+    type: 'emphasis',
+    children: [link],
+    data: {
+      hName: 'sup',
+      hProperties: { className: ['memo-marker-wrap'] },
+    },
+  };
+}
+
+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);
+}
+
+function rewriteMemoReferences(node, memos, file) {
+  if (!node || typeof node !== 'object' || !Array.isArray(node.children)) return;
+  if (node.type === 'link' || node.type === 'linkReference') return;
+
+  for (let index = 0; index < node.children.length; index++) {
+    const child = node.children[index];
+    if (child?.type !== 'text' || typeof child.value !== 'string') {
+      rewriteMemoReferences(child, memos, file);
+      continue;
+    }
+
+    const replacements = [];
+    let cursor = 0;
+    let match;
+    MEMO_REFERENCE_PATTERN.lastIndex = 0;
+    while ((match = MEMO_REFERENCE_PATTERN.exec(child.value))) {
+      if (match.index > cursor) {
+        replacements.push({ type: 'text', value: child.value.slice(cursor, match.index) });
+      }
+      const memo = memos.get(match[1]);
+      if (!memo) {
+        fail(
+          file,
+          `Unknown memo reference [[memo-${match[1]}]]: no <Memo> on this page carries id="${match[1]}".`,
+          child,
+        );
+      }
+      replacements.push(markerNode({ ...memo, label: undefined }));
+      cursor = match.index + match[0].length;
+    }
+    if (replacements.length === 0) continue;
+    if (cursor < child.value.length) {
+      replacements.push({ type: 'text', value: child.value.slice(cursor) });
+    }
+    node.children.splice(index, 1, ...replacements);
+    index += replacements.length - 1;
+  }
+}
+
+/**
+ * Number memo blocks from one on every page and resolve same-page
+ * `[[memo-id]]` references. Numbering is intentionally page-local.
+ *
+ * @this {any}
+ */
+export default function remarkMemo() {
+  const processor = this;
+  const parse = processor.parser;
+  if (typeof parse !== 'function') {
+    throw new Error(
+      'remarkMemo must be registered after the Markdown parser (and after remark-mdx when configured explicitly).',
+    );
+  }
+  Reflect.set(processor, 'parser', (document, file) =>
+    parse(preprocessMemos(document), file),
+  );
+
+  return function transform(tree, file) {
+    const blocks = new Map();
+    const markerLocations = new Map();
+    const unprocessed = [];
+
+    visit(tree, (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 (markerLocations.has(token)) {
+          fail(file, 'Internal memo marker collision.', node);
+        }
+        markerLocations.set(token, { node, parent });
+      }
+      if (node.name !== 'Memo') return;
+      const internal = mdxAttributesNamed(node, BLOCK_ATTRIBUTE);
+      if (internal.length === 0) {
+        unprocessed.push(node);
+        return;
+      }
+      const token = literalAttribute(node, BLOCK_ATTRIBUTE, file);
+      if (blocks.has(token)) fail(file, 'Internal memo block collision.', node);
+      blocks.set(token, node);
+    });
+
+    if (unprocessed.length > 0) {
+      fail(
+        file,
+        '<Memo> must use a paired opening and closing tag so remarkMemo can place its inline marker and block body.',
+        unprocessed[0],
+      );
+    }
+    for (const token of markerLocations.keys()) {
+      if (!blocks.has(token)) fail(file, 'Internal memo marker/block pairing failed.', tree);
+    }
+
+    const seenIds = new Set();
+    const memos = new Map();
+    let number = 0;
+    for (const [token, node] of blocks) {
+      const marker = markerLocations.get(token);
+      if (marker && (!marker.parent || !Array.isArray(marker.parent.children))) {
+        fail(file, 'Internal memo marker has no paragraph parent.', marker.node);
+      }
+      if (node.type !== 'mdxJsxFlowElement') {
+        fail(file, '<Memo> did not become a block-level MDX element.', node);
+      }
+
+      const id = literalAttribute(node, 'id', file);
+      const title = literalAttribute(node, 'title', file);
+      literalAttribute(node, 'description', file);
+      const label = literalAttribute(node, 'label', file, { optional: true });
+      if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
+        fail(
+          file,
+          `Invalid <Memo id="${id}">; use lowercase letters/numbers separated by single hyphens.`,
+          node,
+        );
+      }
+      if (seenIds.has(id)) {
+        fail(file, `Duplicate <Memo id="${id}"> on this page.`, node);
+      }
+      seenIds.add(id);
+
+      number += 1;
+      const anchorId = `memo-${id}`;
+      removeMdxAttribute(node, BLOCK_ATTRIBUTE);
+      injectMdxStringAttributes(node, {
+        number: String(number),
+        anchorId,
+      });
+
+      const memo = {
+        id,
+        title,
+        label,
+        number: String(number),
+        anchorId,
+      };
+      memos.set(id, memo);
+
+      if (marker) {
+        const markerIndex = marker.parent.children.indexOf(marker.node);
+        marker.parent.children[markerIndex] = markerNode(memo);
+      }
+    }
+
+    rewriteMemoReferences(tree, memos, file);
+  };
+}