@rapidmx/web-client 0.9.0 → 0.10.0

package/dist/apps/shared/keyboard/keymap.js

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The scopes the help dialog lists, in the order it lists them. */
+export const HELP_SCOPES = ["global", "mail", "compose", "calendar", "contacts", "tasks"];
+export const SCOPE_LABELS = {
+    global: "Global",
+    mail: "Mail",
+    compose: "Compose",
+    calendar: "Calendar",
+    contacts: "Contacts",
+    tasks: "Tasks",
+    dialog: "Dialog",
+};
+function def(shortcut) {
+    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" }),
+    },
+};
+/** Every shortcut of the map flattened, in listing order. */
+export const ALL_SHORTCUTS = Object.values(SHORTCUTS).flatMap((group) => Object.values(group));
+/** Where a shortcut sits in the listing, for ordering registrations that arrive in whatever order components mount. */
+export function shortcutRank(shortcut) {
+    const index = ALL_SHORTCUTS.findIndex((candidate) => candidate.id === shortcut.id);
+    return index === -1 ? ALL_SHORTCUTS.length : index;
+}

package/dist/apps/shared/keyboard/match.d.ts

@@ -0,0 +1,20 @@
+import { ParsedSpec } 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 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 declare function matchesEvent(parsed: ParsedSpec, event: KeyEventLike, env: KeyEnvironment): boolean;

package/dist/apps/shared/keyboard/match.js

@@ -0,0 +1,31 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { isSymbolKey, resolveModifiers } from "./parse.js";
+/** 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) {
+    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, event, env) {
+    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/dist/apps/shared/keyboard/parse.d.ts

@@ -0,0 +1,31 @@
+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;
+}
+/**
+ * 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 declare function parseSpec(spec: string): ParsedSpec;
+/** The modifiers a spec needs on a given platform, with `mod` turned into Cmd (macOS) or Ctrl. */
+export declare function resolveModifiers(parsed: ParsedSpec, env: KeyEnvironment): {
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+};
+/** Whether the key is a printable symbol whose shifted-ness depends on the layout (`?` is Shift+/ on a US keyboard, not on others). */
+export declare function isSymbolKey(key: string): boolean;

package/dist/apps/shared/keyboard/parse.js

@@ -0,0 +1,107 @@
+const MODIFIERS = {
+    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 = {
+    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 = { "/": "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) {
+    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) {
+    // 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 = { 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, env) {
+    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) {
+    return [...key].length === 1 && !/[a-z0-9]/.test(key);
+}

package/dist/apps/shared/keyboard/platform.d.ts

@@ -0,0 +1,15 @@
+/** 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 declare const SERVER_ENVIRONMENT: KeyEnvironment;
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export declare function isMacPlatform(): boolean;
+/** Whether the page is running inside the desktop client, which is what `window.rapidmx` (its preload's `contextBridge`) tells. */
+export declare function isElectronClient(): boolean;
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export declare function currentEnvironment(): KeyEnvironment;

package/dist/apps/shared/keyboard/platform.js

@@ -0,0 +1,22 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** 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 = { mac: false, electron: false };
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export function isMacPlatform() {
+    if (typeof navigator === "undefined") {
+        return false;
+    }
+    const uaData = navigator.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() {
+    return typeof window !== "undefined" && window.rapidmx !== undefined;
+}
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export function currentEnvironment() {
+    return { mac: isMacPlatform(), electron: isElectronClient() };
+}

package/dist/apps/shared/keyboard/registry.d.ts

@@ -0,0 +1,39 @@
+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 declare class ShortcutRegistry {
+    private registrations;
+    private counter;
+    private listeners;
+    /** Adds a claim; returns what removes it. */
+    add(claim: Omit<Registration, "id" | "order">): () => void;
+    /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+    getSnapshot: () => readonly Registration[];
+    subscribe: (listener: () => void) => (() => void);
+    private publish;
+}

package/dist/apps/shared/keyboard/registry.js

@@ -0,0 +1,33 @@
+/**
+ * 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 {
+    constructor() {
+        this.registrations = [];
+        this.counter = 0;
+        this.listeners = new Set();
+        /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+        this.getSnapshot = () => this.registrations;
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        };
+    }
+    /** Adds a claim; returns what removes it. */
+    add(claim) {
+        const 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();
+        };
+    }
+    publish() {
+        this.listeners.forEach((listener) => listener());
+    }
+}

package/dist/apps/shared/keyboard/targets.d.ts

@@ -0,0 +1,14 @@
+/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
+export declare function isTextEntry(target: EventTarget | null): boolean;
+/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
+export declare function isInWidget(target: EventTarget | null): boolean;
+/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
+export declare function isActivatable(target: EventTarget | null): boolean;
+/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
+export declare function isPopupOpenAt(target: EventTarget | null): boolean;
+/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
+export declare function isModalOpen(doc: Document): boolean;
+/** 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 declare function isInPopoverDialog(target: EventTarget | null): boolean;
+/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
+export declare function regionScopeOf(target: EventTarget | null): string | undefined;

package/dist/apps/shared/keyboard/targets.js

@@ -0,0 +1,67 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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) {
+    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) {
+    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.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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
+}

package/dist/apps/shared/keyboard/useShortcut.d.ts

@@ -0,0 +1,19 @@
+import { RefObject } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import type { ShortcutHandler } from "./registry.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 declare function useShortcut(shortcut: ShortcutDef | string, handler: ShortcutHandler, options?: UseShortcutOptions): void;

package/dist/apps/shared/keyboard/useShortcut.js

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useRef } from "react";
+import { parseSpec } from "./parse.js";
+import { useShortcutRegistry } from "./ShortcutProvider.js";
+/**
+ * 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, handler, options = {}) {
+    const { scope, enabled = true, container } = options;
+    const registry = useShortcutRegistry();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const def = useMemo(() => (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/dist/apps/shared/keyboard/useShortcutProps.d.ts

@@ -0,0 +1,10 @@
+import type { ShortcutDef } from "./keymap.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 declare function useShortcutProps(label: string, shortcut: ShortcutDef, active?: boolean): {
+    title: string;
+    "aria-keyshortcuts"?: string;
+};

package/dist/apps/shared/keyboard/useShortcutProps.js

@@ -0,0 +1,15 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ariaKeyShortcuts, withHint } from "./format.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, shortcut, active = true) {
+    const env = useKeyEnvironment();
+    return active ? { title: withHint(label, shortcut, env), "aria-keyshortcuts": ariaKeyShortcuts(shortcut, env) } : { title: label };
+}