react-x11 1.2.0 → 2.0.0

package/src/components/scribble.js

@@ -0,0 +1,247 @@
+// The scribble a masked field is drawn with, and the arithmetic behind it.
+//
+// A row of bullets answers the wrong question. It says *how many characters
+// you have typed* — loudly, countably, from across the room — and it says
+// nothing at all about the keystroke that just landed, because one more
+// identical dot at the end of a row of identical dots is the least visible
+// change a field could make.
+//
+// This inverts both. A stroke is drawn through points chosen by a generator
+// seeded from the window and the value, so **every keystroke redraws the
+// whole curve**: the feedback is the entire mask moving, not a mark
+// appearing. And nothing in the shape is per-character — the pen visits a
+// number of points taken from the mask's *width*, where a character is worth
+// about half a point, so no part of the stroke can be matched to anything
+// that was typed.
+//
+// It is a scribble rather than a wave, and that is a decision rather than a
+// look: a stroke whose `x` only ever increases is the plot of a function, and
+// the eye reads it as one — value against position, meaning in the peaks —
+// however wild the `y` is. So the pen doubles back, crosses what it has
+// already drawn, and leaves loops. `scribblePoints` is where that happens.
+//
+// What does grow is the width, because a mask that did not grow would say
+// nothing about progress at all. It grows by a per-position advance drawn
+// from a **window-seeded** stream rather than by a fixed step, so the width
+// is monotonic in the length (typing always widens it) without being a clean
+// multiple of anything (a glance does not give a character count). Those two
+// streams are deliberately separate: the shape reshuffles on every keystroke,
+// the width never does.
+//
+// The honest limits, since a mask that oversells itself is worse than one
+// that does not: an observer who watches the field grow keystroke by
+// keystroke still learns the length, and the width still puts a long password
+// in a different bracket from a short one. This hides a glance, not a
+// recording.
+
+/** FNV-1a over the UTF-16 units, which is all a seed needs to be. */
+export function hash32(text) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * mulberry32: a small, fast, well-distributed PRNG with a 32-bit state.
+ *
+ * The point is not statistical quality, it is that the sequence is a pure
+ * function of the seed — the same value in the same window draws the same
+ * scribble on every repaint, so a frame that redraws a damaged strip cannot
+ * come back with a different curve than the frame before it.
+ */
+export function seededRandom(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * How many points the pen visits, per pixel of mask.
+ *
+ * Deriving the count from the **width** rather than fixing it keeps the
+ * scrawl at one density: a fixed count stretches into a few long shallow
+ * strokes as the field fills, which both stops looking like a scribble and —
+ * since density would then fall with length — says as much about the length
+ * as the count would. Width is already on show; density does not have to be.
+ *
+ * The count is not per-character either way. At this rate a character is
+ * worth about half a point, so nothing in the stroke can be matched to
+ * anything that was typed.
+ */
+const PX_PER_POINT = 9;
+const MIN_POINTS = 7;
+
+/** How far apart, in pixels, the curve is sampled when it is drawn. */
+const SAMPLE_PX = 2;
+const MAX_POINTS = 30;
+
+/** How many points a mask this wide is drawn through. */
+export function scribblePointCount(width) {
+  return Math.max(
+    MIN_POINTS,
+    Math.min(MAX_POINTS, Math.round(width / PX_PER_POINT)),
+  );
+}
+
+/** How far the pen may jump out of order: the width of the window the
+ *  visiting order is shuffled inside. See `scribblePoints`. */
+export const SCRIBBLE_GROUP = 3;
+
+/** The narrowest and widest a character may push the mask, as a fraction of
+ *  the reference advance. Wide enough that the steps do not read as a ruler,
+ *  narrow enough that the mask still tracks what has been typed. */
+const MIN_ADVANCE = 0.55;
+const MAX_ADVANCE = 1.35;
+
+/**
+ * How wide the mask for a value of `length` characters is, in pixels.
+ *
+ * `unit` is the reference advance — one character of the field's own font —
+ * and `seed` is derived from the **window**, never from the value, which is
+ * what makes position 7 contribute the same width whatever is typed there.
+ * So the mask only ever grows as you type, and never twitches when a
+ * character is replaced.
+ */
+export function maskWidth(length, unit, seed, max = Infinity) {
+  if (length <= 0) return 0;
+  const rnd = seededRandom(seed);
+  let width = 0;
+  for (let i = 0; i < length; i++) {
+    const advance = unit * (MIN_ADVANCE + rnd() * (MAX_ADVANCE - MIN_ADVANCE));
+    width += advance;
+    // A field that has run out of room stops growing, the way a text input
+    // that has scrolled stops showing you where the end is — and the loop
+    // stops with it, so a pasted novel is not a hundred thousand rounds of a
+    // generator whose answer is already known.
+    if (width >= max) return max;
+  }
+  return width;
+}
+
+/**
+ * The points the pen visits, inside a `width` × `height` box.
+ *
+ * **Not in left-to-right order.** A stroke whose `x` only ever increases is a
+ * plot of a function — a waveform, a time series — and it reads as one however
+ * wild the `y` is: the eye follows it as "value against position" and starts
+ * looking for meaning in the peaks. A pen moved at random over a piece of
+ * paper does not do that. It doubles back, crosses what it has already drawn,
+ * and leaves loops.
+ *
+ * So the points are laid out in **columns** — one per column, which is what
+ * guarantees the stroke covers the width it was given rather than knotting
+ * itself in one corner — and then the *visiting order is shuffled*. The pen
+ * therefore starts somewhere in the middle, sweeps across, comes back, and
+ * crosses itself on the way.
+ */
+export function scribblePoints({
+  width,
+  height,
+  seed,
+  points = scribblePointCount(width),
+  group = SCRIBBLE_GROUP,
+  inset = 2,
+}) {
+  const rnd = seededRandom(seed);
+  const span = Math.max(1, height - inset * 2);
+  const usable = Math.max(1, width - inset * 2);
+  const column = usable / points;
+  const out = [];
+  for (let i = 0; i < points; i++) {
+    out.push({
+      // inside its own column, so no two points share a place and the whole
+      // width is used, but nowhere near the middle of it
+      x: inset + i * column + rnd() * column,
+      y: inset + rnd() * span,
+    });
+  }
+  // Fisher-Yates within a sliding group rather than over the whole list. A
+  // full shuffle puts consecutive points a third of the width apart on
+  // average, and in a box this short every one of those moves is a long
+  // shallow sweep — the stroke ends up a bundle of near-horizontal scratches.
+  // Shuffling locally keeps the moves short, so the pen has room to go up and
+  // down between them, and it still doubles back and crosses itself.
+  for (let start = 0; start < out.length; start += group) {
+    const end = Math.min(out.length, start + group);
+    for (let i = end - 1; i > start; i--) {
+      const j = start + Math.floor(rnd() * (i - start + 1));
+      const swap = out[i];
+      out[i] = out[j];
+      out[j] = swap;
+    }
+  }
+  return out;
+}
+
+/**
+ * The pen's path as a **dense polyline**, sampled off a Catmull-Rom spline
+ * through the points — a curve that passes through every one of them rather
+ * than being pulled towards it.
+ *
+ * Sampled here rather than handed to the context as béziers, which is what
+ * this did first. A mask is 17 pixels tall, its control points land within a
+ * pixel of each other constantly, and ntk's stroker answers a curve that
+ * small with the occasional spike: a stray tail shooting out of the field,
+ * several times the width of the mask. The same points drawn as line segments
+ * are exact at any size, and a curve sampled every couple of pixels is
+ * smooth long before anyone can see the difference. (The béziers themselves
+ * are fine — the shape is right when it is drawn eight times bigger — so this
+ * is a workaround for the stroker, not for the geometry.)
+ *
+ * Every sample is clamped into the box, so "the stroke stays in the field" is
+ * arithmetic rather than a hope.
+ */
+export function scribblePath(pts, { width, height, inset = 2 }) {
+  const clampX = (v) => Math.min(width, Math.max(0, v));
+  const clampY = (v) => Math.min(height - inset, Math.max(inset, v));
+  const out = [{ x: clampX(pts[0].x), y: clampY(pts[0].y) }];
+  for (let i = 0; i < pts.length - 1; i++) {
+    const p0 = pts[i - 1] ?? pts[i];
+    const p1 = pts[i];
+    const p2 = pts[i + 1];
+    const p3 = pts[i + 2] ?? p2;
+    const span = Math.abs(p2.x - p1.x) + Math.abs(p2.y - p1.y);
+    const steps = Math.max(3, Math.min(14, Math.round(span / SAMPLE_PX)));
+    for (let step = 1; step <= steps; step++) {
+      const t = step / steps;
+      const t2 = t * t;
+      const t3 = t2 * t;
+      // Catmull-Rom basis, uniform parameterisation
+      const at = (a, b, c, d) =>
+        0.5 *
+        (2 * b +
+          (c - a) * t +
+          (2 * a - 5 * b + 4 * c - d) * t2 +
+          (3 * b - a - 3 * c + d) * t3);
+      out.push({
+        x: clampX(at(p0.x, p1.x, p2.x, p3.x)),
+        y: clampY(at(p0.y, p1.y, p2.y, p3.y)),
+      });
+    }
+  }
+  return out;
+}
+
+/** Stroke the scribble for `seed` into a `width` × `height` box. */
+export function strokeScribble(ctx, { width, height, seed, color, lineWidth }) {
+  if (!(width > 2) || !(height > 2)) return;
+  const inset = 2;
+  const pts = scribblePoints({ width, height, seed, inset });
+  const path = scribblePath(pts, { width, height, inset });
+  ctx.strokeStyle = color;
+  ctx.lineWidth = lineWidth ?? 1.5;
+  ctx.lineCap = 'round';
+  ctx.lineJoin = 'round';
+  ctx.beginPath();
+  ctx.moveTo(path[0].x, path[0].y);
+  for (const point of path.slice(1)) ctx.lineTo(point.x, point.y);
+  ctx.stroke();
+}

package/src/components/theme.js

@@ -1,66 +1,374 @@
 // Widget components built purely on the host primitives — no reconciler
 // support needed. Plain createElement (no JSX) so the library stays
 // build-step-free for consumers.
+//
+// The palettes themselves are in `../palette.js`, one layer down: a `$token`
+// in a style is resolved by walking the *node* tree, which knows nothing
+// about React, and both routes have to agree on what "no theme was given"
+// means.
 
-import React, { useContext, useState } from 'react';
-import { XK_RETURN } from './keys.js';
+import React, { useContext, useMemo, useState } from 'react';
+import { useAppearanceWhen } from '../appearancehooks.js';
+import { EnvValue, registerFrameProvider } from '../frame/env.js';
+import { DarkTheme, DefaultTheme, resolveTheme } from '../palette.js';
 
 const h = React.createElement;
 
-const DefaultTheme = {
-  border: '#b2bec3',
-  borderActive: '#2980b9',
-  background: 'white',
-  text: '#2d3436',
-  dim: '#7f8c8d',
-  hoverBackground: '#2980b9',
-  hoverText: 'white',
-  accent: '#2980b9',
-  accentHover: '#1f6693',
-  accentText: 'white',
-  surfaceHover: '#f1f2f6',
-  track: '#dfe6e9',
-};
+export { DarkTheme, DefaultTheme, resolveTheme };
 
-const ThemeContext = React.createContext(DefaultTheme);
+// `null` means **no provider above here**, which is different from "the
+// default palette": with nothing said, the palette to use is the desktop's,
+// and that is not a constant. `useTheme()` substitutes it, and subscribes so
+// the widget re-renders when the desktop changes.
+//
+// A provider always publishes a complete palette, so nothing downstream ever
+// has to merge again.
+const ThemeContext = React.createContext(null);
 
-/** Themes all widgets; partial palettes merge over the defaults. */
-export const ThemeProvider = ThemeContext.Provider;
+// The provider's box fills its parent, which is what an app-level provider
+// wants; `style` is there for the ones that wrap a single control.
+const FILL = Object.freeze({ flexGrow: 1 });
 
-export const SelectThemeProvider = ThemeContext.Provider; // back-compat alias
+/**
+ * <ThemeProvider value={palette}> — the palette everything below reads, by
+ * both routes at once. A partial palette merges over whatever is already in
+ * force, exactly as a nested `theme` prop merges in the tree.
+ *
+ * There are two consumers and they are not the same mechanism: widgets read
+ * React context through `useTheme()`, while a `$token` in a style resolves
+ * against the nearest `theme` **prop** above the node — resolution walks the
+ * node tree and knows nothing about React. So the provider feeds both: the
+ * merged palette goes on the context *and* onto a real node in the tree.
+ * Skip the second and `<ThemeProvider value={dark}>` over
+ * `<box style={{ color: '$text' }}>` silently paints nothing (#119).
+ *
+ * ## What "already in force" means
+ *
+ * **The desktop's palette.** With no provider at all an app is dark on a dark
+ * desktop, so a provider that names an accent and a corner radius keeps
+ * following the desktop for everything it did not name — which is what an app
+ * that wants to look like it belongs there wants, and what it would have had
+ * to write `dark={…}` by hand for otherwise.
+ *
+ * `colorScheme` is the override, for an app that owns the choice rather than
+ * the desktop — a preference in its own settings, or a design that only works
+ * one way:
+ *
+ * ```jsx
+ * <ThemeProvider value={brand} colorScheme="light">   // never follows
+ * <ThemeProvider value={brand} colorScheme={settings.theme}>
+ * ```
+ *
+ * `dark` is the other half: a palette layered on only when the scheme in
+ * force is dark, for a design whose two schemes are not one recolour of the
+ * other.
+ *
+ * ```jsx
+ * <ThemeProvider value={light} dark={{ background: '#101418' }}>
+ * ```
+ *
+ * The desktop's **accent** is deliberately not adopted on its own: an app in
+ * dark mode did not ask for its buttons to change colour, and most portal
+ * backends report no accent at all. Take it explicitly where you want it, and
+ * keep a fallback:
+ *
+ * ```jsx
+ * const { accent } = useSystemAppearance();
+ * <ThemeProvider value={{ ...brand, accent: accent ?? brand.accent }}>
+ * ```
+ */
+export function ThemeProvider({
+  value,
+  dark,
+  colorScheme = 'system',
+  style,
+  children,
+}) {
+  const outer = useContext(ThemeContext);
+  // **Pinning is the complete opt-out.** A provider that names its own scheme
+  // subscribes to nothing, and the widgets under it read the provided palette
+  // rather than the store — so an app that does not want react-x11 asking the
+  // desktop anything says `colorScheme="light"` once at the top.
+  const follows = colorScheme === 'system';
+  const system = useAppearanceWhen(follows);
+  const wantsDark =
+    colorScheme === 'dark' || (follows && system.colorScheme === 'dark');
+  const theme = useMemo(
+    () =>
+      // An outer provider is the base; with none, the base is the scheme's
+      // own built-in palette. So `value` names what this app changes and
+      // everything else keeps following the desktop.
+      resolveTheme(
+        dark && wantsDark ? { ...value, ...dark } : value,
+        outer ?? (wantsDark ? DarkTheme : DefaultTheme),
+      ),
+    [outer, value, dark, wantsDark],
+  );
+  // A provider that **names** a direction plants it as a style too, so the
+  // node tree mirrors along with the widgets: `useTheme().direction` is what
+  // a `<Slider>` reads, and the `direction` style property is what yoga
+  // reads, and they have to be the same answer. Only when this provider named
+  // it — every provider publishes a *complete* palette, so planting
+  // `theme.direction` unconditionally would pin an inner provider's subtree
+  // back to LTR inside a `<box style={{ direction: 'rtl' }}>`.
+  const named = value?.direction ?? (wantsDark ? dark?.direction : undefined);
+  const boxStyle = useMemo(() => {
+    const base = named ? [FILL, { direction: named }] : [FILL];
+    return style ? [...base, style] : base.length === 1 ? FILL : base;
+  }, [style, named]);
+  return h(
+    ThemeContext.Provider,
+    { value: theme },
+    // The palette also crosses into any <Frame> below here (THEME_ENV_KEY):
+    // it is the one ambient thing the *app* authors, so a pane that said
+    // nothing about colour comes up in the app's palette rather than one
+    // frame of default. With no provider at all nothing is published, and
+    // the pane follows the desktop by itself — same answer, no bridge.
+    h(
+      EnvValue,
+      { k: THEME_ENV_KEY, value: theme },
+      planted(children, theme, boxStyle),
+    ),
+  );
+}
+
+/** What the theme is called on a frame's wire (docs/frame.md). */
+export const THEME_ENV_KEY = 'react-x11:theme';
+
+// The child half of the default theme bridge: recreate with the *real*
+// provider, because the palette travels two routes — the context widgets
+// read, and the `theme` prop planted on a node so `$token` styles resolve
+// (#119) — and only ThemeProvider itself feeds both. The bridged value is
+// the complete merged palette, so it wins every token; a pane's own inner
+// ThemeProvider still overrides below it, which is the opt-out a pane that
+// wants its own look already has.
+registerFrameProvider(
+  THEME_ENV_KEY,
+  (value, children) => h(ThemeProvider, { value }, children),
+  // directly around the pane's window: `planted` puts the palette on a
+  // window among its direct children, and the window is where it must land
+  { innermost: true },
+);
+
+/**
+ * The node that carries the palette into the tree. Normally a box — but a
+ * `<window>` may only be a root child or nested in another window, never
+ * inside a box, so a provider above one plants the prop on the windows
+ * themselves instead of coming between them. An explicit `theme` on a child
+ * still wins, since that is what it means everywhere else.
+ */
+function planted(children, theme, style) {
+  const kids = React.Children.toArray(children);
+  if (kids.some((k) => React.isValidElement(k) && k.type === 'window')) {
+    return kids.map((k) =>
+      React.isValidElement(k)
+        ? React.cloneElement(k, { theme: k.props.theme ?? theme })
+        : k,
+    );
+  }
+  return h('box', { theme, style }, children);
+}
 
+/**
+ * The palette in force here — already merged over any outer provider, and the
+ * same object the provider planted in the tree, so `useTheme()` and a `$token`
+ * always read one palette.
+ *
+ * **With no provider it is the desktop's**, and this re-renders when the
+ * desktop changes, which is what makes a react-x11 app that says nothing
+ * about colour go dark on a dark desktop. `node.theme` in `nodes.js` answers
+ * the same question for the other route.
+ *
+ * Identity matters: widgets plant what this returns on their own root node,
+ * and a fresh object every render would re-resolve every `$token` beneath it
+ * and defeat the resolution cache. Both built-in palettes are module
+ * constants, so the unprovided answer is stable too.
+ */
 export function useTheme() {
-  const theme = useContext(ThemeContext);
-  return theme === DefaultTheme ? theme : { ...DefaultTheme, ...theme };
+  const provided = useContext(ThemeContext);
+  const system = useAppearanceWhen(provided == null);
+  if (provided) return provided;
+  return system.colorScheme === 'dark' ? DarkTheme : DefaultTheme;
 }
 
-/** Shared interactive-control plumbing: hover/focus state plus the box
- * props wiring them, click + Space/Enter activation. */
-export function useControl(disabled, onActivate) {
+/**
+ * Which way the widgets here read — `'ltr'` or `'rtl'`.
+ *
+ * **What a widget mirrors is not what a box mirrors.** Yoga mirrors the boxes
+ * on its own from the `direction` style property, so most of the widget set
+ * needs nothing from this: a `<Checkbox>` is a `row` with a gap and a
+ * `<ProgressBar>` is two flex ratios, and both come out mirrored without a
+ * line of code. This is for the decisions yoga cannot make — which way an
+ * arrow key steps, which way a glyph points, which side a menu opens on.
+ *
+ * It comes from the palette because that is the channel a widget can read
+ * during its own render, and because an app with a language menu is already
+ * swapping a `<ThemeProvider>`. The provider plants the matching style
+ * property as it goes, so the boxes and the widgets under it mirror together.
+ *
+ * The one case the two can part company is a bare `<box style={{ direction:
+ * 'rtl' }}>` wrapped around widgets with no provider: the layout mirrors and
+ * a widget's own arithmetic does not. Use a `<ThemeProvider>` to mirror a
+ * region that contains widgets. Where a widget is measuring a **pointer**
+ * against a laid-out box it reads `node.direction` instead — the coordinate
+ * has to be interpreted in the direction the box was really laid out in, or a
+ * drag runs backwards.
+ */
+export function useDirection() {
+  return useTheme().direction === 'rtl' ? 'rtl' : 'ltr';
+}
+
+/**
+ * Shared interactive-control plumbing: hover/focus/press state plus the box
+ * props wiring them, click + Space/Enter activation.
+ *
+ * `styled: true` says the widget expresses hover, focus and the press with
+ * `:hover`, `:focus` and `:active` style blocks. Then none of it is React
+ * state: no enter/leave handlers, no re-render on pointer move, and the
+ * returned `hover`/`focused`/`pressed` stay false. **Prefer it.** The state
+ * blocks are a repaint of one node where the React state is a re-render of
+ * the widget and its label.
+ *
+ * The exception is a control whose pressed part is not the node the press
+ * lands on. `:active` marks the press chain — the pressed node and its
+ * ancestors — so a `<Checkbox>` pressed anywhere along its row cannot light
+ * up its 16px well that way, the well being a sibling of the label rather
+ * than an ancestor of it. There the press is React state, which costs one
+ * render for a discrete event that in the ordinary case was about to
+ * re-render anyway when the value changed.
+ */
+export function useControl(disabled, onActivate, { styled = false } = {}) {
   const [hover, setHover] = useState(false);
   const [focused, setFocused] = useState(false);
+  const [pressed, setPressed] = useState(false);
+  const activation = {
+    focusable: true,
+    // The click, and nothing else: Space and Enter are a click on anything
+    // with an `onClick` now (`Node.defaultKeyDown`, issue #329), so the
+    // hand-rolled key mapping that used to live here is gone — and with it
+    // the reason a widget answered the keyboard while a hand-built control
+    // beside it did not.
+    //
+    // the event travels: `ButtonProps.onPress` has always been declared as
+    // taking one, and a handler that wants `ev.shiftKey` or `ev.detail` —
+    // shift-click, double-click — has no other way to get it. From the
+    // keyboard it is the synthesized click, carrying the key press's own
+    // modifiers, so Shift+Enter still reads as a shift-click.
+    onClick: (ev) => onActivate?.(ev),
+  };
   const props = disabled
-    ? {}
-    : {
-        focusable: true,
-        cursor: 'pointer',
-        onMouseEnter: () => setHover(true),
-        onMouseLeave: () => setHover(false),
-        onFocus: () => setFocused(true),
-        onBlur: () => setFocused(false),
-        onClick: () => onActivate?.(),
-        onKeyDown: (ev) => {
-          if (ev.codepoint === 32 || ev.keysym === XK_RETURN) onActivate?.();
-        },
-      };
-  return { hover: hover && !disabled, focused: focused && !disabled, props };
+    ? // the node still has to *say* it is disabled: `:disabled` style
+      // blocks, the focus rule and the AT-SPI ENABLED state all read the
+      // prop off the node, not off the widget's closure
+      { disabled: true }
+    : styled
+      ? activation
+      : {
+          ...activation,
+          onMouseEnter: () => setHover(true),
+          // a press released off the control never sends it a mouseup, so
+          // leaving is what ends the press — which is also what it means:
+          // releasing out there activates nothing
+          onMouseLeave: () => {
+            setHover(false);
+            setPressed(false);
+          },
+          onMouseDown: () => setPressed(true),
+          onMouseUp: () => setPressed(false),
+          onFocus: () => setFocused(true),
+          onBlur: () => {
+            setFocused(false);
+            setPressed(false);
+          },
+        };
+  return {
+    hover: !styled && hover && !disabled,
+    focused: !styled && focused && !disabled,
+    pressed: !styled && pressed && !disabled,
+    props,
+    // `cursor` is style, so it travels in the style channel — put it first
+    // in the widget's style array and anything it declares still wins
+    style: disabled ? undefined : POINTER,
+  };
 }
 
-/** String/number children become a <text>; elements pass through. */
-export function labelContent(children, textProps) {
+const POINTER = Object.freeze({ cursor: 'pointer' });
+
+/**
+ * What every widget label is measured to: the capitals down to the last
+ * baseline, rather than the font's line box.
+ *
+ * **A line box is not the letters.** It is ascent plus descent plus line
+ * gap, and the space it leaves over a capital differs from the space under a
+ * baseline by `(ascent - capHeight) - descent` — a property of the typeface,
+ * not of the design. So a label centred in a row, or padded inside a button,
+ * is only ever optically even by luck, and which way it is off changes with
+ * the font: at 14px, SF NS leaves 3.7px above the cap against 2.9px below
+ * the baseline and the label rides low, while Helvetica leaves 0.7 against
+ * 3.2 and it rides high. Nothing in the widget can correct for that, because
+ * the widget does not know the face it will be drawn in.
+ *
+ * Trimming makes the box *be* the letters, so the padding around a label is
+ * the padding you asked for and centring centres what can be seen. It is
+ * `textBoxTrim` in styling.md — CSS's `text-box-trim: trim-both` with
+ * `text-box-edge: cap alphabetic` — and the palette's `paddingY` is sized
+ * for the trimmed box.
+ *
+ * **Labels, not glyph marks.** A check, a submenu arrow or an icon drawn as
+ * text is centred on its own middle rather than sitting on a baseline, and
+ * cap-trimming its box moves it off centre. Those keep the full line box.
+ */
+export const capTrim = Object.freeze({ textBoxTrim: 'cap-alphabetic' });
+
+/**
+ * How tall a trimmed single-line label comes out at this size — the band the
+ * space around a row has to be even about.
+ *
+ * From the size rather than from the face on purpose: a popup is **sized
+ * before it is laid out** (a menu is an X window, and its width and height go
+ * to the server with the map request), so the row height cannot wait for a
+ * font to be matched. Cap height is 0.70–0.73em in every UI face measured —
+ * Arial .717, Helvetica .717, SF NS .704, Verdana .727, DejaVu .729 — so this
+ * lands within a pixel of the metrics for all of them, and the trim keeps the
+ * label centred inside whatever it lands on.
+ */
+export const capBand = (fontSize) => Math.round(fontSize * 0.72);
+
+/**
+ * The geometry of rows on a rounded sheet: how far a row sits inside the
+ * sheet's edge, and how round its own corners are.
+ *
+ * **Concentric corners.** A rounded rect inside a rounded rect only looks
+ * like one shape when the two curves share a centre, which happens exactly
+ * when the inner radius is the outer radius less the gap between them. Any
+ * other pairing leaves the pill's corner either tighter or wider than the
+ * sheet's, and the eye reads the mismatch as a wobble along the corner even
+ * where it cannot name it. So the inset and the pill's radius are not two
+ * numbers a widget picks: given the sheet's radius, choosing one fixes the
+ * other, and this returns the pair.
+ *
+ * The inset is the free choice — a pill has to be *seen* to be inset, and it
+ * is also what the popup's own size was measured with — so the widget names
+ * it and the radius follows. `radiusPopupItem` is the ceiling rather than the
+ * value: a theme that wants rounder pills says so by rounding the sheet they
+ * sit on, which is the only way the two can agree.
+ */
+export const rowRadius = (theme, border, inset) =>
+  Math.max(
+    0,
+    Math.min(
+      theme.radiusPopupItem ?? Infinity,
+      (theme.radiusPopup ?? 0) - border - inset,
+    ),
+  );
+
+/** String/number children become a `<text>` with `style`; elements pass
+ * through untouched. Strings are labels, so they are trimmed to their
+ * letters — see {@link capTrim}. */
+export function labelContent(children, style) {
   return React.Children.map(children, (child) =>
     typeof child === 'string' || typeof child === 'number'
-      ? h('text', textProps, child)
+      ? h('text', { style: [capTrim, style] }, child)
       : child,
   );
 }