react-x11 1.2.0 → 2.0.0

package/src/inputtime.js

@@ -0,0 +1,206 @@
+// The server timestamp of the last X input event, per app — and a way to ask
+// the server for a fresh one when there has not been an input to name.
+//
+// X arbitrates between clients by timestamp, and every selection operation
+// wants one: taking a selection (ICCCM 2.1), converting one (ICCCM 2.4) and
+// giving one back (ICCCM 2.3.1) all say to use "the timestamp of the event
+// that caused this" and not CurrentTime. The only place that value exists is
+// the X event being dispatched, which is nowhere near the code that copies —
+// `_copySelection` is four frames down from the keystroke that triggered it.
+//
+// So it is stashed on the way past, the same trick GTK plays with
+// `gtk_get_current_event_time()`. Without it ntk asks the server for a
+// timestamp on every acquisition, which is a round trip per copy — and
+// select-to-own PRIMARY copies on every selection-extending keystroke.
+//
+// Keyed on the app rather than stored on it: one process can drive several
+// roots on several connections, and a timestamp is only meaningful against
+// the server clock that issued it.
+//
+// ## Why both halves are public
+//
+// react-x11 owns the clipboard, so for a long time nothing outside this file
+// needed either. An application that owns a selection of its own does — a
+// system tray takes `_NET_SYSTEM_TRAY_S<screen>`, a clipboard manager takes
+// `CLIPBOARD_MANAGER`, an input method takes `XIM_SERVERS` — and the choice
+// it faces is exactly the one the two exports name:
+//
+//   - There **was** a user action behind this, and ICCCM wants that event's
+//     own time: `lastInputTime(app)`, free, already stashed.
+//   - There was **not** — a tray acquires its selection when it starts, not
+//     because anyone clicked — so there is no causing event and any current
+//     server time is correct: `await serverTime(app)`, one round trip.
+//
+// Both beat `CurrentTime`, which is the failure this exists to prevent: the
+// server takes it, two clients racing for one selection cannot be ordered by
+// it, and the loser is never told it lost.
+
+const lastInput = new WeakMap();
+
+// Motion is deliberately not tracked. Nothing converts or acquires a
+// selection from a motion event — a drag-select owns PRIMARY on the mouseup
+// that ends it, and a drag publishes on the mousedown that began it — so
+// tracking motion would add a write per motion event to buy nothing.
+const TRACKED = new Set(['mousedown', 'mouseup', 'keydown', 'keyup']);
+
+/** Remember the server time an input event carried, if it carried one. */
+export function noteInputTime(app, name, native) {
+  if (!app || !TRACKED.has(name)) return;
+  const time = native?.time;
+  if (typeof time === 'number') lastInput.set(app, time >>> 0);
+}
+
+/**
+ * The last input timestamp seen on this app's connection, or `undefined`
+ * when no input has arrived yet.
+ *
+ * ```jsx
+ * const app = useApp();
+ * // acquiring PRIMARY because the user just selected something
+ * app.X.SetSelectionOwner(wid, atom, lastInputTime(app));
+ * ```
+ *
+ * This is EWMH's own definition of `_NET_WM_USER_TIME` and ICCCM's "the
+ * timestamp of the event that caused this", so it is the right value for
+ * anything happening *because the user did something* — which includes every
+ * selection a keystroke or a click acquires, and the `_NET_ACTIVE_WINDOW`
+ * request behind {@link activateWindow}.
+ *
+ * `undefined` is passed straight through to ntk rather than replaced with a
+ * zero: ntk's `write()` turns it into a real server timestamp, and
+ * CurrentTime is what ICCCM 2.1 forbids. Elsewhere `undefined` means there
+ * is no user action to name and {@link serverTime} is the answer — a caller
+ * who reaches for `?? 0` has written CurrentTime back in.
+ */
+export function lastInputTime(app) {
+  return app ? lastInput.get(app) : undefined;
+}
+
+/** ms before `serverTime()` gives up on the round trip. */
+const TIMEOUT = 5000;
+
+/** x11.eventMask.PropertyChange, and PropertyNotify's event code. */
+const PROPERTY_CHANGE_MASK = 4194304;
+const PROPERTY_NOTIFY = 28;
+
+/** ChangeProperty's Append mode, and PropertyNotify's NewValue state. */
+const APPEND = 2;
+const NEW_VALUE = 0;
+
+const TIME_PROPERTY = '_REACT_X11_TIMESTAMP';
+
+/** The 1x1 window and property atom each connection derives times through. */
+const timeSources = new WeakMap();
+
+/**
+ * A current timestamp from this connection's server.
+ *
+ * ```jsx
+ * // a tray taking its manager selection at startup: nothing the user did
+ * // caused this, so there is no event time to use
+ * app.X.SetSelectionOwner(manager, selection, await serverTime(app));
+ * ```
+ *
+ * There is no request that just asks for the time, so this is the trick every
+ * X client uses instead: append zero bytes to a property on a window we own
+ * and watch, and read the time off the `PropertyNotify` that generates. One
+ * round trip, no visible side effect — the window is 1x1, never mapped, and
+ * created once per connection.
+ *
+ * Prefer {@link lastInputTime} where a user action caused the operation: it
+ * is free, and ICCCM asks for the causing event's time specifically. Reach
+ * for this where nothing did, and where a stale value would be wrong anyway —
+ * `SetSelectionOwner` is refused outright if the timestamp predates the
+ * current owner's acquisition, so "the last thing the user touched, an hour
+ * ago" is not a safe substitute for "now".
+ *
+ * Resolves `0` — CurrentTime — if the server has not answered within five
+ * seconds, or if this app has no connection to ask. Never rejects and never
+ * hangs: a caller stuck waiting for a timestamp is worse than one told the
+ * connection is not answering.
+ */
+export async function serverTime(app) {
+  const X = app?.X;
+  const source = await timeSource(app);
+  if (!source) return 0;
+  return new Promise((resolve) => {
+    const done = (time) => {
+      clearTimeout(timer);
+      X.removeListener('event', onEvent);
+      resolve(time);
+    };
+    const onEvent = (ev) => {
+      if (
+        ev.type === PROPERTY_NOTIFY &&
+        ev.wid === source.window &&
+        ev.atom === source.atom &&
+        ev.state === NEW_VALUE
+      ) {
+        done(ev.time >>> 0);
+      }
+    };
+    const timer = setTimeout(() => done(0), TIMEOUT);
+    timer.unref?.();
+    X.on('event', onEvent);
+    // Appending nothing still rewrites the property, which is what generates
+    // the event; replacing would too, but appending cannot grow the property
+    // however many times this is called.
+    X.ChangeProperty(
+      APPEND,
+      source.window,
+      source.atom,
+      X.atoms.STRING,
+      8,
+      Buffer.alloc(0),
+    );
+  });
+}
+
+/**
+ * The window and atom to bounce a timestamp off, created on first use and
+ * shared by every later call on the same connection.
+ *
+ * Its own window rather than one of the app's: selecting PropertyChange on a
+ * `<window>` would put every property the window manager writes on it — and
+ * `_NET_WM_STATE` changes constantly — through this connection's event stream
+ * for the life of the app, to serve a call that happens once.
+ *
+ * A promise because the property atom has to be interned before anything can
+ * be appended to it; awaiting it is also what keeps two calls racing at
+ * startup from creating two windows. Resolves null on a connection that
+ * cannot do this at all, which is a headless mock rather than any real
+ * server.
+ */
+function timeSource(app) {
+  if (!app || typeof app !== 'object') return null;
+  const cached = timeSources.get(app);
+  if (cached !== undefined) return cached;
+
+  const X = app.X;
+  const root = X?.display?.screen?.[0]?.root;
+  if (
+    root == null ||
+    typeof X.AllocID !== 'function' ||
+    typeof X.CreateWindow !== 'function' ||
+    typeof X.ChangeProperty !== 'function' ||
+    typeof X.on !== 'function'
+  ) {
+    timeSources.set(app, null);
+    return null;
+  }
+
+  const window = X.AllocID();
+  // InputOutput rather than InputOnly: properties are legal on both, but a
+  // 1x1 window that is never mapped costs the same either way, and this is
+  // the shape every other toolkit's timestamp window has.
+  X.CreateWindow(window, root, -100, -100, 1, 1, 0, 0, 1, 0, {
+    eventMask: PROPERTY_CHANGE_MASK,
+  });
+  const pending = new Promise((resolve) => {
+    X.InternAtom(false, TIME_PROPERTY, (err, atom) =>
+      resolve(err || !atom ? null : { window, atom }),
+    );
+  });
+  timeSources.set(app, pending);
+  return pending;
+}

package/src/jsx-dev-runtime.d.ts

@@ -0,0 +1,21 @@
+/** Development counterpart of jsx-runtime.d.ts — the same JSX namespace. */
+
+import type * as React from 'react';
+import type { ReactX11Elements } from './types/elements.js';
+
+export { Fragment, jsxDEV } from 'react/jsx-dev-runtime';
+
+export namespace JSX {
+  type ElementType = React.JSX.ElementType;
+  type Element = React.JSX.Element;
+  type ElementClass = React.JSX.ElementClass;
+  type ElementAttributesProperty = React.JSX.ElementAttributesProperty;
+  type ElementChildrenAttribute = React.JSX.ElementChildrenAttribute;
+  type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<
+    C,
+    P
+  >;
+  type IntrinsicAttributes = React.JSX.IntrinsicAttributes;
+  type IntrinsicClassAttributes<T> = React.JSX.IntrinsicClassAttributes<T>;
+  interface IntrinsicElements extends ReactX11Elements {}
+}

package/src/jsx-dev-runtime.js

@@ -0,0 +1,2 @@
+// Development counterpart of jsx-runtime.js — see the note there.
+export { Fragment, jsxDEV } from 'react/jsx-dev-runtime';

package/src/jsx-runtime.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The JSX namespace for react-x11. Set
+ *
+ *   { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "react-x11" } }
+ *
+ * and `<window>`, `<box>`, `<text>` … type-check, while `<div>` does not.
+ *
+ * This has to be a JSX *source* rather than an augmentation of React's own
+ * namespace: five element names — `text`, `image`, `canvas`, `html`, `svg` —
+ * also exist in `@types/react` as HTML or SVG elements with incompatible
+ * props, and declaration merging cannot replace an existing member. Owning
+ * the namespace is also what makes `<div>` an error here, which augmenting
+ * could never do.
+ */
+
+import type * as React from 'react';
+import type { ReactX11Elements } from './types/elements.js';
+
+export { Fragment, jsx, jsxs } from 'react/jsx-runtime';
+
+export namespace JSX {
+  type ElementType = React.JSX.ElementType;
+  type Element = React.JSX.Element;
+  type ElementClass = React.JSX.ElementClass;
+  type ElementAttributesProperty = React.JSX.ElementAttributesProperty;
+  type ElementChildrenAttribute = React.JSX.ElementChildrenAttribute;
+  type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<
+    C,
+    P
+  >;
+  type IntrinsicAttributes = React.JSX.IntrinsicAttributes;
+  type IntrinsicClassAttributes<T> = React.JSX.IntrinsicClassAttributes<T>;
+
+  /**
+   * The X11 host elements — and only those. An interface so a project can
+   * still declare extra elements of its own by merging into it.
+   */
+  interface IntrinsicElements extends ReactX11Elements {}
+}

package/src/jsx-runtime.js

@@ -0,0 +1,6 @@
+// The automatic JSX runtime, so a project can set
+// `"jsxImportSource": "react-x11"` and have JSX type-check against the X11
+// elements instead of the DOM's. At runtime this is React's own runtime —
+// the elements are host components either way; only the *types* differ, and
+// they have to come from somewhere TypeScript will look.
+export { Fragment, jsx, jsxs } from 'react/jsx-runtime';

package/src/keyboard.js

@@ -0,0 +1,256 @@
+// The accelerator half of a key event: which keysym a shortcut matches
+// against when the user is typing in another script (issue #85).
+//
+// A key event answers two different questions and they have different
+// answers the moment a non-Latin layout is active:
+//
+// - **text input** — the active group, the active level. `ev.codepoint` and
+//   `ev.key`, both decoded by ntk against the keymap and the event's state
+//   field, so a Cyrillic layout types Cyrillic.
+// - **accelerators** — the *Latin* keysym for that physical key, whichever
+//   group happens to hold it. `ev.keysym`, resolved here. Shortcuts do not
+//   move with the layout: GTK, Qt and the browsers all resolve them this
+//   way, and Ctrl+Z has to keep undoing while the user types Russian.
+//
+// ntk hands us group 1 level 1 as `baseKeysym`, which is the right answer
+// whenever group 1 is Latin — the `us,ru` ordering everybody on Linux
+// actually uses. It is the wrong answer in the two cases this module is
+// for:
+//
+// - **`ru,us`** — the Latin layout is group 2, so group 1 level 1 is
+//   `Cyrillic_ya` and a chord matched against it matches nothing. The
+//   keysym we want is on the same keycode, two entries along.
+// - **XQuartz** — there are no groups at all. XQuartz synthesizes the keymap
+//   from the active macOS layout and *overwrites* it when the input menu
+//   changes (Preferences → Input → "Follow system keyboard layout"), so
+//   after a switch to Russian no group anywhere holds Latin. Nothing in the
+//   keymap can answer, and the only thing left that still means "the Z key"
+//   is the keycode itself.
+//
+// So: the base keysym if it is already Latin, else the Latin letter another
+// group puts on the same keycode, else the letter the *physical position*
+// carries on a US keyboard. The last step needs to know which keycodes the
+// server is speaking, which is what `SCHEMES` fingerprints.
+
+import { keysymOf } from './keysyms.js';
+
+// Keysyms from 0xfd00 to 0xffff are keys rather than characters — Return,
+// the arrows, the function row, the modifiers, ISO_Level3_Shift, the dead
+// keys. They are the same in every layout and never need resolving.
+const KEY_LOW = 0xfd00;
+
+// Direct Unicode keysyms: 0x01000000 + code point.
+const UNICODE_LOW = 0x01000000;
+const UNICODE_HIGH = 0x0110ffff;
+
+// The legacy keysym blocks that are not Latin script. Below 0x400 is
+// Latin-1 through Latin-4; 0x800-0xbff are technical, publishing and APL
+// symbols; 0x1200-0x13ff are Latin-8 and Latin-9 and 0x1e00-0x1eff is
+// Vietnamese, all of them Latin. What is left is the scripts a shortcut
+// cannot be written in.
+const NON_LATIN_BLOCKS = [
+  [0x0400, 0x04ff], // Kana
+  [0x0500, 0x05ff], // Arabic
+  [0x0600, 0x06ff], // Cyrillic
+  [0x0700, 0x07ff], // Greek
+  [0x0c00, 0x0cff], // Hebrew
+  [0x0d00, 0x0dff], // Thai
+  [0x0e00, 0x0eff], // Korean
+  [0x1400, 0x16ff], // Armenian, Georgian, Caucasus
+];
+
+// For the direct-Unicode block, where there is no block structure to read:
+// anything that is not Latin script and not script-neutral (digits,
+// punctuation, symbols, spaces) is a letter of some other alphabet.
+const LATIN_OR_NEUTRAL =
+  /^[\p{Script=Latin}\p{Script=Common}\p{Script=Inherited}]$/u;
+
+/**
+ * Whether a keysym is a letter of a script an accelerator cannot be written
+ * in — the question that decides whether anything below runs at all.
+ */
+export function isNonLatinKeysym(keysym) {
+  if (typeof keysym !== 'number' || keysym <= 0xff) return false;
+  if (keysym >= KEY_LOW && keysym <= 0xffff) return false;
+  if (keysym >= UNICODE_LOW) {
+    if (keysym > UNICODE_HIGH) return false;
+    return !LATIN_OR_NEUTRAL.test(String.fromCodePoint(keysym - UNICODE_LOW));
+  }
+  return NON_LATIN_BLOCKS.some(([lo, hi]) => keysym >= lo && keysym <= hi);
+}
+
+// An ASCII keysym is its own code point, so `a`-`z` is a range.
+const LOWER_A = 0x61;
+const LOWER_Z = 0x7a;
+const TO_UPPER = -0x20;
+
+/**
+ * The Latin letter another group puts on this keycode, if one does.
+ *
+ * The core keyboard map flattens XKB's groups into pairs —
+ * `[g1l1, g1l2, g2l1, g2l2, ...]` — so the second group starts at index 2.
+ * What the core map cannot say is whether those two entries are a second
+ * *group* or levels 3 and 4 of the first one: four keysyms on a keycode are
+ * `us,ru` under one reading and `us(intl)` under the other, and the request
+ * that would settle it (XkbGetMap) is not implemented downstream. ntk's
+ * `decodeKey` refuses to guess and reads groups only; this refuses in the
+ * other direction, by taking a later pair only when it looks like a Latin
+ * letter and its own capital.
+ *
+ * That is deliberately narrow. An AltGr row that happens to reach an ASCII
+ * symbol — macOS's Option layer is full of them — must not be mistaken for
+ * a Latin layout, and a Latin *letter* pair is both the thing that is
+ * unlikely to be an accident and the thing accelerators are made of.
+ */
+function latinInLaterGroup(syms) {
+  for (let i = 2; i < syms.length; i += 2) {
+    const lower = syms[i];
+    const upper = syms[i + 1];
+    if (lower < LOWER_A || lower > LOWER_Z) continue;
+    // "if the second element is NoSymbol, the group is treated as the lower
+    // and upper case of the first" — X core protocol
+    if (!upper || upper === lower + TO_UPPER) return lower;
+  }
+  return undefined;
+}
+
+/** `{ 10: 0x31, 11: 0x32, … }` from runs of consecutive keycodes. */
+function positions(runs) {
+  const table = {};
+  for (const [first, chars] of runs) {
+    for (let i = 0; i < chars.length; i++)
+      table[first + i] = chars.charCodeAt(i);
+  }
+  return table;
+}
+
+/**
+ * What each physical key carries on a US keyboard, per keycode scheme, and
+ * the layout-independent keys that identify the scheme.
+ *
+ * Keycodes are not a standard: they are whatever the server's input driver
+ * assigns. Two schemes cover everything this renderer runs on — Linux's
+ * evdev, and the macOS virtual keycodes XQuartz passes through with 8 added
+ * — and they disagree everywhere, which is exactly what makes the probe
+ * reliable. Return alone separates them (36 on evdev is `8` on macOS), and
+ * five keys make it certain.
+ */
+const SCHEMES = [
+  {
+    name: 'evdev',
+    probe: { 9: 0xff1b, 22: 0xff08, 23: 0xff09, 36: 0xff0d, 65: 0x20 },
+    latin: positions([
+      [10, '1234567890-='],
+      [24, 'qwertyuiop[]'],
+      [38, "asdfghjkl;'"],
+      [49, '`'],
+      [51, '\\'],
+      [52, 'zxcvbnm,./'],
+      [65, ' '],
+    ]),
+  },
+  {
+    name: 'macos',
+    probe: { 44: 0xff0d, 56: 0xff09, 57: 0x20, 59: 0xff08, 61: 0xff1b },
+    latin: positions([
+      [8, 'asdfhgzxcv'],
+      [19, 'b'],
+      [20, 'qweryt'],
+      [26, '123465=97-80'],
+      [38, ']ou[ip'],
+      [45, "lj'k;\\,/nm."],
+      [57, ' '],
+      [58, '`'],
+    ]),
+  },
+];
+
+/**
+ * Which keycode scheme this keymap is speaking, or null if it is neither.
+ *
+ * The probe reads keys whose keysym no layout moves, so it answers the same
+ * before and after a switch — which matters, because on XQuartz the keymap
+ * it is reading is rewritten under it.
+ */
+export function physicalLatinTable(keycode2keysyms) {
+  if (!keycode2keysyms) return null;
+  for (const scheme of SCHEMES) {
+    const matches = Object.entries(scheme.probe).every(
+      ([keycode, keysym]) => keycode2keysyms[keycode]?.[0] === keysym,
+    );
+    if (matches) return scheme.latin;
+  }
+  return null;
+}
+
+/**
+ * The keysym a shortcut matches against, given ntk's group 1 level 1 and
+ * the keycode's whole row.
+ *
+ * `physical` is the keycode→Latin table for this server, or null when the
+ * scheme is unknown — in which case a key with no Latin anywhere on it
+ * keeps its own keysym, since a wrong shortcut is worse than a missing one.
+ */
+export function latinKeysym(base, syms, keycode, physical) {
+  if (!isNonLatinKeysym(base)) return base;
+  const fromGroup = syms ? latinInLaterGroup(syms) : undefined;
+  if (fromGroup !== undefined) return fromGroup;
+  return physical?.[keycode] ?? base;
+}
+
+/**
+ * Record what `createRoot({ accelerators })` asked for.
+ *
+ * The default resolves; `'layout'` does not, for an application that wants
+ * the keysym the key actually typed and will do its own matching. An object
+ * is a keycode→Latin keysym table of your own, for a server whose keycodes
+ * are neither of the two schemes above (and it still prefers a Latin group
+ * on the key itself, which is the more accurate answer where there is one).
+ */
+export function beginKeyboard(app, accelerators) {
+  if (!app || accelerators === undefined) return;
+  if (accelerators === 'latin') {
+    app._reactX11Accelerators = undefined;
+    return;
+  }
+  if (accelerators === 'layout' || accelerators === false) {
+    app._reactX11Accelerators = null;
+    return;
+  }
+  if (typeof accelerators !== 'object') {
+    throw new TypeError(
+      `react-x11: createRoot({ accelerators }) takes 'latin', 'layout' or a ` +
+        `keycode table, not ${JSON.stringify(accelerators)}.`,
+    );
+  }
+  const table = {};
+  for (const [keycode, value] of Object.entries(accelerators)) {
+    table[keycode] = typeof value === 'string' ? keysymOf(value) : value;
+  }
+  app._reactX11Accelerators = { table };
+}
+
+/**
+ * The accelerator keysym for one key event, cached per connection.
+ *
+ * Only the *scheme* is cached: the keymap itself is re-read on every
+ * MappingNotify (ntk does that), and on XQuartz a layout switch is a
+ * rewritten keymap, so the row has to be looked at fresh each time. The
+ * scheme is fixed by the server's input driver and cannot change under a
+ * running connection — but it is resolved lazily and not remembered until
+ * it answers, because the first key can beat `GetKeyboardMapping`'s reply.
+ */
+export function acceleratorKeysym(app, keycode, base) {
+  const config = app?._reactX11Accelerators;
+  if (config === null) return base;
+  // The common case, and every key event pays it: a Latin layout, or a key
+  // that is a key rather than a character. One comparison and out.
+  if (!isNonLatinKeysym(base)) return base;
+  const syms = app?.X?.keycode2keysyms?.[keycode];
+  if (config?.table) return latinKeysym(base, syms, keycode, config.table);
+  if (app && !app._reactX11PhysicalLatin) {
+    const table = physicalLatinTable(app.X?.keycode2keysyms);
+    if (table) app._reactX11PhysicalLatin = table;
+  }
+  return latinKeysym(base, syms, keycode, app?._reactX11PhysicalLatin);
+}