react-x11 1.2.0 → 2.0.0

package/src/keyboardstate.js

@@ -0,0 +1,278 @@
+// Caps Lock, Num Lock, and which keyboard layout is live.
+//
+// The one thing an application cannot work out for itself. A key event
+// carries the modifier state at the moment it was pressed, so an app can see
+// that Caps Lock was on for *a key it received* — which is exactly no help in
+// the case that matters, a password field that wants to warn before the first
+// character is typed and while the field is merely focused.
+//
+// XKB answers both halves directly: `GetState` for the state now,
+// `StateNotify` for every change after that, including the ones that happen
+// while another window has the keyboard. There is no polling and no timer.
+//
+// ## Which bit is which lock
+//
+// Caps Lock is `LockMask`, fixed by the core protocol. **Num Lock is not
+// fixed by anything** — it is wherever the modifier map puts it, and that is
+// `Mod2` on every Linux and BSD desktop, on XQuartz, and in every toolkit
+// that hardcodes it (GTK reads the modmap; Qt hardcodes Mod2). Reading the
+// modifier map to be sure costs a round trip and a keysym search to arrive at
+// Mod2 in every real case, so this takes the convention — the same one
+// `MOD.Mod2` in `keysyms.js` already documents for Alt and Super.
+//
+// ## Where the layout names come from
+//
+// `GetState().group` is an *index*, 0 to 3, and says nothing about what is in
+// the group. The names live in `_XKB_RULES_NAMES` on the root window — the
+// property `setxkbmap` writes and `setxkbmap -query` reads back — as
+// NUL-separated rules, model, layouts, variants and options. So `us,ru` plus
+// group 1 is `'ru'`.
+//
+// XKB's own `GetNames(GroupNames)` is the other route and is not used here:
+// it answers atoms that have to be interned back one round trip each, and
+// what it returns is a description like `English (US)` where an indicator in
+// a status bar wants `us`.
+
+import { requireExtension } from './extensions.js';
+
+const sessions = new WeakMap();
+
+/** `1 << xkbType` for the two events this needs. */
+const NEW_KEYBOARD_NOTIFY = 1 << 0;
+const STATE_NOTIFY = 1 << 2;
+
+const XKB_USE_CORE_KBD = 0x100;
+const LOCK_MASK = 2; // MOD.Lock — Caps Lock, per the core protocol
+const MOD2_MASK = 16; // MOD.Mod2 — Num Lock, per universal convention
+const RULES_PROPERTY = '_XKB_RULES_NAMES';
+
+/**
+ * What is known before XKB has answered, and what stays true on a display
+ * without the extension.
+ *
+ * Every field is the "off" answer rather than a null, because every caller of
+ * this is drawing something: a Caps Lock warning that renders `null` as truthy
+ * is worse than one that is briefly absent, and it is absent for one frame.
+ * `layouts` being empty is what distinguishes "not known" from "no lock on".
+ */
+const UNKNOWN = Object.freeze({
+  capsLock: false,
+  numLock: false,
+  group: 0,
+  layout: null,
+  layouts: Object.freeze([]),
+});
+
+class KeyboardSession {
+  constructor(app) {
+    this.app = app;
+    this.snapshot = UNKNOWN;
+    this.listeners = new Set();
+    this.armed = false;
+    this.stopped = false;
+    this._handler = null;
+  }
+
+  publish(values) {
+    const next = { ...this.snapshot, ...values };
+    // `layout` is derived in one place so it cannot disagree with the group
+    // and the list it comes from — a group index past the end of a
+    // just-reconfigured list is null rather than undefined.
+    next.layout = next.layouts[next.group] ?? null;
+    const prev = this.snapshot;
+    if (
+      next.capsLock === prev.capsLock &&
+      next.numLock === prev.numLock &&
+      next.group === prev.group &&
+      next.layout === prev.layout &&
+      // by value: `readLayouts` builds a fresh array every time it runs, and
+      // it runs again on every keymap replacement, most of which change
+      // nothing about the list
+      next.layouts.length === prev.layouts.length &&
+      next.layouts.every((l, i) => l === prev.layouts[i])
+    ) {
+      return;
+    }
+    this.snapshot = Object.freeze(next);
+    for (const fn of [...this.listeners]) {
+      try {
+        fn();
+      } catch {
+        // one subscriber throwing must not take the others with it, nor the
+        // X event loop this runs on
+      }
+    }
+  }
+
+  stop() {
+    this.stopped = true;
+    if (this._handler && this.app?.X?.off) {
+      try {
+        this.app.X.off('event', this._handler);
+      } catch {
+        // an ntk old enough to hand back a client with no `off`
+      }
+    }
+    this._handler = null;
+    this.listeners.clear();
+  }
+}
+
+/**
+ * `_XKB_RULES_NAMES` → the configured layout codes.
+ *
+ * Five NUL-terminated strings — rules, model, layouts, variants, options —
+ * of which the third is `us,ru`. Pure, and exported for the test: the
+ * in-process X server has no XKB, so this is the part of the path that can
+ * be pinned without one.
+ *
+ * A trailing NUL leaves an empty final field, and a layout list can
+ * legitimately have an empty entry (`us,,ru` from a hand-edited config), so
+ * the split keeps position and drops only what is empty at the ends.
+ */
+export function layoutsFromRules(data) {
+  if (!data?.length) return [];
+  const fields = data.toString('latin1').split('\0');
+  const layouts = fields[2];
+  if (!layouts) return [];
+  const list = layouts.split(',').map((s) => s.trim());
+  while (list.length && !list[list.length - 1]) list.pop();
+  // `empty` is a real xkeyboard-config layout, and what it is defined as is a
+  // layout with no symbols in it — which is exactly what XQuartz writes here,
+  // because it synthesizes its keymap from macOS and has no XKB layout to
+  // name. Reporting it would put "EMPTY" in a status-bar indicator; an empty
+  // list is what "this display cannot say" already means everywhere else here.
+  return list.every((name) => name === 'empty') ? [] : list;
+}
+
+/** Caps and Num out of a locked-modifier mask. */
+export function locksFromMods(lockedMods) {
+  return {
+    capsLock: Boolean(lockedMods & LOCK_MASK),
+    numLock: Boolean(lockedMods & MOD2_MASK),
+  };
+}
+
+async function arm(session) {
+  if (session.armed) return;
+  session.armed = true;
+  const app = session.app;
+  const xkb = await requireExtension(app, 'xkb');
+  if (!xkb || session.stopped) return;
+
+  // Subscribe before reading. A lock toggled between the two would otherwise
+  // be lost for the life of the connection — the same ordering rule the
+  // appearance ladder and the clipboard watch both follow.
+  const handler = (ev) => {
+    if (session.stopped || ev.type !== xkb.firstEvent) return;
+    if (ev.xkbType === xkb.events.StateNotify) {
+      session.publish({ ...locksFromMods(ev.lockedMods), group: ev.group });
+      return;
+    }
+    // NewKeyboardNotify: the keymap itself was replaced, which is what
+    // `setxkbmap` does when the *set* of layouts changes rather than which
+    // one is active. Rare, and cheap to answer — one property read.
+    if (ev.xkbType === 0) readLayouts(session);
+  };
+  session._handler = handler;
+  app.X.on('event', handler);
+
+  try {
+    xkb.SelectEvents(
+      XKB_USE_CORE_KBD,
+      STATE_NOTIFY | NEW_KEYBOARD_NOTIFY,
+      0,
+      STATE_NOTIFY | NEW_KEYBOARD_NOTIFY,
+      0,
+      0,
+    );
+  } catch {
+    return;
+  }
+
+  readLayouts(session);
+
+  const state = await new Promise((resolve) => {
+    try {
+      xkb.GetState(XKB_USE_CORE_KBD, (err, value) =>
+        resolve(err ? null : value),
+      );
+    } catch {
+      resolve(null);
+    }
+  });
+  if (state && !session.stopped) {
+    session.publish({ ...locksFromMods(state.lockedMods), group: state.group });
+  }
+}
+
+async function readLayouts(session) {
+  const X = session.app.X;
+  const root = X.display?.screen?.[0]?.root;
+  if (root == null) return;
+  try {
+    const atom = await new Promise((resolve, reject) =>
+      X.InternAtom(false, RULES_PROPERTY, (err, value) =>
+        err ? reject(err) : resolve(value),
+      ),
+    );
+    const prop = await new Promise((resolve) =>
+      X.GetProperty(0, root, atom, 0, 0, 0x1fffffff, (err, value) =>
+        resolve(err ? null : value),
+      ),
+    );
+    if (session.stopped) return;
+    const layouts = layoutsFromRules(prop?.data);
+    if (layouts.length) session.publish({ layouts: Object.freeze(layouts) });
+  } catch {
+    // no rules property: a server configured by other means, or XQuartz,
+    // where the group index is all there is. `layouts` stays empty and
+    // `layout` stays null, which is what those say.
+  }
+}
+
+/** What is known right now. Not public — `useKeyboardState()` is. */
+export function keyboardStateSnapshot(app) {
+  return sessions.get(app)?.snapshot ?? UNKNOWN;
+}
+
+/** Subscribe to the lock and layout state changing. */
+export function watchKeyboardState(app, onChange) {
+  if (!app) return () => {};
+  let session = sessions.get(app);
+  if (!session) {
+    session = new KeyboardSession(app);
+    sessions.set(app, session);
+  }
+  arm(session).catch(() => {
+    // an extension that is not there is not an error
+  });
+  session.listeners.add(onChange);
+  return () => session.listeners.delete(onChange);
+}
+
+/** Tear down with the root that started it. */
+export function endKeyboardState(app) {
+  const session = sessions.get(app);
+  if (!session) return;
+  session.stop();
+  sessions.delete(app);
+}
+
+/**
+ * Test seam: state the keyboard without a server that has XKB. Marks the
+ * session armed, so nothing tries to reach the extension behind the value.
+ */
+export function setKeyboardStateForTests(app, values) {
+  let session = sessions.get(app);
+  if (!session) {
+    session = new KeyboardSession(app);
+    sessions.set(app, session);
+  }
+  session.armed = true;
+  session.publish({
+    ...values,
+    layouts: Object.freeze(values.layouts ?? UNKNOWN.layouts),
+  });
+  return session;
+}

package/src/keyboardstatehooks.js

@@ -0,0 +1,58 @@
+// `useKeyboardState()` — the locks and the active layout, as something a
+// component re-renders on.
+//
+// The store lives in `keyboardstate.js`, keyed by connection: there is one
+// keyboard per display, and its state is the same for every window on it.
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useApp } from './appcontext.js';
+import { keyboardStateSnapshot, watchKeyboardState } from './keyboardstate.js';
+
+/**
+ * The keyboard's locks and layout, live.
+ *
+ * ```jsx
+ * const { capsLock, layout } = useKeyboardState();
+ *
+ * <PasswordInput value={password} onChange={setPassword} />
+ * {capsLock && <text style={{ color: theme.warning }}>Caps Lock is on</text>}
+ * ```
+ *
+ * | | |
+ * | --- | --- |
+ * | `capsLock` `numLock` | on or off, **now** — not "was on for the last key" |
+ * | `group` | the active XKB group, `0`–`3` |
+ * | `layout` | that group's layout code, `'ru'` — or null |
+ * | `layouts` | every configured layout, `['us', 'ru']` — `[]` where unknown |
+ *
+ * The point of the first row is that it is true of the keyboard rather than
+ * of an event: a password field can warn about Caps Lock **before** the first
+ * character is typed, which is the only time the warning is worth anything.
+ * A key event's own modifier state cannot do that, because it needs a key.
+ *
+ * The second is for a status-bar indicator, and for the case that costs
+ * people real time — a password typed in the wrong script, which looks
+ * identical to a wrong password. `layout` is a code rather than a
+ * description (`'ru'`, not `'Russian'`) because that is what an indicator
+ * shows and what a lookup key wants; uppercase it for display.
+ *
+ * Everything here needs **XKB**, which Xorg and XQuartz both have. Where it
+ * is missing the locks read false and `layouts` is empty, and an app that
+ * renders a warning only when `capsLock` is true degrades to not warning.
+ * `layouts` is the field to check when the difference between "off" and "not
+ * known" matters.
+ *
+ * Nothing is asked of the server until a component calls this, and the change
+ * is delivered by `XkbStateNotify` — no polling, and it arrives even while
+ * another application has the keyboard.
+ */
+export function useKeyboardState() {
+  const app = useApp();
+  const subscribe = useCallback(
+    (onChange) => watchKeyboardState(app, onChange),
+    [app],
+  );
+  const snapshot = useCallback(() => keyboardStateSnapshot(app), [app]);
+  return useSyncExternalStore(subscribe, snapshot, snapshot);
+}

package/src/keysyms.d.ts

@@ -0,0 +1,149 @@
+/**
+ * X11 keysyms — `react-x11/keysyms`. One vocabulary for app code, the
+ * widgets and `fireEvent.key`.
+ */
+
+/**
+ * The keysym for a character. Latin-1 (U+0020–U+00FF) is identity, so `'a'`
+ * is `0x61` and `'é'` is `0xe9`; anything else is `0x01000000 + codePoint`.
+ */
+export function keysymOf(char: string): number;
+
+/** The character a keysym produces, or `''` for a non-printing key. */
+export function charOf(keysym: number): string;
+
+/**
+ * The letter of a Ctrl chord, independent of Shift — the keysym for its
+ * lowercase form, so `keysymOf('z')` matches both Ctrl+Z and Ctrl+Shift+Z.
+ * Null when the event carries neither a keysym nor a codepoint.
+ *
+ * ntk derives `codepoint` from the *shifted* keysym, so a handler that
+ * compared code points would see `Z` for Ctrl+Shift+Z and miss the chord.
+ * Here rather than inside `<textinput>` because both layers need it: the
+ * built-in editors read Ctrl+C/V/Z, and so does any widget that answers a
+ * chord of its own.
+ *
+ * ```js
+ * if (ev.ctrlKey && ctrlChordLetter(ev) === keysymOf('d')) duplicateLine();
+ * ```
+ */
+export function ctrlChordLetter(ev: {
+  keysym?: number | null;
+  codepoint?: number | null;
+}): number | null;
+
+/**
+ * The keysym an X11 key *name* stands for — `'Return'`, `'plus'`, `'F5'`,
+ * `'s'` — or `undefined` for a name nothing here knows.
+ *
+ * This is the vocabulary a menu item's `shortcut` chords are written in
+ * (X11's names, which is what `gdk_keyval_name()` emits and what a panel's
+ * dbusmenu importer parses), so a chord can be matched, drawn and exported
+ * from one spelling. A one-character name is the character itself.
+ */
+export function keysymFromName(name: string): number | undefined;
+
+export const XK_BACKSPACE: 0xff08;
+export const XK_TAB: 0xff09;
+export const XK_RETURN: 0xff0d;
+export const XK_ESCAPE: 0xff1b;
+export const XK_DELETE: 0xffff;
+export const XK_INSERT: 0xff63;
+
+export const XK_HOME: 0xff50;
+export const XK_LEFT: 0xff51;
+export const XK_UP: 0xff52;
+export const XK_RIGHT: 0xff53;
+export const XK_DOWN: 0xff54;
+export const XK_PAGE_UP: 0xff55;
+export const XK_PAGE_DOWN: 0xff56;
+export const XK_END: 0xff57;
+
+export const XK_KP_ENTER: 0xff8d;
+export const XK_MENU: 0xff67;
+export const XK_SPACE: 0x0020;
+
+/**
+ * The Compose key. It types nothing on its own: it opens a sequence that
+ * the next keys finish — `Compose o c` is `©`. See
+ * [docs/events.md](events.md#composition).
+ */
+export const XK_MULTI_KEY: 0xff20;
+
+// The dead keys. Each waits for the character it decorates, so `dead_acute`
+// then `e` is `é`; on its own — followed by a space, or pressed twice — it
+// types the accent.
+export const XK_DEAD_GRAVE: 0xfe50;
+export const XK_DEAD_ACUTE: 0xfe51;
+export const XK_DEAD_CIRCUMFLEX: 0xfe52;
+export const XK_DEAD_TILDE: 0xfe53;
+export const XK_DEAD_MACRON: 0xfe54;
+export const XK_DEAD_BREVE: 0xfe55;
+export const XK_DEAD_ABOVEDOT: 0xfe56;
+export const XK_DEAD_DIAERESIS: 0xfe57;
+export const XK_DEAD_ABOVERING: 0xfe58;
+export const XK_DEAD_DOUBLEACUTE: 0xfe59;
+export const XK_DEAD_CARON: 0xfe5a;
+export const XK_DEAD_CEDILLA: 0xfe5b;
+export const XK_DEAD_OGONEK: 0xfe5c;
+export const XK_DEAD_IOTA: 0xfe5d;
+export const XK_DEAD_VOICED_SOUND: 0xfe5e;
+export const XK_DEAD_SEMIVOICED_SOUND: 0xfe5f;
+export const XK_DEAD_BELOWDOT: 0xfe60;
+export const XK_DEAD_HOOK: 0xfe61;
+export const XK_DEAD_HORN: 0xfe62;
+export const XK_DEAD_STROKE: 0xfe63;
+export const XK_DEAD_ABOVECOMMA: 0xfe64;
+export const XK_DEAD_ABOVEREVERSEDCOMMA: 0xfe65;
+export const XK_DEAD_DOUBLEGRAVE: 0xfe66;
+export const XK_DEAD_BELOWRING: 0xfe67;
+export const XK_DEAD_BELOWMACRON: 0xfe68;
+export const XK_DEAD_BELOWCIRCUMFLEX: 0xfe69;
+export const XK_DEAD_BELOWTILDE: 0xfe6a;
+export const XK_DEAD_BELOWBREVE: 0xfe6b;
+export const XK_DEAD_BELOWDIAERESIS: 0xfe6c;
+export const XK_DEAD_INVERTEDBREVE: 0xfe6d;
+export const XK_DEAD_BELOWCOMMA: 0xfe6e;
+export const XK_DEAD_CURRENCY: 0xfe6f;
+
+/** Whether a keysym is one of the `XK_dead_*` block. */
+export function isDeadKeysym(keysym: number): boolean;
+
+export const XK_SHIFT_L: 0xffe1;
+export const XK_SHIFT_R: 0xffe2;
+export const XK_CONTROL_L: 0xffe3;
+export const XK_CONTROL_R: 0xffe4;
+export const XK_CAPS_LOCK: 0xffe5;
+export const XK_ALT_L: 0xffe9;
+export const XK_ALT_R: 0xffea;
+export const XK_SUPER_L: 0xffeb;
+export const XK_SUPER_R: 0xffec;
+
+export const XK_F1: 0xffbe;
+export const XK_F2: 0xffbf;
+export const XK_F3: 0xffc0;
+export const XK_F4: 0xffc1;
+export const XK_F5: 0xffc2;
+export const XK_F6: 0xffc3;
+export const XK_F7: 0xffc4;
+export const XK_F8: 0xffc5;
+export const XK_F9: 0xffc6;
+export const XK_F10: 0xffc7;
+export const XK_F11: 0xffc8;
+export const XK_F12: 0xffc9;
+
+/** X11 modifier mask bits, as `ev.nativeEvent.buttons` carries them. */
+export const MOD: {
+  Shift: 1;
+  Lock: 2;
+  Control: 4;
+  Mod1: 8;
+  Alt: 8;
+  Mod2: 16;
+  Mod3: 32;
+  Mod4: 64;
+  Super: 64;
+  Mod5: 128;
+};
+
+export type ModifierName = keyof typeof MOD;