@react-x11/components 0.8.0 → 0.10.0

package/src/rich-text-editor/keys.ts

@@ -0,0 +1,228 @@
+// Stable identities for the blocks of a document, carried across edits.
+//
+// React needs a key per rendered block, and the three obvious ones are all
+// wrong for an editor:
+//
+//   - **an index** shifts every block after an inserted paragraph, so Enter
+//     at the top of a long document re-renders — and re-lays-out — every
+//     paragraph below it;
+//   - **a position** shifts on every keystroke, for the same reason;
+//   - **a node's identity** changes whenever its content does, because
+//     ProseMirror's nodes are immutable, so typing would remount the very
+//     paragraph being typed in and throw its layout cache away.
+//
+// What survives an edit is what ProseMirror's own view keys its DOM on: a
+// node's *place*, mapped through the transaction. A block whose start maps
+// cleanly keeps its key; one whose opening token the transaction deleted —
+// the second half of a join — loses it, and a block nobody had before (the
+// second half of a split) gets a fresh one. When there is no mapping — a
+// whole state handed in from outside, the controlled-state rung — the node
+// objects that survived are matched by identity instead, which is the other
+// thing ProseMirror's structural sharing guarantees.
+//
+// Pure: no React, no react-x11. The component asks it three questions — the
+// key at a position, the position of a key, the node under a key — and
+// `test/rich-text-editor-model.test.ts` asks it the rest.
+import type { Node as PMNode } from 'prosemirror-model';
+import { Mapping } from 'prosemirror-transform';
+import type { Mappable } from 'prosemirror-transform';
+import { spliceAll } from '../internal/splice.js';
+
+/** A block: its key, where it starts, and the node it is. */
+interface Entry {
+  key: string;
+  pos: number;
+  node: PMNode;
+}
+
+export class BlockKeys {
+  private counter = 0;
+  /** Every block, in document order — which is the order of their starts,
+   *  so a position is found by bisection. */
+  private entries: Entry[] = [];
+  private byKey = new Map<string, Entry>();
+  /** The document the entries describe. */
+  private doc: PMNode | null = null;
+
+  constructor(doc: PMNode) {
+    this.update(doc, null);
+  }
+
+  /** How many blocks the document has — every non-inline node but the
+   *  document itself. */
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** The key of the block that starts at `pos`, if one does. */
+  keyAt(pos: number): string | undefined {
+    const entries = this.entries;
+    let lo = 0;
+    let hi = entries.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      const at = entries[mid].pos;
+      if (at === pos) return entries[mid].key;
+      if (at < pos) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return undefined;
+  }
+
+  /** Where the block under `key` starts now. */
+  posOf(key: string): number | undefined {
+    return this.byKey.get(key)?.pos;
+  }
+
+  /** The node the block under `key` is now. */
+  nodeOf(key: string): PMNode | undefined {
+    return this.byKey.get(key)?.node;
+  }
+
+  /**
+   * Re-key for a new document. `mapping` is the transaction (or the run of
+   * transactions) that produced it from the one the keys were last built
+   * for; null when nothing knows how the two relate.
+   *
+   * The top-level blocks the two documents share at either end — the same
+   * node objects, which is what ProseMirror's structural sharing leaves
+   * everywhere an edit did not reach — keep their keys, and the blocks
+   * after the edit only move. What lies between is keyed as the whole
+   * document used to be, on every keystroke: a mapped start first, then a
+   * surviving node, then a fresh key. So a keystroke costs the block it
+   * lands in plus a pass that adds a number to each block after it, where
+   * it cost a walk of the document and three maps built from scratch —
+   * six milliseconds a key in a 2 MB document.
+   */
+  update(doc: PMNode, mapping: Mappable | null): void {
+    const was = this.doc;
+    this.doc = doc;
+    // the top-level children the two documents share at either end
+    let head = 0;
+    let tail = 0;
+    if (was) {
+      const shared = Math.min(was.childCount, doc.childCount);
+      while (head < shared && was.child(head) === doc.child(head)) head++;
+      while (
+        tail < shared - head &&
+        was.child(was.childCount - 1 - tail) ===
+          doc.child(doc.childCount - 1 - tail)
+      ) {
+        tail++;
+      }
+    }
+    let from = 0; // where the changed children start, in both documents
+    for (let i = 0; i < head; i++) from += doc.child(i).nodeSize;
+    let wasTo = from;
+    if (was) {
+      for (let i = head; i < was.childCount - tail; i++) {
+        wasTo += was.child(i).nodeSize;
+      }
+    }
+    let to = from;
+    for (let i = head; i < doc.childCount - tail; i++) {
+      to += doc.child(i).nodeSize;
+    }
+    const entries = this.entries;
+    const first = this._firstAtOrAfter(from);
+    const end = this._firstAtOrAfter(wasTo);
+    const old = entries.slice(first, end);
+
+    // 1. Where each old block's start went — nowhere, when nothing in the
+    // mapping moves a position: a mark added or taken off, an attribute set.
+    // Bold over a whole document is one step a paragraph, and mapping every
+    // block through every one of them was a third of the command.
+    const carried = new Map<number, string>();
+    if (mapping && !movesNothing(mapping)) {
+      for (const { pos, key } of old) {
+        const result = mapping.mapResult(pos, 1);
+        // the token after the start is the block's own opening — gone means
+        // the block is gone, merged into whatever preceded it
+        if (result.deletedAfter) continue;
+        if (!carried.has(result.pos)) carried.set(result.pos, key);
+      }
+    } else if (mapping) {
+      for (const { pos, key } of old) {
+        if (!carried.has(pos)) carried.set(pos, key);
+      }
+    }
+    // 2. Which old node objects are still here, for when nothing mapped.
+    const byNode = new Map<PMNode, string[]>();
+    const carriedKeys = new Set(carried.values());
+    for (const { key, node } of old) {
+      if (carriedKeys.has(key)) continue;
+      const list = byNode.get(node);
+      if (list) list.push(key);
+      else byNode.set(node, [key]);
+    }
+    for (const { key } of old) this.byKey.delete(key);
+
+    // 3. The changed children, keyed.
+    const fresh: Entry[] = [];
+    const used = new Set<string>();
+    const visit = (node: PMNode, pos: number): boolean => {
+      if (node.isInline) return false;
+      let key = carried.get(pos);
+      if (key !== undefined && used.has(key)) key = undefined;
+      if (key === undefined) {
+        const list = byNode.get(node);
+        while (list && list.length > 0) {
+          const candidate = list.shift()!;
+          if (!used.has(candidate)) {
+            key = candidate;
+            break;
+          }
+        }
+      }
+      if (key === undefined) key = `b${(this.counter++).toString(36)}`;
+      used.add(key);
+      const entry = { key, pos, node };
+      fresh.push(entry);
+      this.byKey.set(key, entry);
+      // a textblock's children are inline: nothing below it has a key
+      return !node.isTextblock;
+    };
+    let at = from;
+    for (let i = head; i < doc.childCount - tail; i++) {
+      const child = doc.child(i);
+      if (visit(child, at)) {
+        const base = at + 1;
+        child.descendants((node, pos) => visit(node, base + pos));
+      }
+      at += child.nodeSize;
+    }
+
+    // 4. The blocks after them moved, and are otherwise as they were.
+    const shift = to - wasTo;
+    if (shift !== 0) {
+      for (let i = end; i < entries.length; i++) entries[i].pos += shift;
+    }
+    spliceAll(entries, first, end - first, fresh);
+  }
+
+  /** The index of the first block starting at or after `pos`. */
+  private _firstAtOrAfter(pos: number): number {
+    const entries = this.entries;
+    let lo = 0;
+    let hi = entries.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (entries[mid].pos < pos) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+}
+
+/** Whether a mapping is made only of steps that move no position. */
+function movesNothing(mapping: Mappable): boolean {
+  if (!(mapping instanceof Mapping)) return false;
+  for (const map of mapping.maps) {
+    let moved = false;
+    map.forEach(() => {
+      moved = true;
+    });
+    if (moved) return false;
+  }
+  return true;
+}

package/src/rich-text-editor/look.ts

@@ -0,0 +1,427 @@
+// What the document looks like: the theme, read once per render, into the
+// styles every block and mark is drawn with.
+//
+// The numbers are `<Markdown>`'s (src/markdown/index.ts, `deriveLook`) — the
+// heading scales, the block gap, the chip behind inline code — and a fenced
+// block's whole look comes from the same shared module both use
+// (`src/codeblock/`). A component never imports another, so the two are kept
+// in step by value: a note edited here and rendered there should look like
+// one document, and a change to one of these numbers belongs in both.
+//
+// A schema this file has never heard of still gets a look. A node or mark is
+// recognised by name first (the reference schema's, then TipTap's), and then
+// by the tag its own `toDOM` writes: an unknown node that says `['h2', 0]` is
+// a second-level heading, an unknown mark that says `['u', 0]` underlines, and
+// a `style` attribute on either is read for the few properties text can
+// carry. The app's `markStyles` has the last word.
+import { tint } from 'react-x11/style';
+import type { Mark, Node as PMNode } from 'prosemirror-model';
+
+import { codeBlockLook, codeBlockRuns } from '../codeblock/index.js';
+import type { CodeBlockLook } from '../codeblock/index.js';
+import type { Language } from '../code-language/index.js';
+import type { InlineLook, RunStyle } from './inline.js';
+
+/** How a mark looks: a fixed style, or one worked out from what it covers. */
+export type MarkStyle = RunStyle | ((mark: Mark, under: RunStyle) => RunStyle);
+
+export interface LookOptions {
+  fontSize?: number;
+  fontFamily?: string;
+  monoFamily?: string;
+  markStyles?: Readonly<Record<string, MarkStyle>>;
+  resolveLanguage?: (tag: string) => Language | null;
+  highlight?: boolean;
+  /** A disabled editor: the document is set in the muted ink. (react-x11
+   *  styles have no opacity to fade a subtree with.) */
+  dim?: boolean;
+}
+
+/** Where a textblock sits, as far as its look is concerned. */
+export interface BlockContext {
+  /** Inside a blockquote: set in the muted ink, as `<Markdown>` sets it. */
+  quote: boolean;
+  /** A table's header row. */
+  header: boolean;
+}
+
+export interface EditorLook {
+  size: number;
+  family: string;
+  mono: string;
+  text: string;
+  muted: string;
+  link: string;
+  accent: string;
+  accentText: string;
+  border: string;
+  background: string;
+  surface: string;
+  selection: string;
+  /** The selection while focus is elsewhere — still there, but quieter. */
+  selectionBlurred: string;
+  caret: string;
+  codeBg: string;
+  headerBg: string;
+  highlight: string;
+  radius: number;
+  blockGap: number;
+  headingScales: readonly number[];
+  code: CodeBlockLook;
+  /** Two looks with the same key draw identically — the render cache's epoch. */
+  key: string;
+  /** A textblock's inline look. Cached: the same node type in the same
+   *  context is the same object, which is what lets a block that did not
+   *  change skip its layout. */
+  inline(node: PMNode, context: BlockContext): InlineLook;
+}
+
+const HEADING_SCALES = [1.75, 1.4, 1.2, 1.05, 0.95, 0.85] as const;
+
+type Role =
+  | 'strong'
+  | 'em'
+  | 'code'
+  | 'strike'
+  | 'link'
+  | 'underline'
+  | 'highlight'
+  | 'sub'
+  | 'sup'
+  | 'textStyle';
+
+const MARK_ROLES: Record<string, Role> = {
+  strong: 'strong',
+  bold: 'strong',
+  b: 'strong',
+  em: 'em',
+  italic: 'em',
+  i: 'em',
+  code: 'code',
+  strike: 'strike',
+  strikethrough: 'strike',
+  s: 'strike',
+  del: 'strike',
+  link: 'link',
+  a: 'link',
+  underline: 'underline',
+  u: 'underline',
+  highlight: 'highlight',
+  mark: 'highlight',
+  subscript: 'sub',
+  sub: 'sub',
+  superscript: 'sup',
+  sup: 'sup',
+  textStyle: 'textStyle',
+  span: 'textStyle',
+};
+
+/** The tag and attributes a node's or mark's `toDOM` writes, if it writes an
+ *  array — the one shape readable without a DOM. */
+export function domTagOf(
+  spec: { toDOM?: unknown } | undefined,
+  value: unknown,
+): { tag: string; attrs: Record<string, unknown> } | null {
+  const toDOM = spec?.toDOM as
+    ((v: unknown, inline?: boolean) => unknown) | undefined;
+  if (typeof toDOM !== 'function') return null;
+  try {
+    const out = toDOM(value, true);
+    if (!Array.isArray(out) || typeof out[0] !== 'string') return null;
+    const second = out[1];
+    const attrs =
+      second && typeof second === 'object' && !Array.isArray(second)
+        ? (second as Record<string, unknown>)
+        : {};
+    return { tag: out[0].replace(/^.*\s/, '').toLowerCase(), attrs };
+  } catch {
+    // a `toDOM` that builds real DOM nodes has no document to build them in
+    return null;
+  }
+}
+
+/**
+ * The part of a CSS declaration block text can carry — colour, background,
+ * weight, style, decoration, family, pixel size. What a decoration's
+ * `style` attribute and an unknown mark's `toDOM` attributes are read
+ * through; everything else in them is ignored.
+ */
+export function styleFromCSS(css: string, under: RunStyle): RunStyle {
+  const out: RunStyle = {};
+  for (const decl of css.split(';')) {
+    const colon = decl.indexOf(':');
+    if (colon <= 0) continue;
+    const name = decl.slice(0, colon).trim().toLowerCase();
+    const value = decl.slice(colon + 1).trim();
+    if (!value) continue;
+    switch (name) {
+      case 'color':
+        out.color = value;
+        break;
+      case 'background':
+      case 'background-color':
+        out.bg = value;
+        break;
+      case 'font-weight': {
+        const n = Number(value);
+        if (value === 'bold' || value === 'bolder' || n >= 600)
+          out.weight = 700;
+        else if (value === 'normal' || (Number.isFinite(n) && n < 600))
+          out.weight = 'normal';
+        break;
+      }
+      case 'font-style':
+        out.style =
+          value === 'italic' || value === 'oblique' ? 'italic' : 'normal';
+        break;
+      case 'text-decoration':
+      case 'text-decoration-line':
+        if (/line-through/.test(value))
+          out.strike = out.color ?? under.color ?? 'currentColor';
+        if (/underline/.test(value))
+          out.underline = out.color ?? under.color ?? 'currentColor';
+        break;
+      case 'font-family':
+        out.family = value;
+        break;
+      case 'font-size': {
+        const px = /^(\d+(?:\.\d+)?)px$/.exec(value);
+        if (px) out.size = Number(px[1]);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+function str(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value ? value : fallback;
+}
+
+/** The first word of a code block's info string — its language. */
+function languageOf(node: PMNode): string {
+  const info = node.attrs.params ?? node.attrs.language ?? '';
+  return String(info).trim().split(/\s/, 1)[0].toLowerCase();
+}
+
+/** What kind of textblock this is, for its look: its name, then its tag. */
+function blockKind(node: PMNode): {
+  kind: 'paragraph' | 'heading' | 'code';
+  level: number;
+} {
+  const name = node.type.name;
+  if (node.type.spec.code || name === 'code_block' || name === 'codeBlock') {
+    return { kind: 'code', level: 0 };
+  }
+  if (name === 'heading') {
+    return { kind: 'heading', level: Number(node.attrs.level ?? 1) };
+  }
+  const dom = domTagOf(node.type.spec, node);
+  const h = dom && /^h([1-6])$/.exec(dom.tag);
+  if (h) return { kind: 'heading', level: Number(h[1]) };
+  if (dom?.tag === 'pre') return { kind: 'code', level: 0 };
+  return { kind: 'paragraph', level: 0 };
+}
+
+export function deriveLook(
+  theme: Record<string, unknown>,
+  options: LookOptions,
+): EditorLook {
+  const muted = str(theme.textMuted, '#7f8c8d');
+  const text = options.dim ? muted : str(theme.text, '#2d3436');
+  const accent = str(theme.accent, '#2980b9');
+  const accentText = str(theme.accentText, '#ffffff');
+  const link = str(theme.link, accent);
+  const border = str(theme.border, '#b2bec3');
+  const background = str(theme.background, '#ffffff');
+  const surface = str(theme.surface, background);
+  const size = options.fontSize ?? Number(theme.fontSize ?? 14);
+  const family = options.fontFamily ?? str(theme.fontFamily, 'sans-serif');
+  const mono = options.monoFamily ?? 'monospace';
+  const selection = str(theme.selection, tint(accent, 0.35));
+  const caret = str(theme.caret, text);
+  const code = codeBlockLook(theme, { baseSize: size, monoFamily: mono });
+  const codeBg = tint(text, 0.08);
+  const highlight = tint('#f5c400', 0.45);
+  const radius = Number(theme.radius ?? 6);
+
+  const markStyles = options.markStyles;
+  const resolveLanguage = options.resolveLanguage;
+  const highlightCode = options.highlight !== false;
+
+  const markStyle = (mark: Mark, under: RunStyle): RunStyle => {
+    const role =
+      MARK_ROLES[mark.type.name] ??
+      MARK_ROLES[domTagOf(mark.type.spec, mark)?.tag ?? ''];
+    let out: RunStyle = {};
+    switch (role) {
+      case 'strong':
+        out = { weight: 700 };
+        break;
+      case 'em':
+        out = { style: 'italic' };
+        break;
+      case 'code':
+        out = {
+          family: mono,
+          size: Math.round((under.size ?? size) * 0.9),
+          color: under.color === muted ? muted : text,
+          bg: codeBg,
+        };
+        break;
+      case 'strike':
+        out = { strike: under.color ?? text };
+        break;
+      case 'link': {
+        const href = mark.attrs.href;
+        out = {
+          color: link,
+          underline: link,
+          href: typeof href === 'string' ? href : null,
+        };
+        break;
+      }
+      case 'underline':
+        out = { underline: under.color ?? text };
+        break;
+      case 'highlight':
+        out = { bg: str(mark.attrs.color, highlight) };
+        break;
+      case 'sub':
+      case 'sup':
+        out = { size: Math.round((under.size ?? size) * 0.8) };
+        break;
+      case 'textStyle': {
+        const a = mark.attrs as Record<string, unknown>;
+        if (typeof a.color === 'string') out.color = a.color;
+        if (typeof a.fontFamily === 'string') out.family = a.fontFamily;
+        if (typeof a.fontSize === 'string') {
+          const px = /^(\d+(?:\.\d+)?)px$/.exec(a.fontSize);
+          if (px) out.size = Number(px[1]);
+        }
+        break;
+      }
+    }
+    // an unknown mark's own `style` attribute, and a known one's too
+    const dom = domTagOf(mark.type.spec, mark);
+    if (dom && typeof dom.attrs.style === 'string') {
+      out = { ...out, ...styleFromCSS(dom.attrs.style, { ...under, ...out }) };
+    }
+    const custom = markStyles?.[mark.type.name];
+    if (custom) {
+      const merged = { ...under, ...out };
+      out = {
+        ...out,
+        ...(typeof custom === 'function' ? custom(mark, merged) : custom),
+      };
+    }
+    return out;
+  };
+
+  const atom = (node: PMNode): { text: string; style?: RunStyle } => {
+    const name = node.type.name;
+    if (
+      name === 'hard_break' ||
+      name === 'hardBreak' ||
+      domTagOf(node.type.spec, node)?.tag === 'br'
+    ) {
+      return { text: '\n' };
+    }
+    if (name === 'image') {
+      const src = String(node.attrs.src ?? '');
+      const label =
+        str(node.attrs.alt, '') ||
+        str(node.attrs.title, '') ||
+        src.split(/[/\\]/).pop() ||
+        'image';
+      return { text: label, style: { color: muted, bg: codeBg } };
+    }
+    const leaf = node.type.spec.leafText?.(node) ?? '';
+    return { text: leaf || name, style: { color: muted, bg: codeBg } };
+  };
+
+  const cache = new Map<string, InlineLook>();
+  const inline = (node: PMNode, context: BlockContext): InlineLook => {
+    const { kind, level } = blockKind(node);
+    const lang = kind === 'code' ? languageOf(node) : '';
+    const key = `${node.type.name}|${kind}|${level}|${lang}|${context.quote ? 'q' : ''}${context.header ? 'h' : ''}`;
+    const hit = cache.get(key);
+    if (hit) return hit;
+    const ink = context.quote ? muted : text;
+    let base: RunStyle;
+    if (kind === 'heading') {
+      const scale = HEADING_SCALES[Math.max(1, Math.min(6, level)) - 1];
+      base = {
+        family,
+        size: Math.round(size * scale),
+        weight: 700,
+        color: ink,
+      };
+    } else if (kind === 'code') {
+      base = { family: code.family, size: code.size, color: code.color };
+    } else {
+      base = {
+        family,
+        size,
+        color: ink,
+        ...(context.header ? { weight: 700 } : null),
+      };
+    }
+    const look: InlineLook = {
+      base,
+      mark: markStyle,
+      atom,
+      ...(kind === 'code'
+        ? {
+            code: (source: string) =>
+              codeBlockRuns(source, code, {
+                lang,
+                highlight: highlightCode,
+                ...(resolveLanguage ? { resolveLanguage } : null),
+              }),
+          }
+        : null),
+    };
+    cache.set(key, look);
+    return look;
+  };
+
+  return {
+    size,
+    family,
+    mono,
+    text,
+    muted,
+    link,
+    accent,
+    accentText,
+    border,
+    background,
+    surface,
+    selection,
+    selectionBlurred: tint(text, 0.14),
+    caret,
+    codeBg,
+    headerBg: tint(text, 0.05),
+    highlight,
+    radius,
+    blockGap: Math.round(size * 0.7),
+    headingScales: HEADING_SCALES,
+    code,
+    key: [
+      text,
+      muted,
+      link,
+      accent,
+      border,
+      background,
+      size,
+      family,
+      mono,
+      selection,
+      caret,
+      highlightCode,
+    ].join('|'),
+    inline,
+  };
+}