react-x11 2.15.3 → 2.16.1

package/src/nodes/animation.js

@@ -40,36 +40,6 @@ const gridContainerMoved = (was, now) =>
 const gridItemMoved = (was, now) =>
   GRID_ITEM_PROPS.some((prop) => was[prop] !== now[prop]);
 
-/**
- * The node whose bounds cover where an animating node will be next frame, or
- * `null` when that cannot be known and the frame has to repaint everything.
- *
- * Three cases, and the middle one is the interesting one:
- *
- *  - **paint-only** (a colour, an opacity): the node stays put, so its own
- *    bounds are the damage.
- *  - **a layout property on an out-of-flow node** (`position: absolute`, the
- *    arrangement a sliding thumb uses): the node moves, so its own bounds
- *    cover where it is going but not where it has been. Its *parent* covers
- *    both — an absolute child is laid out inside its parent and, being out of
- *    flow, moves nothing else when it shifts. This is what keeps a `Switch`
- *    from repainting the window on every frame of its 120ms slide.
- *  - **a layout property in flow**: a reflow can move any node in the tree,
- *    including ones that leave stale pixels outside every bound we could name
- *    here. Nothing to do but repaint in full.
- */
-function damageForAnimation(node) {
-  let movesInLayout = false;
-  for (const prop of node._anim?.keys() ?? []) {
-    if (isLayoutProp(prop)) movesInLayout = true;
-  }
-  if (!movesInLayout) return node;
-  if (node.style?.position !== 'absolute') return null;
-  // A window parent bounds nothing useful — its own rect is the whole surface.
-  const parent = node.parent;
-  return parent && !parent.isWindow ? parent : null;
-}
-
 // Frame timestamps for transitions. Indirected so tests can drive the clock
 // instead of sleeping through real animations.
 export let now = () => Date.now();
@@ -129,7 +99,7 @@ export class NodeAnimation {
         // such presenter, the window's frame clock runs it as it always has.
         if (this._offload(prop, entry)) {
           entry.offloaded = true;
-          this.root?.invalidate(false, damageForAnimation(this), 'animation');
+          this.root?.invalidate(false, this, 'animation');
         } else {
           // …and one the presenter had must not keep running underneath the
           // values the clock is about to write
@@ -342,7 +312,7 @@ export class NodeAnimation {
       }
     }
     this.root?._animating.delete(this);
-    this.root?.invalidate(false, damageForAnimation(this), 'animation');
+    this.root?.invalidate(false, this, 'animation');
   }
 
   /**
@@ -608,7 +578,7 @@ export class WindowAnimation {
     // invalidate anyway, but a React prop change does not — and a transition
     // no one schedules only runs when something else dirties the window,
     // by which time its start is stale and it snaps to the end.
-    this.invalidate(false, damageForAnimation(node), 'animation');
+    this.invalidate(false, node, 'animation');
   }
 
   /**
@@ -618,27 +588,27 @@ export class WindowAnimation {
    */
   _advanceAnimations(now) {
     if (this._animating.size === 0) return;
-    const claims = [];
     for (const node of [...this._animating]) {
       if (node.destroyed) {
         this._animating.delete(node);
         continue;
       }
-      // Decided *before* the tick, deliberately: a tick that finishes deletes
-      // the property from `_anim`, and after that there is no way to tell a
-      // layout animation from a paint-only one — the node's own bounds would
-      // be claimed for something that just moved, leaving a trail behind it.
-      claims.push(damageForAnimation(node));
+      // The node where it stands, which is where it *was*: nothing has been
+      // laid out yet, so its rect is the one the last pass gave it. Where it
+      // goes is the layout pass's to claim. A tick on a layout property asks
+      // for one, and that pass claims the old and new rect of every node it
+      // moves (`_assignAbs`) — this one, and whatever this one pushed, in
+      // flow or out of it. A paint-only property moves nothing, and this
+      // claim is the whole frame.
+      //
+      // Claimed rather than left unbounded because an animation repaints
+      // every frame for as long as it runs: eight height loops in a menu-bar
+      // popover were a full-window repaint per frame at 120Hz (#603). A node
+      // that *finishes* on this tick is claimed too — it just landed on its
+      // final value, and this last frame still has to paint it there.
+      this.invalidate(false, node, 'animation');
       if (!node._tickAnimations(now)) this._animating.delete(node);
     }
     this.needsPaint = true;
-    // Claim a region rather than leaving the frame unbounded: an animation is
-    // a repaint every frame for its whole duration, so this is the difference
-    // between a 120ms transition costing eight full-window repaints and eight
-    // repaints of the thing that moved. Nodes that *finished* on this tick are
-    // claimed too — one just landed on its final value and that last frame
-    // still has to paint it, which is why every transition used to end with a
-    // full-window repaint.
-    for (const claim of claims) this.invalidate(false, claim, 'animation');
   }
 }

package/src/nodes/cascade.js

@@ -190,10 +190,20 @@ export class NodeCascade {
    * A detached node has no ancestors yet and so cannot see a provider two
    * levels up; it still resolves, against the base, and `_themeChanged()` on
    * attach re-resolves it against the real one.
+   *
+   * A window can take its palette from somewhere other than its parent: a
+   * `<ThemeProvider>` above it at the root, which is not its parent because a
+   * top-level window has none, or one directly inside the window it is
+   * nested in, which passed it on to that window. Either is `_scope`, and it
+   * comes first (nodes/scope.js).
    */
   get theme() {
     if (this._theme !== undefined) return this._theme;
-    const inherited = this.parent ? this.parent.theme : baseTheme();
+    const inherited = this._scope
+      ? this._scope.theme
+      : this.parent
+        ? this.parent.theme
+        : baseTheme();
     const own = this.props.theme;
     this._theme = own ? { ...inherited, ...own } : inherited;
     return this._theme;
@@ -312,7 +322,12 @@ export class NodeCascade {
       const size = (inherited.size * to) / from;
       const cached = this._textScaled;
       if (cached?.from !== inherited || cached.style.size !== size) {
-        this._textScaled = { from: inherited, style: { ...inherited, size } };
+        const style = { ...inherited, size };
+        // the other length that travels, re-expressed the same way
+        if (inherited.letterSpacing) {
+          style.letterSpacing = (inherited.letterSpacing * to) / from;
+        }
+        this._textScaled = { from: inherited, style };
       }
       return this._textScaled.style;
     }

package/src/nodes/image.js

@@ -11,6 +11,7 @@ import {
   isDirectImageSource,
   isPathImageSource,
   isRawImageSource,
+  isSymbolImageSource,
   releaseImageSource,
   toLoadablePath,
   validateImageProps,
@@ -20,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';
@@ -42,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.
@@ -67,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,
@@ -96,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
@@ -223,9 +252,29 @@ export class ImageNode extends Node {
       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);
@@ -234,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)
     ) {
@@ -254,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