@rapidmx/web-client 0.20.0 → 0.21.0

package/apps/shared/keyboard/dispatch.ts

@@ -1,124 +1,124 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import type { ShortcutScope } from "./keymap.js";
-import { matchesEvent } from "./match.js";
-import { ParsedSpec, resolveModifiers } from "./parse.js";
-import type { KeyEnvironment } from "./platform.js";
-import type { Registration, ShortcutRegistry } from "./registry.js";
-import { isActivatable, isInPopoverDialog, isInWidget, isModalOpen, isPopupOpenAt, isTextEntry, regionScopeOf } from "./targets.js";
-
-/** The keys of the four view scopes: only the mounted view has registrations, so precedence among them is moot. */
-const VIEW_SCOPES: readonly ShortcutScope[] = ["mail", "calendar", "contacts", "tasks"];
-
-/** Keys that move the caret or delete text, which a text field owns even with Ctrl or Alt held (word jumps, delete-word). */
-const EDITING_KEYS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright", "home", "end", "pageup", "pagedown", "backspace", "delete"]);
-
-/** The Copy / Cut / Paste / Select all / Undo / Redo / Find chords: never a shortcut, anywhere - they act on the page's selection, not on a view. */
-function isReservedChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && !modifiers.shift && ["a", "c", "v", "x", "z", "y", "f"].includes(parsed.key);
-}
-
-/** Paste as plain text (Ctrl+Shift+V) and Redo (Ctrl+Shift+Z): text-editing chords in a field, free everywhere else (Ctrl+Shift+V is Move to). */
-function isShiftedEditingChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && modifiers.shift && ["z", "v"].includes(parsed.key);
-}
-
-/**
- * Whether `parsed` may fire with the event on this target.
- *
- * A text field (input, textarea, select, contenteditable - the rich-text editor) keeps everything that types or edits: bare keys
- * (`j`, `?`, Delete), the caret keys with any modifier, and paste-as-plain-text and redo. A chord with Ctrl/Cmd/Alt works from one (that is how Ctrl+Enter sends from
- * the body), except that Option on a Mac and Ctrl+Alt (AltGr) elsewhere type characters, so those don't. Escape works from a field unless a
- * popup it owns is open (or it is in a popover dialog of its own). Outside a field, a bare key still isn't taken from a widget that reads keys itself (an open menu, a list box), and
- * Enter/Space are left to the button or link that has the focus - unless the shortcut asked for them.
- */
-function allowedOnTarget(registration: Registration, parsed: ParsedSpec, target: EventTarget | null, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    const command = modifiers.ctrl || modifiers.meta || modifiers.alt;
-    if (parsed.key === "escape" && (isPopupOpenAt(target) || isInPopoverDialog(target))) {
-        return false;
-    }
-    if (isTextEntry(target)) {
-        if (parsed.key === "escape") {
-            return true;
-        }
-        if (!command || EDITING_KEYS.has(parsed.key) || isShiftedEditingChord(parsed, env)) {
-            return false;
-        }
-        return !(modifiers.alt && !modifiers.meta && (env.mac || modifiers.ctrl));
-    }
-    if (!command) {
-        if (isInWidget(target)) {
-            return false;
-        }
-        if ((parsed.key === "enter" || parsed.key === " ") && !registration.shortcut.allowOnActivatable && isActivatable(target)) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** The scopes that may act on this event, highest precedence first. */
-function activeScopes(event: KeyboardEvent, doc: Document): readonly ShortcutScope[] {
-    if (isModalOpen(doc)) {
-        return ["dialog"];
-    }
-    if (regionScopeOf(event.target) === "compose") {
-        return ["compose", "global"];
-    }
-    return [...VIEW_SCOPES, "global"];
-}
-
-/** Whether the registration applies to where the event happened (a compose window's shortcuts only inside it). */
-function inContainer(registration: Registration, event: KeyboardEvent): boolean {
-    if (!registration.container) {
-        return true;
-    }
-    return !!registration.container.current?.contains(event.target as Node | null);
-}
-
-/**
- * Handles one `keydown`: finds the registered shortcut it is, and runs its handler. Returns whether a handler ran - and only then is the
- * event's default prevented and its propagation stopped, so a key nobody claims (or a handler that declines) behaves exactly as if this layer
- * did not exist.
- *
- * Skipped outright: an event some other handler already `defaultPrevented` (a menu, the rich-text editor's own bindings), one from an IME
- * composition, a bare modifier key, and the Copy/Cut/Paste/Select all/Undo/Redo/Find chords. A held key repeats: an action that is not
- * marked `repeat` runs on the first press only, and the repeats are swallowed (so a browser doesn't reload on a held Ctrl+R) without running it.
- *
- * Which registration wins: the dialog scope alone while a modal is open; else, inside a compose window, `compose` then `global`; else
- * whichever view is mounted, then `global`. Within a scope the most recently mounted registration goes first, and one that returns
- * `false` passes the key on to the next.
- */
-export function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean {
-    if (event.defaultPrevented || event.isComposing || event.key === "Process" || ["Control", "Shift", "Alt", "Meta"].includes(event.key)) {
-        return false;
-    }
-    const scopes = activeScopes(event, doc);
-    const candidates = registry
-        .getSnapshot()
-        .filter((registration) => scopes.includes(registration.scope) && inContainer(registration, event))
-        .sort((a, b) => scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || b.order - a.order);
-    for (const registration of candidates) {
-        const specs = env.electron ? [...registration.keys, ...registration.electronKeys] : registration.keys;
-        const parsed = specs.find((spec) => matchesEvent(spec, event, env));
-        if (!parsed || isReservedChord(parsed, env) || !allowedOnTarget(registration, parsed, event.target, env)) {
-            continue;
-        }
-        if (event.repeat && !registration.shortcut.repeat) {
-            event.preventDefault();
-            event.stopPropagation();
-            return true;
-        }
-        if (registration.run(event) !== false) {
-            event.preventDefault();
-            event.stopPropagation();
-            return true;
-        }
-    }
-    return false;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ShortcutScope } from "./keymap.js";
+import { matchesEvent } from "./match.js";
+import { ParsedSpec, resolveModifiers } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+import type { Registration, ShortcutRegistry } from "./registry.js";
+import { isActivatable, isInPopoverDialog, isInWidget, isModalOpen, isPopupOpenAt, isTextEntry, regionScopeOf } from "./targets.js";
+
+/** The keys of the four view scopes: only the mounted view has registrations, so precedence among them is moot. */
+const VIEW_SCOPES: readonly ShortcutScope[] = ["mail", "calendar", "contacts", "tasks"];
+
+/** Keys that move the caret or delete text, which a text field owns even with Ctrl or Alt held (word jumps, delete-word). */
+const EDITING_KEYS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright", "home", "end", "pageup", "pagedown", "backspace", "delete"]);
+
+/** The Copy / Cut / Paste / Select all / Undo / Redo / Find chords: never a shortcut, anywhere - they act on the page's selection, not on a view. */
+function isReservedChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && !modifiers.shift && ["a", "c", "v", "x", "z", "y", "f"].includes(parsed.key);
+}
+
+/** Paste as plain text (Ctrl+Shift+V) and Redo (Ctrl+Shift+Z): text-editing chords in a field, free everywhere else (Ctrl+Shift+V is Move to). */
+function isShiftedEditingChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && modifiers.shift && ["z", "v"].includes(parsed.key);
+}
+
+/**
+ * Whether `parsed` may fire with the event on this target.
+ *
+ * A text field (input, textarea, select, contenteditable - the rich-text editor) keeps everything that types or edits: bare keys
+ * (`j`, `?`, Delete), the caret keys with any modifier, and paste-as-plain-text and redo. A chord with Ctrl/Cmd/Alt works from one (that is how Ctrl+Enter sends from
+ * the body), except that Option on a Mac and Ctrl+Alt (AltGr) elsewhere type characters, so those don't. Escape works from a field unless a
+ * popup it owns is open (or it is in a popover dialog of its own). Outside a field, a bare key still isn't taken from a widget that reads keys itself (an open menu, a list box), and
+ * Enter/Space are left to the button or link that has the focus - unless the shortcut asked for them.
+ */
+function allowedOnTarget(registration: Registration, parsed: ParsedSpec, target: EventTarget | null, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    const command = modifiers.ctrl || modifiers.meta || modifiers.alt;
+    if (parsed.key === "escape" && (isPopupOpenAt(target) || isInPopoverDialog(target))) {
+        return false;
+    }
+    if (isTextEntry(target)) {
+        if (parsed.key === "escape") {
+            return true;
+        }
+        if (!command || EDITING_KEYS.has(parsed.key) || isShiftedEditingChord(parsed, env)) {
+            return false;
+        }
+        return !(modifiers.alt && !modifiers.meta && (env.mac || modifiers.ctrl));
+    }
+    if (!command) {
+        if (isInWidget(target)) {
+            return false;
+        }
+        if ((parsed.key === "enter" || parsed.key === " ") && !registration.shortcut.allowOnActivatable && isActivatable(target)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** The scopes that may act on this event, highest precedence first. */
+function activeScopes(event: KeyboardEvent, doc: Document): readonly ShortcutScope[] {
+    if (isModalOpen(doc)) {
+        return ["dialog"];
+    }
+    if (regionScopeOf(event.target) === "compose") {
+        return ["compose", "global"];
+    }
+    return [...VIEW_SCOPES, "global"];
+}
+
+/** Whether the registration applies to where the event happened (a compose window's shortcuts only inside it). */
+function inContainer(registration: Registration, event: KeyboardEvent): boolean {
+    if (!registration.container) {
+        return true;
+    }
+    return !!registration.container.current?.contains(event.target as Node | null);
+}
+
+/**
+ * Handles one `keydown`: finds the registered shortcut it is, and runs its handler. Returns whether a handler ran - and only then is the
+ * event's default prevented and its propagation stopped, so a key nobody claims (or a handler that declines) behaves exactly as if this layer
+ * did not exist.
+ *
+ * Skipped outright: an event some other handler already `defaultPrevented` (a menu, the rich-text editor's own bindings), one from an IME
+ * composition, a bare modifier key, and the Copy/Cut/Paste/Select all/Undo/Redo/Find chords. A held key repeats: an action that is not
+ * marked `repeat` runs on the first press only, and the repeats are swallowed (so a browser doesn't reload on a held Ctrl+R) without running it.
+ *
+ * Which registration wins: the dialog scope alone while a modal is open; else, inside a compose window, `compose` then `global`; else
+ * whichever view is mounted, then `global`. Within a scope the most recently mounted registration goes first, and one that returns
+ * `false` passes the key on to the next.
+ */
+export function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean {
+    if (event.defaultPrevented || event.isComposing || event.key === "Process" || ["Control", "Shift", "Alt", "Meta"].includes(event.key)) {
+        return false;
+    }
+    const scopes = activeScopes(event, doc);
+    const candidates = registry
+        .getSnapshot()
+        .filter((registration) => scopes.includes(registration.scope) && inContainer(registration, event))
+        .sort((a, b) => scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || b.order - a.order);
+    for (const registration of candidates) {
+        const specs = env.electron ? [...registration.keys, ...registration.electronKeys] : registration.keys;
+        const parsed = specs.find((spec) => matchesEvent(spec, event, env));
+        if (!parsed || isReservedChord(parsed, env) || !allowedOnTarget(registration, parsed, event.target, env)) {
+            continue;
+        }
+        if (event.repeat && !registration.shortcut.repeat) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+        if (registration.run(event) !== false) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+    }
+    return false;
+}

package/apps/shared/keyboard/format.ts

@@ -1,89 +1,89 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import type { ShortcutDef } from "./keymap.js";
-import { parseSpec, resolveModifiers } from "./parse.js";
-import type { KeyEnvironment } from "./platform.js";
-
-const KEY_NAMES: Record<string, string> = {
-    escape: "Esc",
-    enter: "Enter",
-    tab: "Tab",
-    backspace: "Backspace",
-    delete: "Delete",
-    insert: "Insert",
-    home: "Home",
-    end: "End",
-    pageup: "Page Up",
-    pagedown: "Page Down",
-    arrowup: "↑",
-    arrowdown: "↓",
-    arrowleft: "←",
-    arrowright: "→",
-    " ": "Space",
-};
-
-const MAC_KEY_NAMES: Record<string, string> = { ...KEY_NAMES, enter: "↩", backspace: "⌫", delete: "⌦" };
-
-/** The key as it is printed on a key cap: `R`, `F5`, `Enter`, an arrow. */
-function keyLabel(key: string, mac: boolean): string {
-    return (mac ? MAC_KEY_NAMES : KEY_NAMES)[key] ?? key.toUpperCase();
-}
-
-/** A spec as a person reads it: `Ctrl+Shift+R`, or `⌃⇧R`-style glyphs on a Mac (`⌘` for Cmd, `⌥` for Option). */
-export function formatSpec(spec: string, env: KeyEnvironment): string {
-    const parsed = parseSpec(spec);
-    const modifiers = resolveModifiers(parsed, env);
-    if (env.mac) {
-        return [modifiers.ctrl && "⌃", modifiers.alt && "⌥", modifiers.shift && "⇧", modifiers.meta && "⌘", keyLabel(parsed.key, true)]
-            .filter(Boolean)
-            .join("");
-    }
-    return [modifiers.ctrl && "Ctrl", modifiers.shift && "Shift", modifiers.alt && "Alt", modifiers.meta && "Meta", keyLabel(parsed.key, false)]
-        .filter(Boolean)
-        .join("+");
-}
-
-const ARIA_NAMED_KEYS: Record<string, string> = {
-    escape: "Escape",
-    enter: "Enter",
-    tab: "Tab",
-    backspace: "Backspace",
-    delete: "Delete",
-    insert: "Insert",
-    home: "Home",
-    end: "End",
-    pageup: "PageUp",
-    pagedown: "PageDown",
-    arrowup: "ArrowUp",
-    arrowdown: "ArrowDown",
-    arrowleft: "ArrowLeft",
-    arrowright: "ArrowRight",
-    " ": "Space",
-};
-
-/** A spec in `aria-keyshortcuts` syntax: `Control+Shift+R`, `Meta+R`. */
-export function ariaSpec(spec: string, env: KeyEnvironment): string {
-    const parsed = parseSpec(spec);
-    const modifiers = resolveModifiers(parsed, env);
-    const key = ARIA_NAMED_KEYS[parsed.key] ?? parsed.key.toUpperCase();
-    return [modifiers.ctrl && "Control", modifiers.alt && "Alt", modifiers.shift && "Shift", modifiers.meta && "Meta", key].filter(Boolean).join("+");
-}
-
-/** Every spec that triggers a shortcut here: its keys, and in the desktop client also its desktop-only ones. */
-export function specsFor(shortcut: ShortcutDef, env: KeyEnvironment): string[] {
-    return env.electron && shortcut.electronKeys ? [...shortcut.keys, ...shortcut.electronKeys] : [...shortcut.keys];
-}
-
-/** The `aria-keyshortcuts` value for a control that runs a shortcut: every alternative, space separated. */
-export function ariaKeyShortcuts(shortcut: ShortcutDef, env: KeyEnvironment): string {
-    return specsFor(shortcut, env)
-        .map((spec) => ariaSpec(spec, env))
-        .join(" ");
-}
-
-/** A tooltip/name suffix such as `Reply (Ctrl+R)`: the label with the shortcut's first key. */
-export function withHint(label: string, shortcut: ShortcutDef, env: KeyEnvironment): string {
-    return `${label} (${formatSpec(shortcut.keys[0], env)})`;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ShortcutDef } from "./keymap.js";
+import { parseSpec, resolveModifiers } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+
+const KEY_NAMES: Record<string, string> = {
+    escape: "Esc",
+    enter: "Enter",
+    tab: "Tab",
+    backspace: "Backspace",
+    delete: "Delete",
+    insert: "Insert",
+    home: "Home",
+    end: "End",
+    pageup: "Page Up",
+    pagedown: "Page Down",
+    arrowup: "↑",
+    arrowdown: "↓",
+    arrowleft: "←",
+    arrowright: "→",
+    " ": "Space",
+};
+
+const MAC_KEY_NAMES: Record<string, string> = { ...KEY_NAMES, enter: "↩", backspace: "⌫", delete: "⌦" };
+
+/** The key as it is printed on a key cap: `R`, `F5`, `Enter`, an arrow. */
+function keyLabel(key: string, mac: boolean): string {
+    return (mac ? MAC_KEY_NAMES : KEY_NAMES)[key] ?? key.toUpperCase();
+}
+
+/** A spec as a person reads it: `Ctrl+Shift+R`, or `⌃⇧R`-style glyphs on a Mac (`⌘` for Cmd, `⌥` for Option). */
+export function formatSpec(spec: string, env: KeyEnvironment): string {
+    const parsed = parseSpec(spec);
+    const modifiers = resolveModifiers(parsed, env);
+    if (env.mac) {
+        return [modifiers.ctrl && "⌃", modifiers.alt && "⌥", modifiers.shift && "⇧", modifiers.meta && "⌘", keyLabel(parsed.key, true)]
+            .filter(Boolean)
+            .join("");
+    }
+    return [modifiers.ctrl && "Ctrl", modifiers.shift && "Shift", modifiers.alt && "Alt", modifiers.meta && "Meta", keyLabel(parsed.key, false)]
+        .filter(Boolean)
+        .join("+");
+}
+
+const ARIA_NAMED_KEYS: Record<string, string> = {
+    escape: "Escape",
+    enter: "Enter",
+    tab: "Tab",
+    backspace: "Backspace",
+    delete: "Delete",
+    insert: "Insert",
+    home: "Home",
+    end: "End",
+    pageup: "PageUp",
+    pagedown: "PageDown",
+    arrowup: "ArrowUp",
+    arrowdown: "ArrowDown",
+    arrowleft: "ArrowLeft",
+    arrowright: "ArrowRight",
+    " ": "Space",
+};
+
+/** A spec in `aria-keyshortcuts` syntax: `Control+Shift+R`, `Meta+R`. */
+export function ariaSpec(spec: string, env: KeyEnvironment): string {
+    const parsed = parseSpec(spec);
+    const modifiers = resolveModifiers(parsed, env);
+    const key = ARIA_NAMED_KEYS[parsed.key] ?? parsed.key.toUpperCase();
+    return [modifiers.ctrl && "Control", modifiers.alt && "Alt", modifiers.shift && "Shift", modifiers.meta && "Meta", key].filter(Boolean).join("+");
+}
+
+/** Every spec that triggers a shortcut here: its keys, and in the desktop client also its desktop-only ones. */
+export function specsFor(shortcut: ShortcutDef, env: KeyEnvironment): string[] {
+    return env.electron && shortcut.electronKeys ? [...shortcut.keys, ...shortcut.electronKeys] : [...shortcut.keys];
+}
+
+/** The `aria-keyshortcuts` value for a control that runs a shortcut: every alternative, space separated. */
+export function ariaKeyShortcuts(shortcut: ShortcutDef, env: KeyEnvironment): string {
+    return specsFor(shortcut, env)
+        .map((spec) => ariaSpec(spec, env))
+        .join(" ");
+}
+
+/** A tooltip/name suffix such as `Reply (Ctrl+R)`: the label with the shortcut's first key. */
+export function withHint(label: string, shortcut: ShortcutDef, env: KeyEnvironment): string {
+    return `${label} (${formatSpec(shortcut.keys[0], env)})`;
+}