react-x11 2.6.1 → 2.8.0

package/src/palette.js

@@ -9,11 +9,12 @@
 //
 // **The default follows the desktop.** A react-x11 app that says nothing
 // about colour is dark on a dark desktop and light on a light one, the way a
-// GTK or Qt app is; `<ThemeProvider>` and `colorScheme` are how an app that
-// wants otherwise says so. See docs/appearance.md.
+// GTK or Qt app is, and its accent is the desktop's where the desktop has
+// one; `<ThemeProvider>` and `colorScheme` are how an app that wants
+// otherwise says so. See docs/appearance.md.
 
 import { appearanceSnapshot } from './appearance.js';
-import { readableInk, stepBeyond } from './styles.js';
+import { readableInk, stepBeyond, tint } from './styles.js';
 
 /**
  * The language subtags written right-to-left — CLDR's set, by the language
@@ -171,6 +172,17 @@ export const DefaultTheme = {
   focusRing: '#2980b9',
   focusRingWidth: 2,
   focusRingOffset: 1,
+  // The highlight behind selected text. A *tint* rather than an opaque
+  // fill, so the ink keeps its own contrast on both palettes; derived from
+  // `accent` for any palette that moves the accent and not this. A desktop
+  // that names one (macOS's Highlight colour) gives an opaque fill here.
+  selection: tint('#2980b9', 0.35),
+  // The insertion caret. `null` is the text's own colour, which is what a
+  // caret is unless the desktop says otherwise — macOS draws it in the
+  // Highlight colour's accent.
+  caret: null,
+  // Ink for a link. Not the accent: a link is blue everywhere, as a note is.
+  link: '#1c6ea4',
   // shape
   radius: 4,
   radiusSmall: 3,
@@ -268,6 +280,9 @@ const TEXT_FROM = {
   infoText: 'info',
 };
 
+// The selection tint follows the accent it is a tint of.
+const TINT_FROM = { selection: ['accent', 0.35] };
+
 // And the same for the floating-surface radii, which are a function of the
 // text they wrap: a palette that sets `fontSize` and nothing else still gets
 // menus in proportion to it.
@@ -323,6 +338,11 @@ export function resolveTheme(value, base = DefaultTheme) {
       continue;
     merged[token] = readableInk(merged[fill], [merged.text, merged.background]);
   }
+  for (const [token, [fill, alpha]] of Object.entries(TINT_FROM)) {
+    if (named[token] == null && named[fill] != null) {
+      merged[token] = tint(merged[fill], alpha);
+    }
+  }
   if (named.fontSize != null) {
     for (const [token, from] of Object.entries(RADIUS_FROM_FONT)) {
       if (named[token] == null) merged[token] = from(merged.fontSize);
@@ -377,18 +397,134 @@ export const DarkTheme = resolveTheme({
   hoverText: 'white',
   borderFocus: '#5aa4e6',
   focusRing: '#5aa4e6',
+  link: '#5aa4e6',
 });
 
+/**
+ * `#rrggbb` moved `amount` of the way toward `toward`. The one colour
+ * operation the desktop palette needs, on the one shape the ladder
+ * guarantees an accent has (`sanitize`, `accentFromPortal`).
+ */
+function mixHex(hex, toward, amount) {
+  const channel = (c, i) => parseInt(c.slice(1 + 2 * i, 3 + 2 * i), 16);
+  return (
+    '#' +
+    [0, 1, 2]
+      .map((i) => {
+        const a = channel(hex, i);
+        const b = channel(toward, i);
+        return Math.round(a + (b - a) * amount)
+          .toString(16)
+          .padStart(2, '0');
+      })
+      .join('')
+  );
+}
+
+/**
+ * The built-in palette with the desktop's accent on it.
+ *
+ * Only the accent family moves — `accent`, its hover, the menu-row highlight
+ * (the desktop's own selection shade where it names one: on macOS that is a
+ * darker cut of the accent, and a row lit in the raw accent beside a native
+ * menu reads as too bright; the accent itself otherwise, as in both built-in
+ * palettes), and the focus ring —
+ * and the steps are taken the way each palette takes them: the hover sinks
+ * into a light ground and lifts off a dark one, and `resolveTheme` derives
+ * the press from the pair. `info` stays its own blue, as it does under a
+ * theme with a green accent: a note looks like a note everywhere.
+ *
+ * The ink is the desktop's where the desktop named one — AppKit writes white
+ * on every accent a Mac offers, including the ones a contrast ratio would
+ * put dark letters on, and the point of following the desktop is to look
+ * like the controls beside ours. Where the source has no ink (the portal)
+ * `resolveTheme` picks the legible one, as it does for any theme that names
+ * a fill and stops there.
+ */
+function withDesktopAccent(scheme, accent, ink, selection) {
+  const dark = scheme.scheme === 'dark';
+  const accentHover = dark
+    ? mixHex(accent, '#ffffff', 0.2)
+    : mixHex(accent, '#000000', 0.22);
+  const focus = dark ? accentHover : accent;
+  const value = {
+    accent,
+    accentHover,
+    hoverBackground: selection ?? accent,
+    borderFocus: focus,
+    focusRing: focus,
+  };
+  if (ink) {
+    value.accentText = ink;
+    value.hoverText = ink;
+  }
+  return resolveTheme(value, scheme);
+}
+
+// A desktop that names its whole palette (macOS, through the semantic
+// colours AppKit paints with) is merged over the scheme's built-in one the
+// way a `<ThemeProvider>` value is: every colour it named, and the shape
+// tokens, the derived inks and the pressed steps from `resolveTheme`. Keyed
+// on the palette object itself — the store replaces it, never mutates it.
+const desktopPalettesByObject = new WeakMap();
+function withDesktopPalette(scheme, palette) {
+  let byScheme = desktopPalettesByObject.get(palette);
+  if (!byScheme) {
+    byScheme = new Map();
+    desktopPalettesByObject.set(palette, byScheme);
+  }
+  let resolved = byScheme.get(scheme);
+  if (!resolved) {
+    resolved = resolveTheme(palette, scheme);
+    byScheme.set(scheme, resolved);
+  }
+  return resolved;
+}
+
+// One palette per desktop answer, so the unprovided palette keeps the
+// identity `useTheme()` and the `$token` resolution cache both count on: a
+// fresh object per read would re-resolve every token in the tree on every
+// paint. Bounded because a desktop's accent changes a handful of times in the
+// life of a process, never per frame.
+const desktopPalettes = new Map();
+
+/**
+ * The built-in palette for a desktop that looks like `appearance` — the
+ * scheme's own, with the desktop's accent on it where the desktop named one.
+ *
+ * **The default follows the accent as well as the scheme.** An app that says
+ * nothing about colour is asking to look like it belongs on this desktop, and
+ * on the one that reports an accent every native control beside it is already
+ * that colour — the Cocoa backend draws its bezels with AppKit, so the app's
+ * own checkbox is orange while its `<Tabs>` indicator stayed blue. An app
+ * with a brand names `accent` in its `<ThemeProvider>` and keeps it; a pinned
+ * `colorScheme` follows nothing, the accent included.
+ *
+ * `'no-preference'` means *use your own default*, which is the light one.
+ */
+export function paletteFor(appearance) {
+  const scheme = appearance.colorScheme === 'dark' ? DarkTheme : DefaultTheme;
+  if (appearance.palette) return withDesktopPalette(scheme, appearance.palette);
+  const { accent, accentText, selection } = appearance;
+  if (!accent) return scheme;
+  const key = `${scheme.scheme} ${accent} ${accentText ?? ''} ${selection ?? ''}`;
+  let palette = desktopPalettes.get(key);
+  if (!palette) {
+    if (desktopPalettes.size >= 8) desktopPalettes.clear();
+    palette = withDesktopAccent(scheme, accent, accentText, selection);
+    desktopPalettes.set(key, palette);
+  }
+  return palette;
+}
+
 /**
  * The palette in force where nothing has been said — which is to say, the
  * desktop's.
  *
  * Read synchronously and cheaply: `appearanceSnapshot()` is a frozen object
- * seeded from disk before the first render, so this is a property lookup and
- * a comparison, and it is called from the paint path.
- *
- * `'no-preference'` means *use your own default*, which is the light one.
+ * seeded from disk before the first render, so this is a property lookup, a
+ * comparison and a map hit, and it is called from the paint path.
  */
 export function baseTheme() {
-  return appearanceSnapshot().colorScheme === 'dark' ? DarkTheme : DefaultTheme;
+  return paletteFor(appearanceSnapshot());
 }

package/src/permissionhooks.js

@@ -0,0 +1,89 @@
+// `usePermission()` — a permission as a component sees it: the status as
+// render state, a request that updates it, and whether this backend can
+// answer at all.
+//
+// The bare functions in `permissions.js` are complete; what a component
+// wants on top is binding — the tree's connection, the status re-read after
+// a request — not another rung. There is no change notification behind a
+// status on any platform, so the status is what was last read: on mount,
+// and after each `request()`. An app that wants it fresher re-reads with
+// `refresh()` on its own cue (a window coming back to the front, say).
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import {
+  openPrivacySettings,
+  permissionBackend,
+  permissionStatus,
+  requestPermission,
+} from './permissions.js';
+
+/**
+ * ```jsx
+ * const camera = usePermission('camera');
+ *
+ * {camera.available && camera.status !== 'granted' && (
+ *   <Button
+ *     label={camera.status === 'prompt' ? 'Allow camera' : 'Open Settings'}
+ *     onPress={() =>
+ *       camera.status === 'prompt' ? camera.request() : camera.openSettings()
+ *     }
+ *   />
+ * )}
+ * ```
+ *
+ * `status` starts `'unknown'` and settles once read. `request()` resolves
+ * with the status after the user answered and updates `status` with it;
+ * while one is in flight a second call returns the same promise.
+ * `available` is whether this backend has an authorization API — false on
+ * X11 today — and the honest branch to keep a feature behind.
+ */
+export function usePermission(kind, options = {}) {
+  const app = useAppOrNull();
+  const target = options.target;
+  const available = permissionBackend({ app }) !== null;
+  const [status, setStatus] = useState('unknown');
+  const inflight = useRef(null);
+
+  const refresh = useCallback(async () => {
+    const next = await permissionStatus(kind, { app, target });
+    setStatus(next);
+    return next;
+  }, [kind, app, target]);
+
+  useEffect(() => {
+    let alive = true;
+    permissionStatus(kind, { app, target }).then(
+      (next) => alive && setStatus(next),
+      () => alive && setStatus('unknown'),
+    );
+    return () => {
+      alive = false;
+    };
+  }, [kind, app, target]);
+
+  const request = useCallback(() => {
+    if (inflight.current) return inflight.current;
+    const run = requestPermission(kind, { app, target })
+      .then((next) => {
+        setStatus(next);
+        return next;
+      })
+      .finally(() => {
+        inflight.current = null;
+      });
+    inflight.current = run;
+    return run;
+  }, [kind, app, target]);
+
+  const openSettings = useCallback(
+    () => openPrivacySettings(kind, { app }),
+    [kind, app],
+  );
+
+  return useMemo(
+    () => ({ status, available, request, refresh, openSettings }),
+    [status, available, request, refresh, openSettings],
+  );
+}

package/src/permissions.js

@@ -0,0 +1,196 @@
+// Permissions: may this app use the camera, the microphone, the screen, the
+// accessibility APIs — and how does it ask?
+//
+// The file dialog's ladder again (docs/filedialog.md), with one rung that
+// answers and one that only points:
+//
+//   1. **the platform's own authorization** — the cocoa backend, where the
+//      bridge reads macOS's privacy (TCC) status per kind and raises the
+//      system prompt where a framework offers one (src/cocoa/permissions.js).
+//      Found by the app the tree renders through carrying `permissions`,
+//      never by naming a backend here.
+//   2. **the Settings pane** — `open x-apple.systempreferences:…` on a Mac
+//      with no bridge (the X11 backend under XQuartz). It cannot read a
+//      status or raise a prompt; it can put the user in front of the switch,
+//      which is what `openPrivacySettings` promises and no more.
+//
+// On Linux nothing answers yet. The freedesktop counterparts are the
+// per-device portals (`org.freedesktop.portal.Camera`, `.Location`), which
+// need no bridge and are react-x11#466's remaining half; until then a
+// status query says `'unknown'` and a request rejects with a **typed**
+// error, the `NoFileDialogError` rule — a signal to keep the feature behind
+// the answer, not a crash.
+//
+// ## Two things the vocabulary decides
+//
+// - A status is one of five words. `'granted'`, `'denied'` and
+//   `'restricted'` (MDM or parental controls: the user cannot grant it) are
+//   the platform's; `'prompt'` is "not decided yet — a request would ask";
+//   `'unknown'` is "nothing here can say", which is a fact about the machine
+//   rather than about the permission, and the reason a query never throws.
+// - A request answers with the status **after** the user has, never with a
+//   bare boolean, because `'restricted'` and `'denied'` want different UI —
+//   one is a Settings switch the user can flip, the other is not.
+
+import { liveApps } from './trace-registry.js';
+
+/** The kinds a status can be asked for. `automation` wants `{ target }`. */
+export const PERMISSION_KINDS = Object.freeze([
+  'camera',
+  'microphone',
+  'screen-recording',
+  'accessibility',
+  'input-monitoring',
+  'automation',
+  'location',
+]);
+
+/** The Settings panes, the kinds above plus the two that have no API at all
+ *  because reading the folder *is* the prompt. */
+const SETTINGS_PANES = Object.freeze({
+  camera: 'Privacy_Camera',
+  microphone: 'Privacy_Microphone',
+  'screen-recording': 'Privacy_ScreenCapture',
+  accessibility: 'Privacy_Accessibility',
+  'input-monitoring': 'Privacy_ListenEvent',
+  automation: 'Privacy_Automation',
+  location: 'Privacy_LocationServices',
+  'files-and-folders': 'Privacy_FilesAndFolders',
+  'full-disk-access': 'Privacy_AllFiles',
+});
+
+/**
+ * Nothing on this machine can ask. A **typed** rejection, so a caller keeps
+ * the feature behind it rather than crashing — `usePermission().available`
+ * is that branch as render state.
+ */
+export class NoPermissionServiceError extends Error {
+  constructor(kind, cause) {
+    super(
+      `react-x11: nothing here can ask for the ${kind} permission — this ` +
+        'backend has no authorization API (the cocoa backend has; the ' +
+        'freedesktop device portals are not implemented yet). Read ' +
+        "permissionStatus() first: 'unknown' is this machine's answer.",
+      { cause },
+    );
+    this.name = 'NoPermissionServiceError';
+  }
+}
+
+function checkKind(kind) {
+  if (!PERMISSION_KINDS.includes(kind)) {
+    throw new TypeError(
+      `react-x11: ${JSON.stringify(kind)} is not a permission kind. ` +
+        `Expected one of ${PERMISSION_KINDS.join(', ')}.`,
+    );
+  }
+}
+
+/** The deep link into System Settings for a pane, or the Privacy pane. */
+export function privacySettingsUrl(kind) {
+  const pane = kind == null ? null : SETTINGS_PANES[kind];
+  if (kind != null && !pane) {
+    throw new TypeError(
+      `react-x11: ${JSON.stringify(kind)} is not a privacy pane. Expected ` +
+        `one of ${Object.keys(SETTINGS_PANES).join(', ')}.`,
+    );
+  }
+  return (
+    'x-apple.systempreferences:com.apple.preference.security' +
+    (pane ? `?${pane}` : '?Privacy')
+  );
+}
+
+/** The app whose authorization API to ask when the caller did not say. */
+function soleApp() {
+  const apps = liveApps();
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((app) => (app._rootChildren ?? []).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
+function serviceFor({ app } = {}) {
+  const target = app ?? soleApp();
+  return target?.permissions ?? null;
+}
+
+/**
+ * Which rung answers here, without asking anything: `'cocoa'` where the
+ * tree's backend has an authorization API, `null` where a status would be
+ * `'unknown'` and a request would reject. Synchronous — a capability, not
+ * a probe.
+ *
+ * @returns {'cocoa' | null}
+ */
+export function permissionBackend(options = {}) {
+  return serviceFor(options) ? 'cocoa' : null;
+}
+
+/**
+ * Whether this app may use `kind`, without prompting.
+ *
+ * ```js
+ * const status = await permissionStatus('camera');
+ * // 'granted' | 'denied' | 'restricted' | 'prompt' | 'unknown'
+ * ```
+ *
+ * Never rejects for anything about the machine: `'unknown'` is the answer
+ * where nothing can say. `automation` asks about one target app, by bundle
+ * id, and only a running one has an answer (`{ target }`).
+ */
+export async function permissionStatus(kind, options = {}) {
+  checkKind(kind);
+  const service = serviceFor(options);
+  if (!service) return 'unknown';
+  return service.status(kind, options);
+}
+
+/**
+ * Ask for `kind`, raising the system's prompt where the platform has one,
+ * and resolve with the status once the user has answered.
+ *
+ * ```js
+ * const status = await requestPermission('microphone');
+ * if (status === 'granted') startRecording();
+ * else if (status === 'denied') await openPrivacySettings('microphone');
+ * ```
+ *
+ * A status the user has already decided answers at once, without a prompt.
+ * Where the platform's only "prompt" is a dialog that sends the user to
+ * Settings (screen recording, accessibility) the request resolves as soon
+ * as that dialog is up, with the status as it stands — `'denied'` until the
+ * switch is flipped, and for screen recording a restart after it.
+ *
+ * Rejects with {@link NoPermissionServiceError} where nothing can ask —
+ * which `permissionStatus` foretells with `'unknown'`.
+ */
+export async function requestPermission(kind, options = {}) {
+  checkKind(kind);
+  const service = serviceFor(options);
+  if (!service) throw new NoPermissionServiceError(kind);
+  return service.request(kind, options);
+}
+
+/**
+ * Put the user in front of the switch: System Settings › Privacy & Security
+ * › `kind`, or the Privacy pane itself with no kind. The two panes with no
+ * API — `files-and-folders`, `full-disk-access` — are reachable here too.
+ *
+ * Through the bridge where there is one, and by `open` on any Mac
+ * otherwise, since a deep link needs no framework. Resolves to whether
+ * anything opened: `false` off macOS, where there is no such pane.
+ */
+export async function openPrivacySettings(kind, options = {}) {
+  const url = privacySettingsUrl(kind);
+  const service = serviceFor(options);
+  if (service) return service.openSettings(kind);
+  if (process.platform !== 'darwin') return false;
+  const { execFile } = await import('node:child_process');
+  return new Promise((resolve) => {
+    try {
+      execFile('open', [url], (error) => resolve(!error));
+    } catch {
+      resolve(false);
+    }
+  });
+}

package/src/style.d.ts

@@ -58,21 +58,27 @@ export function styleHasSizeQueries(style: StyleProperties): boolean;
 /** Does the style carry a `'@supports …'` block? Those are re-resolved when
  *  the server's answer changes, not when the window is laid out. */
 export function styleHasSupportsQueries(style: StyleProperties): boolean;
+/** Does the style carry a `'@container …'` block? Those are re-resolved after
+ *  a layout pass moved the container they ask about. */
+export function styleHasContainerQueries(style: StyleProperties): boolean;
 /** `resolveQueries` with only the size half — the shape this had before
  *  capability blocks existed. */
 export function resolveSizeQueries(
   style: StyleProperties,
   size: { width: number; height: number },
 ): StyleProperties;
-/** Merge every matching `@` block — size and capability alike — in
- *  declaration order. `supports` maps feature name to whether the window can
- *  actually do it; a missing map matches nothing, which is the safe way
- *  round. */
+/** Merge every matching `@` block — size, container and capability alike —
+ *  in declaration order. `supports` maps feature name to whether the window
+ *  can actually do it; `containers` maps a container name (`''` for the
+ *  unnamed query) to that container's size in the node's logical pixels. A
+ *  missing map, or a name it does not hold, matches nothing, which is the
+ *  safe way round. */
 export function resolveQueries(
   style: StyleProperties,
   context?: {
     size?: { width: number; height: number } | null;
     supports?: Record<string, boolean> | null;
+    containers?: Record<string, { width: number; height: number }> | null;
   },
 ): StyleProperties;
 

package/src/style.js

@@ -17,6 +17,7 @@ export {
   resolveTokens,
   styleHasSizeQueries,
   styleHasSupportsQueries,
+  styleHasContainerQueries,
   resolveSizeQueries,
   resolveQueries,
   interpolate,