react-x11 2.15.2 → 2.16.0

package/src/nodes/image.js

@@ -6,10 +6,12 @@ import {
   PictureSource,
   acquireImageSource,
   decodeImageSource,
+  freeImage,
   imageSourceChanged,
   isDirectImageSource,
   isPathImageSource,
   isRawImageSource,
+  isSymbolImageSource,
   releaseImageSource,
   toLoadablePath,
   validateImageProps,
@@ -19,6 +21,7 @@ import {
 // 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 { symbolWeight, symbolsFor, warnOnce } from '../symbols.js';
 import { intrinsicSize } from './layout.js';
 import { Node } from './node.js';
 import { DEV } from './util.js';
@@ -41,6 +44,8 @@ export class ImageNode extends Node {
     this._ownedImage = null;
     /** PictureSource/DrawableSource, when the source is server-side */
     this._serverSource = null;
+    /** `{ symbol, … }`, when the source is a name the platform draws */
+    this._symbol = 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.
@@ -66,6 +71,25 @@ export class ImageNode extends Node {
   measureContent(constraints) {
     this._ensureSource();
     const s = this.scale;
+    if (this._symbol) {
+      const name = this._symbol.symbol;
+      const size = symbolsFor(this.app).size(name, this._symbolOptions());
+      // A name this desktop does not have takes no room and draws nothing,
+      // which is right for an app that runs on both and wrong for a typo —
+      // development tells the two apart for it.
+      if (!size) {
+        warnOnce(
+          `react-x11: <image src={{ symbol: ${JSON.stringify(name)} }}> is ` +
+            'not a symbol this desktop has, so it takes no room and draws ' +
+            'nothing. SF Symbols are the names on macOS, and the icon ' +
+            "theme's names, like 'audio-volume-high', elsewhere.",
+        );
+      }
+      return intrinsicSize(
+        { width: (size?.width ?? 0) * s, height: (size?.height ?? 0) * s },
+        constraints,
+      );
+    }
     return intrinsicSize(
       {
         width: (this.image?.width ?? 0) * s,
@@ -95,6 +119,12 @@ export class ImageNode extends Node {
       return;
     }
     if (src == null) return;
+    if (isSymbolImageSource(src)) {
+      // nothing to load: the platform draws the name at paint, which is also
+      // when the text colour it is drawn in is known
+      this._symbol = src;
+      return;
+    }
     if (isDirectImageSource(src)) {
       // the caller's object — its upload cache is the dedupe, and it is
       // never destroyed here
@@ -215,16 +245,36 @@ export class ImageNode extends Node {
     }
     if (this._ownedImage) {
       // frees the per-app upload; the caller's own Images are never here
-      this._ownedImage.destroy();
+      freeImage(this.app, this._ownedImage);
       this._ownedImage = null;
     }
     if (this._serverSource) {
       this._serverSource.destroy?.();
       this._serverSource = null;
     }
+    this._symbol = null;
     this.image = null;
   }
 
+  /**
+   * How a symbol is drawn beside the text around it: at that text's size and
+   * weight unless the source says otherwise — what SF Symbols are designed
+   * for, and what lets a toolbar of them follow a theme's `fontSize` — in its
+   * colour, which is `currentColor` for an `<svg>` too. Sizes are logical.
+   */
+  _symbolOptions() {
+    const text = this.resolvedTextStyle();
+    const src = this._symbol;
+    return {
+      pointSize: text.size / this.scale,
+      weight: symbolWeight(src.weight ?? text.weight),
+      scale: src.scale,
+      variableValue: src.variableValue,
+      displayScale: this.scale,
+      color: text.color,
+    };
+  }
+
   applyProps(newProps, oldProps) {
     const before = oldProps ?? this.props;
     const sourceChanged = imageSourceChanged(newProps, before);
@@ -233,12 +283,16 @@ export class ImageNode extends Node {
     super.applyProps(newProps, oldProps);
     if (!sourceChanged) return;
     const prev = this.image;
+    const wasSymbol = this._symbol;
     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
+    // new intrinsic size needs more than that — and a symbol's size is the
+    // platform's to say, so any change to one is measured again
     if (
+      wasSymbol ||
+      this._symbol ||
       (prev?.width ?? 0) !== (this.image?.width ?? 0) ||
       (prev?.height ?? 0) !== (this.image?.height ?? 0)
     ) {
@@ -253,6 +307,15 @@ export class ImageNode extends Node {
 
   paintContent(ctx) {
     this._ensureSource();
+    if (this._symbol) {
+      symbolsFor(this.app).draw(
+        ctx,
+        this._symbol.symbol,
+        this.contentBox(),
+        this._symbolOptions(),
+      );
+      return;
+    }
     if (!this.image) return;
     const content = this.contentBox();
     ctx.drawImage(

package/src/nodes/kinds.js

@@ -29,3 +29,15 @@ export const CUSTOM_SEMANTIC_NAMES = new Map();
  * arrangement as above, for the other declaration a scene-drawing element
  * makes (issue #301). */
 export const CUSTOM_SELF_DAMAGED = new Map();
+
+/**
+ * The element `<ThemeProvider>` renders to carry its palette into the node
+ * tree. Not one of `HOST_TYPES` and not documented as an element: the
+ * provider is the API. What node it becomes depends on where it is written
+ * (`createInstance`): inside a window it is a `<box>` that fills its parent —
+ * directly inside one, a `ThemeBoxNode` that also hands nested windows on to
+ * it — and at the root of the tree, above the windows, where nothing drawn
+ * may be, a `ThemeScopeNode` that draws nothing and hands the palette to the
+ * windows under it (nodes/scope.js).
+ */
+export const THEME_SCOPE = 'themescope';

package/src/nodes/layout.js

@@ -284,7 +284,11 @@ export class NodeLayout {
     // cached unions all the way up with it
     this._clearHitBounds();
     if (layoutDiff.sink) {
-      const grow = this._outlineExtent() + DAMAGE_SLOP;
+      // the reach `_ownPaintBounds` names, ring and shadow alike: a card
+      // pushed down by a row above it leaves its old shadow on the surface
+      // unless the claim for where it was covers that shadow too
+      const grow =
+        Math.max(this._outlineExtent(), this._shadowExtent()) + DAMAGE_SLOP;
       const shift = layoutDiff.shift;
       const had = old.width > 0 && old.height > 0;
       if (shift) {

package/src/nodes/node.js

@@ -34,7 +34,7 @@ import { NO_DAMAGE } from './damage.js';
 import { NodeHitTest } from './hittest.js';
 import { installMethods } from './install.js';
 import { NodeInvalidate } from './invalidate.js';
-import { CUSTOM_SELF_DAMAGED } from './kinds.js';
+import { CUSTOM_SELF_DAMAGED, THEME_SCOPE } from './kinds.js';
 import { NodeLayout } from './layout.js';
 import { NodeLayoutHost } from './layouthost.js';
 import { NodePaint } from './paint.js';
@@ -154,6 +154,9 @@ export class Node {
     // subtree's hit reach, invalidated through _clearHitBounds()
     this._paintOrderCache = null;
     this._hitBoundsCache = null;
+    // the surface an `opacity` below 1 draws this subtree through, kept from
+    // one frame to the next while it fits (`NodePaint._paintGroup`)
+    this._groupSurface = null;
     // a `$token` the theme does not define, held for `commitMount` to throw
     // on this node's own fiber — see `_tokenProblem`. Strict mode only.
     // `null` is "commitMount is still to come", `false` is "it has been and
@@ -327,9 +330,19 @@ export class Node {
       return;
     }
     if (child.isWindow) {
+      // A `<ThemeProvider>` inside a window is drawn as a box, which the
+      // developer never wrote — so the message names what they did write.
+      // Directly inside a window it passes a nested window on
+      // (nodes/scope.js, `ThemeBoxNode`); this is one further down.
       throw new Error(
-        `react-x11: <window> cannot be nested inside <${this.kind}>; ` +
-          'windows may only appear at the root or inside another <window>.',
+        this._reactFiber?.type === THEME_SCOPE
+          ? 'react-x11: a <window> under this <ThemeProvider> cannot be ' +
+              'nested — the provider is inside a <box>, where it is a box ' +
+              'itself, and a window nests only in a window. Put the ' +
+              'provider directly inside the outer <window>, or inside the ' +
+              'nested one.'
+          : `react-x11: <window> cannot be nested inside <${this.kind}>; ` +
+              'windows may only appear at the root or inside another <window>.',
       );
     }
     // A registered element that declared childrenAllowed: false says so
@@ -499,6 +512,7 @@ export class Node {
    * freed by the caller via freeRecursive on the subtree top. */
   destroySubtree() {
     this.destroyed = true;
+    if (this._groupSurface) this._releaseGroupSurface();
     // a loop outlives nothing: the window drops it from the set that keeps
     // its frame clock alive, and stops watching visibility with the last one
     this.root?._forgetLoopNode(this);

package/src/nodes/paint.js

@@ -3,6 +3,7 @@
 // window, background first.
 
 import { isPlaced } from '../layouts.js';
+import { Surface } from '../ntk.js';
 import { isPaintedColor } from './boxpaint.js';
 import { DAMAGE_SLOP } from './damage.js';
 import { DRAWN_KINDS } from './kinds.js';
@@ -97,6 +98,122 @@ export class NodePaint {
 
   paint(ctx) {
     if (this.hidden) return;
+    const opacity = this.style.opacity;
+    // A retained presenter replaying this node's own paint into a layer puts
+    // the opacity on the layer instead (src/cocoa/presenter.js), and a group
+    // drawn here as well would fade it twice.
+    if (opacity !== undefined && opacity < 1 && !this._ownPaintOnly) {
+      // Nothing to see, so nothing to draw — NaN included. The node is still
+      // laid out and still hit, as CSS's `opacity: 0` is.
+      if (!(opacity > 0)) return;
+      this._paintGroup(ctx, opacity);
+      return;
+    }
+    // back to opaque: the surface a fade drew through is not needed any more
+    if (this._groupSurface) this._releaseGroupSurface();
+    this._paintNode(ctx);
+  }
+
+  /**
+   * `opacity` below 1: this node and everything under it drawn **once**, into
+   * a surface, and composited at that alpha — so it fades as a group. An icon
+   * over its own card does not show the card through the icon, a border does
+   * not double up where it meets a background, and text keeps the colour it
+   * had. That is CSS's `opacity`, and the reason it is not a `globalAlpha` on
+   * each draw.
+   *
+   * The surface is the subtree's paint bounds inside the window — stable
+   * across frames, so a fade reuses it — and only this pass's damage is drawn
+   * into it. Where the backend makes no surfaces (the headless mock) the
+   * subtree is drawn with the alpha on each draw instead: the same pixels
+   * wherever nothing inside it overlaps.
+   */
+  _paintGroup(ctx, opacity) {
+    const rect = this._groupRect();
+    if (!rect) return;
+    const surface = this._groupSurfaceFor(rect.width, rect.height);
+    const alpha = ctx.globalAlpha ?? 1;
+    if (!surface) {
+      ctx.globalAlpha = alpha * opacity;
+      try {
+        this._paintNode(ctx);
+      } finally {
+        ctx.globalAlpha = alpha;
+      }
+      return;
+    }
+    surface.render((sctx) => {
+      sctx.clearRect(0, 0, rect.width, rect.height);
+      sctx.translate(-rect.x, -rect.y);
+      const damage = this.root?._paintDamage;
+      if (damage) {
+        sctx.beginPath();
+        sctx.rect(damage.x, damage.y, damage.width, damage.height);
+        sctx.clip();
+      }
+      this._paintNode(sctx);
+    });
+    ctx.globalAlpha = alpha * opacity;
+    try {
+      ctx.drawImage(surface, rect.x, rect.y);
+    } finally {
+      ctx.globalAlpha = alpha;
+    }
+  }
+
+  /** Where a group's surface goes: the subtree's paint bounds, on whole
+   *  pixels, cut to the window — a faded pane scrolled far off the top has
+   *  nothing of its own down there to keep. Null when none of it is on the
+   *  window at all. */
+  _groupRect() {
+    const b = this._subtreeBounds();
+    const win = this.root?.abs;
+    let x0 = Math.floor(b.x);
+    let y0 = Math.floor(b.y);
+    let x1 = Math.ceil(b.x + b.width);
+    let y1 = Math.ceil(b.y + b.height);
+    if (win) {
+      x0 = Math.max(x0, 0);
+      y0 = Math.max(y0, 0);
+      x1 = Math.min(x1, Math.ceil(win.width));
+      y1 = Math.min(y1, Math.ceil(win.height));
+    }
+    if (x1 <= x0 || y1 <= y0) return null;
+    return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+  }
+
+  /** The group surface at this size, kept from the last frame when it fits —
+   *  a fade asks for the same one every frame. Null where the backend has
+   *  none to give. */
+  _groupSurfaceFor(width, height) {
+    const kept = this._groupSurface;
+    if (kept && kept.width === width && kept.height === height) return kept;
+    if (kept) this._releaseGroupSurface();
+    const app = this.app;
+    if (!app?.display?.Render && typeof app?.createSurface !== 'function') {
+      return null;
+    }
+    try {
+      this._groupSurface = new Surface(app, { width, height });
+    } catch {
+      // no pixmap to be had: the fallback draws with the alpha instead
+      this._groupSurface = null;
+    }
+    return this._groupSurface;
+  }
+
+  _releaseGroupSurface() {
+    const surface = this._groupSurface;
+    this._groupSurface = null;
+    try {
+      surface?.destroy();
+    } catch {
+      // gone with its connection
+    }
+  }
+
+  /** Everything this node draws, and its children: `paint` minus the group. */
+  _paintNode(ctx) {
     // Outside the box and under everything, which is the whole of what makes
     // a shadow different from a colour: it is drawn before this node's own
     // background so a translucent background does not sit on top of it, and

package/src/nodes/scope.js

@@ -0,0 +1,259 @@
+// Where a `<ThemeProvider>` meets the windows. At the root of the tree: what
+// the container holds — top-level windows and popups — and the node a
+// provider written above them becomes. And directly inside a window: the box
+// a provider becomes there, which passes a nested window on to that window.
+
+import { hooks as a11yHooks } from '../a11y.js';
+import { baseTheme } from '../palette.js';
+import { BoxNode } from './box.js';
+import { THEME_SCOPE } from './kinds.js';
+import { Node } from './node.js';
+
+/**
+ * Put `node` at the top of the tree: realize a window against the screen
+ * root, and record it among the container's top-level windows — the list
+ * every "which windows does this app have" question reads
+ * (`app._rootChildren`). A theme scope puts its windows there instead of
+ * itself, so the list stays one of windows.
+ *
+ * Idempotent, because React reorders a keyed list at the root by inserting
+ * a child that is already mounted: a second entry for the same window would
+ * be a window counted twice, and announced to assistive technology twice.
+ */
+export function attachTopLevel(app, node) {
+  if (node.isThemeScope) {
+    node._attach();
+    return;
+  }
+  // realize the whole subtree top-down against the screen root
+  if (!node.window) node.realize(null);
+  // React's getPublicRootInstance answers from the root fiber's first
+  // child, and only when that child is a host component. `render()` wraps
+  // the tree in a context provider, which is not one, so it would answer
+  // null — the container keeps the list instead.
+  const roots = (app._rootChildren ??= []);
+  if (roots.includes(node)) return;
+  roots.push(node);
+  a11yHooks.rootMounted?.(node);
+}
+
+/** Take `node` back off the top of the tree, before its subtree is
+ * destroyed — the bridge reads the subtree to say what went. */
+export function detachTopLevel(app, node) {
+  if (node.isThemeScope) {
+    node._detach();
+    return;
+  }
+  const roots = app._rootChildren;
+  const at = roots ? roots.indexOf(node) : -1;
+  if (at !== -1) roots.splice(at, 1);
+  a11yHooks.rootUnmounted?.(node);
+}
+
+/**
+ * `<ThemeProvider>` above the windows (#584).
+ *
+ * A provider has to put its palette on a node, because a `$token` resolves by
+ * walking the node tree and knows nothing about React context. Inside a window
+ * that node is a `<box>`. At the root it cannot be — nothing drawn can be
+ * there, and a window cannot be inside a box — so the provider used to put
+ * the palette on the windows it could see among its children instead. It
+ * could only see literal `<window>` elements: a component that renders one,
+ * a window that is closed, a fragment of two, all planted a box at the root.
+ *
+ * This is the node for that position. It draws nothing, lays nothing out and
+ * holds only windows, popups and other scopes, and the windows under it take
+ * their palette from it: a top-level window keeps **no parent** — a window
+ * with a parent is a nested one to everything that asks, the accessibility
+ * bridge first — and reads the scope through `_scope` instead
+ * (`Node.theme`).
+ *
+ * The scope itself is never in `app._rootChildren`; its windows are, from
+ * the moment it is attached to the container (`attachTopLevel`).
+ */
+export class ThemeScopeNode extends Node {
+  constructor(props, app) {
+    super(THEME_SCOPE, props, app, { yoga: false });
+    this.isThemeScope = true;
+    // the scope this one is written inside, when providers nest at the root
+    this._scope = null;
+    // in the container: its windows are realized and on the root list
+    this._attached = false;
+    // React's hide (`<Suspense>`, `<Activity>`), which lands on the topmost
+    // host instance under the boundary — this, when the provider is there
+    this._reactHidden = false;
+  }
+
+  /**
+   * The palette the windows under this scope inherit: this scope's own
+   * `theme` over the scope around it, or over the desktop's palette.
+   *
+   * Not cached, unlike `Node.theme`. Nothing tells a scope that the
+   * desktop's palette moved — `appearanceChanged` walks the windows — and a
+   * cached merge would hand them the old base. Each window caches what it
+   * read, so this runs once per window per theme change.
+   */
+  get theme() {
+    const inherited = this._scope ? this._scope.theme : baseTheme();
+    const own = this.props.theme;
+    return own ? { ...inherited, ...own } : inherited;
+  }
+
+  insertBefore(child, beforeChild) {
+    const from = this.children.indexOf(child);
+    if (from !== -1) this.children.splice(from, 1);
+    const before =
+      beforeChild == null ? -1 : this.children.indexOf(beforeChild);
+    this.children.splice(
+      before === -1 ? this.children.length : before,
+      0,
+      child,
+    );
+    // a keyed reorder: the child is already linked, themed and attached
+    if (from !== -1) return;
+    child._scope = this;
+    // Built while detached, the subtree resolved its tokens against the
+    // desktop's palette; this is the attach walk that re-resolves them, the
+    // same one `Node.insertBefore` runs — a mount, so it claims no damage.
+    child._themeChanged(true);
+    if (this._hiddenByReact()) child._applyHidden();
+    if (this._attached) attachTopLevel(this.app, child);
+  }
+
+  removeChild(child) {
+    const at = this.children.indexOf(child);
+    if (at === -1) return;
+    this.children.splice(at, 1);
+    if (this._attached) detachTopLevel(this.app, child);
+    child._scope = null;
+    child.destroySubtree();
+  }
+
+  applyProps(newProps, oldProps) {
+    const before = oldProps ?? this.props;
+    this.props = newProps;
+    // A swap walks the windows as a live change, which repaints them. The
+    // `style` a provider passes lays out a box inside a window and means
+    // nothing here: a direction it names is in the palette as well, which
+    // is what a window reads its direction from.
+    if (newProps.theme !== before.theme) this._themeChanged();
+  }
+
+  setHidden(hidden) {
+    this._reactHidden = hidden;
+    this._applyHidden();
+  }
+
+  /** The hidden state above the windows moved: each one re-derives its own. */
+  _applyHidden() {
+    for (const child of this.children) child._applyHidden();
+  }
+
+  /** Whether React hides this scope, here or at a scope around it. */
+  _hiddenByReact() {
+    return this._reactHidden || (this._scope?._hiddenByReact() ?? false);
+  }
+
+  _attach() {
+    this._attached = true;
+    for (const child of this.children) attachTopLevel(this.app, child);
+  }
+
+  _detach() {
+    this._attached = false;
+    for (const child of this.children) detachTopLevel(this.app, child);
+  }
+}
+
+/**
+ * `<ThemeProvider>` written directly inside a `<window>` (or a `<popup>`).
+ *
+ * There it is a box that fills its parent, like a provider anywhere else in
+ * a window — but a window may nest windows, and a provider wrapped around one
+ * has to hand it on, since a window cannot live inside a box. So a nested
+ * window put under this box is **passed through** to the window the box is
+ * in: that window holds it, realizes and stacks it the way it does any
+ * nested window, and the window reads its palette from here through
+ * `_scope`, which a palette lookup asks before the parent (`Node.theme`).
+ *
+ * React still sees the window as this box's child, so the calls it makes on
+ * the box for that window — a move, a removal — are forwarded as well, and
+ * the box answers for the passed windows in the three things it owns over its
+ * subtree: a theme swap, a hide, and its own removal.
+ *
+ * Only here. Under a provider that is inside a `<box>` there is no window to
+ * pass a window to, and `Node.insertBefore` says so.
+ */
+export class ThemeBoxNode extends BoxNode {
+  constructor(props, app) {
+    super(props, app);
+    // the nested windows React put under this box, in the order it did
+    this._windows = [];
+  }
+
+  insertBefore(child, beforeChild) {
+    if (!child.isWindow || child.isPopup) {
+      super.insertBefore(child, beforeChild);
+      return;
+    }
+    if (!this._windows.includes(child)) {
+      this._windows.push(child);
+      child._scope = this;
+    }
+    // Before the box is in its window the window waits here, and `_setRoot`
+    // passes it on at the attach. A move is re-inserted at the end: nested
+    // windows stack among themselves, not among the box's drawn children.
+    if (this.parent) this.parent.insertBefore(child, null);
+  }
+
+  removeChild(child) {
+    const at = this._windows.indexOf(child);
+    if (at === -1) {
+      super.removeChild(child);
+      return;
+    }
+    this._windows.splice(at, 1);
+    // the window destroys it, and takes it off its stacking list
+    if (child.parent) child.parent.removeChild(child);
+    else child.destroySubtree();
+    child._scope = null;
+  }
+
+  _setRoot(root) {
+    const attaching = this.root !== root;
+    super._setRoot(root);
+    if (!attaching || !this.parent) return;
+    for (const win of this._windows) {
+      if (win.parent !== this.parent) this.parent.insertBefore(win, null);
+    }
+  }
+
+  _themeChanged(mounting = false) {
+    super._themeChanged(mounting);
+    for (const win of this._windows) win._themeChanged(mounting);
+  }
+
+  setHidden(hidden) {
+    super.setHidden(hidden);
+    for (const win of this._windows) win._applyHidden();
+  }
+
+  /** React hid this box — the hide a `<Suspense>` around the provider
+   * lands on, which the windows passed on from here have to follow. */
+  _hiddenByReact() {
+    return this.hidden;
+  }
+
+  destroySubtree() {
+    super.destroySubtree();
+    // React removes the box alone, never the windows under it, so they go
+    // with it — out of the window that holds them, which is each one's
+    // parent (the box's own is already cleared by now), unless that window
+    // is being destroyed itself and is walking its children as it does.
+    for (const win of this._windows) {
+      const holder = win.parent;
+      if (holder && !holder.destroyed) holder.removeChild(win);
+      else if (!win.destroyed) win.destroySubtree();
+    }
+  }
+}