@rapidmx/web-client 0.20.0 → 0.22.0

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -4,11 +4,12 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
 import { HiOutlineBars3 } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
-import { Mailbox, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
+import Drawer from "../../../../../lib/components/overlays/Drawer.js";
+import { Mailbox, listMailboxes } from "../../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../../lib/util/apiClientContext.js";
+import Alert from "../../../../../lib/components/feedback/Alert.js";
+import Skeleton, { SkeletonList } from "../../../../../lib/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
 import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
@@ -93,6 +94,7 @@ export default function SettingsShell({
     pluginNav,
     children,
 }: PropsWithChildren<SettingsShellProps>) {
+    const client = useApiClient();
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
     const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
@@ -116,7 +118,7 @@ export default function SettingsShell({
         if (!userUid) {
             return;
         }
-        listMailboxes({ limit: 100 })
+        listMailboxes({ limit: 100 }, client)
             .then((result) => {
                 setMailboxes(orderMailboxes(result, userUid));
                 setStatus("ready");

package/apps/shared/components/sharing/PrincipalListField.tsx

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React from "react";
-import { ResolvedPrincipal } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+import { ResolvedPrincipal } from "../../../../lib/mail/mailboxAccessApi.js";
 import PrincipalResolver, { describePerson } from "./PrincipalResolver.js";
 
 export interface PrincipalListFieldProps {

package/apps/shared/components/sharing/PrincipalPicker.tsx

@@ -8,7 +8,7 @@ import {
     ResolvedPrincipal,
     resolveMailboxPrincipal,
     setMailboxAccess,
-} from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+} from "../../../../lib/mail/mailboxAccessApi.js";
 import PrincipalResolver, { describePerson } from "./PrincipalResolver.js";
 
 export { describePerson };

package/apps/shared/components/sharing/PrincipalResolver.tsx

@@ -3,10 +3,10 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { KeyboardEvent, ReactNode, useEffect, useState } from "react";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { ResolvedPrincipal } 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";
+import { ApiRequestError } from "../../../../lib/util/api.js";
+import { ResolvedPrincipal } from "../../../../lib/mail/mailboxAccessApi.js";
+import Alert from "../../../../lib/components/feedback/Alert.js";
+import Button from "../../../../lib/components/buttons/Button.js";
 
 export interface PrincipalResolverProps {
     /** Resolves what was typed - a mailbox address, an auth-server username or e-mail alias, or a user uid - to

package/apps/shared/components/tasks/TasksSidebar.tsx

@@ -4,9 +4,10 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useEffect, useMemo, useState } from "react";
 import { HiOutlineBars3 } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { Task, TaskList, createTaskList, listTaskLists } from "@rapidmx/react-shared/tasks/tasksApi.js";
-import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { ApiRequestError } from "../../../../lib/util/api.js";
+import { Task, TaskList, createTaskList, listTaskLists } from "../../../../lib/tasks/tasksApi.js";
+import Drawer from "../../../../lib/components/overlays/Drawer.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
 import { notifyApiError } from "../../notifications/apiErrors.js";
 
 export type TasksView =
@@ -61,6 +62,7 @@ function NavItem({ label, count, active, onClick }: { label: string; count?: num
  * lists are real `TaskList` records, fetched here (same pattern as `ContactsSidebar`'s contact lists).
  */
 export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSelect, refreshToken }: TasksSidebarProps) {
+    const client = useApiClient();
     const [lists, setLists] = useState<TaskList[]>([]);
     const [listsError, setListsError] = useState<string | null>(null);
     const [addingList, setAddingList] = useState(false);
@@ -73,7 +75,7 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
             return;
         }
         setListsError(null);
-        listTaskLists(mailboxUid, { limit: 200 })
+        listTaskLists(mailboxUid, { limit: 200 }, client)
             .then(setLists)
             .catch((err) => setListsError(err instanceof ApiRequestError ? err.message : "Could not load task lists."));
     }, [mailboxUid, refreshToken]);
@@ -98,7 +100,7 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
             return;
         }
         try {
-            const created = await createTaskList({ mailboxUid, name: newListName.trim() });
+            const created = await createTaskList({ mailboxUid, name: newListName.trim() }, client);
             setLists((prev) => [...prev, created].sort((a, b) => a.name.localeCompare(b.name)));
             setNewListName("");
             setAddingList(false);

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

@@ -4,11 +4,12 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
 import { HiOutlineBars3 } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
-import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
+import Drawer from "../../../../../lib/components/overlays/Drawer.js";
+import { Folder, Mailbox, listFolders, listMailboxes } from "../../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../../lib/util/apiClientContext.js";
+import Alert from "../../../../../lib/components/feedback/Alert.js";
+import Skeleton, { SkeletonList } from "../../../../../lib/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
 import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
@@ -53,6 +54,7 @@ export default function TasksShell({
     pluginNav,
     children,
 }: PropsWithChildren<TasksShellProps>) {
+    const client = useApiClient();
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
     const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
@@ -78,7 +80,7 @@ export default function TasksShell({
         if (!userUid) {
             return;
         }
-        listMailboxes({ limit: 100 })
+        listMailboxes({ limit: 100 }, client)
             .then((result) => {
                 setMailboxes(orderMailboxes(result, userUid));
                 setStatus("ready");
@@ -99,7 +101,7 @@ export default function TasksShell({
             return;
         }
         setFolderError(null);
-        listFolders(mailboxUid)
+        listFolders(mailboxUid, client)
             .then(setFolders)
             .catch((err) => setFolderError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox's tasks folder."));
     }, [mailboxUid]);

package/apps/shared/keyboard/GlobalShortcuts.tsx

@@ -1,51 +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/index.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;
-}
+///////////////////////////////////////////////////////////////////////////////
+// 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/index.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

@@ -1,62 +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);
-}
+///////////////////////////////////////////////////////////////////////////////
+// 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

@@ -1,84 +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>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Modal from "../../../lib/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>
+    );
+}