react-x11 2.15.2 → 2.16.0

package/src/desktopcapabilityhooks.js

@@ -0,0 +1,160 @@
+// `useDesktopCapability()` — what this desktop can do, as render state.
+//
+// The vocabulary and the probes are `capabilities.js`; this is the part that
+// makes them safe to branch on inside a component. Three things it has to get
+// right, and each is a bug an app would otherwise hit:
+//
+//   1. **The first frame has no answer.** Probing takes a bus round trip, so
+//      the hook returns `NO_CAPABILITY` — available false, empty features —
+//      until one arrives. An app therefore renders its fallback first and
+//      upgrades, which is the right way round: the opposite order flashes a
+//      feature that turns out not to exist.
+//
+//   2. **The answer changes.** A panel restarts, an AppIndicator extension is
+//      toggled, a notification daemon is installed. The hook follows
+//      `NameOwnerChanged` for the whole session rather than sampling once, for
+//      the same reason `globalmenu.js` does: a cached "no" outlives the fix.
+//
+//   3. **The object identity must be stable.** A probe that returned a fresh
+//      object every time would re-render every consumer on every bus event,
+//      and a `features` object in a dependency array would never compare
+//      equal. Results are frozen and replaced only when they differ by value.
+
+import { useEffect, useState } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import { sessionBus } from './bus.js';
+import {
+  NO_CAPABILITY,
+  capabilityNow,
+  desktopCapability,
+} from './capabilities.js';
+
+/** No answer yet: nothing available, and not settled. */
+const PENDING = Object.freeze({ ...NO_CAPABILITY, settled: false });
+
+/** A probe's answer, as the hook hands it out. */
+const settledState = (result) => Object.freeze({ ...result, settled: true });
+
+/** Value equality over the two levels a capability result has. */
+function same(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.available !== b.available || a.backend !== b.backend) return false;
+  if (a.reason !== b.reason || a.settled !== b.settled) return false;
+  const ka = Object.keys(a.features);
+  const kb = Object.keys(b.features);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => a.features[k] === b.features[k]);
+}
+
+/**
+ * What this desktop can do for one feature, as a value a component branches
+ * on.
+ *
+ * ```jsx
+ * const notifications = useDesktopCapability('notifications');
+ *
+ * // The portable question is about the feature, never about the platform.
+ * if (notifications.features.actions) {
+ *   return <ReplyFromBanner />;
+ * }
+ * return <OpenAppToReply available={notifications.available} />;
+ * ```
+ *
+ * `{ available, backend, features }`, starting at
+ * {@link NO_CAPABILITY} and settling a tick later — see the header for why
+ * that order is deliberate. It re-probes whenever a name appears or vanishes
+ * on the session bus, so a panel that starts after the app does is picked up.
+ *
+ * Capability names: `'notifications'`, `'tray'`, `'launcher'`.
+ */
+export function useDesktopCapability(name) {
+  // The app this component is rendered into, when there is one: a process
+  // with several connections has several answers, and the one that matters
+  // here is this tree's.
+  const app = useAppOrNull() ?? undefined;
+  // Settled from the first frame where the answer needed no asking — the
+  // Cocoa app's tray and Dock tile — and pending everywhere else until the
+  // first probe answers, so an app can hold back its fallback instead of
+  // flashing it.
+  const [state, setState] = useState(() => {
+    const now = capabilityNow(name, { app });
+    return now ? settledState(now) : PENDING;
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    let subscription = null;
+    let ref = null;
+    let onChanged = null;
+
+    const probe = () => {
+      desktopCapability(name, { app })
+        .then((next) => {
+          if (cancelled) return;
+          // Replaced only when it differs by value: see the header.
+          const settled = settledState(next);
+          setState((prev) => (same(prev, settled) ? prev : settled));
+        })
+        .catch(() => {});
+    };
+
+    probe();
+
+    // Follow the session for anything appearing or going away. Deliberately
+    // *not* narrowed by `arg0`: one capability can depend on several names
+    // (the tray watcher, the notification daemon, a launcher), and the set is
+    // a detail of `capabilities.js` rather than of this hook. The handler is
+    // a re-probe, so the cost of a wide match is a bus round trip on an event
+    // that is rare in a settled session.
+    void (async () => {
+      ref = await sessionBus();
+      if (!ref || cancelled) {
+        await ref?.release();
+        ref = null;
+        return;
+      }
+      try {
+        subscription = await ref.bus.watch(
+          "type='signal',sender='org.freedesktop.DBus'," +
+            "interface='org.freedesktop.DBus',member='NameOwnerChanged'",
+        );
+      } catch {
+        return;
+      }
+      // The mount/unmount race `AddMatch` always has — see
+      // `GlobalMenuExport.watchRegistrar` for the long version.
+      if (cancelled) {
+        await subscription.remove().catch(() => {});
+        subscription = null;
+        return;
+      }
+      const key = ref.bus.mangle(
+        '/org/freedesktop/DBus',
+        'org.freedesktop.DBus',
+        'NameOwnerChanged',
+      );
+      onChanged = () => probe();
+      ref.bus.signals.on(key, onChanged);
+    })();
+
+    return () => {
+      cancelled = true;
+      void (async () => {
+        if (ref && onChanged) {
+          const key = ref.bus.mangle(
+            '/org/freedesktop/DBus',
+            'org.freedesktop.DBus',
+            'NameOwnerChanged',
+          );
+          ref.bus.signals.removeListener(key, onChanged);
+        }
+        await subscription?.remove().catch(() => {});
+        await ref?.release();
+      })();
+    };
+  }, [name, app]);
+
+  return state;
+}

package/src/filedialoghooks.js

@@ -40,11 +40,9 @@ async function showBuiltin(app, theme, props) {
   const root = await createRoot({ app });
   try {
     return await new Promise((resolve) => {
-      // `<FileDialog>` renders a `<window>`, and a window may only be a root
-      // child or nested in another window — so the palette travels as a prop
-      // and the dialog installs the provider *inside* its own window. Wrapping
-      // it here in `<ThemeProvider>` would put a `<box>` between the root and
-      // the window, which throws.
+      // The dialog is on a root of its own, which no provider in the app's
+      // tree reaches — so the palette the caller resolved travels as a prop,
+      // and the dialog puts it on its window and in a provider inside it.
       root.render(
         React.createElement(FileDialog, { ...props, theme, onDone: resolve }),
       );

package/src/frame/childmain.js

@@ -53,10 +53,7 @@ const h = React.createElement;
 /** Recreate the bridged providers around the pane's window, outermost
  * first — the parent's own nesting order, which the env Map records and
  * structured clone preserves. A key the pane never registered wraps
- * nothing: no module in this process reads it. Providers registered
- * `innermost` (the theme) wrap directly around the window, inside the
- * rest — see registerFrameProvider (src/frame/env.js) for why the
- * adjacency matters. */
+ * nothing: no module in this process reads it. */
 function wrapEnv(env, inner) {
   const wrap = (tree, [key, value]) => {
     const registered = registeredFrameContext(key);
@@ -69,16 +66,8 @@ function wrapEnv(env, inner) {
           tree,
         );
   };
-  const entries = [...env];
-  const isInnermost = ([key]) =>
-    registeredFrameContext(key)?.innermost === true;
   let tree = inner;
-  for (const entry of entries.filter(isInnermost).reverse()) {
-    tree = wrap(tree, entry);
-  }
-  for (const entry of entries.filter((e) => !isInnermost(e)).reverse()) {
-    tree = wrap(tree, entry);
-  }
+  for (const entry of [...env].reverse()) tree = wrap(tree, entry);
   return tree;
 }
 
@@ -118,13 +107,12 @@ function Bridge({ Component, store, rect, invoke, onReady }) {
   }, [onReady]);
 
   // The bridged providers wrap the *window*, not the pane component — the
-  // same position they held in the host. ThemeProvider plants the palette
-  // on a window it finds among its children (theme.js, `planted`), and the
-  // window is where it has to land: the window's own background follows the
-  // palette, and it is the top of the node tree every `$token` beneath
-  // resolves through. Mounted inside the window, the palette reached a box
-  // and the window kept resolving against the pane process's own desktop —
-  // a dark-desktop pane in a light-themed app, wrong in both directions.
+  // same position they held in the host. The theme has to reach the window
+  // itself: the window's own background follows the palette, and it is the
+  // top of the node tree every `$token` beneath resolves through. Mounted
+  // inside the window, the palette reached a box and the window kept
+  // resolving against the pane process's own desktop — a dark-desktop pane
+  // in a light-themed app, wrong in both directions.
   return wrapEnv(
     snapshot.env,
     h(

package/src/frame/env.js

@@ -69,17 +69,9 @@ export function registeredFrameContext(key) {
  * than `Context.Provider`, like `ThemeProvider`, which also plants the
  * palette on a node so `$token` styles resolve. `render(value, children)`
  * returns the wrapped element.
- *
- * `innermost: true` puts the provider directly around the pane's window,
- * inside every other bridged provider. ThemeProvider needs the adjacency:
- * it plants the palette on a window it finds among its *direct* children,
- * and the window is where the palette must land — the window's own
- * background follows it, and the node tree under it is what every `$token`
- * resolves through. Plain context providers have no such constraint and
- * keep the host's nesting order outside.
  */
-export function registerFrameProvider(key, render, { innermost = false } = {}) {
-  registry.set(key, { render, innermost });
+export function registerFrameProvider(key, render) {
+  registry.set(key, { render });
 }
 
 /**

package/src/globalmenu.js

@@ -58,15 +58,7 @@ import { useEffect, useRef, useState } from 'react';
 
 import { loadTransport, sessionBus } from './bus.js';
 import { desktopIntegrationEnabled } from './desktopintegration.js';
-import {
-  DBUSMENU_IFACE,
-  PROPERTY_TYPES,
-  diffSnapshots,
-  groupProperties,
-  layoutOf,
-  snapshot,
-  IdAllocator,
-} from './dbusmenu.js';
+import { DbusMenuExport } from './dbusmenuexport.js';
 import { useAppOrNull } from './appcontext.js';
 import { useTopLevelWindow, windowIdOf } from './windowid.js';
 
@@ -76,9 +68,6 @@ export const REGISTRAR_PATH = '/com/canonical/AppMenu/Registrar';
 const KDE_SERVICE_PROPERTY = '_KDE_NET_WM_APPMENU_SERVICE_NAME';
 const KDE_PATH_PROPERTY = '_KDE_NET_WM_APPMENU_OBJECT_PATH';
 
-/** dbusmenu's recursive layout struct: `(id, properties, children)`. */
-const LAYOUT_SIGNATURE = '(ia{sv}av)';
-
 /**
  * How long the registrar gets to answer.
  *
@@ -162,20 +151,13 @@ function ntkWindowOf(target) {
  * it, and the parts that are awkward (a panel restarting, a window closing
  * mid-call, no bus at all) are awkward in ways React has nothing to say about.
  */
-export class GlobalMenuExport {
+export class GlobalMenuExport extends DbusMenuExport {
   constructor({ getMenus, onSelect, onAboutToShow, target, onChange }) {
-    this.getMenus = getMenus;
-    this.onSelect = onSelect;
-    this.onAboutToShow = onAboutToShow;
+    super({ getMenus, onSelect, onAboutToShow });
     this.target = target;
     this.onChange = onChange ?? (() => {});
 
-    this.alloc = new IdAllocator();
-    this.nodes = snapshot(getMenus(), this.alloc);
-    this.revision = 1;
-
     this.stopped = false;
-    this.exported = false;
     /** The in-flight `sync()`, which the next one queues behind. */
     this.syncing = null;
     this.ref = null;
@@ -443,190 +425,6 @@ export class GlobalMenuExport {
     await this.ref?.release();
     this.ref = null;
   }
-
-  // ----------------------------------------------------------------- update
-
-  /**
-   * A new `menus` array. Serialise, diff, and send the *narrower* of the two
-   * signals the protocol has — see `diffSnapshots`, where the choice is made
-   * and why it matters.
-   */
-  update(menus) {
-    const next = snapshot(menus, this.alloc);
-    const change = diffSnapshots(this.nodes, next);
-    this.nodes = next;
-    if (!this.exported || change.kind === 'none') return;
-
-    if (change.kind === 'properties') {
-      this.iface?.emit.ItemsPropertiesUpdated(
-        change.updated.map(([id, props]) => [id, this.wrap(props)]),
-        change.removed,
-      );
-      return;
-    }
-    this.revision += 1;
-    this.iface?.emit.LayoutUpdated(this.revision, change.parent);
-  }
-
-  /** Plain property values → the `a{sv}` the wire wants. */
-  wrap(props) {
-    const out = {};
-    for (const [name, value] of Object.entries(props)) {
-      const type = PROPERTY_TYPES[name];
-      if (type) out[name] = new this.dbus.Variant(type, value);
-    }
-    return out;
-  }
-
-  /** `layoutOf`'s plain tree → the recursive `(ia{sv}av)`. */
-  wrapLayout(node) {
-    const [id, props, children] = node;
-    return [
-      id,
-      this.wrap(props),
-      children.map(
-        (child) =>
-          new this.dbus.Variant(LAYOUT_SIGNATURE, this.wrapLayout(child)),
-      ),
-    ];
-  }
-
-  // --------------------------------------------------------------- protocol
-
-  itemFor(id) {
-    return this.nodes.get(id)?.item ?? null;
-  }
-
-  defineMenu(dbus) {
-    this.dbus = dbus;
-    const fire = (id, eventId) => {
-      const item = this.itemFor(id);
-      if (!item) return;
-      if (eventId === 'clicked') this.onSelect?.(item);
-      else if (eventId === 'opened') this.onAboutToShow?.(item);
-    };
-
-    return dbus.defineInterface({
-      name: DBUSMENU_IFACE,
-      methods: {
-        GetLayout: {
-          in: { parentId: 'i', recursionDepth: 'i', propertyNames: 'as' },
-          out: { revision: 'u', layout: LAYOUT_SIGNATURE },
-          handler: ({ parentId, recursionDepth, propertyNames }) => {
-            const tree = layoutOf(
-              this.nodes,
-              parentId,
-              recursionDepth ?? -1,
-              propertyNames,
-            );
-            // An id the shell remembers from before a structural change is the
-            // normal way to arrive here, not a protocol violation: answer with
-            // an empty item rather than an error, and let the LayoutUpdated it
-            // has already been sent bring it back for the real tree.
-            return {
-              revision: this.revision,
-              layout: this.wrapLayout(tree ?? [parentId, {}, []]),
-            };
-          },
-        },
-        GetGroupProperties: {
-          in: { ids: 'ai', propertyNames: 'as' },
-          out: { properties: 'a(ia{sv})' },
-          handler: ({ ids, propertyNames }) =>
-            groupProperties(this.nodes, ids, propertyNames).map(
-              ([id, props]) => [id, this.wrap(props)],
-            ),
-        },
-        GetProperty: {
-          in: { id: 'i', name: 's' },
-          out: { value: 'v' },
-          handler: ({ id, name }) => {
-            const props = this.nodes.get(id)?.props;
-            // `hasOwn` on both, so a name like `constructor` reads as absent
-            // rather than as a function that then fails to marshal.
-            const known = Object.hasOwn(PROPERTY_TYPES, name);
-            const value =
-              props && Object.hasOwn(props, name) ? props[name] : undefined;
-            // A property this item does not carry is at its default, and the
-            // spec's own advice is to answer with it rather than to error.
-            if (value === undefined || !known) return new dbus.Variant('s', '');
-            return new dbus.Variant(PROPERTY_TYPES[name], value);
-          },
-        },
-        Event: {
-          in: { id: 'i', eventId: 's', data: 'v', timestamp: 'u' },
-          out: {},
-          handler: ({ id, eventId }) => fire(id, eventId),
-        },
-        EventGroup: {
-          in: { events: 'a(isvu)' },
-          out: { idErrors: 'ai' },
-          handler: ({ events }) => {
-            const errors = [];
-            for (const [id, eventId] of events ?? []) {
-              if (this.itemFor(id)) fire(id, eventId);
-              else errors.push(id);
-            }
-            return errors;
-          },
-        },
-        AboutToShow: {
-          in: { id: 'i' },
-          out: { needUpdate: 'b' },
-          handler: ({ id }) => this.aboutToShow(id),
-        },
-        AboutToShowGroup: {
-          in: { ids: 'ai' },
-          out: { updatesNeeded: 'ai', idErrors: 'ai' },
-          handler: ({ ids }) => {
-            const errors = [];
-            for (const id of ids ?? []) {
-              if (this.itemFor(id)) this.aboutToShow(id);
-              else errors.push(id);
-            }
-            return { updatesNeeded: [], idErrors: errors };
-          },
-        },
-      },
-      properties: {
-        Version: { type: 'u', access: 'read', get: () => 3 },
-        Status: { type: 's', access: 'read', get: () => 'normal' },
-        TextDirection: { type: 's', access: 'read', get: () => 'ltr' },
-        // Empty, and not a placeholder: `icon-name` is looked up in the
-        // desktop's own theme, which is where an app's icons should come from.
-        // A path here would be for icons shipped beside the app.
-        IconThemePath: { type: 'as', access: 'read', get: () => [] },
-      },
-      signals: {
-        LayoutUpdated: { args: { revision: 'u', parent: 'i' } },
-        ItemsPropertiesUpdated: {
-          args: { updated: 'a(ia{sv})', removed: 'a(ias)' },
-        },
-        ItemActivationRequested: { args: { id: 'i', timestamp: 'u' } },
-      },
-    });
-  }
-
-  /**
-   * The reply has to go out **now**, and React has not rendered yet.
-   *
-   * `setState` from here does not produce a new tree before this function
-   * returns, so there is no honest way to answer `true` — and answering `true`
-   * dishonestly is worse than answering `false`: the shell then blocks on a
-   * `GetLayout` for a subtree that has not been built, gets the old one, and
-   * caches it.
-   *
-   * So: answer `false`, let the handler run, and let the ordinary update path
-   * emit `LayoutUpdated` when the new items actually serialise. Shells listen
-   * for that unconditionally — it is the same signal a menu changing while
-   * open produces — so a lazily-built submenu still fills in, one round trip
-   * later than a synchronous toolkit would manage.
-   */
-  aboutToShow(id) {
-    const item = this.itemFor(id);
-    if (item) this.onAboutToShow?.(item);
-    return false;
-  }
 }
 
 /**