react-x11 2.6.1 → 2.8.0

package/src/cocoa/presenter.js

@@ -32,9 +32,10 @@ import {
   damageToPaint,
   intersectRects,
 } from '../nodes.js';
+import { EASING_CONTROL_POINTS, TRANSITION_CONTROL_POINTS } from '../styles.js';
 import { CocoaContext2D } from './context2d.js';
 
-const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
+export const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
 
 /**
  * A recording "context" for ntk's SvgView.draw: instead of rasterizing, it
@@ -324,9 +325,14 @@ const EDGE_PROPS = [
   'borderEndWidth',
 ];
 
-function stylePaintsPlain(node) {
+/**
+ * Does `style` draw as a plain box — the property vocabulary of a layer
+ * (background, a uniform solid border, one radius), nothing that needs a
+ * raster? What decides whether a node is a PropBox on the layer presenter,
+ * and whether the surface presenter can promote it (src/cocoa/promotion.js).
+ */
+export function stylePaintsPlain(node, style = node.style ?? {}) {
   if (node.kind !== 'box') return false;
-  const style = node.style ?? {};
   if (style.backgroundImage || style.boxShadow || style.outlineWidth) {
     return false;
   }
@@ -339,13 +345,33 @@ function stylePaintsPlain(node) {
   return uniformRadius(style.borderRadius) !== null;
 }
 
-function uniformRadius(radius) {
+/**
+ * Style property → the key path on a PropBox's own layer, for the
+ * animations the presenter takes off the frame clock and hands to the
+ * render server (docs/architecture/animation.md §4.2). Only what the layer
+ * expresses as a property of itself qualifies: a colour on `<text>` is a
+ * re-raster per frame, a layout property moves the siblings, and both stay
+ * on the JS loop. `scaled` values go out in points, as `_syncPropBox`
+ * sends them.
+ */
+const ANIMATED_KEY_PATHS = Object.freeze({
+  backgroundColor: { keyPath: 'backgroundColor', colour: true },
+  borderColor: { keyPath: 'borderColor', colour: true },
+  borderWidth: { keyPath: 'borderWidth', scaled: true },
+  borderRadius: { keyPath: 'cornerRadius', scaled: true },
+});
+
+// the ids the bridge reports an animation's end under: unique per process,
+// looked up per app (`_animationEnds`)
+let animationSeq = 0;
+
+export function uniformRadius(radius) {
   if (radius === undefined) return 0;
   if (typeof radius === 'number') return radius;
   return null; // per-corner shapes go to raster
 }
 
-class Visual {
+export class Visual {
   constructor(presenter, node) {
     this.presenter = presenter;
     this.node = node;
@@ -389,7 +415,7 @@ class Visual {
   }
 }
 
-class RasterState {
+export class RasterState {
   constructor() {
     this.surface = null;
     this.gen = 0;
@@ -430,6 +456,218 @@ class RasterState {
   }
 }
 
+/**
+ * A plain box as the properties of its layer — what a PropBox visual sends
+ * on the layer presenter and what a promoted node's layer is set from on
+ * the surface presenter (src/cocoa/promotion.js): one function, so a box
+ * reads the same on either. `parentOrigin` is what `frame` is relative to,
+ * in window coordinates; everything goes out in points.
+ */
+export function propBoxProps(node, app, scale, parentOrigin, order) {
+  const abs = node.abs;
+  const style = node.style ?? {};
+  const border = typeof style.borderWidth === 'number' ? style.borderWidth : 0;
+  const colour = (value) =>
+    value ? (app._parseColor(String(value)) ?? [0, 0, 0, 0]) : [0, 0, 0, 0];
+  return {
+    frame: [
+      (abs.x - parentOrigin.x) / scale,
+      (abs.y - parentOrigin.y) / scale,
+      Math.max(0, abs.width) / scale,
+      Math.max(0, abs.height) / scale,
+    ],
+    zPosition: order,
+    hidden: Boolean(node.hidden),
+    masksToBounds: Boolean(node.clipsChildren?.()) && !node.isScroller?.(),
+    cornerRadius: (uniformRadius(style.borderRadius) ?? 0) / scale,
+    backgroundColor: colour(style.backgroundColor),
+    borderWidth: border / scale,
+    borderColor: colour(style.borderColor),
+  };
+}
+
+// --- animations the render server runs ---------------------------------------
+//
+// The node model keeps deciding what is animating and when it ends
+// (nodes.js `_retarget` / `_updateLoops`); what moves here is who
+// interpolates. Taken means the node's style goes to its target — the
+// layer's model value, sent by the next frame's property diff — and that
+// frame attaches an explicit animation carrying the pixels there; no frame
+// after it is scheduled for the property, and a loop costs no JS frames at
+// all. Declined means the frame clock runs it exactly as before, so
+// nothing here is load-bearing for correctness.
+//
+// Kept apart from the presenter because two of them hand animations over:
+// the layer presenter, where every plain box has a layer, and the surface
+// presenter's promotion (src/cocoa/promotion.js), where only the nodes
+// that animate do. They differ in which node has a layer and agree on
+// everything from there — `layerOf(node)` is the whole of the difference.
+
+/**
+ * The animations one presenter has handed to the render server: what
+ * `take` accepted and is waiting for the frame that attaches it, and what
+ * is running on a layer. `onIdle(node)`, when given, hears that the last
+ * animation running for a node ended on the bridge's word — the one end
+ * no frame follows on its own.
+ */
+export class LayerAnimations {
+  constructor({ native, app, scale, layerOf, onIdle = null }) {
+    this.native = native;
+    this.app = app;
+    this.scale = scale;
+    this.layerOf = layerOf;
+    this.onIdle = onIdle;
+    this.pending = new Map(); // node -> Map(prop -> entry)
+    this.live = new Map(); // node -> Map(id -> { prop, key, entry })
+  }
+
+  /**
+   * Take `prop`'s animation for `node`, or decline. Decided against the
+   * *target* style: a `:hover` that adds a shadow turns the node into a
+   * raster in the same swap that starts a fade, and a raster's background
+   * is in its bitmap, not on its layer.
+   */
+  take(node, prop, entry) {
+    const map = ANIMATED_KEY_PATHS[prop];
+    if (!map || !stylePaintsPlain(node, node._targetStyle ?? node.style)) {
+      return false;
+    }
+    if (this._value(map, entry.from) == null) return false;
+    if (this._value(map, entry.to) == null) return false;
+    let pending = this.pending.get(node);
+    if (!pending) this.pending.set(node, (pending = new Map()));
+    pending.set(prop, entry);
+    return true;
+  }
+
+  /** Stop what runs for `prop` on `node`: a loop the window lost sight of,
+   *  a declaration that changed, a transition the clock takes back. */
+  cancel(node, prop) {
+    this.pending.get(node)?.delete(prop);
+    this._removeLive(node, prop);
+  }
+
+  /** Is anything taken for `node` — waiting for a frame, or running? */
+  has(node) {
+    return this.pending.has(node) || this.live.has(node);
+  }
+
+  _ends() {
+    return (this.app._animationEnds ??= new Map());
+  }
+
+  /** A style value as the layer takes it — a colour as components, a
+   *  length in points — or null for one the layer cannot animate. */
+  _value(map, value) {
+    if (map.colour) {
+      return typeof value === 'string'
+        ? (this.app._parseColor(value) ?? null)
+        : null;
+    }
+    return typeof value === 'number'
+      ? value / (map.scaled ? this.scale : 1)
+      : null;
+  }
+
+  /** The frame's half: attach what `take` accepted to `layer`, after the
+   *  model value went out, inside the same transaction. */
+  apply(node, layer) {
+    const pending = this.pending.get(node);
+    if (!pending) return;
+    this.pending.delete(node);
+    for (const [prop, entry] of pending) {
+      const map = ANIMATED_KEY_PATHS[prop];
+      const id = `rx${++animationSeq}`;
+      const key = `${prop}:${id}`;
+      const opts = { duration: entry.duration / 1000, id };
+      if (entry.loop) {
+        // a loop replaces whatever ran for the property: its declaration
+        // changed, and a loop restarts from the top when it does
+        this._removeLive(node, prop);
+        opts.from = this._value(map, entry.from);
+        opts.to = this._value(map, entry.to);
+        opts.timing = EASING_CONTROL_POINTS[entry.easing];
+        opts.repeat = Infinity;
+        opts.autoreverse = entry.alternate;
+      } else if (map.colour) {
+        // From where the pixels are — which is what "an interrupted
+        // transition reverses from where it got to" means here. A colour
+        // cannot be additive, so the one before it is replaced.
+        this._removeLive(node, prop);
+        const shown = this.native.presentationValue?.(layer, map.keyPath);
+        opts.from = Array.isArray(shown) ? shown : this._value(map, entry.from);
+        opts.to = this._value(map, entry.to);
+        opts.timing = TRANSITION_CONTROL_POINTS;
+      } else {
+        // Additive: a delta over the model value, (old − new) → 0, and the
+        // ones before it keep running and sum. Continuity on a retarget with
+        // nothing read back, however many are in flight.
+        opts.from = this._value(map, entry.from) - this._value(map, entry.to);
+        opts.to = 0;
+        opts.additive = true;
+        opts.timing = TRANSITION_CONTROL_POINTS;
+      }
+      this.native.addAnimation(layer, map.keyPath, opts, key);
+      // looked up after the removals above, which may have pruned the map
+      let live = this.live.get(node);
+      if (!live) this.live.set(node, (live = new Map()));
+      live.set(id, { prop, key, entry });
+      this._ends().set(id, (ev) => this._animationEnded(node, id, ev));
+    }
+  }
+
+  /** Every animation running for `prop` on `node`, off the layer and out
+   *  of the books. */
+  _removeLive(node, prop) {
+    const live = this.live.get(node);
+    if (!live) return;
+    const layer = this.layerOf(node);
+    for (const [id, run] of live) {
+      if (run.prop !== prop) continue;
+      live.delete(id);
+      this._ends().delete(id);
+      if (layer) this.native.removeAnimation(layer, run.key);
+    }
+    if (live.size === 0) this.live.delete(node);
+  }
+
+  /** The bridge's `animation-end` for one of ours — it ran out, or CA
+   *  dropped it. An older additive one ending changes nothing: the node
+   *  checks the entry is still the one it holds. */
+  _animationEnded(node, id) {
+    this._ends().delete(id);
+    const live = this.live.get(node);
+    const run = live?.get(id);
+    if (!run) return;
+    live.delete(id);
+    if (live.size === 0) this.live.delete(node);
+    node._offloadEnded(run.prop, run.entry);
+    if (!this.has(node)) this.onIdle?.(node);
+  }
+
+  /** The layer is going — the visual is destroyed, or turns into a raster —
+   *  and every animation on it goes with it. What was still waiting for a
+   *  frame goes back to the frame clock when the node stays (`reclaim`);
+   *  what was running is over, and the model shows. */
+  drop(node, reclaim) {
+    const pending = this.pending.get(node);
+    if (pending) {
+      this.pending.delete(node);
+      for (const [prop, entry] of pending) {
+        if (reclaim) node._offloadDeclined(prop, entry);
+        else node._offloadEnded(prop, entry);
+      }
+    }
+    const live = this.live.get(node);
+    if (!live) return;
+    this.live.delete(node);
+    for (const [id, run] of live) {
+      this._ends().delete(id);
+      node._offloadEnded(run.prop, run.entry);
+    }
+  }
+}
+
 export class CocoaLayerPresenter {
   constructor(window) {
     this.window = window;
@@ -439,6 +677,13 @@ export class CocoaLayerPresenter {
     this.visuals = new Map(); // node -> Visual
     this.rasters = new Map(); // node -> RasterState
     this.bars = new Map(); // scroller node -> Map(axis -> { layer, raster })
+    // animations taken off the frame clock, by the node's own layer
+    this.animations = new LayerAnimations({
+      native: this.native,
+      app: window.app,
+      scale: this.scale,
+      layerOf: (node) => this.visuals.get(node)?.layer ?? null,
+    });
     // Claims since the last frame — taken at the top of `frame()`, the way
     // the X11 path takes its damage before painting, so a claim made from
     // inside a paint lands in the next frame instead of being cleared with
@@ -548,6 +793,7 @@ export class CocoaLayerPresenter {
           visual.destroy();
           this.visuals.delete(node);
           this._dropRaster(node);
+          this.animations.drop(node, false);
           const bars = this.bars.get(node);
           if (bars) {
             for (const entry of bars.values()) {
@@ -612,8 +858,14 @@ export class CocoaLayerPresenter {
     if (visual && visual.isRaster !== wantsRaster) {
       visual.destroy();
       this._dropRaster(node);
+      // a layer that turns into a raster takes its animations with it; the
+      // frame clock can still run them over the bitmap
+      if (wantsRaster) this.animations.drop(node, true);
       visual = null;
     }
+    if (wantsRaster && this.animations.pending.has(node)) {
+      this.animations.drop(node, true);
+    }
     if (!visual) {
       visual = new Visual(this, node);
       visual.isRaster = wantsRaster;
@@ -700,34 +952,23 @@ export class CocoaLayerPresenter {
 
   _syncPropBox(node, visual, parentOrigin, order) {
     const abs = node.abs;
-    const style = node.style ?? {};
-    const s = this.scale;
     visual.origin = { x: abs.x, y: abs.y };
-    const border =
-      typeof style.borderWidth === 'number' ? style.borderWidth : 0;
-    visual.set({
-      frame: [
-        (abs.x - parentOrigin.x) / s,
-        (abs.y - parentOrigin.y) / s,
-        Math.max(0, abs.width) / s,
-        Math.max(0, abs.height) / s,
-      ],
-      zPosition: order,
-      hidden: Boolean(node.hidden),
-      masksToBounds: Boolean(node.clipsChildren?.()) && !node.isScroller?.(),
-      cornerRadius: (uniformRadius(style.borderRadius) ?? 0) / s,
-      backgroundColor: style.backgroundColor
-        ? (this.window.app._parseColor(String(style.backgroundColor)) ?? [
-            0, 0, 0, 0,
-          ])
-        : [0, 0, 0, 0],
-      borderWidth: border / s,
-      borderColor: style.borderColor
-        ? (this.window.app._parseColor(String(style.borderColor)) ?? [
-            0, 0, 0, 0,
-          ])
-        : [0, 0, 0, 0],
-    });
+    visual.set(
+      propBoxProps(node, this.window.app, this.scale, parentOrigin, order),
+    );
+    // after the model value went out, inside the same transaction
+    this.animations.apply(node, visual.layer);
+  }
+
+  /** The window's animation seam (src/cocoa/window.js): take `prop`'s
+   *  animation for `node` off the frame clock, or decline. */
+  animate(node, prop, entry) {
+    return this.animations.take(node, prop, entry);
+  }
+
+  /** …and stop what runs for `prop` on `node`. */
+  cancel(node, prop) {
+    this.animations.cancel(node, prop);
   }
 
   /**