react-x11 2.28.0 → 2.30.0

package/src/components/Select.js

@@ -143,6 +143,33 @@ const TRIGGER_PAD_LEFT = 10;
 // (`nodes/scrollbars.js`, SCROLLBAR_WIDTH), so a menu that scrolls reserves the room
 const SCROLLBAR_WIDTH = 6;
 
+// The family a caption's style names, for the platform's menu: the first of
+// a CSS list, unquoted, and nothing for a generic one, which is the menu
+// font's own to answer.
+const GENERIC_FAMILIES = new Set([
+  'sans-serif',
+  'serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-monospace',
+  '-apple-system',
+  'blinkmacsystemfont',
+]);
+function menuFamily(family) {
+  if (typeof family !== 'string') return undefined;
+  const first = family
+    .split(',')[0]
+    .trim()
+    .replace(/^["']|["']$/g, '');
+  return first && !GENERIC_FAMILIES.has(first.toLowerCase())
+    ? first
+    : undefined;
+}
+
 function normalizeOption(option) {
   return typeof option === 'object' && option !== null
     ? option
@@ -291,6 +318,17 @@ function Option({
  * caption's `fontSize` is read back: the chevron is as tall as the capitals
  * beside it. Any slot also chooses the drawn trigger over the platform's
  * popup bezel, whose pixels no style reaches.
+ *
+ * `nativeMenu` is the menu's half of `native`: where the backend drops a
+ * control's menu as the platform's own (`app.nativePopUpMenus`, macOS), the
+ * list is that menu — the chosen row over the trigger, the platform's
+ * tracking, type-select and VoiceOver — rather than a `<popup>` drawn to
+ * look like it. It follows the trigger by default, so a select under the
+ * native bezel gets the native menu and a drawn one keeps the drawn menu;
+ * `true` asks for the platform's menu under a drawn trigger too, which is
+ * what a browser does with a `<select>` a page styled, and `false` keeps the
+ * drawn one. A drawn trigger's menu is set at the caption's size, in the
+ * family its style names when the system has it.
  */
 export function Select({
   value,
@@ -299,6 +337,7 @@ export function Select({
   name,
   placeholder = 'Select…',
   native,
+  nativeMenu,
   style,
   labelStyle,
   chevronStyle,
@@ -308,11 +347,20 @@ export function Select({
   const app = useAppOrNull();
   const styled = Boolean(labelStyle || chevronStyle);
   const nativeControls = useNativeControls(styled ? false : native);
+  // the platform's own menu, where there is one and this select wants it
+  const platformMenu =
+    (nativeMenu ?? nativeControls) && Boolean(app?.nativePopUpMenus);
   // The size the caption is set in, where its slot names one: the chevron is
   // measured against those capitals, and an `<Icon>`'s size does not inherit.
   const ownSize = flattenStyle(labelStyle).fontSize;
   const captionSize = typeof ownSize === 'number' ? ownSize : theme.fontSize;
   const [open, setOpen] = useState(false);
+  // The platform's menu, while it is down: its cancel function, and whether
+  // it is open, for the trigger's open look and `aria-expanded`.
+  const platformRef = useRef(null);
+  const [platformOpen, setPlatformOpen] = useState(false);
+  // a menu is down, whichever one: the trigger's open look follows it
+  const expanded = open || platformOpen;
   const [anchor, setAnchor] = useState(null);
   const [focused, setFocused] = useState(false);
   const [activeIndex, setActiveIndex] = useState(-1);
@@ -387,8 +435,48 @@ export function Select({
     };
   };
 
-  const close = () => setOpen(false);
+  const close = () => {
+    setOpen(false);
+    platformRef.current?.();
+  };
+  // The platform's menu, dropped from the trigger: the same options, the
+  // current one placed over it. Its answer is a pick like a row's.
+  const openPlatformMenu = () => {
+    const node = triggerRef.current;
+    const wnd = node?.root?.window;
+    if (!node || !wnd || platformRef.current) return;
+    const chosen = normalized.findIndex((o) => o.value === value);
+    const family = menuFamily(flattenStyle(labelStyle).fontFamily);
+    setPlatformOpen(true);
+    platformRef.current = app.popUpMenu(
+      wnd,
+      {
+        items: normalized.map((o, i) => ({
+          id: i + 1,
+          title: String(o.label),
+        })),
+        frame: [node.abs.x, node.abs.y, node.abs.width, node.abs.height],
+        ...(chosen >= 0 && { selected: chosen + 1 }),
+        // under the bezel the menu is the bezel's, at the menu font's size
+        ...(!nativeControls && { fontSize: captionSize }),
+        ...(!nativeControls && family && { fontFamily: family }),
+        // the theme's, as the bezel's appearance is
+        appearance: theme.scheme === 'dark' ? 'dark' : 'light',
+        rtl: node.direction === 'rtl',
+      },
+      (id) => {
+        platformRef.current = null;
+        setPlatformOpen(false);
+        const option = id != null ? normalized[id - 1] : null;
+        if (option && option.value !== value) emit(option.value);
+      },
+    );
+  };
   const openMenu = () => {
+    if (platformMenu) {
+      openPlatformMenu();
+      return;
+    }
     const node = triggerRef.current;
     if (!node) return;
     const rect = measureAnchor(menuAnchorOptions());
@@ -398,7 +486,9 @@ export function Select({
     setActiveIndex(selected >= 0 ? selected : 0);
     setOpen(true);
   };
-  const toggle = () => (open ? close() : openMenu());
+  const toggle = () => (expanded ? close() : openMenu());
+  // a menu still down when the select goes is taken with it
+  useEffect(() => () => platformRef.current?.(), []);
 
   // keeps the menu under the trigger for as long as it is open: a scrolled
   // ancestor, the trigger's own layout moving it (a neighbouring field
@@ -491,7 +581,7 @@ export function Select({
     {
       theme,
       role: 'combobox',
-      'aria-expanded': open,
+      'aria-expanded': expanded,
       'aria-haspopup': 'listbox',
       ref: triggerRef,
       focusable: true,
@@ -546,7 +636,8 @@ export function Select({
               paddingRight: 10,
               borderWidth: theme.borderWidth,
               borderRadius: theme.radius,
-              borderColor: focused || open ? theme.borderFocus : theme.border,
+              borderColor:
+                focused || expanded ? theme.borderFocus : theme.border,
               backgroundColor: theme.surface,
             },
         // Hover and press belong to the trigger while it is *shut*: they say
@@ -560,7 +651,7 @@ export function Select({
         // not overwrite. The only way for open to win is to not be competing.
         // (In native mode the wash overlay below answers the press instead.)
         !nativeControls &&
-          !open && {
+          !expanded && {
             ':hover': { backgroundColor: theme.surfaceHover },
             ':active': { backgroundColor: theme.surfaceActive },
           },
@@ -576,7 +667,7 @@ export function Select({
     nativeControls &&
       h(Bezel, {
         kind: 'popup',
-        pressed: open,
+        pressed: expanded,
         enabled: true,
         style: ABS_FILL,
       }),
@@ -605,7 +696,7 @@ export function Select({
           style: [
             ABS_FILL,
             { borderRadius: 6 },
-            !open && { ':active': { backgroundColor: pressWash(theme) } },
+            !expanded && { ':active': { backgroundColor: pressWash(theme) } },
           ],
         })
       : h(Icon, {

package/src/frame/index.js

@@ -529,7 +529,9 @@ function PaneHostView({
     }
     let host;
     try {
-      host = app.createPaneHost(wnd);
+      // `send` is for the windows the pane makes besides its own, which a
+      // backend whose pane process cannot show one shows here (Cocoa's)
+      host = app.createPaneHost(wnd, { send: (msg) => s.trySend?.(msg) });
     } catch (err) {
       embedErrorRef.current?.(err);
       return undefined;
@@ -539,17 +541,44 @@ function PaneHostView({
     // The pane's size is this box's laid-out size, told to the pane whenever
     // it changes — the same absolutize hook a <foreign> child window uses
     // (src/foreignnodes.js), because onViewport fires only for scrollers.
-    let sentSize = null;
+    //
+    // And where the box is on the screen, in device pixels (`screen`): the
+    // pane has no window of its own to ask, and a popup it anchors to one of
+    // its nodes is placed against it (`windowOrigin`, src/anchor.js) — a
+    // dropdown in a pane opened from the screen's corner without it. It
+    // moves when the box does and when the window does, so it is sent on
+    // layout, on a scroll that shifts the box, and on every anchor change
+    // of the window, which a move of the window is.
+    let sent = null;
     const syncSize = () => {
       host.setRect(node.abs);
       const sc = node.scale ?? 1;
       const width = Math.max(1, Math.round(node.abs.width / sc));
       const height = Math.max(1, Math.round(node.abs.height / sc));
-      if (sentSize && sentSize.width === width && sentSize.height === height) {
+      const origin = node.root?.window?._screenOrigin;
+      const screen = origin
+        ? {
+            x: Math.round(origin.x + node.abs.x),
+            y: Math.round(origin.y + node.abs.y),
+          }
+        : null;
+      if (
+        sent &&
+        sent.width === width &&
+        sent.height === height &&
+        sent.screen?.x === screen?.x &&
+        sent.screen?.y === screen?.y
+      ) {
         return;
       }
-      sentSize = { width, height };
-      s.trySend?.({ type: 'pane-rect', width, height, scale: sc });
+      sent = { width, height, screen };
+      s.trySend?.({
+        type: 'pane-rect',
+        width,
+        height,
+        scale: sc,
+        ...(screen && { screen }),
+      });
     };
     const origAbsolutize = node.absolutize.bind(node);
     node.absolutize = (ox, oy) => {
@@ -560,13 +589,35 @@ function PaneHostView({
     if (origShift) {
       node._shiftAbs = (dx, dy) => {
         origShift(dx, dy);
-        host.setRect(node.abs);
+        syncSize();
       };
     }
+    const offAnchor = node.root?.onAnchorChange?.(syncSize);
     if (node.abs?.width) syncSize();
 
+    // The window's focus, which the pane has no window to hear: a menu it
+    // keeps open on the strength of the window having it closes when the
+    // user goes to another application (`useDismissOnWindowBlur`).
+    const offFocus = node.root?.onWindowFocusChange?.((focused) =>
+      s.trySend?.({
+        type: 'pane-event',
+        name: focused ? 'focus' : 'blur',
+        ev: { buttons: 0, time: Date.now() },
+      }),
+    );
+
     const off = s.transport.onMessage((msg) => {
-      if (msg?.type === 'pane-present') {
+      if (msg?.type === 'pane-window') {
+        host.paneWindow?.(msg);
+      } else if (msg?.type === 'pane-menu') {
+        host.popUpMenu?.(msg);
+      } else if (msg?.type === 'pane-menu-cancel') {
+        host.cancelMenu?.(msg.menu);
+      } else if (msg?.type === 'pane-present' && msg.window != null) {
+        host.presentWindow?.(msg);
+      } else if (msg?.type === 'pane-cursor' && msg.window != null) {
+        host.windowCursor?.(msg);
+      } else if (msg?.type === 'pane-present') {
         host.setRect(node.abs);
         host.present(msg.id);
       } else if (msg?.type === 'pane-cursor') {
@@ -581,6 +632,8 @@ function PaneHostView({
     });
     return () => {
       off();
+      offAnchor?.();
+      offFocus?.();
       node.defaultCursor = undefined;
       node.root?.events?.refreshCursor();
       node.absolutize = origAbsolutize;

package/src/node.d.ts

@@ -230,6 +230,80 @@ export interface PaintCachePlan {
   tint?: string;
 }
 
+/**
+ * CSS's `matrix(a, b, c, d, e, f)`: a point (x, y) goes to
+ * (a·x + c·y + e, b·x + d·y + f), with `e` and `f` in device pixels.
+ */
+export type SpriteMatrix = [number, number, number, number, number, number];
+
+/** A cubic-bezier's control points `[x1, y1, x2, y2]`, `x1` and `x2` in
+ *  0..1, or one of Core Animation's curve names. */
+export type SpriteTiming = [number, number, number, number] | string;
+
+/**
+ * An animation the render server runs on a sprite: keyframes for one
+ * property, played as CSS plays an animation's iterations.
+ */
+export interface SpriteAnimation {
+  /** The element's own name for this run, which `spriteAnimationEnded`
+   * reports. An animation is attached once per id: to change one, give it
+   * a new id. */
+  id: string;
+  property: 'opacity' | 'transform';
+  /** At least two: opacities, or matrices for a transform — sampled densely
+   * where the element interpolates in a way the render server would not. */
+  values: number[] | SpriteMatrix[];
+  /** One per value, 0 to 1, never decreasing; evenly spaced when left out. */
+  keyTimes?: number[];
+  /** One curve per segment, so one fewer than `values`; linear when left
+   * out. */
+  timings?: SpriteTiming[];
+  /** Milliseconds, one iteration. */
+  duration: number;
+  /** Milliseconds from the frame that asks: ahead, or — negative — already
+   * that far in. Read when the animation is attached and not after. */
+  delay?: number;
+  /** Iterations, `Infinity` for a loop; one when left out. */
+  repeat?: number;
+  /** Each iteration turns round at its end, as `alternate` does. */
+  autoreverse?: boolean;
+  /** The last value stays on screen after the end. */
+  hold?: boolean;
+}
+
+/**
+ * A part of an element's drawing a presenter may put on a layer of its own
+ * — what `sprites()` answers with (docs/extending.md "Parts of your drawing
+ * on layers of their own").
+ */
+export interface Sprite {
+  /** The same across frames for the same part. */
+  key: string;
+  /** Its box, untransformed: device pixels, window coordinates, like
+   * `abs`. */
+  rect: Rect;
+  /** What it draws, untransformed, when that is more than `rect`. */
+  reach?: Rect;
+  /** Where it shows, when the element clips it: device pixels, window
+   * coordinates. Its layer is cut to the rect, and so it is to the clip of
+   * every ancestor with square corners (a rounded one has to hold all of
+   * it). */
+  clip?: Rect;
+  /** Draws the part where it is in the window, as `paint` would, but at
+   * opacity 1 and untransformed. */
+  paint(ctx: Context2D): void;
+  /** Compared with `===` from frame to frame; a change paints the part
+   * again. Left out, it is painted once. */
+  version?: unknown;
+  /** What the layer shows when no animation runs on it; 1 when left out. */
+  opacity?: number;
+  /** …and the transform, about `origin`; the identity when left out. */
+  transform?: SpriteMatrix;
+  /** Device pixels, window coordinates; `rect`'s centre when left out. */
+  origin?: { x: number; y: number };
+  animations?: SpriteAnimation[];
+}
+
 /** How an axis is bounded when layout asks an element for its size.
  * `'exactly'` — the style decided this axis; `'at-most'` — that many pixels
  * are on offer; `'unconstrained'` — nothing bounds it. */
@@ -570,6 +644,28 @@ export declare class Node {
    * read-only.
    */
   paintDamage(): Rect | null;
+  /**
+   * The parts of this element's drawing a presenter may put on layers of
+   * their own, and animate there in the render server — or null, the
+   * default. Asked every frame, after layout and before the damage is
+   * taken, by the macOS surface presenter's layer promotion and by nothing
+   * else: on X11, on Wayland and wherever a frame's scene refuses a part,
+   * the element draws everything, as it would without this.
+   */
+  sprites(): Sprite[] | null;
+  /**
+   * The keys of this element's sprites that are on layers of their own now.
+   * Called in the frame that changes the set, before it paints; `paint`
+   * leaves a lifted part out from then on, and draws again one the set no
+   * longer holds.
+   */
+  spritesLifted(keys: ReadonlySet<string>): void;
+  /** The render server is done with animation `id` on sprite `key`: it ran
+   * out (`finished`), or it was taken off with its layer. */
+  spriteAnimationEnded(key: string, id: string, finished: boolean): void;
+  /** Ask for the frame in which `sprites()` is asked again, when the parts
+   * changed and nothing the element draws did. A no-op where nothing asks. */
+  spritesChanged(): void;
   /**
    * "The pixels in `rect` moved by (dx, dy); the rest of it is new" — for an
    * element with a viewport of its own, whose pan is a scroll in every way

package/src/nodes/node.js

@@ -45,6 +45,7 @@ import { NodePosition } from './position.js';
 import { NodeQueries } from './queries.js';
 import { NodeScrollBlit } from './scrollblit.js';
 import { NodeSelectable } from './selectable.js';
+import { NodeSprites } from './sprites.js';
 import { NodeStyling } from './styling.js';
 import { DEV } from './util.js';
 
@@ -608,6 +609,7 @@ export class Node {
     this.root?._animating.delete(this);
     this.root?._opaqueNodes?.delete(this);
     this.root?._viewportFixedNodes?.delete(this);
+    this.root?._spriteNodes?.delete(this);
     // a surface that goes away takes its selection with it, and the app-wide
     // claim on being the one showing one goes with it too
     this._textSelection?.destroy();
@@ -627,14 +629,18 @@ export class Node {
       root?._layoutHosts?.add(this);
     }
     // an element answering `opaqueRect()` is one the window asks per pass,
-    // and one answering `viewportFixedRects()` one it asks per scroll blit
+    // one answering `viewportFixedRects()` one it asks per scroll blit, and
+    // one answering `sprites()` one its presenter asks per frame
     const opaque = this.opaqueRect !== Node.prototype.opaqueRect;
     const fixed = this.viewportFixedRects !== Node.prototype.viewportFixedRects;
+    const sprites = this.sprites !== Node.prototype.sprites;
     if (opaque) this.root?._opaqueNodes?.delete(this);
     if (fixed) this.root?._viewportFixedNodes?.delete(this);
+    if (sprites) this.root?._spriteNodes?.delete(this);
     this.root = root;
     if (opaque) root?._opaqueNodes?.add(this);
     if (fixed) root?._viewportFixedNodes?.add(this);
+    if (sprites) root?._spriteNodes?.add(this);
     // styled before it had a window, so this is where a placed node is
     // first registered (WindowNode._placeNodes)
     if (this.style && isPlaced(this.style)) root?._placedNodes?.add(this);
@@ -1034,4 +1040,5 @@ installMethods(
   NodePaint,
   NodeBoxPaint,
   NodeSelectable,
+  NodeSprites,
 );

package/src/nodes/sprites.js

@@ -0,0 +1,73 @@
+// Sprites (issue #819): the parts of what an element draws that a retained
+// presenter may lift onto layers of their own, and animate there in the
+// render server. The element's half of the seam is here; the presenter's is
+// src/cocoa/sprites.js, under layer promotion.
+//
+// It is the shape of `opaqueRect()`: an accessor core asks every frame, a
+// registry of the nodes that override it (`WindowNode._spriteNodes`, kept by
+// `_setRoot`), and a default that answers nothing, so an element that never
+// heard of sprites pays nothing and one that answers them draws exactly what
+// it draws today wherever nothing asks — on X11, on Wayland, on the layer
+// presenter, and in any frame whose scene refuses a lift.
+
+/** Node's half of sprites, installed onto `Node.prototype` by node.js. */
+export class NodeSprites {
+  /**
+   * The parts of this element's drawing a presenter may put on layers of
+   * their own, or null, the default. Each is a plain object:
+   *
+   * - `key`: a string, the same across frames for the same part.
+   * - `rect`: its box, untransformed — device pixels, window coordinates,
+   *   like `abs`.
+   * - `reach`: what it draws, untransformed, when that is more than `rect`.
+   * - `paint(ctx)`: draws it where it is in the window, as `paint` would,
+   *   but at opacity 1 and untransformed: the layer carries both.
+   * - `version`: compared with `===` from frame to frame; a change paints
+   *   the part again. Left out, it is painted once.
+   * - `opacity`, and `transform` — CSS's `matrix(a, b, c, d, e, f)` as an
+   *   array, `e` and `f` in device pixels — about `origin`, a point in
+   *   device pixels that defaults to `rect`'s centre: the values the layer
+   *   shows when no animation is running on it.
+   * - `animations`: what the render server runs on it, each `{ id,
+   *   property: 'opacity' | 'transform', values, keyTimes, timings,
+   *   duration, delay, repeat, autoreverse, hold }`, with times in
+   *   milliseconds and `delay` counted from the frame that asks — negative
+   *   for one that started before it. An animation is attached once per
+   *   `id`: to change one, give it a new id.
+   *
+   * Asked every frame, after layout and before the damage is taken, on a
+   * window whose presenter lifts sprites; nowhere else. An element whose
+   * parts changed while nothing was going to paint asks for that frame with
+   * `spritesChanged()`.
+   */
+  sprites() {
+    return null;
+  }
+
+  /**
+   * The keys of this element's sprites that are on layers of their own now,
+   * a set the element may keep. Called in the frame that changes it, before
+   * that frame paints. From then on `paint` must not draw a lifted part —
+   * where it is, the window's bitmap holds a hole the layer shows through —
+   * and must draw again one the set no longer holds: a presenter gives a
+   * part back whenever the scene stops allowing it, and the bitmap under it
+   * is repainted in that same frame.
+   */
+  spritesLifted(keys) {}
+
+  /**
+   * The render server is done with animation `id` on sprite `key`: it ran
+   * out (`finished`), or it was taken off with its layer. Called from the
+   * backend's event, between frames.
+   */
+  spriteAnimationEnded(key, id, finished) {}
+
+  /**
+   * Ask for the frame in which this element's sprites are asked for again —
+   * one whose parts changed while nothing it drew had. Does nothing on a
+   * window whose presenter lifts none.
+   */
+  spritesChanged() {
+    this.root?.window?.spritesChanged?.(this);
+  }
+}

package/src/nodes/window/window.js

@@ -196,6 +196,9 @@ export class WindowNode extends Scrollable(Node) {
     // the nodes answering `viewportFixedRects()`, whose rects a scroll pane
     // they are in repairs when it blits (`_viewportFixedPins`)
     this._viewportFixedNodes = new Set();
+    // the nodes answering `sprites()`, which a presenter that lifts parts of
+    // an element onto layers asks every frame (src/cocoa/sprites.js)
+    this._spriteNodes = new Set();
     // Nodes that want the `attention` event (ntk#37) — an
     // `unstable_onAttention` prop,
     // an `:attention` block, or both. Built before the EventManager so the
@@ -547,12 +550,22 @@ export class WindowNode extends Scrollable(Node) {
    * relative to the *frame*, not the root. A popup anchored with them lands
    * near the corner of the screen instead of under its trigger. The server
    * will translate for us, and its answer is right whatever the WM did.
+   *
+   * A backend with no server to ask keeps the origin on its window object
+   * itself, current as of the event that moved it — Cocoa's
+   * `_nativeResized`, a frame pane's `setPaneSize`. There is no question to
+   * ask there, and what is left is what the answer would have done: tell
+   * whatever is anchored to this window that it moved. Without it a popup
+   * stayed where the window had been, and a frame pane told its new place
+   * on the screen dropped its next menu from the old one.
    */
   _refreshScreenOrigin() {
     const wnd = this.window;
+    if (!wnd) return;
     const X = this.app?.X;
     const root = X?.display?.screen?.[0]?.root;
-    if (!wnd || root == null || typeof X.TranslateCoordinates !== 'function') {
+    if (root == null || typeof X.TranslateCoordinates !== 'function') {
+      this._notifyAnchorChange();
       return;
     }
     X.TranslateCoordinates(wnd.id, root, 0, 0, (err, res) => {

package/src/types/components.d.ts

@@ -521,6 +521,16 @@ export interface SelectProps<T = unknown>
   /** The chevron's style, over `textMuted` at the caption's cap height.
    *  `display: 'none'` leaves it out. */
   chevronStyle?: StyleProp;
+  /**
+   * The menu's half of `native`: where the backend drops a control's menu
+   * as the platform's own (macOS, with `@windowkit/appkit` 0.20 or later),
+   * the list is that menu rather than a drawn one. Follows the trigger by
+   * default — the native bezel's select gets the native menu, a drawn one
+   * the drawn menu. `true` asks for the platform's menu under a drawn
+   * trigger too, set at the caption's size; `false` keeps the drawn menu.
+   * Ignored where the backend has no such menu.
+   */
+  nativeMenu?: boolean;
 }
 export function Select<T = unknown>(props: SelectProps<T>): ReactNode;