react-x11 2.36.0 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/appearance.js

@@ -135,12 +135,22 @@ const SAME = (a, b) =>
  * and a re-render per announcement would be churn with nothing behind it.
  */
 function publish(values, source) {
+  // **A pin is a pin.** A rung can answer long after it was asked — the
+  // ladder a test started before releasing its pin, a watcher's next line, a
+  // portal signal — and its answer lands in whatever test is running by
+  // then. Taken, that turns the next test's pixels into this machine's
+  // desktop, which is the one thing the pin exists to prevent.
+  if (owner === 'test' && source !== 'test') return;
   const next = Object.freeze({ ...NOTHING, ...values, source });
   if (SAME(next, snapshot)) return;
   snapshot = next;
-  // What came *off* the disk does not go back onto it, and a pinned test
-  // value must never reach a developer's real cache file.
-  if (source !== 'cache' && source !== 'test') save(next);
+  // Only what a rung answered is remembered. What came *off* the disk does
+  // not go back onto it, a pinned test value must never reach a developer's
+  // real cache file — and nor must the defaults a released pin falls back
+  // to (`source: null`), which every `cleanup()` publishes: written, they
+  // replaced the developer's remembered desktop after every test, and their
+  // next app drew its first frame in the wrong colours.
+  if (source && source !== 'cache' && source !== 'test') save(next);
   for (const fn of [...watchers]) {
     try {
       fn(snapshot);
@@ -162,27 +172,42 @@ function publish(values, source) {
  * Pass `null` to release the pin and let the ladder run again.
  */
 export function setAppearanceForTests(values) {
-  probe = null;
-  // Never touch the developer's own remembered answer either, in either
-  // direction: `publish` will not write a pinned value, and marking the cache
-  // as already checked keeps `load()` from reading one back over it.
-  cacheChecked = true;
   if (values === null) {
-    cacheChecked = false;
     // Releasing undoes a *pin*, and only a pin. A real rung's answer is not
     // this function's to throw away: `cleanup()` releases after every test,
     // and a suite that resolved the appearance for real would otherwise find
-    // it wiped by the harness that was meant to leave it alone.
-    if (owner === 'test') {
-      owner = null;
-      publish({}, null);
-    }
+    // it wiped by the harness that was meant to leave it alone — or, with
+    // the cache marked unread, replaced on the next read by what the disk
+    // says, which is a verified answer turned back into a remembered one.
+    if (owner !== 'test') return;
+    owner = null;
+    probe = null;
+    // Unpinned, the remembered answer is this machine's to read again —
+    // intact, because neither the pin nor this release is ever written
+    // (`publish`).
+    cacheChecked = false;
+    publish({}, null);
     return;
   }
+  probe = null;
+  // Never touch the developer's own remembered answer either, in either
+  // direction: `publish` will not write a pinned value, and marking the cache
+  // as already checked keeps `load()` from reading one back over it.
+  cacheChecked = true;
   owner = 'test';
   publish(values, 'test');
 }
 
+/**
+ * What is pinned right now, or null where nothing is. `react-x11/test`'s
+ * `setAppearance` merges over it, so changing one value keeps the rest of the
+ * pin — and asks the store rather than keeping a copy, which a direct
+ * `setAppearanceForTests` call would leave stale.
+ */
+export function pinnedAppearanceForTests() {
+  return owner === 'test' ? snapshot : null;
+}
+
 // --------------------------------------------------------------------------
 // The last known answer
 // --------------------------------------------------------------------------
@@ -929,6 +954,11 @@ async function runWatcher() {
         answered = true;
         publish(values, 'macos');
         done(true);
+        // Refused, because a test pinned the store while this was starting
+        // (`publish`): nothing will hear this watcher again, and while it
+        // lives the rung starts no other — so the ladder that runs once the
+        // pin is released would find the Mac silent.
+        if (owner === 'test') proc.kill();
       }
     };
     proc.stdout.setEncoding?.('utf8');
@@ -1020,7 +1050,10 @@ async function runLadder(app) {
       answered = false;
     }
     if (answered) {
-      owner = name;
+      // A pin set while this rung was being asked keeps the store: the
+      // rung's answer was refused (`publish`), and owning it would hand the
+      // rung's live updates a store they must not write to.
+      if (owner !== 'test') owner = name;
       return snapshot;
     }
   }

package/src/appearancehooks.js

@@ -73,7 +73,7 @@ export function useAppearanceWhen(enabled) {
  * | `selection` | the fill under a selected menu or list row — a darker cut of the accent on macOS — or **null** |
  * | `contrast` | `'normal'` or `'high'` |
  * | `reducedMotion` | `true` when the user asked for less animation |
- * | `source` | `'portal'`, `'xsettings'`, `'macos'`, `'cache'`, or null |
+ * | `source` | `'portal'`, `'xsettings'`, `'macos'`, `'windows'`, `'cache'`, `'test'` (pinned by `react-x11/test`), or null |
  *
  * **`'no-preference'` means use your own default**, not "use light". And
  * `accent` is null far more often than not, so fall back to your own brand

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;