react-x11 2.51.0 → 2.52.0

package/docs/eyedropper.md

@@ -0,0 +1,223 @@
+# 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`. The same contract as the
+[file dialogs](filedialog.md), on purpose.
+
+## The ladder
+
+|     |                        |                                                                                                                                                                                                                                                                                                                                                            |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the system sampler** | `NSColorSampler` on the [cocoa backend](macos.md), where the app the tree renders through carries `colorSampler` (`@windowkit/appkit` >= 0.9). macOS draws the loupe out of process, so the app needs no Screen Recording grant of its own and the user gets the magnifier every other Mac colour picker shows.                                            |
+| 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, shown as an overlay, and the click is taken on that (`src/wayland/screencopy.js`). Below the portal because the portal is the desktop's own, user-consented picker. |
+| 4   | **X11**                | The classic route: grab the pointer with a crosshair, wait for the click, read the 1×1 under it, decode by the server's own pixel layout. 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.
+
+The first three rungs are the same shape — ask the system, it draws the
+picker, it hands back an sRGB triple — which is why the sampler goes on top
+of the portal and not under the crosshair: where the OS will do this for us,
+it does it better.
+
+There is no rung to _draw_, and that is the difference from the file dialog's
+ladder: the thing being read — the whole screen — is precisely what an
+application cannot draw itself. So the hook adds binding, not a fallback of
+its own — and the ladder can therefore run out. Where it does, the floor is
+the typed rejection and `supported: false`, never a crash. A cocoa app on a
+bridge **older than 0.9** is that place: its `app.X` is a stub, so there is
+no pointer to grab and no root window to read either ([macos.md](macos.md)).
+Both system rungs are gated on what they are built out of — one bridge verb,
+three X requests — rather than on there being an app, so a picker there draws
+no eyedropper button instead of one that throws on its first press.
+
+### The version gate
+
+`PickColor` arrived in **version 2** of the Screenshot interface, and the
+portal being on the bus says nothing about that: `hasService()` sees the
+service, not what its backends provide. XFCE's portal, for example, ships no
+Screenshot interface at all — a machine where every FileChooser call works
+and every PickColor would fail. So the probe reads the interface's own
+`version` property, via `portalVersion()` (exported, since the next portal
+feature will need the same question answered):
+
+```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
+```
+
+Where the answer is below 2, the ladder falls through to the X11 rung
+rather than calling a method the portal would refuse.
+
+## `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, with
+`parentWindow` as the override for a tree with several top-level windows.
+
+Two things the hook does beyond forwarding:
+
+- **`picking` is the pressed state**, and it is honest: 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 on this toolkit.** An X11 tree has a
+  connection by definition, and the connection _is_ the fallback rung; 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 — which is what keeps the button honest on whatever
+  platform comes next.
+
+## The bare function
+
+```js
+import { pickScreenColor, screenColorBackend } from 'react-x11';
+
+const hex = await pickScreenColor({ app });
+```
+
+Same options, same results. The one addition is `app`: the X11 rung needs a
+connection to grab and read on and the cocoa rung needs the app whose
+sampler to show, and a bare function has no tree to take one from — pass the
+app `createRoot()` returned (or `useApp()` in a component, or a
+`parentWindow` that points at a mounted node, which carries its app with
+it). With no app named, the connections the renderer is currently drawing
+through are asked, the way `openFile()` finds its native panel. 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, because a second grab
+from the same client would silently _replace_ the first and one pick would
+settle with the other's click. The hook's shared in-flight promise is the
+friendly version of the same rule. The system sampler needs no such refusal:
+`NSColorSampler` "begins or attaches to an existing color sampling session",
+so 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 deliberately does not.**
+  On X11 it is grab, crosshair, click — and Escape cancels. The desktops
+  whose users expect a loupe have a portal or an `NSColorSampler` that draws
+  one; a hand-rolled loupe on the bottom rung would be a screenshot of the
+  screen re-rendered at 8×, permanently slightly wrong about scaling and
+  colour management.
+- **Only the system rungs need no permission.** Both the portal and
+  `NSColorSampler` run the picker in another process and hand back a
+  colour, so nothing here asks for a screen-capture grant — on macOS that
+  is the difference between a dropper button and a 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 — GTK's shape — and
+  the keyboard is grabbed for the duration so Escape works wherever the
+  focus happens to be.
+- **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. What exactly the portal samples is the desktop's
+  choice, not this API's — GNOME's and KDE's pickers read the composited
+  screen too.
+- **`signal` means less on the cocoa rung.** AppKit offers no way to dismiss
+  a sampler from code — the session ends when the user picks or presses
+  Escape — so an abort there ends the wait and nothing else: the loupe stays
+  up, and the colour it eventually reports is dropped. Until then that
+  pending sample holds the process's event loop open, the way pending I/O
+  does. The portal's request is Closed and the X11 grab is released, which
+  is what an abort has to guarantee where something _is_ held.
+- **Every rung answers `'#rrggbb'`.** The portal and the sampler hand back
+  sRGB floats and X11 hands back server-layout words; every consumer wants a
+  CSS colour it can paint with, so the conversion happens once, here — the
+  same function for the two float rungs. If something later needs the
+  unrounded values, an option can widen the return — starting with channels
+  would have made the common case do arithmetic.
+
+## The grab, and what it displaces
+
+The X11 rung holds a **server pointer grab** while it waits. That is the
+dangerous part of the feature — an application that leaks a grab leaves a
+desktop that has stopped answering clicks — and it is why the grab's whole
+lifecycle belongs to core rather than to apps:
+
+- Every way out — click, Escape, abort, error — releases the grab before the
+  promise settles. The `signal` option releases it too; that is guaranteed
+  here, not delegated to the caller.
+- A `<popup grab>` that was open when the pick started — an open `Select`,
+  a menu, the colour panel the eyedropper button itself sits in — had its
+  grab silently replaced by the pick's (same client, so X raises no error
+  and tells no one). When the pick ends, core hands that popup its grab
+  back, so dismiss-on-outside-click still works afterwards.
+- A grab released out from under a pick — this client's own popup teardown
+  calls `UngrabPointer`, which releases whatever the client's active grab is
+  — is detected (the server announces it with a `LeaveNotify` of mode
+  `Ungrab` on the grab window) and taken back, rather than leaving a pick
+  that never resolves while the app answers clicks as if nothing were
+  happening.
+
+## 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 |
+
+## Building a colour picker on it
+
+The eyedropper is the one part of a colour picker that cannot be composed
+out of public elements, which is why it lives in core and the picker panel
+does not. A `<ColorPicker>` in `@react-x11/components` consumes it as a
+function prop:
+
+```jsx
+<ColorPicker eyedropper={pickScreenColor} value={fill} onChange={setFill} />
+```
+
+and once that component exists, this function is its default and no app
+changes.

package/docs/filedialog.md

@@ -0,0 +1,258 @@
+# 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
+
+There is no single answer to "show a file dialog" across the machines this
+runs on, so this is a ladder and the rung is chosen for you:
+
+|     |                         |                                                                                                                                                                                                                                                                                                                                                                             |
+| --- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the native panel**    | `NSOpenPanel` / `NSSavePanel` in this process, 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 it as `'cocoa'` too). |
+| 2   | **the portal**          | `org.freedesktop.portal.FileChooser` over D-Bus. The desktop's own dialog, drawn by GTK or KDE in another process, with the user's bookmarks and recent files.                                                                                                                                                                                                              |
+| 3   | **`osascript`**         | macOS on the X11 backend with no portal — which is every XQuartz install that has not gone out of its way. `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 never chosen by naming a backend: the dialog asks the window
+it belongs to which connection it is on, and an app that can show native
+panels says so. That is what keeps the ladder one ladder as backends join it.
+
+`fileDialogBackend()` reports which one this machine lands on, without showing
+anything — useful for a diagnostics panel, and for a menu that wants to say so.
+
+**The ladder is the design, not a fallback chain bolted on.** react-x11's
+flagship case is an app running on one machine and drawing to another, and a
+file dialog that only worked on a full GNOME session would be useless to
+exactly the person the renderer exists for.
+
+## `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, because it is the only one with a tree to
+draw 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 — which is what makes the window manager treat it as belonging
+to your window: stacked above it, and not a second entry in the task switcher.
+
+**You do not pass anything for that.** `useFileDialog()` resolves the owner
+window through `useTopLevelWindow()` at the moment a dialog opens, by which
+time the window is mounted and has an XID.
+
+On the [native Wayland backend](wayland-backend.md) the window has no XID,
+and the portal is handed an **xdg-foreign** export of it instead —
+`wayland:<handle>`, which GNOME and KDE both parent to. Where the compositor
+has no xdg-foreign the handle is empty and the dialog opens unparented.
+
+Why inference rather than a lookup: a hook has no position in the host tree.
+React context cannot come from a host element, the host context
+`getChildHostContext` builds reaches `createInstance` and not components, and a
+`<window>` has no XID until the commit phase. So it answers from what the
+renderer does know — the top-level windows this connection is rendering:
+
+- **one top-level window is exact.** The component is in it, because there is
+  nowhere else to be. That is nearly every app.
+- several, one focused: that one. You clicked in it a moment ago, which is why
+  a dialog is opening.
+- several with nothing to separate them: the most recently opened, plus a
+  development warning naming `parentWindow` as the way to be exact.
+- **none at all: the root-level `<popup>` that took the keyboard.** A menu-bar
+  app is a tray item and the popover a click on it opens, and nothing else
+  ([elements.md](elements.md#a-popover-under-a-tray-item)) — so the popup is
+  the top of that tree, and answering nothing left every hook that reads this
+  one with no owner to belong to.
+
+So `parentWindow` survives as 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, and logical parenting is all there is. There is no version of this
+where the file list appears inside your window.
+
+## 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
+
+Most of the API is the same everywhere. These are the places it genuinely is
+not, stated here rather than discovered:
+
+- **MIME-type filters do not reach `osascript`.** `extensions` translate
+  exactly to every rung; `mimeTypes` reach the portal and the native panel
+  (the cocoa backend asks the OS's own type database, so `image/png` is
+  `public.png` there) and are dropped by `osascript`, because AppleScript's
+  `of type` wants extensions or UTIs and guessing a UTI wrong hides the user's
+  file with no way to get at it. Give `extensions` where you can.
+- **`osascript` ignores `parentWindow`; the native panel is a sheet on it.**
+  XQuartz windows are `NSWindow`s owned by X11.app, macOS has no cross-process
+  transient-for, and `osascript` is a third process besides: its panel
+  appears over the app but is not attached to it, and application modality
+  works only because your code is awaiting the promise. On the cocoa backend
+  the panel is a **sheet** on that window, 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. It is
+  deliberately 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
+— and a selected directory is drawn in the selection's own text colour rather
+than the accent it wears at rest, since the selected row is filled with that
+accent in both schemes.
+
+## Running it where there is no bus
+
+The interesting configurations, and what each one does:
+
+| 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. If you do run a portal shim on a
+Mac (see [issue #111](https://github.com/sidorares/react-x11/issues/111)), it
+wins on the X11 backend, which is what you asked for by running it; 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. Every portal
+method that shows UI returns an object path immediately and answers later with
+a `Request.Response` signal — and the path is predictable **by design**, so the
+client subscribes _before_ it calls and cannot lose the answer:
+
+```js
+const { response, results } = await portalRequest(busRef, {
+  iface: 'org.freedesktop.portal.FileChooser',
+  member: 'OpenFile',
+  parentWindow: 'x11:1a00007',
+  title: 'Open',
+  options: { multiple: true },
+});
+```
+
+It owns the three things every portal caller otherwise re-solves: subscribing
+first, `Request.Close()` on abort (which emits **no** `Response`, so the
+promise has to be settled locally), and no timeout on the answer — a dialog can
+legitimately be open for an hour, and only the initial call is deadlined.
+
+The default argument shape is FileChooser's, `(s parent_window, s title, a{sv}
+options)` — and that shape is FileChooser's alone. Every other Request-shaped
+portal has its own leading arguments, so a caller states them, as `signature`
+and `args` together; the [eyedropper](eyedropper.md)'s `PickColor`, which has
+no title, is the worked example:
+
+```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 is where `handle_token`
+rides, so 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:
+`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.
+
+`portalVersion(iface)` answers the question `hasService()` cannot: whether the
+portal's backends provide one _interface_, and at what version — `0` when it
+is not there at all. Capability lives in the interface's own `version`
+property, and gating on the service alone breaks exactly on the desktops that
+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.