@react-x11/components 0.5.0 → 0.6.0

package/src/markdown/expressions.ts

@@ -0,0 +1,223 @@
+// Compiling `{…}` — the rung where a document runs code (docs/prd-mdx.md,
+// M2), and the one place in this component that calls `new Function`.
+//
+// It is a small file on purpose. Everything hard about MDX expressions was
+// decided elsewhere: the parser holds an expression as *source* rather than
+// a value, so a parse is pure and one AST can be rendered against two
+// scopes; and `<Markdown>` only turns any of this on when the application
+// passes a `scope`, which is the prop that means "I accept that this
+// document may compute". What is left here is compiling the source once, and
+// not letting a half-typed expression take down a document that is still
+// being typed.
+//
+// **There is no sandbox.** `new Function` runs in this process with this
+// process's authority. That is why the gate is a prop, and why the docs say
+// in as few words as they can: do not pass `scope` alongside a document you
+// did not write.
+
+import type { BlockNode, Document, InlineNode } from './ast.js';
+
+/** A compiled expression, or null if it would not compile at all. */
+type Compiled = ((...args: unknown[]) => unknown) | null;
+
+/**
+ * Keyed on the scope's shape *and* the source, because a compiled function
+ * closes over its parameter names. Bounded the way `richtext/node.ts` bounds
+ * its layout cache: a streaming document recompiles its tail on every chunk,
+ * and an unbounded map would hold every intermediate spelling of an
+ * expression that was being typed.
+ */
+const CACHE = new Map<string, Compiled>();
+const LIMIT = 256;
+
+let warned = false;
+
+/**
+ * Say so, once, when an expression does not work out. A document that
+ * silently loses a value should not be a mystery — and saying it on every
+ * frame of a streaming render would be worse than saying nothing.
+ *
+ * `process` and `console` come off `globalThis` because `src/` compiles with
+ * `types: []` — a Node global that wandered in would fail the build rather
+ * than become an implicit `@types/node` dependency.
+ */
+function warnFailed(src: string, error: unknown): void {
+  if (warned) return;
+  warned = true;
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    console?: { warn(message: string, ...rest: unknown[]): void };
+  };
+  if (g.process?.env?.NODE_ENV === 'production') return;
+  g.console?.warn(
+    '@react-x11/components: a markdown expression did not evaluate, so it ' +
+      `rendered as nothing: {${src}}`,
+    error,
+  );
+}
+
+function compile(src: string, keys: readonly string[]): Compiled {
+  const key = `${keys.join(',')} ${src}`;
+  const hit = CACHE.get(key);
+  if (hit !== undefined) return hit;
+  let compiled: Compiled = null;
+  try {
+    // `return (…)` rather than a bare body: an expression is what the braces
+    // promised, and the parentheses keep an object literal an object literal
+    // rather than a block.
+    compiled = new Function(...keys, `"use strict"; return (${src});`) as (
+      ...args: unknown[]
+    ) => unknown;
+  } catch (error) {
+    // A syntax error is the ordinary state of an expression being typed.
+    warnFailed(src, error);
+  }
+  if (CACHE.size >= LIMIT) CACHE.clear();
+  CACHE.set(key, compiled);
+  return compiled;
+}
+
+/**
+ * What a renderer calls: source in, value out, `undefined` if it did not
+ * work. Never throws — a document being edited is full of expressions that
+ * do not work yet.
+ */
+export type Evaluate = (src: string) => unknown;
+
+/**
+ * An evaluator over `scope`. The keys are read once, so a scope mutated in
+ * place after this is called keeps its old shape — the same contract every
+ * other seam here has, and the reason the prop doc asks for a stable object.
+ */
+export function evaluator(scope: Record<string, unknown>): Evaluate {
+  const keys = Object.keys(scope);
+  const values = keys.map((k) => scope[k]);
+  return (src) => {
+    const fn = compile(src, keys);
+    if (!fn) return undefined;
+    try {
+      return fn(...values);
+    } catch (error) {
+      warnFailed(src, error);
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Only the tests need to reach in: a compile cache that survived between
+ * them would make one test's expression another's, and the warn-once flag
+ * would hide the second failure anyone asserted on.
+ */
+export function clearExpressionCache(): void {
+  CACHE.clear();
+  warned = false;
+}
+
+// --- resolving a parsed document ------------------------------------------
+
+/**
+ * A copy of `nodes` with every `expression` replaced by the text it
+ * evaluates to. Primitives stringify; anything else — an object, an array, a
+ * React element — renders as nothing, because a paragraph is text and there
+ * is nowhere in a text run to put an element (see "The inline half" in
+ * docs/prd-mdx.md). `null` and `undefined` are nothing on purpose, so
+ * `{maybe}` reads as absent rather than as the word "undefined".
+ */
+function resolveInline(nodes: InlineNode[], evaluate: Evaluate): InlineNode[] {
+  let changed = false;
+  const out: InlineNode[] = [];
+  for (const node of nodes) {
+    if (node.type === 'expression') {
+      changed = true;
+      const value = evaluate(node.src);
+      const text =
+        value == null ||
+        typeof value === 'object' ||
+        typeof value === 'function'
+          ? ''
+          : String(value);
+      if (text) out.push({ type: 'text', text });
+      continue;
+    }
+    if ('children' in node) {
+      const children = resolveInline(node.children, evaluate);
+      if (children !== node.children) {
+        changed = true;
+        out.push({ ...node, children });
+        continue;
+      }
+    }
+    out.push(node);
+  }
+  return changed ? out : nodes;
+}
+
+function resolveBlocks(blocks: BlockNode[], evaluate: Evaluate): BlockNode[] {
+  let changed = false;
+  const out = blocks.map((block): BlockNode => {
+    switch (block.type) {
+      case 'paragraph':
+      case 'heading': {
+        const children = resolveInline(block.children, evaluate);
+        if (children === block.children) return block;
+        changed = true;
+        return { ...block, children };
+      }
+      case 'quote':
+      case 'component': {
+        const children = resolveBlocks(block.children, evaluate);
+        if (children === block.children) return block;
+        changed = true;
+        return { ...block, children };
+      }
+      case 'list': {
+        let itemsChanged = false;
+        const items = block.items.map((item) => {
+          const children = resolveBlocks(item.children, evaluate);
+          if (children === item.children) return item;
+          itemsChanged = true;
+          return { ...item, children };
+        });
+        if (!itemsChanged) return block;
+        changed = true;
+        return { ...block, items };
+      }
+      case 'table': {
+        let rowsChanged = false;
+        const rows = block.rows.map((row) =>
+          row.map((cell) => {
+            const next = resolveInline(cell, evaluate);
+            if (next !== cell) rowsChanged = true;
+            return next;
+          }),
+        );
+        const header = block.header.map((cell) => {
+          const next = resolveInline(cell, evaluate);
+          if (next !== cell) rowsChanged = true;
+          return next;
+        });
+        if (!rowsChanged) return block;
+        changed = true;
+        return { ...block, header, rows };
+      }
+      default:
+        return block;
+    }
+  });
+  return changed ? out : blocks;
+}
+
+/**
+ * The document with its expressions evaluated. `raws` is carried over
+ * untouched: it is the block cache's key, and what changed is the values an
+ * expression produced, not the text that produced them — a change of `scope`
+ * invalidates that cache through its own identity instead.
+ */
+export function resolveExpressions(
+  doc: Document,
+  evaluate: Evaluate,
+): Document {
+  const blocks = resolveBlocks(doc.blocks, evaluate);
+  return blocks === doc.blocks ? doc : { blocks, raws: doc.raws };
+}

package/src/markdown/index.ts

@@ -38,7 +38,7 @@
 // answering the four accessors in core's docs/extending.md, with nothing to
 // register.
 import React from 'react';
-import type { ReactElement, ReactNode } from 'react';
+import type { ComponentType, ReactElement, ReactNode } from 'react';
 import { Icon, useApp, useTheme } from 'react-x11';
 import type { DrawnNode, MouseEvent as X11MouseEvent } from 'react-x11';
 import { tint } from 'react-x11/style';
@@ -46,6 +46,7 @@ import type { Style } from 'react-x11/style';
 
 import type {
   BlockNode,
+  ComponentBlock,
   Document,
   InlineNode,
   ListBlock,
@@ -67,17 +68,27 @@ import type { CodeBlockLook } from '../codeblock/index.js';
 import type { Language } from '../code-language/index.js';
 
 import { parse } from './parse.js';
+import { evaluator, resolveExpressions } from './expressions.js';
+import type { Evaluate } from './expressions.js';
+import { SPREAD_PREFIX } from './ast.js';
 import { runsOf, plainTextOf } from './spans.js';
 import type { InlineStyles } from './spans.js';
 import { useLinkClicks } from '../richtext/index.js';
 import { hx } from './hx.js';
 
 export type {
+  AttributeValue,
   BlockNode,
+  ComponentBlock,
+  ComponentInline,
+  ExpressionInline,
   InlineNode,
   Document as MarkdownDocument,
   ParseOptions,
 } from './ast.js';
+export { SPREAD_PREFIX } from './ast.js';
+export { scanTag } from './tags.js';
+export type { ScannedTag, ScanResult } from './tags.js';
 export { parse, parseInline } from './parse.js';
 
 const h = React.createElement;
@@ -156,6 +167,62 @@ export interface MarkdownProps {
    * stable identity — a new object per render defeats the block cache.
    */
   fences?: Record<string, (fence: FenceInfo) => ReactNode>;
+  /**
+   * Components a document may name — the MDX gate (docs/prd-mdx.md).
+   *
+   * A tag is a component **iff its name is a key here**: there is no
+   * capitalisation rule and no HTML fallback, so `<Chart/>` in a document
+   * with no `Chart` key is the literal text it has always been, and a
+   * document that never passes this prop parses exactly as it did before
+   * the feature existed.
+   *
+   * ```tsx
+   * <Markdown source={doc} components={{ Chart, Callout }} />
+   * ```
+   *
+   * A dotted name resolves flat first (`components['Card.Header']`), then by
+   * walking (`components.Card.Header`), so compound components work.
+   *
+   * **Nothing is evaluated.** An attribute is a string, `true` for a bare
+   * name, or the `JSON.parse` of a `{…}`; a brace that is not JSON makes the
+   * tag unreadable and it stays text. That is what makes this safe to point
+   * at a document you did not write — which, for this component, is the
+   * usual case.
+   *
+   * Block position only: a tag on its own line(s) is a component, and one in
+   * the middle of a sentence is still text. See `ComponentInline` in ast.ts.
+   *
+   * Give the map a stable identity — a new object per render defeats the
+   * block cache, the same way a new `fences` map does.
+   */
+  components?: Record<string, ComponentType<Record<string, unknown>>>;
+  /**
+   * Bindings that `{…}` in this document may read — and, by passing it, the
+   * statement that this document may **run code**.
+   *
+   * ```tsx
+   * <Markdown source={doc} components={{ Chart }} scope={{ quarters }} />
+   * ```
+   *
+   * With it, an attribute `{…}` that is not JSON is compiled instead of
+   * making the tag text, `{...spread}` works, and `{count}` in the middle of
+   * a paragraph renders the value. Without it none of those exist and
+   * nothing is ever compiled.
+   *
+   * **There is no sandbox.** Expressions run through `new Function`, in this
+   * process, with this process's authority. `components` decides what a
+   * document may *reach*; this decides whether it may *compute* — so do not
+   * pass it alongside a document you did not write, which for this component
+   * usually means anything a model produced.
+   *
+   * An expression that throws, or does not compile, renders as nothing and
+   * warns once. A value that is not a primitive renders as nothing in prose:
+   * there is nowhere in a line of text to put an element.
+   *
+   * Stable identity, as with `components` — the keys are read once, and a new
+   * object per render re-parses the document.
+   */
+  scope?: Record<string, unknown>;
   /** The root `<box>`'s style — width, padding, margins, `overflow`. */
   style?: Style | Style[];
   'data-testname'?: string;
@@ -222,6 +289,33 @@ function deriveLook(
   };
 }
 
+// --- components ------------------------------------------------------------
+
+/**
+ * The component a tag names, or undefined. Flat key first, so a map can spell
+ * a dotted name literally, then the walk, so `Card.Header` finds the property
+ * hanging off `Card`.
+ */
+function resolveComponent(
+  map: MarkdownProps['components'],
+  name: string,
+): ComponentType<Record<string, unknown>> | undefined {
+  if (!map) return undefined;
+  const flat = map[name];
+  if (flat) return flat;
+  if (!name.includes('.')) return undefined;
+  let cur: unknown = map;
+  for (const part of name.split('.')) {
+    if (cur == null || (typeof cur !== 'object' && typeof cur !== 'function')) {
+      return undefined;
+    }
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur == null
+    ? undefined
+    : (cur as ComponentType<Record<string, unknown>>);
+}
+
 // --- rendering -------------------------------------------------------------
 
 interface RenderCtx {
@@ -230,6 +324,9 @@ interface RenderCtx {
   fonts: FontsMeasureLike | null;
   fences?: MarkdownProps['fences'];
   resolveLanguage?: MarkdownProps['resolveLanguage'];
+  components?: MarkdownProps['components'];
+  /** Present exactly when `scope` was given — the rung that compiles. */
+  evaluate?: Evaluate;
   /** True while rendering the live tail block of a streaming document. */
   live?: boolean;
 }
@@ -325,7 +422,56 @@ function renderBlock(block: BlockNode, ctx: RenderCtx, key: number): ReactNode {
 
     case 'table':
       return renderTable(block, ctx, key);
+
+    case 'component':
+      return renderComponent(block, ctx, key);
+  }
+}
+
+/**
+ * A component block. The node only exists because the parser was told this
+ * name resolves, so the lookup here agrees by construction — the `undefined`
+ * branch is for the window between a `components` prop changing and the
+ * re-parse that follows it.
+ *
+ * Children arrive as a laid-out column of blocks, so a component places one
+ * child and does not have to know what markdown is.
+ */
+function renderComponent(
+  block: ComponentBlock,
+  ctx: RenderCtx,
+  key: number,
+): ReactNode {
+  const Component = resolveComponent(ctx.components, block.name);
+  if (!Component) return null;
+  const props: Record<string, unknown> = {};
+  // Insertion order is the order they were written, which is what decides
+  // whether a spread overrides a named attribute or the other way round.
+  for (const [name, value] of Object.entries(block.attributes)) {
+    if (name.startsWith(SPREAD_PREFIX)) {
+      const spread =
+        value.kind === 'expression' ? ctx.evaluate?.(value.src) : undefined;
+      if (spread && typeof spread === 'object') Object.assign(props, spread);
+      continue;
+    }
+    props[name] =
+      value.kind === 'literal' ? value.value : ctx.evaluate?.(value.src);
   }
+  const children =
+    block.children.length === 0
+      ? undefined
+      : hx(
+          'box',
+          {
+            style: {
+              flexDirection: 'column',
+              gap: ctx.look.blockGap,
+              alignItems: 'stretch',
+            },
+          },
+          renderBlocks(block.children, ctx),
+        );
+  return h(React.Fragment, { key }, h(Component, props, children));
 }
 
 function renderCode(
@@ -591,11 +737,40 @@ export function Markdown(props: MarkdownProps): ReactElement {
     ],
   );
 
-  const doc: Document = React.useMemo(
-    () => parse(source, { partial }),
-    [source, partial],
+  // The gate the parser asks. Memoised on the map's identity so that a
+  // stable `components` prop keeps one function, and the parse memo below
+  // does not re-read the whole document on every render.
+  const componentMap = props.components;
+  const isComponent = React.useMemo(
+    () =>
+      componentMap
+        ? (name: string) => resolveComponent(componentMap, name) !== undefined
+        : undefined,
+    [componentMap],
   );
 
+  // `scope` is both the gate and the bindings: giving one turns expression
+  // parsing on, and is where the compiled functions get their arguments.
+  const scope = props.scope;
+  const evaluate = React.useMemo(
+    () => (scope ? evaluator(scope) : undefined),
+    [scope],
+  );
+
+  const doc: Document = React.useMemo(() => {
+    const parsed = parse(source, {
+      partial,
+      ...(isComponent ? { isComponent } : null),
+      ...(evaluate ? { expressions: true } : null),
+    });
+    // Expressions resolve to text here rather than during the render, so
+    // every `runsOf` caller downstream keeps seeing an inline tree it
+    // already understands. `raws` is carried through, so the block cache
+    // still keys on the source text; a change of `scope` invalidates it
+    // through the seam epoch instead.
+    return evaluate ? resolveExpressions(parsed, evaluate) : parsed;
+  }, [source, partial, isComponent, evaluate]);
+
   // Per-block element cache, keyed on the block's raw source (+ whether it
   // is the live tail). Streaming appends re-render only the block that
   // changed; everything else is the same ReactElement, so React bails out
@@ -608,19 +783,27 @@ export function Markdown(props: MarkdownProps): ReactElement {
   const seamsRef = React.useRef<{
     fences: MarkdownProps['fences'];
     resolveLanguage: MarkdownProps['resolveLanguage'];
+    components: MarkdownProps['components'];
+    scope: MarkdownProps['scope'];
     gen: number;
   }>({
     fences: props.fences,
     resolveLanguage: props.resolveLanguage,
+    components: props.components,
+    scope: props.scope,
     gen: 0,
   });
   if (
     seamsRef.current.fences !== props.fences ||
-    seamsRef.current.resolveLanguage !== props.resolveLanguage
+    seamsRef.current.resolveLanguage !== props.resolveLanguage ||
+    seamsRef.current.components !== props.components ||
+    seamsRef.current.scope !== props.scope
   ) {
     seamsRef.current = {
       fences: props.fences,
       resolveLanguage: props.resolveLanguage,
+      components: props.components,
+      scope: props.scope,
       gen: seamsRef.current.gen + 1,
     };
   }
@@ -638,6 +821,8 @@ export function Markdown(props: MarkdownProps): ReactElement {
       fonts,
       fences: props.fences,
       resolveLanguage: props.resolveLanguage,
+      components: props.components,
+      ...(evaluate ? { evaluate } : null),
     };
     for (let i = 0; i < doc.blocks.length; i += 1) {
       const live = partial && i === doc.blocks.length - 1;