react-x11 1.2.0 → 2.0.0

package/src/types/filedialog.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The file dialog and the portal machinery under it. See docs/filedialog.md.
+ */
+
+import type { ReactNode, RefObject } from 'react';
+import type { MessageBus } from './dbus.js';
+import type { DrawnNode, NtkWindow } from './nodes.js';
+
+/**
+ * The shape of `AbortSignal` this uses.
+ *
+ * Named structurally rather than reaching for the global: these declarations
+ * compile with `types: []` and no `DOM` lib — adding `DOM` to get one name
+ * would also make `<div>` legal JSX, which owning the element namespace exists
+ * to prevent. A real `AbortSignal` satisfies this.
+ */
+export interface AbortSignalLike {
+  readonly aborted: boolean;
+  readonly reason?: unknown;
+  addEventListener(
+    type: 'abort',
+    listener: () => void,
+    options?: { once?: boolean },
+  ): void;
+  removeEventListener(type: 'abort', listener: () => void): void;
+}
+
+/** Which rung of the ladder answered — or would. */
+export type FileDialogBackend = 'portal' | 'osascript' | 'builtin';
+
+/**
+ * One entry in a dialog's type filter.
+ *
+ * Give `extensions` where you can: they translate to every backend. MIME types
+ * reach the portal exactly and macOS not at all — see docs/filedialog.md.
+ */
+export interface FileFilter {
+  name: string;
+  /** `['png', 'jpg']` — with or without the leading dot. */
+  extensions?: string[];
+  /** `['image/png']`. Portal only. */
+  mimeTypes?: string[];
+}
+
+/** Anything a `<window>`/`<popup>` ref or XID can be given as. */
+export type WindowTarget =
+  | NtkWindow
+  | DrawnNode
+  | RefObject<NtkWindow | DrawnNode | null>
+  | number
+  | null;
+
+export interface FileDialogOptions {
+  title?: string;
+  /** Several files at once. Ignored when saving — that is always one file. */
+  multiple?: boolean;
+  filters?: FileFilter[];
+  /** Where the dialog opens. */
+  defaultFolder?: string;
+  /** The name a save dialog starts with. */
+  defaultName?: string;
+  /** The file a save dialog starts on, replacing `defaultName`. */
+  defaultPath?: string;
+  /** The confirm button's text — 'Import', 'Attach', … */
+  acceptLabel?: string;
+  /**
+   * The window the dialog belongs to. `transientFor` for the built-in dialog,
+   * `parent_window` for the portal; macOS has no cross-process equivalent and
+   * ignores it. Worth the one line — without it the dialog floats.
+   */
+  parentWindow?: WindowTarget;
+  /** Abort the dialog. Closes the portal request or kills `osascript`. */
+  signal?: AbortSignalLike;
+  /**
+   * Force a rung instead of taking the best available one. The seam for a
+   * kiosk that must never show the desktop's dialog, and for tests.
+   */
+  backend?: FileDialogBackend;
+  /** `false` lets the portal dialog be non-modal. Default `true`. */
+  modal?: boolean;
+}
+
+/**
+ * Nothing on this machine can show a file dialog, and the caller cannot draw
+ * one either. A **typed** rejection, so it reads as "fall back to your own UI"
+ * rather than as a crash — {@link useFileDialog} never throws it, because it
+ * has a tree to draw in.
+ */
+export declare class NoFileDialogError extends Error {
+  readonly name: 'NoFileDialogError';
+  readonly cause?: unknown;
+}
+
+/** There is no portal here — no bus, no service, or a version too old. */
+export declare class NoPortalError extends Error {
+  readonly name: 'NoPortalError';
+  readonly cause?: unknown;
+}
+
+/** The user dismissed the dialog. Surfaced as `null`, not thrown, by the
+ * functions below; exported for code driving {@link portalRequest} directly. */
+export declare class PortalCancelledError extends Error {
+  readonly name: 'PortalCancelledError';
+  /** 1 when the user cancelled, 2 when it ended some other way. */
+  readonly response: number;
+}
+
+/**
+ * Which rung this machine lands on, without showing anything.
+ *
+ * Acquires a bus reference and releases it, so it is cheap but not free —
+ * cache it rather than calling it on a render path.
+ */
+export declare function fileDialogBackend(): Promise<FileDialogBackend>;
+
+/**
+ * Ask for existing files. Resolves to absolute paths, or `null` when the user
+ * cancelled.
+ *
+ * Rejects with {@link NoFileDialogError} where there is no portal and no
+ * `osascript`; {@link useFileDialog} draws its own dialog instead.
+ */
+export declare function openFile(
+  options?: FileDialogOptions,
+): Promise<string[] | null>;
+
+/** Ask where to write a file. One absolute path, which need not exist yet. */
+export declare function saveFile(
+  options?: FileDialogOptions,
+): Promise<string | null>;
+
+/** Ask for directories. Absolute paths, or `null` when cancelled. */
+export declare function selectFolder(
+  options?: FileDialogOptions,
+): Promise<string[] | null>;
+
+export interface FileDialogs {
+  openFile(options?: FileDialogOptions): Promise<string[] | null>;
+  saveFile(options?: FileDialogOptions): Promise<string | null>;
+  selectFolder(options?: FileDialogOptions): Promise<string[] | null>;
+}
+
+/**
+ * The window this component is in, resolved when it is read rather than at
+ * render time — a `<window>` has no XID until the commit phase.
+ *
+ * Returns a **ref-like object**, so it drops into anything that already takes
+ * a ref (`parentWindow`, `transientFor`) and `windowIdOf()` resolves it.
+ * `useFileDialog()` uses it for you; reach for it directly when something
+ * else needs the owner window.
+ *
+ * Exact when the tree has one top-level window, which is nearly every app.
+ * With several it prefers the focused one and warns in development when it
+ * has to guess — see docs/filedialog.md.
+ */
+export declare function useTopLevelWindow(): {
+  readonly current: NtkWindow | DrawnNode | null;
+};
+
+/**
+ * File dialogs that never run out of rungs: the desktop's own where there is
+ * one, `osascript` on macOS, and a browser react-x11 draws itself everywhere
+ * else. Cancelling resolves to `null` on all three.
+ *
+ * ```tsx
+ * const { openFile } = useFileDialog({ parentWindow: windowRef });
+ * const files = await openFile({ filters: [{ name: 'Text', extensions: ['txt'] }] });
+ * if (files) load(files[0]);
+ * ```
+ */
+export declare function useFileDialog(
+  defaults?: FileDialogOptions,
+): FileDialogs;
+
+export interface FileDialogProps {
+  kind?: 'open' | 'save' | 'folder';
+  title?: string;
+  startFolder?: string;
+  defaultName?: string;
+  filters?: FileFilter[];
+  multiple?: boolean;
+  acceptLabel?: string;
+  /** An XID. Resolved for you when this is rendered by `useFileDialog()`. */
+  parentWindow?: number;
+  /** Called exactly once: the chosen paths, or `null` for cancel. */
+  onDone?: (paths: string[] | null) => void;
+  /** The palette, for when this is rendered on a root with no provider. */
+  theme?: Record<string, unknown>;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * The built-in file browser, as a component. `useFileDialog()` renders this
+ * for you; reach for it directly only when this dialog is the one you want
+ * regardless of what the desktop offers.
+ */
+export declare function FileDialog(props: FileDialogProps): ReactNode;
+
+// ---------------------------------------------------------------------------
+// The portal floor
+// ---------------------------------------------------------------------------
+
+/**
+ * Is `name` reachable — owned now, **or activatable on demand**?
+ *
+ * `NameHasOwner` is the wrong question: `org.freedesktop.portal.Desktop` is
+ * D-Bus-activatable, so on a healthy desktop where no app has touched a portal
+ * yet it has no owner, and a feature gated on that takes the fallback path
+ * forever.
+ */
+export declare function hasService(
+  name: string,
+  busRef?: { bus: MessageBus; uniqueName: string },
+): Promise<boolean>;
+
+export interface PortalRequestOptions {
+  iface: string;
+  member: string;
+  /** `'x11:1a00007'`, or `''` for none. */
+  parentWindow?: string;
+  title?: string;
+  /**
+   * The method's full argument signature, ending in the options dict —
+   * `'sa{sv}'` for `Screenshot.PickColor`. Travels with `args`; omitting
+   * both means FileChooser's `'ssa{sv}'` with `[parentWindow, title]`.
+   */
+  signature?: string;
+  /** The leading arguments the signature describes, before the options dict. */
+  args?: unknown[];
+  options?: Record<string, unknown>;
+  signal?: AbortSignalLike;
+}
+
+/**
+ * Call a portal method that answers through a `Request`, with the
+ * subscription in place **before** the call goes out — which is the whole
+ * reason this exists rather than each portal doing it slightly wrong.
+ *
+ * There is deliberately no timeout on the answer: a dialog can be open for an
+ * hour. Only the initial call is deadlined.
+ */
+export declare function portalRequest(
+  busRef: { bus: MessageBus; uniqueName: string },
+  options: PortalRequestOptions,
+): Promise<{ response: number; results: Record<string, unknown> }>;
+
+/**
+ * The version of one portal *interface*, or `0` when it is not there.
+ *
+ * {@link hasService} answers a different question: the portal service being
+ * reachable says nothing about which interfaces its backends provide.
+ * Capability lives in the interface's own `version` property — `PickColor`
+ * needs `org.freedesktop.portal.Screenshot` at 2, and XFCE's portal has no
+ * Screenshot interface at all.
+ */
+export declare function portalVersion(
+  iface: string,
+  busRef?: { bus: MessageBus; uniqueName: string },
+): Promise<number>;

package/src/types/fonts.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Font files an application opens for itself — reading one, and registering
+ * one so `fontFamily` can name it. See docs/styling.md#a-font-file-of-your-own.
+ */
+
+import type { NtkApp } from './nodes.js';
+
+/**
+ * ntk's `Font`, as much of it as is worth declaring by hand.
+ *
+ * Deliberately loose, for the same reason `react-x11/ntk` is: ntk ships no
+ * types, and a full mirror written here would drift out of date silently.
+ * The members below are the ones an application reads; everything else the
+ * class has is still there at runtime.
+ */
+export interface Font {
+  /** The family the file calls itself — not necessarily what it is
+   *  registered as; see {@link loadFont}. */
+  readonly familyName: string;
+  readonly postscriptName: string;
+  readonly unitsPerEm: number;
+  /** Stable cache key — the same file opened twice has the same one. */
+  readonly key: string;
+  /** The path it was opened from, or null for a font opened from bytes. */
+  readonly path: string | null;
+  /** fontkit's own font object, for what this interface does not cover
+   *  (`namedVariations`, the raw tables). */
+  readonly fk: Record<string, unknown> & {
+    namedVariations?: Record<string, Record<string, number>>;
+  };
+  /**
+   * `{}` for a static face, so `Object.keys(font.variationAxes).length` is
+   * the whole of "is this variable?".
+   */
+  readonly variationAxes: Record<
+    string,
+    { name?: string; min: number; default: number; max: number }
+  >;
+  /** Scaled to a pixel size. A metric the face never declared is `null`
+   *  rather than 0 — a cap height it did not state is not a cap height of
+   *  zero. */
+  metrics(size: number): {
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    capHeight: number | null;
+    xHeight: number | null;
+    [key: string]: number | null;
+  };
+  hasGlyph(codepoint: number): boolean;
+  /** This face at a point in its design space: `variation({ wght: 460 })`. */
+  variation(settings: Record<string, number>): Font;
+}
+
+export interface OpenFontOptions {
+  /** Which face of a `.ttc` collection; the first otherwise. */
+  postscriptName?: string;
+}
+
+export interface LoadFontOptions extends OpenFontOptions {
+  /** Register under this name instead of the font's own, and use it
+   *  verbatim. */
+  family?: string;
+  /** Override the weight the file declares. */
+  weight?: number | string;
+  /** `'italic'` / `'oblique'`, overriding what the file declares. */
+  style?: string;
+}
+
+export interface LoadedFont {
+  readonly font: Font;
+  /** What to put in `fontFamily` — the font's own name, scoped to
+   *  `Inter 2` only where a second file would otherwise be unreachable. */
+  readonly family: string;
+}
+
+/**
+ * Read a font file — metrics, coverage, variation axes — through the
+ * connection's font cache, so it is read once however often this is called.
+ *
+ * ```ts
+ * const font = openFont(app, '/usr/share/fonts/truetype/inter/Inter.ttf');
+ * font.metrics(30);
+ * font.variationAxes;
+ * ```
+ *
+ * Nothing about the app changes: the face is not registered, so it is
+ * neither a `fontFamily` candidate nor part of the fallback chain. Use
+ * {@link loadFont} to draw with it.
+ */
+export function openFont(
+  app: NtkApp,
+  source: string | Uint8Array,
+  opts?: OpenFontOptions,
+): Font;
+
+/**
+ * Read a font file and register it, returning the face and the family name
+ * to draw it with.
+ *
+ * ```tsx
+ * const { family } = loadFont(app, '/path/to/Inter.ttf');
+ * <text style={{ fontFamily: family }}>Handgloves</text>;
+ * ```
+ */
+export function loadFont(
+  app: NtkApp,
+  source: string | Uint8Array,
+  opts?: LoadFontOptions,
+): LoadedFont;
+
+/**
+ * {@link loadFont} from a component, memoized per app and file. Null when
+ * `source` is null, so a picker can call it before anything is picked.
+ *
+ * ```tsx
+ * const picked = useFont(path);
+ * <text style={{ fontFamily: picked?.family }}>{sample}</text>;
+ * ```
+ */
+export function useFont(
+  source?: string | Uint8Array | null,
+  opts?: LoadFontOptions,
+): LoadedFont | null;

package/src/types/frame.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `<Frame>` — a pane of this application in its own process — and the
+ * context bridge that follows the app into it. See docs/frame.md.
+ */
+
+import type { Context, ReactElement, ReactNode, Ref } from 'react';
+import type { StyleProp } from './style.js';
+
+/**
+ * The props bag a `<Frame>` sends its pane. Values cross by structured
+ * clone; functions become fire-and-forget stubs on the pane side, so a
+ * callback's return value is always `undefined` over there.
+ */
+export type FrameProps = Record<string, unknown>;
+
+/** Why a pane is not running, for `fallback` and `onExit` to read. */
+export interface FrameError extends Error {
+  /** Where it went wrong: `'spawn' | 'load' | 'connect' | 'handshake' |
+   * 'runtime' | 'send' | 'embed' | 'exit'`. */
+  phase?: string;
+  code?: number | null;
+  signal?: string | null;
+}
+
+export interface FrameHandle {
+  /** Start a fresh pane process; what `fallback` receives to retry with. */
+  restart(): void;
+  /** The pane's pid, `null` before the first spawn and after an exit. */
+  pid: number | null;
+}
+
+export interface FrameComponentProps {
+  /**
+   * The pane module: its default export is mounted as the pane's root
+   * component. A `URL` (`new URL('./pane.js', import.meta.url)` — typed
+   * structurally so no DOM lib is needed) or an absolute path — never
+   * relative, which would resolve against react-x11's own files rather
+   * than the caller's.
+   */
+  src: { href: string } | string;
+  /** Data for the pane, snapshotted and sent whole once per commit that
+   * changes it. Functions anywhere in the bag become RPC stubs. */
+  props?: FrameProps;
+  /** The embedded pane's rect in this tree — sized like any other child. */
+  style?: StyleProp;
+  /** X display for the pane process; defaults to the inherited `$DISPLAY`. */
+  display?: string;
+  /**
+   * Which bridged contexts follow the app into this pane: `true` (default)
+   * for every registered one — the theme included — `false` for none, or an
+   * allowlist of keys.
+   */
+  bridge?: boolean | string[];
+  /**
+   * What this rect shows when the pane crashed or could not start: an
+   * element, or a function of the error and a `restart` that respawns.
+   * Without one the rect is an empty box in its `style`.
+   */
+  fallback?:
+    | ReactElement
+    | ((info: { error: FrameError | null; restart: () => void }) => ReactNode);
+  /** Whether the pane joins the tab order, like any `<foreign>`. */
+  focusable?: boolean;
+  /** The pane mounted and its window is being embedded. */
+  onStarted?(info: { pid: number | null; windowId: number }): void;
+  /** The pane process ended. `expected` is true when this side asked —
+   * unmount, `restart()`, a `src` change — and false for a crash. */
+  onExit?(info: {
+    code: number | null;
+    signal: string | null;
+    expected: boolean;
+  }): void;
+  /**
+   * Replace the fork with a transport of your own — the seam the tests use
+   * (a loopback pair into `runFrameChild`), and the door to running a pane
+   * somewhere other than a child process. Advanced; see docs/frame.md.
+   */
+  transport?(options: { src: string; display?: string }): FrameTransport;
+  ref?: Ref<FrameHandle>;
+}
+
+/** The parent's end of the wire to a pane. */
+export interface FrameTransport {
+  /** May throw when the channel is gone or the message will not clone. */
+  send(msg: object): void;
+  onMessage(cb: (msg: object) => void): () => void;
+  onExit(
+    cb: (info: {
+      code?: number | null;
+      signal?: string | null;
+      error?: Error | null;
+    }) => void,
+  ): () => void;
+  kill?(signal: string): void;
+  pid?: number;
+}
+
+/**
+ * A module of this application, mounted in its own process, its window
+ * embedded here (over `<foreign>`). Props cross as data, callbacks as
+ * fire-and-forget stubs, context through the bridge — and the process
+ * boundary contains the pane's failures, not its intentions: it is not a
+ * security boundary (docs/security.md).
+ */
+export function Frame(props: FrameComponentProps): ReactElement | null;
+
+export interface FrameContext<T> {
+  /** The name this value travels under; unique per application. */
+  key: string;
+  /** The ordinary React context, for `useContext` and class consumers. */
+  Context: Context<T>;
+  /** The provider that also publishes the value to `<Frame>` panes. */
+  Provider: (props: { value: T; children?: ReactNode }) => ReactElement;
+  /** `useContext(Context)`, as a method. */
+  use(): T;
+}
+
+/**
+ * A React context whose value follows the app into its `<Frame>` panes:
+ * in-process an ordinary context, across a frame a structured-clone
+ * snapshot recreated as a real provider around the pane. One direction,
+ * data only — a value that will not clone is dropped with a warning, and
+ * dispatchers travel in `props` where the wiring is visible.
+ *
+ * Both sides must import the module that calls this — which the pane
+ * already does, since its components read the context from it.
+ */
+export function createFrameContext<T>(
+  key: string,
+  defaultValue: T,
+  options?: {
+    serialize?: (value: T) => unknown;
+    revive?: (wire: unknown) => T;
+  },
+): FrameContext<T>;
+
+/**
+ * Runs when the host is letting this pane go — the `<Frame>` unmounted,
+ * the host app is exiting — bounded by the host's patience (it escalates
+ * to signals). May return a promise. Not called on a crash; outside a
+ * frame it never runs.
+ */
+export function useFrameClose(handler: () => void | Promise<void>): void;
+
+/** Whether this process is a `<Frame>` pane. */
+export function isFramed(): boolean;

package/src/types/globalmenu.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The global menu — handing a window's menu bar to the desktop's panel.
+ *
+ * `MenuBar` does all of this itself. These names are for a component that
+ * draws its own bar and wants the same behaviour. See docs/globalmenu.md.
+ */
+
+import type { MenuBarMenu, MenuItem } from './components.js';
+
+export interface GlobalMenuOptions {
+  /** Runs after the item's own `onSelect`, exactly as `MenuBar`'s does. */
+  onSelect?: (item: MenuItem) => void;
+  /**
+   * A submenu is about to be shown. dbusmenu wants a synchronous answer that
+   * React cannot give, so this is a notification rather than a chance to
+   * fill the menu in time — update state from it and the new items reach the
+   * panel one round trip later. See docs/globalmenu.md.
+   */
+  onAboutToShow?: (item: MenuItem) => void;
+  /** `false` keeps the menu in the window. Defaults to `true`. */
+  enabled?: boolean;
+}
+
+/**
+ * Is this window's menu being drawn by the desktop?
+ *
+ * `false` until proven otherwise, and the proof is a registrar answering
+ * `RegisterWindow` — so no bus, no panel, or a panel that refused the
+ * registration all keep the menu where the app drew it.
+ *
+ * ```tsx
+ * const exported = useGlobalMenu(menus, { onSelect });
+ * if (exported) return null;
+ * ```
+ */
+export function useGlobalMenu(
+  menus: readonly MenuBarMenu[] | undefined,
+  options?: GlobalMenuOptions,
+): boolean;
+
+/** The bus name a panel owns while it is showing application menus. */
+export const REGISTRAR_NAME: string;