react-x11 1.2.0 → 2.0.0

package/src/clientmessage.js

@@ -0,0 +1,140 @@
+// ClientMessage, delivered to the element it was addressed to.
+//
+// ClientMessage is the carrier of every convention layered over the core
+// protocol: EWMH's requests to the window manager, ICCCM's WM_PROTOCOLS,
+// XEmbed, XDND, the system tray, and whatever two copies of one application
+// agree between themselves. react-x11 speaks a few of those itself — XDND in
+// `src/dnd.js`, WM_DELETE_WINDOW through ntk's `close` — and an application
+// that speaks one core does not had exactly one route: subscribe to
+// `X.on('event')`, which is every event on the connection for every window,
+// and filter. `src/xsettings.js` does that internally and it is the right
+// shape *there*, because a settings daemon's window is nobody's element. It
+// is the wrong shape to hand an application: it is not scoped to a window,
+// it does not go away when the window unmounts, and it is expressed in atom
+// ids rather than names.
+//
+// So `<window onClientMessage>` is the seam, and this is what fills it.
+//
+// ## The type is a name, and that costs a round trip once
+//
+// `message_type` is an atom, and an atom is a number that means nothing away
+// from the server that issued it. Comparing against one means interning it
+// first, which is asynchronous, so the obvious handler cannot be written as a
+// `switch` — it has to wait for an atom table to arrive before it can tell
+// one message from another, and that table is the boilerplate this seam
+// exists to delete.
+//
+// Most of the time the name is already there: node-x11 keeps a per-connection
+// id → name table filled from every InternAtom and GetAtomName reply, so an
+// atom this application has ever *named* — which is every atom in a protocol
+// it sends, advertises or owns anything for — resolves synchronously and the
+// message is dispatched in the turn it arrived in.
+//
+// A protocol this application only ever *receives* has no such moment, and
+// that case is the whole point of the feature: a tray host does not send
+// `_NET_SYSTEM_TRAY_OPCODE`, it is sent one. So an unknown atom is resolved
+// with `GetAtomName` — and **every message behind it waits**, which is the
+// part that is not optional. The protocols carried this way are chunked
+// (`_NET_SYSTEM_TRAY_BEGIN_MESSAGE` and the `_NET_SYSTEM_TRAY_MESSAGE_DATA`
+// pieces that reassemble by arrival order alone) or sequenced (XEmbed), so a
+// round trip that let a later message overtake an earlier one would corrupt
+// them in a way no handler could detect. The same FIFO gate `src/dnd.js`
+// runs its own messages through, for the same reason.
+//
+// The cost is one round trip per message *type* per connection — node-x11
+// caches the reply, so the second `_NET_SYSTEM_TRAY_OPCODE` is synchronous
+// like everything else. `messageType` is therefore null only for an atom the
+// server itself does not know, which is a broken sender rather than a case to
+// design around; `atom` carries the id regardless.
+
+/** X's event code for ClientMessage, for `ev.type`. */
+const CLIENT_MESSAGE = 33;
+
+/** Per-connection id → name lookups in flight or resolved, negatives kept:
+ * a sender repeating a bogus atom must not repeat the round trip. */
+const nameCaches = new WeakMap();
+
+/** The name of an atom, or a promise for it. Never rejects. */
+function atomName(X, id) {
+  const known = X?.atom_names?.[id];
+  if (known !== undefined) return known;
+  if (typeof X?.GetAtomName !== 'function') return null;
+  let cache = nameCaches.get(X);
+  if (!cache) nameCaches.set(X, (cache = new Map()));
+  const hit = cache.get(id);
+  if (hit) return hit;
+  const pending = new Promise((resolve) =>
+    X.GetAtomName(id, (err, name) => resolve(err ? null : name)),
+  );
+  cache.set(id, pending);
+  return pending;
+}
+
+/**
+ * The stream of ClientMessages for one window: names each message's type and
+ * hands it to `dispatch` in arrival order.
+ *
+ * `dispatch` is the caller's, so the priority and the paint stay with the
+ * other window events in nodes.js; what lives here is the naming and the
+ * ordering it has to preserve.
+ */
+export function createClientMessages(node, dispatch) {
+  let queued = 0;
+  let chain = Promise.resolve();
+
+  /**
+   * The event a handler receives. Not a `SyntheticEvent`: a ClientMessage is
+   * addressed to a *window*, so there is no node under it, nothing to hit
+   * test and no chain to bubble along. Same shape `onResize` has, for the
+   * same reason.
+   */
+  const build = (raw, messageType) => ({
+    type: CLIENT_MESSAGE,
+    messageType,
+    atom: raw.message_type,
+    format: raw.format,
+    data: raw.data,
+    window: node.window,
+    target: node.window,
+    nativeEvent: raw,
+    get defaultPrevented() {
+      return raw.defaultPrevented === true;
+    },
+    preventDefault() {
+      // Marked on the raw event, because what reads it is a second
+      // subscriber to the same ntk stream (`WindowNode._initDnd`) rather
+      // than a later step of this dispatch.
+      raw.defaultPrevented = true;
+    },
+  });
+
+  return {
+    /** Take one raw ntk `'message'` event. */
+    handle(raw) {
+      const name = atomName(node.app?.X, raw.message_type);
+      const settled = name === null || typeof name === 'string';
+      if (queued === 0 && settled) {
+        dispatch(build(raw, name));
+        return;
+      }
+      queued++;
+      chain = chain
+        .then(() => name)
+        .then((resolved) => dispatch(build(raw, resolved)))
+        .catch(() => {}) // a handler throw is already reported by callHandler
+        .then(() => {
+          queued--;
+        });
+    },
+
+    /**
+     * `null` when every message so far has been dispatched, so a default
+     * action can run in the same turn its message arrived in; otherwise the
+     * promise after which it has been — which is what lets `preventDefault()`
+     * still reach XDND on the one message whose type had to be named first.
+     */
+    pending() {
+      return queued === 0 ? null : chain;
+    },
+  };
+}

package/src/clipboard.js

@@ -0,0 +1,121 @@
+// The clipboard an application sees.
+//
+// ntk's `app.clipboard` is the ICCCM selection machinery: it owns
+// selections, answers conversions, and speaks INCR. This is the layer above
+// it, and it adds exactly three things, none of which belong upstream:
+//
+//   1. the type vocabulary (transfer.js) — so `read('text')` finds GTK's
+//      UTF8_STRING and `readFiles()` parses a file manager's uri-list,
+//      instead of every app rediscovering the same table;
+//   2. an ICCCM timestamp by default (inputtime.js), so a copy is stamped
+//      with the keystroke that caused it rather than with "now";
+//   3. a way in from React (useClipboard), since a component has no route
+//      to the connection.
+//
+// Everything on the wire is still ntk's. `root.app.clipboard` remains the
+// documented escape hatch for anything this does not cover.
+
+import { lastInputTime } from './inputtime.js';
+import { decodeData, parseUriList, resolveType } from './transfer.js';
+
+/** Ask the owner what it has, so a group name can be resolved against a
+ * real offer rather than guessed at one failed conversion per guess. */
+async function offeredTypes(clipboard, options) {
+  try {
+    return await clipboard.targets(options);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The object `useClipboard()` hands back. One per app — it holds no state
+ * of its own, so making a second is harmless.
+ */
+export function createClipboard(app) {
+  const raw = () => {
+    const c = app?.clipboard;
+    if (!c) throw new Error('react-x11: this app has no clipboard');
+    return c;
+  };
+  // every call takes the same three, and every one of them has a default
+  // worth not repeating
+  const opts = ({ selection = 'CLIPBOARD', timeout, time } = {}) => ({
+    selection,
+    ...(timeout === undefined ? {} : { timeout }),
+    time: time === undefined ? lastInputTime(app) : time,
+  });
+
+  return {
+    /** Take a selection and serve `data` — a string, or a map of type name
+     * to string/bytes for offering several flavours of one thing. */
+    write(data, options) {
+      return raw().write(data, opts(options));
+    },
+
+    /** Shorthand for the common case; offered as UTF8_STRING and STRING. */
+    writeText(text, options) {
+      return raw().write(String(text), opts(options));
+    },
+
+    /** Give the selection back, so nothing is served for it any more. */
+    clear(selection = 'CLIPBOARD') {
+      return raw().clear(selection);
+    },
+
+    /** What the current owner can convert to. `[]` when nothing owns it. */
+    targets(options) {
+      return raw().targets(opts(options));
+    },
+
+    /** The plain text of a selection, ntk's UTF8_STRING → STRING walk.
+     * `read('text')` is the interop-hardened version of this. */
+    readText(options) {
+      return raw().read(opts(options));
+    },
+
+    /**
+     * One type, decoded: a concrete name (`'image/png'`) or a group
+     * (`'text'`, `'files'`, `'uris'`) resolved against what the owner
+     * actually offers. Text-ish types come back as a string, everything
+     * else as bytes. `null` when the owner has nothing of that kind —
+     * which is a question, not an error, unlike `readText()` on an empty
+     * clipboard.
+     */
+    async read(type, options) {
+      const o = opts(options);
+      const offered = await offeredTypes(raw(), o);
+      const target = resolveType(type, offered);
+      if (!offered.includes(target)) return null;
+      const data = await raw().read({ ...o, target });
+      return typeof data === 'string' ? data : decodeData(data, target);
+    },
+
+    /**
+     * Files copied in a file manager, parsed (RFC 2483). `[]` when the
+     * clipboard holds no file flavour, so a paste handler can call it
+     * without asking first.
+     */
+    async readFiles(options) {
+      const list = await this.read('files', options);
+      return typeof list === 'string' ? parseUriList(list) : [];
+    },
+
+    /**
+     * Call `handler` whenever the selection changes hands — an XFixes
+     * subscription, not a poll. `ev.owner === 0` means nothing is on the
+     * clipboard, which is the case an edit menu wants.
+     *
+     * Rejects on a server without XFixes; every X server since about 2004
+     * has it, so treat that as "this server is unusual" rather than as a
+     * path to code around.
+     */
+    watch(selectionOrHandler, maybeHandler) {
+      const [selection, handler] =
+        typeof selectionOrHandler === 'function'
+          ? ['CLIPBOARD', selectionOrHandler]
+          : [selectionOrHandler, maybeHandler];
+      return raw().watch(selection, handler);
+    },
+  };
+}

package/src/components/Button.js

@@ -7,57 +7,172 @@ import { labelContent, useControl, useTheme } from './theme.js';
 
 const h = React.createElement;
 
+const VARIANTS = ['solid', 'outline', 'ghost'];
+const SIZES = ['medium', 'small'];
+
 /**
- * <Button onPress primary disabled …boxProps>label</Button> — the standard
- * push button the examples kept re-implementing: hover/focus feedback,
- * Space/Enter activation, pointer cursor.
+ * <Button onPress variant size primary disabled …boxProps>label</Button> —
+ * the standard push button the examples kept re-implementing: hover/press/
+ * focus feedback, Space/Enter activation, pointer cursor.
+ *
+ * Two axes rather than one list of looks. `variant` is how much chrome the
+ * button carries — `solid` a fill, `outline` a border on nothing, `ghost`
+ * neither, for the affordance that sits *inside* other content (a `✕` on a
+ * chip, a jump arrow beside a value) and must not add a box to the row it
+ * lives in. `primary` is whose colours it speaks in: the accent as the fill
+ * when there is one, the accent as ink and border when there is not. The
+ * axes compose, so a dialog footer's secondary action is `variant="outline"`
+ * next to a `primary` solid, and a toolbar's loudest icon is
+ * `primary variant="ghost"` — one component, one set of states.
+ *
+ * `size="small"` is the compact metric a toolbar or an inline row wants:
+ * half the control padding, everything else in proportion. In the component
+ * rather than in a `style` because the padding is derived from the palette —
+ * a theme that moves `paddingY` moves both sizes together, where a hand-made
+ * `{ height: 22 }` would be left behind.
+ *
+ * `onPress` fires on the **release**, as a click does everywhere — so the
+ * button darkens on the press instead, and keeps the darker fill for as long
+ * as the button is held. Without that the whole of a slow click is a control
+ * that has not answered: press, nothing, nothing, and then the action. The
+ * press state is what makes an unhurried click feel immediate, and it costs
+ * one node's repaint because it is a style block rather than React state.
  */
 export function Button({
   children,
   label,
   onPress,
   primary = false,
+  variant = 'solid',
+  size = 'medium',
   disabled = false,
+  style,
   ...boxProps
 }) {
+  // Before the hook on purpose, as `<Icon name>` does it: an unknown value
+  // never renders, so the message lands on the call site — where TypeScript
+  // is not there to catch the typo, silence would be an outline button.
+  if (!VARIANTS.includes(variant)) {
+    throw new Error(
+      `<Button variant="${variant}">: one of ${VARIANTS.join(', ')}`,
+    );
+  }
+  if (!SIZES.includes(size)) {
+    throw new Error(`<Button size="${size}">: one of ${SIZES.join(', ')}`);
+  }
   const theme = useTheme();
-  const { hover, focused, props } = useControl(disabled, onPress);
-  const background = disabled
-    ? theme.surfaceHover
+  const { props, style: controlStyle } = useControl(disabled, onPress, {
+    styled: true,
+  });
+  const solid = variant === 'solid';
+  const ghost = variant === 'ghost';
+  const small = size === 'small';
+  const background = !solid
+    ? // `transparent` rather than the ground's colour: an outline or ghost
+      // button sits on whatever it sits on — a toolbar, a card, a table row —
+      // and naming a fill would give it a box on any ground but one
+      'transparent'
+    : disabled
+      ? theme.surfaceHover
+      : primary
+        ? theme.accent
+        : theme.surface;
+  const color = disabled
+    ? theme.textMuted
     : primary
-      ? hover
-        ? theme.accentHover
+      ? solid
+        ? theme.accentText
         : theme.accent
-      : hover
-        ? theme.surfaceHover
-        : theme.background;
-  const color = disabled ? theme.dim : primary ? theme.accentText : theme.text;
+      : theme.text;
+  // A ghost button keeps the border *width* and loses only the colour, so
+  // every variant is the same sum and a mixed row lines up — a field padded
+  // with `$paddingY` is exactly this tall too (docs/styling.md).
+  const borderColor = ghost
+    ? 'transparent'
+    : disabled || !primary
+      ? theme.border
+      : theme.accent;
   return h(
     'box',
     {
-      flexDirection: 'row',
-      alignItems: 'center',
-      justifyContent: 'center',
-      gap: 8,
-      paddingTop: 8,
-      paddingBottom: 8,
-      paddingLeft: 16,
-      paddingRight: 16,
-      borderRadius: 4,
-      borderWidth: 1,
-      borderColor: disabled
-        ? theme.border
-        : focused
-          ? primary
-            ? theme.accentHover
-            : theme.borderActive
-          : primary
-            ? theme.accent
-            : theme.border,
-      backgroundColor: background,
+      theme,
+      role: 'button',
       ...props,
       ...boxProps,
+      style: [
+        controlStyle,
+        {
+          flexDirection: 'row',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: small ? 6 : 8,
+          paddingTop: small ? Math.round(theme.paddingY / 2) : theme.paddingY,
+          paddingBottom: small
+            ? Math.round(theme.paddingY / 2)
+            : theme.paddingY,
+          paddingLeft: small ? Math.round(theme.paddingX / 2) : theme.paddingX,
+          paddingRight: small ? Math.round(theme.paddingX / 2) : theme.paddingX,
+          borderRadius: small ? theme.radiusSmall : theme.radius,
+          borderWidth: theme.borderWidth,
+          borderColor,
+          backgroundColor: background,
+          // The label ink goes on the box, not on the label: `color` is
+          // inherited (docs/styling.md), so an element child — an <Icon>,
+          // a <text> — takes the same answer a string child always got,
+          // and an icon+label button dims as one thing when disabled.
+          color,
+        },
+        // All three as state blocks: a repaint of one node each, where React
+        // state re-rendered the button and its label to change a colour.
+        // `:focus-visible` rather than `:focus` is the difference between
+        // "you clicked here" and "your keyboard is here", and only the
+        // second is worth a ring.
+        !disabled &&
+          (solid
+            ? {
+                ':hover': {
+                  backgroundColor: primary
+                    ? theme.accentHover
+                    : theme.surfaceHover,
+                  borderColor: primary ? theme.accentHover : theme.border,
+                },
+                // the border follows the fill: a dark pressed face inside a
+                // resting-coloured ring reads as a rendering bug, not a press
+                ':active': {
+                  backgroundColor: primary
+                    ? theme.accentActive
+                    : theme.surfaceActive,
+                  borderColor: primary ? theme.accentActive : theme.textMuted,
+                },
+                ':focus-visible': {
+                  borderColor: primary ? theme.accentHover : theme.borderFocus,
+                },
+              }
+            : {
+                // Outline and ghost answer the pointer with the neutral wash
+                // whichever colours they speak in: the surface steps are the
+                // hover-and-press ramp for anything without an accent fill,
+                // and the background paints under the border band, so a ghost
+                // button's wash covers the full box.
+                ':hover': { backgroundColor: theme.surfaceHover },
+                ':active': {
+                  backgroundColor: theme.surfaceActive,
+                  ...(ghost
+                    ? null
+                    : {
+                        borderColor: primary
+                          ? theme.accentActive
+                          : theme.textMuted,
+                      }),
+                },
+                // …which on a ghost button makes the border appear, and that
+                // is right: the keyboard has no hover, so the ring is how a
+                // chrome-less control says "your keyboard is here".
+                ':focus-visible': { borderColor: theme.borderFocus },
+              }),
+        style,
+      ],
     },
-    labelContent(children ?? label, { color }),
+    labelContent(children ?? label),
   );
 }

package/src/components/Checkbox.js

@@ -3,67 +3,101 @@
 // build-step-free for consumers.
 
 import React from 'react';
+import { changeEvent } from './change.js';
+import { Icon } from './Icon.js';
 import { labelContent, useControl, useTheme } from './theme.js';
 
 const h = React.createElement;
 
+/** The mark inside the 16px well. */
+const MARK = 11;
+
 /**
  * <Checkbox checked onChange disabled>label</Checkbox> — 16px check well +
- * label row; click or Space toggles (onChange receives the next value).
+ * label row; click or Space toggles. `onChange(ev)` gets a change event, the
+ * same shape `<textinput>` fires: the next value is `ev.value`, and
+ * `ev.target` carries `name`/`checked` for a form library.
+ *
+ * The tick only appears on the release, so the well takes a pressed fill on
+ * the press to cover the gap. This is the case `useControl` keeps in React
+ * state rather than a style block: the press lands anywhere along the row —
+ * usually the label — and `:active` marks that node and its ancestors, which
+ * the well is not. One render per press, for a control whose next act is to
+ * re-render with a new `checked` anyway.
  */
 export function Checkbox({
   children,
   label,
   checked = false,
   onChange,
+  name,
   disabled = false,
+  style,
   ...boxProps
 }) {
   const theme = useTheme();
-  const { focused, props } = useControl(disabled, () => onChange?.(!checked));
-  const fill = disabled ? theme.dim : theme.accent;
+  const {
+    hover,
+    focused,
+    pressed,
+    props,
+    style: controlStyle,
+  } = useControl(disabled, () =>
+    onChange?.(changeEvent('checkbox', name, !checked)),
+  );
+  const fill = disabled
+    ? theme.textMuted
+    : pressed
+      ? theme.accentActive
+      : hover
+        ? theme.accentHover
+        : theme.accent;
+  // An empty well has no fill to step, so it shows the two states in two
+  // different places: hovering firms the ring up, and pressing greys the
+  // inside as well. Three looks, which is the point — a hover the press
+  // cannot be told apart from says nothing about the press.
+  const empty = {
+    borderColor:
+      pressed || hover
+        ? theme.textMuted
+        : focused
+          ? theme.borderFocus
+          : theme.border,
+    backgroundColor: pressed ? theme.surfaceActive : theme.surface,
+  };
   return h(
     'box',
     {
-      flexDirection: 'row',
-      alignItems: 'center',
-      gap: 8,
+      theme,
+      role: 'checkbox',
+      'aria-checked': checked,
       ...props,
       ...boxProps,
+      style: [
+        controlStyle,
+        { flexDirection: 'row', alignItems: 'center', gap: 8 },
+        style,
+      ],
     },
     h(
       'box',
       {
-        width: 16,
-        height: 16,
-        borderRadius: 3,
-        borderWidth: 1,
-        borderColor: checked
-          ? fill
-          : focused
-            ? theme.borderActive
-            : theme.border,
-        backgroundColor: checked ? fill : theme.background,
-        alignItems: 'center',
-        justifyContent: 'center',
+        style: {
+          width: 16,
+          height: 16,
+          borderRadius: theme.radiusSmall,
+          borderWidth: theme.borderWidth,
+          borderColor: checked ? fill : empty.borderColor,
+          backgroundColor: checked ? fill : empty.backgroundColor,
+          alignItems: 'center',
+          justifyContent: 'center',
+        },
       },
       checked &&
-        h('canvas', {
-          width: 10,
-          height: 8,
-          onDraw: (ctx) => {
-            ctx.strokeStyle = theme.accentText;
-            ctx.lineWidth = 2;
-            ctx.beginPath();
-            ctx.moveTo(1, 4);
-            ctx.lineTo(3.5, 6.5);
-            ctx.lineTo(9, 1);
-            ctx.stroke();
-          },
-        }),
+        h(Icon, { name: 'check', size: MARK, color: theme.accentText }),
     ),
     labelContent(children ?? label, {
-      color: disabled ? theme.dim : theme.text,
+      color: disabled ? theme.textMuted : theme.text,
     }),
   );
 }