@react-x11/components 0.5.0 → 0.7.0

package/src/markdown/ast.ts

@@ -1,9 +1,10 @@
 // The markdown AST `parse.ts` produces and `index.ts` renders. Deliberately
 // small: it is the GFM constructs this component draws, not a general
 // mdast — but it is shaped so that growing it stays additive. In particular
-// `component` is reserved for the MDX direction: a parser extension can emit
-// one without the renderer, the selection model or the caches changing shape
-// (see "MDX" in index.ts).
+// `component` is the MDX direction: `ComponentBlock` is parsed and rendered
+// (docs/prd-mdx.md, M1), and `ComponentInline` is still reserved — see the
+// note on it for why the inline half needs machinery `<richtext>` does not
+// have yet.
 
 /** Inline content, inside a paragraph, heading, list item or table cell. */
 export type InlineNode =
@@ -12,7 +13,19 @@ export type InlineNode =
   | EmphasisInline
   | LinkInline
   | BreakInline
-  | ComponentInline;
+  | ComponentInline
+  | ExpressionInline;
+
+/**
+ * `{count}` in the middle of a sentence: unevaluated source, which the
+ * renderer compiles against its `scope` and turns into text. Only emitted
+ * when `ParseOptions.expressions` says so, so `{braces}` in an ordinary
+ * document remain the characters they have always been.
+ */
+export interface ExpressionInline {
+  type: 'expression';
+  src: string;
+}
 
 /** A run of plain text. Softbreaks arrive collapsed to spaces. */
 export interface TextInline {
@@ -51,14 +64,41 @@ export interface BreakInline {
 }
 
 /**
- * Reserved for MDX: `<Chart data={…} />` would parse to one of these. The
- * current parser never emits it; the renderer maps unknown names to plain
- * text so a future parser upgrade cannot crash an older renderer.
+ * An attribute's value. `literal` is what an attribute string or a `{json}`
+ * attribute resolves to at parse time; `expression` holds unevaluated source
+ * for the rung that compiles it, so that parsing stays pure and one AST can
+ * be rendered against two scopes (docs/prd-mdx.md, M2). The parser emits
+ * only `literal` today.
+ */
+export type AttributeValue =
+  { kind: 'literal'; value: unknown } | { kind: 'expression'; src: string };
+
+/**
+ * A spread (`{...props}`) is an attribute with no name, so it is keyed
+ * `...0`, `...1`, … in the order it appeared. An attribute name cannot start
+ * with `.`, so these cannot collide with one; a renderer walking
+ * `Object.entries` in insertion order applies each spread where it was
+ * written, which is what decides whether it overrides `height` or `height`
+ * overrides it.
+ */
+export const SPREAD_PREFIX = '...';
+
+/**
+ * **Still reserved.** `<Badge/>` in the middle of a sentence parses to one of
+ * these — except that nothing emits them yet, because nothing can render
+ * them: a paragraph is laid out as a single `<richtext>`, and a `TextRun`
+ * has no way to say "reserve this much advance width for an element someone
+ * else paints". Giving it one is the inline half of MDX and is its own piece
+ * of work (baseline alignment, wrapping around the element, and what a
+ * selection dragged across it should copy).
+ *
+ * Kept in the union so the shape stays stable, and so a renderer written
+ * against it today cannot be broken by the parser learning to emit them.
  */
 export interface ComponentInline {
   type: 'component';
   name: string;
-  attributes: Record<string, string>;
+  attributes: Record<string, AttributeValue>;
   children: InlineNode[];
 }
 
@@ -70,7 +110,22 @@ export type BlockNode =
   | QuoteBlock
   | ListBlock
   | TableBlock
-  | RuleBlock;
+  | RuleBlock
+  | ComponentBlock;
+
+/**
+ * A component standing where a paragraph would: `<Chart data={…} />` on its
+ * own line, or `<Callout>` … `</Callout>` around blocks.
+ *
+ * Only emitted when `ParseOptions.isComponent` says the name is one — which
+ * is what keeps every document that renders today rendering the same way.
+ */
+export interface ComponentBlock {
+  type: 'component';
+  name: string;
+  attributes: Record<string, AttributeValue>;
+  children: BlockNode[];
+}
 
 export interface ParagraphBlock {
   type: 'paragraph';
@@ -160,4 +215,25 @@ export interface ParseOptions {
    * underline or a rule) is held back. Pass false for text that is final.
    */
   partial?: boolean;
+  /**
+   * Whether `name` is a component this document may use. Absent — the
+   * default — means no tag is a component and `<Chart/>` stays the literal
+   * text it has always been, so turning MDX on is opt-in and turning it off
+   * is byte-for-byte the old behaviour.
+   *
+   * `<Markdown>` supplies one from its `components` prop. A dotted name
+   * (`Card.Header`) is passed through whole; resolving it is the caller's.
+   */
+  isComponent?: (name: string) => boolean;
+  /**
+   * Whether `{…}` may hold a JavaScript expression — in an attribute, as a
+   * `{...spread}`, or bare in the prose. Off by default, and off is the
+   * whole of rung 1: a `{…}` attribute must be JSON, and a brace in a
+   * paragraph is a brace.
+   *
+   * `<Markdown>` turns this on when it is given a `scope`, which is the prop
+   * that says the application accepts a document running code. Parsing still
+   * evaluates nothing — an expression is kept as source.
+   */
+  expressions?: boolean;
 }

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;