react-x11 2.16.1 → 2.17.0

package/src/notifications.js

@@ -429,6 +429,19 @@ function centreFor(options) {
   return app?.notifications ?? null;
 }
 
+/**
+ * Which rung a backend's own notification centre is.
+ *
+ * The seam is the backend's, not macOS's: a centre answers `available()` and
+ * `post()`, and the cocoa one was simply the first. `kind` is how a centre
+ * says which rung it is, so `notificationBackend()` reports the truth rather
+ * than the name of whoever got here first. Cocoa's predates the field and is
+ * the default.
+ */
+function kindOf(centre) {
+  return centre?.kind ?? 'cocoa';
+}
+
 /**
  * Which rung this machine lands on, without posting anything.
  *
@@ -442,10 +455,11 @@ function centreFor(options) {
 export async function notificationBackend(options = {}) {
   const backend = options.backend;
   const want = (rung) => !backend || backend === rung;
-  if (want('cocoa')) {
-    const centre = centreFor(options);
-    if (centre && (await centre.available())) return 'cocoa';
-    if (backend === 'cocoa') return null;
+  const centre = centreFor(options);
+  const kind = kindOf(centre);
+  if (want(kind)) {
+    if (centre && (await centre.available())) return kind;
+    if (backend === kind) return null;
   }
   if (want('dbus')) {
     const ref = await sessionBus();
@@ -461,7 +475,14 @@ export async function notificationBackend(options = {}) {
   if (want('osascript') && (process.platform === 'darwin' || backend)) {
     return 'osascript';
   }
-  if (want('notify-send') && (process.platform !== 'darwin' || backend)) {
+  // `notify-send` is a freedesktop tool. Windows has neither it nor a shell
+  // command that shows a notification, so the rung above is the floor there
+  // and `null` is the honest answer when the tree is not on the win32
+  // backend — a spawn that would fail with ENOENT is not a rung.
+  if (
+    want('notify-send') &&
+    (backend || (process.platform !== 'darwin' && process.platform !== 'win32'))
+  ) {
     return 'notify-send';
   }
   return null;
@@ -497,26 +518,28 @@ export async function notify(options = {}) {
   const backend = options.backend;
   const want = (rung) => !backend || backend === rung;
 
-  if (want('cocoa')) {
-    const centre = centreFor(options);
+  const centre = centreFor(options);
+  const kind = kindOf(centre);
+  if (want(kind)) {
     if (centre && (await centre.available())) {
       const handle = await centre.post(options);
       if (handle) return handle;
       // The bundle is right and the centre is there, but the system never
       // put the prompt in front of anybody, so nobody declined: not the
       // refusal above, and no reason to stop. The ladder moves on.
-      if (backend === 'cocoa') {
+      if (backend === kind) {
         throw new NoNotificationServiceError(
-          "backend: 'cocoa' — the centre could not ask for authorization " +
+          `backend: '${kind}' — the centre could not ask for authorization ` +
             '(the status is still notDetermined). A bundle macOS has not ' +
             'registered never gets the prompt (docs/notifications.md).',
         );
       }
-    } else if (backend === 'cocoa') {
+    } else if (backend === kind) {
       throw new NoNotificationServiceError(
-        "backend: 'cocoa' — no notification centre here: the tree is not " +
-          'on the cocoa backend, the bridge is older than 0.5, or this ' +
-          'process is not an app bundle (docs/notifications.md).',
+        `backend: '${kind}' — no notification centre here: the tree is not ` +
+          'on a backend that has one, the bridge is older than the version ' +
+          'that added it, or on macOS this process is not an app bundle ' +
+          '(docs/notifications.md).',
       );
     }
   }
@@ -534,7 +557,9 @@ export async function notify(options = {}) {
   const shell =
     want('osascript') && (process.platform === 'darwin' || backend)
       ? 'osascript'
-      : want('notify-send') && (process.platform !== 'darwin' || backend)
+      : want('notify-send') &&
+          (backend ||
+            (process.platform !== 'darwin' && process.platform !== 'win32'))
         ? 'notify-send'
         : null;
   if (shell) {

package/src/taskbarhooks.js

@@ -0,0 +1,164 @@
+// The Windows taskbar's own surfaces, as hooks.
+//
+// Three things the taskbar has that no other desktop does, so none of them is
+// a rung on an existing ladder and none of them pretends to be portable. What
+// makes them safe to use anyway is that the answer to "is this here" is a
+// value a component branches on rather than a platform check, and the hooks
+// below do nothing at all where the backend has not installed them. An app
+// writes the same tree everywhere and gets the feature where it exists.
+//
+// ```jsx
+// const launcher = useDesktopCapability('launcher');
+// useThumbnailToolbar(
+//   launcher.features.thumbnailToolbar ? [
+//     { id: 'prev', tooltip: 'Previous', icon: prevIcon },
+//     { id: 'play', tooltip: playing ? 'Pause' : 'Play', icon: playIcon },
+//   ] : null,
+//   (id) => transport(id),
+// );
+// ```
+//
+// They are **features of the launcher** — the same rung as the badge and the
+// progress bar, since all of them hang off the one icon the desktop shows for
+// this app — and not entries in `useSupports()`, which answers for the
+// display. The seam is one rule: the backend installs a method, and its
+// presence is the capability; the probe in `src/capabilities.js` reads those
+// same methods, so the prediction and the hook cannot disagree. Nothing here
+// knows what Windows is, and neither does anything in an app that uses it.
+import { useEffect, useRef } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import { liveApps } from './trace-registry.js';
+import { useTopLevelWindow } from './windowid.js';
+
+/** The app to act on when the caller did not say — the same rule the
+ *  launcher's own imperative calls use. */
+function soleApp() {
+  const apps = liveApps();
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((app) => (app._rootChildren ?? []).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
+/** The value a caller passed, read by an effect that must not re-run for it. */
+function useLatest(value) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+/** A stable key for a button list, so an effect re-runs when one actually
+ *  changed rather than on every render. Icons compare by identity — a caller
+ *  holding its icons still is the fast path, and one that rebuilds them every
+ *  render was going to re-upload them anyway. */
+function signatureOf(buttons) {
+  if (!buttons) return '';
+  return buttons
+    .map(
+      (b) =>
+        `${b.id ?? ''}\u0000${b.tooltip ?? b.label ?? ''}\u0000` +
+        `${b.enabled === false ? 0 : 1}${b.dismissOnClick ? 1 : 0}`,
+    )
+    .join('\u0001');
+}
+
+/**
+ * Up to seven buttons under this window's taskbar hover preview — where a
+ * media player puts play and skip.
+ *
+ * `buttons` is `[{ id, tooltip, icon, enabled, dismissOnClick }]`, and `icon`
+ * is whatever `useTray` takes: an ntk `Image`, raw RGBA with a size, or a
+ * path. `null` takes the toolbar down as far as the shell allows, which is to
+ * hide the buttons — a toolbar cannot be removed once the window has one, and
+ * saying so is better than a call that looks like it worked.
+ *
+ * `onClick` is called with the button's own `id`.
+ *
+ * Does nothing where the backend has no toolbar. The eighth button and beyond
+ * are dropped rather than refused, because the shell refuses the whole call
+ * for an eighth and one silently missing button is a better outcome than a
+ * toolbar that never appears.
+ */
+export function useThumbnailToolbar(buttons, onClick) {
+  const app = useAppOrNull();
+  const owner = useTopLevelWindow();
+  const handler = useLatest(onClick);
+  const latest = useLatest(buttons);
+  const signature = signatureOf(buttons);
+
+  useEffect(() => {
+    if (typeof app?.thumbnailToolbar !== 'function') return;
+    // Read inside the effect: `useTopLevelWindow` answers through a getter,
+    // so the window a tree is in is whatever it is when the effect runs
+    // rather than what it was at render.
+    const wnd = owner?.current?.window;
+    if (!wnd?.id) return;
+    app.thumbnailToolbar(wnd.id, latest.current ?? []);
+
+    const fire = (event) => handler.current?.(event.id, event);
+    wnd.on?.('thumbbutton', fire);
+    return () => {
+      wnd.off?.('thumbbutton', fire);
+      // Hidden rather than removed, which is all the shell offers.
+      app.thumbnailToolbar(wnd.id, []);
+    };
+    // `signature` is the dependency; the buttons themselves are read through
+    // a ref, so a new array holding the same buttons does not re-send them.
+  }, [app, owner, signature, latest, handler]);
+}
+
+/**
+ * The Tasks category of this application's jump list — the menu on a right
+ * click of its taskbar button.
+ *
+ * `tasks` is `[{ title, arguments, description }]`. Each one **relaunches
+ * this executable** with the arguments given, which is what a jump-list task
+ * is: the shell starts the program, it does not call back into the running
+ * one. An app that wants the running instance to answer needs the single
+ * instance path, which is not built (docs/windows-integrations.md) — so until
+ * then a task is for something the app can do from a cold start.
+ *
+ * `null` deletes the category.
+ */
+export function useJumpList(tasks) {
+  const app = useAppOrNull();
+  const latest = useLatest(tasks);
+  // The tasks are plain data — a title, arguments, a description — so their
+  // own JSON is the dependency, and a caller rebuilding an equal array every
+  // render does not re-send it. Read through a ref for the same reason
+  // `useThumbnailToolbar` does: the value is what it is when the effect runs.
+  const signature = JSON.stringify(tasks ?? null);
+
+  useEffect(() => {
+    if (typeof app?.jumpList !== 'function') return;
+    app.jumpList(latest.current ?? []);
+    return () => app.jumpList([]);
+  }, [app, signature, latest]);
+}
+
+/**
+ * Note a document this app just opened, for the shell's Recent lists — the
+ * jump list's own Recent section, and Explorer's quick access.
+ *
+ * The same act as macOS's `noteNewRecentDocumentURL:`; it lives here rather
+ * than in a cross-platform hook because this is the only backend with one to
+ * call today. Where the file type is not associated with this application the
+ * shell may keep it and show it nowhere, which is its decision to make.
+ *
+ * `null` clears the list.
+ */
+export function noteRecentDocument(path, { app } = {}) {
+  const target = app ?? soleApp();
+  if (typeof target?.noteRecentDocument !== 'function') return false;
+  target.noteRecentDocument(path);
+  return true;
+}
+
+/** The hook form: notes `path` whenever it changes. */
+export function useRecentDocument(path) {
+  const app = useAppOrNull();
+  useEffect(() => {
+    if (typeof app?.noteRecentDocument !== 'function' || path == null) return;
+    app.noteRecentDocument(path);
+  }, [app, path]);
+}

package/src/transfer.js

@@ -70,6 +70,25 @@ export function decodeData(data, target) {
  * URIs that are actually local — a remote `file://host/...` has no local
  * path and must not pretend to.
  */
+/**
+ * A `file:` URL's pathname as a path this machine can open.
+ *
+ * On a POSIX path the two are the same string. A Windows one is not: the URL
+ * form of `C:\Users\a` is `file:///C:/Users/a`, whose pathname is
+ * `/C:/Users/a` — a leading slash that no Windows API accepts, and forward
+ * slashes that most of them tolerate and no user recognises. A drive letter
+ * after the slash is the tell, and it is unambiguous: no POSIX path begins
+ * `/C:`.
+ *
+ * Decided by the shape of the path rather than by `process.platform`, so a
+ * uri-list that arrived from another machine reads the same way on both.
+ */
+function pathOfFileUrl(pathname) {
+  const drive = /^\/([A-Za-z]:)(\/.*)?$/.exec(pathname);
+  if (!drive) return pathname;
+  return (drive[1] + (drive[2] ?? '\\')).replace(/\//g, '\\');
+}
+
 export function parseUriList(text) {
   const files = [];
   for (const line of String(text).split(/\r?\n/)) {
@@ -82,7 +101,7 @@ export function parseUriList(text) {
         url.protocol === 'file:' &&
         (url.hostname === '' || url.hostname === 'localhost')
       ) {
-        entry.path = decodeURIComponent(url.pathname);
+        entry.path = pathOfFileUrl(decodeURIComponent(url.pathname));
       }
     } catch {
       // not a parseable URI — keep the raw line, claim no path

package/src/trayhooks.js

@@ -73,7 +73,7 @@ import { StatusNotifierItem, allocateItemSlot } from './statusnotifier.js';
  * ```
  *
  * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
- * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
+ * `useLauncherMenu` take, an item's `onSelect` firing when picked. Without one,
  * `onClick` is called with the button and where the click was, in logical
  * screen pixels — with the item's rect, where the backend knows it. `null`
  * means no item. Every field follows its value while mounted; the item is

package/src/types/capabilities.d.ts

@@ -10,7 +10,13 @@ export type DesktopBackend =
   | 'osascript'
   | 'notify-send'
   | 'statusnotifier'
-  | 'launcherentry';
+  | 'launcherentry'
+  /** A Shell_NotifyIcon balloon. */
+  | 'win32'
+  /** The notify icon itself, as a tray. */
+  | 'shellnotifyicon'
+  /** `ITaskbarList3` and the jump list, as a launcher. */
+  | 'taskbar';
 
 /** The capabilities {@link desktopCapability} can be asked about. */
 export type DesktopCapabilityName = 'notifications' | 'tray' | 'launcher';
@@ -60,14 +66,37 @@ export interface TrayFeatures {
 
 export interface LauncherFeatures {
   badge: boolean;
-  /** A string badge. macOS only — the launcher protocol carries a count. */
+  /**
+   * A string badge rather than a count. False on the launcher protocol,
+   * which carries a number; the taskbar draws the text into its overlay
+   * icon, where about three glyphs fit before it becomes `99+`.
+   */
   badgeText: boolean;
   progress: boolean;
   urgent: boolean;
-  /** The Dock menu / quicklist. */
+  /**
+   * The Dock menu / quicklist: entries that **call back into this process**.
+   * False on the taskbar, whose menu is the jump list — see `tasks`.
+   */
   menu: boolean;
   /** The launcher needs an installed `.desktop` file to attach this to. */
   needsDesktopFile: boolean;
+  /**
+   * Static entries on the icon's menu that start a **new process** with
+   * arguments, rather than calling back into this one: the jump list's Tasks
+   * category. A different feature from `menu`, and `useJumpList` drives it.
+   */
+  tasks: boolean;
+  /**
+   * Buttons under the icon's hover preview, which `useThumbnailToolbar`
+   * drives. The taskbar's alone.
+   */
+  thumbnailToolbar: boolean;
+  /**
+   * The launcher keeps a Recent list this app can add to, through
+   * `useRecentDocument`.
+   */
+  recentDocuments: boolean;
 }
 
 export interface DesktopCapabilityResult<F = Record<string, boolean>> {

package/src/types/elements.d.ts

@@ -371,7 +371,29 @@ export interface WindowProps
   y?: number;
   /** Palette that `$token` style values resolve against, for this subtree. */
   theme?: Record<string, string | number>;
-  /** ICCCM `WM_CLASS`. */
+  /**
+   * The desktop identity of this window — which application it belongs to,
+   * and so which launcher icon it groups under and which `.desktop` entry a
+   * launcher matches it to.
+   *
+   * One name for what every desktop calls something else: ICCCM `WM_CLASS` on
+   * X11, `xdg_toplevel.set_app_id` on Wayland, the AppUserModelID on Windows.
+   * Normally the same string as `registerApplication({ appId })`, which is
+   * what a launcher matches against.
+   *
+   * A string is the modern single-id form. X11's instance/class pair is still
+   * accepted and passed through on that backend; every other backend takes
+   * the class, which is the part naming the application.
+   *
+   * Honoured on X11, on Windows — where it is the window's AppUserModelID,
+   * and where the jump list is attached to the same id — and, for windows
+   * opened after it is set, on Wayland, whose `app_id` is fixed when the
+   * surface is created. The cocoa backend accepts it and does nothing with
+   * it: macOS identity is the bundle's, decided at build time.
+   */
+  appId?: string | [string, string] | { instance: string; class?: string };
+  /** @deprecated Renamed to {@link WindowProps.appId} — `wmClass` is X11's
+   *  word for an identity every desktop has. Still accepted. */
   wmClass?: string | [string, string] | { instance: string; class?: string };
   /** EWMH `_NET_WM_WINDOW_TYPE`, or a list of fallbacks. */
   windowType?: WindowType | WindowType[];

package/src/types/events.d.ts

@@ -39,6 +39,22 @@ export interface SyntheticEvent<T = DrawnNode> {
    * what a node's `abs` is in (docs/scale.md). */
   x: number;
   y: number;
+  /**
+   * Where the pointer is on the **virtual screen**, in the same logical
+   * pixels `x`/`y` are in — what to reach for when placing something outside
+   * the window, such as a context menu at the pointer.
+   *
+   * Present exactly where the backend reported a position. That is most
+   * events, including keys on X11, whose KeyPress carries where the pointer
+   * was; it is undefined rather than `0` where a backend reported none, since
+   * zero is the screen's top-left corner and not an absence.
+   *
+   * `nativeEvent.rootx`/`rooty` is X11's name for the same point and is still
+   * there, in *device* pixels — the same split as `x` against
+   * `nativeEvent.x`.
+   */
+  screenX?: number;
+  screenY?: number;
   /** Coordinates relative to `target`'s box. */
   localX: number;
   localY: number;

package/src/types/launcher.d.ts

@@ -35,17 +35,23 @@ export declare function setBadge(
 export declare function useBadge(value: BadgeValue): void;
 
 /**
- * The menu behind a right-click on the app's icon in the Dock or launcher,
- * from the same item vocabulary `MenuBar` takes; an item's `onSelect` fires
- * when picked. Installed while mounted, replaced when `items` changes, taken
- * down on unmount.
+ * The menu behind a right-click on the app's **launcher icon** — the Dock on
+ * macOS, the launcher on Linux — from the same item vocabulary `MenuBar`
+ * takes; an item's `onSelect` fires when picked. Installed while mounted,
+ * replaced when `items` changes, taken down on unmount.
  *
  * `NSDockTile`'s menu on the cocoa backend; the launcher protocol's
  * **quicklist** on Linux — a `com.canonical.dbusmenu` tree, the same menu
  * protocol the tray and the global menu speak. Needs the identity
  * `registerApplication({ appId })` establishes and a `.desktop` file of that
  * name, like the badge.
+ *
+ * Reads `useDesktopCapability('launcher').features.menu`.
  */
+export declare function useLauncherMenu(items: MenuItem[] | null): void;
+
+/** @deprecated Renamed to {@link useLauncherMenu} — "Dock" is one desktop's
+ *  word for the icon every desktop has. Still exported and still works. */
 export declare function useDockMenu(items: MenuItem[] | null): void;
 
 /**
@@ -80,9 +86,17 @@ export declare function setUrgent(
 ): Promise<boolean>;
 
 /**
- * {@link useDockMenu}'s imperative twin, for code with no component. `null`
- * takes the menu down.
+ * {@link useLauncherMenu}'s imperative twin, for code with no component.
+ * `null` takes the menu down.
  */
+export declare function setLauncherMenu(
+  items: MenuItem[] | null,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/** @deprecated Renamed to {@link setLauncherMenu} — "quicklist" is the Unity
+ *  launcher's word for the menu macOS calls the Dock menu, and this drove
+ *  both all along. Still exported and still works. */
 export declare function setQuicklist(
   items: MenuItem[] | null,
   options?: SetBadgeOptions,

package/src/types/taskbar.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The Windows taskbar's own surfaces. See docs/windows-integrations.md.
+ *
+ * Three things the taskbar has that no other desktop does, so none of them is
+ * a rung on an existing ladder. They are reported as features of the
+ * **launcher** — `useDesktopCapability('launcher').features.thumbnailToolbar`
+ * and its two siblings — because all of them hang off the one icon the
+ * desktop shows for this app, beside the badge and the progress bar. The
+ * hooks do nothing where the backend has none, so they are safe to call
+ * unconditionally and an app needs no platform check.
+ */
+
+/**
+ * An icon for a toolbar button: raw RGBA with its size, an ntk `Image`, or a
+ * path to a file. The shell tints it for the theme, so the shape is the whole
+ * of it and a white glyph on transparent is the usual choice.
+ */
+export type TaskbarIcon =
+  | string
+  | { data: Uint8Array; width: number; height: number }
+  | { width: number; height: number };
+
+export interface ThumbnailToolbarButton {
+  /** What a click is reported as. Not the shell's index. */
+  id: string;
+  /** The hover tooltip; `label` is accepted as a synonym. */
+  tooltip?: string;
+  label?: string;
+  icon?: TaskbarIcon | null;
+  /** Default true. A disabled button is shown greyed rather than hidden. */
+  enabled?: boolean;
+  /** Close the hover preview when this one is clicked. */
+  dismissOnClick?: boolean;
+}
+
+/**
+ * Up to seven buttons under this window's taskbar hover preview — where a
+ * media player puts play and skip. `null` hides them, which is as far down as
+ * the shell allows: a window that has had a toolbar keeps one.
+ *
+ * The eighth button and beyond are dropped rather than refused, because the
+ * shell refuses the whole call for an eighth.
+ */
+export declare function useThumbnailToolbar(
+  buttons: readonly ThumbnailToolbarButton[] | null | undefined,
+  onClick?: (id: string, event: unknown) => void,
+): void;
+
+export interface JumpListTask {
+  title: string;
+  /** Passed to a **new** process; nothing calls back into this one. */
+  arguments?: string;
+  description?: string;
+}
+
+/**
+ * The Tasks category of this application's jump list — the menu on a right
+ * click of its taskbar button. `null` deletes the category.
+ *
+ * Each entry **relaunches this executable** with the arguments given, which
+ * is what a jump-list task is. That is why this is not `useLauncherMenu`, whose
+ * items carry a callback: reported as `features.tasks` rather than
+ * `features.menu`, so an app cannot mistake one for the other.
+ */
+export declare function useJumpList(
+  tasks: readonly JumpListTask[] | null | undefined,
+): void;
+
+/** Notes `path` for the shell's Recent lists whenever it changes. */
+export declare function useRecentDocument(path?: string | null): void;
+
+/**
+ * The imperative form of {@link useRecentDocument}. Returns false where the
+ * backend has no Recent list, rather than throwing.
+ */
+export declare function noteRecentDocument(
+  path: string | null,
+  options?: { app?: unknown },
+): boolean;

package/src/wayland/context2d.js

@@ -206,7 +206,7 @@ function scaleOf(m) {
 
 /**
  * The Render ops a `drawGlyphs` call can name, numbered as XRender numbers
- * them — the same table the Cocoa backend answers (`src/cocoa/context2d.js`),
+ * them — the same table the native backends answer (`src/backend/context2d.js`),
  * so `ctx.Render.PictOp.Over` reads the same on every backend. The op is
  * ignored here: text composites Over, and for the opaque inks text uses Src
  * and Over agree.