@react-x11/components 0.5.0 → 0.7.0

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);
     }

package/src/markdown/tags.ts

@@ -0,0 +1,240 @@
+// Scanning a JSX-shaped tag, for the MDX direction (docs/prd-mdx.md).
+//
+// Deliberately not a JavaScript parser, and deliberately not an HTML one.
+// What it recognises is `<Name …>`, `</Name>` and `<Name … />` where `Name`
+// is a component the *caller* claims — a tag whose name nobody claims is not
+// a tag, it is the literal text it has always been. That one rule is what
+// lets this exist inside a parser whose documents are full of `<box>` and
+// `{braces}` without changing what any of them mean.
+//
+// Attribute values are read at parse time. A quoted string is a string, a
+// bare name is `true`, and `{…}` is **JSON** — until the caller passes
+// `expressions`, when a brace that is not JSON is kept as *source* for
+// someone else to compile (docs/prd-mdx.md, M2). Nothing is evaluated here
+// on either rung: this file finds where an expression ends, and holding it
+// as text is what lets one parse be rendered against two scopes.
+//
+// Finding where it ends is the only part that has to know about JavaScript,
+// and it knows the least it can: strings (including template literals and
+// their `${…}` holes), comments, and bracket depth. It never parses an
+// expression, the way `src/qml/parse.ts` never does.
+import type { AttributeValue } from './ast.js';
+
+/** A tag's shape. `end` is the index just past its `>`. */
+export interface ScannedTag {
+  kind: 'open' | 'close' | 'self';
+  name: string;
+  attributes: Record<string, AttributeValue>;
+  end: number;
+}
+
+/**
+ * What a scan can say. `null` is "not a tag, never will be"; `'incomplete'`
+ * is "could still become one if more text arrives", which is what a
+ * streaming document needs in order to hold the tail back rather than
+ * flashing `<Cha` on the screen.
+ */
+export type ScanResult = ScannedTag | 'incomplete' | null;
+
+/** A component name, dotted paths included. Deliberately not HTML's. */
+const RE_NAME = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/;
+/** An attribute name: JSX's, plus the `-` and `:` that data attributes use. */
+const RE_ATTR = /^[A-Za-z_$][\w$:-]*/;
+
+function isSpace(ch: string | undefined): boolean {
+  return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
+}
+
+/**
+ * The index just past the closing quote of the string literal starting at
+ * `from`, or -1 if the text ends first. A template literal's `${…}` holes
+ * are walked as expressions, so a brace or a quote inside one counts for
+ * nothing outside it.
+ */
+function skipString(text: string, from: number): number {
+  const quote = text[from];
+  let i = from + 1;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    if (quote === '`' && ch === '$' && text[i + 1] === '{') {
+      const end = closeBrace(text, i + 1);
+      if (end === -1) return -1;
+      i = end;
+      continue;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/** The index just past a `//` or block comment starting at `from`. */
+function skipComment(text: string, from: number): number {
+  if (text[from + 1] === '/') {
+    const nl = text.indexOf('\n', from);
+    return nl === -1 ? text.length : nl;
+  }
+  const end = text.indexOf('*/', from + 2);
+  return end === -1 ? -1 : end + 2;
+}
+
+/**
+ * The index just past the `}` that closes the `{` at `from`, or -1 if the
+ * text ends first — the one piece here that has to know JavaScript's shape.
+ * Strings, template holes and comments are stepped over whole, so a brace
+ * inside any of them closes nothing.
+ */
+export function closeBrace(text: string, from: number): number {
+  let depth = 0;
+  let i = from;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const end = skipString(text, i);
+      if (end === -1) return -1;
+      i = end;
+      continue;
+    }
+    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
+      const end = skipComment(text, i);
+      if (end === -1) return -1;
+      i = end;
+      continue;
+    }
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/**
+ * Scan the tag starting at `text[at]`, which must be `<`.
+ *
+ * `isComponent` is asked before anything else is parsed, so a `<` that opens
+ * nothing anybody claims costs one regex and a lookup.
+ *
+ * `expressions` is the second rung: with it, a `{…}` that is not JSON is
+ * kept as source instead of making the tag unreadable, and `{...spread}`
+ * becomes an attribute. Without it — the default — neither exists, and a
+ * document can only hand a component data it wrote down literally.
+ */
+export function scanTag(
+  text: string,
+  at: number,
+  isComponent: (name: string) => boolean,
+  expressions = false,
+): ScanResult {
+  if (text[at] !== '<') return null;
+  let i = at + 1;
+
+  const close = text[i] === '/';
+  if (close) i += 1;
+
+  const nameMatch = RE_NAME.exec(text.slice(i));
+  if (!nameMatch) {
+    // `<` at the very end could still grow into a tag; anything else is text.
+    return i >= text.length ? 'incomplete' : null;
+  }
+  const name = nameMatch[0];
+  i += name.length;
+  // A name that reaches the end may still be growing — `<Cha` could be
+  // `<Chart`, and a document that decided too early would flash the wrong
+  // thing. Only ask about names we have all of.
+  if (i >= text.length) return 'incomplete';
+  if (!isComponent(name)) return null;
+
+  if (close) {
+    while (isSpace(text[i])) i += 1;
+    if (i >= text.length) return 'incomplete';
+    if (text[i] !== '>') return null;
+    return { kind: 'close', name, attributes: {}, end: i + 1 };
+  }
+
+  const attributes: Record<string, AttributeValue> = {};
+  let spreads = 0;
+  for (;;) {
+    const hadSpace = isSpace(text[i]);
+    while (isSpace(text[i])) i += 1;
+    if (i >= text.length) return 'incomplete';
+
+    if (text[i] === '>') return { kind: 'open', name, attributes, end: i + 1 };
+    if (text[i] === '/') {
+      i += 1;
+      while (isSpace(text[i])) i += 1;
+      if (i >= text.length) return 'incomplete';
+      if (text[i] !== '>') return null;
+      return { kind: 'self', name, attributes, end: i + 1 };
+    }
+
+    // `<Chart data="x"height={2}>` is a typo, not a tag.
+    if (!hadSpace) return null;
+
+    // `{...props}` — an attribute with no name. Its key records where it
+    // sat among the named ones, because a spread after `height` overrides
+    // it and one before it does not; `...` cannot collide with a real
+    // attribute name, which must start with a letter.
+    if (text[i] === '{') {
+      if (!expressions) return null;
+      const end = closeBrace(text, i);
+      if (end === -1) return 'incomplete';
+      const inner = text.slice(i + 1, end - 1).trim();
+      if (!inner.startsWith('...')) return null;
+      attributes[`...${spreads}`] = {
+        kind: 'expression',
+        src: inner.slice(3).trim(),
+      };
+      spreads += 1;
+      i = end;
+      continue;
+    }
+
+    const attr = RE_ATTR.exec(text.slice(i));
+    if (!attr) return null;
+    const key = attr[0];
+    i += key.length;
+    if (i >= text.length) return 'incomplete';
+
+    if (text[i] !== '=') {
+      // A bare attribute is `true`, as it is in JSX.
+      attributes[key] = { kind: 'literal', value: true };
+      continue;
+    }
+    i += 1;
+    if (i >= text.length) return 'incomplete';
+
+    const ch = text[i];
+    if (ch === '"' || ch === "'") {
+      const end = text.indexOf(ch, i + 1);
+      if (end === -1) return 'incomplete';
+      attributes[key] = { kind: 'literal', value: text.slice(i + 1, end) };
+      i = end + 1;
+      continue;
+    }
+    if (ch === '{') {
+      const end = closeBrace(text, i);
+      if (end === -1) return 'incomplete';
+      const src = text.slice(i + 1, end - 1);
+      try {
+        attributes[key] = { kind: 'literal', value: JSON.parse(src) };
+      } catch {
+        // Not JSON. On the rung that compiles, that is an expression and it
+        // is kept as source; on the rung that does not, it is unreadable and
+        // the tag is text.
+        if (!expressions) return null;
+        attributes[key] = { kind: 'expression', src: src.trim() };
+      }
+      i = end;
+      continue;
+    }
+    // An unquoted value is HTML's, not JSX's.
+    return null;
+  }
+}

package/src/richtext/node.ts

@@ -418,8 +418,13 @@ export class RichTextNode extends Node {
     //    arrive from the surface above; `textRangeRects` is what a custom
     //    element and core's own `<text>` both fill, so they cannot drift.
     const range = this.selectionRange;
-    if (range && range.end > range.start) {
-      ctx.fillStyle = this.selectionColor;
+    // The colour is the condition, not just the range: core types it
+    // `string | null` and defines it as what to fill the rectangles with
+    // *while a selection is set*, so a null one is "nothing to draw"
+    // rather than a band in the default ink.
+    const selectionColor = this.selectionColor;
+    if (selectionColor && range && range.end > range.start) {
+      ctx.fillStyle = selectionColor;
       for (const r of this.textRangeRects(range.start, range.end)) {
         ctx.fillRect(
           Math.round(r.x),