react-x11 2.39.0 → 2.41.0

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 {
@@ -139,10 +140,14 @@ export interface KeyboardEvent<T = DrawnNode> extends SyntheticEvent<T> {
    * group and sends no other notice. */
   group: number;
   /** Unicode code point, undefined when the key produces no character —
-   * which includes every key a composition took (see `composing`). */
+   * which includes every key a composition took (see `composing`), a dead
+   * key on the Cocoa backend, and a key that typed more than one character
+   * there, whose text arrives as a composition that starts and ends on it. */
   codepoint?: number;
   /** The character the key produced, undefined for non-printing keys and
-   * for keys a composition took. */
+   * for the keys `codepoint` is undefined for. On the Cocoa backend it is
+   * what the layout typed with ⌥ applied — `ß` for ⌥S — while `keysym` is
+   * still the key. */
   key?: string;
   /** Whether this key belongs to an open composition — a dead key, or a key
    * of a Compose sequence. Its text arrives on the composition events
@@ -331,7 +336,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 +561,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 +575,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 +605,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;
 }