react-x11 1.2.0 → 2.0.0

package/src/appearancehooks.js

@@ -0,0 +1,96 @@
+// `useSystemAppearance()` — the desktop's appearance as something a component
+// re-renders on.
+//
+// The store lives in `appearance.js` and is process-global, because that is
+// what it describes: one desktop, one set of preferences, shared by every
+// root in the process the way the D-Bus connection under it is.
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+import {
+  appearanceSnapshot,
+  systemAppearance,
+  watchAppearance,
+} from './appearance.js';
+import { useAppOrNull } from './appcontext.js';
+
+/**
+ * Read the store, and start the ladder if `enabled`.
+ *
+ * The flag exists for `<ThemeProvider>`, which calls this on every render and
+ * must not open a D-Bus connection for an app that gave it a single palette
+ * and no `dark`. Hooks cannot be conditional, so the condition goes in here
+ * rather than into which hooks run.
+ */
+function useAppearance(enabled) {
+  const app = useAppOrNull();
+  const subscribe = useCallback(
+    (onChange) => {
+      if (!enabled) return () => {};
+      // Subscribe, *then* ask — the same ordering the portal rung uses
+      // internally, and for the same reason. React's own re-check after
+      // subscribing would cover a value that landed in between, but not a
+      // change that arrived and left.
+      const stop = watchAppearance(onChange);
+      systemAppearance({ app }).catch(() => {
+        // `systemAppearance` does not reject; this is belt and braces so a
+        // future rung cannot turn a desktop probe into an unhandled rejection
+      });
+      return stop;
+    },
+    [app, enabled],
+  );
+  // The same frozen object until something changes — `getSnapshot` returning
+  // a fresh `{ colorScheme, … }` per call is what makes React loop.
+  return useSyncExternalStore(
+    subscribe,
+    appearanceSnapshot,
+    appearanceSnapshot,
+  );
+}
+
+/** Not public: `<ThemeProvider>`'s seam, so following the desktop is opt-in. */
+export function useAppearanceWhen(enabled) {
+  return useAppearance(enabled);
+}
+
+/**
+ * What the desktop looks like, live.
+ *
+ * ```jsx
+ * const { colorScheme, accent, contrast, reducedMotion } = useSystemAppearance();
+ *
+ * <box style={{ backgroundColor: colorScheme === 'dark' ? '#1e1e1e' : 'white' }}>
+ *   <Button style={{ backgroundColor: accent ?? '#2980b9' }} label="Save" />
+ * </box>
+ * ```
+ *
+ * | | |
+ * | --- | --- |
+ * | `colorScheme` | `'light'`, `'dark'` or `'no-preference'` |
+ * | `accent` | `'#ed5b00'`, or **null** — most backends do not implement it |
+ * | `contrast` | `'normal'` or `'high'` |
+ * | `reducedMotion` | `true` when the user asked for less animation |
+ * | `source` | `'portal'`, `'xsettings'`, `'macos'`, `'cache'`, or null |
+ *
+ * **`'no-preference'` means use your own default**, not "use light". And
+ * `accent` is null far more often than not, so fall back to your own brand
+ * colour rather than to grey — an app that goes colourless on a desktop that
+ * simply did not answer the question looks broken.
+ *
+ * The **first** render is served from what this machine answered last time
+ * (`source: 'cache'`), so it starts in the right colours rather than in the
+ * defaults, and a real rung replaces it a frame or two later. An app that
+ * needs a verified answer before it draws anything at all — the first launch
+ * on a machine — waits for one:
+ *
+ * ```jsx
+ * const [root] = await Promise.all([createRoot(), systemAppearance()]);
+ * ```
+ *
+ * See `docs/appearance.md`, and `<ThemeProvider dark={…}>` for the case where
+ * all you want is for the app to follow the desktop.
+ */
+export function useSystemAppearance() {
+  return useAppearance(true);
+}

package/src/apphooks.js

@@ -0,0 +1,73 @@
+// The two inbound events, as rendering code sees them.
+//
+// Thin on purpose. `application.js` owns the bus, the buffer and the replay;
+// this is the lid that lets a component take a deep link without the app
+// author threading a callback down from the module scope where
+// `registerApplication()` had to be called.
+//
+// There is **nothing to wrap** — the registration is process-global, because
+// an application has one identity on the desktop — so these work in any tree,
+// including a component library's.
+
+import { useEffect, useRef } from 'react';
+
+import { onAppActivate, onAppOpen } from './application.js';
+
+/**
+ * Subscribe without re-subscribing when the handler identity changes.
+ *
+ * The subscription must be installed **once**, on mount: a launch that arrived
+ * before anything was listening is replayed to the first handler that
+ * attaches, and re-subscribing on every render would keep re-arming a drain
+ * that has already happened while doing nothing useful. The handler itself is
+ * read at call time, so a link that arrives three minutes from now runs the
+ * closure from the current render rather than the mounting one.
+ */
+function useLaunchSubscription(subscribe, handler) {
+  const live = useRef(handler);
+  live.current = handler;
+  useEffect(() => subscribe((...args) => live.current?.(...args)), [subscribe]);
+}
+
+/**
+ * The desktop handed this app URIs to open — a `myapp://` link clicked
+ * somewhere else, or a document opened from a file manager.
+ *
+ * ```jsx
+ * function App() {
+ *   const win = useRef(null);
+ *   useAppOpen((uris, ctx) => {
+ *     activateWindow(win, { timestamp: ctx.timestamp });
+ *     const code = new URL(uris[0]).searchParams.get('code');
+ *     finishLogin(code);
+ *   });
+ *   return <window ref={win}>…</window>;
+ * }
+ * ```
+ *
+ * Fires for links that arrived **before the tree mounted** too, which is the
+ * normal case when the bus started this process to deliver one: they are
+ * buffered and replayed to the first handler that attaches.
+ *
+ * `uris` is attacker-controlled input from an unauthenticated local peer —
+ * `Open` is callable by anything on the session bus. Validate before acting,
+ * and never treat a URI's path as a filesystem path. See docs/uri-schemes.md.
+ */
+export function useAppOpen(handler) {
+  useLaunchSubscription(onAppOpen, handler);
+}
+
+/**
+ * The desktop asked this app to come forward with nothing to open — the user
+ * launched it again from the panel while it was already running.
+ *
+ * ```jsx
+ * useAppActivate((ctx) => activateWindow(win, { timestamp: ctx.timestamp }));
+ * ```
+ *
+ * Nothing is raised for you: an app that answers a second launch by opening a
+ * new document should not have to undo a raise first.
+ */
+export function useAppActivate(handler) {
+  useLaunchSubscription(onAppActivate, handler);
+}