react-x11 2.51.1 → 2.53.0

package/docs/eyedropper.md

@@ -0,0 +1,164 @@
+# The eyedropper
+
+Sample one pixel from the screen — any window, any application, the
+wallpaper — and get a colour an app can paint with.
+
+```jsx
+import { useEyedropper } from 'react-x11';
+
+function StrokePicker({ value, onChange }) {
+  const eyedropper = useEyedropper();
+
+  return (
+    <Button
+      label="Pick from screen"
+      disabled={eyedropper.picking}
+      onPress={async () => {
+        const hex = await eyedropper.pick();
+        if (hex) onChange(hex); // '#rrggbb'
+      }}
+    />
+  );
+}
+```
+
+Cancelling — Escape, the desktop dialog's own cancel, a dismissed macOS
+sampler — resolves to `null`. It is an ordinary outcome, not an exception,
+on every rung, so the whole error path is one `if`, as with the
+[file dialogs](filedialog.md).
+
+## The ladder
+
+|     |                        |                                                                                                                                                                                                                              |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the system sampler** | `NSColorSampler` on the [cocoa backend](macos.md) (`@windowkit/appkit` >= 0.9). macOS draws the loupe out of process, so the app needs no Screen Recording grant and the user gets the usual Mac magnifier.                  |
+| 2   | **the portal**         | `org.freedesktop.portal.Screenshot.PickColor` over D-Bus. The desktop draws its own magnifier and hands the colour back. GNOME and KDE ship it; it is also GNOME's only route on Wayland.                                    |
+| 3   | **the Wayland picker** | On the [Wayland backend](wayland-backend.md) where the compositor offers screen capture and layer-shell but no portal (wlroots: sway, labwc, …): the output is frozen into a capture overlay and the click is taken on that. |
+| 4   | **X11**                | Grab the pointer with a crosshair, wait for the click, read the pixel under it. Works under a bare WM, over ssh, on XQuartz — everywhere there is a display and nothing else.                                                |
+
+`screenColorBackend()` reports which rung this machine lands on without
+grabbing anything; `useEyedropper().supported` is the same answer as render
+state.
+
+There is no rung that react-x11 draws itself — the screen is exactly what an
+app cannot draw — so the ladder can run out. Where it does, `supported` is
+`false` and a pick rejects with a typed error, never a crash. A cocoa app on a
+bridge **older than 0.9** is that place ([macos.md](macos.md)): hide the
+button there.
+
+### The version gate
+
+`PickColor` arrived in **version 2** of the Screenshot interface, and a portal
+on the bus may not have it (XFCE's ships no Screenshot interface at all). The
+probe reads the interface's own `version` with `portalVersion()`, which is
+exported:
+
+```js
+import { portalVersion } from 'react-x11';
+
+const v = await portalVersion('org.freedesktop.portal.Screenshot');
+// 0 — not there at all; 1 — there, but before PickColor; 2+ — usable
+```
+
+Below 2, the ladder falls through to the X11 rung.
+
+## `useEyedropper()`
+
+```ts
+const { pick, supported, picking } = useEyedropper(defaults?);
+
+pick(options?): Promise<string | null>; // '#rrggbb', or null on cancel
+supported: boolean; // screenColorBackend() !== null, resolved for you
+picking: boolean;   // a pick is in flight — the button's pressed state
+```
+
+| option         |                                                           |
+| -------------- | --------------------------------------------------------- |
+| `parentWindow` | override the owner window; inferred otherwise             |
+| `signal`       | an `AbortSignal` that ends the pick and releases the grab |
+| `backend`      | force a rung; the seam for a kiosk, and for tests         |
+
+Options given to the hook are defaults for every pick; options given to a
+call win. The portal's dialog is parented to the window the component is in,
+resolved when the pick starts — the
+[`useFileDialog()` inference](filedialog.md#the-dialog-parents-itself), with
+`parentWindow` as the override for a tree with several top-level windows.
+
+- **`picking` is the pressed state.** While it is true, a second `pick()`
+  returns the promise already in flight rather than starting a second grab,
+  so a double-clicked button cannot make the user click twice.
+- **`supported` is almost always true.** An X11 tree's connection _is_ the
+  fallback rung, and a cocoa tree has the system sampler. It goes false when a
+  forced `backend: 'portal'` finds no portal, and on a cocoa app whose bridge
+  predates the sampler.
+
+## The bare function
+
+```js
+import { pickScreenColor, screenColorBackend } from 'react-x11';
+
+const hex = await pickScreenColor({ app });
+```
+
+Same options, same results. The one addition is `app`, because a bare function
+has no tree to take a connection from: pass the app `createRoot()` returned
+(or `useApp()` in a component, or a `parentWindow` that points at a mounted
+node). With no app named, the connections the renderer is currently drawing
+through are asked. Where no rung answers it rejects with `NoScreenColorError`
+— a **typed** rejection, so it reads as "hide the button", not as a crash.
+
+One pick per connection at a time **on the X11 rung**: a second concurrent
+`pickScreenColor()` on the same app is refused loudly (two grabs from one
+client would steal each other's click). The hook's shared in-flight promise is
+the friendly version of the same rule. On the system sampler a second pick
+joins the loupe that is up, and both callers get the same colour.
+
+## What differs between the rungs
+
+- **The system rungs draw a magnifier; the X11 rung does not.** On X11 it is
+  grab, crosshair, click — and Escape cancels.
+- **Only the system rungs need no permission.** The portal and
+  `NSColorSampler` run the picker in another process, so nothing asks for a
+  screen-capture grant (on macOS, no TCC prompt for Screen Recording).
+- **On the X11 rung the keyboard also picks.** Return, KP Enter or space
+  samples the pixel under the pointer without a click, and the keyboard is
+  grabbed for the duration so Escape works wherever the focus is.
+- **What is sampled is what is on the screen.** The X11 rung reads the
+  rendered pixel, so a colour under a translucent overlay is the blend, not
+  the window's own value. The portal's pickers (GNOME's, KDE's) read the
+  composited screen too.
+- **`signal` means less on the cocoa rung.** AppKit cannot dismiss a sampler
+  from code, so an abort there ends the wait and nothing else: the loupe stays
+  up until the user picks or presses Escape, its colour is dropped, and until
+  then the pending sample holds the process's event loop open. On the portal
+  and X11 rungs an abort closes the request or releases the grab.
+- **Every rung answers `'#rrggbb'`**, converted from the portal's and
+  sampler's sRGB floats or X11's server-layout pixel.
+
+## The grab, and what it displaces
+
+The X11 rung holds a **server pointer grab** while it waits, and core owns its
+whole lifecycle:
+
+- Every way out — click, Escape, abort, error — releases the grab before the
+  promise settles.
+- A `<popup grab>` that was open when the pick started (an open `Select`, a
+  menu, the colour panel the button sits in) gets its grab back when the pick
+  ends, so dismiss-on-outside-click still works afterwards.
+- If this client's own popup teardown releases the grab mid-pick, the pick
+  takes it back rather than hanging.
+
+Design notes: [design/eyedropper.md](../design/eyedropper.md).
+
+## Running it anywhere
+
+| where                                                | rung                                                                                         |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| macOS, the cocoa backend, `@windowkit/appkit` >= 0.9 | cocoa — `NSColorSampler` ([macos.md](macos.md))                                              |
+| macOS, the cocoa backend, an older bridge            | none — `supported` is false, `pickScreenColor()` rejects typed                               |
+| GNOME / KDE, or any portal with Screenshot ≥ 2       | portal                                                                                       |
+| XFCE (portal present, no Screenshot interface)       | X11                                                                                          |
+| ssh, `startx`, XQuartz, a container with a display   | X11                                                                                          |
+| Node 20, where npm skips `dbus-native`               | X11                                                                                          |
+| the Wayland backend, a portal with Screenshot ≥ 2    | portal                                                                                       |
+| the Wayland backend on wlroots (sway, labwc, …)      | wayland — the backend's own picker; there is no root window to read, so no X11 rung under it |

package/docs/filedialog.md

@@ -0,0 +1,222 @@
+# File dialogs
+
+Open a file, save a file, pick a folder — on whatever the machine has.
+
+```jsx
+import { useFileDialog } from 'react-x11';
+
+function Toolbar() {
+  const { openFile } = useFileDialog();
+
+  return (
+    <Button
+      label="Open…"
+      onPress={async () => {
+        const files = await openFile({
+          filters: [{ name: 'Markdown', extensions: ['md'] }],
+        });
+        if (!files) return; // cancelled
+        load(files[0]);
+      }}
+    />
+  );
+}
+```
+
+Cancelling resolves to `null`. It is an ordinary outcome, not an exception, on
+every backend — so the whole error path for a file dialog is one `if`.
+
+## The ladder
+
+The rung is chosen for you, top to bottom:
+
+|     |                         |                                                                                                                                                                                                                                                                                                                                                            |
+| --- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the native panel**    | `NSOpenPanel` / `NSSavePanel` on the [cocoa backend](macos.md) (`@windowkit/appkit` ≥ 0.5): a **sheet** on the window that asked, with every filter the OS type database knows. On the [win32 backend](windows.md), Windows' own open/save dialog, owned by the window that asked, takes the same rung (`fileDialogBackend()` reports `'cocoa'` for both). |
+| 2   | **the portal**          | `org.freedesktop.portal.FileChooser` over D-Bus: the desktop's own GTK or KDE dialog, with the user's bookmarks and recent files.                                                                                                                                                                                                                          |
+| 3   | **`osascript`**         | macOS on the X11 backend with no portal (every ordinary XQuartz install). `choose file` _is_ `NSOpenPanel`, in a third process.                                                                                                                                                                                                                            |
+| 4   | **the built-in dialog** | A browser react-x11 draws itself. ssh, a bare `startx`, a container: everywhere there is a display and nothing else.                                                                                                                                                                                                                                       |
+
+The top rung is chosen by the window the dialog belongs to, never by naming a
+backend. `fileDialogBackend()` reports which rung this machine lands on,
+without showing anything — for a diagnostics panel, or a menu that wants to
+say so.
+
+## `useFileDialog()`
+
+```ts
+const { openFile, saveFile, selectFolder } = useFileDialog(defaults?);
+
+openFile(options?): Promise<string[] | null>;    // absolute paths
+saveFile(options?): Promise<string | null>;      // one path, may not exist yet
+selectFolder(options?): Promise<string[] | null>;
+```
+
+The hook is the surface to reach for: it has a tree to draw the built-in dialog
+in, so it never runs out of rungs and never rejects for lack of a dialog.
+
+| option                        |                                                   |
+| ----------------------------- | ------------------------------------------------- |
+| `title`                       | the dialog's title                                |
+| `multiple`                    | several files at once; ignored when saving        |
+| `filters`                     | `{ name, extensions?, mimeTypes? }[]`             |
+| `defaultFolder`               | where it opens                                    |
+| `defaultName` / `defaultPath` | what a save dialog starts on                      |
+| `acceptLabel`                 | the confirm button's text — 'Import', 'Attach', … |
+| `parentWindow`                | override the owner window; inferred otherwise     |
+| `signal`                      | an `AbortSignal` that closes the dialog           |
+| `backend`                     | force a rung; the seam for a kiosk, and for tests |
+
+Options given to the hook are defaults for every call; options given to a call
+win.
+
+### The dialog parents itself
+
+The dialog is `transientFor` the window the component is in (`parent_window`
+for the portal), so the window manager stacks it above your window and keeps
+it out of the task switcher. **You do not pass anything for that**:
+`useFileDialog()` resolves the owner window through `useTopLevelWindow()` when
+the dialog opens.
+
+On the [native Wayland backend](wayland-backend.md) the portal is handed an
+**xdg-foreign** export of the window (`wayland:<handle>`), which GNOME and KDE
+both parent to. Where the compositor has no xdg-foreign the dialog opens
+unparented.
+
+The owner is inferred from the top-level windows this connection is rendering:
+
+- **one top-level window** — that one; nearly every app.
+- several, one focused — the focused one.
+- several with nothing to separate them — the most recently opened, plus a
+  development warning naming `parentWindow`.
+- **none at all** — the root-level `<popup>` that took the keyboard (a
+  menu-bar app's popover,
+  [elements.md](elements.md#a-popover-under-a-tray-item)).
+
+`parentWindow` is the **override for multi-window apps**, and takes a
+`<window>` ref, an XID, or anything `windowIdOf()` accepts:
+
+```jsx
+const win = useRef(null);
+const { openFile } = useFileDialog({ parentWindow: win });
+return <window ref={win}>…</window>;
+```
+
+`useTopLevelWindow()` is exported for anything else that needs the owner
+window. It returns a **ref-like object** — the window is not realized on the
+first render, so a value read then would be `null` on the render that matters —
+which drops into `parentWindow`, `transientFor`, or `windowIdOf()`.
+
+**The portal never embeds the dialog.** It is a top-level window in another
+process; the file list never appears inside your window.
+
+Design notes: [design/filedialog.md](../design/filedialog.md).
+
+## The imperative functions
+
+```ts
+import { openFile, saveFile, selectFolder } from 'react-x11';
+```
+
+Same options, same results — but they can only reach the native panel, the
+portal and `osascript`, because a function has nowhere to draw. Where there is
+none of those they reject with `NoFileDialogError`, which is a **typed**
+rejection: the signal to show your own UI, not a crash.
+
+Reach for these from host-side code and event-loop glue that has no component
+to hang off. In a component, use the hook.
+
+## What differs between the rungs
+
+- **MIME-type filters do not reach `osascript`.** `extensions` translate
+  exactly to every rung; `mimeTypes` reach the portal and the native panel
+  (the cocoa backend maps `image/png` to `public.png` through the OS type
+  database) and are dropped by `osascript`, where a wrong UTI guess would hide
+  the user's file. Give `extensions` where you can.
+- **`osascript` ignores `parentWindow`; the native panel is a sheet on it.**
+  The `osascript` panel appears over the app but is not attached to it;
+  application modality holds only because your code is awaiting the promise.
+  On the cocoa backend the panel is a **sheet**, and the app keeps running
+  while it is up. With no window at all — a bare `openFile()` with nothing in
+  `parentWindow` and no tree to infer one from — the native panel is
+  app-modal and **blocks the process**, timers included, until it is
+  dismissed. `useFileDialog()` always names the window, so it never lands
+  there.
+- **The built-in dialog has never seen the user's bookmarks.** It offers the
+  filesystem, a filter, hidden files, and a path you can type into — not a
+  re-creation of GTK's chooser.
+- **`multiple` in the built-in dialog is a tick column**, not ctrl-click.
+
+In the built-in dialog a double click opens a directory or picks a file, Enter
+does the same to the selected row, `Up` goes to the parent, and Escape cancels.
+
+## Running it where there is no bus
+
+| where                                                  | rung                                                                                                              |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| macOS, the **cocoa backend**                           | the native panel                                                                                                  |
+| GNOME / KDE / any desktop with xdg-desktop-portal      | portal                                                                                                            |
+| macOS + XQuartz, app running **on the Mac**            | `osascript`                                                                                                       |
+| macOS + XQuartz, app running on a **remote Linux box** | built-in — `osascript` would run on the wrong machine, and the paths it returned would not exist where the app is |
+| ssh, `startx`, a container, CI                         | built-in                                                                                                          |
+| Node 20, where npm skips `dbus-native`                 | built-in on Linux, `osascript` on a Mac                                                                           |
+
+The `osascript` rung is reached by _not_ finding a portal, so it also covers a
+Mac that has a session bus for other reasons. A portal shim on a Mac wins on
+the X11 backend; on the cocoa backend the native panel is above it either way.
+
+## The portal machinery, if you need it directly
+
+`portalRequest()` is exported for building other portals on. It calls a portal
+method that shows UI and resolves with its `Request.Response`:
+
+```js
+const { response, results } = await portalRequest(busRef, {
+  iface: 'org.freedesktop.portal.FileChooser',
+  member: 'OpenFile',
+  parentWindow: 'x11:1a00007',
+  title: 'Open',
+  options: { multiple: true },
+});
+```
+
+It subscribes to the response before calling, so the answer cannot be lost;
+an abort sends `Request.Close()` and settles the promise locally (the portal
+emits no `Response` for it); and only the initial call has a deadline — the
+answer has none, because a dialog can legitimately be open for an hour.
+
+The default argument shape, `(s parent_window, s title, a{sv} options)`, is
+FileChooser's alone. Any other Request-shaped portal states its leading
+arguments as `signature` and `args` together; the
+[eyedropper](eyedropper.md)'s `PickColor`, which has no title:
+
+```js
+await portalRequest(busRef, {
+  iface: 'org.freedesktop.portal.Screenshot',
+  member: 'PickColor',
+  signature: 'sa{sv}',
+  args: [parentWindow],
+});
+```
+
+The signature must end in `a{sv}` (the options dict carries `handle_token`); a
+method without one does not answer through a `Request` and wants a plain
+`bus.invoke` instead.
+
+`hasService(name)` answers whether a service is reachable — owned now **or
+activatable on demand**. (`NameHasOwner` alone is the wrong question: the
+portal is D-Bus-activatable and often has no owner until first use.)
+
+`portalVersion(iface)` answers whether the portal's backends provide one
+_interface_, and at what version — `0` when it is not there at all. Gate on
+this rather than on the service: desktops provide some portals and not others
+(XFCE has FileChooser and no Screenshot).
+
+See [dbus.md](dbus.md) for the connection these sit on.
+
+## Seeing it
+
+- `npm run examples:menu` — a File menu whose Open/Save entries are real, with
+  the rung this machine landed on shown in the window.
+  Force the bottom rung anywhere with `backend: 'builtin'`, which is also how the
+  tests exercise it.