react-x11 2.39.0 → 2.41.0

package/src/nodes/textarea.js

@@ -10,14 +10,85 @@ import {
   XK_PAGE_UP,
   XK_PAGE_DOWN,
   XK_END,
+  primaryModifierHeld,
 } from '../keysyms.js';
 import {
   scrollbarGeometry,
   scrollbarHit,
   paintScrollbarThumb,
 } from './scrollbars.js';
+import { installMethods } from './install.js';
 import { rangeBands } from './text.js';
 import { CARET_WIDTH, CARET_RESERVE, TextInputNode } from './textinput.js';
+import { TextAreaKeys } from './textkeys.js';
+
+/** A hard line break at the end of the value — the breaks ntk's TextLayout
+ * and CoreText both end a line at. */
+const FINAL_BREAK = /[\n\r\u2028\u2029]$/;
+
+/**
+ * The layout of a value that ends in a line break, with the empty line the
+ * break opens: the line Return at the end of a textarea puts the caret on.
+ *
+ * Neither engine sets it. ntk's TextLayout and CoreText both end a paragraph
+ * at its last break, which is right for a `<text>` — CSS draws no line after
+ * a final newline either — and wrong for an editor, where that line is
+ * where the next letter goes. Without it the caret after Return was drawn at
+ * the end of the line above, Up from there skipped a line, Down never
+ * reached it, and the scroll that follows the caret stopped a line short.
+ *
+ * The line is the one the engine sets for an empty paragraph with a break
+ * after it — `lineBreak()`, a lone `\n` laid out in the value's style and
+ * options — moved down under the last line, so its height, baseline and
+ * place across the box (`textAlign`, the base direction), and the caret
+ * drawn on it, are that engine's: typing the next letter moves the caret
+ * along the line and nothing else. A lone break rather than no text, because
+ * ntk resolves an empty string's direction from paragraphs it does not have,
+ * and puts an RTL one against the left edge. An engine that already sets the
+ * line — its last line starts where the text ends — is left alone.
+ */
+export function withFinalLine(layout, text, lineBreak) {
+  const lines = layout.lines;
+  const last = lines?.[lines.length - 1];
+  if (!FINAL_BREAK.test(text) || !last || last.start >= text.length) {
+    return layout;
+  }
+  const lone = lineBreak();
+  const model = lone.lines?.[0];
+  if (!model) return layout;
+  const dy = last.y + last.height - model.y;
+  const line = {
+    x: model.x,
+    y: model.y + dy,
+    width: 0,
+    height: model.height,
+    baseline: model.baseline + dy,
+    ascent: model.ascent,
+    descent: model.descent,
+    start: text.length,
+    end: text.length,
+    runs: [],
+  };
+  const index = lines.length;
+  const end = Array.from(text).length;
+  const caret = lone.caretPosition(0);
+  return Object.create(layout, {
+    lines: { value: [...lines, line] },
+    height: { value: Math.max(layout.height, line.y + line.height) },
+    caretPosition: {
+      value: (cp) =>
+        cp >= end
+          ? { x: caret.x, y: caret.y + dy, height: caret.height, line: index }
+          : layout.caretPosition(cp),
+    },
+    indexAt: {
+      value: (x, y) => (y >= line.y ? end : layout.indexAt(x, y)),
+    },
+    // the engine draws, and measures the coverage of, the text it laid out
+    draw: { value: (ctx, x, y) => layout.draw(ctx, x, y) },
+    coverage: { value: (options) => layout.coverage?.(options) ?? null },
+  });
+}
 
 /**
  * <textarea>: multi-line editable text on the same editing core as
@@ -26,6 +97,8 @@ import { CARET_WIDTH, CARET_RESERVE, TextInputNode } from './textinput.js';
  * between visual lines keeping a goal column, Home/End are wrap-aware,
  * selection spans lines, and the view scrolls vertically to follow the
  * caret (wheel scrolls too). `rows` (default 3) sets the preferred height.
+ * Where the app's shortcuts are ⌘, the keys are the Mac's (textkeys.js):
+ * ⌘↑/⌘↓ for the ends of the value, ⌥↑/⌥↓ for a paragraph's.
  */
 export class TextAreaNode extends TextInputNode {
   /**
@@ -140,11 +213,13 @@ export class TextAreaNode extends TextInputNode {
     const key = `${width}|${color}|${shown}|${s.family}|${s.size}|${s.weight}|${s.style}|${direction}|${align}|${s.letterSpacing}|${JSON.stringify(s.features ?? null)}`;
     if (this._valueLayoutKey !== key) {
       this._valueLayoutKey = key;
-      this._valueLayoutCache = fonts.layout([{ text: shown, ...s, color }], s, {
-        maxWidth: container,
-        align,
-        direction,
-      });
+      const options = { maxWidth: container, align, direction };
+      const layout = fonts.layout([{ text: shown, ...s, color }], s, options);
+      this._valueLayoutCache = isEmpty
+        ? layout
+        : withFinalLine(layout, shown, () =>
+            fonts.layout([{ text: '\n', ...s, color }], s, options),
+          );
     }
     return this._valueLayoutCache;
   }
@@ -235,7 +310,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;
       }
@@ -263,17 +339,11 @@ export class TextAreaNode extends TextInputNode {
       return true;
     }
     if ((k === XK_HOME || k === XK_END) && layout && this.value.length > 0) {
-      const pos = layout.caretPosition(this._caret);
-      const line = layout.lines[pos.line];
-      const y = line.y + (line.ascent + line.descent) / 2;
-      // indexAt clamps into the line: far left = line start; just past the
-      // right edge = end of visible content (before the newline)
-      const i =
-        k === XK_HOME
-          ? layout.indexAt(-1e6, y)
-          : layout.indexAt(line.x + line.width + 0.01, y);
       this._goalX = null;
-      this._moveCaret(i, ev.shiftKey);
+      this._moveCaret(
+        this._lineEdge(this._caret, k === XK_HOME ? -1 : 1),
+        ev.shiftKey,
+      );
       return true;
     }
     this._goalX = null;
@@ -389,3 +459,5 @@ export class TextAreaNode extends TextInputNode {
     ctx.restore();
   }
 }
+
+installMethods(TextAreaNode, TextAreaKeys);

package/src/nodes/textinput.js

@@ -1,6 +1,7 @@
 // <textinput>: a single-line editable field — value, caret and selection,
 // the keys, the mouse, the clipboard, the edit menu and painting. Undo/redo
-// is in edithistory.js and IME composition in preedit.js, installed below.
+// is in edithistory.js, IME composition in preedit.js and the Mac's editing
+// keys in textkeys.js, installed below.
 
 import { localTextStyleChanged } from '../styles.js';
 import { Yoga } from '../yoga.js';
@@ -14,6 +15,7 @@ import { lastInputTime } from '../inputtime.js';
 import {
   ctrlChordLetter,
   MOD,
+  primaryModifierHeld,
   XK_BACKSPACE,
   XK_RETURN,
   XK_KP_ENTER,
@@ -31,6 +33,7 @@ import { installMethods } from './install.js';
 import { Node } from './node.js';
 import { TextInputPreedit } from './preedit.js';
 import { rangeBands } from './text.js';
+import { TextInputKeys } from './textkeys.js';
 
 /**
  * How long a caret stays in each of its two states, in milliseconds, on a
@@ -486,7 +489,11 @@ export class TextInputNode extends Node {
     const previous = this._keyNative;
     this._keyNative = ev.nativeEvent ?? null;
     try {
-      if (this._editKeyDown(ev)) ev.preventDefault();
+      // Where the app's shortcuts are ⌘ the keys are the Mac's (textkeys.js),
+      // and they come first: ⌃← and ⌃A mean something else to them than
+      // to the bindings in `_editKeyDown`.
+      const answered = this._macKeyDown(ev) ?? this._editKeyDown(ev);
+      if (answered) ev.preventDefault();
     } finally {
       this._keyNative = previous;
     }
@@ -550,7 +557,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 +571,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 +587,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');
@@ -1142,4 +1158,9 @@ export class TextInputNode extends Node {
 }
 
 // Undo/redo and IME composition live in their own files (see install.js).
-installMethods(TextInputNode, TextInputHistory, TextInputPreedit);
+installMethods(
+  TextInputNode,
+  TextInputHistory,
+  TextInputPreedit,
+  TextInputKeys,
+);

package/src/nodes/textkeys.js

@@ -0,0 +1,322 @@
+// The Mac's text-editing keys for <textinput> and <textarea>, and the caret
+// geometry they move by: the ends of a line, of a paragraph and of the
+// value, and a line up or down.
+//
+// The bindings are AppKit's own (StandardKeyBinding.dict, the table every
+// Cocoa field reads): ⌥ moves and deletes by word, ⌘ goes to the ends of the
+// line and of the document, ⌘⌫ deletes to the start of the line, and ⌃ is
+// the Emacs set — ⌃A and ⌃E to the ends of the paragraph, ⌃K kills to its
+// end and ⌃Y yanks it back. They apply where the app's shortcuts are pressed
+// with ⌘ (`app.primaryModifier`, the Cocoa app), which is a fact about the
+// backend rather than the platform: an X11 app under XQuartz is an X client
+// and keeps the bindings in textinput.js's `_editKeyDown` — GTK's, Qt's and
+// Windows', where Ctrl moves by word. The two sets disagree about Ctrl
+// outright, which is why the Mac's are not a layer over the others: ⌃← is
+// the start of the line here and a word there, and ⌃A is the start of the
+// paragraph here and Select All there.
+//
+// Directions are logical, as the rest of the field's keys are: ← is towards
+// the start of the value, also in a right-to-left field.
+
+import {
+  ctrlChordLetter,
+  primaryModifier,
+  XK_BACKSPACE,
+  XK_DELETE,
+  XK_DOWN,
+  XK_LEFT,
+  XK_RIGHT,
+  XK_UP,
+} from '../keysyms.js';
+
+/** A chord a Mac field answers by doing nothing — and typing nothing. */
+const NOTHING = 'noop';
+
+/**
+ * The AppKit command a key is bound to in a Mac text field — the selector's
+ * name without the colon or `AndModifySelection`, since Shift is the
+ * `extend` the command runs with — `NOTHING` for a chord the field types
+ * nothing for, or null for a key the field's own handling covers: typing, a
+ * plain arrow, Return, Tab, a ⌘ chord (Undo, Copy and the rest), and every
+ * ⌃ chord the Mac does not bind, which `_editKeyDown` types nothing for.
+ */
+function macBinding(ev) {
+  const cmd = ev.metaKey;
+  const ctrl = ev.ctrlKey;
+  const opt = ev.altKey;
+  switch (ev.keysym) {
+    case XK_LEFT:
+    case XK_RIGHT: {
+      const left = ev.keysym === XK_LEFT;
+      // ⌘⌃← sets the paragraph's writing direction, which a field leaves
+      // to its `direction` style
+      if (cmd && ctrl) return NOTHING;
+      // ⌃← is Mission Control's before it is the field's, and when the
+      // system lets it through AppKit binds it beside ⌘←, not to a word
+      if (cmd || ctrl) {
+        return left ? 'moveToLeftEndOfLine' : 'moveToRightEndOfLine';
+      }
+      if (opt) return left ? 'moveWordLeft' : 'moveWordRight';
+      return null;
+    }
+    case XK_UP:
+    case XK_DOWN: {
+      const up = ev.keysym === XK_UP;
+      if (cmd) return up ? 'moveToBeginningOfDocument' : 'moveToEndOfDocument';
+      // ⌃↑ scrolls a page without moving the caret, when Mission Control
+      // has not taken it
+      if (ctrl) return NOTHING;
+      if (opt) return up ? 'moveParagraphBackward' : 'moveParagraphForward';
+      return up ? 'moveUp' : 'moveDown';
+    }
+    case XK_BACKSPACE:
+      if (opt) return 'deleteWordBackward'; // ⌥⌫, and ⌥⌃⌫
+      if (cmd) return 'deleteToBeginningOfLine';
+      if (ctrl) return 'deleteBackwardByDecomposingPreviousCharacter';
+      return null;
+    case XK_DELETE:
+      if (opt) return 'deleteWordForward';
+      if (ctrl) return 'deleteForward';
+      return null;
+  }
+  // ⌃ and a letter: the Emacs set
+  if (!ctrl || cmd || opt) return null;
+  switch (ctrlChordLetter(ev)) {
+    case 0x61 /* a */:
+      return 'moveToBeginningOfParagraph';
+    case 0x65 /* e */:
+      return 'moveToEndOfParagraph';
+    case 0x62 /* b */:
+      return 'moveBackward';
+    case 0x66 /* f */:
+      return 'moveForward';
+    case 0x70 /* p */:
+      return 'moveUp';
+    case 0x6e /* n */:
+      return 'moveDown';
+    case 0x68 /* h */:
+      return 'deleteBackward';
+    case 0x64 /* d */:
+      return 'deleteForward';
+    case 0x6b /* k */:
+      return 'deleteToEndOfParagraph';
+    case 0x79 /* y */:
+      return 'yank';
+  }
+  return null;
+}
+
+/**
+ * What ⌃K killed, per application: AppKit's kill buffer, which is its own
+ * and not the pasteboard — a kill does not replace what ⌘C copied, and ⌃Y
+ * in one field yanks what ⌃K killed in another.
+ */
+const killBuffers = new WeakMap();
+const NO_APP = {};
+
+/** Mac text keys for `TextInputNode`, installed by textinput.js. */
+export class TextInputKeys {
+  /**
+   * The Mac binding for this key, run, ahead of `_editKeyDown`. Answers
+   * whether the field took the key, as `_editKeyDown` does — false for a
+   * chord the field types nothing for — and undefined where the key is not
+   * a Mac binding, or this app does not edit with them.
+   */
+  _macKeyDown(ev) {
+    // the Mac's keys go with the Mac's shortcuts, read off the app on every
+    // key rather than cached, like every capability an app object carries
+    if (primaryModifier(this.app) !== 'Super') return undefined;
+    const command = macBinding(ev);
+    if (command == null) return undefined;
+    if (command === NOTHING) return false;
+    this._runTextCommand(command, Boolean(ev.shiftKey));
+    return true;
+  }
+
+  /** One AppKit editing command; `extend` keeps the anchor where it is. */
+  _runTextCommand(command, extend) {
+    const [a, b] = this._selection();
+    const hasSelection = a !== b;
+    const caret = this._caret;
+    const length = this._chars().length;
+    const move = (index) => this._moveCaret(index, extend);
+    switch (command) {
+      case 'moveBackward':
+        return move(!extend && hasSelection ? a : caret - 1);
+      case 'moveForward':
+        return move(!extend && hasSelection ? b : caret + 1);
+      case 'moveWordLeft':
+        return move(this._wordBoundary(caret, -1));
+      case 'moveWordRight':
+        return move(this._wordBoundary(caret, 1));
+      case 'moveToLeftEndOfLine':
+        return move(this._lineEdge(caret, -1));
+      case 'moveToRightEndOfLine':
+        return move(this._lineEdge(caret, 1));
+      case 'moveToBeginningOfParagraph':
+        return move(this._paragraphEdge(caret, -1));
+      case 'moveToEndOfParagraph':
+        return move(this._paragraphEdge(caret, 1));
+      // ⌥↑ is AppKit's (moveBackward:, moveToBeginningOfParagraph:): a caret
+      // already at the start of a paragraph goes on to the previous one's
+      case 'moveParagraphBackward':
+        return move(
+          this._paragraphEdge(!extend && hasSelection ? a : caret - 1, -1),
+        );
+      case 'moveParagraphForward':
+        return move(
+          this._paragraphEdge(!extend && hasSelection ? b : caret + 1, 1),
+        );
+      case 'moveToBeginningOfDocument':
+        return move(0);
+      case 'moveToEndOfDocument':
+        return move(length);
+      case 'moveUp':
+        return move(this._verticalStep(-1));
+      case 'moveDown':
+        return move(this._verticalStep(1));
+    }
+    if (hasSelection && command !== 'yank') {
+      if (command === 'deleteToEndOfParagraph') this._kill(a, b);
+      else this._deleteRange(a, b);
+      return;
+    }
+    switch (command) {
+      case 'deleteBackward':
+        if (caret > 0) this._deleteRange(caret - 1, caret, 'delete-back');
+        return;
+      case 'deleteForward':
+        if (caret < length) {
+          this._deleteRange(caret, caret + 1, 'delete-forward');
+        }
+        return;
+      case 'deleteWordBackward':
+        return this._deleteRange(this._wordBoundary(caret, -1), caret);
+      case 'deleteWordForward':
+        return this._deleteRange(caret, this._wordBoundary(caret, 1));
+      case 'deleteToBeginningOfLine':
+        return this._deleteRange(this._lineEdge(caret, -1), caret);
+      case 'deleteToEndOfParagraph': {
+        // at the end of a paragraph, the kill takes the line break, which
+        // joins the next paragraph to this one — Emacs's ⌃K, and AppKit's
+        const end = this._paragraphEdge(caret, 1);
+        this._kill(caret, end > caret ? end : Math.min(caret + 1, length));
+        return;
+      }
+      case 'deleteBackwardByDecomposingPreviousCharacter':
+        return this._deleteDecomposing(caret);
+      case 'yank': {
+        const text = killBuffers.get(this.app ?? NO_APP)?.text;
+        if (text) this._insert(text);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Delete `[from, to)` into the kill buffer. Kills one after another — ⌃K,
+   * ⌃K, with nothing in between — add up, so the two that take a line and
+   * then its break yank back as the line.
+   *
+   * A `sensitive` field deletes and keeps nothing, for the reason it offers
+   * no Copy: the text would outlive the field.
+   */
+  _kill(from, to) {
+    if (to <= from) return;
+    const chars = this._chars();
+    const killed = chars.slice(from, to).join('');
+    // What the kill leaves, worked out rather than read back: a controlled
+    // field's `value` is the parent's until it re-renders.
+    const left = [...chars.slice(0, from), ...chars.slice(to)].join('');
+    const key = this.app ?? NO_APP;
+    const buffer = killBuffers.get(key);
+    const last = this._lastKill;
+    const appends =
+      buffer != null &&
+      last?.buffer === buffer &&
+      last.value === this.value &&
+      last.caret === from;
+    this._deleteRange(from, to);
+    if (this.props.sensitive) return;
+    const next = { text: appends ? buffer.text + killed : killed };
+    killBuffers.set(key, next);
+    this._lastKill = { buffer: next, value: left, caret: from };
+  }
+
+  /**
+   * ⌃⌫: take the last mark off the character before the caret — `é` back to
+   * `e` — and delete the character only when it has none.
+   */
+  _deleteDecomposing(caret) {
+    if (caret === 0) return;
+    const chars = this._chars();
+    const parts = Array.from(chars[caret - 1].normalize('NFD'));
+    if (parts.length < 2) {
+      this._deleteRange(caret - 1, caret, 'delete-back');
+      return;
+    }
+    const left = Array.from(parts.slice(0, -1).join('').normalize('NFC'));
+    this._commit(
+      [...chars.slice(0, caret - 1), ...left, ...chars.slice(caret)],
+      caret - 1 + left.length,
+    );
+  }
+
+  /** The start (`dir` < 0) or end of the paragraph `index` is in: the
+   * value's ends in a single line, a line break's two sides in a textarea. */
+  _paragraphEdge(index, dir) {
+    const chars = this._chars();
+    let i = Math.min(Math.max(0, index), chars.length);
+    if (dir < 0) {
+      while (i > 0 && chars[i - 1] !== '\n') i--;
+    } else {
+      while (i < chars.length && chars[i] !== '\n') i++;
+    }
+    return i;
+  }
+
+  /** The start or end of the line `index` is on as it is drawn. One line
+   * here; a textarea's wraps. */
+  _lineEdge(index, dir) {
+    return this._paragraphEdge(index, dir);
+  }
+
+  /** Where ↑ and ↓ take the caret: in a single line, as in an NSTextField,
+   * to its start and its end. */
+  _verticalStep(dir) {
+    return dir < 0 ? 0 : this._chars().length;
+  }
+}
+
+/** Mac text keys for `TextAreaNode`, installed by textarea.js. */
+export class TextAreaKeys {
+  /** ↑ and ↓ keep the goal column they set; every other command is a fresh
+   * start, as every other key is in `_editKeyDown`. */
+  _runTextCommand(command, extend) {
+    if (command !== 'moveUp' && command !== 'moveDown') this._goalX = null;
+    return super._runTextCommand(command, extend);
+  }
+
+  /** The wrapped line's ends, as Home and End find them. */
+  _lineEdge(index, dir) {
+    const layout = this._valueLayout();
+    if (!layout || this.value.length === 0) {
+      return super._lineEdge(index, dir);
+    }
+    const pos = layout.caretPosition(index);
+    const line = layout.lines[pos.line];
+    const y = line.y + (line.ascent + line.descent) / 2;
+    // indexAt clamps into the line: far left = line start; just past the
+    // right edge = end of visible content (before the newline)
+    return dir < 0
+      ? layout.indexAt(-1e6, y)
+      : layout.indexAt(line.x + line.width + 0.01, y);
+  }
+
+  /** A visual line up or down, keeping the goal column. */
+  _verticalStep(dir) {
+    const layout = this._valueLayout();
+    if (!layout || this.value.length === 0) return this._caret;
+    return this._verticalMove(layout, dir);
+  }
+}

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;