react-x11 2.2.0 → 2.3.0

package/src/components/Select.js

@@ -3,8 +3,16 @@
 // build-step-free for consumers.
 
 import React, { useEffect, useRef, useState } from 'react';
+import { useAppOrNull } from '../appcontext.js';
 import { capBand, capTrim, rowRadius, useTheme } from './theme.js';
 import { Icon } from './Icon.js';
+import {
+  ABS_FILL,
+  Bezel,
+  bezelNatural,
+  pressWash,
+  useNativeControls,
+} from './native.js';
 import { changeEvent } from './change.js';
 import {
   anchorArea,
@@ -184,10 +192,13 @@ export function Select({
   onChange,
   name,
   placeholder = 'Select…',
+  native,
   style,
   ...boxProps
 }) {
   const theme = useTheme();
+  const app = useAppOrNull();
+  const nativeControls = useNativeControls(native);
   const [open, setOpen] = useState(false);
   const [anchor, setAnchor] = useState(null);
   const [focused, setFocused] = useState(false);
@@ -336,25 +347,38 @@ export function Select({
       onKeyDown,
       ...boxProps,
       style: [
-        {
-          cursor: 'pointer',
-          flexDirection: 'row',
-          alignItems: 'center',
-          gap: 8,
-          // The vertical padding is the palette's, the same one a `<Button>`
-          // takes, because these are controls of one family and a form puts
-          // them in a row together. Horizontally it is its own, tighter
-          // number: a dropdown is a field with a value in it, not a button
-          // with a word centred on it.
-          paddingTop: theme.paddingY,
-          paddingBottom: theme.paddingY,
-          paddingLeft: 10,
-          paddingRight: 10,
-          borderWidth: theme.borderWidth,
-          borderRadius: theme.radius,
-          borderColor: focused || open ? theme.borderFocus : theme.border,
-          backgroundColor: theme.surface,
-        },
+        nativeControls
+          ? // The native popup bezel carries the border, the fill and the
+            // arrow capsule, so the trigger keeps only its row layout and
+            // AppKit's own height. The right padding clears the arrows.
+            {
+              cursor: 'pointer',
+              flexDirection: 'row',
+              alignItems: 'center',
+              gap: 8,
+              height: bezelNatural(app, 'popup').height,
+              paddingLeft: 10,
+              paddingRight: 26,
+            }
+          : {
+              cursor: 'pointer',
+              flexDirection: 'row',
+              alignItems: 'center',
+              gap: 8,
+              // The vertical padding is the palette's, the same one a `<Button>`
+              // takes, because these are controls of one family and a form puts
+              // them in a row together. Horizontally it is its own, tighter
+              // number: a dropdown is a field with a value in it, not a button
+              // with a word centred on it.
+              paddingTop: theme.paddingY,
+              paddingBottom: theme.paddingY,
+              paddingLeft: 10,
+              paddingRight: 10,
+              borderWidth: theme.borderWidth,
+              borderRadius: theme.radius,
+              borderColor: focused || open ? theme.borderFocus : theme.border,
+              backgroundColor: theme.surface,
+            },
         // Hover and press belong to the trigger while it is *shut*: they say
         // "this opens". Once the menu is down that is answered, and the
         // trigger's job is to read as one surface with the popup hanging off
@@ -364,13 +388,25 @@ export function Select({
         // state block always outranks the base style, so there is no colour
         // the open state could put in `backgroundColor` that `:hover` would
         // not overwrite. The only way for open to win is to not be competing.
-        !open && {
-          ':hover': { backgroundColor: theme.surfaceHover },
-          ':active': { backgroundColor: theme.surfaceActive },
-        },
+        // (In native mode the wash overlay below answers the press instead.)
+        !nativeControls &&
+          !open && {
+            ':hover': { backgroundColor: theme.surfaceHover },
+            ':active': { backgroundColor: theme.surfaceActive },
+          },
         style,
       ],
     },
+    // `pressed` while the menu is down: AppKit's popup answers being open
+    // by highlighting the arrow capsule, which is the open look this
+    // trigger otherwise lost with its borderFocus.
+    nativeControls &&
+      h(Bezel, {
+        kind: 'popup',
+        pressed: open,
+        enabled: true,
+        style: ABS_FILL,
+      }),
     h(
       'text',
       { style: [capTrim, { color: current ? theme.text : theme.textMuted }] },
@@ -382,11 +418,20 @@ export function Select({
     // row have to be one height, and they only are if the tallest thing in
     // each is measured the same way. A glyph taller than the cap band makes
     // the dropdown alone two pixels taller than everything next to it.
-    h(Icon, {
-      name: 'chevronDown',
-      size: capBand(theme.fontSize),
-      color: theme.textMuted,
-    }),
+    // The native bezel draws its own arrow capsule instead.
+    nativeControls
+      ? h('box', {
+          style: [
+            ABS_FILL,
+            { borderRadius: 6 },
+            !open && { ':active': { backgroundColor: pressWash(theme) } },
+          ],
+        })
+      : h(Icon, {
+          name: 'chevronDown',
+          size: capBand(theme.fontSize),
+          color: theme.textMuted,
+        }),
     open &&
       anchor &&
       h(

package/src/components/Slider.js

@@ -3,6 +3,8 @@
 // build-step-free for consumers.
 
 import React, { useRef, useState } from 'react';
+import { useAppOrNull } from '../appcontext.js';
+import { Bezel, bezelNatural, useNativeControls } from './native.js';
 import { useTheme } from './theme.js';
 import { changeEvent } from './change.js';
 import {
@@ -42,10 +44,13 @@ export function Slider({
   name,
   disabled = false,
   height = 4,
+  native,
   style,
   ...boxProps
 }) {
   const theme = useTheme();
+  const app = useAppOrNull();
+  const nativeControls = useNativeControls(native);
   const [focused, setFocused] = useState(false);
   const [dragging, setDragging] = useState(false);
   const trackRef = useRef(null);
@@ -152,6 +157,60 @@ export function Slider({
         },
       };
 
+  // The whole control as one NSSlider render, keyed by the value so a drag
+  // is a sequence of cached-or-rendered bezels. Pointer math, keyboard and
+  // a11y are the shared implementation above — the bezel is presentation.
+  //
+  // The *small* control size on purpose: its 16pt knob is exactly the
+  // drawn thumb's footprint, so rows laid out for the drawn slider fit,
+  // and the pointer math shares one thumb constant across both modes —
+  // the regular size's 20pt knob overflowed every compact row it met.
+  if (nativeControls) {
+    const nat = bezelNatural(app, 'slider', 'small');
+    return h(
+      'box',
+      {
+        theme,
+        role: 'slider',
+        'aria-valuenow': clamp(value),
+        'aria-valuemin': min,
+        'aria-valuemax': max,
+        'aria-orientation': 'horizontal',
+        ref: trackRef,
+        ...controlProps,
+        ...boxProps,
+        style: [
+          disabled || { cursor: 'pointer' },
+          {
+            height: nat.height,
+            minWidth: 0,
+            hitSlop: {
+              top: Math.max(0, (24 - nat.height) / 2),
+              bottom: Math.max(0, (24 - nat.height) / 2),
+            },
+          },
+          style,
+        ],
+      },
+      h(Bezel, {
+        kind: 'slider',
+        controlSize: 'small',
+        // quantized so a drag reuses cache entries instead of minting one
+        // per sub-pixel float; 400 steps is finer than any track is wide
+        value: Math.round(fraction * 400) / 400,
+        enabled: !disabled,
+        style: {
+          position: 'absolute',
+          top: 0,
+          right: 0,
+          bottom: 0,
+          left: 0,
+          pointerEvents: 'none',
+        },
+      }),
+    );
+  }
+
   return h(
     'box',
     {

package/src/components/Switch.js

@@ -3,8 +3,16 @@
 // build-step-free for consumers.
 
 import React from 'react';
+import { useAppOrNull } from '../appcontext.js';
 import { createStyles } from '../styles.js';
 import { changeEvent } from './change.js';
+import {
+  ABS_FILL,
+  Bezel,
+  bezelNatural,
+  pressWash,
+  useNativeControls,
+} from './native.js';
 import { useControl, useTheme } from './theme.js';
 
 const h = React.createElement;
@@ -74,15 +82,59 @@ export function Switch({
   onChange,
   name,
   disabled = false,
+  native,
   style,
   ...boxProps
 }) {
   const theme = useTheme();
+  const app = useAppOrNull();
+  const nativeControls = useNativeControls(native);
   const control = useControl(
     disabled,
     () => onChange?.(changeEvent('checkbox', name, !checked)),
     { styled: true },
   );
+
+  // NSSwitch's own pixels, on/off as two cached bezels. The knob slide is
+  // the fidelity this loses for now (docs/macos.md flags the switch as the
+  // one control worth revisiting if that disappoints); the press keeps its
+  // answer as the wash, since NSSwitch renders no pressed state offscreen.
+  if (nativeControls) {
+    const nat = bezelNatural(app, 'switch');
+    return h(
+      'box',
+      {
+        theme,
+        role: 'switch',
+        'aria-checked': checked,
+        ...control.props,
+        ...boxProps,
+        style: [
+          control.style,
+          {
+            width: nat.width,
+            height: nat.height,
+            hitSlop: Math.max(0, (24 - nat.height) / 2),
+          },
+          style,
+        ],
+      },
+      h(Bezel, {
+        kind: 'switch',
+        state: checked ? 1 : 0,
+        enabled: !disabled,
+        style: ABS_FILL,
+      }),
+      h('box', {
+        style: [
+          ABS_FILL,
+          { borderRadius: nat.height / 2 },
+          !disabled && { ':active': { backgroundColor: pressWash(theme) } },
+        ],
+      }),
+    );
+  }
+
   return h(
     'box',
     {

package/src/components/native.js

@@ -0,0 +1,142 @@
+// The native half of the widget set (docs/macos.md §Native controls).
+//
+// House rule: **default native, seam out.** On a backend that renders the
+// platform's own control bezels — today the Cocoa backend — the core
+// controls wear AppKit's pixels while interaction, focus, keyboard and
+// a11y stay the shared implementation. The mechanism is a bezel *image*
+// drawn through the ordinary paint path, never an embedded platform view:
+// the press model, the focus rules and the event routing are behaviour this
+// project considers part of its identity, and a real NSControl would take
+// them over wholesale.
+//
+// The policy lives in the theme (`controls: 'auto' | 'native' | 'drawn'`),
+// because whether an app looks native is an app-identity decision, not a
+// per-node style. The per-instance escape hatch is `native={false}` on the
+// one custom-branded control — a themed `style` override is ignored by a
+// native bezel, so a control that names its own colours should also name
+// `native={false}` (the widgets keep today's drawn rendering everywhere the
+// bezel is off, so custom-designed apps lose nothing).
+
+import React, { useCallback } from 'react';
+import { useAppOrNull } from '../appcontext.js';
+import { useTheme } from './theme.js';
+
+const h = React.createElement;
+
+let warnedUnsupported = false;
+
+/**
+ * Should this control render the platform bezel? Combines the per-instance
+ * `native` prop, the theme's `controls` policy and the backend capability.
+ * An explicit `controls: 'native'` on a backend without the capability
+ * warns once and draws — erroring would make the same app code illegal on
+ * X11, which is the opposite of what a cross-backend widget set is for.
+ */
+export function useNativeControls(native) {
+  const app = useAppOrNull();
+  const theme = useTheme();
+  const capable = Boolean(app?.nativeBezels);
+  if (native === false) return false;
+  const mode = native === true ? 'native' : (theme.controls ?? 'auto');
+  if (mode === 'drawn') return false;
+  if (mode === 'native' && !capable && !warnedUnsupported) {
+    warnedUnsupported = true;
+    console.warn(
+      "react-x11: controls: 'native' — this backend has no native control " +
+        'rendering; the themed drawn controls are used instead.',
+    );
+  }
+  return capable;
+}
+
+/**
+ * The control's natural size in logical px — AppKit's own metrics, which
+ * native-mode layout adopts (a stretched checkbox is a wrong checkbox).
+ * `null` where there is no bezel store, so callers can guard in one step.
+ */
+export function bezelNatural(app, kind, controlSize = 'regular') {
+  return app?.nativeBezels?.natural(kind, controlSize) ?? null;
+}
+
+/** Absolute fill inside the control's box — where every bezel layer goes. */
+export const ABS_FILL = Object.freeze({
+  position: 'absolute',
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+});
+
+/**
+ * The press wash — the one hover/press affordance native mode keeps.
+ * AppKit's controls have no hover state, so hover tints are deliberately
+ * absent here; the press is answered with a translucent wash over the
+ * bezel, dark on light and light on dark, the direction macOS itself steps
+ * a pressed control.
+ */
+export const pressWash = (theme) =>
+  theme.scheme === 'dark' ? 'rgba(255,255,255,0.12)' : 'rgba(0,0,0,0.07)';
+
+/**
+ * `<Bezel kind …states style>` — one AppKit bezel, rendered at exactly the
+ * box layout gives it. A `<canvas>` under the hood: the bezel comes out of
+ * the app's `BezelStore` (cached by every parameter that changes the
+ * pixels) and is blitted with the 9-arg `drawImage`, so a state change is a
+ * cache lookup and one blit, bounded to this node's damage.
+ */
+export function Bezel({
+  kind,
+  state = 0,
+  pressed = false,
+  enabled = true,
+  isDefault = false,
+  value,
+  controlSize = 'regular',
+  style,
+}) {
+  const app = useAppOrNull();
+  const theme = useTheme();
+  // The theme in force decides the bezel's appearance, not the desktop: a
+  // pinned-light app on a dark desktop gets light bezels beside its light
+  // surfaces. `scheme` is the palette's own statement of which it is.
+  const appearance = theme.scheme === 'dark' ? 'dark' : 'light';
+  const params = {
+    kind,
+    controlSize,
+    state: state ? 1 : 0,
+    pressed: Boolean(pressed),
+    enabled: Boolean(enabled),
+    isDefault: Boolean(isDefault),
+    appearance,
+  };
+  if (value !== undefined) params.value = value;
+  const sig = JSON.stringify(params);
+  const store = app?.nativeBezels;
+  // Keyed on the parameter signature so an unchanged bezel keeps its
+  // `onDraw` identity — CanvasNode invalidates when the closure changes,
+  // and a Button re-rendered by its parent must not repaint its bezel.
+  const onDraw = useCallback(
+    (ctx, info) => {
+      if (!store || !info.width || !info.height) return;
+      const bezel = store.get(
+        JSON.parse(sig),
+        info.width,
+        info.height,
+        info.scale,
+      );
+      ctx.drawImage(
+        { _surfaceHandle: bezel.surface },
+        bezel.sx,
+        bezel.sy,
+        bezel.sw,
+        bezel.sh,
+        0,
+        0,
+        info.width,
+        info.height,
+      );
+    },
+    [store, sig],
+  );
+  return h('canvas', { onDraw, style });
+}

package/src/decorations.js

@@ -30,6 +30,12 @@
 // - `textShadow`: per glyph, through the glyph cache, and much rarer in a
 //   desktop UI.
 
+// The kernel maths is ntk's: `blurCoverage` runs the blur, so the reach it
+// derives is the padding a coverage surface has to carry. Both are pure
+// functions — no connection, nothing drawn — so this module stays testable
+// without a server.
+import { shadowReach, shadowSigma } from 'ntk';
+
 /** A number, with or without the `px` CSS wants and this vocabulary does not. */
 const LENGTH = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:px)?$/i;
 /** …and the same thing as a percentage, which colour stops also take. */
@@ -366,36 +372,27 @@ function readShadow(part, value) {
 }
 
 /**
- * The gaussian a CSS blur radius means, and the room it needs.
+ * The gaussian a `blur` asks for, and the padding its coverage surface needs.
  *
- * CSS defines the blur radius as *twice* the standard deviation, and ntk's
- * `Picture.setBlurFilter(size, sigma)` takes the convolution kernel's edge
- * length rather than a radius — so the two names that look like they match
- * are the two that must not be passed to each other. The kernel is cut at
- * 3σ, where the gaussian is down to 1% and the truncation is invisible;
- * `pad` is the same distance, and it is what stops the blur clipping square
- * against the edge of the surface it was rendered into.
+ * CSS defines the blur radius as *twice* the standard deviation, so the two
+ * names that look like they match are the two that must not be passed to
+ * each other; `shadowSigma` is the halving, and it applies ntk's policy cap
+ * so a 4000px blur asked for by accident cannot become a kernel nothing
+ * finishes.
  *
- * `MAX_KERNEL` bounds a pathological value: the server convolves N² taps per
- * pixel, so a 200px blur asked for by accident would otherwise be a frame
- * that never lands.
+ * `pad` is the reach of the kernel **ntk will actually run** — that is why
+ * it comes from `shadowReach` rather than from arithmetic of our own. The
+ * blur is baked by `blurCoverage`, which derives its own kernel from sigma,
+ * and a surface padded by less than that reach ends the shadow in a straight
+ * line where the kernel ran out of pixels. The two numbers have to agree and
+ * nothing about a wrong answer looks like a bug, so they come from one
+ * place. The extra pixel is slack against the rounding above.
  */
-const MAX_KERNEL = 61;
-
 export function blurKernel(blur) {
-  const sigma = blur / 2;
-  const reach = Math.ceil(3 * sigma);
-  const size = Math.min(MAX_KERNEL, 2 * reach + 1);
-  return { sigma, size, pad: (size - 1) / 2 + 1 };
+  const sigma = shadowSigma(blur);
+  return { sigma, pad: sigma > 0 ? shadowReach(sigma) + 1 : 0 };
 }
 
-/**
- * How far outside the node's own box this shadow list reaches, in device
- * pixels — the damage inflation, and the reason a shadow is not just a
- * colour. Symmetric on purpose: a shadow offset down and right claims the
- * same slack above and left, which costs a few pixels of repaint and saves
- * every caller from carrying four numbers around.
- */
 export function shadowExtent(shadows) {
   let extent = 0;
   for (const s of shadows ?? []) {

package/src/editmenu.js

@@ -21,6 +21,11 @@
  */
 import { formatShortcut, isSeparator } from './menuitem.js';
 
+// Logical px, multiplied by the display scale where they are used: the
+// menu's text is measured and painted in device pixels (fonts are sized on
+// the device grid), so the chrome around it has to live on the same grid —
+// unscaled constants against scaled glyph ink is rows shorter than their
+// own labels (the compact-menu bug, first seen on the 2x Cocoa backend).
 const ROW_HEIGHT = 22;
 const SEPARATOR_HEIGHT = 7;
 const PAD_X = 10;
@@ -143,33 +148,35 @@ export function editMenuItems(actions = {}, { canPaste = true } = {}) {
  * @param {(text: string) => number|null} [measure] text width, or null when
  *   nothing can be measured yet
  */
-export function editMenuGeometry(items, measure) {
+export function editMenuGeometry(items, measure, scale = 1) {
   const widthOf = (text) => {
     if (!text) return 0;
     const w = measure?.(text);
     return typeof w === 'number' && w > 0
       ? w
-      : text.length * FALLBACK_CHAR_WIDTH;
+      : text.length * FALLBACK_CHAR_WIDTH * scale;
   };
   const rows = [];
-  let y = PAD_Y;
+  let y = PAD_Y * scale;
   let widest = 0;
   for (const item of items) {
     const separator = isSeparator(item);
     const shortcut = formatShortcut(item.shortcut);
-    const height = separator ? SEPARATOR_HEIGHT : ROW_HEIGHT;
+    const height = (separator ? SEPARATOR_HEIGHT : ROW_HEIGHT) * scale;
     rows.push({ ...item, separator, shortcut, y, height });
     y += height;
     if (separator) continue;
     widest = Math.max(
       widest,
-      widthOf(item.label) + (shortcut ? SHORTCUT_GAP + widthOf(shortcut) : 0),
+      widthOf(item.label) +
+        (shortcut ? SHORTCUT_GAP * scale + widthOf(shortcut) : 0),
     );
   }
   return {
     rows,
-    width: Math.max(MIN_WIDTH, Math.ceil(widest + PAD_X * 2)),
-    height: Math.ceil(y + PAD_Y),
+    scale,
+    width: Math.max(MIN_WIDTH * scale, Math.ceil(widest + PAD_X * scale * 2)),
+    height: Math.ceil(y + PAD_Y * scale),
   };
 }
 
@@ -220,12 +227,14 @@ export function paintEditMenu(
   { geometry, active = -1, colors = EDIT_MENU_COLORS, layoutOf, radius = 4 },
 ) {
   const { width, height, rows } = geometry;
+  const s = geometry.scale ?? 1;
+  const padX = PAD_X * s;
 
-  panelPath(ctx, width, height, radius);
+  panelPath(ctx, width, height, radius * s);
   ctx.fillStyle = colors.background;
   ctx.fill();
   ctx.strokeStyle = colors.border;
-  ctx.lineWidth = 1;
+  ctx.lineWidth = s;
   ctx.stroke();
 
   const label = (text, color, x, row) => {
@@ -241,10 +250,10 @@ export function paintEditMenu(
     if (row.separator) {
       ctx.fillStyle = colors.separator;
       ctx.fillRect(
-        PAD_X,
+        padX,
         Math.round(row.y + row.height / 2) + 0.5,
-        width - PAD_X * 2,
-        1,
+        width - padX * 2,
+        s,
       );
       continue;
     }
@@ -259,14 +268,14 @@ export function paintEditMenu(
       : on
         ? colors.highlightText
         : colors.text;
-    label(row.label, color, PAD_X, row);
+    label(row.label, color, padX, row);
     if (row.shortcut) {
       // the shortcut column stays quieter than the label, except in the
       // highlighted row where it has to stay legible on the accent
       const shortcutColor = on ? colors.highlightText : colors.dim;
       const layout = layoutOf?.(row.shortcut, shortcutColor);
       const w = layout?.width ?? 0;
-      label(row.shortcut, shortcutColor, width - PAD_X - w, row);
+      label(row.shortcut, shortcutColor, width - padX - w, row);
     }
   }
 }

package/src/errors.js

@@ -59,6 +59,48 @@ export function reportHandlerError(node, handler, error) {
   markFailed();
 }
 
+/**
+ * `REACT_X11_STRICT_TOKENS=1` makes a `$token` the theme does not define
+ * fatal again, for a build that would rather stop than paint something
+ * wrong. The default reports and carries on — see `reportStyleError`.
+ *
+ * Guarded rather than a bare `process.env` because the playground bundle
+ * runs in a browser, where there is no `process` at all.
+ */
+export const STRICT_TOKENS =
+  (typeof process === 'undefined'
+    ? undefined
+    : process.env?.REACT_X11_STRICT_TOKENS) === '1';
+
+/** Messages already printed, so a shared misspelled style reports once per
+ *  (node, message) rather than once per restyle — a theme swap re-resolves
+ *  the whole subtree and would otherwise print the same line every time. */
+const reportedStyleErrors = new WeakMap();
+
+/**
+ * A style the node cannot resolve — today only an unknown `$token`.
+ *
+ * Not a throw, and deliberately: the mistake is one property in one style,
+ * and the tree it would take down is the whole GUI. The property is dropped
+ * (so the widget paints without it, visibly wrong), the message names the
+ * token and whose element wore it, and `process.exitCode` is set so a test
+ * run or a supervisor still counts this as a failure. `REACT_X11_STRICT_TOKENS=1`
+ * restores the throw.
+ */
+export function reportStyleError(node, message) {
+  const seen = reportedStyleErrors.get(node);
+  if (seen?.has(message)) return;
+  if (seen) seen.add(message);
+  else reportedStyleErrors.set(node, new Set([message]));
+  const owner = ownerName(node);
+  console.error(
+    `${message}${owner ? ` — in ${owner}` : ''}. ` +
+      'The property is dropped and the app carries on; set ' +
+      'REACT_X11_STRICT_TOKENS=1 to make this throw instead.',
+  );
+  markFailed();
+}
+
 /** Wrap a call to user code so a throw is reported instead of escaping. */
 export function callHandler(node, handler, fn, ev) {
   try {