react-x11 2.35.0 → 2.37.0

package/src/nodes/animation.js

@@ -12,6 +12,7 @@ import {
   interpolate,
   ease,
   isLayoutProp,
+  TEXT_LAYOUT_PROPS,
 } from '../styles.js';
 import { GRID_CONTAINER_PROPS, GRID_ITEM_PROPS } from '../grid.js';
 import { isPlaced } from '../layouts.js';
@@ -19,9 +20,19 @@ import { desktopSettings, watchDesktopSettings } from '../desktopsettings.js';
 import { watchWindowState, windowStateSnapshot } from '../windowstate.js';
 import { shadowExtentOf } from './boxpaint.js';
 import { inThemeWalk } from './cascade.js';
-import { insetRect } from './rects.js';
+import { insetRect, intersectRects, outerPixels } from './rects.js';
 import { shallowEqual } from './util.js';
 
+/** How often a loop the clock runs is offered to a presenter again, at
+ *  most (`_recheckLoops`): a check is a walk up the node's ancestors and
+ *  along what is painted after it, and the loop is a frame every refresh
+ *  for as long as it waits. */
+const REOFFER_MS = 250;
+
+/** The loopable properties that reach past the node's box without moving
+ *  anything: a ring that grows draws further out than the node did. */
+const REACH_PROPS = new Set(['outlineWidth', 'outlineOffset']);
+
 /** Two values of a grid property that lay out the same: an inline
  *  `gridTemplateAreas` array is a new array every render. */
 const sameGridValue = (a, b) =>
@@ -299,16 +310,53 @@ export class NodeAnimation {
   }
 
   /** The presenter could not run `entry` after all — the node turned into a
-   *  raster between the swap and the frame. The frame clock takes it from
-   *  the top; the property's declared start is where the pixels still are. */
+   *  raster between the swap and the frame, or its layer went. A transition
+   *  starts again from the top, since the property's declared start is
+   *  where its pixels still are. A loop goes on where it is in its cycle:
+   *  the render server ran it from `start` (`LayerAnimations.apply`), or it
+   *  never left the clock, so a spinner given back does not jump. */
   _offloadDeclined(prop, entry) {
     if (this._anim?.get(prop) !== entry || this.destroyed) return;
     entry.offloaded = false;
-    entry.start = now();
+    entry.headStart = undefined;
+    if (entry.loop) entry.value = animationValueAt(entry, now() - entry.start);
+    else entry.start = now();
     this.style = { ...this._targetStyle, ...this._animatedValues() };
     this.root?._startAnimating(this);
   }
 
+  /**
+   * Loops the frame clock runs that the presenter would take now: turned
+   * down by a frame, or given back, by a scene that has changed since — an
+   * ancestor done fading, a sibling gone, a thumb scrolled away. Nothing
+   * about a loop would ever ask again, so the window asks (`_recheckLoops`),
+   * and only where the presenter says a frame would take it
+   * (`wouldAnimateNode`), so a loop it would turn down again costs no swap.
+   * Handed over where it is in its cycle (`headStart`).
+   */
+  _offerLoopsAgain() {
+    const wnd = this.root?.window;
+    let asked = false;
+    let moved = false;
+    for (const [prop, a] of this._anim ?? []) {
+      if (!a.loop || a.offloaded) continue;
+      if (!asked) {
+        if (!wnd.wouldAnimateNode(this)) return;
+        asked = true;
+      }
+      a.headStart = now() - a.start;
+      if (this._offload(prop, a)) {
+        a.offloaded = true;
+        moved = true;
+      } else {
+        a.headStart = undefined;
+      }
+    }
+    if (!moved) return;
+    this.style = { ...this._targetStyle, ...this._animatedValues() };
+    this._scheduleAnimationFrames();
+  }
+
   /** Keep the frame clock running only for what the clock itself animates;
    *  an offloaded-only node needs one frame — the one that sends the model
    *  and the animation — and not a loop of them. */
@@ -383,13 +431,19 @@ export class NodeAnimation {
         // re-rendered — which is the frame after every state change in the
         // app.
         if (current?.loop && sameAnimation(current, spec)) {
-          // A loop the clock started before the window had a presenter —
-          // one declared at mount runs from `_setRoot`, before `realize` —
-          // moves over the first time a presenter can take it. Its phase is
-          // the render server's from here, which is what a restart costs.
-          if (!current.offloaded && this._offload(spec.prop, current)) {
-            current.offloaded = true;
-            changed = true;
+          // A loop the clock runs moves over the first time a presenter
+          // takes it: one declared at mount runs from `_setRoot`, before
+          // `realize`, and one a frame turned down runs until the next swap
+          // offers it again (or `_offerLoopsAgain` does). It goes where it
+          // has got to in its cycle (`headStart`), so nothing jumps.
+          if (!current.offloaded) {
+            current.headStart = now() - current.start;
+            if (this._offload(spec.prop, current)) {
+              current.offloaded = true;
+              changed = true;
+            } else {
+              current.headStart = undefined;
+            }
           }
           continue;
         }
@@ -443,7 +497,76 @@ export class NodeAnimation {
       return false;
     }
     if (desktopSettings(root.app).animations === false) return false;
-    return !this._hiddenInTree();
+    if (this._hiddenInTree()) return false;
+    // last, since it is the one that measures — and a hidden subtree's
+    // rects are wherever it was when it went
+    this._outOfSight = this._loopsOutOfSight();
+    return !this._outOfSight;
+  }
+
+  /**
+   * Whether nothing this node's loops draw can be seen: all of it is cut
+   * away by the boxes that clip it, or lies outside the window — a spinner
+   * in a row scrolled out of its list, a bar in a panel scrolled away.
+   * Judged against the arrangement the last layout pass left, and again
+   * after every pass that moved anything (`_recheckLoops`).
+   *
+   * Never from where a frame of the loop has the node *now*: a block that
+   * slides across a track is off it at the start of every crossing, and a
+   * loop stopped there would rest there, unseen, for good. What is judged is
+   * what holds every frame (`_loopReach`), and a loop whose frames can move
+   * what is around it is never judged out of sight at all.
+   */
+  _loopsOutOfSight() {
+    const window = this.root?.abs;
+    if (!this._placed || !window) return false;
+    const reach = this._loopReach();
+    if (!reach) return false;
+    let out = reach.rect;
+    for (let n = reach.from.parent; n && out; n = n.parent) {
+      if (n.isWindow) break;
+      if (n.clipsChildren()) out = intersectRects(out, outerPixels(n.abs));
+    }
+    return (
+      !out ||
+      !intersectRects(out, {
+        x: 0,
+        y: 0,
+        width: window.width,
+        height: window.height,
+      })
+    );
+  }
+
+  /**
+   * What every frame of this node's loops stays inside, as `{ rect, from }`
+   * — `from` is the node whose clipping ancestors cut `rect` — or null when
+   * nothing short of the window holds it.
+   *
+   * A loop on a colour, an opacity or a radius moves nothing and grows
+   * nothing, so it draws where the node and what it holds already reach.
+   * One that grows the node's outline, or moves or sizes a node out of the
+   * flow, can put it anywhere in the nearest box that clips it — and nowhere
+   * else, since a node out of the flow sizes nothing around it; with no such
+   * box, anywhere in the window. One that moves or sizes a node in the flow
+   * moves its siblings and can resize every box above it, the clipping ones
+   * among them, so no box holds it.
+   */
+  _loopReach() {
+    let inPlace = true;
+    for (const { prop } of this._loops ?? []) {
+      if (REACH_PROPS.has(prop)) {
+        inPlace = false;
+      } else if (isLayoutProp(prop) || TEXT_LAYOUT_PROPS.has(prop)) {
+        if (this.style?.position !== 'absolute') return null;
+        inPlace = false;
+      }
+    }
+    if (inPlace) return { rect: this.paintBounds(), from: this };
+    for (let n = this.parent; n && !n.isWindow; n = n.parent) {
+      if (n.clipsChildren()) return { rect: outerPixels(n.abs), from: n };
+    }
+    return null;
   }
 
   /** Whether anything between this node and its window has taken it off the
@@ -579,6 +702,42 @@ export class WindowAnimation {
     for (const node of [...this._loopNodes]) node._updateLoops();
   }
 
+  /**
+   * After the frame's layout and placements, before the presenter's word.
+   *
+   * Where a pass moved things (`moved`), a loop it put out of sight stops,
+   * and one it brought back runs again (`_loopsOutOfSight`) — from the top,
+   * as every stop here resumes, since nobody saw where it had got to. Only
+   * the loops whose answer changed are asked again, so a pass that moved
+   * nothing of theirs costs a walk up from each.
+   *
+   * And where a presenter can run a loop in the render server, a loop in
+   * sight that the clock runs is offered to it again (`_offerLoopsAgain`),
+   * each at most every `REOFFER_MS`: what turned it down can go without a
+   * layout pass — an ancestor's fade arriving is a paint — and the loop is
+   * a frame every refresh until it is taken.
+   */
+  _recheckLoops(moved) {
+    const offer = typeof this.window?.wouldAnimateNode === 'function';
+    if (!moved && !offer) return;
+    const t = offer ? now() : 0;
+    for (const node of [...this._loopNodes]) {
+      if (moved) {
+        const out = node._loopsOutOfSight();
+        if (out !== (node._outOfSight === true)) {
+          node._outOfSight = out;
+          node._updateLoops();
+          continue;
+        }
+      }
+      if (!offer || node._outOfSight === true || node.destroyed) continue;
+      if (!(t - (node._offeredAt ?? -Infinity) >= REOFFER_MS)) continue;
+      if (!node.root?._animating.has(node)) continue; // the clock runs none
+      node._offeredAt = t;
+      node._offerLoopsAgain();
+    }
+  }
+
   /** A node in this window started a transition. */
   _startAnimating(node) {
     this._animating.add(node);

package/src/nodes/scrollable.js

@@ -950,6 +950,9 @@ export const Scrollable = (Base) =>
      * its own route, since it paints through `_paintRegion` and never
      * through `Node.paint`. */
     _paintScrollbars(ctx) {
+      // on layers of their own, over the layers of the rows they are drawn
+      // over (src/cocoa/promotion.js `_syncThumbs`)
+      if (this._thumbsLifted) return;
       for (const bar of this._scrollbars()) {
         paintScrollbarThumb(ctx, bar, this.props.scrollbarColor);
       }

package/src/nodes/window/flush.js

@@ -286,9 +286,18 @@ export class WindowFlush {
     }
     // An animated placement asked for this frame and nothing laid out: its
     // pass runs on its own, against the arrangement the last one left
+    let placed = false;
     if (!layoutRan && this._placementsDue && this._placeNodes()) {
       this.needsPaint = true;
+      placed = true;
     }
+    // A loop this arrangement put out of sight stops, and one it brought
+    // back runs again; one the clock runs is offered to the presenter
+    // again (`_recheckLoops`). After the pass and the placements, so it is
+    // judged where things landed, and before the presenter's word, so a
+    // loop handed to it, or taken back, is in this frame. Nothing moves
+    // anything but these two passes, so sight is judged only after one.
+    if (this._loopNodes.size) this._recheckLoops(layoutRan || placed);
     // A presenter compositing part of the tree on layers of its own — the
     // surface presenter's promoted nodes (src/cocoa/promotion.js) — gets
     // its word in here: after layout, so it sees where everything landed,

package/src/testing/harness.js

@@ -10,7 +10,10 @@
 import React from 'react';
 import { createRoot } from '../Reconciler.js';
 import { setAnimationClock } from '../nodes/animation.js';
-import { setAppearanceForTests } from '../appearance.js';
+import {
+  pinnedAppearanceForTests,
+  setAppearanceForTests,
+} from '../appearance.js';
 
 // A test process must not register with the desktop's live AT-SPI registry —
 // a suite on a developer desktop would otherwise parade hundreds of phantom
@@ -140,10 +143,26 @@ export async function renderX11(element, options = {}) {
     wrap = element?.type !== 'window',
     title = 'react-x11 test',
     colorScheme = 'light',
+    appearance = null,
     a11y = false,
     ...rootOptions
   } = options;
 
+  // Checked before anything is created, so a mistake costs no server
+  const pin = appearancePin(colorScheme, appearance);
+  if (setBeforeMount) {
+    const values = setBeforeMount;
+    setBeforeMount = null;
+    throw new Error(
+      'react-x11/test: setAppearance() was called before renderX11(), which ' +
+        'pins the appearance as it mounts — the values it set would be ' +
+        'replaced without a word. Pass them to the render instead:\n\n' +
+        `  await renderX11(<App />, { appearance: ${JSON.stringify(values)} });\n\n` +
+        'setAppearance() is for changing them once the tree is mounted. ' +
+        'See docs/testing.md#the-desktops-appearance.',
+    );
+  }
+
   let server = null;
   let app = options.app ?? null;
   if (!app) {
@@ -161,14 +180,9 @@ export async function renderX11(element, options = {}) {
   // on a light desktop, red on a dark one, with nothing in the test saying
   // so. After the app exists, so it wins over `createMockApp`'s own pin.
   // `colorScheme: 'dark'` renders the other palette; `'system'` releases the
-  // pin, for a test that is *about* what the desktop reports.
-  setAppearanceForTests(
-    colorScheme === 'system'
-      ? null
-      : colorScheme === 'dark'
-        ? { colorScheme: 'dark' }
-        : {},
-  );
+  // pin, for a test that is *about* what the desktop reports; `appearance`
+  // pins the rest of what `useSystemAppearance()` reports.
+  setAppearanceForTests(pin);
 
   const root = await createRoot({ app, ...rootOptions });
 
@@ -374,6 +388,131 @@ export async function cleanup() {
   // change, every mounted root repaints on one, and a repaint scheduled onto
   // a connection that is about to close lands after it has.
   setAppearanceForTests(null);
+  setBeforeMount = null;
+}
+
+// --- the desktop's appearance ----------------------------------------------
+
+/**
+ * What a test may pin, and what each value may be — the fields
+ * `useSystemAppearance()` reports, less `source`, which reads `'test'` for as
+ * long as anything is pinned.
+ *
+ * Checked rather than passed through, because the store takes anything: a
+ * `reduceMotion: true` would pin nothing, render the component the way it
+ * always does, and pass a test that was meant to prove the opposite.
+ */
+const APPEARANCE = {
+  colorScheme: [
+    (v) => v === 'light' || v === 'dark' || v === 'no-preference',
+    "'light', 'dark' or 'no-preference'",
+  ],
+  accent: [colourOrNull, "a CSS colour such as '#ed5b00', or null"],
+  accentText: [colourOrNull, "a CSS colour such as '#ffffff', or null"],
+  selection: [colourOrNull, "a CSS colour such as '#c96003', or null"],
+  palette: [
+    (v) => v === null || (typeof v === 'object' && !Array.isArray(v)),
+    'an object of palette tokens, or null',
+  ],
+  contrast: [(v) => v === 'normal' || v === 'high', "'normal' or 'high'"],
+  reducedMotion: [(v) => typeof v === 'boolean', 'true or false'],
+};
+
+function colourOrNull(value) {
+  return value === null || (typeof value === 'string' && value !== '');
+}
+
+function checkAppearance(values, where) {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    throw new TypeError(
+      `react-x11/test: ${where} takes an object of appearance values, such ` +
+        `as { reducedMotion: true } — got ${String(values)}.`,
+    );
+  }
+  for (const [key, value] of Object.entries(values)) {
+    if (key === 'source') {
+      throw new TypeError(
+        `react-x11/test: ${where} cannot set \`source\` — a pinned ` +
+          "appearance reports 'test', which is how a component can tell " +
+          'one from a desktop that answered.',
+      );
+    }
+    const rule = APPEARANCE[key];
+    if (!rule) {
+      throw new TypeError(
+        `react-x11/test: ${where} has no appearance value \`${key}\`. ` +
+          `The values are ${Object.keys(APPEARANCE).join(', ')} — the ` +
+          'fields useSystemAppearance() reports.',
+      );
+    }
+    if (!rule[0](value)) {
+      throw new TypeError(
+        `react-x11/test: ${where}: \`${key}\` is ${rule[1]}, not ` +
+          `${JSON.stringify(value) ?? String(value)}.`,
+      );
+    }
+  }
+  return values;
+}
+
+/** `renderX11`'s two appearance options → the pin, or null to release. */
+function appearancePin(colorScheme, appearance) {
+  if (colorScheme === 'system') {
+    if (appearance) {
+      throw new TypeError(
+        "react-x11/test: renderX11 was given colorScheme: 'system', which " +
+          'follows the real desktop, and `appearance`, which pins it. Pass ' +
+          'one: pin `colorScheme` inside `appearance`, or drop `appearance` ' +
+          'to follow the desktop.',
+      );
+    }
+    return null;
+  }
+  if (colorScheme !== 'light' && colorScheme !== 'dark') {
+    throw new TypeError(
+      "react-x11/test: renderX11's colorScheme is 'light' (the default), " +
+        `'dark' or 'system', not ${JSON.stringify(colorScheme)}.`,
+    );
+  }
+  return {
+    // Light is pinned as "the desktop said nothing", which resolves to the
+    // light palette and is what the mock app pins too
+    ...(colorScheme === 'dark' ? { colorScheme: 'dark' } : {}),
+    ...(appearance ? checkAppearance(appearance, 'renderX11 appearance') : {}),
+  };
+}
+
+/** Values set with nothing mounted, which the next `renderX11` would lose. */
+let setBeforeMount = null;
+
+/**
+ * Change the pinned appearance under a mounted tree, and flush what it
+ * changed — the re-render of everything reading `useSystemAppearance()`, the
+ * palette's repaint, and the frame — the way `userEvent` flushes an input.
+ *
+ * Merged over what is pinned: `setAppearance({ reducedMotion: true })` under
+ * a `colorScheme: 'dark'` render stays dark. Where nothing is pinned
+ * (`colorScheme: 'system'`), it pins these values over the defaults rather
+ * than over this machine's answer, so the result is the test's alone.
+ *
+ * ```js
+ * await renderX11(<Spinner />, { appearance: { reducedMotion: true } });
+ * await setAppearance({ reducedMotion: false });
+ * ```
+ *
+ * The appearance is the desktop's, so it is one for the process: every
+ * mounted root sees the change, as every window would. `cleanup()` releases
+ * it, and a pinned value is never written to the cache the next run of a
+ * real app reads.
+ */
+export async function setAppearance(values) {
+  checkAppearance(values, 'setAppearance()');
+  // `source` comes along and does not matter: the pin overwrites it
+  const next = { ...pinnedAppearanceForTests(), ...values };
+  if (mounted.size === 0) setBeforeMount = { ...setBeforeMount, ...values };
+  await act(() => {
+    setAppearanceForTests(next);
+  });
 }
 
 // --- the animation clock ---------------------------------------------------

package/src/testing/index.d.ts

@@ -5,6 +5,7 @@
 
 import type { ReactNode } from 'react';
 import type { DrawnNode, NtkApp, NtkWindow } from '../types/nodes.js';
+import type { SystemAppearance } from '../types/appearance.js';
 import type { ModifierName } from '../keysyms.js';
 
 export * from '../keysyms.js';
@@ -29,6 +30,14 @@ export interface TestServer {
 /** ntk's 2d context. Pixel helpers take it; `renderX11` hands it back. */
 export type TestContext2D = unknown;
 
+/**
+ * The desktop's appearance as a test pins it: any of the values
+ * `useSystemAppearance()` reports, except `source`, which reads `'test'` for
+ * as long as anything is pinned. A key outside these throws, so a typo cannot
+ * pin nothing and pass.
+ */
+export type PinnedAppearance = Partial<Omit<SystemAppearance, 'source'>>;
+
 export interface RenderX11Options {
   /** Window size (default 640×480). */
   width?: number;
@@ -59,6 +68,21 @@ export interface RenderX11Options {
   title?: string;
   /** Render into a connection you already have. */
   app?: NtkApp;
+  /**
+   * The desktop's colour scheme, **pinned** so a pixel assertion means the
+   * same on every machine. `'light'` (the default) and `'dark'` pick the
+   * built-in palette; `'system'` releases the pin, for a test that is about
+   * what the real desktop reports.
+   */
+  colorScheme?: 'light' | 'dark' | 'system';
+  /**
+   * The rest of the desktop's appearance, pinned from the first render:
+   * reduced motion, contrast, the accent. Merged over `colorScheme`, so
+   * `appearance.colorScheme` wins where both name one; it cannot be combined
+   * with `colorScheme: 'system'`. To change it while mounted, use
+   * `setAppearance()`.
+   */
+  appearance?: PinnedAppearance;
   /**
    * Install the assistive-technology spy before the mount and hand it back
    * as `at`: an in-process log of everything a screen reader would have
@@ -288,9 +312,30 @@ export function renderX11(
  */
 export function act(fn?: () => unknown): Promise<void>;
 
-/** Unmount everything, restore the animation clock, close every server. */
+/**
+ * Unmount everything, restore the animation clock, release the pinned
+ * appearance, close every server.
+ */
 export function cleanup(): Promise<void>;
 
+/**
+ * Change the pinned appearance under a mounted tree and flush what it moved:
+ * every component reading `useSystemAppearance()` re-renders, the palette
+ * repaints, and the frame lands — the way `userEvent` flushes an input.
+ *
+ * Merged over what is pinned, so `setAppearance({ reducedMotion: true })`
+ * under a `colorScheme: 'dark'` render stays dark. The appearance is the
+ * desktop's and so one per process: every mounted root sees the change.
+ * Calling it before `renderX11()` is an error at that render, which pins as
+ * it mounts — pass `appearance` to the render instead.
+ *
+ * ```ts
+ * await renderX11(<Spinner />, { appearance: { reducedMotion: true } });
+ * await setAppearance({ reducedMotion: false });
+ * ```
+ */
+export function setAppearance(values: PinnedAppearance): Promise<void>;
+
 /** Drain in-flight requests on a connection. */
 export function settle(app: NtkApp, roundTrips?: number): Promise<void>;
 

package/src/testing/index.js

@@ -30,6 +30,7 @@ import { setDefaultTarget } from './events.js';
 export {
   act,
   cleanup,
+  setAppearance,
   settle,
   waitFor,
   withFrameClock,

package/src/types/appearance.d.ts

@@ -20,10 +20,10 @@ export type ColorSchemePreference = 'system' | 'light' | 'dark';
  *
  * `'cache'` is the answer this machine gave last time, read off disk before
  * the first render so it does not start from the defaults. A real rung
- * replaces it a moment later.
+ * replaces it a moment later. `'test'` is a value `react-x11/test` pinned.
  */
 export type AppearanceSource =
-  'portal' | 'xsettings' | 'macos' | 'cache' | null;
+  'portal' | 'xsettings' | 'macos' | 'windows' | 'cache' | 'test' | null;
 
 export interface SystemAppearance {
   readonly colorScheme: ColorScheme;

package/src/types/system.d.ts

@@ -247,6 +247,12 @@ export interface DesktopSettings {
   readonly doubleClickDistance: number;
   /** How far a press moves before it is a drag rather than a click. */
   readonly dragThreshold: number;
+  /** **False means hold still** — the desktop asked for less motion:
+   *  `Gtk/EnableAnimations` off over XSETTINGS, reduce motion on macOS.
+   *  Core's loops do not start then (docs/styling.md, "Loops"); an element
+   *  that animates on a timer of its own holds still too, and draws its
+   *  resting frame. True wherever the desktop said nothing. */
+  readonly animations: boolean;
   /** `'xsettings'`; `'macos'` on the Cocoa backend, where only `animations`
    *  comes from the system (reduce motion) and the rest are the defaults; or
    *  null where no settings daemon answered and these are the renderer's own