react-x11 2.15.2 → 2.16.0

package/src/launcher.js

@@ -1,35 +1,55 @@
-// The launcher's view of the app: the badge on its icon.
+// The launcher's view of the app: the badge on its icon, a progress bar
+// across it, an attention flag, and the menu behind a right-click.
 //
 // A count on the Dock tile, a dot on the taskbar entry — the one thing an
 // app says to the desktop that the user reads without opening it. Two
-// desktops, two mechanisms, one call:
+// desktops, two mechanisms, one call each:
 //
-//   1. **the app's own tile** — the cocoa backend's `NSDockTile.badgeLabel`,
-//      reached through the app object (`setDockBadge`, src/cocoa/app.js).
-//      Any string shows, and it is the whole of the API on a Mac.
+//   1. **the app's own tile** — the cocoa backend's `NSDockTile`, reached
+//      through the app object (`setDockBadge`, `setDockMenu`, src/cocoa/
+//      app.js).
 //   2. **`com.canonical.Unity.LauncherEntry`** over the session bus — the
-//      protocol Unity defined and the KDE, elementary and Cairo-Dock
-//      launchers still listen for. One signal, `Update(app_uri, a{sv})`,
-//      carrying a `count` and whether it is visible, attributed to the app
-//      by `application://<id>.desktop` — which is why it needs the identity
+//      protocol Unity defined and the KDE, elementary, Cairo-Dock and
+//      Dash-to-Dock launchers still listen for. One signal,
+//      `Update(app_uri, a{sv})`, attributed to the app by
+//      `application://<id>.desktop` — which is why it needs the identity
 //      `registerApplication({ appId })` established: with no app id there is
-//      nothing for a launcher to pin the count to, and the call resolves
+//      nothing for a launcher to pin anything to, and the calls resolve
 //      false rather than guessing.
 //
-// The two disagree on what a badge *is*, and the API takes the stricter
-// shape: a **count**. A number shows on both; a string shows on macOS and is
-// a visible count of nothing on Linux (the protocol has no text field), so
-// pass a string only where the Mac is the audience. `0`, `null` and `''`
-// all clear it, because a badge of zero is the badge nobody wanted.
+// The badge takes the stricter of the two shapes: a **count**. A number shows
+// on both; a string shows on macOS and is a visible count of nothing on Linux
+// (the protocol has no text field), so pass a string only where the Mac is
+// the audience. `0`, `null` and `''` all clear it, because a badge of zero is
+// the badge nobody wanted.
 //
-// Nothing here imports react: `useBadge` (launcherhooks.js) is the hook, and
-// this is the function under it, callable from host-side code with no tree.
-// The entry on the bus is held for as long as the badge is shown and
-// released when it is cleared — a held bus ref is a ref()'d socket, and an
-// app that cleared its badge on the way out should be free to exit.
+// ## The quicklist is not "desktop actions"
+//
+// This module used to say the freedesktop counterpart of the Dock menu was
+// `Actions=` in the `.desktop` file — an install step, not runtime code — and
+// that the hook was therefore cocoa-only. That was half the story and the
+// wrong half. `LauncherEntry` carries a **`quicklist`** property: an object
+// path to a `com.canonical.dbusmenu` tree, which is the same menu protocol
+// the global menu and the tray already speak, built from the same items. It
+// is runtime, it follows state, and Dash-to-Dock/ubuntu-dock, Plank and the
+// Unity heritage launchers all render it.
+//
+// So `useDockMenu()` has a Linux rung after all, and the three menus an app
+// puts on the desktop — panel, tray, launcher — are now one authoring model
+// on both backends. `.desktop` actions are still the right place for entries
+// that must work *while the app is not running*; they are a different feature
+// wearing a similar hat.
+//
+// Nothing here imports react: `useBadge`/`useDockMenu` (launcherhooks.js) are
+// the hooks, and these are the functions under them, callable from host-side
+// code with no tree. The entry on the bus is held for as long as anything is
+// shown and released when the last of it is cleared — a held bus ref is a
+// ref()'d socket, and an app that cleared its badge on the way out should be
+// free to exit.
 
 import { currentRegistration } from './application.js';
 import { loadTransport, sessionBus } from './bus.js';
+import { DbusMenuExport } from './dbusmenuexport.js';
 import { liveApps } from './trace-registry.js';
 
 export const LAUNCHER_ENTRY_IFACE = 'com.canonical.Unity.LauncherEntry';
@@ -78,6 +98,29 @@ function soleApp() {
 /** The one exported entry per process — an app has one icon. */
 let entry = null;
 
+/**
+ * What the launcher currently believes, so an `Update` can carry the whole of
+ * it. The protocol's dict is a *patch* and every launcher merges it, but
+ * sending the full state makes the call idempotent and means a launcher that
+ * restarted and missed a patch is corrected by the next one of any kind.
+ */
+function blankState() {
+  return {
+    count: 0,
+    countVisible: false,
+    progress: 0,
+    progressVisible: false,
+    urgent: false,
+  };
+}
+
+/** Is anything still being shown? When not, the entry can go. */
+function stateIsEmpty(state, hasMenu) {
+  return (
+    !hasMenu && !state.countVisible && !state.progressVisible && !state.urgent
+  );
+}
+
 async function launcherEntry(appUri) {
   if (entry && entry.appUri === appUri) return entry;
   if (entry) await releaseEntry();
@@ -104,7 +147,17 @@ async function launcherEntry(appUri) {
     await ref.release();
     return null;
   }
-  entry = { appUri, ref, dbus, iface, registration };
+  entry = {
+    appUri,
+    ref,
+    dbus,
+    iface,
+    registration,
+    state: blankState(),
+    menu: null,
+    menuRegistration: null,
+    menuPath: `${launcherEntryPath(appUri)}/Menu`,
+  };
   return entry;
 }
 
@@ -112,10 +165,53 @@ async function releaseEntry() {
   const held = entry;
   entry = null;
   if (!held) return;
+  await held.menuRegistration?.remove?.().catch(() => {});
   await held.registration?.remove?.().catch(() => {});
   await held.ref.release();
 }
 
+/** Emit the whole of the current state under the app's URI. */
+function emit(held) {
+  const V = held.dbus.Variant;
+  const props = {
+    count: new V('x', held.state.count),
+    'count-visible': new V('b', held.state.countVisible),
+    progress: new V('d', held.state.progress),
+    'progress-visible': new V('b', held.state.progressVisible),
+    urgent: new V('b', held.state.urgent),
+  };
+  // Only advertised when there is one: a path to an object that is not
+  // exported makes a launcher build a menu client against nothing, and
+  // Dash-to-Dock keeps the stale client until the path *changes*.
+  if (held.menuRegistration) props.quicklist = new V('o', held.menuPath);
+  held.iface.emit.Update(held.appUri, props);
+}
+
+/**
+ * The shared half of every setter: find the identity, take or make the entry,
+ * let `mutate` move the state, emit, and drop the entry if nothing is left.
+ *
+ * `mutate` returns false to mean "nothing changed and nothing was being
+ * shown" — the case where clearing something that was already clear must not
+ * dial the bus.
+ */
+async function withEntry(mutate, { clearing }) {
+  const appId = currentRegistration()?.appId;
+  if (!appId) {
+    if (clearing && entry) await releaseEntry();
+    return false;
+  }
+  if (clearing && !entry) return false; // nothing shown, nothing to clear
+  const held = await launcherEntry(launcherAppUri(appId));
+  if (!held) return false;
+  mutate(held.state);
+  emit(held);
+  if (stateIsEmpty(held.state, Boolean(held.menuRegistration))) {
+    await releaseEntry();
+  }
+  return true;
+}
+
 /**
  * Show `value` on the app's icon, or clear it.
  *
@@ -144,23 +240,130 @@ export async function setBadge(value, { app } = {}) {
   }
 
   // Rung 2: the launcher protocol, which needs an identity to badge.
+  const count =
+    typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : 0;
+  return withEntry(
+    (state) => {
+      state.count = label === null ? 0 : count;
+      state.countVisible = label !== null;
+    },
+    { clearing: label === null },
+  );
+}
+
+/**
+ * A progress bar across the app's icon: `0`…`1`, or `null` to clear it.
+ *
+ * ```js
+ * await setProgress(downloaded / total);
+ * await setProgress(null);           // done
+ * ```
+ *
+ * The launcher protocol's `progress`, which ubuntu-dock, Plank and the
+ * Unity-heritage launchers draw across the tile. **Inert on the cocoa
+ * backend**: `NSDockTile` has no progress of its own — an app that wants one
+ * on a Mac draws it into a custom tile view, which is app-side art rather
+ * than a call. Resolves to whether a launcher was told.
+ */
+export async function setProgress(value, { app } = {}) {
+  const target = app ?? soleApp();
+  // No cocoa rung to try: the Dock has no progress. Left deliberately without
+  // a `setDockProgress` probe so that adding one to the bridge later is the
+  // only change needed here.
+  void target;
+  const clearing =
+    value == null || value === false || !Number.isFinite(Number(value));
+  const clamped = clearing ? 0 : Math.min(1, Math.max(0, Number(value)));
+  return withEntry(
+    (state) => {
+      state.progress = clamped;
+      state.progressVisible = !clearing;
+    },
+    { clearing },
+  );
+}
+
+/**
+ * Ask the launcher for the user's attention, or stop asking.
+ *
+ * The launcher protocol's `urgent`, which is the tile bouncing or glowing.
+ * Distinct from `<window states={['demands_attention']}>`, which is the
+ * *window's* urgency hint and what a taskbar blinks: this one marks the app's
+ * icon in the launcher whether or not any window is open. On the cocoa
+ * backend the window state is the mechanism and this is inert.
+ */
+export async function setUrgent(urgent, { app } = {}) {
+  void (app ?? soleApp());
+  return withEntry((state) => void (state.urgent = Boolean(urgent)), {
+    clearing: !urgent,
+  });
+}
+
+/**
+ * The menu behind a right-click on the app's launcher icon — the quicklist.
+ *
+ * Takes `MenuBar`'s item vocabulary and exports it as a `com.canonical.dbusmenu`
+ * tree, exactly as the tray and the global menu do. `null` takes it down.
+ * Resolves to whether a launcher was told.
+ *
+ * The menu is exported **before** the property naming it is emitted, so a
+ * launcher that builds its client the instant it sees `quicklist` finds an
+ * object there.
+ */
+export async function setQuicklist(items, { app } = {}) {
+  const target = app ?? soleApp();
+
+  // Rung 1: the app's own tile menu.
+  if (typeof target?.setDockMenu === 'function') {
+    target.setDockMenu(items ?? null);
+    return true;
+  }
+
   const appId = currentRegistration()?.appId;
   if (!appId) {
-    if (label === null) await releaseEntry();
+    if (!items && entry) await releaseEntry();
     return false;
   }
-  const appUri = launcherAppUri(appId);
-  if (label === null && !entry) return false; // nothing shown, nothing to clear
-  const held = await launcherEntry(appUri);
+  if (!items) {
+    // Taking the menu down: drop the export, then say so.
+    if (!entry?.menuRegistration) return false;
+    const held = entry;
+    const registration = held.menuRegistration;
+    held.menuRegistration = null;
+    held.menu = null;
+    await registration?.remove?.().catch(() => {});
+    // `quicklist` is omitted rather than set empty — there is no "no menu"
+    // value in the protocol, and an object path to nothing is worse than a
+    // property a launcher never saw.
+    emit(held);
+    if (stateIsEmpty(held.state, false)) await releaseEntry();
+    return true;
+  }
+
+  const held = await launcherEntry(launcherAppUri(appId));
   if (!held) return false;
-  const count =
-    typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : 0;
-  const V = held.dbus.Variant;
-  held.iface.emit.Update(appUri, {
-    count: new V('x', label === null ? 0 : count),
-    'count-visible': new V('b', label !== null),
+
+  if (held.menu) {
+    // Already exported: this is a re-render, and the tree diffs itself.
+    held.menu.update(items);
+    return true;
+  }
+
+  const menu = new DbusMenuExport({
+    getMenus: () => items,
+    onSelect: (item) => item.onSelect?.(),
+    onAboutToShow: (item) => item.onAboutToShow?.(),
   });
-  if (label === null) await releaseEntry();
+  const iface = menu.defineMenu(held.dbus);
+  try {
+    held.menuRegistration = await held.ref.bus.export(held.menuPath, iface);
+  } catch {
+    return false;
+  }
+  menu.iface = iface;
+  menu.exported = true;
+  held.menu = menu;
+  emit(held);
   return true;
 }
 

package/src/launcherhooks.js

@@ -1,17 +1,21 @@
-// `useBadge()` and `useDockMenu()` — the launcher's view of the app, as
-// things a component declares rather than manages.
+// `useBadge()`, `useProgress()` and `useDockMenu()` — the launcher's view of
+// the app, as things a component declares rather than manages.
 //
-// The badge lives in `launcher.js` and is cross-backend; the Dock menu is
-// the cocoa backend's alone, because its freedesktop counterpart — desktop
-// actions in the `.desktop` file — is an install step and not runtime code.
-// Where a hook has no mechanism it is inert, with a one-time development
-// note naming the backend: the inert-props policy of docs/macos.md, so
-// shared app code stays branch-free.
+// All three now have a rung on both backends except progress, which has one
+// only on Linux (`NSDockTile` has no progress bar; see `setProgress`). Where
+// a hook has no mechanism it is inert and silent: a mark on an icon is not a
+// feature an app should branch on, and a development warning for every
+// desktop that lacks one is a warning nobody can act on.
+//
+// The one that changed shape is `useDockMenu`. It used to be cocoa-only on
+// the grounds that the freedesktop counterpart was an install step — see
+// `launcher.js`, where that reasoning is corrected: the launcher protocol
+// carries a `quicklist` dbusmenu, so the Dock menu is runtime code on both.
 
 import { useEffect, useRef } from 'react';
 
 import { useAppOrNull } from './appcontext.js';
-import { setBadge } from './launcher.js';
+import { setBadge, setProgress, setQuicklist } from './launcher.js';
 
 /**
  * Show `value` on the app's icon while this component is mounted, and clear
@@ -37,12 +41,31 @@ export function useBadge(value) {
   }, [app]);
 }
 
-let warnedInert = false;
+/**
+ * A progress bar across the app's icon, `0`…`1`, cleared on unmount.
+ *
+ * ```jsx
+ * useProgress(done / total); // null or undefined clears it
+ * ```
+ *
+ * Linux launchers only — the Dock has no progress bar of its own.
+ */
+export function useProgress(value) {
+  const app = useAppOrNull();
+  useEffect(() => {
+    setProgress(value, { app }).catch(() => {});
+  }, [value, app]);
+  useEffect(() => {
+    return () => {
+      setProgress(null, { app }).catch(() => {});
+    };
+  }, [app]);
+}
 
 /**
- * The menu behind a right-click on the Dock icon, from the same `items`
- * vocabulary `MenuBar` and `ContextMenu` take — an item's `onSelect` fires
- * when the user picks it.
+ * The menu behind a right-click on the app's icon in the Dock or launcher,
+ * from the same `items` vocabulary `MenuBar` and `ContextMenu` take — an
+ * item's `onSelect` fires when the user picks it.
  *
  * ```jsx
  * useDockMenu([
@@ -53,8 +76,10 @@ let warnedInert = false;
  * ```
  *
  * Installed for as long as the component is mounted, replaced when `items`
- * changes, and taken down on unmount. Inert off the cocoa backend, with a
- * development note the first time.
+ * changes, and taken down on unmount. `NSDockTile`'s menu on the cocoa
+ * backend; the launcher protocol's `quicklist` on Linux, which needs the
+ * identity `registerApplication({ appId })` establishes and a `.desktop` file
+ * of that name for a launcher to attach it to.
  */
 export function useDockMenu(items) {
   const app = useAppOrNull();
@@ -64,18 +89,12 @@ export function useDockMenu(items) {
   live.current = items;
 
   useEffect(() => {
-    if (typeof app?.setDockMenu !== 'function') {
-      if (process.env.NODE_ENV !== 'production' && !warnedInert && app) {
-        warnedInert = true;
-        console.warn(
-          'react-x11: useDockMenu() is inert on this backend — only the ' +
-            'cocoa backend has a Dock. On a Linux desktop the counterpart ' +
-            'is desktop actions in the .desktop file (docs/desktop.md).',
-        );
-      }
-      return undefined;
-    }
-    app.setDockMenu(items ?? null);
-    return () => app.setDockMenu(null);
+    setQuicklist(items ?? null, { app }).catch(() => {});
   }, [items, app]);
+
+  useEffect(() => {
+    return () => {
+      setQuicklist(null, { app }).catch(() => {});
+    };
+  }, [app]);
 }

package/src/node.d.ts

@@ -236,6 +236,13 @@ export interface TextStyle {
   variations: Record<string, number> | undefined;
   textRendering: TextRendering | undefined;
   color: string;
+  /** `letterSpacing`, in device pixels like `size` — undefined unless a
+   * style or the cascade above it named one. */
+  letterSpacing: number | undefined;
+  /** The OpenType features `fontVariantNumeric` and `fontFeatureSettings`
+   * resolve to, tag → 1 on, 0 off or an alternate — undefined unless either
+   * was named. The same object for the same pair of values. */
+  features: Readonly<Record<string, number>> | undefined;
 }
 
 /**

package/src/nodes/animation.js

@@ -40,36 +40,6 @@ const gridContainerMoved = (was, now) =>
 const gridItemMoved = (was, now) =>
   GRID_ITEM_PROPS.some((prop) => was[prop] !== now[prop]);
 
-/**
- * The node whose bounds cover where an animating node will be next frame, or
- * `null` when that cannot be known and the frame has to repaint everything.
- *
- * Three cases, and the middle one is the interesting one:
- *
- *  - **paint-only** (a colour, an opacity): the node stays put, so its own
- *    bounds are the damage.
- *  - **a layout property on an out-of-flow node** (`position: absolute`, the
- *    arrangement a sliding thumb uses): the node moves, so its own bounds
- *    cover where it is going but not where it has been. Its *parent* covers
- *    both — an absolute child is laid out inside its parent and, being out of
- *    flow, moves nothing else when it shifts. This is what keeps a `Switch`
- *    from repainting the window on every frame of its 120ms slide.
- *  - **a layout property in flow**: a reflow can move any node in the tree,
- *    including ones that leave stale pixels outside every bound we could name
- *    here. Nothing to do but repaint in full.
- */
-function damageForAnimation(node) {
-  let movesInLayout = false;
-  for (const prop of node._anim?.keys() ?? []) {
-    if (isLayoutProp(prop)) movesInLayout = true;
-  }
-  if (!movesInLayout) return node;
-  if (node.style?.position !== 'absolute') return null;
-  // A window parent bounds nothing useful — its own rect is the whole surface.
-  const parent = node.parent;
-  return parent && !parent.isWindow ? parent : null;
-}
-
 // Frame timestamps for transitions. Indirected so tests can drive the clock
 // instead of sleeping through real animations.
 export let now = () => Date.now();
@@ -129,7 +99,7 @@ export class NodeAnimation {
         // such presenter, the window's frame clock runs it as it always has.
         if (this._offload(prop, entry)) {
           entry.offloaded = true;
-          this.root?.invalidate(false, damageForAnimation(this), 'animation');
+          this.root?.invalidate(false, this, 'animation');
         } else {
           // …and one the presenter had must not keep running underneath the
           // values the clock is about to write
@@ -342,7 +312,7 @@ export class NodeAnimation {
       }
     }
     this.root?._animating.delete(this);
-    this.root?.invalidate(false, damageForAnimation(this), 'animation');
+    this.root?.invalidate(false, this, 'animation');
   }
 
   /**
@@ -608,7 +578,7 @@ export class WindowAnimation {
     // invalidate anyway, but a React prop change does not — and a transition
     // no one schedules only runs when something else dirties the window,
     // by which time its start is stale and it snaps to the end.
-    this.invalidate(false, damageForAnimation(node), 'animation');
+    this.invalidate(false, node, 'animation');
   }
 
   /**
@@ -618,27 +588,27 @@ export class WindowAnimation {
    */
   _advanceAnimations(now) {
     if (this._animating.size === 0) return;
-    const claims = [];
     for (const node of [...this._animating]) {
       if (node.destroyed) {
         this._animating.delete(node);
         continue;
       }
-      // Decided *before* the tick, deliberately: a tick that finishes deletes
-      // the property from `_anim`, and after that there is no way to tell a
-      // layout animation from a paint-only one — the node's own bounds would
-      // be claimed for something that just moved, leaving a trail behind it.
-      claims.push(damageForAnimation(node));
+      // The node where it stands, which is where it *was*: nothing has been
+      // laid out yet, so its rect is the one the last pass gave it. Where it
+      // goes is the layout pass's to claim. A tick on a layout property asks
+      // for one, and that pass claims the old and new rect of every node it
+      // moves (`_assignAbs`) — this one, and whatever this one pushed, in
+      // flow or out of it. A paint-only property moves nothing, and this
+      // claim is the whole frame.
+      //
+      // Claimed rather than left unbounded because an animation repaints
+      // every frame for as long as it runs: eight height loops in a menu-bar
+      // popover were a full-window repaint per frame at 120Hz (#603). A node
+      // that *finishes* on this tick is claimed too — it just landed on its
+      // final value, and this last frame still has to paint it there.
+      this.invalidate(false, node, 'animation');
       if (!node._tickAnimations(now)) this._animating.delete(node);
     }
     this.needsPaint = true;
-    // Claim a region rather than leaving the frame unbounded: an animation is
-    // a repaint every frame for its whole duration, so this is the difference
-    // between a 120ms transition costing eight full-window repaints and eight
-    // repaints of the thing that moved. Nodes that *finished* on this tick are
-    // claimed too — one just landed on its final value and that last frame
-    // still has to paint it, which is why every transition used to end with a
-    // full-window repaint.
-    for (const claim of claims) this.invalidate(false, claim, 'animation');
   }
 }

package/src/nodes/cascade.js

@@ -190,10 +190,20 @@ export class NodeCascade {
    * A detached node has no ancestors yet and so cannot see a provider two
    * levels up; it still resolves, against the base, and `_themeChanged()` on
    * attach re-resolves it against the real one.
+   *
+   * A window can take its palette from somewhere other than its parent: a
+   * `<ThemeProvider>` above it at the root, which is not its parent because a
+   * top-level window has none, or one directly inside the window it is
+   * nested in, which passed it on to that window. Either is `_scope`, and it
+   * comes first (nodes/scope.js).
    */
   get theme() {
     if (this._theme !== undefined) return this._theme;
-    const inherited = this.parent ? this.parent.theme : baseTheme();
+    const inherited = this._scope
+      ? this._scope.theme
+      : this.parent
+        ? this.parent.theme
+        : baseTheme();
     const own = this.props.theme;
     this._theme = own ? { ...inherited, ...own } : inherited;
     return this._theme;
@@ -312,7 +322,12 @@ export class NodeCascade {
       const size = (inherited.size * to) / from;
       const cached = this._textScaled;
       if (cached?.from !== inherited || cached.style.size !== size) {
-        this._textScaled = { from: inherited, style: { ...inherited, size } };
+        const style = { ...inherited, size };
+        // the other length that travels, re-expressed the same way
+        if (inherited.letterSpacing) {
+          style.letterSpacing = (inherited.letterSpacing * to) / from;
+        }
+        this._textScaled = { from: inherited, style };
       }
       return this._textScaled.style;
     }