react-x11 2.11.0 → 2.13.0

package/src/nodes/util.js

@@ -0,0 +1,17 @@
+// Small shared pieces with no more specific home under src/nodes/.
+
+export const DEV = process.env.NODE_ENV !== 'production';
+
+/** Equality for props that may be a scalar, an array or a plain object
+ *  (window hints are all three shapes), so an unchanged inline object
+ *  literal does not re-send the property every render. */
+export function shallowEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || !a || !b) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
+}
+
+export const NO_CHILDREN = Object.freeze([]);

package/src/nodes/window/anchoring.js

@@ -0,0 +1,161 @@
+// A window anchored to a rect in another (#255, #280): where it goes, and
+// following the anchor as it moves.
+
+import { anchorOffscreen, anchorRect } from '../../anchor.js';
+
+/** Anchoring, installed onto `WindowNode.prototype` by window.js. */
+export class WindowAnchoring {
+  // --- anchoring ----------------------------------------------------------
+  //
+  // A `<popup anchor={{to: ref, …}}>` works out its own position, because it
+  // is the only thing that can: with `width="auto"` the size is settled
+  // inside `realize()`, between `_measure()` and `CreateWindow`, which is
+  // after the last moment React could have computed a rect for it — and the
+  // placement *needs* the size, since which side it flips to and how far it
+  // is pulled back from an edge are both functions of how big it is.
+  //
+  // So the same order the natural size already established: measure, place,
+  // create. The popup is born the right size **and** in the right place,
+  // rather than mapped somewhere provisional and corrected a frame later.
+  // A widget that knows its own size has no such problem and stays on
+  // `useAnchor` / `useAnchorTracking`; both call the same functions
+  // (src/anchor.js), so the two agree by construction.
+
+  /** A `to`/`alignTo` in an `anchor` prop: a ref, or the node itself. */
+  _anchorTarget(target) {
+    if (target == null || typeof target !== 'object') return null;
+    const node = target.abs ? target : target.current;
+    return node?.abs ? node : null;
+  }
+
+  /** Where this window goes at `size`, or null when there is nothing to
+   *  anchor to yet — a ref whose node has not been laid out. */
+  _anchorPlacement(size) {
+    const anchor = this.props.anchor;
+    const node = this._anchorTarget(anchor?.to);
+    if (!node) return null;
+    // `anchorRect` is public API and speaks logical pixels on both sides;
+    // this caller's `size` came from `_measure` (device) and its result is
+    // headed for CreateWindow (device), so both convert here.
+    const s = this.scale;
+    const rect = anchorRect(node, {
+      ...anchor,
+      alignTo: this._anchorTarget(anchor.alignTo) ?? undefined,
+      width: size.width / s,
+      height: size.height / s,
+    });
+    if (!rect || s === 1) return rect;
+    return {
+      ...rect,
+      x: Math.round(rect.x * s),
+      y: Math.round(rect.y * s),
+      width: Math.round(rect.width * s),
+      height: Math.round(rect.height * s),
+    };
+  }
+
+  /**
+   * Keep an anchored window over the thing it points at: the trigger's own
+   * layout moving, an ancestor of it scrolling, the owner window being
+   * dragged, or this window's content changing size under it.
+   *
+   * The first three arrive through the *owner* window's `onAnchorChange`
+   * (`_watchAnchor`) — the same signal `useAnchorTracking` reads, since it
+   * is the same set of things that can move a trigger. The fourth is
+   * `_refit`, which knows the new size before the server does.
+   *
+   * **Out of view is not a position.** A popup is a real X window, not a
+   * web element its ancestors clip, so a caret that has scrolled out of the
+   * editor leaves a completion list floating over a document it no longer
+   * points into. There is no placement that fixes that, so the window is
+   * unmapped for as long as the anchor is gone and mapped again where it
+   * belongs when it comes back — the one answer the renderer can give on
+   * its own, since whether the popup should *close* is React state and
+   * therefore the application's. (An app that would rather close it keeps
+   * `useAnchorTracking`'s `onOutOfView`, which is exactly that seam.)
+   */
+  _followAnchor(size = this._requestedSize) {
+    if (this.destroyed || !this.window || !this.props.anchor) return;
+    const node = this._anchorTarget(this.props.anchor.to);
+    // A ref that has not attached yet counts as gone, and for the same
+    // reason: there is nowhere for the popup to be. Refs attach in the
+    // commit phase a popup realizes in, so one written *above* its own
+    // trigger in the JSX gets a frame of this — and waiting it out is
+    // better than a frame in the corner of the screen.
+    const lost = !node || anchorOffscreen(node, this.props.anchor.at);
+    if (lost !== Boolean(this._anchorLost)) {
+      this._anchorLost = lost;
+      // The grab goes with it and comes back with it. X releases a pointer
+      // grab whose window stops being viewable, so a menu that hid and
+      // reappeared would be one no press outside could dismiss — the
+      // `onDismiss` that reads as "click anywhere to close" would simply
+      // stop happening. The re-take is `PopupNode._mapNow`'s, which is what
+      // keeps it beside the map on every route back to the screen.
+      if (lost) {
+        if (this.props.grab) this.window.ungrabPointer?.();
+        this.window.unmap?.();
+      } else {
+        this._mapNow();
+      }
+    }
+    if (lost || !size) return;
+    const rect = this._anchorPlacement(size);
+    if (!rect) return;
+    if (this._placedAt?.x === rect.x && this._placedAt?.y === rect.y) return;
+    this._placedAt = { x: rect.x, y: rect.y };
+    if (typeof this.window.setState === 'function') {
+      this.window.setState({ x: rect.x, y: rect.y });
+    } else {
+      this.window.move?.(rect.x, rect.y);
+    }
+  }
+
+  /**
+   * Subscribe to whatever can move the anchor. On the **owner's** window,
+   * not on this one: what moves is the trigger, and this window's own
+   * layout passes say nothing about where it sits on screen.
+   */
+  _watchAnchor() {
+    this._unwatchAnchor();
+    if (!this.props.anchor) return;
+    // The anchor's own window where the ref has attached, and the window
+    // this popup was *written into* otherwise — which is the same one in
+    // every case that matters, and is what makes an unattached ref a
+    // one-frame wait rather than a popup nothing ever notifies again. The
+    // notification is only ever a prompt to re-measure, so subscribing to a
+    // window the anchor turns out not to be in costs a no-op.
+    const root =
+      this._anchorTarget(this.props.anchor.to)?.root ?? this.parent?.root;
+    if (!root?.onAnchorChange || root === this) return;
+    this._anchorWatch = root.onAnchorChange(() => this._followAnchor());
+  }
+
+  _unwatchAnchor() {
+    this._anchorWatch?.();
+    this._anchorWatch = null;
+  }
+
+  /**
+   * Subscribe to "something this window's popups might be anchored to just
+   * moved" — a real layout pass (a trigger's own position changing: text
+   * wrapping, a sibling growing, an ancestor viewport scrolling — scroll
+   * offset is applied during absolutize, so it is a layout change too) or a
+   * fresh `_screenOrigin` (the window manager or a script moving this window).
+   * Returns an unsubscribe function.
+   *
+   * Event-driven off the same signals `flush()` and `_refreshScreenOrigin()`
+   * already track internally, rather than a polling loop: costs nothing
+   * between real changes, and `useAnchor`'s tracking hook (`anchor.js`) is
+   * what turns this into a popup that follows its trigger instead of hanging
+   * over stale ground once opened.
+   */
+  onAnchorChange(cb) {
+    (this._anchorListeners ??= new Set()).add(cb);
+    return () => this._anchorListeners?.delete(cb);
+  }
+
+  _notifyAnchorChange() {
+    if (!this._anchorListeners?.size) return;
+    for (const cb of this._anchorListeners) cb();
+  }
+}

package/src/nodes/window/capabilities.js

@@ -0,0 +1,190 @@
+// What a window can paint: compositing and ARGB transparency, the window
+// background, and the capabilities `@supports` blocks read.
+
+import { cssColorStraight } from 'ntk';
+import {
+  argbVisual,
+  compositingActive,
+  transparencyDisabled,
+  watchCompositing,
+} from '../../compositing.js';
+import { DEV } from '../util.js';
+
+/**
+ * A CSS colour as an X pixel value.
+ *
+ * The 24-bit TrueColor layout, which is what `redMask`/`greenMask`/`blueMask`
+ * say on every server a client meets today and what ntk's own ARGB visual
+ * uses. Alpha is dropped: this is the *window background attribute*, a single
+ * opaque pixel the server repeats, not something composited.
+ */
+export function pixelFor(color) {
+  const rgba = cssColorStraight(color);
+  if (!rgba) return null;
+  const [r, g, b] = rgba;
+  const byte = (c) => Math.max(0, Math.min(255, Math.round(c * 255)));
+  return ((byte(r) << 16) | (byte(g) << 8) | byte(b)) >>> 0;
+}
+
+// Connections already told they have no 32-bit visual (`_argbAttributes`).
+const warnedNoArgb = new WeakSet();
+
+/**
+ * `boxShadow` on a `<window>`/`<popup>`, warned about once.
+ *
+ * A shadow falls *outside* the box, and outside a toplevel there is nothing
+ * of ours to paint on — the pixels belong to the desktop. Doing it properly
+ * means the window asking for a translucent margin it does not otherwise
+ * want (an ARGB visual, a bigger X window, and hit testing that knows the
+ * difference), which is a feature of its own rather than a line in the
+ * painter. Said out loud because the alternative is a style that reads as
+ * ignored for no reason.
+ */
+let warnedWindowShadow = false;
+export function devWarnWindowShadow(kind) {
+  if (warnedWindowShadow) return;
+  warnedWindowShadow = true;
+  console.warn(
+    `react-x11: boxShadow on <${kind}> is ignored — a shadow is painted ` +
+      'outside the box, and a toplevel window owns no pixels there. Put the ' +
+      'shadow on a <box> inside it, or draw the window with a translucent ' +
+      'margin of its own (docs/styling.md).',
+  );
+}
+
+/** What the window can paint, installed onto `WindowNode.prototype` by window.js. */
+export class WindowCapabilities {
+  /**
+   * What this window can actually do, for `@supports` blocks to read and for
+   * the paint path to obey. Read-only to callers; recomputed by
+   * `_refreshCapabilities`.
+   */
+  get capabilities() {
+    return this._capabilities;
+  }
+
+  /**
+   * Will transparency actually be *seen*? Both halves have to hold: the
+   * window needs an alpha channel to write, and something has to be
+   * compositing it. Miss either and a cleared corner is a black corner, so
+   * the paint path fills opaque instead.
+   *
+   * This is deliberately not the same question as "was `transparent` asked
+   * for". A visual is fixed at CreateWindow and cannot follow a compositor
+   * that starts or stops mid-session; what it paints can, and does.
+   */
+  get transparencyEffective() {
+    return this._capabilities.transparency;
+  }
+
+  /**
+   * Recompute, and if the answer moved, re-resolve every `@supports` block
+   * under this window and repaint. Returns whether anything changed.
+   */
+  _refreshCapabilities() {
+    const transparency = this._transparent && compositingActive(this.app);
+    if (transparency === this._capabilities.transparency) return false;
+    // a new object rather than a mutation: `resolveQueries` may have handed
+    // this map to a memoized style, and identity is how that stays honest
+    this._capabilities = { ...this._capabilities, transparency };
+    // The window's own style first, and separately: it resolves its style
+    // in the Node constructor, before `root` exists to register against, so
+    // it is not in its own registry on the pass that matters — the one
+    // realize() triggers once the visual is known.
+    if (this._supportsQueried) this._sizeQueriesChanged();
+    for (const node of [...this._supportsQueryNodes]) {
+      if (node.destroyed) this._supportsQueryNodes.delete(node);
+      else if (node !== this) node._sizeQueriesChanged();
+    }
+    // The window's own background is not a styled node and has no query
+    // block to re-resolve — it reads `transparencyEffective` directly, so
+    // it just needs the repaint.
+    this.invalidate(true, null, 'capabilities');
+    return true;
+  }
+
+  /**
+   * Follow the compositor for the life of the window. A menu that was opaque
+   * because nothing was compositing becomes a rounded translucent one the
+   * moment something is, with no remount — which is the whole reason the
+   * ARGB visual is taken even when no compositor is running yet.
+   */
+  _watchCapabilities() {
+    this._refreshCapabilities();
+    this._unwatchCompositing ??= watchCompositing(this.app, () => {
+      if (!this.destroyed) this._refreshCapabilities();
+    });
+  }
+
+  /**
+   * Creation attributes for a per-pixel transparent window: a 32-bit
+   * TrueColor visual, and a background of transparent black rather than the
+   * server's white, so nothing flashes before the first paint. ntk gives the
+   * window its own colormap and border pixel to go with the visual —
+   * inheriting either from a parent of a different depth is a BadMatch.
+   *
+   * Empty when the display has no such visual (XQuartz has none) or ntk is
+   * too old to find one, and then `_transparent` stays false and the window
+   * paints its background opaque, exactly as it did before. A transparent
+   * window that cannot be transparent is a square opaque one, not a broken
+   * one — and the alternative, black corners, is worse than square.
+   */
+  /** What this window paints as its background — its own, or the palette's. */
+  _windowBackground() {
+    return this.style.backgroundColor || this.theme.background;
+  }
+
+  /**
+   * Keep the server's idea of the background in step with ours. Called when
+   * the palette moves under an unstyled window and when the style names a new
+   * colour; a `transparent` window keeps its 0, which means transparent.
+   */
+  _syncWindowBackground() {
+    if (this._transparent || !this.window || this.destroyed) return;
+    const pixel = pixelFor(this._windowBackground());
+    if (pixel === null || pixel === this._backgroundPixel) return;
+    if (this.app?.X?._closing) return;
+    this._backgroundPixel = pixel;
+    // One call for both halves, because a double-buffered window has two
+    // backgrounds: the X window attribute the server paints into exposed
+    // area, and the colour ntk's backing store clears the part a resize
+    // grows into. They used to be free to disagree — the backing store
+    // cleared to the screen's white whatever the window said — which is why
+    // enlarging a dark window flashed a white strip that survived until
+    // something damaged it (ntk#209, 6.6.1).
+    this.window.setBackgroundPixel?.(pixel);
+  }
+
+  _argbAttributes() {
+    const argb = argbVisual(this.app);
+    if (!argb) {
+      // Once per connection. The answer is a property of the display (or of
+      // an environment switch) and cannot change while it is open, and since
+      // the widgets ask for a transparent popup every time a menu or a
+      // tooltip opens, warning per window would turn one piece of news into
+      // a running commentary.
+      if (DEV && this.app && !warnedNoArgb.has(this.app)) {
+        warnedNoArgb.add(this.app);
+        const what = this.isPopup ? 'popup' : 'window';
+        if (transparencyDisabled()) {
+          console.warn(
+            'react-x11: REACT_X11_NO_TRANSPARENCY=1 — <%s transparent> ' +
+              'ignored, this run is opaque',
+            what,
+          );
+        } else {
+          console.warn(
+            'react-x11: <%s transparent> — no 32-bit TrueColor visual on ' +
+              'this display, falling back to an opaque window',
+            what,
+          );
+        }
+      }
+      return null;
+    }
+    // What the paint path keys off: the window really does have an alpha
+    // channel, so clearing it means transparent rather than white.
+    this._transparent = true;
+    return { ...argb, backgroundPixel: 0 };
+  }
+}

package/src/nodes/window/debugpaint.js

@@ -0,0 +1,83 @@
+// Debug overlays: REACT_X11_DEBUG_PAINT's damage flashes, and DevTools'
+// highlight and trace-updates outlines.
+
+// REACT_X11_DEBUG_PAINT: each frame strokes its damage rects in the next of
+// these, so a region repainting every frame strobes visibly.
+export const FLASH_COLORS = [
+  '#e6194b',
+  '#3cb44b',
+  '#ffe119',
+  '#4363d8',
+  '#f58231',
+  '#911eb4',
+];
+
+// REACT_X11_DEBUG_PAINT, read once: a process.env read is a real
+// environment lookup, and this switch sits on invalidate() and the paint
+// loop — the diagnostics must cost nothing when they are off. Indirected
+// like the animation clock so tests can flip it without a subprocess.
+export let debugPaint = process.env.REACT_X11_DEBUG_PAINT || '';
+export function setDebugPaint(mode) {
+  debugPaint = mode || '';
+}
+
+/** Debug overlays, installed onto `WindowNode.prototype` by window.js. */
+export class WindowDebugPaint {
+  /** DevTools hover highlight: tint a node's rect on the next paint. */
+  setHighlight(node) {
+    if (this._highlight === node) return;
+    const prev = this._highlight;
+    this._highlight = node;
+    // The tint leaves one rect and lands on another, and both are already
+    // known, so the claim is their union rather than the window. A side
+    // with no laid-out rect tints (or tinted) the whole window — the same
+    // fallback _paintRegion paints — so only that case stays unbounded.
+    const rects = [];
+    for (const n of [prev, node]) {
+      if (!n) continue;
+      if (!n.abs?.width) {
+        this.invalidate(false, null, 'highlight');
+        return;
+      }
+      rects.push(n.abs);
+    }
+    for (const rect of rects) this.invalidate(false, rect, 'highlight');
+  }
+
+  /**
+   * DevTools' "highlight updates when components render": outline the rects
+   * that just re-rendered, in the colour the backend assigned each one (it
+   * ramps with the update count and fades them out on its own clock, so
+   * this is a dumb overlay — `rects` is the whole state, `null` clears it).
+   */
+  setTraceUpdates(rects) {
+    const previous = this._traceUpdates;
+    const next = rects?.length ? rects : null;
+    if (!previous && !next) return;
+    this._traceUpdates = next;
+    // The stroke sits inside the rect, but a rect whose node has since
+    // moved or gone claims where it *was*; both lists are claimed for the
+    // same reason setHighlight claims both of its rects.
+    for (const r of [...(previous ?? []), ...(next ?? [])]) {
+      this.invalidate(false, r, 'trace-updates');
+    }
+  }
+
+  /** REACT_X11_DEBUG_LAYOUT=1: outline every drawn node, color by depth. */
+  _paintDebugOverlay(ctx, node, depth) {
+    const colors = ['#e74c3c', '#27ae60', '#2980b9', '#8e44ad', '#f39c12'];
+    for (const child of node.paintOrder()) {
+      ctx.strokeStyle = colors[depth % colors.length];
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.rect(
+        child.abs.x + 0.5,
+        child.abs.y + 0.5,
+        child.abs.width - 1,
+        child.abs.height - 1,
+      );
+      ctx.stroke();
+      this._paintDebugOverlay(ctx, child, depth + 1);
+    }
+  }
+}

package/src/nodes/window/droptarget.js

@@ -0,0 +1,145 @@
+// The window's half of XDND (docs/architecture/drag-and-drop.md): the drop
+// targets registered under it and the types they accept.
+
+import {
+  DropSession,
+  dndAtoms,
+  registerTopLevel,
+  XDND_VERSION,
+} from '../../dnd.js';
+import { TYPE_GROUPS } from '../../transfer.js';
+
+/** The window's half of XDND, installed onto `WindowNode.prototype` by window.js. */
+export class WindowDropTarget {
+  /**
+   * XDND drop-target wiring (src/dnd.js): write `XdndAware = 5`, start the
+   * atom interning, and route incoming ClientMessages to the session.
+   * Unconditional — the property is 4 bytes on a window that exists anyway,
+   * and advertising lazily would race sources that cache the window list
+   * at drag start. A window with no registered drop targets answers "not
+   * accepting" once per entry instead (DropSession).
+   *
+   * The one exception is a `<popup dragPreview>`. It follows the pointer,
+   * so for the whole gesture it is the frontmost window under it, and it
+   * must never be what the drag is over. Where react-x11 picks the target
+   * itself (src/dnd.js `topLevelAt`) it is skipped by name. Where the OS
+   * picks, registering nothing is not enough: AppKit finds the window
+   * under the pointer first and does not look past one with no dragged
+   * types — the drag then has no destination at all — so the cocoa window
+   * is made transparent to the pointer instead (src/cocoa/window.js,
+   * `ignoresMouseEvents`, #488). A preview still gets none of this: no
+   * session, no registry entry, no property, nothing to refuse with.
+   */
+  _initDnd() {
+    if (this.props.dragPreview) return;
+    const wnd = this.window;
+    const X = this.app?.X;
+    // A backend with drop machinery of its own (the cocoa backend's
+    // NSDraggingDestination, src/cocoa/dnd.js): the same DropSession, driven
+    // through its local entry points by the window's transport instead of
+    // by XDND ClientMessages. No property to write, nothing to intern.
+    if (typeof wnd?.attachDropTransport === 'function') {
+      this._dnd = new DropSession(this);
+      registerTopLevel(this);
+      wnd.attachDropTransport(this._dnd, this);
+      return;
+    }
+    if (
+      !X ||
+      typeof X.InternAtom !== 'function' ||
+      typeof wnd.on !== 'function' ||
+      typeof wnd.setProperty !== 'function'
+    ) {
+      return; // mock app, or an ntk too old to write raw properties
+    }
+    this._dnd = new DropSession(this);
+    registerTopLevel(this);
+    void dndAtoms(X).catch(() => {});
+    wnd
+      .setProperty('XdndAware', [XDND_VERSION], { type: 'ATOM' })
+      .catch(() => {});
+    wnd.on('message', (ev) => {
+      // XDND is a *default action* on a ClientMessage, so it follows the same
+      // rule every other one does: it runs after the application's handler
+      // and is skipped when that handler called `preventDefault()`. That is
+      // the seam for a window answering the drag protocol itself.
+      //
+      // `_attachWindowListeners` subscribed to this stream first, so normally
+      // the flag is already decided by the time this runs. `pending()` is the
+      // exception it cannot cover: a message whose type had to be named with
+      // a round trip is dispatched a few turns later, and answering the drag
+      // before the application has been asked would make `preventDefault()`
+      // depend on whether an atom happened to be cached.
+      const said = this._clientMessages?.pending();
+      const route = () => {
+        if (ev.defaultPrevented) return;
+        this._dnd.handleMessage(ev);
+        // a drag *out* of this window gets its XdndStatus/XdndFinished back
+        // on the same channel
+        this._dragSession?.handleMessage(ev);
+      };
+      if (said) said.then(route);
+      else route();
+    });
+  }
+
+  /** Nodes with drop props register with their root; the count gates the
+   * whole-window "not accepting" fast path. Child <window>s roll up into
+   * their top-level's count, since that is where the messages arrive. */
+  _registerDropTarget(node) {
+    (this._dropTargets ??= new Set()).add(node);
+    this._dndTopLevel()?.window?.dropTargetsChanged?.();
+  }
+
+  _forgetDropTarget(node) {
+    this._dropTargets?.delete(node);
+    this._dndOwner()?.forget(node);
+    this._dndTopLevel()?.window?.dropTargetsChanged?.();
+  }
+
+  /** The top-level whose drop session — and transport — this window's
+   * targets roll up into. */
+  _dndTopLevel() {
+    let node = this;
+    while (node && !node._dnd) node = node.parent?.root;
+    return node ?? null;
+  }
+
+  /** The concrete type names every `dropAccept` under this top-level asks
+   * for — what a backend that registers its accepted types up front (the
+   * cocoa backend) adds to its base set. Groups and predicates name none. */
+  _dndConcreteTypes() {
+    const out = new Set();
+    const walk = (wn) => {
+      for (const node of wn._dropTargets ?? []) {
+        const accept = node.props.dropAccept;
+        for (const entry of Array.isArray(accept) ? accept : []) {
+          if (typeof entry === 'string' && !(entry in TYPE_GROUPS)) {
+            out.add(entry);
+          }
+        }
+      }
+      for (const child of wn.children) {
+        if (child.isWindow && !child.isPopup) walk(child);
+      }
+    };
+    walk(this);
+    return [...out];
+  }
+
+  _dndTargetCount() {
+    let count = this._dropTargets?.size ?? 0;
+    for (const child of this.children) {
+      if (child.isWindow && !child.isPopup) count += child._dndTargetCount();
+    }
+    return count;
+  }
+
+  /** The session that owns drags over this window: its own for a
+   * top-level, the enclosing top-level's for a nested <window>. */
+  _dndOwner() {
+    let node = this;
+    while (node && !node._dnd) node = node.parent?.root;
+    return node?._dnd ?? null;
+  }
+}