react-x11 2.10.2 → 2.12.0

package/src/nodes/hittest.js

@@ -0,0 +1,185 @@
+// Hit testing, and the geometry a node reports about itself: containsPoint
+// with and without slop, hitTest down the paint order, getClientRects, and
+// the box-model measure DevTools reads.
+
+import { resolveHitSlop } from '../styles.js';
+
+/** Hit testing, installed onto `Node.prototype` by node.js. */
+export class NodeHitTest {
+  containsPoint(x, y) {
+    return (
+      x >= this.abs.x &&
+      y >= this.abs.y &&
+      x < this.abs.x + this.abs.width &&
+      y < this.abs.y + this.abs.height
+    );
+  }
+
+  /**
+   * The same test grown by `hitSlop`. Deliberately separate from
+   * `containsPoint`: slop belongs to *this* node's target and nothing else,
+   * so it must not widen the rect that clips this node's children, must not
+   * reach `paintBounds`, and must never touch yoga. A 16px slider with 4px
+   * of slop top and bottom is a 24px target that still draws 16px tall,
+   * which is the whole point — WCAG 2.2 SC 2.5.8 without a redesign.
+   *
+   * The slop can overlap a sibling's box. Hit testing is front-to-back over
+   * paint order, so the sibling on top keeps its own pixels either way.
+   */
+  containsPointWithSlop(x, y) {
+    if (this.containsPoint(x, y)) return true;
+    const slop = resolveHitSlop(this.style.hitSlop);
+    if (!slop) return false;
+    return (
+      x >= this.abs.x - slop.left &&
+      y >= this.abs.y - slop.top &&
+      x < this.abs.x + this.abs.width + slop.right &&
+      y < this.abs.y + this.abs.height + slop.bottom
+    );
+  }
+
+  /** DOM-ish rect accessor. React DevTools' Highlighter requires host
+   * instances to expose getClientRects() with a non-empty rect before it
+   * emits showNativeHighlight — without this, hovering the tree silently
+   * no-ops. Anything with getClientRects is also measured at mount via
+   * `instance.ownerDocument.documentElement` (see ownerDocument below). */
+  getClientRects() {
+    const r = this.abs;
+    if (!(r.width > 0 || r.height > 0)) return [];
+    // `abs` is device pixels; this is public API, which is logical — the
+    // same conversion events make on the way out (src/scale.js)
+    const s = this.scale;
+    return [
+      {
+        x: r.x / s,
+        y: r.y / s,
+        left: r.x / s,
+        top: r.y / s,
+        width: r.width / s,
+        height: r.height / s,
+        right: (r.x + r.width) / s,
+        bottom: (r.y + r.height) / s,
+      },
+    ];
+  }
+
+  /**
+   * React Native's measure contract, which is what DevTools' style editor
+   * calls to draw the box model beside the style it is editing:
+   * `(x, y, width, height, left, top)` — position within the parent, size,
+   * then position within the window. A node with no laid-out rect calls
+   * back with nothing, the "unmeasurable" answer the editor checks for.
+   */
+  measure(callback) {
+    if (typeof callback !== 'function') return;
+    const r = this.abs;
+    if (!(r.width > 0 || r.height > 0)) {
+      callback();
+      return;
+    }
+    const s = this.scale;
+    const parent = this.parent?.abs;
+    callback(
+      (parent ? r.x - parent.x : r.x) / s,
+      (parent ? r.y - parent.y : r.y) / s,
+      r.width / s,
+      r.height / s,
+      r.x / s,
+      r.y / s,
+    );
+  }
+
+  /**
+   * The rect a hit anywhere in this subtree must fall inside: this node's
+   * rect grown by its own hitSlop, unioned with every child's reach —
+   * except under a clipping node, whose children can only be hit while the
+   * point is inside its rect (hitTest never descends from outside one).
+   *
+   * A conservative superset, and only ever that: hidden and
+   * pointerEvents-none subtrees are counted anyway, and nothing shrinks a
+   * cached bound before the next invalidation. A bound too big costs a
+   * walk; one too small would drop real input. Every change that can
+   * *grow* the true reach funnels through `_clearHitBounds`: `_assignAbs`
+   * for whatever layout moves (mounts, reveals and scrolls all change
+   * `abs`), `_retarget` for `hitSlop` and `overflow`, `_childListChanged`
+   * for a subtree attached with its rect already laid out, and `flush`
+   * for the root's own rect, which is written without `_assignAbs`.
+   */
+  _hitBounds() {
+    let b = this._hitBoundsCache;
+    if (b) return b;
+    const abs = this.abs;
+    const slop = resolveHitSlop(this.style.hitSlop);
+    let left = abs.x;
+    let top = abs.y;
+    let right = abs.x + abs.width;
+    let bottom = abs.y + abs.height;
+    if (slop) {
+      left -= slop.left;
+      top -= slop.top;
+      right += slop.right;
+      bottom += slop.bottom;
+    }
+    if (!this.clipsChildren()) {
+      for (const child of this.children) {
+        if (child.isWindow || !child.yoga) continue;
+        const cb = child._hitBounds();
+        if (cb.left < left) left = cb.left;
+        if (cb.top < top) top = cb.top;
+        if (cb.right > right) right = cb.right;
+        if (cb.bottom > bottom) bottom = cb.bottom;
+      }
+    }
+    b = { left, top, right, bottom };
+    this._hitBoundsCache = b;
+    return b;
+  }
+
+  /**
+   * This node's reach changed: drop the cached bounds here and up the
+   * chain of ancestors whose unions embed them. The walk stops at a
+   * clipping ancestor — its reach is its own rect, so nothing below it
+   * changes what it or anything above it reports — or at one already
+   * invalid, whose own clear walked the rest of the way up.
+   */
+  _clearHitBounds() {
+    // what moves a hit reach moves the paint reach — first, because the
+    // walk below returns from wherever it finds an ancestor already clear
+    this._clearPaintBounds();
+    this._hitBoundsCache = null;
+    for (let n = this.parent; n; n = n.parent) {
+      if (n.clipsChildren() || n._hitBoundsCache === null) return;
+      n._hitBoundsCache = null;
+    }
+  }
+
+  /** Front-to-back hit test. Returns the deepest hit node or null. */
+  hitTest(x, y) {
+    if (
+      this.hidden ||
+      this.style.display === 'none' ||
+      this.style.pointerEvents === 'none'
+    ) {
+      return null;
+    }
+    // nothing in this subtree reaches the point: skip it whole, children
+    // and all — this is what keeps a motion event from walking every node
+    // in the window (issue #188)
+    const b = this._hitBounds();
+    if (x < b.left || y < b.top || x >= b.right || y >= b.bottom) {
+      return null;
+    }
+    const inside = this.containsPoint(x, y);
+    // the children are culled on the strict rect — slop grows this node's
+    // target, not the region its clip lets through
+    if (!inside && this.clipsChildren()) {
+      return this.containsPointWithSlop(x, y) ? this : null;
+    }
+    const order = this.paintOrder();
+    for (let i = order.length - 1; i >= 0; i--) {
+      const hit = order[i].hitTest(x, y);
+      if (hit) return hit;
+    }
+    return inside || this.containsPointWithSlop(x, y) ? this : null;
+  }
+}

package/src/nodes/image.js

@@ -0,0 +1,266 @@
+// <image>: an image source, loaded or decoded, sized from its intrinsic size
+// and drawn into the node's box.
+
+import {
+  DrawableSource,
+  PictureSource,
+  acquireImageSource,
+  decodeImageSource,
+  imageSourceChanged,
+  isDirectImageSource,
+  isPathImageSource,
+  isRawImageSource,
+  releaseImageSource,
+  toLoadablePath,
+  validateImageProps,
+} from '../imagesource.js';
+// Namespace import for `Surface`, the same shape and the same reason as
+// `paintcache.js`: a named import of something an older ntk does not export
+// is a *load-time* SyntaxError, which would take the renderer down rather
+// than the one feature that needs it.
+import * as ntk from 'ntk';
+import { intrinsicSize } from './layout.js';
+import { Node } from './node.js';
+import { DEV } from './util.js';
+
+/** The props `ImageNode.applyProps` diffs by value itself, kept out of the
+ * base class's identity walk — a buffer rebuilt under an unchanged
+ * `cacheKey` and a `{ id, … }` descriptor rebuilt with the same numbers are
+ * both "nothing changed". */
+const IMAGE_SOURCE_PROPS = new Set(['src', 'picture', 'drawable', 'cacheKey']);
+
+export class ImageNode extends Node {
+  constructor(props, app) {
+    super('image', props, app);
+    validateImageProps(props);
+    this.image = null;
+    this._loadToken = 0;
+    /** hold on the `cacheKey` cache entry, when one is held */
+    this._hold = null;
+    /** an Image decoded for this node alone (no cacheKey), freed on release */
+    this._ownedImage = null;
+    /** PictureSource/DrawableSource, when the source is server-side */
+    this._serverSource = null;
+    // Resolution waits for the first layout/paint: the constructor runs in
+    // the render phase, which React may discard, and resolving here would
+    // start file reads and take cache holds nothing would ever release.
+    this._sourceDirty = true;
+  }
+
+  get selfDamagedProps() {
+    return IMAGE_SOURCE_PROPS;
+  }
+
+  paintChanged(next, prev) {
+    return imageSourceChanged(next, prev) || super.paintChanged(next, prev);
+  }
+
+  /** The source's size, kept to its aspect ratio. Read per measure rather
+   * than once, because a decode can arrive late.
+   *
+   * Source pixels are *logical* pixels, the browser's rule: a 100px-wide
+   * PNG occupies 100 logical px at any display scale (upscaled onto the
+   * device grid at 2x, the way an `<img>` without `srcset` is), rather
+   * than shrinking to half its neighbours' size. The constraints are
+   * already device, so only the natural size converts (src/scale.js). */
+  measureContent(constraints) {
+    this._ensureSource();
+    const s = this.scale;
+    return intrinsicSize(
+      {
+        width: (this.image?.width ?? 0) * s,
+        height: (this.image?.height ?? 0) * s,
+      },
+      constraints,
+    );
+  }
+
+  /** First layout or paint after a mount or a source change — both run
+   * after commit, so an instance a concurrent render threw away never
+   * resolves anything. */
+  _ensureSource() {
+    if (!this._sourceDirty || this.destroyed) return;
+    this._sourceDirty = false;
+    this._resolveSource();
+  }
+
+  _resolveSource() {
+    const { src, picture, drawable, cacheKey } = this.props;
+    if (picture != null || drawable != null) {
+      this._serverSource =
+        picture != null
+          ? new PictureSource(this.app, picture)
+          : new DrawableSource(this.app, drawable);
+      this.image = this._serverSource;
+      return;
+    }
+    if (src == null) return;
+    if (isDirectImageSource(src)) {
+      // the caller's object — its upload cache is the dedupe, and it is
+      // never destroyed here
+      this.image = src;
+      return;
+    }
+    if (cacheKey != null) {
+      const entry = acquireImageSource(this.app, cacheKey, () =>
+        this._loadEntry(src),
+      );
+      this._hold = entry;
+      if (entry.image) {
+        this.image = entry.image;
+        if (DEV) this._devCheckCacheKey(src, entry.image, cacheKey);
+      } else {
+        entry.promise?.then((image) => {
+          if (image && this._hold === entry && !this.destroyed) {
+            this._setImage(image);
+          }
+        });
+      }
+      return;
+    }
+    if (isPathImageSource(src)) {
+      this._loadFile(src);
+      return;
+    }
+    const image = this._decode(src);
+    if (image) {
+      this._ownedImage = image;
+      this.image = image;
+    }
+  }
+
+  /** `{ image }` or `{ promise }` for the cache. Failures resolve to null
+   * and are reported once, here — not per node holding the key. */
+  _loadEntry(src) {
+    if (isPathImageSource(src)) {
+      return {
+        promise: ntk.loadImage(toLoadablePath(src)).then(
+          (image) => image,
+          (err) => {
+            console.error(
+              `react-x11: failed to load image ${src}:`,
+              err.message,
+            );
+            return null;
+          },
+        ),
+      };
+    }
+    return { image: this._decode(src) };
+  }
+
+  _decode(src) {
+    try {
+      return decodeImageSource(src);
+    } catch (err) {
+      // corrupt or unrecognized bytes are a content failure, not a
+      // programming error: log and show nothing, like a missing file
+      console.error(
+        'react-x11: <image src> bytes did not decode:',
+        err.message,
+      );
+      return null;
+    }
+  }
+
+  async _loadFile(src) {
+    const token = ++this._loadToken;
+    try {
+      const image = await ntk.loadImage(toLoadablePath(src));
+      if (token !== this._loadToken || this.destroyed) return;
+      this._ownedImage = image;
+      this._setImage(image);
+    } catch (err) {
+      if (token === this._loadToken && !this.destroyed) {
+        console.error(`react-x11: failed to load image ${src}:`, err.message);
+      }
+    }
+  }
+
+  /** Adopt pixels that arrived after the frame that asked for them. A size
+   * change reflows; same-size new pixels claim only this node's box. */
+  _setImage(image) {
+    const prev = this.image;
+    this.image = image;
+    if (
+      (prev?.width ?? 0) !== (image?.width ?? 0) ||
+      (prev?.height ?? 0) !== (image?.height ?? 0)
+    ) {
+      this.invalidateMeasure('content');
+    } else {
+      this.root?.invalidate(false, this, 'content');
+    }
+  }
+
+  /** Two different pictures sharing one cacheKey is the one mistake this
+   * design can make show stale pixels; the raw form carries enough to catch
+   * the common case cheaply. */
+  _devCheckCacheKey(src, image, key) {
+    if (!isRawImageSource(src)) return;
+    if (src.width === image.width && src.height === image.height) return;
+    console.error(
+      `react-x11: <image cacheKey=${JSON.stringify(key)}> is ` +
+        `${image.width}x${image.height} in the cache, but this src says ` +
+        `${src.width}x${src.height}. Two different pictures are sharing one ` +
+        'cacheKey — the key must name the content, so include whatever ' +
+        'distinguishes them.',
+    );
+  }
+
+  _releaseSource() {
+    this._loadToken++; // orphan any in-flight file read
+    if (this._hold) {
+      releaseImageSource(this.app, this._hold);
+      this._hold = null;
+    }
+    if (this._ownedImage) {
+      // frees the per-app upload; the caller's own Images are never here
+      this._ownedImage.destroy();
+      this._ownedImage = null;
+    }
+    if (this._serverSource) {
+      this._serverSource.destroy?.();
+      this._serverSource = null;
+    }
+    this.image = null;
+  }
+
+  applyProps(newProps, oldProps) {
+    const before = oldProps ?? this.props;
+    const sourceChanged = imageSourceChanged(newProps, before);
+    // before super touches anything, so a bad update leaves the node whole
+    if (sourceChanged) validateImageProps(newProps);
+    super.applyProps(newProps, oldProps);
+    if (!sourceChanged) return;
+    const prev = this.image;
+    this._releaseSource();
+    this._sourceDirty = false;
+    this._resolveSource();
+    // paintChanged already claimed this node's box through super; only a
+    // new intrinsic size needs more than that
+    if (
+      (prev?.width ?? 0) !== (this.image?.width ?? 0) ||
+      (prev?.height ?? 0) !== (this.image?.height ?? 0)
+    ) {
+      this.invalidateMeasure('content');
+    }
+  }
+
+  destroySubtree() {
+    this._releaseSource();
+    super.destroySubtree();
+  }
+
+  paintContent(ctx) {
+    this._ensureSource();
+    if (!this.image) return;
+    const content = this.contentBox();
+    ctx.drawImage(
+      this.image,
+      content.x,
+      content.y,
+      content.width,
+      content.height,
+    );
+  }
+}

package/src/nodes/install.js

@@ -0,0 +1,75 @@
+// Puts a concern's methods onto the class they belong to.
+//
+// The node classes are split by concern rather than by class: the scroll
+// blit's methods live in scrollblit.js whether they are Node's or
+// WindowNode's, the paint walk's in paint.js, and so on. Each concern writes
+// its methods as the body of a class that is never instantiated — a part —
+// and the class's own file installs its parts right after declaring it:
+//
+//   installMethods(Node, NodeStyling, NodeCascade, …);
+//
+// What the class ends up with is what one class body would have given it: the
+// same function objects, as non-enumerable properties of the same prototype.
+// Anything that compares against a prototype (`node.paint !==
+// Node.prototype.paint`) or overrides a method in a subclass sees no
+// difference.
+//
+// Two guards keep the arrangement safe to edit. A name defined twice — in the
+// class and a part, or in two parts — throws while the module loads, instead
+// of whichever ran last silently winning. And each part's prototype is
+// re-parented onto the class's parent, so `super` in a moved method means
+// what it meant in the class body.
+
+/** part -> the class it was installed onto */
+const installed = new WeakMap();
+
+/** prototype -> (key -> the part that defined it) */
+const origins = new WeakMap();
+
+/**
+ * Install each part's methods and accessors onto `target.prototype`.
+ *
+ * @param {Function} target the class
+ * @param {...Function} parts classes whose bodies hold the rest of its methods
+ */
+export function installMethods(target, ...parts) {
+  const proto = target.prototype;
+  const parent = Object.getPrototypeOf(proto);
+  if (!origins.has(proto)) origins.set(proto, new Map());
+  const defined = origins.get(proto);
+  for (const part of parts) {
+    if (installed.has(part)) {
+      throw new Error(
+        `react-x11: ${part.name} is already installed onto ` +
+          `${installed.get(part).name}; a part belongs to exactly one class.`,
+      );
+    }
+    const keys = Reflect.ownKeys(part.prototype).filter(
+      (key) => key !== 'constructor',
+    );
+    for (const key of keys) {
+      if (Object.hasOwn(proto, key)) {
+        const first = defined.get(key) ?? `the ${target.name} class body`;
+        throw new Error(
+          `react-x11: ${target.name}.${String(key)} is defined twice, in ` +
+            `${first} and in ${part.name}. A method lives in exactly one ` +
+            `file under src/nodes/ — rename one of them, or delete it.`,
+        );
+      }
+    }
+    Object.setPrototypeOf(part.prototype, parent);
+    for (const key of keys) {
+      Object.defineProperty(
+        proto,
+        key,
+        Object.getOwnPropertyDescriptor(part.prototype, key),
+      );
+      defined.set(key, part.name);
+    }
+    installed.set(part, target);
+  }
+}
+
+/** The class `part` was installed onto, or undefined: what the test that
+ *  every part under src/nodes/ is installed somewhere reads. */
+export const installedOnto = (part) => installed.get(part);