@react-x11/components 0.4.0 → 0.6.0

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;

package/src/markdown/parse.ts

@@ -22,10 +22,14 @@
 //   definitions pass over the whole document, and streamed model output
 //   essentially never uses them.
 // - **Raw HTML is literal text.** There is no HTML pass anywhere in this
-//   component, by design; `<Component />` syntax is reserved for a future
-//   MDX extension (see `ComponentInline` in ast.ts).
+//   component, by design. `<Component />` is a component only when
+//   `options.isComponent` claims the name — the MDX gate (docs/prd-mdx.md).
+//   Without it, every `<` here means exactly what it always did, which is
+//   how turning MDX on cannot change a document that never asked for it.
+//   Block position only in M1; see `ComponentInline` in ast.ts.
 import type {
   BlockNode,
+  ComponentBlock,
   Document,
   InlineNode,
   ListBlock,
@@ -33,6 +37,11 @@ import type {
   ParseOptions,
   TableAlign,
 } from './ast.js';
+import { closeBrace, scanTag } from './tags.js';
+import type { ScannedTag } from './tags.js';
+
+/** Nothing is a component unless the caller says so. */
+const NO_COMPONENTS = (): boolean => false;
 
 // --- line-level regexes, compiled once -------------------------------------
 
@@ -54,16 +63,96 @@ const RE_TABLE_DELIM_PREFIX = /^ {0,3}\|[ \t:|-]*$/;
 
 /** Would this line open something other than a paragraph? The test lazy
  *  continuation and list/quote termination share. */
-function isBlockStart(line: string): boolean {
+function isBlockStart(
+  line: string,
+  isComponent: (name: string) => boolean = NO_COMPONENTS,
+  expressions = false,
+): boolean {
   return (
     RE_ATX.test(line) ||
     RE_FENCE_OPEN.test(line) ||
     RE_HR.test(line) ||
     RE_QUOTE.test(line) ||
-    RE_LIST.test(line)
+    RE_LIST.test(line) ||
+    isComponentBlockLine(line, isComponent, expressions)
   );
 }
 
+/** A line that opens a component block, resolved — speculation does not
+ *  interrupt a paragraph. */
+function isComponentBlockLine(
+  line: string,
+  isComponent: (name: string) => boolean,
+  expressions: boolean,
+): boolean {
+  const found = componentBlockAt([line], 0, isComponent, expressions);
+  return found !== null && found !== 'incomplete';
+}
+
+/**
+ * The component block opening at `lines[at]`, if one does.
+ *
+ * A component block owns its whole line — `<Chart/>` with prose after it is
+ * a paragraph with a tag in it, which is the inline case and not this one —
+ * but it may spend several lines doing so, because a component with six
+ * props is written down the page and MDX authors expect that to work. Lines
+ * are joined until the tag closes; a blank line gives up, since a tag does
+ * not span a paragraph break.
+ *
+ * `'incomplete'` means "still arriving", which only the live tail acts on.
+ */
+function componentBlockAt(
+  lines: string[],
+  at: number,
+  isComponent: (name: string) => boolean,
+  expressions = false,
+): { tag: ScannedTag; lastLine: number } | 'incomplete' | null {
+  // The identity check is not an optimisation: `scanTag` reports a bare
+  // `<Chart` as "still arriving" before it can know whether anyone claims
+  // the name, and a document that never opted in must not have its lazy
+  // continuation changed by a line that merely looks like a tag.
+  if (isComponent === NO_COMPONENTS) return null;
+  const indent = indentOf(lines[at]);
+  if (indent > 3 || lines[at][indent] !== '<') return null;
+
+  let text = lines[at];
+  for (let j = at; j < lines.length; j += 1) {
+    if (j > at) text += `\n${lines[j]}`;
+    const tag = scanTag(text, indent, isComponent, expressions);
+    if (tag === null) return null;
+    if (tag === 'incomplete') {
+      if (j + 1 < lines.length && RE_BLANK.test(lines[j + 1])) return null;
+      continue;
+    }
+    if (tag.kind === 'close') return null;
+    return text.slice(tag.end).trim() === '' ? { tag, lastLine: j } : null;
+  }
+  return 'incomplete';
+}
+
+/** The line closing `name`, counting same-name nesting, or -1. */
+function componentCloseLine(
+  lines: string[],
+  from: number,
+  name: string,
+  isComponent: (name: string) => boolean,
+): number {
+  let depth = 0;
+  for (let i = from; i < lines.length; i += 1) {
+    const indent = indentOf(lines[i]);
+    if (indent > 3 || lines[i][indent] !== '<') continue;
+    const tag = scanTag(lines[i], indent, isComponent);
+    if (tag === null || tag === 'incomplete' || tag.name !== name) continue;
+    if (lines[i].slice(tag.end).trim() !== '') continue;
+    if (tag.kind === 'open') depth += 1;
+    else if (tag.kind === 'close') {
+      if (depth === 0) return i;
+      depth -= 1;
+    }
+  }
+  return -1;
+}
+
 /** Leading tabs advance to 4-column stops; content tabs are left alone. */
 function expandLeadingTabs(line: string): string {
   let i = 0;
@@ -93,7 +182,14 @@ export function parse(source: string, options: ParseOptions = {}): Document {
   const lines = normalized.split('\n').map(expandLeadingTabs);
   const blocks: BlockNode[] = [];
   const ranges: Array<[number, number]> = [];
-  parseBlocks(lines, partial, blocks, ranges);
+  parseBlocks(
+    lines,
+    partial,
+    blocks,
+    ranges,
+    options.isComponent ?? NO_COMPONENTS,
+    options.expressions === true,
+  );
   return {
     blocks,
     raws: ranges.map(([a, b]) => lines.slice(a, b).join('\n')),
@@ -113,6 +209,8 @@ function parseBlocks(
   tailOpen: boolean,
   out: BlockNode[],
   ranges?: Array<[number, number]>,
+  isComponent: (name: string) => boolean = NO_COMPONENTS,
+  expressions = false,
 ): void {
   let i = 0;
   const n = lines.length;
@@ -132,7 +230,7 @@ function parseBlocks(
     para.length = 0;
     paraStart = -1;
     // the paragraph owns the live tail iff its last line is the document's
-    const children = parseInline(text, tailOpen && end === n);
+    const children = parseInline(text, tailOpen && end === n, expressions);
     if (children.length > 0)
       commit({ type: 'paragraph', children }, start, end);
   };
@@ -166,7 +264,7 @@ function parseBlocks(
           {
             type: 'heading',
             depth: setext[1][0] === '=' ? 1 : 2,
-            children: parseInline(text, false),
+            children: parseInline(text, false, expressions),
           },
           start,
           i + 1,
@@ -203,7 +301,7 @@ function parseBlocks(
         {
           type: 'heading',
           depth: atx[1].length,
-          children: parseInline(atx[2] ?? '', held),
+          children: parseInline(atx[2] ?? '', held, expressions),
         },
         i,
         i + 1,
@@ -248,6 +346,69 @@ function parseBlocks(
       continue;
     }
 
+    // A component standing where a paragraph would (docs/prd-mdx.md). Gated
+    // on `isComponent`, so a document that never opted in never gets here.
+    const component = componentBlockAt(lines, i, isComponent, expressions);
+    if (component === 'incomplete') {
+      // A tag still arriving: hold it back rather than flash `<Cha` on the
+      // screen, the way a half-arrived link is held. Only the live tail may
+      // do this — anywhere else the tag is simply never going to close.
+      if (tailOpen) {
+        flushPara(i);
+        i = n;
+        continue;
+      }
+    } else if (component) {
+      const { tag, lastLine } = component;
+      flushPara(i);
+      const start = i;
+      const node = (children: BlockNode[]): ComponentBlock => ({
+        type: 'component',
+        name: tag.name,
+        attributes: tag.attributes,
+        children,
+      });
+
+      if (tag.kind === 'self') {
+        i = lastLine + 1;
+        commit(node([]), start, i);
+        continue;
+      }
+
+      const closeAt = componentCloseLine(
+        lines,
+        lastLine + 1,
+        tag.name,
+        isComponent,
+      );
+      if (closeAt !== -1) {
+        const children: BlockNode[] = [];
+        parseBlocks(
+          lines.slice(lastLine + 1, closeAt),
+          tailOpen && closeAt >= n,
+          children,
+          undefined,
+          isComponent,
+          expressions,
+        );
+        i = closeAt + 1;
+        commit(node(children), start, i);
+        continue;
+      }
+
+      // Open, with no close yet. While the document is still arriving that
+      // is the ordinary state of an element being typed: hold the tag and
+      // let the children render as the markdown they are, so the reader sees
+      // the prose rather than nothing. Mounting the component now and
+      // appending to its children instead would remount it — and lose its
+      // state — on the chunk that finally closes it.
+      if (tailOpen) {
+        i = lastLine + 1;
+        continue;
+      }
+      // Final document, never closed: the tag is text, so fall through.
+    }
+
     const quote = RE_QUOTE.exec(line);
     if (quote) {
       flushPara(i);
@@ -266,7 +427,7 @@ function parseBlocks(
         }
         if (
           !RE_BLANK.test(l) &&
-          !isBlockStart(l) &&
+          !isBlockStart(l, isComponent, expressions) &&
           inner.length > 0 &&
           !RE_BLANK.test(inner[inner.length - 1])
         ) {
@@ -277,7 +438,14 @@ function parseBlocks(
         break;
       }
       const children: BlockNode[] = [];
-      parseBlocks(inner, tailOpen && i === n, children);
+      parseBlocks(
+        inner,
+        tailOpen && i === n,
+        children,
+        undefined,
+        isComponent,
+        expressions,
+      );
       if (children.length > 0) commit({ type: 'quote', children }, start, i);
       continue;
     }
@@ -288,7 +456,7 @@ function parseBlocks(
     if (list && !(para.length > 0 && !list[4]) && !(held && !list[4])) {
       flushPara(i);
       const start = i;
-      const block = parseList(lines, i, tailOpen);
+      const block = parseList(lines, i, tailOpen, isComponent, expressions);
       i = block.end;
       commit(block.list, start, i);
       continue;
@@ -323,7 +491,12 @@ function parseBlocks(
         const rows: InlineNode[][][] = [];
         while (i < n) {
           const l = lines[i];
-          if (RE_BLANK.test(l) || !l.includes('|') || isBlockStart(l)) break;
+          if (
+            RE_BLANK.test(l) ||
+            !l.includes('|') ||
+            isBlockStart(l, isComponent, expressions)
+          )
+            break;
           rows.push(
             normalizeRow(splitRow(l), align.length, tailOpen && i === n - 1),
           );
@@ -395,6 +568,8 @@ function parseList(
   lines: string[],
   from: number,
   tailOpen: boolean,
+  isComponent: (name: string) => boolean = NO_COMPONENTS,
+  expressions = false,
 ): ParsedList {
   const n = lines.length;
   const first = RE_LIST.exec(lines[from]);
@@ -452,7 +627,11 @@ function parseList(
         i += 1;
         continue;
       }
-      if (pendingBlanks === 0 && !isBlockStart(l) && !RE_BLANK.test(l)) {
+      if (
+        pendingBlanks === 0 &&
+        !isBlockStart(l, isComponent, expressions) &&
+        !RE_BLANK.test(l)
+      ) {
         inner.push(l); // lazy paragraph continuation
         i += 1;
         continue;
@@ -470,7 +649,14 @@ function parseList(
     }
 
     const children: BlockNode[] = [];
-    parseBlocks(inner, tailOpen && i >= n, children);
+    parseBlocks(
+      inner,
+      tailOpen && i >= n,
+      children,
+      undefined,
+      isComponent,
+      expressions,
+    );
     items.push({ checked, children });
   }
 
@@ -603,7 +789,11 @@ function classify(ch: string | undefined): 'ws' | 'punct' | 'other' {
  * Parse inline markdown. `atDocEnd` marks text whose end is the live end of
  * a streaming document — only then do the implicit-close rules apply.
  */
-export function parseInline(text: string, atDocEnd: boolean): InlineNode[] {
+export function parseInline(
+  text: string,
+  atDocEnd: boolean,
+  expressions = false,
+): InlineNode[] {
   const items: Item[] = [];
   let buf = '';
 
@@ -700,6 +890,31 @@ export function parseInline(text: string, atDocEnd: boolean): InlineNode[] {
       continue;
     }
 
+    // `{expr}` in the prose — rung 2 only, so a brace in an ordinary
+    // document is the character it has always been.
+    if (expressions && ch === '{') {
+      const end = closeBrace(text, i);
+      if (end === -1) {
+        // Still arriving: hold the rest of the line back rather than show
+        // half an expression. In a final document it is just text.
+        if (atDocEnd) {
+          flushText();
+          i = len;
+          continue;
+        }
+        buf += ch;
+        i += 1;
+        continue;
+      }
+      flushText();
+      items.push({
+        kind: 'node',
+        node: { type: 'expression', src: text.slice(i + 1, end - 1).trim() },
+      });
+      i = end;
+      continue;
+    }
+
     if (ch === '<') {
       const rest = text.slice(i);
       const auto = RE_AUTOLINK.exec(rest) ?? RE_AUTOEMAIL.exec(rest);

package/src/markdown/spans.ts

@@ -135,6 +135,10 @@ export function plainTextOf(nodes: InlineNode[]): string {
       case 'break':
         out += '\n';
         break;
+      case 'expression':
+        // Resolved to text before rendering (`<Markdown>`'s `scope`), so a
+        // node reaching here was never evaluated and has no text to give.
+        break;
       default:
         out += plainTextOf(node.children);
     }