react-x11 2.15.3 → 2.16.0

package/src/nodes/window/flush.js

@@ -75,8 +75,8 @@ export class WindowFlush {
 
   /**
    * The backend's half of a frame's cost, where it has one: the Cocoa
-   * present — the swapchain flip and its catch-up copy — runs after the
-   * flush returns, on the same thread, and is part of what the frame cost
+   * present — the swapchain flip — runs after the flush returns, on the
+   * same thread, and is part of what the frame cost
    * (src/cocoa/window.js reports it). An ntk window's present is one
    * request, and reports nothing.
    */
@@ -335,11 +335,12 @@ export class WindowFlush {
     // after every region: an entry drawn in one damage rect must not be
     // evicted before the next rect of the same frame asks for it
     this._paintCache?.endFrame();
-    // The swapchain seam: a backend presenting from double buffers has to
+    // The swapchain seam: a backend presenting from a swapchain has to
     // know exactly which pixels each flush touched — several flushes can
     // land between two presents, so reading only the last frame's rects
-    // would leave the flipped-in back buffer stale where an earlier flush
-    // painted. Feature-detected like presentFrame; null means everything.
+    // would leave the next buffer it draws into stale where an earlier
+    // flush painted. Feature-detected like presentFrame; null means
+    // everything.
     this.window.noteFrameDamage?.(damage ?? null);
     if (frameHook) {
       frameHook({

package/src/nodes/window/popup.js

@@ -30,15 +30,25 @@ export class PopupNode extends WindowNode {
    * from realize looked equivalent until `hidden` existed, and would have
    * left a revealed menu holding no grab: open forever behind the first
    * outside click, with nothing saying why.
+   *
+   * `grabKeyboard` is the keyboard's half, taken and dropped with the map
+   * the same way: keys come to this popup while it is up, whatever holds
+   * the focus — what a popover a tray click opened needs, since a menu-bar
+   * app has no window of its own for the keys to reach. On Cocoa it is a
+   * property of the window rather than a grab, and was decided when the
+   * window was made (src/cocoa/window.js); on Wayland a grabbing popup has
+   * the keyboard already.
    */
   _mapNow() {
     if (!super._mapNow()) return false;
     if (this.props.grab) this.window.grabPointer?.({}, () => {});
+    if (this.props.grabKeyboard) this.window.grabKeyboard?.({}, () => {});
     return true;
   }
 
   destroySubtree() {
     if (this.props.grab) this.window?.ungrabPointer?.();
+    if (this.props.grabKeyboard) this.window?.ungrabKeyboard?.();
     super.destroySubtree();
   }
 

package/src/nodes/window/size.js

@@ -398,6 +398,18 @@ export class WindowSize {
       return { width: props.width, height: props.height, hints };
     }
 
+    // **The floors on hand are the last frame's content.** A node whose
+    // content shrank still carries the minimum the old content needed — the
+    // automatic minimum size this window wrote into yoga — and a natural-size
+    // pass would read it back as content the tree cannot give up, so an
+    // `'auto'` window could only ever grow (#586). The stale ones come off
+    // first, which is exactly what `_applyContentFloors` does ahead of its
+    // own measurement: a node whose extent is stale gets the minimum its
+    // style asks for, and a node whose extent still stands keeps the floor it
+    // earned. The pass after this one measures and writes them again.
+    this._writeFloors('width');
+    this._writeFloors('height');
+
     const dir = this._rootDirection;
     const measure = () => {
       this._sweepLayoutHosts();
@@ -525,9 +537,14 @@ export class WindowSize {
     );
     if (!tracking && !bounded) return;
     const asked = this._requestedSize;
-    const next = this._measure();
-    this._sendSizeHints(props, next.hints);
+    const measured = this._measure();
+    this._sendSizeHints(props, measured.hints);
     if (!tracking) return;
+    // The size the backend will really give, compared against the last one
+    // for the same reason it is recorded: two natural sizes a third of a
+    // point apart are one window size, and asking again every frame for a
+    // size that cannot change is a configure per frame.
+    const next = this._snapSize(measured);
     if (asked && next.width === asked.width && next.height === asked.height) {
       return;
     }
@@ -553,6 +570,27 @@ export class WindowSize {
     this._followAnchor({ width: next.width, height: next.height });
   }
 
+  /**
+   * The size the backend will really take for one this window asks for.
+   *
+   * A window is not always free to be exactly the size its content wants:
+   * Cocoa puts one on the **point** grid, so a natural height of 201 device
+   * pixels at scale 2 is a window 202 tall. Every record of
+   * `_requestedSize` goes through here, because that record is what the
+   * resize echo is compared against — and an echo that does not match it
+   * reads as the user or the window manager taking the size over, which
+   * ends an `'auto'` window's tracking for good (#586). A backend that
+   * takes any size, X11's, answers with the size it was handed.
+   */
+  _snapSize(size) {
+    return (
+      this.window?.snapSize?.(size.width, size.height) ?? {
+        width: size.width,
+        height: size.height,
+      }
+    );
+  }
+
   /** One layout pass at the window's size, with the content floors it
    *  needs: fresh ones when something changed them, the ones in hand during
    *  a live resize, none when nothing moved them. */

package/src/nodes/window/window.js

@@ -11,7 +11,6 @@ import { forgetTopLevel, hasDropProps } from '../../dnd.js';
 import { clearPendingFrame } from '../../frames.js';
 import { FramePacer } from '../../pacing.js';
 import { endWindowState } from '../../windowstate.js';
-import { anchorOffscreen } from '../../anchor.js';
 import { topLevelWindows } from '../../windowid.js';
 import { WindowAnimation } from '../animation.js';
 import { WindowCascade } from '../cascade.js';
@@ -153,6 +152,12 @@ export class WindowNode extends Scrollable(Node) {
     // one flag everything reads (`_mapNow`, painting, a11y, anchoring).
     this._reactHidden = false;
     this.hidden = Boolean(props.hidden);
+    // A `<ThemeProvider>` this window takes its palette from other than its
+    // parent — one written above it at the root, or one directly inside the
+    // window it is nested in, which handed it on — and a third writer of
+    // `hidden`, since React hides the provider's node rather than the window
+    // under it (nodes/scope.js). Null everywhere else.
+    this._scope = null;
     // whether this is the tree's own top-level window rather than a nested
     // one or a popup — decided by realize(), read when it maps
     this._topLevel = false;
@@ -360,6 +365,11 @@ export class WindowNode extends Scrollable(Node) {
     attributes.eventMask = (attributes.eventMask ?? 0) | WINDOW_EVENT_MASK;
     const wnd = this.app.createWindow(attributes);
     this.window = wnd;
+    // What the window actually took, which is not always what was asked
+    // for: Cocoa puts a window on the point grid. The record is what the
+    // resize echo is compared against, so it has to be the size the echo
+    // will carry (#586, `_snapSize`).
+    this._requestedSize = { width: wnd.width, height: wnd.height };
     // Now that the visual is known: settle the capabilities, re-resolve any
     // `@supports` block against them, and start following the compositor.
     // Before the first paint, and before children realize against it.
@@ -422,8 +432,7 @@ export class WindowNode extends Scrollable(Node) {
     // and vanish.
     if (this.props.anchor) {
       this._watchAnchor();
-      const node = this._anchorTarget(this.props.anchor.to);
-      this._anchorLost = !node || anchorOffscreen(node, this.props.anchor.at);
+      this._anchorLost = this._anchorGone();
     }
     // Queued rather than mapped, when there is a commit to queue behind:
     // React hides a subtree only once it has inserted it (beginWindowMaps).
@@ -747,7 +756,7 @@ export class WindowNode extends Scrollable(Node) {
       // The flag `realize()`'s map will read — set directly, since there is
       // nothing on screen yet for the notification half of `_applyHidden`
       // to be about.
-      this.hidden = this._reactHidden || Boolean(newProps.hidden);
+      this.hidden = this._hiddenByReact() || Boolean(newProps.hidden);
       return;
     }
 
@@ -804,10 +813,10 @@ export class WindowNode extends Scrollable(Node) {
     const geo = scaleWindowGeometry(newProps, this.scale);
     if (sizeChanged) {
       this._userSized = false;
-      this._requestedSize = {
+      this._requestedSize = this._snapSize({
         width: isAutoSize(geo.width) ? wnd.width : geo.width,
         height: isAutoSize(geo.height) ? wnd.height : geo.height,
-      };
+      });
     }
     if (geometryChanged) {
       if (typeof wnd.setState === 'function') {
@@ -821,8 +830,15 @@ export class WindowNode extends Scrollable(Node) {
           height: isAutoSize(geo.height) ? undefined : geo.height,
         });
       } else {
-        if (sizeChanged && !isAutoSize(geo.width) && !isAutoSize(geo.height)) {
-          wnd.resize?.(geo.width, geo.height);
+        // A window with no `setState` — Cocoa's — is resized whole or not at
+        // all, so an axis handed back to `'auto'` goes as the size recorded
+        // for it above: the one the window has, which this change leaves
+        // alone. Skipping the call for one `'auto'` axis dropped the other
+        // axis's change on the floor: `_refit()` then found the record
+        // already matching and sent nothing either (#585). With both axes
+        // `'auto'` there is no size to send, and `_refit()` works one out.
+        if (sizeChanged && !(isAutoSize(geo.width) && isAutoSize(geo.height))) {
+          wnd.resize?.(this._requestedSize.width, this._requestedSize.height);
         }
         if (movedByProps) {
           wnd.move?.(geo.x, geo.y);
@@ -887,14 +903,25 @@ export class WindowNode extends Scrollable(Node) {
   }
 
   /**
-   * Re-derive `this.hidden` from its two writers — the reconciler's flag and
-   * the `hidden` prop — and make the window agree. Either saying "hidden"
-   * wins, so a `<Suspense>` revealing its content does not map a window the
-   * app is holding off screen, and clearing the prop does not map one React
-   * still hides.
+   * Whether React is hiding this window: its own flag, or one on the theme
+   * scope it is written under — a `<Suspense>` around a `<ThemeProvider>` at
+   * the root hides the provider's node, the topmost host instance there.
+   * Kept apart from the window's own flag so an inner boundary that still
+   * hides the window is not overruled when an outer one reveals the scope.
+   */
+  _hiddenByReact() {
+    return this._reactHidden || (this._scope?._hiddenByReact() ?? false);
+  }
+
+  /**
+   * Re-derive `this.hidden` from its writers — React, through
+   * `_hiddenByReact`, and the `hidden` prop — and make the window agree.
+   * Either saying "hidden" wins, so a `<Suspense>` revealing its content does
+   * not map a window the app is holding off screen, and clearing the prop
+   * does not map one React still hides.
    */
   _applyHidden() {
-    const hidden = this._reactHidden || Boolean(this.props.hidden);
+    const hidden = this._hiddenByReact() || Boolean(this.props.hidden);
     if (hidden === this.hidden) return;
     this.hidden = hidden;
     // An unmapped window draws nothing, so a loop inside one is frames

package/src/registry.js

@@ -28,6 +28,7 @@ import {
   DRAWN_KINDS,
   CUSTOM_SEMANTIC_NAMES,
   CUSTOM_SELF_DAMAGED,
+  THEME_SCOPE,
 } from './nodes/kinds.js';
 import { Node } from './nodes/node.js';
 import { markLayoutsHotReloadSession } from './layouts.js';
@@ -35,7 +36,7 @@ import { markLayoutsHotReloadSession } from './layouts.js';
 /** kind -> definition. Insertion-ordered, which is the order errors list. */
 const registry = new Map();
 
-const RESERVED = new Set(['textchunk', 'svgchild']);
+const RESERVED = new Set(['textchunk', 'svgchild', THEME_SCOPE]);
 
 // The re-registration policy for hot reload (issue #318). Module-scope
 // registration is the pattern the docs recommend and tree-shaking forces on

package/src/settings.js

@@ -0,0 +1,332 @@
+// What an app remembers between launches (#592): a store of JSON values in
+// the per-user directory for this app, read once, written atomically, and
+// coalesced so a slider's stream of changes is one write when it settles.
+//
+//   const settings = createSettings({
+//     appId: 'com.example.Hush',
+//     defaults: { noiseType: 'brown', volume: 0.5, dark: false },
+//   });
+//   const [volume, setVolume] = settings.use('volume');
+//
+// Every app that remembered anything did this by hand — a directory per
+// platform, serialize, write, debounce — and the easy version of it is wrong
+// in three quiet ways: a crash mid-write leaves half a file, a drag writes on
+// every event, and quitting inside the debounce loses the last change.
+//
+// ## Where
+//
+// One JSON file, `settings.json`, in the app's own directory: under
+// `~/Library/Application Support` on macOS and `$XDG_CONFIG_HOME` (`~/.config`)
+// elsewhere. A file rather than `NSUserDefaults` on macOS, so the format and
+// the behaviour are one thing on every platform. The directory is named by
+// the app id, which is a reverse-DNS name like the one `registerApplication`
+// takes — the store does not register anything, it only needs a name no
+// other app is using.
+//
+// ## When it is read and written
+//
+// Read **synchronously**, the first time a value is asked for, so the first
+// render already has what was saved: an asynchronous read would render the
+// defaults and then jump. It is a small file read once. Written
+// **asynchronously**, a quarter second after the last change and at least
+// once a second while changes keep coming, through a temporary file and a
+// rename, which is atomic: the file on disk is always the old one or the new
+// one. Whatever is still waiting is written synchronously when the process
+// exits, and `flush()` writes it now.
+//
+// Two processes of the same app share the file and the last write wins;
+// nothing here watches for another process changing it.
+
+import * as nodeFs from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** A reverse-DNS app id: two or more dot-separated elements, the grammar
+ *  `registerApplication` checks, which is also a safe directory name. */
+const APP_ID_RE = /^[A-Za-z_-][A-Za-z0-9_-]*(\.[A-Za-z_-][A-Za-z0-9_-]*)+$/;
+
+/** How long a change waits for the next one, and how long a stream of
+ *  changes may put a write off. */
+const DELAY_MS = 250;
+const MAX_WAIT_MS = 1000;
+
+/** The per-user directory apps keep their settings under, for a platform. */
+export function settingsBaseDir({
+  platform = process.platform,
+  env = process.env,
+  home = homedir(),
+} = {}) {
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support');
+  }
+  if (platform === 'win32') {
+    return env.APPDATA || join(home, 'AppData', 'Roaming');
+  }
+  return env.XDG_CONFIG_HOME || join(home, '.config');
+}
+
+/** One store per file in a process, so a module evaluated twice — a hot
+ *  reload — and two call sites naming the same app share their values
+ *  rather than overwriting each other's writes. */
+const stores = new Map();
+
+/**
+ * The settings store for `appId`: values read from and written to its
+ * `settings.json`, with `defaults` for what was never saved.
+ */
+export function createSettings(options = {}) {
+  const { appId, defaults = {}, directory, fs = nodeFs } = options;
+  if (typeof appId !== 'string' || !APP_ID_RE.test(appId)) {
+    throw new Error(
+      `react-x11: createSettings({ appId: ${JSON.stringify(appId)} }) — the ` +
+        "app id names the app's settings directory, so it is a reverse-DNS " +
+        'name no other app uses: two or more dot-separated elements of ' +
+        '[A-Za-z_-][A-Za-z0-9_-]*, like "com.example.myapp".',
+    );
+  }
+  if (defaults === null || typeof defaults !== 'object') {
+    throw new Error(
+      'react-x11: createSettings({ defaults }) — expected an object of each ' +
+        "setting's value when nothing was saved, like { volume: 0.5 }.",
+    );
+  }
+  const path = join(
+    directory ?? join(settingsBaseDir(), appId),
+    'settings.json',
+  );
+  let store = stores.get(path);
+  if (!store) {
+    store = new SettingsStore(path, fs, options);
+    stores.set(path, store);
+  }
+  // the latest module's defaults win, as a reload's edit to them should
+  store._defaults = { ...defaults };
+  return store.api;
+}
+
+class SettingsStore {
+  constructor(path, fs, { delay = DELAY_MS, maxWait = MAX_WAIT_MS }) {
+    this.path = path;
+    this.fs = fs;
+    this.delay = delay;
+    this.maxWait = maxWait;
+    this._defaults = {};
+    this._fallbacks = new Map(); // key -> the first object fallback asked with
+    this._values = null; // what was saved, read on first use
+    this._listeners = new Set();
+    this._timer = null;
+    this._firstPending = 0; // when the oldest unwritten change was made
+    // Changes are counted, and a write records the count it wrote, so a
+    // change is unsaved until a write *finished* with it in — which is what
+    // the exit path asks, since a write still in flight when the process
+    // exits never finishes.
+    this._version = 0;
+    this._savedVersion = 0;
+    this._writing = null; // the write in flight
+    this._onExit = () => this._flushSync();
+
+    const store = this;
+    this.api = {
+      path,
+      get: (key, fallback) => store.get(key, fallback),
+      set: (key, value) => store.set(key, value),
+      reset: (key) => store.reset(key),
+      flush: () => store.flush(),
+      subscribe: (listener) => store.subscribe(listener),
+      /**
+       * `[value, setValue]` for one setting, like `useState` — and every
+       * component using the same key, in any window, sees the same value.
+       */
+      use(key, fallback) {
+        const subscribe = useCallback(
+          (listener) => store.subscribe(listener),
+          [],
+        );
+        const value = useSyncExternalStore(subscribe, () =>
+          store.get(key, fallback),
+        );
+        const setValue = useCallback(
+          (next) =>
+            store.set(
+              key,
+              typeof next === 'function'
+                ? next(store.get(key, fallback))
+                : next,
+            ),
+          [key, fallback],
+        );
+        return [value, setValue];
+      },
+    };
+  }
+
+  _load() {
+    if (this._values) return this._values;
+    this._values = {};
+    let text;
+    try {
+      text = this.fs.readFileSync(this.path, 'utf8');
+    } catch (err) {
+      // never saved is the ordinary first launch; anything else is worth a line
+      if (err?.code !== 'ENOENT') {
+        console.warn(
+          `react-x11: settings at ${this.path} could not be read ` +
+            `(${err.message}); the defaults stand.`,
+        );
+      }
+      return this._values;
+    }
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        this._values = parsed;
+        return this._values;
+      }
+      throw new Error('not an object');
+    } catch (err) {
+      console.warn(
+        `react-x11: settings at ${this.path} are not a JSON object ` +
+          `(${err.message}); the defaults stand, and the next change ` +
+          'replaces the file.',
+      );
+    }
+    return this._values;
+  }
+
+  get(key, fallback) {
+    const values = this._load();
+    if (Object.hasOwn(values, key)) return values[key];
+    if (Object.hasOwn(this._defaults, key)) return this._defaults[key];
+    // An object literal is a new object every render, and a hook's snapshot
+    // that changes every time it is read never settles: the first one stands.
+    if (fallback !== null && typeof fallback === 'object') {
+      if (!this._fallbacks.has(key)) this._fallbacks.set(key, fallback);
+      return this._fallbacks.get(key);
+    }
+    return fallback;
+  }
+
+  set(key, value) {
+    let text;
+    try {
+      text = JSON.stringify(value);
+    } catch (err) {
+      throw new TypeError(
+        `react-x11: settings.set(${JSON.stringify(key)}) — the value has to ` +
+          `be JSON: ${err.message}`,
+      );
+    }
+    if (text === undefined) {
+      throw new TypeError(
+        `react-x11: settings.set(${JSON.stringify(key)}) — ${typeof value} is ` +
+          'not a value JSON can keep; use reset() to go back to the default.',
+      );
+    }
+    const values = this._load();
+    if (Object.hasOwn(values, key) && values[key] === value) return;
+    this._values = { ...values, [key]: value };
+    this._changed();
+  }
+
+  reset(key) {
+    const values = this._load();
+    if (!Object.hasOwn(values, key)) return;
+    const rest = { ...values };
+    delete rest[key];
+    this._values = rest;
+    this._changed();
+  }
+
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  get _unsaved() {
+    return this._savedVersion !== this._version;
+  }
+
+  _changed() {
+    for (const listener of [...this._listeners]) listener();
+    if (!this._unsaved) {
+      this._firstPending = Date.now();
+      process.once('exit', this._onExit);
+    }
+    this._version++;
+    clearTimeout(this._timer);
+    const waited = Date.now() - this._firstPending;
+    const wait = Math.max(0, Math.min(this.delay, this.maxWait - waited));
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      this.flush().catch((err) => {
+        console.warn(
+          `react-x11: settings at ${this.path} could not be written ` +
+            `(${err.message}).`,
+        );
+      });
+    }, wait);
+    // a pending write must not be what keeps the process alive
+    this._timer.unref?.();
+  }
+
+  /** Write what is waiting now. Resolves when it is on disk. */
+  async flush() {
+    clearTimeout(this._timer);
+    this._timer = null;
+    // one write at a time, and a change made during one is written after it;
+    // the one before failing is that write's to report, not this one's
+    while (this._writing) await this._writing.catch(() => {});
+    if (!this._unsaved) return;
+    const version = this._version;
+    const text = `${JSON.stringify(this._values, null, 2)}\n`;
+    this._writing = this._write(text).finally(() => {
+      this._writing = null;
+    });
+    await this._writing;
+    this._savedVersion = version;
+    // saved, unless something changed while it was written
+    if (!this._unsaved) process.removeListener('exit', this._onExit);
+  }
+
+  async _write(text) {
+    const fs = this.fs.promises;
+    const temp = `${this.path}.${process.pid}.tmp`;
+    await fs.mkdir(dirname(this.path), { recursive: true });
+    const handle = await fs.open(temp, 'w');
+    try {
+      await handle.writeFile(text);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(temp, this.path);
+  }
+
+  /** The exit path, where nothing asynchronous runs any more. */
+  _flushSync() {
+    if (!this._unsaved) return;
+    this._savedVersion = this._version;
+    try {
+      const temp = `${this.path}.${process.pid}.tmp`;
+      this.fs.mkdirSync(dirname(this.path), { recursive: true });
+      this.fs.writeFileSync(temp, `${JSON.stringify(this._values, null, 2)}\n`);
+      this.fs.renameSync(temp, this.path);
+    } catch (err) {
+      console.warn(
+        `react-x11: settings at ${this.path} could not be written on exit ` +
+          `(${err.message}).`,
+      );
+    }
+  }
+}
+
+/** Forget every store — for tests that create stores over temporary
+ *  directories and want the next `createSettings` to read afresh. */
+export function resetSettingsForTests() {
+  for (const store of stores.values()) {
+    clearTimeout(store._timer);
+    process.removeListener('exit', store._onExit);
+  }
+  stores.clear();
+}