@rapidmx/web-client 0.8.0 → 0.10.0

package/apps/shared/components/tasks/layout/TasksShell.tsx

@@ -10,6 +10,7 @@ import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shar
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 
 export type TasksShellProps = Omit<AppShellProps, "active">;
@@ -47,6 +48,7 @@ export default function TasksShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    trustedRoles,
     pluginNav,
     children,
 }: PropsWithChildren<TasksShellProps>) {
@@ -58,9 +60,18 @@ export default function TasksShell({
     const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
 
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
 
     useEffect(() => {
         if (!userUid) {
@@ -144,7 +155,7 @@ export default function TasksShell({
                             className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
                             value={mailboxUid}
                             onChange={(e) => {
-                                window.location.href = `/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                navigate(`/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`);
                             }}
                         >
                             {mailboxes.map((mb) => (
@@ -193,6 +204,7 @@ export default function TasksShell({
             impersonating={impersonating}
             impersonationBaseUrl={impersonationBaseUrl}
             trusted={trusted}
+            trustedRoles={trustedRoles}
             pluginNav={pluginNav}
         >
             {inner}

package/apps/shared/keyboard/GlobalShortcuts.tsx

@@ -0,0 +1,51 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { accountUrlOf } from "../auth/accountUrl.js";
+import { APP_HREFS, SETTINGS_HREF, isSettingsPath } from "../navigation/appHrefs.js";
+import { useNavigate } from "../navigation/routerContext.js";
+import { SHORTCUTS } from "./keymap.js";
+import { useShortcut } from "./useShortcut.js";
+
+export interface GlobalShortcutsProps {
+    /** auth-server's base URL - "Go to Account" is offered only when it is set. */
+    authServerUrl?: string;
+    /** Opens the keyboard shortcuts dialog, or closes it if it is open. */
+    onToggleHelp: () => void;
+}
+
+/**
+ * The shortcuts that work in every view: the "Go to ..." navigation set and the keyboard help. Mounted once by `AppChrome`, next to the
+ * `ShortcutProvider`, so it works from Settings and every app alike. Renders nothing.
+ *
+ * In-app places go through the client-side router (`useNavigate()`); Account is another origin, so it is a plain navigation. Asking for the
+ * page you are already on does nothing - but the key is still taken, so the browser doesn't act on it either.
+ */
+export function GlobalShortcuts({ authServerUrl, onToggleHelp }: GlobalShortcutsProps) {
+    const navigate = useNavigate();
+    const accountUrl = accountUrlOf(authServerUrl);
+
+    /** A handler that goes to `href` unless the address bar's path says it is already there. */
+    const goTo = (href: string, isHere: (pathname: string) => boolean) => () => {
+        if (!isHere(window.location.pathname)) {
+            navigate(href);
+        }
+    };
+    const isPath = (path: string) => (pathname: string) => pathname === path;
+
+    useShortcut(SHORTCUTS.global.mail, goTo(APP_HREFS.mail, isPath(APP_HREFS.mail)));
+    useShortcut(SHORTCUTS.global.calendar, goTo(APP_HREFS.calendar, isPath(APP_HREFS.calendar)));
+    useShortcut(SHORTCUTS.global.contacts, goTo(APP_HREFS.contacts, isPath(APP_HREFS.contacts)));
+    useShortcut(SHORTCUTS.global.tasks, goTo(APP_HREFS.tasks, isPath(APP_HREFS.tasks)));
+    useShortcut(SHORTCUTS.global.settings, goTo(SETTINGS_HREF, isSettingsPath));
+    useShortcut(
+        SHORTCUTS.global.account,
+        () => {
+            window.location.href = accountUrl!;
+        },
+        { enabled: !!accountUrl },
+    );
+    useShortcut(SHORTCUTS.global.help, onToggleHelp);
+    return null;
+}

package/apps/shared/keyboard/ShortcutProvider.tsx

@@ -0,0 +1,62 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren, createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { dispatchKeyEvent } from "./dispatch.js";
+import { KeyEnvironment, SERVER_ENVIRONMENT, currentEnvironment } from "./platform.js";
+import { Registration, ShortcutRegistry } from "./registry.js";
+
+interface ShortcutContextValue {
+    registry: ShortcutRegistry;
+    env: KeyEnvironment;
+}
+
+const ShortcutContext = createContext<ShortcutContextValue | null>(null);
+
+/**
+ * The web client's one keyboard layer. Mounted once, by `AppChrome` (the frame that stays mounted as the router swaps pages), so shortcuts
+ * work in every view - mail, calendar, contacts, tasks, settings - and a page change only changes which handlers are registered.
+ *
+ * One `keydown` listener on `document` (bubbling, so what a widget handles itself and `preventDefault()`s is left alone) hands each key to
+ * `dispatchKeyEvent()`. Views claim keys with `useShortcut()`. Outside a provider - an admin page, a component rendered on its own - that
+ * hook does nothing.
+ *
+ * The platform (macOS, the desktop client) is read after mount, never during render, so the server render and hydration agree.
+ */
+export function ShortcutProvider({ children }: PropsWithChildren) {
+    const registry = useMemo(() => new ShortcutRegistry(), []);
+    const [env, setEnv] = useState<KeyEnvironment>(SERVER_ENVIRONMENT);
+    useEffect(() => {
+        setEnv(currentEnvironment());
+    }, []);
+    useEffect(() => {
+        function handleKeyDown(event: KeyboardEvent) {
+            dispatchKeyEvent(registry, event, currentEnvironment(), document);
+        }
+        document.addEventListener("keydown", handleKeyDown);
+        return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [registry]);
+    const value = useMemo(() => ({ registry, env }), [registry, env]);
+    return <ShortcutContext.Provider value={value}>{children}</ShortcutContext.Provider>;
+}
+
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export function useShortcutRegistry(): ShortcutRegistry | null {
+    return useContext(ShortcutContext)?.registry ?? null;
+}
+
+/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
+export function useKeyEnvironment(): KeyEnvironment {
+    return useContext(ShortcutContext)?.env ?? SERVER_ENVIRONMENT;
+}
+
+const NO_REGISTRATIONS: readonly Registration[] = [];
+const getNoRegistrations = () => NO_REGISTRATIONS;
+const NEVER = () => () => undefined;
+
+/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
+export function useRegisteredShortcuts(): readonly Registration[] {
+    const registry = useShortcutRegistry();
+    return useSyncExternalStore(registry?.subscribe ?? NEVER, registry?.getSnapshot ?? getNoRegistrations, getNoRegistrations);
+}

package/apps/shared/keyboard/ShortcutsDialog.tsx

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import { formatSpec, specsFor } from "./format.js";
+import { HELP_SCOPES, SCOPE_LABELS, SHORTCUTS, ShortcutDef, shortcutRank } from "./keymap.js";
+import { useKeyEnvironment, useRegisteredShortcuts } from "./ShortcutProvider.js";
+import { useShortcut } from "./useShortcut.js";
+
+export interface ShortcutsDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+function Keys({ shortcut }: { shortcut: ShortcutDef }) {
+    const env = useKeyEnvironment();
+    return (
+        <span className="flex flex-wrap justify-end gap-x-1.5 gap-y-1 shrink-0">
+            {specsFor(shortcut, env).map((spec, index) => (
+                <React.Fragment key={spec}>
+                    {index > 0 && <span className="text-xs text-text-muted self-center">or</span>}
+                    <kbd className="px-1.5 py-0.5 rounded-sm border border-border bg-surface-alt text-xs font-sans font-semibold whitespace-nowrap">
+                        {formatSpec(spec, env)}
+                    </kbd>
+                </React.Fragment>
+            ))}
+        </span>
+    );
+}
+
+/**
+ * The keyboard shortcuts help dialog: what can be done from the keyboard *here*. It lists what is registered right now (see
+ * `useRegisteredShortcuts()`), so it shows the global shortcuts and those of the view that is on screen - and the compose window's while one
+ * is open - in groups, with the platform's own key names (Ctrl or Cmd, Alt or Option), and in the desktop client also the keys only it has.
+ * A shortcut a view cannot do at the moment (no message selected) is not registered, and so not listed.
+ *
+ * Built on `Modal`: focus moves into the dialog and stays there, Escape closes it, and it has an accessible name. `?` and Ctrl+/ close it too.
+ */
+export default function ShortcutsDialog({ open, onClose }: ShortcutsDialogProps) {
+    // Mounted only while open: the body subscribes to the registry, which every view's shortcuts change as it mounts - not something the
+    // whole app should re-render for while the dialog is closed.
+    return open ? <ShortcutsDialogBody onClose={onClose} /> : null;
+}
+
+function ShortcutsDialogBody({ onClose }: { onClose: () => void }) {
+    const registrations = useRegisteredShortcuts();
+    useShortcut(SHORTCUTS.global.help, onClose, { scope: "dialog" });
+    const groups = HELP_SCOPES.map((scope) => {
+        const listed = new Map<string, ShortcutDef>();
+        for (const registration of registrations) {
+            if (registration.scope === scope) {
+                listed.set(registration.shortcut.id, registration.shortcut);
+            }
+        }
+        return { scope, shortcuts: [...listed.values()].sort((a, b) => shortcutRank(a) - shortcutRank(b)) };
+    }).filter((group) => group.shortcuts.length > 0);
+
+    return (
+        <Modal open onClose={onClose} title="Keyboard shortcuts">
+            <div className="flex flex-col gap-5">
+                {groups.map(({ scope, shortcuts }) => (
+                    <section key={scope} aria-labelledby={`shortcuts-${scope}`}>
+                        <h3 id={`shortcuts-${scope}`} className="text-xs font-bold uppercase tracking-wide text-text-muted mb-2">
+                            {SCOPE_LABELS[scope]}
+                        </h3>
+                        <ul className="flex flex-col gap-1.5">
+                            {shortcuts.map((shortcut) => (
+                                <li key={shortcut.id} className="flex items-start justify-between gap-4 text-sm">
+                                    <span>{shortcut.label}</span>
+                                    <Keys shortcut={shortcut} />
+                                </li>
+                            ))}
+                        </ul>
+                    </section>
+                ))}
+                <p className="text-xs text-text-muted border-t border-border pt-3">
+                    Some browsers keep a few keys for themselves, so a shortcut may not work everywhere.
+                </p>
+            </div>
+        </Modal>
+    );
+}

package/apps/shared/keyboard/dispatch.ts

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

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);
+}