react-x11 2.38.0 → 2.40.0

package/src/menuitem.js

@@ -112,21 +112,62 @@ const KEY_LABELS = {
   Next: 'PgDn',
 };
 
+// The Mac prints a chord as glyphs, in one fixed order whatever order the
+// chord was written in — ⌃⌥⇧⌘ — and with nothing between them: `⇧⌘Z`, never
+// `Cmd+Shift+Z`. `Control` and `Super` are both ⌘ there, for the reason
+// `primaryModifier` gives below: a cross-platform chord is written in the
+// primary modifier, and the Mac's is Command.
+const MAC_MODIFIER_ORDER = ['Alt', 'Shift', 'Command'];
+const MAC_MODIFIER_GLYPHS = { Alt: '⌥', Shift: '⇧', Command: '⌘' };
+
+// The keys a Mac menu draws as a glyph rather than a word. The rest are
+// `KEY_LABELS`' answer, which is already the Mac's for punctuation.
+const MAC_KEY_LABELS = {
+  Return: '↩',
+  KP_Enter: '⌤',
+  Tab: '⇥',
+  BackSpace: '⌫',
+  Delete: '⌦',
+  Escape: '⎋',
+  Left: '←',
+  Right: '→',
+  Up: '↑',
+  Down: '↓',
+  Prior: '⇞',
+  Next: '⇟',
+  Home: '↖',
+  End: '↘',
+};
+
+const keyLabel = (key, labels) =>
+  labels[key] ??
+  KEY_LABELS[key] ??
+  (key.length === 1 ? key.toUpperCase() : key);
+
 /**
  * One `aas` alternative — `['Control', 'S']` — as the string a menu row
- * shows: `Ctrl+S`.
+ * shows: `Ctrl+S`, or `⌘S` where the primary modifier is ⌘.
  *
  * A single-character key is upper-cased because that is how every toolkit
  * prints one, and because dbusmenu carries the *key*, not the character it
  * types: `['Control', 's']` and `['Control', 'S']` are the same binding and
  * must not render differently.
  */
-function formatChord(chord) {
+function formatChord(chord, primary) {
   const { modifiers, key } = splitChord(chord);
-  const parts = [...modifiers].map((token) => MODIFIER_LABELS[token]);
-  if (key != null) {
-    parts.push(KEY_LABELS[key] ?? (key.length === 1 ? key.toUpperCase() : key));
+  if (primary === 'Super') {
+    const held = new Set(
+      [...modifiers].map((token) =>
+        token === 'Control' || token === 'Super' ? 'Command' : token,
+      ),
+    );
+    const glyphs = MAC_MODIFIER_ORDER.filter((token) => held.has(token))
+      .map((token) => MAC_MODIFIER_GLYPHS[token])
+      .join('');
+    return glyphs + (key == null ? '' : keyLabel(key, MAC_KEY_LABELS));
   }
+  const parts = [...modifiers].map((token) => MODIFIER_LABELS[token]);
+  if (key != null) parts.push(keyLabel(key, {}));
   return parts.join('+');
 }
 
@@ -137,11 +178,14 @@ function formatChord(chord) {
  * modifier tokens ending in the key. Only the first alternative is drawn —
  * a row has one shortcut column, and a menu that printed `Ctrl+S / F2` in it
  * would be wider than the menu for the benefit of the rarer binding.
+ *
+ * `primary` is the app's `primaryModifier` (keysyms.js): `'Super'` draws the
+ * chord the way a Mac menu does, `⇧⌘Z` for `['Control', 'Shift', 'Z']`.
  */
-export function formatShortcut(shortcut) {
+export function formatShortcut(shortcut, { primary = 'Control' } = {}) {
   const first = shortcut?.[0];
   if (!Array.isArray(first) || first.length === 0) return '';
-  return formatChord(first);
+  return formatChord(first, primary);
 }
 
 // What UI Events calls the modifiers, which is what `aria-keyshortcuts` is
@@ -160,19 +204,21 @@ const ARIA_MODIFIERS = {
  * dbusmenu's `aas` already has — so unlike the drawn menu, **every**
  * alternative is announced rather than only the first: a screen reader is
  * reading them out, not fitting them in a column.
+ *
+ * `primary` is `formatShortcut`'s: under `'Super'` a `Control` is ⌘, which
+ * UI Events calls `Meta`, so what is announced is what is drawn and bound.
  */
-export function ariaKeyShortcuts(shortcut) {
+export function ariaKeyShortcuts(shortcut, { primary = 'Control' } = {}) {
   if (!isValidShortcut(shortcut)) return undefined;
+  const name = (token) => {
+    if (!MODIFIER_TOKENS.has(token)) return KEY_LABELS[token] ?? token;
+    return primary === 'Super' && token === 'Control'
+      ? 'Meta'
+      : ARIA_MODIFIERS[token];
+  };
+  // a chord naming both `Control` and `Super` is one ⌘ there, said once
   return shortcut
-    .map((chord) =>
-      chord
-        .map((token) =>
-          MODIFIER_TOKENS.has(token)
-            ? ARIA_MODIFIERS[token]
-            : (KEY_LABELS[token] ?? token),
-        )
-        .join('+'),
-    )
+    .map((chord) => [...new Set(chord.map(name))].join('+'))
     .join(' ');
 }
 

package/src/node.d.ts

@@ -73,6 +73,29 @@ export interface Context2D {
    * `'globalCompositeOperation' in ctx`.
    */
   globalCompositeOperation?: string;
+  /**
+   * Canvas's: whether an image drawn scaled or turned is smoothed, or
+   * drawn as its nearest pixels. Native contexts only (macOS, Windows), and
+   * only where the bridge can set it: assign and read back to know.
+   */
+  imageSmoothingEnabled?: boolean;
+  /**
+   * Canvas's: how it is smoothed, `'low'` being bilinear. A native context
+   * starts at `'medium'`, which on macOS resamples the whole source for a
+   * draw through a matrix whatever the clip — so a surface drawn a tile at
+   * a time is far cheaper at `'low'`.
+   */
+  imageSmoothingQuality?: 'low' | 'medium' | 'high';
+  /**
+   * Canvas's: a CSS filter list applied to what is drawn after it. Native
+   * contexts only (macOS, Windows), and only the colour functions —
+   * `grayscale()`, `sepia()`, `saturate()`, `hue-rotate()`, `invert()`,
+   * `brightness()`, `contrast()` and `opacity()` — over a bridge that reads
+   * a surface's pixels back. Anything else does not stick: assign and read
+   * back to know. Absent on X11, whose server runs no colour matrix and
+   * answers a read a round trip later.
+   */
+  filter?: string;
   save(): void;
   restore(): void;
   translate(x: number, y: number): void;
@@ -237,6 +260,23 @@ export interface PaintCachePlan {
  */
 export type SpriteMatrix = [number, number, number, number, number, number];
 
+/**
+ * CSS's `matrix3d()`: sixteen numbers, column by column, a point
+ * (x, y, z, 1) going to the first three rows over the fourth — a turn out
+ * of the plane and the perspective it is seen in, about the sprite's
+ * `origin`. Its translation (the 13th to 15th) is in device pixels, and so
+ * is the distance its perspective row divides by. A presenter lifts a
+ * sprite with one only where none of its corners is behind the viewer, at
+ * rest or in any keyframe, and where its bridge takes one.
+ */
+// prettier-ignore
+export type SpriteMatrix3D = [
+  number, number, number, number,
+  number, number, number, number,
+  number, number, 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;
@@ -252,8 +292,9 @@ export interface SpriteAnimation {
   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[];
+   * where the element interpolates in a way the render server would not.
+   * A transform's may be `matrix3d`s, in any mix with `matrix`es. */
+  values: number[] | (SpriteMatrix | SpriteMatrix3D)[];
   /** 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
@@ -321,7 +362,7 @@ export interface Sprite {
   /** 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;
+  transform?: SpriteMatrix | SpriteMatrix3D;
   /** Device pixels, window coordinates; `rect`'s centre when left out. */
   origin?: { x: number; y: number };
   animations?: SpriteAnimation[];

package/src/nodes/editmenupopup.js

@@ -5,6 +5,7 @@
 import { deviceAnchorArea, windowOrigin } from '../anchor.js';
 import { armPasteState, canPaste } from '../pastestate.js';
 import {
+  primaryModifier,
   XK_RETURN,
   XK_KP_ENTER,
   XK_UP,
@@ -125,6 +126,7 @@ export function openEditMenu(node, at, actions = {}) {
     items,
     (text) => app?.fonts?.layout(text, style)?.width,
     s,
+    { primary: primaryModifier(app) },
   );
   const deviceAt = at && {
     ...at,
@@ -221,6 +223,17 @@ export function openEditMenu(node, at, actions = {}) {
   node._editMenu = popup;
   // read *before* the menu takes the keyboard, and handed back on close
   node._editMenuRestore = node._focusManager()?.focused ?? null;
+  // The window losing focus closes it — the user went to another
+  // application, ⌘-Tab or a click on its window. Neither reaches us as a
+  // press: the grab redirects presses only between windows of ours on Cocoa,
+  // and a popup panel never takes the keyboard there, so this is the one
+  // event that says so. The node keeps its focus across the blur, so nothing
+  // in the tree hears it either; the same answer `Menu` and `Select` give
+  // (`useDismissOnWindowBlur`, components/anchor.js).
+  node._editMenuOffBlur =
+    node.root?.onWindowFocusChange?.((focused) => {
+      if (!focused) closeEditMenu(node);
+    }) ?? null;
   // the menu takes the keyboard so arrows and Escape reach it rather than
   // the element behind it
   popup.events?.focus?.(canvas);
@@ -241,6 +254,8 @@ export function closeEditMenu(node) {
   const popup = node?._editMenu;
   if (!popup) return;
   node._editMenu = null;
+  node._editMenuOffBlur?.();
+  node._editMenuOffBlur = null;
   const restore = node._editMenuRestore;
   node._editMenuRestore = null;
   // the popup is a child, so a node destroyed while its menu was up took the
@@ -255,6 +270,10 @@ export function closeEditMenu(node) {
   // menu and a ring appearing on the way back would be news to nobody. A
   // surface that was not focusable in the first place, or that stopped being
   // on screen while the menu was up, gets nothing back rather than the
-  // destroyed menu canvas keeping the keyboard.
-  events.focus(events._canRestoreTo(restore) ? restore : null, 'pointer');
+  // destroyed menu canvas keeping the keyboard. And a restore, which takes
+  // the window no keyboard: a menu closed because the user went to another
+  // application must not drag them back to this one.
+  events.focus(events._canRestoreTo(restore) ? restore : null, 'pointer', {
+    restoring: true,
+  });
 }

package/src/nodes/sprites.js

@@ -25,9 +25,12 @@ export class NodeSprites {
    * - `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.
+   *   array, `e` and `f` in device pixels, or `matrix3d()`'s sixteen
+   *   numbers for a part turned out of the plane and seen in a perspective
+   *   — 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. A matrix3d part is lifted only where none of its corners is behind
+   *   the viewer, at rest or in any keyframe.
    * - `animations`: what the render server runs on it, each `{ id,
    *   property: 'opacity' | 'transform', values, keyTimes, timings,
    *   duration, delay, repeat, autoreverse, hold }`, with times in

package/src/nodes/textarea.js

@@ -10,6 +10,7 @@ import {
   XK_PAGE_UP,
   XK_PAGE_DOWN,
   XK_END,
+  primaryModifierHeld,
 } from '../keysyms.js';
 import {
   scrollbarGeometry,
@@ -235,7 +236,8 @@ export class TextAreaNode extends TextInputNode {
     const layout = this._valueLayout();
 
     if (k === XK_RETURN || k === XK_KP_ENTER) {
-      if (ev.ctrlKey) {
+      // Ctrl+Enter, ⌘↩ on the Cocoa backend
+      if (primaryModifierHeld(ev, this.app)) {
         this._fireValueEvent('onSubmit', this.value, ev.nativeEvent);
         return true;
       }

package/src/nodes/textinput.js

@@ -14,6 +14,7 @@ import { lastInputTime } from '../inputtime.js';
 import {
   ctrlChordLetter,
   MOD,
+  primaryModifierHeld,
   XK_BACKSPACE,
   XK_RETURN,
   XK_KP_ENTER,
@@ -550,7 +551,9 @@ export class TextInputNode extends Node {
       this._moveCaret(this._chars().length, ev.shiftKey);
       return true;
     }
-    if (ev.ctrlKey) {
+    // Ctrl, or ⌘ on the Cocoa backend (`primaryModifierHeld`): the keys the
+    // edit menu prints beside its rows are the keys that do what they say
+    if (primaryModifierHeld(ev, this.app)) {
       const letter = ctrlChordLetter(ev);
       if (letter === 0x61 /* a */) {
         this._selectAll();
@@ -562,10 +565,12 @@ export class TextInputNode extends Node {
       } else if (letter === 0x76 /* v */) {
         this._pasteFrom();
       } else if (letter === 0x7a /* z */) {
-        // Ctrl+Shift+Z redoes, the way it does in GTK and Qt
+        // Ctrl+Shift+Z redoes, the way it does in GTK and Qt — and ⇧⌘Z is
+        // the Mac's own redo
         if (ev.shiftKey) this.redo();
         else this.undo();
-      } else if (letter === 0x79 /* y */) {
+      } else if (letter === 0x79 /* y */ && !ev.metaKey) {
+        // Ctrl+Y is Windows' redo; ⌘Y is nobody's, so it is not taken
         this.redo();
       } else {
         // A chord this field has no answer for is not the field's: Ctrl+S
@@ -576,6 +581,11 @@ export class TextInputNode extends Node {
       }
       return true;
     }
+    // …and a chord on the other one is not text either. AppKit hands over
+    // the key's bare character with ⌘ or ⌃ held, so ⌘S in a focused field
+    // typed an `s` before this, and ⌃A typed an `a` once ⌘ became the
+    // primary — Ctrl and Super chords are commands on every backend.
+    if (ev.ctrlKey || ev.metaKey) return false;
     if (ev.codepoint != null && ev.codepoint >= 0x20 && ev.codepoint !== 0x7f) {
       const ch = String.fromCodePoint(ev.codepoint);
       this._insert(ch, 'type');

package/src/textselection.js

@@ -30,7 +30,7 @@
 
 import { callHandler } from './errors.js';
 import { lastInputTime } from './inputtime.js';
-import { ctrlChordLetter } from './keysyms.js';
+import { ctrlChordLetter, primaryModifierHeld } from './keysyms.js';
 import { codePoints, wordRangeAt } from './textrange.js';
 // --- who is showing a selection ------------------------------------------
 //
@@ -201,14 +201,14 @@ export class TextSelection {
   }
 
   /**
-   * Ctrl+A and Ctrl+C, run as this element's default action — which is why a
-   * surface is a focus target (a11y.js): the copy has to have somewhere to
-   * arrive. Nothing else is bound. A read-only document has no caret, so
-   * shift+arrows would be caret browsing, which is a mode rather than a
-   * default.
+   * Ctrl+A and Ctrl+C — ⌘A and ⌘C on the Cocoa backend — run as this
+   * element's default action, which is why a surface is a focus target
+   * (a11y.js): the copy has to have somewhere to arrive. Nothing else is
+   * bound. A read-only document has no caret, so shift+arrows would be caret
+   * browsing, which is a mode rather than a default.
    */
   keyDown(ev) {
-    if (!ev.ctrlKey) return;
+    if (!primaryModifierHeld(ev, this.node.app)) return;
     const letter = ctrlChordLetter(ev);
     if (letter === 0x61 /* a */) {
       this.selectAll();

package/src/types/components.d.ts

@@ -579,6 +579,10 @@ export interface MenuItem {
    * the menu is mounted, without the menu being opened (#351). `enabled`
    * and `visible` gate the binding with the row. `accelerators={false}` on
    * the menu turns that off for an app with a dispatcher of its own.
+   *
+   * `Control` is the primary modifier: on the Cocoa backend `[['Control',
+   * 'S']]` is drawn `⌘S`, bound to ⌘S, and installed in the macOS menu bar
+   * as ⌘S — which then answers it by itself (docs/events.md).
    */
   shortcut?: MenuShortcut;
   /** With `toggleState`, draws a check mark or a radio dot in the gutter. */
@@ -654,8 +658,10 @@ export interface MenuBarProps extends WidgetProps {
   /**
    * Honour the items' own `shortcut`s while this bar is mounted — including
    * when the desktop's panel has taken the menu over, since the panel draws
-   * the rows but the key is pressed in this window. On by default; `false`
-   * leaves the chords to an app that dispatches its own.
+   * the rows but the key is pressed in this window. The macOS menu bar is the
+   * exception: it answers the ⌘ chords it holds as key equivalents itself,
+   * and the window leaves those alone. On by default; `false` leaves the
+   * chords to an app that dispatches its own.
    */
   accelerators?: boolean;
   fontSize?: number;

package/src/types/elements.d.ts

@@ -739,7 +739,7 @@ export interface TextInputProps extends DrawnProps<TextInputNode> {
    * both read naturally.
    */
   onChange?: (ev: ChangeEvent<TextInputNode>) => void;
-  /** Enter — or Ctrl+Enter in a `<textarea>`. */
+  /** Enter — or Ctrl+Enter in a `<textarea>` (⌘↩ on the Cocoa backend). */
   onSubmit?: (ev: SubmitEvent<TextInputNode>) => void;
   placeholder?: string;
   placeholderColor?: Color;

package/src/types/events.d.ts

@@ -7,6 +7,7 @@
 import type { RefObject } from 'react';
 import type { DrawnNode, NtkWindow, TextInputNode } from './nodes.js';
 import type { MenuShortcut } from './components.js';
+import type { PrimaryModifier } from '../keysyms.js';
 
 /** The raw ntk/X11 event a synthetic one was made from. */
 export interface NativeEvent {
@@ -331,7 +332,7 @@ export interface ChangeEvent<T = TextInputNode> extends Omit<
 }
 
 /**
- * `<textinput onSubmit>` — Enter, or Ctrl+Enter in a `<textarea>`. Same
+ * `<textinput onSubmit>` — Enter, or Ctrl+Enter in a `<textarea>` (⌘↩ on Cocoa). Same
  * shape as {@link ChangeEvent}; `nativeEvent` is the X key event.
  */
 export interface SubmitEvent<T = TextInputNode> extends Omit<
@@ -556,7 +557,8 @@ export interface AcceleratorOptions {
  * Exact on Control/Alt/Shift/Super, indifferent to Caps Lock and Num Lock,
  * matched against the Latin keysym so a layout switch does not turn it off,
  * and behind whatever a focused element consumed with `preventDefault()`.
- * See docs/events.md.
+ * `Control` is the app's primary modifier: ⌘ on the Cocoa backend, the key
+ * its menus print. See docs/events.md.
  *
  * With no `scope` the binding belongs to the tree's top-level `<window>`, or,
  * in an app that has none, to the root-level `<popup>` holding the keyboard —
@@ -569,10 +571,25 @@ export function useAccelerator(
   options?: AcceleratorOptions,
 ): void;
 
+export interface MatchesShortcutOptions {
+  /**
+   * The app's primary modifier — `primaryModifier(app)` from
+   * `react-x11/keysyms`. `'Super'` reads a chord's `Control` (and its
+   * `Super`) as ⌘ and wants ⌃ up, which is the Cocoa backend's rule;
+   * `'Control'`, the default, reads the chord literally.
+   */
+  primary?: PrimaryModifier;
+}
+
 /**
  * Whether a key event presses any alternative of a `shortcut` — the matcher
  * the menus and {@link useAccelerator} both run on, for an application
- * dispatching chords its own way.
+ * dispatching chords its own way. Pass the app's primary modifier to match
+ * the way they do:
+ *
+ * ```ts
+ * matchesShortcut(ev, [['Control', 'S']], { primary: primaryModifier(app) });
+ * ```
  */
 export function matchesShortcut(
   ev: {
@@ -584,4 +601,5 @@ export function matchesShortcut(
     metaKey?: boolean;
   },
   shortcut: MenuShortcut | undefined,
+  options?: MatchesShortcutOptions,
 ): boolean;

package/src/types/nodes.d.ts

@@ -243,5 +243,11 @@ export interface NtkApp {
   createWindow(args?: Record<string, unknown>): NtkWindow;
   rootWindow(screen?: number): NtkWindow;
   close(): Promise<void>;
+  /**
+   * The modifier shortcuts are pressed with on this backend: `'Super'` (⌘)
+   * on Cocoa, absent — Ctrl — everywhere else. Read it through
+   * `primaryModifierHeld` from `react-x11/keysyms`.
+   */
+  readonly primaryModifier?: 'Control' | 'Super';
   [key: string]: any;
 }