react-x11 2.11.0 → 2.13.0

package/src/nodes/damage.js

@@ -0,0 +1,183 @@
+// The damage model's vocabulary: the whole-window sentinel, the bounded list
+// of rects a frame repaints and how it is merged, the reasons an
+// invalidate() may give, and the diff a layout pass reports into. Data and
+// pure functions only; the methods that feed it are in invalidate.js.
+
+import { unionRect, rectArea, rectsBounds, rectsOverlap } from './rects.js';
+
+// --- damage -------------------------------------------------------------
+//
+// A frame either repaints the whole window or a bounded region of it. The
+// sentinel is deliberately not a rect: "the whole window" has to stay
+// distinguishable from "a rect that happens to cover it", because the
+// window can be resized between the invalidation and the paint.
+export const FULL_DAMAGE = Symbol('full-damage');
+
+// "I need a frame, but nothing I own changed appearance." Distinct from
+// passing no node, which means "something changed and I cannot say where" —
+// the safe reading, and the one that repaints everything.
+export const NO_DAMAGE = Symbol('no-damage');
+
+// Painting is not perfectly bounded by a node's rect — an antialiased
+// rounded corner or glyph edge puts coverage a fraction of a pixel outside
+// it — so damage grows by a pixel on each side before anything is culled
+// against it.
+export const DAMAGE_SLOP = 1;
+
+/** Stale bounds are undebuggable, and every other cache here has an escape
+ * hatch — see NO_SCROLL_BLIT and the paint cache's DISABLED. */
+export const NO_BOUNDS_CACHE = process.env.REACT_X11_NO_BOUNDS_CACHE === '1';
+
+// The two pieces of state a bounded frame's layout pass reports through.
+// One object rather than two `let`s: the pass runs through more than one
+// module, and a module cannot assign a binding it imported.
+export const layoutDiff = {
+  // While a bounded frame's layout pass runs, every node whose absolute rect
+  // comes out different reports its old and new rects here (each already
+  // inflated by that node's own paint reach) — which is what lets a layout
+  // change stay a handful of rects instead of degrading the frame to
+  // FULL_DAMAGE. Module state rather than a parameter because absolutize is
+  // a hot recursive walk with overrides in three classes; null outside the
+  // pass, and always restored through `finally`.
+  sink: null,
+
+  // The uniform translation the subtree currently being walked is riding: set
+  // while a scroll container whose blit is armed lays its children out, so the
+  // diff can tell "moved" from "scrolled" (issue #398). Every child of such a
+  // container lands at its old rect plus this shift, which is precisely what
+  // the blit is about to do to those pixels — so it is not a change, and the
+  // diff reports only the children that landed somewhere else. Null everywhere
+  // else, and restored through `finally` like the sink beside it.
+  shift: null,
+};
+
+// What an invalidate() may name as its reason — a small closed set, so the
+// frame log, the tracer and the full-repaint warning can print "why" next
+// to "where". A typo'd reason would silently vanish from every report, so
+// DEV validates against this list.
+export const INVALIDATE_REASONS = new Set([
+  'props', // a React commit changed what a node draws
+  'style-state', // :hover/:focus/:active/:disabled restyle
+  'shadow', // a boxShadow got smaller: where it *was* still owes a repaint
+  'outline', // …and the same for an outline a style swap took away
+  'theme', // a theme/token change restyled a subtree
+  'direction', // the reading direction moved: sides, glyph order, bar edge
+  'scale', // a `scale` prop zoomed a subtree: every length in it moved
+  'animation', // a transition frame
+  'scroll', // scrollTo/scrollBy/scrollIntoView, textarea/textinput panning
+  'text', // text content, input value or caret editing
+  'selection', // the document selection lit or unlit a range of text
+  'content', // async content arrived (image decode, rich-content reflow)
+  'measure', // an element said its own size changed (invalidateMeasure)
+  'child-list', // children were added, removed or reordered
+  'focus', // focus moved: ring/caret handover between nodes
+  'caret', // the caret blink timer
+  'resize', // the window changed size
+  'mount', // the window was just realized; its first frame
+  'expose', // ntk asked for a redraw (backing store invalidated)
+  'highlight', // DevTools hover highlight
+  'trace-updates', // DevTools' outline of what just re-rendered
+  'capabilities', // a compositor started or stopped: what the window may paint
+  'layout', // a layout algorithm arrived, left, or has something new to read
+]);
+
+// A frame with no recorded reasons shares one frozen empty list, so the
+// per-frame cost of the reason machinery when nothing is reading it is a
+// property write.
+export const EMPTY_REASONS = Object.freeze([]);
+
+// How many rectangles a frame's damage is allowed to hold.
+//
+// Kept much smaller than the equivalent cap in ntk, because a rectangle costs
+// more here: ntk pays one extra CopyArea per rectangle, while this pays a whole
+// extra pass over the tree — `paintOrder()` allocates and sorts per node — plus
+// a clip. Four is enough for the shapes that actually occur (a ticker and a
+// table row; a control and the status line it updates) and cheap enough that
+// the worst case is not worth avoiding.
+export const MAX_DAMAGE_RECTS = 4;
+
+// How much of the box around them several rectangles have to save to be worth
+// painting separately. Two adjacent tab headers describe nearly the same area
+// either way and are better off as one pass; two corners of the window are not.
+const SPLIT_SAVING = 0.75;
+
+/**
+ * Merge overlapping rects until none of them overlap.
+ *
+ * Disjointness is not tidiness here, it is correctness. Each rect gets its own
+ * pass over the tree, and a node inside two of them would be painted twice —
+ * harmless for opaque drawing, wrong for anything translucent, which would
+ * blend over itself. Merging removes the question and saves the duplicated
+ * pass at the same time.
+ */
+function coalesceRects(rects) {
+  const out = [];
+  for (const rect of rects) {
+    let merged = rect;
+    for (let i = out.length - 1; i >= 0; i--) {
+      if (!rectsOverlap(out[i], merged)) continue;
+      merged = unionRect(merged, out[i]);
+      out.splice(i, 1);
+      // start the scan again: having grown, the rect can now reach ones
+      // already passed over
+      i = out.length;
+    }
+    out.push(merged);
+  }
+  return out;
+}
+
+/**
+ * Add one rect to a capped, disjoint damage list, returning a new list.
+ *
+ * Over the cap, the pair whose merge wastes the least area is merged — waste
+ * being the area the merged rect covers that neither of the two did, so
+ * neighbours go first and far-apart rects last. That merge can itself overlap a
+ * third rect, so the result is coalesced again.
+ */
+export function addDamageRect(rects, add, cap = MAX_DAMAGE_RECTS) {
+  let out = coalesceRects(
+    (rects ?? []).concat([
+      { x: add.x, y: add.y, width: add.width, height: add.height },
+    ]),
+  );
+  while (out.length > cap) {
+    let bestI = 0;
+    let bestJ = 1;
+    let bestWaste = Infinity;
+    for (let i = 0; i < out.length; i++) {
+      for (let j = i + 1; j < out.length; j++) {
+        const waste =
+          rectArea(unionRect(out[i], out[j])) -
+          rectArea(out[i]) -
+          rectArea(out[j]);
+        if (waste < bestWaste) {
+          bestWaste = waste;
+          bestI = i;
+          bestJ = j;
+        }
+      }
+    }
+    const merged = unionRect(out[bestI], out[bestJ]);
+    out = coalesceRects(
+      out.filter((_, k) => k !== bestI && k !== bestJ).concat([merged]),
+    );
+  }
+  return out;
+}
+
+/**
+ * The rects a frame actually paints, given the ones that were claimed.
+ *
+ * Each one costs a pass over the tree and a clip, so a list whose pieces nearly
+ * fill the box around them is better served by one pass over that box. Both
+ * answers cover every claimed pixel, so this is a cost decision and never a
+ * correctness one.
+ */
+export function damageToPaint(rects) {
+  if (rects.length < 2) return rects;
+  const box = rectsBounds(rects);
+  let sum = 0;
+  for (const r of rects) sum += rectArea(r);
+  return sum > rectArea(box) * SPLIT_SAVING ? [box] : rects;
+}

package/src/nodes/edithistory.js

@@ -0,0 +1,124 @@
+// Undo and redo for <textinput> and <textarea>: the history an edit is
+// recorded into, run by run, capped at UNDO_LIMIT entries.
+
+/** Undo entries kept per input. Snapshots of a single field are small; the
+ * cap is what stops a long-lived form from growing without bound. */
+const UNDO_LIMIT = 200;
+
+/** Undo and redo, installed onto `TextInputNode.prototype` by textinput.js. */
+export class TextInputHistory {
+  // --- undo/redo ------------------------------------------------------
+  //
+  // Full-value snapshots rather than a diff log: a single field is small,
+  // and a snapshot is the only representation that stays right when the
+  // value is controlled and the parent rewrites what we send it. Each
+  // entry also carries the caret from *before* the edit that produced it,
+  // so undoing puts the caret back where the typing happened rather than
+  // where the run ended.
+
+  /** True while there is an earlier state to go back to. */
+  get canUndo() {
+    return this._historyIndex > 0;
+  }
+
+  /** True while an undone state is still ahead. */
+  get canRedo() {
+    return this._historyIndex < this._history.length - 1;
+  }
+
+  /** Step back one edit. Returns false when there is nothing to undo. */
+  undo() {
+    if (!this.canUndo) return false;
+    const undone = this._history[this._historyIndex];
+    const target = this._history[--this._historyIndex];
+    // the caret goes where the undone edit started, not where it ended
+    this._applyHistory(target.value, undone.beforeCaret, undone.beforeAnchor);
+    return true;
+  }
+
+  /** Step forward one undone edit. False when there is nothing to redo. */
+  redo() {
+    if (!this.canRedo) return false;
+    const target = this._history[++this._historyIndex];
+    this._applyHistory(target.value, target.caret, target.anchor);
+    return true;
+  }
+
+  /** End the coalescing run: the next edit starts a fresh undo entry. */
+  _breakUndoRun() {
+    this._undoRun = null;
+  }
+
+  _applyHistory(value, caret, anchor) {
+    this._breakUndoRun();
+    const previous = this.value;
+    if (this.props.value == null) this._value = value;
+    this._historyValue = value;
+    const len = Array.from(value).length;
+    this._caret = Math.min(Math.max(0, caret), len);
+    this._anchor = Math.min(Math.max(0, anchor), len);
+    if (value !== previous) this._fireValueEvent('onChange', value);
+    this._repaint();
+  }
+
+  /**
+   * Fold the edit into the open run, or start a new entry. A run continues
+   * while the same kind of edit keeps happening at the caret it left off
+   * at, so a word of typing — or a run of backspaces — undoes as one step.
+   */
+  _recordEdit(kind, entry) {
+    const top = this._history[this._historyIndex];
+    const continues =
+      kind != null &&
+      kind === this._undoRun &&
+      // a replaced selection is a distinct edit, however it was typed
+      entry.beforeCaret === entry.beforeAnchor &&
+      top?.caret === entry.beforeCaret;
+    if (continues) {
+      top.value = entry.value;
+      top.caret = entry.caret;
+      top.anchor = entry.anchor;
+    } else {
+      this._pushHistory(kind, entry);
+    }
+    this._historyValue = entry.value;
+  }
+
+  _pushHistory(kind, entry) {
+    // a fresh edit after an undo drops whatever was ahead
+    this._history.length = this._historyIndex + 1;
+    this._history.push(entry);
+    if (this._history.length > UNDO_LIMIT) this._history.shift();
+    this._historyIndex = this._history.length - 1;
+    this._undoRun = kind;
+  }
+
+  /**
+   * A controlled `value` that changed to something we did not commit was
+   * edited outside the control — a form reset, or an onChange that filters
+   * what it is given. It becomes its own history entry, so undo walks back
+   * through states that really existed. The neighbour checks catch the
+   * parent echoing an undo back at us, or refusing one: that moves through
+   * the history instead of appending to it, which is what keeps a filtering
+   * onChange from growing the stack on every keystroke.
+   */
+  _noteExternalValue() {
+    const value = this.value;
+    if (value === this._historyValue) return;
+    this._breakUndoRun();
+    if (this._history[this._historyIndex + 1]?.value === value) {
+      this._historyIndex++;
+    } else if (this._history[this._historyIndex - 1]?.value === value) {
+      this._historyIndex--;
+    } else {
+      this._pushHistory(null, {
+        value,
+        caret: this._caret,
+        anchor: this._anchor,
+        beforeCaret: this._caret,
+        beforeAnchor: this._anchor,
+      });
+    }
+    this._historyValue = value;
+  }
+}

package/src/nodes/editmenupopup.js

@@ -0,0 +1,260 @@
+// The built-in edit menu's popup: a <popup> with a canvas in it, opened at
+// the caret or the pointer. The menu's items, geometry and painting are in
+// src/editmenu.js; this is the node half that shows them.
+
+import { deviceAnchorArea, windowOrigin } from '../anchor.js';
+import { armPasteState, canPaste } from '../pastestate.js';
+import {
+  XK_RETURN,
+  XK_KP_ENTER,
+  XK_UP,
+  XK_DOWN,
+  XK_ESCAPE,
+} from '../keysyms.js';
+import {
+  editMenuColors,
+  editMenuGeometry,
+  editMenuIndexAt,
+  editMenuItems,
+  editMenuStep,
+  paintEditMenu,
+} from '../editmenu.js';
+import { CanvasNode } from './canvas.js';
+import { PopupNode } from './window/popup.js';
+
+// --- the standard edit menu ------------------------------------------------
+//
+// Right-click gets Undo/Cut/Copy/Paste with no wiring, the way a browser
+// gives `<input>` one. The rows cannot be `Menu` components — those are
+// React over the nodes, and a node cannot mount one — so the menu is a
+// `<popup>` built here with a `<canvas>` child that paints the rows
+// (src/editmenu.js) and handles its own pointer and key events. That reuses
+// the popup's pointer grab, dismissal and focus rather than reinventing
+// them.
+//
+// `<textinput>` is a *caller* of this, not its owner (issue #256): the
+// enablement rules, the PRIMARY/CLIPBOARD subtleties and the menu's keyboard
+// handling are the parts a second editable element would otherwise have to
+// re-debug, so they live here, once, behind a verb interface anything can
+// speak.
+
+/** Where the popup goes: at `at`, which is in the owner window's coordinates
+ * the way a synthetic event's `x`/`y` are, pulled back inside the monitor
+ * when the menu would hang off an edge of it. */
+function editMenuOrigin(node, at, size) {
+  const origin = windowOrigin(node);
+  let x = origin.x + (Number.isFinite(at?.x) ? at.x : (node.abs?.x ?? 0));
+  let y = origin.y + (Number.isFinite(at?.y) ? at.y : (node.abs?.y ?? 0));
+  // the monitor's work area rather than the whole virtual desktop, so a menu
+  // near a seam flips back onto the screen it was opened on — the same
+  // answer `<ContextMenu>` clamps a pointer-anchored menu into. Clamped, not
+  // flipped: there is no anchor rect to flip around.
+  const area = deviceAnchorArea(node);
+  if (area) {
+    x = Math.max(area.x, Math.min(x, area.x + area.width - size.width));
+    y = Math.max(area.y, Math.min(y, area.y + area.height - size.height));
+  }
+  return { x, y };
+}
+
+/**
+ * Open the standard edit menu on `node`, for a target that speaks a small
+ * verb interface.
+ *
+ * This is what `<textinput>`'s own right-click menu is, and the reason it is
+ * exported is that everything about it except the verbs is worth having
+ * once: which rows are enabled, Paste watching selection ownership rather
+ * than asking the server on the way to opening a menu, the arrow keys and
+ * Escape, the pointer grab that dismisses it, and handing the keyboard back
+ * where it came from afterwards.
+ *
+ * ```js
+ * openEditMenu(node, { x: ev.x, y: ev.y }, {
+ *   canUndo: this.canUndo,  undo: () => this.undo(),
+ *   canRedo: this.canRedo,  redo: () => this.redo(),
+ *   hasSelection: this.hasSelection(),
+ *   cut: () => this.cut(),
+ *   copy: () => this.copy(),
+ *   paste: () => this.paste(),
+ *   selectAll: () => this.selectAll(),
+ * });
+ * ```
+ *
+ * **A verb you leave out is a row that is not there**, rather than a greyed
+ * one — see `editMenuItems`. A read-only surface passes `hasSelection`,
+ * `copy` and `selectAll` and gets a two-row menu; a password field passes no
+ * `copy` and no `cut` and gets a menu that offers neither. Leave out every
+ * verb and nothing opens at all.
+ *
+ * @param {Node} node the element the menu belongs to. The popup hangs off it
+ *   in the tree, so it goes away with the element and counts as inside it
+ *   for `:focus-within`.
+ * @param {{x: number, y: number}} at where the pointer was, in the owner
+ *   window's coordinates — `ev.x`/`ev.y` from the event that asked for the
+ *   menu. A surface with no caret has nothing else to offer, and this is
+ *   what it already has.
+ * @param {object} actions the verbs, and what each is worth right now:
+ *   `hasSelection` (Cut and Copy follow it), `canUndo`, `canRedo`,
+ *   `canSelectAll` (defaults to true), and the functions `undo`, `redo`,
+ *   `cut`, `copy`, `paste`, `selectAll`.
+ */
+export function openEditMenu(node, at, actions = {}) {
+  closeEditMenu(node);
+  if (!node?.root || node.destroyed) return;
+  const app = node.app;
+  const clipboard = app?.clipboard ?? null;
+  // From here on the menu knows whether there is anything to paste. This
+  // first open still shows the row enabled — the answer arrives after it
+  // is drawn — which is the pre-tracking behaviour, and correct far more
+  // often than not.
+  if (typeof actions.paste === 'function') armPasteState(app, clipboard);
+  const items = editMenuItems(actions, {
+    // greyed only when the server has told us the selection is unowned
+    // (pastestate.js). Never a round trip on the way to opening a menu.
+    canPaste: Boolean(clipboard) && canPaste(app),
+  });
+  if (items.length === 0) return;
+
+  const style = node.resolvedTextStyle();
+  // `at` is `{x: ev.x, y: ev.y}` per the doc above — logical, like every
+  // coordinate a handler reads — and everything below is device: the
+  // geometry takes the scale so its chrome lands on the same grid as the
+  // device-sized text it measures.
+  const s = node.scale;
+  const geometry = editMenuGeometry(
+    items,
+    (text) => app?.fonts?.layout(text, style)?.width,
+    s,
+  );
+  const deviceAt = at && {
+    ...at,
+    ...(Number.isFinite(at.x) && { x: at.x * s }),
+    ...(Number.isFinite(at.y) && { y: at.y * s }),
+  };
+  const { x, y } = editMenuOrigin(node, deviceAt, geometry);
+  const colors = editMenuColors(node.theme);
+  const state = { active: -1 };
+  const choose = (id) => {
+    closeEditMenu(node);
+    // the target's own entry point, so the row can never drift from what
+    // the equivalent shortcut does
+    if (id) actions[id]?.();
+  };
+
+  const canvas = new CanvasNode(
+    {
+      focusable: true,
+      style: { flexGrow: 1 },
+      onDraw: (ctx) =>
+        paintEditMenu(ctx, {
+          geometry,
+          active: state.active,
+          colors,
+          radius: node.theme?.radius ?? 4,
+          layoutOf: (text, color) =>
+            app?.fonts?.layout([{ text, ...style, color }], style),
+        }),
+      onMouseMove: (mv) => {
+        const next = editMenuIndexAt(geometry, mv.nativeEvent?.y ?? mv.y * s);
+        if (next === state.active) return;
+        state.active = next;
+        popup.invalidate(false, null, 'style-state');
+      },
+      onMouseUp: (mv) => {
+        const i = editMenuIndexAt(geometry, mv.nativeEvent?.y ?? mv.y * s);
+        if (i !== -1) choose(geometry.rows[i].id);
+        else closeEditMenu(node);
+      },
+      onKeyDown: (k) => {
+        if (k.keysym === XK_ESCAPE) return closeEditMenu(node);
+        if (k.keysym === XK_UP || k.keysym === XK_DOWN) {
+          state.active = editMenuStep(
+            geometry,
+            state.active,
+            k.keysym === XK_DOWN ? 1 : -1,
+          );
+          popup.invalidate(false, null, 'style-state');
+          return;
+        }
+        if (k.keysym === XK_RETURN || k.keysym === XK_KP_ENTER) {
+          const row = geometry.rows[state.active];
+          if (row && !row.separator) choose(row.id);
+        }
+      },
+    },
+    app,
+  );
+
+  const popup = new PopupNode(
+    app,
+    {
+      x,
+      y,
+      width: geometry.width,
+      height: geometry.height,
+      windowType: 'popup_menu',
+    },
+    {
+      // **The size goes in the props, not only in the attributes.** A
+      // `<window>`/`<popup>` size is `'auto'` when the props do not name one,
+      // and `realize()` then *measures* the content and overwrites whatever
+      // the attributes said (issue #248) — which for a canvas that only
+      // `flexGrow`s is nothing at all, so this popup opened 1x1 and the menu
+      // was invisible. Every other popup in the tree comes from React, where
+      // one props object is both, so nothing else could reach it.
+      // Props are the logical contract (`_measure` multiplies them back);
+      // the attributes above carry the same size already in device pixels.
+      width: geometry.width / s,
+      height: geometry.height / s,
+      grab: true,
+      // a press outside the menu closes it and goes no further, which is
+      // what the grab is for
+      onDismiss: () => closeEditMenu(node),
+    },
+  );
+  popup.insertBefore(canvas, null);
+  node.insertBefore(popup, null);
+  popup.realize(null);
+  // the rows as they were built, for a test to read: they are painted into a
+  // canvas, so there is no tree for `screen` to query them out of
+  popup._editMenuRows = geometry.rows;
+  node._editMenu = popup;
+  // read *before* the menu takes the keyboard, and handed back on close
+  node._editMenuRestore = node._focusManager()?.focused ?? null;
+  // the menu takes the keyboard so arrows and Escape reach it rather than
+  // the element behind it
+  popup.events?.focus?.(canvas);
+}
+
+/** Whether `node` has the standard edit menu open. An element that paints a
+ * selection asks: the popup holds the keyboard, so the element is not
+ * focused, and the text the menu is about to act on has to stay visibly
+ * selected. */
+export function editMenuOpen(node) {
+  return Boolean(node?._editMenu);
+}
+
+/** Close it, if it is open. The menu closes itself on a choice, a press
+ * outside and Escape; this is for an element that has decided the menu no
+ * longer applies — its content changed underneath it, or it scrolled. */
+export function closeEditMenu(node) {
+  const popup = node?._editMenu;
+  if (!popup) return;
+  node._editMenu = null;
+  const restore = node._editMenuRestore;
+  node._editMenuRestore = null;
+  // the popup is a child, so a node destroyed while its menu was up took the
+  // menu with it: there is nothing left to remove and nowhere to hand the
+  // keyboard back to
+  if (node.destroyed) return;
+  node.removeChild(popup);
+  const events = node._focusManager();
+  if (!events) return;
+  // focus goes back where the menu took it from, so typing carries on where
+  // it left off — as a pointer focus, since a right-click is what opened the
+  // menu and a ring appearing on the way back would be news to nobody. A
+  // surface that was not focusable in the first place, or that stopped being
+  // on screen while the menu was up, gets nothing back rather than the
+  // destroyed menu canvas keeping the keyboard.
+  events.focus(events._canRestoreTo(restore) ? restore : null, 'pointer');
+}