@rapidmx/web-client 0.9.0 → 0.11.0

package/dist/apps/shared/components/sharing/PrincipalPicker.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+import { MailboxAccessRole, ResolvedPrincipal } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+export interface PrincipalPickerProps {
+    mailboxUid: string;
+    /** What each access level is called on this page. */
+    roleLabels: Record<MailboxAccessRole, string>;
+    /** Text put in the box to start with - a stored entry being replaced, say. */
+    initialPrincipal?: string;
+    /** The access level pre-selected. */
+    defaultRole?: MailboxAccessRole;
+    /** What the box asks for. */
+    placeholder?: string;
+    /** Called once the grant is saved, with the person it went to. */
+    onGranted: (person: ResolvedPrincipal, role: MailboxAccessRole) => void | Promise<void>;
+    /** Shown as a Cancel button next to the box when set (replacing an entry). */
+    onCancel?: () => void;
+}
+/** Who a resolved person is, for a person to check before saving: their name and address, else their uid. */
+export declare function describePerson(person: ResolvedPrincipal): string;
+/**
+ * "Who?" for a sharing screen. What is typed - a mailbox address, an auth-server username or e-mail alias, or a user id -
+ * is RESOLVED by the server (`resolveMailboxPrincipal()`) to the person it names before anything is saved, and the person
+ * is shown (name and address) for the caller to confirm; only then is the grant made, against that person's uid. Free text
+ * is never stored: an ACL record matches a user uid and nothing else, so a grant to a typed username applies to nobody.
+ */
+export default function PrincipalPicker({ mailboxUid, roleLabels, initialPrincipal, defaultRole, placeholder, onGranted, onCancel }: PrincipalPickerProps): React.JSX.Element;

package/dist/apps/shared/components/sharing/PrincipalPicker.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { resolveMailboxPrincipal, setMailboxAccess, } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+/** Who a resolved person is, for a person to check before saving: their name and address, else their uid. */
+export function describePerson(person) {
+    if (person.displayName && person.address)
+        return `${person.displayName} <${person.address}>`;
+    return person.displayName ?? person.address ?? `user ${person.userUid}`;
+}
+/**
+ * "Who?" for a sharing screen. What is typed - a mailbox address, an auth-server username or e-mail alias, or a user id -
+ * is RESOLVED by the server (`resolveMailboxPrincipal()`) to the person it names before anything is saved, and the person
+ * is shown (name and address) for the caller to confirm; only then is the grant made, against that person's uid. Free text
+ * is never stored: an ACL record matches a user uid and nothing else, so a grant to a typed username applies to nobody.
+ */
+export default function PrincipalPicker({ mailboxUid, roleLabels, initialPrincipal, defaultRole = "viewer", placeholder, onGranted, onCancel }) {
+    const [typed, setTyped] = useState(initialPrincipal ?? "");
+    const [role, setRole] = useState(defaultRole);
+    const [person, setPerson] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    // A stored entry being replaced is looked up straight away, so its person is shown without a click.
+    useEffect(() => {
+        if (initialPrincipal) {
+            void find(initialPrincipal);
+        }
+    }, [initialPrincipal]);
+    async function find(principal) {
+        setBusy(true);
+        setError(null);
+        setPerson(null);
+        try {
+            setPerson(await resolveMailboxPrincipal(mailboxUid, principal));
+        }
+        catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not look that person up.");
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    function handleFind(e) {
+        e.preventDefault();
+        const principal = typed.trim();
+        if (principal) {
+            void find(principal);
+        }
+    }
+    // Only reachable from the confirm button, which only renders once `person` is set.
+    async function handleGrant() {
+        setBusy(true);
+        setError(null);
+        try {
+            await setMailboxAccess(mailboxUid, person.userUid, role);
+            await onGranted(person, role);
+            setTyped("");
+            setPerson(null);
+        }
+        catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not grant access.");
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleFind, className: "flex gap-2", children: [_jsx("input", { type: "text", "aria-label": "Who to share with", placeholder: placeholder ?? "Email address, username or user id", className: "flex-1 text-sm border border-border rounded-sm py-1.5 px-2 bg-surface text-text", value: typed, onChange: (e) => {
+                            setTyped(e.target.value);
+                            setPerson(null);
+                        }, disabled: busy }), _jsx("select", { "aria-label": "Access level", className: "text-sm border border-border rounded-sm py-1.5 px-2 bg-surface text-text", value: role, onChange: (e) => setRole(e.target.value), disabled: busy, children: Object.keys(roleLabels).map((value) => (_jsx("option", { value: value, children: roleLabels[value] }, value))) }), _jsx(Button, { type: "submit", variant: "secondary", loading: busy && !person, disabled: busy, className: "!w-auto", children: "Find" }), onCancel && (_jsx(Button, { type: "button", variant: "text", className: "!w-auto", onClick: onCancel, children: "Cancel" }))] }), person && (_jsxs("div", { className: "flex items-center justify-between gap-3 text-sm py-2 px-3 border border-border rounded-sm", children: [_jsxs("span", { children: ["Share with ", _jsx("strong", { className: "break-all", children: describePerson(person) }), " as ", _jsx("em", { children: roleLabels[role] }), "?"] }), _jsx(Button, { type: "button", loading: busy, disabled: busy, className: "!w-auto", onClick: () => void handleGrant(), children: "Grant" })] }))] }));
+}

package/dist/apps/shared/components/tasks/TasksSidebar.js

@@ -8,6 +8,7 @@ import { HiOutlineBars3 } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { createTaskList, listTaskLists } from "@rapidmx/react-shared/tasks/tasksApi.js";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
 export function tasksViewKey(view) {
     return view.type === "list" ? `list:${view.uid}` : view.type;
 }
@@ -66,7 +67,8 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
             setAddingList(false);
         }
         catch (err) {
-            setListsError(err instanceof ApiRequestError ? err.message : "Could not create this list.");
+            // A pop-up: `listsError` is only the lists' own load failure.
+            notifyApiError(err, "Couldn't create the list");
         }
     }
     function handleSelect(view) {
@@ -77,5 +79,5 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
     // `Drawer` (see `ContactsSidebar` for the identical pattern and the duplicate-id reasoning behind
     // the `idPrefix`).
     const navContent = (idPrefix) => (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx(NavItem, { label: "My Day", count: myDayCount, active: active.type === "myDay", onClick: () => handleSelect({ type: "myDay" }) }), _jsx(NavItem, { label: "Important", count: importantCount, active: active.type === "important", onClick: () => handleSelect({ type: "important" }) }), _jsx(NavItem, { label: "Planned", count: plannedCount, active: active.type === "planned", onClick: () => handleSelect({ type: "planned" }) }), _jsx(NavItem, { label: "Assigned to me", count: assignedToMeCount, active: active.type === "assignedToMe", onClick: () => handleSelect({ type: "assignedToMe" }) }), _jsx(NavItem, { label: "Flagged email", active: active.type === "flagged", onClick: () => handleSelect({ type: "flagged" }) })] }), _jsx(NavItem, { label: "Tasks", count: tasks.length, active: active.type === "all", onClick: () => handleSelect({ type: "all" }) }), _jsxs("div", { children: [_jsxs("div", { className: "flex items-center justify-between px-2.5 mb-1", children: [_jsx("h2", { className: "text-xs font-bold uppercase tracking-wide text-text-muted", children: "Lists" }), _jsx("button", { type: "button", onClick: () => setAddingList(true), "aria-label": "New list", className: "text-xs font-bold text-primary-dark hover:underline", children: "+" })] }), listsError && _jsx("p", { className: "px-2.5 text-xs text-danger", children: listsError }), _jsx("div", { className: "flex flex-col gap-0.5", children: lists.map((list) => (_jsx(NavItem, { label: list.name, count: listCounts.get(list.uid) ?? 0, active: active.type === "list" && active.uid === list.uid, onClick: () => handleSelect({ type: "list", uid: list.uid, name: list.name }) }, list.uid))) }), addingList && (_jsxs("form", { onSubmit: handleAddList, className: "flex items-center gap-1 px-2.5 mt-1", children: [_jsx("input", { type: "text", autoFocus: true, "aria-label": "New list name", id: `${idPrefix}-new-list-name`, value: newListName, onChange: (e) => setNewListName(e.target.value), className: "flex-1 text-xs py-1 px-1.5 border border-border rounded-sm bg-surface" }), _jsx("button", { type: "submit", className: "text-xs font-semibold text-primary-dark", children: "Add" })] }))] })] }));
-    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open tasks menu", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("nav", { "aria-label": "Tasks", className: "hidden md:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto", children: navContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Tasks", children: _jsx("div", { className: "flex flex-col gap-4", children: navContent("mobile") }) })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "lg:hidden m-3 mb-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open tasks menu", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("nav", { "aria-label": "Tasks", className: "hidden lg:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto", children: navContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Tasks", children: _jsx("div", { className: "flex flex-col gap-4", children: navContent("mobile") }) })] }));
 }

package/dist/apps/shared/components/tasks/layout/TasksShell.d.ts

@@ -21,4 +21,4 @@ export declare function useTasksShell(): TasksShellContextValue;
  * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
  * grow its own app-specific controls later without threading extra props through a shared one.
  */
-export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<TasksShellProps>): React.JSX.Element;
+export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }: PropsWithChildren<TasksShellProps>): React.JSX.Element;

package/dist/apps/shared/components/tasks/layout/TasksShell.js

@@ -11,6 +11,7 @@ import { listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.j
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 const TasksShellContext = createContext({ mailboxes: [] });
 /** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
@@ -24,7 +25,7 @@ export function useTasksShell() {
  * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
  * grow its own app-specific controls later without threading extra props through a shared one.
  */
-export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
@@ -32,9 +33,18 @@ export default function TasksShell({ userUid, authServerUrl, impersonating, impe
     const [folderError, setFolderError] = useState(null);
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(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) {
             return;
@@ -84,9 +94,11 @@ export default function TasksShell({ userUid, authServerUrl, impersonating, impe
         // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
         // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
         const sidebarContent = (idPrefix) => (_jsxs(_Fragment, { children: [mailboxes.length > 1 && (_jsxs("div", { children: [_jsx("label", { className: "block text-xs font-bold uppercase tracking-wide text-text-muted mb-1", htmlFor: `${idPrefix}-tasks-mailbox-switcher`, children: "Mailbox" }), _jsx("select", { id: `${idPrefix}-tasks-mailbox-switcher`, 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)}`);
                             }, children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) })] })), folderError && _jsx(Alert, { children: folderError })] }));
-        inner = (_jsxs(_Fragment, { children: [_jsx("aside", { className: "hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Mailbox", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [(mailboxes.length > 1 || folderError) && (_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open mailbox switcher", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) })), _jsx(TasksShellContext.Provider, { value: contextValue, children: children })] })] }));
+        // With a single mailbox and no error this column would be empty: no 224 px of nothing beside the tasks' own menu.
+        const hasSidebar = mailboxes.length > 1 || !!folderError;
+        inner = (_jsxs(_Fragment, { children: [hasSidebar && (_jsx("aside", { className: "hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") })), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Mailbox", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [hasSidebar && (_jsx("button", { type: "button", className: "lg:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open mailbox switcher", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) })), _jsx(TasksShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
-    return (_jsx(AppShell, { active: "tasks", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner }));
+    return (_jsx(AppShell, { active: "tasks", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner }));
 }

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

@@ -0,0 +1,14 @@
+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 declare function GlobalShortcuts({ authServerUrl, onToggleHelp }: GlobalShortcutsProps): null;

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

@@ -0,0 +1,37 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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";
+/**
+ * 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 }) {
+    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, isHere) => () => {
+        if (!isHere(window.location.pathname)) {
+            navigate(href);
+        }
+    };
+    const isPath = (path) => (pathname) => 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/dist/apps/shared/keyboard/ShortcutProvider.d.ts

@@ -0,0 +1,20 @@
+import React, { PropsWithChildren } from "react";
+import { KeyEnvironment } from "./platform.js";
+import { Registration, ShortcutRegistry } from "./registry.js";
+/**
+ * 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 declare function ShortcutProvider({ children }: PropsWithChildren): React.JSX.Element;
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export declare function useShortcutRegistry(): ShortcutRegistry | null;
+/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
+export declare function useKeyEnvironment(): KeyEnvironment;
+/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
+export declare function useRegisteredShortcuts(): readonly Registration[];

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

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { dispatchKeyEvent } from "./dispatch.js";
+import { SERVER_ENVIRONMENT, currentEnvironment } from "./platform.js";
+import { ShortcutRegistry } from "./registry.js";
+const ShortcutContext = createContext(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 }) {
+    const registry = useMemo(() => new ShortcutRegistry(), []);
+    const [env, setEnv] = useState(SERVER_ENVIRONMENT);
+    useEffect(() => {
+        setEnv(currentEnvironment());
+    }, []);
+    useEffect(() => {
+        function handleKeyDown(event) {
+            dispatchKeyEvent(registry, event, currentEnvironment(), document);
+        }
+        document.addEventListener("keydown", handleKeyDown);
+        return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [registry]);
+    const value = useMemo(() => ({ registry, env }), [registry, env]);
+    return _jsx(ShortcutContext.Provider, { value: value, children: children });
+}
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export function useShortcutRegistry() {
+    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() {
+    return useContext(ShortcutContext)?.env ?? SERVER_ENVIRONMENT;
+}
+const NO_REGISTRATIONS = [];
+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() {
+    const registry = useShortcutRegistry();
+    return useSyncExternalStore(registry?.subscribe ?? NEVER, registry?.getSnapshot ?? getNoRegistrations, getNoRegistrations);
+}

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

@@ -0,0 +1,14 @@
+import React from "react";
+export interface ShortcutsDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+/**
+ * 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): React.JSX.Element | null;

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

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// 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, shortcutRank } from "./keymap.js";
+import { useKeyEnvironment, useRegisteredShortcuts } from "./ShortcutProvider.js";
+import { useShortcut } from "./useShortcut.js";
+function Keys({ shortcut }) {
+    const env = useKeyEnvironment();
+    return (_jsx("span", { className: "flex flex-wrap justify-end gap-x-1.5 gap-y-1 shrink-0", children: specsFor(shortcut, env).map((spec, index) => (_jsxs(React.Fragment, { children: [index > 0 && _jsx("span", { className: "text-xs text-text-muted self-center", children: "or" }), _jsx("kbd", { className: "px-1.5 py-0.5 rounded-sm border border-border bg-surface-alt text-xs font-sans font-semibold whitespace-nowrap", children: formatSpec(spec, env) })] }, spec))) }));
+}
+/**
+ * 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 }) {
+    // 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 ? _jsx(ShortcutsDialogBody, { onClose: onClose }) : null;
+}
+function ShortcutsDialogBody({ onClose }) {
+    const registrations = useRegisteredShortcuts();
+    useShortcut(SHORTCUTS.global.help, onClose, { scope: "dialog" });
+    const groups = HELP_SCOPES.map((scope) => {
+        const listed = new Map();
+        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 (_jsx(Modal, { open: true, onClose: onClose, title: "Keyboard shortcuts", children: _jsxs("div", { className: "flex flex-col gap-5", children: [groups.map(({ scope, shortcuts }) => (_jsxs("section", { "aria-labelledby": `shortcuts-${scope}`, children: [_jsx("h3", { id: `shortcuts-${scope}`, className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-2", children: SCOPE_LABELS[scope] }), _jsx("ul", { className: "flex flex-col gap-1.5", children: shortcuts.map((shortcut) => (_jsxs("li", { className: "flex items-start justify-between gap-4 text-sm", children: [_jsx("span", { children: shortcut.label }), _jsx(Keys, { shortcut: shortcut })] }, shortcut.id))) })] }, scope))), _jsx("p", { className: "text-xs text-text-muted border-t border-border pt-3", children: "Some browsers keep a few keys for themselves, so a shortcut may not work everywhere." })] }) }));
+}

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

@@ -0,0 +1,16 @@
+import type { KeyEnvironment } from "./platform.js";
+import type { ShortcutRegistry } from "./registry.js";
+/**
+ * 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 declare function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean;

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

@@ -0,0 +1,109 @@
+import { matchesEvent } from "./match.js";
+import { resolveModifiers } from "./parse.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 = ["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, env) {
+    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, env) {
+    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, parsed, target, env) {
+    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, doc) {
+    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, event) {
+    if (!registration.container) {
+        return true;
+    }
+    return !!registration.container.current?.contains(event.target);
+}
+/**
+ * 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, event, env, doc) {
+    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/dist/apps/shared/keyboard/format.d.ts

@@ -0,0 +1,12 @@
+import type { ShortcutDef } from "./keymap.js";
+import type { KeyEnvironment } from "./platform.js";
+/** A spec as a person reads it: `Ctrl+Shift+R`, or `⌃⇧R`-style glyphs on a Mac (`⌘` for Cmd, `⌥` for Option). */
+export declare function formatSpec(spec: string, env: KeyEnvironment): string;
+/** A spec in `aria-keyshortcuts` syntax: `Control+Shift+R`, `Meta+R`. */
+export declare function ariaSpec(spec: string, env: KeyEnvironment): string;
+/** Every spec that triggers a shortcut here: its keys, and in the desktop client also its desktop-only ones. */
+export declare function specsFor(shortcut: ShortcutDef, env: KeyEnvironment): string[];
+/** The `aria-keyshortcuts` value for a control that runs a shortcut: every alternative, space separated. */
+export declare function ariaKeyShortcuts(shortcut: ShortcutDef, env: KeyEnvironment): string;
+/** A tooltip/name suffix such as `Reply (Ctrl+R)`: the label with the shortcut's first key. */
+export declare function withHint(label: string, shortcut: ShortcutDef, env: KeyEnvironment): string;

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

@@ -0,0 +1,74 @@
+import { parseSpec, resolveModifiers } from "./parse.js";
+const KEY_NAMES = {
+    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 = { ...KEY_NAMES, enter: "↩", backspace: "⌫", delete: "⌦" };
+/** The key as it is printed on a key cap: `R`, `F5`, `Enter`, an arrow. */
+function keyLabel(key, mac) {
+    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, env) {
+    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 = {
+    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, env) {
+    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, env) {
+    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, env) {
+    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, shortcut, env) {
+    return `${label} (${formatSpec(shortcut.keys[0], env)})`;
+}