react-x11 1.2.0 → 2.0.0

package/src/acceleratorhooks.js

@@ -0,0 +1,86 @@
+// The React lid on `accelerators.js`: `useAccelerator`, and the internal
+// registration the menus are built on.
+//
+// Split from the matcher for the reason `fonthooks.js` is split from
+// `fonts.js` — the half that has to be right about X11 and the half that has
+// to be right about React have different failure modes, and only one of them
+// can be tested without a tree.
+
+import { useEffect, useMemo, useRef } from 'react';
+
+import { matchesShortcut } from './accelerators.js';
+import { useTopLevelWindow } from './windowid.js';
+
+/**
+ * Bind a chord for as long as this component is mounted, anchored at
+ * `anchorRef` — the node the binding belongs to, which is what decides
+ * whether it is on the screen and whether a modal has taken the keyboard
+ * from it (`EventManager._runAccelerators`).
+ *
+ * `handle(ev)` returns whether it took the key.
+ *
+ * The handler is read from a ref rather than captured, and is deliberately
+ * *not* a dependency: a chord pressed three minutes from now must run the
+ * handler from the current render, and re-registering on every render would
+ * also reorder the bindings under it.
+ */
+export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
+  const live = useRef(handle);
+  live.current = handle;
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const manager = anchorRef.current?.root?.events;
+    if (!manager) return undefined;
+    return manager.registerAccelerator({
+      anchor: () => anchorRef.current ?? null,
+      handle: (ev) => live.current?.(ev) ?? false,
+    });
+  }, [anchorRef, enabled]);
+}
+
+/**
+ * `useAccelerator([['Control', 'K']], () => openPalette())` — a shortcut that
+ * is not in a menu.
+ *
+ * Same chord vocabulary as a menu item's `shortcut` and the same matching, so
+ * a shortcut can be moved into or out of a menu without being rewritten, and
+ * the same rules apply to it: exact on Control/Alt/Shift/Super, indifferent
+ * to Caps Lock and Num Lock, matched against the Latin keysym so it survives
+ * a layout switch, and behind whatever a focused element consumed with
+ * `preventDefault()`.
+ *
+ * The handler is called with the key event, and the key is consumed.
+ *
+ * By default the binding belongs to the window the component is in, which is
+ * what an application-wide shortcut wants. Two options for when it is not:
+ * `enabled: false` unbinds it without unmounting anything, and `scope` takes
+ * a ref to a node the binding hangs off instead — the way to give a modal
+ * `<Dialog>` a shortcut of its own, since a binding on the window behind it
+ * is one the modal has taken the keyboard from.
+ */
+export function useAccelerator(shortcut, handler, options = {}) {
+  const { enabled = true, scope } = options;
+  const owner = useTopLevelWindow();
+  // `useTopLevelWindow` answers when it is read, so the fallback stays a
+  // live getter rather than a node captured on the render that mounted.
+  const anchorRef = useMemo(
+    () =>
+      scope ?? {
+        get current() {
+          return owner.current;
+        },
+      },
+    [scope, owner],
+  );
+  const live = useRef({ shortcut, handler });
+  live.current = { shortcut, handler };
+  useAcceleratorEntry(
+    anchorRef,
+    (ev) => {
+      if (!matchesShortcut(ev, live.current.shortcut)) return false;
+      live.current.handler?.(ev);
+      return true;
+    },
+    enabled,
+  );
+}

package/src/accelerators.js

@@ -0,0 +1,128 @@
+// Accelerators: the half of a menu `shortcut` that was only ever drawn (#351).
+//
+// A `MenuBar` measured its items' shortcuts, drew them, announced them as
+// `aria-keyshortcuts` and handed them to the panel as dbusmenu's `aas` — and
+// bound none of them. An app wrote the binding a second time in an
+// `onKeyDown`, so the promise on the screen and the behaviour behind it were
+// two pieces of state that drifted.
+//
+// This is the matching half, and it is pure: an event and a chord in, a
+// boolean out. The registry and the dispatch order live in `events.js`, next
+// to the key path they are part of; the React lid is `acceleratorhooks.js`.
+//
+// ## Which keysym a chord is compared against
+//
+// `ev.keysym` — the **Latin** keysym for the physical key, whatever layout is
+// live (`src/keyboard.js`, docs/events.md). That is what makes Ctrl+S keep
+// saving while the user types Russian, and it is the reason this module has
+// nothing to say about layouts at all.
+//
+// ## Exact on the four modifiers, indifferent to the locks
+//
+// Ctrl+S must not fire on Ctrl+Shift+S, and must still fire with Caps Lock or
+// Num Lock on. Both fall out of comparing `ctrlKey`/`altKey`/`shiftKey`/
+// `metaKey`, which are the four named modifier bits and nothing else: Lock is
+// bit 1 and Num Lock is normally Mod2, so neither is in the comparison to
+// begin with. This is the line every hand-rolled binding gets wrong, which is
+// most of why it is here rather than in an application.
+
+import {
+  isEnabled,
+  isSeparator,
+  splitChord,
+  visibleItems,
+} from './menuitem.js';
+import { keysymFromName } from './keysyms.js';
+
+/** ASCII upper case folded down, so `'S'` and `'s'` are the same key. */
+const fold = (keysym) =>
+  keysym >= 0x41 && keysym <= 0x5a ? keysym + 0x20 : keysym;
+
+const isLetter = (keysym) => fold(keysym) >= 0x61 && fold(keysym) <= 0x7a;
+
+/** The keysym one chord ends on, or `undefined` for one nothing can match. */
+export function chordKeysym(chord) {
+  const { key } = splitChord(chord);
+  return key == null ? undefined : keysymFromName(key);
+}
+
+/**
+ * Does this key event *press* `chord` — `['Control', 'S']`?
+ *
+ * Two ways a chord's key can be recognised, and the second exists for the
+ * symbols:
+ *
+ * - **as the key it names.** `ev.keysym` is the Latin keysym for the physical
+ *   key, case-folded here because dbusmenu carries the key and not the
+ *   character it types, so `['Control', 's']` and `['Control', 'S']` are one
+ *   binding. All four modifiers are compared exactly.
+ * - **as the character it typed.** `['Control', 'plus']` is a real shortcut
+ *   that no US keyboard can press without Shift — `+` is the shifted `=` — so
+ *   comparing the base keysym alone would draw `Ctrl++` and never fire it.
+ *   Where the chord names a symbol, the character the key actually produced
+ *   counts too, and Shift is then whatever it took to produce it rather than
+ *   a modifier of its own. GTK reaches the same answer through XKB's consumed
+ *   modifiers; this is that rule with the part we cannot ask the server for
+ *   left out.
+ *
+ * The second path is **letters excluded** deliberately: it is exactly what
+ * would make Ctrl+Shift+S fire a Ctrl+S binding, which is the thing the
+ * modifier comparison is here to prevent.
+ */
+export function matchesChord(ev, chord) {
+  const { modifiers, key } = splitChord(chord);
+  if (key == null) return false;
+  const wanted = keysymFromName(key);
+  if (wanted === undefined) return false;
+
+  const ctrl = modifiers.has('Control');
+  const alt = modifiers.has('Alt');
+  const shift = modifiers.has('Shift');
+  const meta = modifiers.has('Super');
+  if (
+    Boolean(ev?.ctrlKey) !== ctrl ||
+    Boolean(ev?.altKey) !== alt ||
+    Boolean(ev?.metaKey) !== meta
+  ) {
+    return false;
+  }
+
+  const pressed = ev?.keysym;
+  if (typeof pressed === 'number' && fold(pressed) === fold(wanted)) {
+    return Boolean(ev?.shiftKey) === shift;
+  }
+  if (isLetter(wanted)) return false;
+  // The character this key typed, which is where a Shift the layout needed
+  // has already been spent — so a chord that did not ask for Shift does not
+  // mind one here, and one that did still gets it.
+  return (!shift || Boolean(ev?.shiftKey)) && ev?.codepoint === wanted;
+}
+
+/** Does this key event press any alternative of an `aas` shortcut? */
+export function matchesShortcut(ev, shortcut) {
+  if (!Array.isArray(shortcut)) return false;
+  return shortcut.some(
+    (chord) => Array.isArray(chord) && matchesChord(ev, chord),
+  );
+}
+
+/**
+ * The item in a menu descriptor whose shortcut this key event presses, or
+ * `null` — submenus included, since a shortcut is a way to reach a command
+ * *without* opening the menu it lives in.
+ *
+ * `enabled` and `visible` gate the search rather than the result, and they
+ * gate a parent's children with it: an item nobody can reach by opening the
+ * menu is not one a chord should reach either. A gated item is skipped and
+ * the walk goes on, so a disabled "Save" does not also swallow the key from
+ * whatever else claims it.
+ */
+export function acceleratedItem(items, ev) {
+  for (const item of visibleItems(items)) {
+    if (isSeparator(item) || !isEnabled(item)) continue;
+    if (matchesShortcut(ev, item.shortcut)) return item;
+    const inner = acceleratedItem(item.items, ev);
+    if (inner) return inner;
+  }
+  return null;
+}

package/src/activate.js

@@ -0,0 +1,168 @@
+// The raise: asking the window manager to bring one of this app's windows to
+// the front, with the timestamp that makes the request legitimate.
+//
+// This is the half of the deep-link story that decides whether a user calls
+// the feature working. The failure mode is not an exception — it is that the
+// user finishes logging in, the browser redirects, the app receives the code
+// correctly, sends `_NET_ACTIVE_WINDOW` with `CurrentTime` because nobody
+// parsed the launch timestamp, the WM's focus-stealing prevention declines,
+// and the taskbar entry blinks. Every layer reports success.
+//
+// So the timestamp is a first-class parameter here rather than an
+// implementation detail, and its default is the value EWMH itself names:
+//
+// > `data.l[1]` — "Client's last user activity timestamp … at the time of the
+// > request"
+//
+// which is exactly what `inputtime.js` already stashes off the event stream.
+// A launch context has something better — the timestamp of the click in the
+// *browser* that redirected here — and that is what a caller passes in.
+//
+// EWMH is explicit that the window manager may refuse, and that its fallback
+// is `_NET_WM_STATE_DEMANDS_ATTENTION`. That is its call, so this reports what
+// was **sent**, never what happened.
+//
+// See docs/uri-schemes.md. Issue #173.
+
+import { lastInputTime } from './inputtime.js';
+import { liveApps } from './trace-registry.js';
+import { topLevelWindows, windowIdOf } from './windowid.js';
+
+const ACTIVE_WINDOW = '_NET_ACTIVE_WINDOW';
+
+/** `1` is an application asking; `2` is a pager, which we are not. */
+const SOURCE_APPLICATION = 1;
+
+let warnedAboutAmbiguity = false;
+
+/** A ref object → what it holds. Anything else passes through. */
+function deref(target) {
+  if (target && typeof target === 'object' && 'current' in target) {
+    return target.isWindow ? target : target.current;
+  }
+  return target;
+}
+
+/**
+ * The ntk window behind a node, a ref or an ntk window. Recognised by having
+ * both an id and a connection, which is the pair this file needs anyway.
+ */
+function ntkWindowOf(node) {
+  if (!node || typeof node !== 'object') return null;
+  if (typeof node.id === 'number' && node.X) return node;
+  if (node.window?.X) return node.window;
+  if (node.root?.window?.X) return node.root.window;
+  return null;
+}
+
+/**
+ * The connection to send through, when the caller named a window that does not
+ * carry one — a raw XID, or nothing at all.
+ *
+ * One process usually has exactly one. Several is legal (a root per display,
+ * and a borrowed connection stays registered after its root unmounts), so the
+ * tie-break is which of them currently has a window: raising is about a window
+ * on screen, and a connection with none cannot be the one meant. Still
+ * ambiguous after that is a real `null` — an XID means nothing without the
+ * server that issued it.
+ */
+function soleApp() {
+  const apps = liveApps();
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((app) => topLevelWindows(app).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
+/**
+ * Which of this app's windows to raise when the caller did not say.
+ *
+ * The same inference `useTopLevelWindow()` makes, for the same reason: one
+ * top-level window is exact, and the focused one is right when there are
+ * several, because it is the window the user was last in.
+ */
+function inferWindow(app) {
+  const windows = topLevelWindows(app);
+  if (windows.length <= 1) return windows[0] ?? null;
+  const focused = windows.filter((w) => w.events?.windowFocused);
+  if (focused.length === 1) return focused[0];
+  if (process.env.NODE_ENV !== 'production' && !warnedAboutAmbiguity) {
+    warnedAboutAmbiguity = true;
+    console.warn(
+      `react-x11: activateWindow() with no window to raise, and this tree ` +
+        `has ${windows.length} top-level windows with none uniquely ` +
+        'focused — raising the most recently opened. Name the window to be ' +
+        'exact:\n' +
+        '  const win = useRef(null);\n' +
+        '  activateWindow(win, { timestamp });\n' +
+        '  return <window ref={win}>…</window>;',
+    );
+  }
+  return windows[windows.length - 1];
+}
+
+/** This app's currently active toplevel, for EWMH's `data.l[2]`. */
+function currentActive(app) {
+  const focused = topLevelWindows(app).filter((w) => w.events?.windowFocused);
+  return focused.length === 1 ? (windowIdOf(focused[0]) ?? 0) : 0;
+}
+
+/**
+ * Ask the window manager to raise and focus a window.
+ *
+ * ```jsx
+ * useAppOpen((uris, ctx) => {
+ *   activateWindow(win, { timestamp: ctx.timestamp });
+ *   route(uris[0]);
+ * });
+ * ```
+ *
+ * `target` is anything {@link windowIdOf} accepts — a `<window>` ref, a ref to
+ * any node inside it, a live ntk window, a raw XID — or nothing, in which case
+ * this app's only top-level window is used (its focused one, when it has
+ * several).
+ *
+ * `timestamp` is the X server time of the user action being answered.
+ * **Getting this wrong is the whole failure mode of the feature**, so:
+ *
+ * - omitted — the last input this app saw, which is EWMH's own definition of
+ *   the field;
+ * - a number — the launch context's timestamp, which is what a deep link
+ *   should pass: the click in the browser is the user action, not whatever
+ *   this app last saw;
+ * - `null` — `CurrentTime`. Legal, and most window managers will decline it.
+ *
+ * Returns whether the request was **issued**: `false` means there was no
+ * window or no connection to send it through. `true` is not a promise that the
+ * window came forward — EWMH lets the WM refuse and set
+ * `_NET_WM_STATE_DEMANDS_ATTENTION` instead, which is the blinking taskbar
+ * entry, and no client can tell the difference from here.
+ */
+export function activateWindow(target, { timestamp, source } = {}) {
+  const node = deref(target);
+  const wnd = ntkWindowOf(node);
+  const app = node?.app ?? node?.root?.app ?? wnd?.app ?? soleApp();
+
+  const chosen = wnd ?? (windowIdOf(node) === null ? inferWindow(app) : null);
+  const xid = windowIdOf(chosen) ?? windowIdOf(node);
+  const X = ntkWindowOf(chosen)?.X ?? wnd?.X ?? app?.X;
+  const root = X?.display?.screen?.[0]?.root;
+
+  if (!xid || !root || !X.SendClientMessage || !X.InternAtom) return false;
+
+  const when =
+    timestamp === undefined ? (lastInputTime(app) ?? 0) : (timestamp ?? 0);
+
+  X.InternAtom(false, ACTIVE_WINDOW, (err, atom) => {
+    if (err || !atom) return;
+    // The message goes to the **root** and is *about* our window, which is why
+    // both are arguments. The default event mask is
+    // SubstructureRedirect|SubstructureNotify — what EWMH requires for
+    // messages sent to the root — so it is deliberately not passed.
+    X.SendClientMessage(root, xid, atom, 32, [
+      source ?? SOURCE_APPLICATION,
+      when >>> 0,
+      currentActive(app),
+    ]);
+  });
+  return true;
+}