react-x11 2.16.1 → 2.17.1

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.