react-x11 2.52.0 → 2.53.0

package/docs/notifications.md

@@ -23,12 +23,11 @@ function Exporter() {
 }
 ```
 
-An in-app toast is deliberately **not** this. That is layout, and it belongs
-to whoever wants it; this page is about the desktop's own banners.
+An in-app toast is **not** this; this page is about the desktop's own banners.
 
 ## The ladder
 
-The [file dialog](filedialog.md)'s shape again, four rungs:
+Like the [file dialog](filedialog.md)'s, four rungs, chosen for you:
 
 |     |                                       |                                                                                                                                                                                                                                                                                                                  |
 | --- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -42,10 +41,6 @@ posting anything. Where none answers, `notify()` rejects with a **typed**
 `NoNotificationServiceError` — the signal to fall back to your own UI, not a
 crash — and `useNotifier().available` is that branch as render state.
 
-The top rung is never chosen by naming a backend: `notify()` asks the
-connection the tree renders through whether it has a centre, and whether that
-centre can deliver.
-
 ## `notify()` and the handle
 
 ```ts
@@ -63,12 +58,11 @@ await banner.update({ body });    // in place, where the rung can
 await banner.close();             // take it down, where the rung can
 ```
 
-**The daemon's vocabulary is the API's.** `urgency` is
+**The vocabulary is freedesktop's on every rung.** `urgency` is
 `low | normal | critical`, an action is `{ key, label }`, a click on the
 banner itself is the action keyed `'default'`, and a banner that went away
-reports `'expired' | 'dismissed' | 'closed' | 'unknown'` — the freedesktop
-words, because it is a published protocol with many daemons and this is one
-of many clients. The cocoa rung translates into them.
+reports `'expired' | 'dismissed' | 'closed' | 'unknown'`. The cocoa rung
+translates into them.
 
 **Attribution is filled in for you.** On Linux the `desktop-entry` hint is
 the `appId` [`registerApplication()`](uri-schemes.md) established, which is
@@ -86,51 +80,41 @@ is nothing to pass.
 | `osascript`   | posts anew          | nothing | no                | nothing              |
 | `notify-send` | with an id, yes     | nothing | no                | nothing              |
 
-`win32` sits with the shell-out rungs on everything but where it is shown:
-a `Shell_NotifyIcon` balloon is a real toast in a real action centre, and
-also a fire-and-forget one. Buttons, replies and a lifetime the app controls
-want the Windows App SDK's notification manager, which will not show anything
-at all until the system knows an AppUserModelID for the process — a
-Start-menu shortcut carrying one, or a registry registration. That is a
-packaging question ([windows.md](windows.md) §"Packaging and identity"), and
-a balloon is what can be shown without asking the user to install anything.
-
-The shell-out rungs are the crude floor: they show a banner and know nothing
-afterwards. `handle.backend` says which rung answered, so an app that cares
+On `win32` the banner is a real toast in the action centre, but
+fire-and-forget: buttons, replies and update-in-place would need an
+AppUserModelID for the process, which is a packaging question
+([windows.md](windows.md) §"Packaging and identity").
+
+The shell-out rungs show a banner and know nothing afterwards. `handle.backend` says which rung answered, so an app that cares
 can say "open the app to see it" there rather than promise a button it
 cannot deliver.
 
-**Actions on the bus are gated by the daemon.** Whether it can show buttons
-is one of its `GetCapabilities`, and an app that sends actions to a daemon
-without `actions` has silently produced a notification nobody can act on —
-so they are dropped with a development warning rather than sent blind.
-Capabilities are read once per bus session.
+**Actions on the bus are gated by the daemon.** To a daemon that cannot show
+buttons (no `actions` in its `GetCapabilities`, read once per bus session)
+they are dropped with a development warning rather than sent blind.
 
 **A refusal is not fallen through.** On the cocoa backend the first post asks
-the system's authorization prompt, once per bundle. A user who declined the
-app's notifications has said something, and `notify()` rejects with the
-platform's error (`NotificationsDeniedError`) rather than posting through
-`osascript` by a side door.
-
-**A refusal is an answer; a prompt nobody saw is not.** The two look identical
-from the call — the authorization request comes back refused either way — so
-the rung reads the status again afterwards, because only a prompt moves it off
-`notDetermined`. A bundle macOS has not registered (an ad-hoc signature in a
-temp directory is the usual way to meet this) never gets the prompt, and
-reporting that as a denial would tell the user they declined something they
-were never shown. Nobody has turned anything off, so the ladder carries on to
-`osascript`; only `backend: 'cocoa'` turns it into an error, and that one says
-`notDetermined` rather than blaming the user.
-
-Which is why an app that counts progress should ask before it decides. `examples/notify.jsx` (`npm run examples:notify`) is a download manager built around exactly that: it posts one banner and updates it in place where the rung can, and on `osascript` or `notify-send` stays quiet and posts once at the end, because posting per step there would be four banners for one download.
+the system's authorization prompt, once per bundle. If the user declined,
+`notify()` rejects with `NotificationsDeniedError` rather than posting through
+`osascript`.
+
+**A prompt nobody saw is not a refusal.** A bundle macOS has not registered
+(typically an ad-hoc signature in a temp directory) never gets the prompt and
+stays `notDetermined`; the ladder then carries on to `osascript`. Only
+`backend: 'cocoa'` turns that into an error, and it says `notDetermined`
+rather than blaming the user.
+
+So an app that reports progress should check `handle.backend` before it
+decides how often to post. `examples/notify.jsx` (`npm run examples:notify`)
+updates one banner in place where the rung can, and on `osascript` or
+`notify-send` posts once at the end.
 
 ## The bundle, on macOS
 
 `UNUserNotificationCenter` attributes every banner to an app bundle — a
-`CFBundleIdentifier` Launch Services can see — and raises in a process that
-is none, which is what a bare `node` is. The bridge probes it once and
-reports `available: false`; `notify()` then takes the `osascript` rung, whose
-banners are Script Editor's. To get the real thing, run as a bundle: the
+`CFBundleIdentifier` Launch Services can see — so a bare `node` process gets
+`available: false` from the centre and `notify()` takes the `osascript` rung,
+whose banners are Script Editor's. To get the real thing, run as a bundle: the
 executable in `Name.app/Contents/MacOS/`, an `Info.plist` that names it and
 carries `CFBundleIdentifier`, and a signature
 (`codesign --force --sign - Name.app` is enough locally). See
@@ -162,3 +146,5 @@ call win.
 The bus rung holds one session-bus reference while any banner is live and
 releases it when the last one closes, so an app that closed its banners on
 the way out is free to exit.
+
+Design notes: [design/notifications.md](../design/notifications.md).