@rapidmx/web-client 0.9.0 → 0.11.0

package/apps/shared/keyboard/format.ts

@@ -0,0 +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)})`;
+}

package/apps/shared/keyboard/keymap.ts

@@ -0,0 +1,114 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Where a shortcut applies. `global` works in every view; a view scope (`mail`, `calendar`, `contacts`, `tasks`) exists only while that
+ * view is mounted; `compose` applies while focus is inside a compose window; `dialog` is for what a modal dialog binds itself - a
+ * dialog on screen silences every other scope.
+ */
+export type ShortcutScope = "global" | "mail" | "compose" | "calendar" | "contacts" | "tasks" | "dialog";
+
+/** The scopes the help dialog lists, in the order it lists them. */
+export const HELP_SCOPES: readonly ShortcutScope[] = ["global", "mail", "compose", "calendar", "contacts", "tasks"];
+
+export const SCOPE_LABELS: Record<ShortcutScope, string> = {
+    global: "Global",
+    mail: "Mail",
+    compose: "Compose",
+    calendar: "Calendar",
+    contacts: "Contacts",
+    tasks: "Tasks",
+    dialog: "Dialog",
+};
+
+/** One action the keyboard can trigger, and the keys that trigger it. Views register handlers for these; nothing else defines a key. */
+export interface ShortcutDef {
+    /** Stable name, unique across the map - what the help dialog de-duplicates on. */
+    id: string;
+    /** Specs (see `parseSpec()`) that trigger it, the first being the one shown first. `mod` is Ctrl, or Cmd on macOS. */
+    keys: readonly string[];
+    /** Extra specs that apply only in the desktop client, where the browser's own reserved keys (Ctrl+N, Ctrl+T) are the app's. */
+    electronKeys?: readonly string[];
+    /** What the help dialog and a button's tooltip call it. */
+    label: string;
+    scope: ShortcutScope;
+    /** Fires from a focused button or link too (Enter on a message row); by default Enter/Space are left to what has the focus. */
+    allowOnActivatable?: boolean;
+    /** Keeps firing while the key is held (arrows); by default a held key runs a one-shot action once. */
+    repeat?: boolean;
+}
+
+function def<T extends ShortcutDef>(shortcut: T): T {
+    return shortcut;
+}
+
+/**
+ * The whole key map, in the order the help dialog lists it. The navigation set is literally Ctrl+Shift+<letter> on every platform (Cmd+Shift
+ * on macOS collides with the browsers' own - Cmd+Shift+A/B/C/L/M/S are tab search, the bookmarks bar, Inspect, the sidebar, the profile
+ * switcher and Save As - so it is not offered); the mail actions use `mod`, so Reply is Ctrl+R on Windows and Linux and Cmd+R on a Mac.
+ * Ctrl+Q (mark read) stays Ctrl on a Mac because Cmd+Q is the system's Quit.
+ */
+export const SHORTCUTS = {
+    global: {
+        account: def({ id: "go.account", keys: ["ctrl+shift+a"], label: "Go to Account", scope: "global" }),
+        settings: def({ id: "go.settings", keys: ["ctrl+shift+s"], label: "Go to Settings", scope: "global" }),
+        contacts: def({ id: "go.contacts", keys: ["ctrl+shift+b"], label: "Go to Contacts", scope: "global" }),
+        mail: def({ id: "go.mail", keys: ["ctrl+shift+m"], label: "Go to Mail", scope: "global" }),
+        calendar: def({ id: "go.calendar", keys: ["ctrl+shift+c"], label: "Go to Calendar", scope: "global" }),
+        tasks: def({ id: "go.tasks", keys: ["ctrl+shift+l"], electronKeys: ["ctrl+shift+t"], label: "Go to Tasks", scope: "global" }),
+        help: def({ id: "help", keys: ["?", "ctrl+/"], label: "Keyboard shortcuts", scope: "global" }),
+    },
+    mail: {
+        create: def({ id: "mail.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New message", scope: "mail" }),
+        reply: def({ id: "mail.reply", keys: ["mod+r"], label: "Reply", scope: "mail" }),
+        replyAll: def({ id: "mail.replyAll", keys: ["mod+shift+r"], label: "Reply all", scope: "mail" }),
+        forward: def({ id: "mail.forward", keys: ["mod+shift+f"], label: "Forward", scope: "mail" }),
+        delete: def({ id: "mail.delete", keys: ["mod+d", "delete"], label: "Delete", scope: "mail" }),
+        archive: def({ id: "mail.archive", keys: ["e", "backspace"], label: "Archive", scope: "mail" }),
+        move: def({ id: "mail.move", keys: ["mod+shift+v"], label: "Move to folder", scope: "mail" }),
+        markRead: def({ id: "mail.markRead", keys: ["ctrl+q"], label: "Mark as read", scope: "mail" }),
+        markUnread: def({ id: "mail.markUnread", keys: ["mod+u"], label: "Mark as unread", scope: "mail" }),
+        flag: def({ id: "mail.flag", keys: ["insert"], label: "Flag or unflag", scope: "mail" }),
+        next: def({ id: "mail.next", keys: ["arrowdown", "j"], label: "Next message", scope: "mail", repeat: true }),
+        previous: def({ id: "mail.previous", keys: ["arrowup", "k"], label: "Previous message", scope: "mail", repeat: true }),
+        nextUnread: def({ id: "mail.nextUnread", keys: ["ctrl+."], label: "Next unread message", scope: "mail" }),
+        previousUnread: def({ id: "mail.previousUnread", keys: ["ctrl+,"], label: "Previous unread message", scope: "mail" }),
+        open: def({ id: "mail.open", keys: ["enter"], label: "Open the message on its own page", scope: "mail", allowOnActivatable: true }),
+        close: def({ id: "mail.close", keys: ["escape"], label: "Clear the selection", scope: "mail" }),
+        search: def({ id: "mail.search", keys: ["/", "mod+e"], label: "Search mail", scope: "mail" }),
+    },
+    compose: {
+        create: def({ id: "compose.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New message", scope: "compose" }),
+        send: def({ id: "compose.send", keys: ["mod+enter"], label: "Send", scope: "compose" }),
+        saveDraft: def({ id: "compose.saveDraft", keys: ["mod+s"], label: "Save draft", scope: "compose" }),
+        close: def({ id: "compose.close", keys: ["escape"], label: "Close (keeps the draft)", scope: "compose" }),
+    },
+    calendar: {
+        create: def({ id: "calendar.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New event", scope: "calendar" }),
+        today: def({ id: "calendar.today", keys: ["t"], label: "Go to today", scope: "calendar" }),
+        previous: def({ id: "calendar.previous", keys: ["arrowleft", "mod+arrowleft"], label: "Previous period", scope: "calendar", repeat: true }),
+        next: def({ id: "calendar.next", keys: ["arrowright", "mod+arrowright"], label: "Next period", scope: "calendar", repeat: true }),
+        day: def({ id: "calendar.day", keys: ["ctrl+alt+1"], label: "Day view", scope: "calendar" }),
+        workWeek: def({ id: "calendar.workWeek", keys: ["ctrl+alt+2"], label: "Work week view", scope: "calendar" }),
+        week: def({ id: "calendar.week", keys: ["ctrl+alt+3"], label: "Week view", scope: "calendar" }),
+        month: def({ id: "calendar.month", keys: ["ctrl+alt+4"], label: "Month view", scope: "calendar" }),
+    },
+    contacts: {
+        create: def({ id: "contacts.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New contact", scope: "contacts" }),
+        search: def({ id: "contacts.search", keys: ["/", "mod+e"], label: "Search contacts", scope: "contacts" }),
+    },
+    tasks: {
+        create: def({ id: "tasks.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New task", scope: "tasks" }),
+    },
+} as const;
+
+/** Every shortcut of the map flattened, in listing order. */
+export const ALL_SHORTCUTS: readonly ShortcutDef[] = Object.values(SHORTCUTS).flatMap((group) => Object.values(group) as ShortcutDef[]);
+
+/** Where a shortcut sits in the listing, for ordering registrations that arrive in whatever order components mount. */
+export function shortcutRank(shortcut: ShortcutDef): number {
+    const index = ALL_SHORTCUTS.findIndex((candidate) => candidate.id === shortcut.id);
+    return index === -1 ? ALL_SHORTCUTS.length : index;
+}

package/apps/shared/keyboard/match.ts

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ParsedSpec, isSymbolKey, resolveModifiers } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+
+/** The part of a `KeyboardEvent` matching reads. */
+export interface KeyEventLike {
+    key: string;
+    code?: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+
+/** Whether `key` is what a Latin layout produces for a printable key: then `event.key` says which key it is, whatever `event.code` is. */
+function isAsciiKey(key: string): boolean {
+    return /^[\x21-\x7e]$/.test(key);
+}
+
+/**
+ * Whether a key event is the shortcut `parsed`, on `env`.
+ *
+ * The key is matched on `event.key` (case-insensitively), so a shortcut means the letter on the key cap on any layout that has it -
+ * Dvorak, AZERTY - and falls back to `event.code` only when `event.key` is not a Latin character at all: macOS Option+N produces a
+ * dead key or `~`-like symbol, and a Cyrillic or Greek layout produces `ф`/`α` for the key that is A on a QWERTY board. Modifiers must
+ * match exactly (Ctrl+Shift+R is not Ctrl+R), except Shift for a printable symbol, which some layouts need to type it (`?`).
+ */
+export function matchesEvent(parsed: ParsedSpec, event: KeyEventLike, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    if (event.ctrlKey !== modifiers.ctrl || event.altKey !== modifiers.alt || event.metaKey !== modifiers.meta) {
+        return false;
+    }
+    if (event.shiftKey !== modifiers.shift && !(isSymbolKey(parsed.key) && !parsed.shift)) {
+        return false;
+    }
+    const key = (event.key ?? "").toLowerCase();
+    if (key === parsed.key) {
+        return true;
+    }
+    return !!parsed.code && event.code === parsed.code && !isAsciiKey(key);
+}

package/apps/shared/keyboard/parse.ts

@@ -0,0 +1,136 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { KeyEnvironment } from "./platform.js";
+
+/** A shortcut such as `ctrl+shift+a`, `alt+n`, `Delete` or `?`, broken into what a key event is compared with. */
+export interface ParsedSpec {
+    /** The spec as written. */
+    spec: string;
+    /** The key, lower-case: a letter or digit, a symbol (`?`, `/`, `.`, `,`), or a named key (`enter`, `delete`, `arrowup`, ...). */
+    key: string;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+    /** Ctrl on Windows and Linux, Cmd on macOS - resolved against the environment by `resolveModifiers()`. */
+    mod: boolean;
+    /** The `KeyboardEvent.code` of the key on a QWERTY keyboard, for layouts where `event.key` is not the letter (see `match.ts`). */
+    code?: string;
+}
+
+const MODIFIERS: Record<string, "ctrl" | "shift" | "alt" | "meta" | "mod"> = {
+    ctrl: "ctrl",
+    control: "ctrl",
+    shift: "shift",
+    alt: "alt",
+    option: "alt",
+    opt: "alt",
+    meta: "meta",
+    cmd: "meta",
+    command: "meta",
+    mod: "mod",
+};
+
+/** Spec spellings of keys whose `event.key` is something else. */
+const KEY_ALIASES: Record<string, string> = {
+    esc: "escape",
+    del: "delete",
+    ins: "insert",
+    return: "enter",
+    up: "arrowup",
+    down: "arrowdown",
+    left: "arrowleft",
+    right: "arrowright",
+    space: " ",
+    spacebar: " ",
+    plus: "+",
+    pgup: "pageup",
+    pgdn: "pagedown",
+};
+
+/** The named keys a spec may use besides a single character and `F1`-`F12`. */
+const NAMED_KEYS = new Set([
+    "escape",
+    "enter",
+    "tab",
+    "backspace",
+    "delete",
+    "insert",
+    "home",
+    "end",
+    "pageup",
+    "pagedown",
+    "arrowup",
+    "arrowdown",
+    "arrowleft",
+    "arrowright",
+]);
+
+const SYMBOL_CODES: Record<string, string> = { "/": "Slash", ".": "Period", ",": "Comma" };
+
+/** The `code` a key has on a QWERTY keyboard, for the keys where one is worth falling back to. */
+function codeFor(key: string): string | undefined {
+    if (/^[a-z]$/.test(key)) {
+        return `Key${key.toUpperCase()}`;
+    }
+    if (/^[0-9]$/.test(key)) {
+        return `Digit${key}`;
+    }
+    return SYMBOL_CODES[key];
+}
+
+/**
+ * Parses a shortcut spec: modifiers and one key joined by `+`, in any order and any case - `ctrl+shift+a`, `Alt+N`, `mod+enter`,
+ * `Delete`, `?`, `ctrl+/`, `ctrl++`. `mod` is Ctrl on Windows/Linux and Cmd on macOS. Throws on a spec that cannot be understood, so a
+ * typo in a key map fails at once rather than silently never matching.
+ */
+export function parseSpec(spec: string): ParsedSpec {
+    // A trailing `+` is the plus key itself (`ctrl++`), which a plain split would lose.
+    const plusKey = spec.length > 1 && spec.endsWith("++");
+    const tokens = (plusKey ? spec.slice(0, -2) : spec).split("+").map((token) => token.trim());
+    if (plusKey) {
+        tokens.push("+");
+    }
+    const parsed: ParsedSpec = { spec, key: "", ctrl: false, shift: false, alt: false, meta: false, mod: false };
+    for (const token of tokens) {
+        if (token === "") {
+            throw new Error(`Invalid shortcut "${spec}": empty part.`);
+        }
+        const lower = token.toLowerCase();
+        const modifier = MODIFIERS[lower];
+        if (modifier) {
+            parsed[modifier] = true;
+            continue;
+        }
+        if (parsed.key !== "") {
+            throw new Error(`Invalid shortcut "${spec}": more than one key.`);
+        }
+        const key = KEY_ALIASES[lower] ?? lower;
+        if ([...key].length > 1 && !NAMED_KEYS.has(key) && !/^f([1-9]|1[0-2])$/.test(key)) {
+            throw new Error(`Invalid shortcut "${spec}": unknown key "${token}".`);
+        }
+        parsed.key = key;
+        parsed.code = codeFor(key);
+    }
+    if (parsed.key === "") {
+        throw new Error(`Invalid shortcut "${spec}": no key.`);
+    }
+    return parsed;
+}
+
+/** The modifiers a spec needs on a given platform, with `mod` turned into Cmd (macOS) or Ctrl. */
+export function resolveModifiers(parsed: ParsedSpec, env: KeyEnvironment): { ctrl: boolean; shift: boolean; alt: boolean; meta: boolean } {
+    return {
+        ctrl: parsed.ctrl || (parsed.mod && !env.mac),
+        shift: parsed.shift,
+        alt: parsed.alt,
+        meta: parsed.meta || (parsed.mod && env.mac),
+    };
+}
+
+/** Whether the key is a printable symbol whose shifted-ness depends on the layout (`?` is Shift+/ on a US keyboard, not on others). */
+export function isSymbolKey(key: string): boolean {
+    return [...key].length === 1 && !/[a-z0-9]/.test(key);
+}

package/apps/shared/keyboard/platform.ts

@@ -0,0 +1,34 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** What the keyboard layer needs to know about where it runs. */
+export interface KeyEnvironment {
+    /** macOS (and iOS/iPadOS): `mod` is Cmd there, and Option is a text-entry modifier. */
+    mac: boolean;
+    /** The desktop client (`electron-client`), which exposes `window.rapidmx` from its preload script. */
+    electron: boolean;
+}
+
+/** What the server render and the first client render use, so the two agree; the real environment is read after mount. */
+export const SERVER_ENVIRONMENT: KeyEnvironment = { mac: false, electron: false };
+
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export function isMacPlatform(): boolean {
+    if (typeof navigator === "undefined") {
+        return false;
+    }
+    const uaData = (navigator as { userAgentData?: { platform?: string } }).userAgentData;
+    return /mac|iphone|ipad|ipod/i.test(uaData?.platform || navigator.platform || "");
+}
+
+/** Whether the page is running inside the desktop client, which is what `window.rapidmx` (its preload's `contextBridge`) tells. */
+export function isElectronClient(): boolean {
+    return typeof window !== "undefined" && (window as { rapidmx?: unknown }).rapidmx !== undefined;
+}
+
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export function currentEnvironment(): KeyEnvironment {
+    return { mac: isMacPlatform(), electron: isElectronClient() };
+}

package/apps/shared/keyboard/registry.ts

@@ -0,0 +1,65 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { RefObject } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import { ParsedSpec } from "./parse.js";
+
+/**
+ * What a handler does with its key. Returning `false` says it did not handle it (nothing selected, a button that is disabled right now)
+ * - the key is then left alone, and a handler of a lower scope may take it. Anything else means it did, and the key is consumed.
+ */
+export type ShortcutHandler = (event: KeyboardEvent) => boolean | void;
+
+/** One mounted view's claim on a shortcut. */
+export interface Registration {
+    /** Unique per registration. */
+    id: number;
+    shortcut: ShortcutDef;
+    scope: ShortcutScope;
+    /** Called at event time; reads whatever the component holds now. */
+    run: ShortcutHandler;
+    /** Applies only to events whose target is inside this element (a compose window). */
+    container?: RefObject<Element | null>;
+    keys: ParsedSpec[];
+    electronKeys: ParsedSpec[];
+    /** Later registrations win over earlier ones in the same scope. */
+    order: number;
+}
+
+/**
+ * The shortcuts that are mounted right now. Components add and remove their claims as they mount and unmount, so a page switch changes
+ * what a key does with nothing to re-wire; the dispatcher (`dispatchKeyEvent()`) looks handlers up here at the time of the key press,
+ * and the help dialog lists what is here.
+ */
+export class ShortcutRegistry {
+    private registrations: readonly Registration[] = [];
+    private counter = 0;
+    private listeners = new Set<() => void>();
+
+    /** Adds a claim; returns what removes it. */
+    add(claim: Omit<Registration, "id" | "order">): () => void {
+        const registration: Registration = { ...claim, id: ++this.counter, order: this.counter };
+        this.registrations = [...this.registrations, registration];
+        this.publish();
+        return () => {
+            this.registrations = this.registrations.filter((existing) => existing.id !== registration.id);
+            this.publish();
+        };
+    }
+
+    /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+    getSnapshot = (): readonly Registration[] => this.registrations;
+
+    subscribe = (listener: () => void): (() => void) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+
+    private publish(): void {
+        this.listeners.forEach((listener) => listener());
+    }
+}

package/apps/shared/keyboard/targets.ts

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** `<input>` types that take no typed text, so a letter pressed on one is a shortcut, not input. (Radios and ranges use the arrows.) */
+const NON_TEXT_INPUT_TYPES = new Set(["button", "checkbox", "submit", "reset", "image", "file", "color"]);
+
+/** Roles whose members have keys of their own (arrows, Enter, Escape, type-ahead): a bare key pressed inside one belongs to the widget. */
+const WIDGET_SELECTOR = [
+    "menu",
+    "menubar",
+    "listbox",
+    "tablist",
+    "tree",
+    "grid",
+    "radiogroup",
+    "slider",
+    "spinbutton",
+    "combobox",
+]
+    .map((role) => `[role="${role}"]`)
+    .join(",");
+
+/** Elements Enter (and Space) already does something on. */
+const ACTIVATABLE_SELECTOR = 'a[href], button, summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"]';
+
+/** An open popup's trigger: Escape closes the popup, so it is not a shortcut then. */
+const OPEN_POPUP_TRIGGER = '[aria-haspopup][aria-expanded="true"], [role="combobox"][aria-expanded="true"]';
+
+function elementOf(target: EventTarget | null): Element | null {
+    return target instanceof Element ? target : null;
+}
+
+/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
+export function isTextEntry(target: EventTarget | null): boolean {
+    const element = elementOf(target);
+    if (!element) {
+        return false;
+    }
+    const tag = element.tagName;
+    if (tag === "TEXTAREA" || tag === "SELECT") {
+        return true;
+    }
+    if (tag === "INPUT") {
+        return !NON_TEXT_INPUT_TYPES.has((element as HTMLInputElement).type);
+    }
+    return !!element.closest('[contenteditable]:not([contenteditable="false"]), [role="textbox"], [role="searchbox"]');
+}
+
+/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
+export function isInWidget(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(WIDGET_SELECTOR);
+}
+
+/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
+export function isActivatable(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(ACTIVATABLE_SELECTOR);
+}
+
+/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
+export function isPopupOpenAt(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(OPEN_POPUP_TRIGGER);
+}
+
+/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
+export function isModalOpen(doc: Document): boolean {
+    return doc.querySelector('[aria-modal="true"]') !== null;
+}
+
+/** Whether the target is inside a popover that is a dialog of its own (the emoji and GIF pickers, the send-later picker): Escape is theirs, not a view's. A region that declares a shortcut scope (a compose window) is not one. */
+export function isInPopoverDialog(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest('[role="dialog"]:not([data-shortcut-scope])');
+}
+
+/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
+export function regionScopeOf(target: EventTarget | null): string | undefined {
+    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
+}

package/apps/shared/keyboard/useShortcut.ts

@@ -0,0 +1,50 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { RefObject, useEffect, useMemo, useRef } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import { parseSpec } from "./parse.js";
+import type { ShortcutHandler } from "./registry.js";
+import { useShortcutRegistry } from "./ShortcutProvider.js";
+
+export interface UseShortcutOptions {
+    /** Overrides the scope the shortcut is defined with - required for a bare spec string, which has none. Default `global`. */
+    scope?: ShortcutScope;
+    /** Registers only while true: a view offers a shortcut only when it can really do the thing. Default true. */
+    enabled?: boolean;
+    /** Restricts it to events whose target is inside this element (a compose window). */
+    container?: RefObject<Element | null>;
+}
+
+/**
+ * Claims a shortcut for as long as the calling component is mounted (and `enabled`). `shortcut` is an entry of `SHORTCUTS` - which is what
+ * the help dialog and tooltips describe - or a bare spec such as `"alt+n"` for a one-off. The handler is read at the time of the key press,
+ * so it always sees the component's current state without the registration being redone; return `false` from it to decline the key.
+ *
+ * Does nothing outside a `ShortcutProvider`.
+ */
+export function useShortcut(shortcut: ShortcutDef | string, handler: ShortcutHandler, options: UseShortcutOptions = {}): void {
+    const { scope, enabled = true, container } = options;
+    const registry = useShortcutRegistry();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const def = useMemo<ShortcutDef>(
+        () => (typeof shortcut === "string" ? { id: `custom:${shortcut}`, keys: [shortcut], label: shortcut, scope: "global" } : shortcut),
+        [shortcut],
+    );
+    const resolvedScope = scope ?? def.scope;
+    useEffect(() => {
+        if (!registry || !enabled) {
+            return;
+        }
+        return registry.add({
+            shortcut: def,
+            scope: resolvedScope,
+            run: (event) => handlerRef.current(event),
+            container,
+            keys: def.keys.map(parseSpec),
+            electronKeys: (def.electronKeys ?? []).map(parseSpec),
+        });
+    }, [registry, enabled, def, resolvedScope, container]);
+}

package/apps/shared/keyboard/useShortcutProps.ts

@@ -0,0 +1,17 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ariaKeyShortcuts, withHint } from "./format.js";
+import type { ShortcutDef } from "./keymap.js";
+import { useKeyEnvironment } from "./ShortcutProvider.js";
+
+/**
+ * What a control that a keyboard shortcut also triggers gets: a tooltip naming the key - `Reply (Ctrl+R)`, in this platform's own key names -
+ * and `aria-keyshortcuts` for assistive technology. The accessible name is left alone (the control keeps its own label), so a tooltip suffix never
+ * changes what a screen reader or a test finds it by. With `active` false - the shortcut isn't registered right now - it is just the plain label.
+ */
+export function useShortcutProps(label: string, shortcut: ShortcutDef, active = true): { title: string; "aria-keyshortcuts"?: string } {
+    const env = useKeyEnvironment();
+    return active ? { title: withHint(label, shortcut, env), "aria-keyshortcuts": ariaKeyShortcuts(shortcut, env) } : { title: label };
+}