react-x11 2.6.0 → 2.7.0

package/src/cocoa/globalmenu.js

@@ -51,6 +51,41 @@ function keyEquivalent(shortcut) {
   return { key: key.toLowerCase(), modifiers: modifiers || FLAG_COMMAND };
 }
 
+/**
+ * A dbusmenu snapshot (`snapshot()`'s `Map<id, node>`) as the bridge's menu
+ * item spec — the vocabulary `setMainMenu`, `setDockMenu` and a status
+ * item's menu all take, so the menu bar, the Dock menu and the tray are one
+ * builder. `ids` defaults to the root's children.
+ */
+export function menuItemsSpec(nodes, ids = nodes.get(ROOT_ID).childIds) {
+  return ids.map((id) => {
+    const node = nodes.get(id);
+    const props = node.props;
+    const out = { id };
+    if (props.type === 'separator') {
+      out.separator = true;
+      if (props.visible === false) out.hidden = true;
+      return out;
+    }
+    out.title = String(props.label ?? '');
+    if (props.enabled === false) out.enabled = false;
+    if (props.visible === false) out.hidden = true;
+    if (props['toggle-state'] === 1) out.checked = true;
+    // the serialisable icon pair (menuitem.js): the name is read in the
+    // platform's icon theme — SF Symbols here, freedesktop on a Linux panel
+    // — and the bytes are the literal-pixel fallback
+    if (props['icon-name']) out.iconName = props['icon-name'];
+    if (props['icon-data']) out.iconData = props['icon-data'];
+    const key = keyEquivalent(props.shortcut);
+    if (key) {
+      out.key = key.key;
+      out.modifiers = key.modifiers;
+    }
+    if (node.childIds.length) out.items = menuItemsSpec(nodes, node.childIds);
+    return out;
+  });
+}
+
 export class CocoaGlobalMenuExport {
   constructor(app, { getMenus, onSelect, onAboutToShow, target, onChange }) {
     this.app = app;
@@ -93,35 +128,7 @@ export class CocoaGlobalMenuExport {
    * `activate` like every real item.
    */
   _spec() {
-    const itemsOf = (ids) =>
-      ids.map((id) => {
-        const node = this.nodes.get(id);
-        const props = node.props;
-        const out = { id };
-        if (props.type === 'separator') {
-          out.separator = true;
-          if (props.visible === false) out.hidden = true;
-          return out;
-        }
-        out.title = String(props.label ?? '');
-        if (props.enabled === false) out.enabled = false;
-        if (props.visible === false) out.hidden = true;
-        if (props['toggle-state'] === 1) out.checked = true;
-        // the serialisable icon pair (menuitem.js): the name is read in
-        // the platform's icon theme — SF Symbols here, freedesktop on a
-        // Linux panel — and the bytes are the literal-pixel fallback
-        if (props['icon-name']) out.iconName = props['icon-name'];
-        if (props['icon-data']) out.iconData = props['icon-data'];
-        const key = keyEquivalent(props.shortcut);
-        if (key) {
-          out.key = key.key;
-          out.modifiers = key.modifiers;
-        }
-        if (node.childIds.length) out.items = itemsOf(node.childIds);
-        return out;
-      });
-    const root = this.nodes.get(ROOT_ID);
-    const menus = itemsOf(root.childIds).map((menu) => ({
+    const menus = menuItemsSpec(this.nodes).map((menu) => ({
       title: menu.title ?? '',
       items: menu.items ?? [],
     }));
@@ -137,10 +144,11 @@ export class CocoaGlobalMenuExport {
   /** A backend menu-activate event landed on this export. */
   activate(id) {
     if (id === QUIT_ID) {
-      // the same route the close button takes: the app decides what
-      // closing means, exactly as it would for the red light
-      const wnd = this.target?.window ?? [...this.app._windows.values()][0];
-      wnd?.emit('close', { preventDefault() {} });
+      // ⌘Q is a quit request like the Dock's and a logout's: one route for
+      // all of them (`CocoaApp.requestQuit`), which is the primary window's
+      // close request — the app decides what closing means, exactly as it
+      // would for the red light
+      this.app.requestQuit();
       return;
     }
     const item = this.nodes?.get(id)?.item;

package/src/cocoa/notifications.js

@@ -0,0 +1,244 @@
+// Desktop notifications on the cocoa backend — `UNUserNotificationCenter`
+// through @windowkit/appkit (>= 0.5), the top rung of src/notifications.js's
+// ladder. `CocoaApp.notifications` is this object; its presence is the
+// capability, and its `available()` is the second gate: the centre only
+// delivers for a code-signed app bundle with a bundle id, and a bare `node`
+// process reports itself unavailable so the ladder can move on to
+// `osascript` rather than post into the void.
+//
+// Three things about the system shape the code:
+//
+// - **Authorization is the system's prompt, once per bundle.** The first
+//   post from an app the user has not answered for asks first, and a
+//   refusal is a refusal — reported, not fallen through.
+// - **Actions are categories.** The centre knows an action set only as a
+//   registered category, and `setNotificationCategories` *replaces* the set,
+//   so every distinct action list this process has used stays registered
+//   under a name derived from its keys. A click on the banner itself is the
+//   action `default`, the freedesktop word the ladder speaks.
+// - **The user's answer comes back as an event** on the app's callback,
+//   naming the notification by identifier — `notification-action` and
+//   `notification-dismissed`, which the app routes here.
+
+function categoryId(actions) {
+  return `react-x11:${actions.map((a) => a.key).join(',')}`;
+}
+
+export class CocoaNotifications {
+  constructor(app) {
+    this.app = app;
+    this._native = app._native;
+    this._handles = new Map(); // identifier -> handle
+    this._categories = new Map(); // id -> { id, actions }
+    this._settings = null;
+    this._authorized = null;
+  }
+
+  /** The bridge's settings, read once — `available` is the bundle question. */
+  settings() {
+    if (this._settings) return this._settings;
+    this._settings = new Promise((resolve) => {
+      try {
+        this._native.notificationSettings((s) =>
+          resolve(s ?? { available: false }),
+        );
+      } catch {
+        resolve({ available: false });
+      }
+    });
+    return this._settings;
+  }
+
+  async available() {
+    const s = await this.settings();
+    return s?.available === true;
+  }
+
+  /**
+   * Ask once; the system remembers, and so does this.
+   *
+   * Three answers, not two. `granted` and `denied` are the obvious pair, and
+   * `unasked` is the one that matters: a falsy `granted` does **not** mean
+   * the user said no. A bundle Launch Services has never registered — an
+   * ad-hoc signature in a temp directory, say — gets no prompt at all, and
+   * the request comes back refused with the status still `notDetermined`.
+   * Calling that a refusal would tell the user they declined something they
+   * were never shown, and would stop a ladder that has every right to carry
+   * on: nobody has turned anything off. So the status is read again
+   * afterwards, and it is the system, not the boolean, that says which
+   * happened.
+   *
+   * @returns {Promise<'granted'|'denied'|'unasked'>}
+   */
+  async _authorize() {
+    if (this._authorized != null) return this._authorized;
+    const s = await this.settings();
+    if (
+      s.authorizationStatus === 'authorized' ||
+      s.authorizationStatus === 'provisional'
+    ) {
+      this._authorized = 'granted';
+      return this._authorized;
+    }
+    if (s.authorizationStatus === 'denied') {
+      this._authorized = 'denied';
+      return this._authorized;
+    }
+    const granted = await new Promise((resolve) => {
+      try {
+        this._native.requestNotificationAuthorization(
+          ['alert', 'sound', 'badge'],
+          (ok) => resolve(Boolean(ok)),
+        );
+      } catch {
+        resolve(false);
+      }
+    });
+    if (granted) {
+      this._authorized = 'granted';
+      return this._authorized;
+    }
+    // Refused — by the user, or by a system that never asked one. The prompt
+    // moves the status off `notDetermined`; nothing else does.
+    this._settings = null;
+    const after = await this.settings();
+    if (after.authorizationStatus === 'notDetermined') {
+      // Not cached: a later post, from a bundle the system has since
+      // registered, deserves the prompt this one never got.
+      return 'unasked';
+    }
+    this._authorized = 'denied';
+    return this._authorized;
+  }
+
+  _ensureCategory(actions) {
+    if (!actions?.length) return undefined;
+    const id = categoryId(actions);
+    if (!this._categories.has(id)) {
+      this._categories.set(id, {
+        id,
+        actions: actions.map((a) => ({
+          id: a.key,
+          title: a.label ?? a.key,
+          foreground: true,
+        })),
+      });
+      this._native.setNotificationCategories([...this._categories.values()]);
+    }
+    return id;
+  }
+
+  _props(options, identifier) {
+    const props = {
+      title: options.summary,
+      body: options.body ?? '',
+      sound: options.silent ? null : 'default',
+    };
+    if (identifier) props.identifier = identifier;
+    if (options.subtitle) props.subtitle = options.subtitle;
+    const categoryId = this._ensureCategory(options.actions);
+    if (categoryId) props.categoryId = categoryId;
+    if (options.userInfo) props.userInfo = options.userInfo;
+    return props;
+  }
+
+  /**
+   * Post, if the user has allowed it.
+   *
+   * `null` rather than a throw when the centre could not ask (see
+   * `_authorize`): the ladder reads that as "this rung cannot serve" and
+   * moves on. A real refusal still throws, because it is an answer.
+   */
+  async post(options) {
+    const auth = await this._authorize();
+    if (auth === 'denied') {
+      const err = new Error(
+        'react-x11: notifications are not allowed for this app — the user ' +
+          'declined them in System Settings › Notifications.',
+      );
+      err.name = 'NotificationsDeniedError';
+      throw err;
+    }
+    if (auth !== 'granted') return null;
+    const handle = new CocoaHandle(this, options);
+    await handle._post({});
+    return handle;
+  }
+
+  /** `notification-action` / `notification-dismissed` from the app. */
+  route(ev) {
+    const handle = this._handles.get(ev.identifier);
+    if (!handle) return;
+    if (ev.type === 'notification-action') {
+      handle._action(
+        ev.actionId === 'default' ? 'default' : String(ev.actionId),
+      );
+    } else if (ev.type === 'notification-dismissed') {
+      this._handles.delete(ev.identifier);
+      handle._closed('dismissed');
+    }
+  }
+}
+
+class CocoaHandle {
+  constructor(centre, options) {
+    this.backend = 'cocoa';
+    this.id = null;
+    this._centre = centre;
+    this._options = options;
+    this._done = false;
+  }
+
+  _post(patch) {
+    const centre = this._centre;
+    const native = centre._native;
+    this._options = { ...this._options, ...patch };
+    const props = centre._props(this._options, this.id);
+    return new Promise((resolve, reject) => {
+      const done = (error) => (error ? reject(error) : resolve(this));
+      try {
+        if (this.id) {
+          native.updateNotification(this.id, props, done);
+        } else {
+          this.id = native.postNotification(props, done);
+          centre._handles.set(this.id, this);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  update(patch = {}) {
+    if (this._done) return Promise.resolve(this);
+    return this._post(patch);
+  }
+
+  async close() {
+    if (this._done || !this.id) return;
+    this._centre._handles.delete(this.id);
+    try {
+      this._centre._native.removeNotification(this.id);
+    } finally {
+      this._closed('closed');
+    }
+  }
+
+  _action(key) {
+    try {
+      this._options.onAction?.(key);
+    } catch (err) {
+      console.error('react-x11: a notification action handler threw', err);
+    }
+  }
+
+  _closed(reason) {
+    if (this._done) return;
+    this._done = true;
+    try {
+      this._options.onClose?.(reason);
+    } catch (err) {
+      console.error('react-x11: a notification close handler threw', err);
+    }
+  }
+}

package/src/cocoa/permissions.js

@@ -0,0 +1,74 @@
+// macOS privacy authorizations (TCC) on the cocoa backend, through
+// @windowkit/appkit (>= 0.5): the rung that answers in src/permissions.js's
+// ladder. `CocoaApp.permissions` is this object and its presence is the
+// capability, the rule `filePanels` and `nativeBezels` follow.
+//
+// The bridge is mechanism — `authorizationStatus(kind, opts?)` never
+// prompts, `requestAuthorization(kind, opts?, cb)` raises the system's
+// prompt where a framework offers one and answers once, asynchronously,
+// `openPrivacySettings(kind?)` deep-links — and its vocabulary is Apple's.
+// What is decided here is the translation into the ladder's five words,
+// and one thing worth knowing: a bare `node` process is attributed to its
+// responsible process (the terminal, an IDE) or to `node` itself, and a
+// bundled app must carry the usage-description keys
+// (`NSCameraUsageDescription` and friends) or a request never prompts.
+
+/** Apple's four words as the ladder's. */
+const STATUS = Object.freeze({
+  authorized: 'granted',
+  denied: 'denied',
+  restricted: 'restricted',
+  notDetermined: 'prompt',
+});
+
+export function statusFromBridge(status) {
+  return STATUS[status] ?? 'unknown';
+}
+
+/** The bridge's options for a kind: `automation` carries its target. */
+function bridgeOptions(kind, options = {}) {
+  return kind === 'automation' && options.target != null
+    ? { target: String(options.target) }
+    : undefined;
+}
+
+export class CocoaPermissions {
+  constructor(native) {
+    this._native = native;
+  }
+
+  status(kind, options) {
+    const opts = bridgeOptions(kind, options);
+    return statusFromBridge(
+      opts
+        ? this._native.authorizationStatus(kind, opts)
+        : this._native.authorizationStatus(kind),
+    );
+  }
+
+  request(kind, options) {
+    const opts = bridgeOptions(kind, options);
+    return new Promise((resolve, reject) => {
+      const done = (granted, status) =>
+        resolve(
+          status != null
+            ? statusFromBridge(status)
+            : granted
+              ? 'granted'
+              : 'denied',
+        );
+      try {
+        if (opts) this._native.requestAuthorization(kind, opts, done);
+        else this._native.requestAuthorization(kind, done);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  openSettings(kind) {
+    if (kind == null) this._native.openPrivacySettings();
+    else this._native.openPrivacySettings(kind);
+    return true;
+  }
+}

package/src/cocoa/presenter.js

@@ -32,6 +32,7 @@ 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
@@ -324,9 +325,8 @@ const EDGE_PROPS = [
   'borderEndWidth',
 ];
 
-function stylePaintsPlain(node) {
+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,6 +339,26 @@ function stylePaintsPlain(node) {
   return uniformRadius(style.borderRadius) !== null;
 }
 
+/**
+ * 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;
+
 function uniformRadius(radius) {
   if (radius === undefined) return 0;
   if (typeof radius === 'number') return radius;
@@ -439,6 +459,10 @@ 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: accepted and waiting for the
+    // frame that attaches them, and running in the render server
+    this.pendingAnimations = new Map(); // node -> Map(prop -> entry)
+    this.liveAnimations = new Map(); // node -> Map(id -> { prop, key, entry })
     // 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 +572,7 @@ export class CocoaLayerPresenter {
           visual.destroy();
           this.visuals.delete(node);
           this._dropRaster(node);
+          this._dropAnimations(node, false);
           const bars = this.bars.get(node);
           if (bars) {
             for (const entry of bars.values()) {
@@ -612,8 +637,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._dropAnimations(node, true);
       visual = null;
     }
+    if (wantsRaster && this.pendingAnimations.has(node)) {
+      this._dropAnimations(node, true);
+    }
     if (!visual) {
       visual = new Visual(this, node);
       visual.isRaster = wantsRaster;
@@ -728,6 +759,163 @@ export class CocoaLayerPresenter {
           ])
         : [0, 0, 0, 0],
     });
+    // after the model value went out, inside the same transaction
+    this._applyAnimations(node, visual);
+  }
+
+  // --- 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.
+
+  /**
+   * 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.
+   */
+  animate(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.pendingAnimations.get(node);
+    if (!pending) this.pendingAnimations.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.pendingAnimations.get(node)?.delete(prop);
+    this._removeLive(node, prop);
+  }
+
+  _ends() {
+    const app = this.window.app;
+    return (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.window.app._parseColor(value) ?? null)
+        : null;
+    }
+    return typeof value === 'number'
+      ? value / (map.scaled ? this.scale : 1)
+      : null;
+  }
+
+  /** The frame's half: attach what `animate` accepted, after the model
+   *  value went out, inside the same transaction. */
+  _applyAnimations(node, visual) {
+    const pending = this.pendingAnimations.get(node);
+    if (!pending) return;
+    this.pendingAnimations.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?.(
+          visual.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(visual.layer, map.keyPath, opts, key);
+      // looked up after the removals above, which may have pruned the map
+      let live = this.liveAnimations.get(node);
+      if (!live) this.liveAnimations.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.liveAnimations.get(node);
+    if (!live) return;
+    const visual = this.visuals.get(node);
+    for (const [id, run] of live) {
+      if (run.prop !== prop) continue;
+      live.delete(id);
+      this._ends().delete(id);
+      if (visual) this.native.removeAnimation(visual.layer, run.key);
+    }
+    if (live.size === 0) this.liveAnimations.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.liveAnimations.get(node);
+    const run = live?.get(id);
+    if (!run) return;
+    live.delete(id);
+    if (live.size === 0) this.liveAnimations.delete(node);
+    node._offloadEnded(run.prop, run.entry);
+  }
+
+  /** 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. */
+  _dropAnimations(node, reclaim) {
+    const pending = this.pendingAnimations.get(node);
+    if (pending) {
+      this.pendingAnimations.delete(node);
+      for (const [prop, entry] of pending) {
+        if (reclaim) node._offloadDeclined(prop, entry);
+        else node._offloadEnded(prop, entry);
+      }
+    }
+    const live = this.liveAnimations.get(node);
+    if (!live) return;
+    this.liveAnimations.delete(node);
+    for (const [id, run] of live) {
+      this._ends().delete(id);
+      node._offloadEnded(run.prop, run.entry);
+    }
   }
 
   /**