@react-x11/components 0.7.1 → 0.9.0

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

@@ -0,0 +1,347 @@
+// Long documents: only the top-level blocks near the viewport are drawn.
+//
+// The machinery is `<Tree>`'s and `<Table>`'s — the height index
+// (../internal/heights.ts), the window (../internal/window.ts) and the owed
+// reveal (../internal/scroll.ts) — laid over the document's top-level blocks
+// and keyed by their block keys (./keys.ts), so a height measured once
+// survives every edit that keeps its block. Each drawn block is in a box of
+// its own, measured after layout (./render.ts, `renderBlockRange`), and the
+// blocks outside the window are two spacers, so the scrollbar measures the
+// whole document.
+//
+// The view's geometry is laid-out text — a caret, a hit, the line an arrow
+// key moves to — so a block that is not drawn has none. The view asks this
+// window (`BlockWindow`) whether the block a position is in is drawn, and
+// when it is not, because the reader scrolled away from the caret, it has
+// the block revealed first and does what it meant to once the block is laid
+// out (./view.ts: `scrollToSelection` and `move`).
+//
+// A block is measured with the gap after it, so that the index's offsets are
+// where blocks start: the content column keeps its `gap`, and each spacer
+// gives back the one gap it stands beside.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { Node as PMNode } from 'prosemirror-model';
+import type { DrawnNode, ScrollableNode } from 'react-x11';
+
+import { RowHeights } from '../internal/heights.js';
+import type { RowKey } from '../internal/heights.js';
+import { useReveal } from '../internal/scroll.js';
+import {
+  afterLayout,
+  cancelAfterLayout,
+  cancelLater,
+  later,
+} from '../internal/timers.js';
+import type { DelayTick, LayoutTick } from '../internal/timers.js';
+import { scaleOf } from '../internal/units.js';
+import {
+  BURST_BUDGET,
+  DEFAULT_OVERSCAN,
+  DEFAULT_PREFETCH,
+  SETTLE_BUDGET,
+  useVirtualWindow,
+} from '../internal/window.js';
+import type { BlockKeys } from './keys.js';
+
+/** Top-level blocks past which `virtual: 'auto'` draws only a window of
+ *  them — `<Tree>`'s threshold, and far more than a composer ever holds. */
+export const VIRTUAL_THRESHOLD = 200;
+
+/** What the view asks of a long document's window. */
+export interface BlockWindow {
+  /** Whether top-level block `index` is drawn and laid out. */
+  drawn(index: number): boolean;
+  /** Scroll top-level block `index` into view, and so draw it; `then` runs
+   *  once it is laid out — unless the reader scrolls somewhere else first,
+   *  which drops it. */
+  reveal(index: number, then: () => void): void;
+}
+
+interface Row {
+  id: string;
+}
+
+interface Drawn {
+  node: DrawnNode;
+  at: number;
+}
+
+/** The document's top-level blocks, by key, in order. */
+function topBlocks(doc: PMNode, keys: BlockKeys): Row[] {
+  const rows: Row[] = [];
+  doc.forEach((_node, offset) => {
+    rows.push({ id: keys.keyAt(offset) ?? `p${offset}` });
+  });
+  return rows;
+}
+
+export interface BlockWindowInputs {
+  doc: PMNode;
+  keys: BlockKeys;
+  virtual: boolean | 'auto';
+  /** What a block nobody has measured is guessed at, gap included —
+   *  logical pixels, like every length here. */
+  estimate: number;
+  /** The content column's gap between blocks. */
+  gap: number;
+}
+
+export interface BlockWindowState {
+  virtualizing: boolean;
+  /** The top-level blocks to draw, `last` exclusive. */
+  first: number;
+  last: number;
+  /** The spacers before and after them — 0 for none. */
+  above: number;
+  below: number;
+  /** The scroll pane. */
+  box: { current: ScrollableNode | null };
+  /** The pane's handlers, while the window is on. */
+  onViewport(ev: { width: number; height: number }): void;
+  onScroll(ev: { scrollY: number }): void;
+  /** A drawn block's box as it mounts, and null as it goes. */
+  register(key: string, at: number, node: unknown): void;
+  /** What the view asks — see `BlockWindow`. */
+  window: BlockWindow;
+}
+
+/** The window over a document's top-level blocks. Call every render, with
+ *  the document about to be drawn. */
+export function useBlockWindow(inputs: BlockWindowInputs): BlockWindowState {
+  const { doc, keys, virtual, estimate, gap } = inputs;
+  const box = useRef<ScrollableNode | null>(null);
+  const [, setMeasured] = useState(0);
+  const rows = useMemo(() => topBlocks(doc, keys), [doc, keys]);
+  const rowsRef = useRef(rows);
+  rowsRef.current = rows;
+  const gapRef = useRef(gap);
+  gapRef.current = gap;
+  /** The drawn blocks' boxes, by key, with the index each was drawn at. */
+  const nodes = useRef(new Map<RowKey, Drawn>());
+  const virtualizing =
+    virtual === true || (virtual === 'auto' && rows.length > VIRTUAL_THRESHOLD);
+
+  // One index per editor, for as long as it is mounted. A new look is a new
+  // height for every block, so what was measured under the old one goes.
+  const [heights] = useState(() => new RowHeights(estimate));
+  const estimated = useRef(estimate);
+  if (estimated.current !== estimate) {
+    estimated.current = estimate;
+    heights.reset();
+  }
+  heights.sync(rows, estimate);
+
+  const win = useVirtualWindow({
+    box,
+    heights,
+    rows,
+    exact: false,
+    virtualizing,
+    overscan: DEFAULT_OVERSCAN,
+    prefetch: DEFAULT_PREFETCH,
+    // a block is built whole or not at all: no skeletons
+    threshold: Number.POSITIVE_INFINITY,
+    burstBudget: BURST_BUDGET,
+    settleBudget: SETTLE_BUDGET,
+  });
+  const reveal = useReveal({ box, rows: rowsRef, nodes, heights });
+
+  /** A reveal the view is waiting on, and what it does once the block is
+   *  laid out. */
+  const owed = useRef<{ id: string; then: () => void } | null>(null);
+
+  const drawnAt = useCallback((index: number): boolean => {
+    const row = rowsRef.current[index];
+    const drawn = row ? nodes.current.get(row.id) : undefined;
+    return !!drawn && drawn.at === index && drawn.node.abs.height > 0;
+  }, []);
+
+  /** What the drawn blocks laid out at, into the index — `<Tree>`'s pass:
+   *  what grew above the viewport comes back out of the offset, so the text
+   *  being read does not move. */
+  const measure = (): boolean => {
+    const pane = box.current;
+    const list = rowsRef.current;
+    const anchor = pane ? heights.indexAt(pane.scrollY / scaleOf(pane)) : 0;
+    let shift = 0;
+    let changed = false;
+    for (const [id, { node, at }] of nodes.current) {
+      if (list[at]?.id !== id || !(node.abs.height > 0)) continue;
+      // `abs` is device, the index logical (../internal/units.ts)
+      const height = node.abs.height / scaleOf(node) + gapRef.current;
+      const was = heights.heightAt(at);
+      if (!heights.measure(id, at, height)) continue;
+      changed = true;
+      if (at < anchor) shift += height - was;
+    }
+    if (!changed) return false;
+    reveal.nudge(shift);
+    setMeasured((n) => n + 1);
+    return true;
+  };
+
+  /** The estimate learns the measured mean — idle only, and the screen
+   *  kept still by the same anchor arithmetic. */
+  const adapt = (): boolean => {
+    const pane = box.current;
+    if (!pane) return false;
+    const anchor = heights.indexAt(pane.scrollY / scaleOf(pane));
+    const before = heights.offsetAt(anchor);
+    if (!heights.adapt()) return false;
+    reveal.nudge(heights.offsetAt(anchor) - before);
+    setMeasured((n) => n + 1);
+    return true;
+  };
+
+  /** Whether a drawn block has no size yet: a commit can land between frame
+   *  flushes, and a pass over it reads zeros. */
+  const unsized = (): boolean => {
+    const list = rowsRef.current;
+    for (const [id, { node, at }] of nodes.current) {
+      if (list[at]?.id === id && !(node.abs.height > 0)) return true;
+    }
+    return false;
+  };
+
+  /** Hand the view the block it was waiting on, once it is laid out — or
+   *  drop the wait, when the block has left the document. */
+  const settle = (): void => {
+    const o = owed.current;
+    if (!o) return;
+    const drawn = nodes.current.get(o.id);
+    if (
+      drawn &&
+      rowsRef.current[drawn.at]?.id === o.id &&
+      drawn.node.abs.height > 0
+    ) {
+      owed.current = null;
+      o.then();
+    } else if (!rowsRef.current.some((row) => row.id === o.id)) {
+      owed.current = null;
+    }
+  };
+
+  // The tick after layout, and everything only known there: what the blocks
+  // measured, whether an owed scroll can go further, where the pane really
+  // is, and whether the block the view waits on is laid out — in that order,
+  // each able to move what the next one reads.
+  const ticks = useRef<{ layout: LayoutTick; look: DelayTick; tries: number }>({
+    layout: null,
+    look: null,
+    tries: 0,
+  });
+  const pass = useRef<() => void>(() => {});
+  pass.current = (): void => {
+    if (!virtualizing) return;
+    const pane = box.current;
+    // `onViewport` reports a change, so a window turned on after the pane's
+    // first layout has never heard its size: read it here
+    if (pane && win.viewRef.current.height === 0 && pane.abs.height > 0) {
+      const s = scaleOf(pane);
+      win.sized(pane.abs.width / s, pane.abs.height / s);
+    }
+    const moved = win.fast() ? false : measure();
+    const adapted = !win.scrolling() && adapt();
+    reveal.retry(moved || adapted);
+    win.sync();
+    settle();
+    // look again, briefly, while a block is unsized or the view still waits
+    // — nothing else would come back for them
+    const t = ticks.current;
+    if ((unsized() || owed.current !== null) && t.tries++ < 8) {
+      t.look = later(() => {
+        t.look = null;
+        pass.current();
+      }, 16);
+    }
+  };
+  const kick = useCallback((): void => {
+    const t = ticks.current;
+    cancelAfterLayout(t.layout);
+    cancelLater(t.look);
+    t.look = null;
+    t.tries = 0;
+    t.layout = afterLayout(() => {
+      t.layout = null;
+      pass.current();
+    });
+  }, []);
+  useEffect(() => {
+    if (virtualizing) kick();
+  });
+  useEffect(
+    () => () => {
+      const t = ticks.current;
+      cancelAfterLayout(t.layout);
+      cancelLater(t.look);
+    },
+    [],
+  );
+
+  const { sized, scrolled, sync } = win;
+  const onViewport = useCallback(
+    (ev: { width: number; height: number }): void => {
+      sized(ev.width, ev.height);
+      // the content changed size: an owed scroll may reach further, and the
+      // pane may have re-clamped its offset without a word
+      reveal.retry(true);
+      sync();
+    },
+    [sized, reveal, sync],
+  );
+  const onScroll = useCallback(
+    (ev: { scrollY: number }): void => {
+      // a scroll this editor did not ask for is the reader's, and what the
+      // view was waiting to do gives way to it
+      if (!reveal.heard(ev.scrollY)) owed.current = null;
+      scrolled(ev.scrollY);
+    },
+    [reveal, scrolled],
+  );
+
+  const register = useCallback(
+    (key: string, at: number, node: unknown): void => {
+      const map = nodes.current;
+      if (node) map.set(key, { node: node as DrawnNode, at });
+      else if (map.get(key)?.at === at) map.delete(key);
+    },
+    [],
+  );
+
+  const window = useMemo<BlockWindow>(
+    () => ({
+      drawn: drawnAt,
+      reveal: (index, then) => {
+        const row = rowsRef.current[index];
+        if (!row) return;
+        if (drawnAt(index)) {
+          then();
+          return;
+        }
+        owed.current = { id: row.id, then };
+        reveal.to(row.id);
+        // the reveal may need no render of its own — a block already in the
+        // window, not yet laid out — so a pass is asked for here
+        kick();
+      },
+    }),
+    [drawnAt, reveal, kick],
+  );
+
+  const { first, last } = win.slice;
+  return {
+    virtualizing,
+    first,
+    last,
+    above: virtualizing && first > 0 ? Math.max(0, win.slice.above - gap) : 0,
+    below:
+      virtualizing && last < rows.length
+        ? Math.max(0, win.slice.below - gap)
+        : 0,
+    box,
+    onViewport,
+    onScroll,
+    register,
+    window,
+  };
+}

package/src/richtext/node.ts

@@ -37,6 +37,7 @@ import {
   paintRunBackgrounds,
   paintRunRules,
 } from './runs.js';
+import type { FillContext } from './runs.js';
 import { codeUnitOffsets } from '../internal/text.js';
 
 /** The element name — registration key, `node.kind` and JSX tag alike. */
@@ -215,8 +216,18 @@ export class RichTextNode extends Node {
   private _layouts = new Map<string, TextLayoutLike | null>();
   private _text: string | null = null;
 
-  constructor(props: Record<string, unknown>, app: NtkApp) {
-    super(ELEMENT, props, app);
+  /**
+   * `kind` is for a subclass registered under a name of its own — the rich
+   * text editor's text blocks are `<richtext>` plus a caret and a selection
+   * the editor owns (`src/rich-text-editor/nodes.ts`). A node's `kind` must be
+   * the name it was registered under, so the subclass passes its own.
+   */
+  constructor(
+    props: Record<string, unknown>,
+    app: NtkApp,
+    kind: string = ELEMENT,
+  ) {
+    super(kind, props, app);
   }
 
   /**
@@ -302,8 +313,10 @@ export class RichTextNode extends Node {
    * The layout this node is currently painted with — and, because it is the
    * one thing every accessor below answers from, the reason a caret rect and
    * a glyph cannot disagree (docs/extending.md, "answer from what you draw").
+   * Protected rather than private for the editor's subclass, whose line-wise
+   * caret motion reads the lines off the same layout the glyphs came from.
    */
-  private _paintLayout(): TextLayoutLike | null {
+  protected paintLayout(): TextLayoutLike | null {
     const wrap = (this.props as unknown as RichTextProps).wrap !== false;
     return this._layoutFor(wrap ? this.abs.width : Infinity);
   }
@@ -347,14 +360,14 @@ export class RichTextNode extends Node {
   }
 
   override textIndexAt(x: number, y: number): number {
-    const layout = this._paintLayout();
+    const layout = this.paintLayout();
     if (!layout) return 0;
     const i = layout.indexAt(x - this.abs.x, y - this.abs.y);
     return Math.max(0, Math.min([...this.textContent()].length, i));
   }
 
   override textCaretRect(index: number): Rect | null {
-    const layout = this._paintLayout();
+    const layout = this.paintLayout();
     if (!layout) return null;
     const caret = layout.caretPosition(index);
     return {
@@ -366,7 +379,7 @@ export class RichTextNode extends Node {
   }
 
   override textRangeRects(start: number, end: number): Rect[] {
-    const layout = this._paintLayout();
+    const layout = this.paintLayout();
     if (!layout) return [];
     return rangeBands(layout, this.textContent(), start, end).map((band) => ({
       x: this.abs.x + band.x,
@@ -381,7 +394,7 @@ export class RichTextNode extends Node {
    *  selection seam: core deliberately left hover and `cursorAt` out of
    *  #291, so following a link stays this package's. */
   hrefAtPoint(x: number, y: number): string | null {
-    const layout = this._paintLayout();
+    const layout = this.paintLayout();
     if (!layout) return null;
     const s = this._scale;
     const lx = x * s - this.abs.x;
@@ -401,7 +414,7 @@ export class RichTextNode extends Node {
 
   override paint(ctx: Context2D): void {
     super.paint(ctx); // background, border, clip to `abs`
-    const layout = this._paintLayout();
+    const layout = this.paintLayout();
     if (!layout || !canFill(ctx)) return;
     const { x, y } = this.abs;
     const s = this._scale;
@@ -412,28 +425,8 @@ export class RichTextNode extends Node {
     //    terminal's cell backgrounds
     for (const line of layout.lines) paintRunBackgrounds(ctx, line, x, y, s);
 
-    // 2. the band the document selection has claimed of this element's text,
-    //    translucent so the ink keeps its contrast on either palette (the
-    //    same reasoning as `<textarea>`'s). The range and the colour both
-    //    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;
-    // 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),
-          Math.round(r.y),
-          Math.ceil(r.width),
-          Math.ceil(r.height),
-        );
-      }
-    }
+    // 2. the band a selection has claimed of this element's text
+    this.paintSelection(ctx);
 
     // 3. the ink
     layout.draw(ctx, x, y);
@@ -441,6 +434,42 @@ export class RichTextNode extends Node {
     // 4. rules over the ink: link underlines, strikethrough
     for (const line of layout.lines) paintRunRules(ctx, line, x, y, s);
 
+    // 5. anything that belongs over everything — a subclass's caret
+    this.paintOverlay(ctx);
+
     ctx.restore();
   }
+
+  /**
+   * The selection band, between the run backgrounds and the ink. The default
+   * is core's document selection: the band the `selectable` surface above
+   * has claimed of this element's text, translucent so the ink keeps its
+   * contrast on either palette (the same reasoning as `<textarea>`'s). The
+   * range and the colour both arrive from that surface; `textRangeRects` is
+   * what a custom element and core's own `<text>` both fill, so they cannot
+   * drift. An element with a selection of its own — the editor's text
+   * blocks — overrides this and fills that one instead.
+   */
+  protected paintSelection(ctx: FillContext): void {
+    const range = this.selectionRange;
+    // 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) return;
+    ctx.fillStyle = selectionColor;
+    for (const r of this.textRangeRects(range.start, range.end)) {
+      ctx.fillRect(
+        Math.round(r.x),
+        Math.round(r.y),
+        Math.ceil(r.width),
+        Math.ceil(r.height),
+      );
+    }
+  }
+
+  /** Drawn last, over the ink and the rules: nothing here, a caret in the
+   *  editor's subclass. Inside the same save/restore as the rest. */
+  protected paintOverlay(_ctx: FillContext): void {}
 }

package/src/table/index.ts

@@ -70,6 +70,7 @@ import {
   cancelLater,
   later,
 } from '../internal/timers.js';
+import { scaleOf } from '../internal/units.js';
 import type { DelayTick } from '../internal/timers.js';
 import { useReveal } from '../internal/scroll.js';
 import {
@@ -953,7 +954,10 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
   const syncScroll = useCallback((): void => {
     const box = body.current;
     if (!box) return;
-    const x = box.scrollX;
+    // Device on the raw property; the header margin it feeds is a style
+    // length, logical — the same division every raw read here makes
+    // (../internal/units.ts).
+    const x = box.scrollX / scaleOf(box);
     setScrollX((prev) => (prev === x ? prev : x));
     winSync();
   }, [winSync]);
@@ -992,13 +996,18 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
     ).total;
     const box = body.current;
     const rows = orderedRef.current;
-    const anchor = box ? heights.indexAt(box.scrollY) : 0;
+    const anchor = box ? heights.indexAt(box.scrollY / scaleOf(box)) : 0;
     let shift = 0;
     let changed = false;
     for (const [id, { node, at }] of rowNodes.current) {
       if (rows[at]?.id !== id) continue; // drawn against a list that moved
-      if (node.abs.width !== expected) continue;
-      const height = node.abs.height;
+      // `abs` is device; the resolved widths and the height index are
+      // logical. Within a pixel rather than exact: a fractional scale
+      // rounds the device width to the pixel grid, and the stale-width
+      // layouts this gate exists for are whole columns off, not fractions.
+      const s = scaleOf(node);
+      if (Math.abs(node.abs.width / s - expected) >= 1) continue;
+      const height = node.abs.height / s;
       const was = heights.heightAt(at);
       if (!heights.measure(id, at, height)) continue;
       changed = true;
@@ -1026,7 +1035,7 @@ export function Table<Row = any>(props: TableProps<Row>): ReactElement {
     if (uniform || !virtualizing) return false;
     const box = body.current;
     if (!box) return false;
-    const anchor = heights.indexAt(box.scrollY);
+    const anchor = heights.indexAt(box.scrollY / scaleOf(box));
     const before = heights.offsetAt(anchor);
     if (!heights.adapt()) return false;
     reveal.nudge(heights.offsetAt(anchor) - before);

package/src/terminal/backends.ts

@@ -21,7 +21,10 @@
  * program installed and is the only backend `write()` can work on.
  *
  * `'auto'` takes the first embeddable emulator that is installed and falls
- * back to `'vt'`. That order — rather than vt first — is deliberate: an
+ * back to `'vt'` — and on a react-x11 backend that cannot host an embedded
+ * window at all (the native macOS one) it takes `'vt'` without looking for
+ * the other three, because an emulator found on `PATH` there is one this app
+ * cannot show. That order — rather than vt first — is deliberate: an
  * external emulator is battle-tested, and a user who installed one expressed
  * a preference. Moving vt to the front is a later, deliberate decision.
  */