react-x11 2.6.1 → 2.8.0

package/src/types/notifications.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Desktop notifications — a banner outside the app's own windows. See
+ * docs/notifications.md.
+ */
+
+import type { NtkApp } from './nodes.js';
+
+/** Which rung of the ladder answered — or would. */
+export type NotificationBackend =
+  'cocoa' | 'dbus' | 'osascript' | 'notify-send';
+
+export type NotificationUrgency = 'low' | 'normal' | 'critical';
+
+/** Why a banner went away: the freedesktop reasons. */
+export type NotificationCloseReason =
+  'expired' | 'dismissed' | 'closed' | 'unknown';
+
+export interface NotificationAction {
+  /** Reported to `onAction`. `'default'` is the click on the banner itself
+   * and not a name for an action of your own. */
+  key: string;
+  label?: string;
+}
+
+export interface NotificationOptions {
+  /** The one line every daemon shows. Required. */
+  summary: string;
+  body?: string;
+  /** macOS only; folded into the body elsewhere. */
+  subtitle?: string;
+  /** An icon-theme name, or an absolute path to an image. Rungs that cannot
+   * show one ignore it. */
+  icon?: string;
+  urgency?: NotificationUrgency;
+  /** Milliseconds until it expires on its own; `0` never; absent is the
+   * daemon's default. */
+  timeout?: number;
+  /** Buttons on the banner. Dropped, with a development warning, on a daemon
+   * without the `actions` capability; never sent on the shell-out rungs. */
+  actions?: NotificationAction[];
+  onAction?: (key: string) => void;
+  onClose?: (reason: NotificationCloseReason) => void;
+  /** `true` posts without a sound on macOS. */
+  silent?: boolean;
+  /** A freedesktop category hint (`'transfer.complete'`, …). */
+  category?: string;
+  /** Keep the banner after an action is invoked (freedesktop `resident`). */
+  resident?: boolean;
+  /** The name a daemon shows for the sender; the process title otherwise. */
+  appName?: string;
+  /** The desktop-entry id the banner is attributed to; the registration's
+   * `appId` otherwise. */
+  appId?: string;
+  /** Opaque data round-tripped on the macOS rung. */
+  userInfo?: Record<string, unknown>;
+  /** Force a rung, for kiosks and for tests. */
+  backend?: NotificationBackend;
+  /** The connection whose centre to post through, when there are several. */
+  app?: NtkApp;
+}
+
+export interface NotificationHandle {
+  /** The daemon's id, the centre's identifier, or `null` where the rung has
+   * none (a shell-out). */
+  readonly id: number | string | null;
+  readonly backend: NotificationBackend;
+  /** Replace the banner in place. On a shell-out rung without an id this
+   * posts a fresh one. */
+  update(patch: Partial<NotificationOptions>): Promise<NotificationHandle>;
+  /** Take it down. Nothing on a shell-out rung. */
+  close(): Promise<void>;
+}
+
+/**
+ * Nothing on this machine can show a notification. A **typed** rejection,
+ * the `NoFileDialogError` rule; `useNotifier().available` is that branch as
+ * render state. A centre that exists and *refused* (the user turned the
+ * app's notifications off) rejects with the platform's own error instead —
+ * a refusal is not fallen through.
+ */
+export declare class NoNotificationServiceError extends Error {
+  readonly name: 'NoNotificationServiceError';
+  readonly cause?: unknown;
+}
+
+/** Show a notification on the best rung this machine has. */
+export declare function notify(
+  options: NotificationOptions,
+): Promise<NotificationHandle>;
+
+/** Which rung this machine lands on, without posting anything. `null`
+ * means {@link notify} would reject. */
+export declare function notificationBackend(
+  options?: Pick<NotificationOptions, 'app' | 'backend'>,
+): Promise<NotificationBackend | null>;
+
+export interface Notifier {
+  notify(
+    options: Omit<NotificationOptions, 'app'>,
+  ): Promise<NotificationHandle>;
+  /** Settled once the ladder has been probed; false where `notify` would
+   * reject. */
+  available: boolean;
+  backend: NotificationBackend | null;
+}
+
+/** Notifications for a component: `notify` bound to the tree's connection,
+ * `available` and `backend` as render state. */
+export declare function useNotifier(
+  defaults?: Omit<NotificationOptions, 'app' | 'summary'> & {
+    summary?: string;
+  },
+): Notifier;

package/src/types/permissions.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Permissions: may this app use the camera, the microphone, the screen, the
+ * accessibility APIs — and how does it ask? See docs/permissions.md.
+ */
+
+import type { NtkApp } from './nodes.js';
+
+export type PermissionKind =
+  | 'camera'
+  | 'microphone'
+  | 'screen-recording'
+  | 'accessibility'
+  | 'input-monitoring'
+  | 'automation'
+  | 'location';
+
+/** The panes `openPrivacySettings` reaches: every kind, plus the two with no
+ * API because reading the folder is the prompt. */
+export type PrivacyPane =
+  PermissionKind | 'files-and-folders' | 'full-disk-access';
+
+/**
+ * `'granted'`, `'denied'` and `'restricted'` (MDM or parental controls — the
+ * user cannot grant it) are the platform's; `'prompt'` is not decided yet, a
+ * request would ask; `'unknown'` is "nothing here can say", a fact about the
+ * machine rather than the permission.
+ */
+export type PermissionStatus =
+  'granted' | 'denied' | 'restricted' | 'prompt' | 'unknown';
+
+export interface PermissionOptions {
+  /** The connection whose backend to ask, when there are several. */
+  app?: NtkApp;
+  /** `automation` only: the bundle id of the app to send Apple Events to.
+   * Only a running target has an answer. */
+  target?: string;
+}
+
+/**
+ * Nothing on this machine can ask. A **typed** rejection, so a caller keeps
+ * the feature behind it rather than crashing; `usePermission().available`
+ * is that branch as render state, and `permissionStatus()` foretells it
+ * with `'unknown'`.
+ */
+export declare class NoPermissionServiceError extends Error {
+  readonly name: 'NoPermissionServiceError';
+  readonly cause?: unknown;
+}
+
+/** Which rung answers here: `'cocoa'`, or `null` where a status would be
+ * `'unknown'` and a request would reject. Synchronous. */
+export declare function permissionBackend(
+  options?: Pick<PermissionOptions, 'app'>,
+): 'cocoa' | null;
+
+/** Whether this app may use `kind`, without prompting. Never rejects for
+ * anything about the machine. */
+export declare function permissionStatus(
+  kind: PermissionKind,
+  options?: PermissionOptions,
+): Promise<PermissionStatus>;
+
+/**
+ * Ask for `kind` — the system's prompt where there is one — and resolve
+ * with the status once the user has answered. Rejects with
+ * {@link NoPermissionServiceError} where nothing can ask.
+ */
+export declare function requestPermission(
+  kind: PermissionKind,
+  options?: PermissionOptions,
+): Promise<PermissionStatus>;
+
+/**
+ * System Settings › Privacy & Security › `pane`, or the Privacy pane with
+ * none. Through the bridge where there is one, by `open` on any Mac
+ * otherwise. Resolves to whether anything opened — `false` off macOS.
+ */
+export declare function openPrivacySettings(
+  pane?: PrivacyPane | null,
+  options?: Pick<PermissionOptions, 'app'>,
+): Promise<boolean>;
+
+export interface Permission {
+  /** `'unknown'` until read; re-read after each `request()`. */
+  status: PermissionStatus;
+  /** Whether this backend has an authorization API at all. */
+  available: boolean;
+  /** Ask, and update `status`. A second call while one is in flight
+   * returns the same promise. */
+  request(): Promise<PermissionStatus>;
+  /** Re-read the status on your own cue. */
+  refresh(): Promise<PermissionStatus>;
+  openSettings(): Promise<boolean>;
+}
+
+/** A permission for a component: the status as render state. */
+export declare function usePermission(
+  kind: PermissionKind,
+  options?: Pick<PermissionOptions, 'target'>,
+): Permission;

package/src/types/style.d.ts

@@ -310,6 +310,16 @@ export interface StyleProperties extends LayoutStyle, PaintStyle, TextStyle {
    * a 16px control can have a 24px target without the layout moving.
    */
   hitSlop?: HitSlop;
+  /**
+   * Declares this node a container for the `'@container …'` blocks below it
+   * — CSS's `container-type` and `container-name` in one property. `true`
+   * answers the unnamed queries; a name answers those and the ones that say
+   * it, so `'@container sidebar width >= 400'` reaches past any nearer
+   * container to the one called `sidebar`. `false` takes back a declaration
+   * from earlier in a style array. Changes nothing about this node itself.
+   * See docs/styling.md#container-queries.
+   */
+  container?: boolean | string;
 }
 
 /**
@@ -361,6 +371,21 @@ export type Animation = { [K in keyof StyleProperties]?: AnimationSpec };
  */
 export type SizeQuery = `@${'width' | 'height'} ${string}`;
 
+/**
+ * A container query — `'@container width >= 400'`, or
+ * `'@container sidebar width >= 400'` naming the container: what a style
+ * can ask about the box it is inside rather than the window it is in. The
+ * container is the nearest ancestor whose style declares `container` (for
+ * the named form, the nearest carrying that name). Like a size query it may
+ * set layout properties; unlike one it is answered *after* the layout pass,
+ * since a container's size is what the pass produces.
+ */
+export type ContainerQuery = `@container ${string}`;
+
+/** A capability query — `'@supports transparency'`: what a style can ask
+ *  about the server. */
+export type SupportsQuery = `@supports ${string}`;
+
 /** The named blocks a style may carry, beside its own properties. */
 export interface StyleBlocks {
   transition?: Transition;
@@ -401,10 +426,13 @@ export interface StyleBlocks {
 
 /**
  * A style: the properties themselves, the state blocks, and any number of
- * size-query blocks keyed `'@width >= 600'`.
+ * query blocks keyed `'@width >= 600'`, `'@container width >= 400'` or
+ * `'@supports transparency'`.
  */
 export type Style = StyleProperties &
-  StyleBlocks & { [K in SizeQuery]?: StyleProperties };
+  StyleBlocks & {
+    [K in SizeQuery | ContainerQuery | SupportsQuery]?: StyleProperties;
+  };
 
 /**
  * What a `style` prop accepts: an object, or a nested array of them with

package/src/types/system.d.ts

@@ -234,9 +234,11 @@ export interface DesktopSettings {
   readonly doubleClickDistance: number;
   /** How far a press moves before it is a drag rather than a click. */
   readonly dragThreshold: number;
-  /** `'xsettings'`, or null where no settings daemon answered and these are
-   *  the renderer's own defaults. */
-  readonly source: 'xsettings' | 'test' | null;
+  /** `'xsettings'`; `'macos'` on the Cocoa backend, where only `animations`
+   *  comes from the system (reduce motion) and the rest are the defaults; or
+   *  null where no settings daemon answered and these are the renderer's own
+   *  defaults. */
+  readonly source: 'xsettings' | 'macos' | 'test' | null;
 }
 
 /**

package/src/types/tray.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The system tray: `useTray()`. See docs/desktop.md "The tray".
+ */
+
+import type { MenuItem } from './components.js';
+
+export interface TrayClickEvent {
+  button: 'left' | 'right' | 'middle';
+  /** The item's screen rect, global top-left coordinates in points — the
+   * anchor for a popup of your own. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  clickCount: number;
+  shift: boolean;
+  control: boolean;
+  option: boolean;
+  command: boolean;
+}
+
+export interface TrayOptions {
+  /** An SF Symbol name (`'bell.badge'`), or the bytes of a PNG. Drawn as a
+   * template image so it follows the bar's light and dark. */
+  icon?: string | Uint8Array | null;
+  /** Text beside the icon, or alone. */
+  title?: string | null;
+  tooltip?: string | null;
+  /** The menu a click opens — `MenuBar`'s item vocabulary. Without one,
+   * clicks reach `onClick`. */
+  menu?: MenuItem[] | null;
+  onClick?: (event: TrayClickEvent) => void;
+  visible?: boolean;
+  /** `false` keeps a PNG's own colours instead of drawing it as a template. */
+  template?: boolean;
+  /** `'variable'` (default) | `'square'` | a width in points. */
+  length?: 'variable' | 'square' | number;
+  /** The image's size in points, `[width, height]`. */
+  iconSize?: [number, number];
+}
+
+export interface TrayState {
+  /** Whether this backend has a tray at all — false on X11 today (#353). */
+  available: boolean;
+  /** Reserved. */
+  rect: null;
+}
+
+/**
+ * An icon in the system tray while this component is mounted; every field
+ * follows its value, and the item is removed on unmount. `null` means no
+ * item. Inert off the cocoa backend, with `available: false`.
+ */
+export declare function useTray(options: TrayOptions | null): TrayState;

package/src/windowid.js

@@ -39,6 +39,29 @@ export function windowIdOf(target) {
   return null;
 }
 
+/**
+ * The window **object** behind anything `windowIdOf` accepts — ntk's on X11,
+ * the cocoa backend's `CocoaWindow` — or `null`. The same walk, one step
+ * short of the id: a `<window>` ref holds the object itself, a `<window>`
+ * node has it as `window`, a drawn node reaches it through its `root`. A raw
+ * XID resolves to nothing, because the number alone does not say which
+ * connection issued it.
+ *
+ * Not public. The file dialog reaches the app a window belongs to through
+ * it, which is how a call names the backend whose native panel it wants
+ * without ever naming a backend.
+ */
+export function windowOf(target) {
+  if (target == null || typeof target === 'number') return null;
+  if (typeof target === 'object' && 'current' in target && !target.isWindow) {
+    return windowOf(target.current);
+  }
+  if (typeof target.window?.id === 'number') return target.window;
+  if (typeof target.root?.window?.id === 'number') return target.root.window;
+  if (typeof target.id === 'number') return target;
+  return null;
+}
+
 /**
  * `windowIdOf` bound to a ref: returns a **getter**, stable across renders,
  * the same shape `useAnchor` has. It is a getter rather than the id itself