react-x11 2.15.2 → 2.16.0

package/src/trayhooks.js

@@ -1,25 +1,72 @@
 // `useTray()` — an icon in the system tray for as long as a component is
 // mounted, on the backends that have one.
 //
-// Today that is the cocoa backend's menu-bar extra (`NSStatusItem`,
-// src/cocoa/statusitem.js). The freedesktop counterpart, StatusNotifierItem
-// over D-Bus, is react-x11#353's open question; until it lands the hook is
-// inert on X11 and says so — `available: false`, and a one-time development
-// note — rather than pretending, so an app can keep the feature behind the
-// answer. The inert-props policy of docs/macos.md, for a hook.
+// Two rungs, found by capability and never by naming a platform:
+//
+//   1. **the app's own status bar** — the cocoa backend's menu-bar extra
+//      (`NSStatusItem`, src/cocoa/statusitem.js), found by the app carrying
+//      `createStatusItem`.
+//   2. **`org.kde.StatusNotifierItem`** over the session bus
+//      (`statusnotifier.js`) — the freedesktop tray, and the same protocol
+//      under X11, XWayland and Wayland. Used when a **live**
+//      `org.kde.StatusNotifierWatcher` is hosting one.
+//
+// Where neither answers there is no tray, and `available` is `false` — a
+// stock GNOME session with no AppIndicator extension is the common case, and
+// it is a configuration rather than a fault. An app reads `available` and
+// keeps its tray feature behind it; nothing is logged, because "this desktop
+// has no tray" is not news.
+//
+// ## What the hook returns, and why it is not just a boolean
+//
+// `{ available, backend, features, error }` — the same shape
+// `useDesktopCapability('tray')` resolves to, and built from the same probe so the
+// two can never disagree. The difference is which question they answer:
+//
+//   - **this hook measures.** `available` is whether *this item* was taken by
+//     a host. It tried; it knows.
+//   - **`useDesktopCapability` predicts.** It answers "would a tray icon be taken if
+//     one were asked for", which is what a settings screen needs — a "Show
+//     tray icon" checkbox must render correctly *without* putting an icon in
+//     the tray to find out.
+//
+// Prefer this one wherever the feature is actually mounted. `features` is the
+// portable vocabulary from `capabilities.js` — `features.clickModifiers` is
+// false on the freedesktop rung, because the protocol carries no modifier
+// state, and an app that dims a shift-click affordance reads it here rather
+// than testing the platform.
+//
+// `error` is the fourth field because "no tray on this desktop" and "there is
+// a tray and it refused me" are different facts with different fixes, and
+// collapsing them into `available: false` loses the one an app could act on.
+//
+// ## `available` settles, it does not start true
+//
+// The cocoa rung can be answered synchronously — the method is either on the
+// app object or it is not. The freedesktop one cannot: it takes a bus
+// connection and a `NameHasOwner` round trip. So `available` is **render
+// state that settles**, false on the first frame and true a tick later if a
+// watcher is there, and it follows the watcher for the life of the item —
+// a panel that exits takes the icon with it and flips this back to false.
+//
+// That is the shape every capability in this family should have, and
+// docs/desktop.md says so: a synchronous "can I?" that is honest on the first
+// frame is not available for anything that has to ask the desktop.
 
 import { useEffect, useRef, useState } from 'react';
+import { decodeImage } from 'ntk';
 
 import { useAppOrNull } from './appcontext.js';
-
-let warnedInert = false;
+import { currentRegistration } from './application.js';
+import { NO_CAPABILITY, desktopCapability } from './capabilities.js';
+import { StatusNotifierItem, allocateItemSlot } from './statusnotifier.js';
 
 /**
  * An icon in the system tray while this component is mounted.
  *
  * ```jsx
  * const { available } = useTray({
- *   icon: 'bell.badge',              // an SF Symbol name, or PNG bytes
+ *   icon: 'bell.badge',              // a themed icon name (an SF Symbol on macOS), or PNG bytes
  *   tooltip: 'Notifications',
  *   menu: [{ label: 'Open', onSelect: open }, { label: 'Quit', onSelect: quit }],
  * });
@@ -27,37 +74,55 @@ let warnedInert = false;
  *
  * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
  * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
- * `onClick` is called with the button and the item's screen rect, which is
- * where to anchor a popup of your own. `null` means no item. Every field
- * follows its value while mounted; the item is removed on unmount.
+ * `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
+ * removed on unmount.
  *
- * `available` is whether this backend has a tray at all: false on X11
- * today (#353), and the honest answer to branch on.
+ * `available` is whether this backend has a tray at all, and it **settles**:
+ * false on the first frame, true once a tray has been found. Branch on it for
+ * a "show tray icon" setting; do not branch on it to decide whether to call
+ * the hook, which would break the rules of hooks the moment it changed.
  */
 export function useTray(options) {
   const app = useAppOrNull();
-  const available = typeof app?.createStatusItem === 'function';
+  const native = typeof app?.createStatusItem === 'function';
   const itemRef = useRef(null);
   const [rect] = useState(null);
+  const [remote, setRemote] = useState(false);
+  // whether the freedesktop registration has answered, either way
+  const [answered, setAnswered] = useState(false);
+  const [error, setError] = useState(null);
+  // The feature vocabulary for whichever rung answered. Probed once per
+  // backend rather than per render — it describes the mechanism, not the
+  // item — and for *both* rungs: the cocoa one is synchronous about whether
+  // it has a tray, but not about what that tray can do, and an app reading
+  // `features.clickModifiers` to dim a shift-click affordance would
+  // otherwise be told `undefined` on the one backend that has modifiers.
+  const [caps, setCaps] = useState(NO_CAPABILITY);
+
+  useEffect(() => {
+    if (!options) return undefined;
+    let cancelled = false;
+    // `app` explicitly rather than letting the probe find the sole one: a
+    // process with several connections has several trays, and this hook
+    // belongs to one of them.
+    void desktopCapability('tray', { app }).then((c) => {
+      if (!cancelled) setCaps(c);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, native, options == null]);
 
   // the options a click or a pick reads are the current render's, not the
   // ones the item was created with three minutes ago
   const live = useRef(options);
   live.current = options;
 
+  // ------------------------------------------------------- rung 1: the app's
   useEffect(() => {
-    if (!available) {
-      if (process.env.NODE_ENV !== 'production' && !warnedInert && app) {
-        warnedInert = true;
-        console.warn(
-          'react-x11: useTray() is inert on this backend — the freedesktop ' +
-            'tray (StatusNotifierItem) is not implemented yet (#353). Read ' +
-            '`available` to keep the feature behind the answer.',
-        );
-      }
-      return undefined;
-    }
-    if (!options) return undefined;
+    if (!native || !options) return undefined;
     const item = app.createStatusItem({
       ...options,
       onClick: (ev) => live.current?.onClick?.(ev),
@@ -70,7 +135,7 @@ export function useTray(options) {
     // Recreated only when the item comes or goes: the fields patch in
     // place below, and an `options` object rebuilt every render must not
     // rebuild the item every render.
-  }, [app, available, options == null]);
+  }, [app, native, options == null]);
 
   useEffect(() => {
     const item = itemRef.current;
@@ -86,5 +151,104 @@ export function useTray(options) {
     options?.menu,
   ]);
 
-  return { available, rect };
+  // ------------------------------------------- rung 2: the freedesktop tray
+  const sniRef = useRef(null);
+  const previous = useRef(options ?? {});
+  // One slot for the life of this hook, **not** per item object. Passing
+  // `null` and then options again is the same tray icon going away and coming
+  // back; on a fresh path the host has no way to know that and draws a second
+  // one beside the first. See `StatusNotifierItem.announcePassive`.
+  const slotRef = useRef(null);
+  slotRef.current ??= allocateItemSlot();
+
+  useEffect(() => {
+    if (native || !options) return undefined;
+    let cancelled = false;
+    // The id hosts key their hidden-icons setting on. The app's registered id
+    // when it has one, so the choice survives a restart.
+    const appId = currentRegistration()?.appId ?? 'react-x11';
+    const item = new StatusNotifierItem({
+      getOptions: () => live.current,
+      // The display a click's position is read against: the host sends it in
+      // a unit of its own choosing — see "The position has no unit" in
+      // statusnotifier.js.
+      app,
+      appId,
+      slot: slotRef.current,
+      decodeIcon: decodeIconBytes,
+      // A host that answered the bus and then refused the registration is a
+      // fact worth reporting; a desktop with no tray at all is not, and does
+      // not come through here.
+      onError: (err) => {
+        if (!cancelled)
+          setError(err instanceof Error ? err : new Error(String(err)));
+      },
+    });
+    sniRef.current = item;
+    previous.current = { ...live.current };
+    void item.start().then((ok) => {
+      if (cancelled) return;
+      setRemote(ok);
+      setAnswered(true);
+    });
+    return () => {
+      cancelled = true;
+      sniRef.current = null;
+      setRemote(false);
+      setAnswered(false);
+      setError(null);
+      void item.stop();
+    };
+  }, [app, native, options == null]);
+
+  // The item reads its fields through `getOptions`, so a render only has to
+  // say *which* of them moved — see `StatusNotifierItem.update`.
+  useEffect(() => {
+    const item = sniRef.current;
+    if (!item) return;
+    item.update(previous.current);
+    previous.current = { ...live.current };
+  }, [
+    options?.icon,
+    options?.overlayIcon,
+    options?.attentionIcon,
+    options?.title,
+    options?.tooltip,
+    options?.visible,
+    options?.attention,
+    options?.menu,
+  ]);
+
+  // The cocoa rung is synchronous and always itself; the freedesktop one
+  // reports whatever the probe found. `features` is empty until one settles,
+  // which is the same "render the fallback first" order `available` has.
+  const backend = native ? 'cocoa' : remote ? caps.backend : null;
+  return {
+    available: native || remote,
+    // Whether `available` is an answer yet: at once on the Cocoa rung and for
+    // no item at all, and on the freedesktop one once the host has taken or
+    // refused the registration — so an app whose whole UI is its tray can
+    // render nothing until then, rather than a fallback window that flashes
+    // up and away on every start.
+    settled: native || !options || answered,
+    backend,
+    features: native || remote ? caps.features : NO_CAPABILITY.features,
+    error,
+    rect,
+  };
+}
+
+/**
+ * PNG/JPEG bytes → raw RGBA, through ntk's decoder.
+ *
+ * Defensive: a corrupt or unsupported image should cost the tray its *icon*,
+ * not its tray. The pixmap ends up empty and the item still registers with
+ * its name, tooltip and menu intact.
+ */
+function decodeIconBytes(bytes) {
+  try {
+    return decodeImage(bytes);
+  } catch {
+    return null;
+  }
 }

package/src/types/capabilities.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Feature discovery for the things an app does outside its own windows.
+ * See docs/desktop.md "Feature discovery".
+ */
+
+/** Which mechanism answered. Named after the mechanism, never the platform. */
+export type DesktopBackend =
+  | 'dbus'
+  | 'cocoa'
+  | 'osascript'
+  | 'notify-send'
+  | 'statusnotifier'
+  | 'launcherentry';
+
+/** The capabilities {@link desktopCapability} can be asked about. */
+export type DesktopCapabilityName = 'notifications' | 'tray' | 'launcher';
+
+/**
+ * What a notification can carry here.
+ *
+ * `actions`/`events` are the pair that decide whether a notification is a
+ * conversation or a sign: false on the shell-out rungs and on a freedesktop
+ * daemon that does not advertise `actions`, where buttons silently never
+ * appear and nothing is ever reported back.
+ */
+export interface NotificationFeatures {
+  actions: boolean;
+  /** `onAction`/`onClose` will fire. Tracks `actions` on every rung. */
+  events: boolean;
+  /** `update()` replaces the banner in place rather than posting a new one. */
+  update: boolean;
+  close: boolean;
+  body: boolean;
+  bodyMarkup: boolean;
+  bodyImage: boolean;
+  icon: boolean;
+  sound: boolean;
+  /** The banner survives in a tray or centre rather than expiring unseen. */
+  persistence: boolean;
+  urgency: boolean;
+}
+
+export interface TrayFeatures {
+  menu: boolean;
+  /** An icon named in the desktop's theme (an SF Symbol on the cocoa rung). */
+  iconName: boolean;
+  iconBytes: boolean;
+  attention: boolean;
+  overlay: boolean;
+  tooltip: boolean;
+  title: boolean;
+  click: boolean;
+  clickPosition: boolean;
+  /** The item's screen rect. False on the freedesktop rung, which has none. */
+  clickRect: boolean;
+  /** Modifier state on a click. False on the freedesktop rung. */
+  clickModifiers: boolean;
+  scroll: boolean;
+}
+
+export interface LauncherFeatures {
+  badge: boolean;
+  /** A string badge. macOS only — the launcher protocol carries a count. */
+  badgeText: boolean;
+  progress: boolean;
+  urgent: boolean;
+  /** The Dock menu / quicklist. */
+  menu: boolean;
+  /** The launcher needs an installed `.desktop` file to attach this to. */
+  needsDesktopFile: boolean;
+}
+
+export interface DesktopCapabilityResult<F = Record<string, boolean>> {
+  /** Whether there is any mechanism at all. Branch on `features` for detail. */
+  available: boolean;
+  backend: DesktopBackend | null;
+  /** Empty when `available` is false. */
+  features: Partial<F>;
+  /**
+   * Why not, when the `false` has a cause worth naming.
+   *
+   * `'no-app-id'` — the launcher needs `registerApplication({ appId })`, and
+   * this one is a mistake in the source.
+   * `'not-primary'` — it was called, and another copy of the app owns the
+   * identity. Correct single-instance behaviour, not a bug: the first copy
+   * owns the badge and the quicklist.
+   */
+  reason?: 'no-app-id' | 'not-primary';
+}
+
+export type DesktopCapabilityFor<N extends DesktopCapabilityName> =
+  N extends 'notifications'
+    ? DesktopCapabilityResult<NotificationFeatures>
+    : N extends 'tray'
+      ? DesktopCapabilityResult<TrayFeatures>
+      : DesktopCapabilityResult<LauncherFeatures>;
+
+export declare const CAPABILITIES: readonly DesktopCapabilityName[];
+
+/** The "nothing here" answer: available false, no backend, no features. */
+export declare const NO_CAPABILITY: DesktopCapabilityResult;
+
+/**
+ * What this desktop can do for one feature.
+ *
+ * Never cached — a panel restarting or an extension being enabled changes the
+ * answer, and a cached `false` would outlive the fix. Throws only for an
+ * unknown name, which is a mistake in the source.
+ */
+export declare function desktopCapability<N extends DesktopCapabilityName>(
+  name: N,
+  options?: { app?: unknown },
+): Promise<DesktopCapabilityFor<N>>;
+
+/**
+ * {@link desktopCapability} as render state: {@link NO_CAPABILITY} on the
+ * first frame, settling a tick later, and re-probed whenever a name appears
+ * or vanishes on the session bus.
+ *
+ * Use it for the *pre-flight* question — a settings screen that must render a
+ * "Show tray icon" checkbox without putting an icon in the tray. Where the
+ * feature is actually mounted, the feature hook's own status is a measurement
+ * rather than a prediction and should be preferred.
+ */
+export declare function useDesktopCapability<N extends DesktopCapabilityName>(
+  name: N,
+): DesktopCapabilityState<N>;
+
+/** {@link useDesktopCapability}'s answer, and whether it is one yet. */
+export type DesktopCapabilityState<N extends DesktopCapabilityName> =
+  DesktopCapabilityFor<N> & {
+    /**
+     * False until the first probe answers, and true from then on, re-probes
+     * included — so an app can hold its fallback back rather than flash it.
+     * True on the first frame where nothing had to be asked: the tray and
+     * the Dock tile on macOS.
+     */
+    settled: boolean;
+  };

package/src/types/components.d.ts

@@ -418,6 +418,17 @@ export interface SliderProps
   disabled?: boolean;
   height?: number;
   style?: StyleProp;
+  /**
+   * The thumb's style, over its default: a 16px circle on `surface` with a
+   * ring. Its `width` and `height`, as numbers, are what the drag's travel
+   * and the control's height are measured with.
+   */
+  thumbStyle?: StyleProp;
+  /** The track's style, over `height` and `track`. Its `height` is the
+   *  fill's too. */
+  trackStyle?: StyleProp;
+  /** The filled part of the track, up to the value, over `accent`. */
+  fillStyle?: StyleProp;
 }
 export const Slider: ComponentType<SliderProps>;
 
@@ -761,6 +772,28 @@ export function anchorRect(
   options?: AnchorOptions,
 ): AnchorRect | null;
 
+/**
+ * The same placement against a rect **on the screen** rather than a node —
+ * the item a tray click reports, a point where the pointer was — in logical
+ * screen pixels on both sides. With no node to ask, `scale` is the
+ * display's (default 1) and `direction` decides `'start'` and `'end'`; the
+ * popup is kept on the monitor the rect is on. `null` for a rect with no
+ * `x`/`y`.
+ */
+export function anchorScreenRect(
+  app: unknown,
+  rect: ScreenAnchorRect,
+  options?: Omit<AnchorOptions, 'at' | 'alignTo'> & { scale?: number },
+): AnchorRect | null;
+
+/** A rect on the screen, in logical pixels; `{x, y}` alone is a point. */
+export interface ScreenAnchorRect {
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+}
+
 /** Centre a popup of this size on the node's screen. */
 export function centerRect(
   node: DrawnNode,

package/src/types/elements.d.ts

@@ -5,14 +5,14 @@
  */
 
 import type { Ref, RefObject, ReactNode, Key } from 'react';
-import type { Color, Cursor, StyleProp } from './style.js';
+import type { Color, Cursor, FontWeight, StyleProp } from './style.js';
 import type {
   DrawnNode,
   NtkWindow,
   ScrollableNode,
   TextInputNode,
 } from './nodes.js';
-import type { AnchorOptions } from './components.js';
+import type { AnchorOptions, ScreenAnchorRect } from './components.js';
 import type {
   ChangeEvent,
   SelectionChangeEvent,
@@ -580,6 +580,16 @@ export interface PopupProps extends WindowProps {
    * this client at all. Needs ntk >= 3.7.0.
    */
   grab?: boolean;
+  /**
+   * Take the keyboard while the popup is up: its keys come to it whatever
+   * holds the focus, which is what a popover a tray click opened needs — a
+   * menu-bar app has no window of its own for keys to arrive at. A keyboard
+   * grab on X, taken and dropped with the map like `grab`. On macOS a window
+   * AppKit can make key, shown activating the app, as `NSPopover`'s own
+   * window is — decided when the popup is created, so it does not change on
+   * a mounted one. A grabbing popup on Wayland has the keyboard already.
+   */
+  grabKeyboard?: boolean;
   /**
    * `true` (the default) keeps the window manager out entirely, which is
    * what makes a menu a menu — no frame, no repositioning, no taskbar entry.
@@ -597,7 +607,9 @@ export interface PopupProps extends WindowProps {
   /**
    * Hang this popup off a node — `anchorRect`'s options plus the node to
    * measure, and the popup works out its own position from them, ignoring
-   * `x`/`y`.
+   * `x`/`y`. Or off a rect on the screen with no node behind it, `rect`
+   * instead of `to`: the item a tray click reports, placed against with the
+   * same flip and clamp.
    *
    * What this does that computing a rect in the application cannot: a popup
    * with an `'auto'` size only knows how big it is *inside* `realize()`,
@@ -622,12 +634,26 @@ export interface PopupProps extends WindowProps {
  *  that renders them) or the node itself. */
 export type AnchorTarget = DrawnNode | RefObject<DrawnNode | null> | null;
 
-export interface PopupAnchor extends Omit<AnchorOptions, 'alignTo'> {
+/** Where a popup hangs: a node, or a rect on the screen. */
+export type PopupAnchor = NodeAnchor | ScreenAnchor;
+
+export interface NodeAnchor extends Omit<AnchorOptions, 'alignTo'> {
   /** The node this popup hangs off. */
   to: AnchorTarget;
   /** Takes the alignment axis from another node — see
    *  {@link AnchorOptions.alignTo}. */
   alignTo?: AnchorTarget;
+  rect?: never;
+}
+
+export interface ScreenAnchor extends Omit<AnchorOptions, 'alignTo' | 'at'> {
+  /**
+   * A rect on the screen, in logical pixels — what `useTray`'s `onClick`
+   * reports where the platform knows the item's frame. `{x, y}` alone is a
+   * point. Nothing moves it but a new one, and it is never out of view.
+   */
+  rect: ScreenAnchorRect;
+  to?: never;
 }
 
 // --- drawn elements --------------------------------------------------------
@@ -758,10 +784,35 @@ export interface FileUrl {
 
 /**
  * What `src` accepts: a file path or file URL (PNG/JPEG, decoded in JS),
- * encoded PNG/JPEG bytes, raw RGBA pixels, or an ntk `Image`/`Surface`.
+ * encoded PNG/JPEG bytes, raw RGBA pixels, an ntk `Image`/`Surface`, or a
+ * symbol by name.
  */
 export type ImageSource =
-  string | FileUrl | Uint8Array | RawImageSource | DirectImageSource;
+  | string
+  | FileUrl
+  | Uint8Array
+  | RawImageSource
+  | DirectImageSource
+  | SymbolImageSource;
+
+/**
+ * The platform's own icon by name, drawn in the text colour: an SF Symbol on
+ * macOS (`'speaker.wave.3.fill'`), and elsewhere an icon from the user's
+ * freedesktop icon theme (`'audio-volume-high'`), its `-symbolic` variant
+ * preferred. Sized like the text around it — the size its `fontSize` calls
+ * for — unless the element is styled a size of its own. A name this desktop
+ * does not have takes no room and draws nothing.
+ */
+export interface SymbolImageSource {
+  symbol: string;
+  /** Default: the weight of the text around it. SF Symbols only. */
+  weight?: FontWeight;
+  /** Relative to the text size, default `'medium'`. SF Symbols only. */
+  scale?: 'small' | 'medium' | 'large';
+  /** How much of a variable symbol shows, 0 to 1 — the waves of
+   *  `speaker.wave.3.fill` at a volume. SF Symbols on macOS 13 and later. */
+  variableValue?: number;
+}
 
 /**
  * An existing server-side Picture, named by X id. The size is stated by the

package/src/types/launcher.d.ts

@@ -35,9 +35,55 @@ export declare function setBadge(
 export declare function useBadge(value: BadgeValue): void;
 
 /**
- * The menu behind a right-click on the Dock icon, 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. Inert off the cocoa backend.
+ * 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.
+ *
+ * `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.
  */
 export declare function useDockMenu(items: MenuItem[] | null): void;
+
+/**
+ * A progress bar across the app's icon, `0`…`1`. `null` clears it; values
+ * outside the range are clamped rather than refused.
+ *
+ * The launcher protocol's `progress`. **Linux launchers only** — `NSDockTile`
+ * has no progress bar, so this is inert on the cocoa backend and
+ * `useDesktopCapability('launcher').features.progress` is the honest answer.
+ */
+export declare function setProgress(
+  value: number | null | false | undefined,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/** {@link setProgress} while mounted; cleared on unmount. */
+export declare function useProgress(
+  value: number | null | false | undefined,
+): void;
+
+/**
+ * Ask the launcher for the user's attention, or stop asking.
+ *
+ * Distinct from `<window states={['demands_attention']}>`, which is the
+ * *window's* urgency hint: this marks the app's icon in the launcher whether
+ * or not any window is open. Inert on the cocoa backend, where the window
+ * state is the mechanism.
+ */
+export declare function setUrgent(
+  urgent: boolean,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/**
+ * {@link useDockMenu}'s imperative twin, for code with no component. `null`
+ * takes the menu down.
+ */
+export declare function setQuicklist(
+  items: MenuItem[] | null,
+  options?: SetBadgeOptions,
+): Promise<boolean>;