@rapidmx/web-client 0.14.1 → 0.16.0

package/apps/shared/gestures/useSwipeSlide.ts

@@ -0,0 +1,113 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+import { SwipeDirection, useSwipe } from "./useSwipe.js";
+
+/** How long the current contents take to leave, and the new ones to arrive - or the current ones to snap back. */
+export const SLIDE_MS = 200;
+/** The pause between the new contents being put off-screen and them starting to slide in, long enough for the browser to draw them there. */
+const SETTLE_MS = 30;
+/** How far a slide goes when the element's width can't be measured. */
+const FALLBACK_WIDTH_PX = 320;
+
+export interface UseSwipeSlideOptions {
+    /** Nothing is tracked while this is `false`. */
+    enabled: boolean;
+    /** Changes what is shown to the period the swipe went to - called once the old contents have left, while the new ones wait off-screen. */
+    onShift: (direction: SwipeDirection) => void;
+}
+
+/** Whether the user asked their device for less motion, in which case the change is made at once instead of slid. */
+function prefersReducedMotion(): boolean {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * A swipe between pages of content that visibly moves them, the way a phone calendar does: the contents follow the finger, and once
+ * the swipe commits they carry on out of view in the direction it went while the next ones - `onShift()` changes what is shown at
+ * that moment - slide in from the other side. A swipe that stops short slides back. The animation is timed here (`SLIDE_MS`) rather than
+ * left to `transitionend`, so it can't stall if the browser skips a transition.
+ *
+ * Put `handlers` and `style` on a clipping element (`overflow-hidden`, so the contents don't widen the page while they are off to
+ * the side), the contents inside it in an element of their own with `contentStyle`, and `ref` on the clipping element.
+ */
+export function useSwipeSlide({ enabled, onShift }: UseSwipeSlideOptions) {
+    const [offset, setOffset] = useState(0);
+    /** Whether a change of `offset` is animated: not while the finger is moving it, yes for everything else. */
+    const [animated, setAnimated] = useState(false);
+    /** A committed slide is under way: further swipes are ignored until it ends. */
+    const [sliding, setSliding] = useState(false);
+    const slidingRef = useRef(false);
+    const ref = useRef<HTMLDivElement | null>(null);
+    const timers = useRef<number[]>([]);
+    const latest = useRef({ onShift });
+    latest.current = { onShift };
+
+    useEffect(
+        () => () => {
+            for (const timer of timers.current) {
+                window.clearTimeout(timer);
+            }
+        },
+        [],
+    );
+
+    function later(work: () => void, ms: number) {
+        timers.current.push(window.setTimeout(work, ms));
+    }
+
+    const swipe = useSwipe({
+        enabled: enabled && !sliding,
+        onDrag: (dx) => {
+            // `useSwipe()` reports the finger lifting (0) right after a swipe commits: that must not undo the slide out.
+            if (slidingRef.current) {
+                return;
+            }
+            setAnimated(dx === 0);
+            setOffset(dx);
+        },
+        onSwipe: (direction) => {
+            if (prefersReducedMotion()) {
+                latest.current.onShift(direction);
+                return;
+            }
+            const width = ref.current?.clientWidth || FALLBACK_WIDTH_PX;
+            // The finger moved `direction`, so the contents go that way and the next ones come from the opposite side.
+            const out = direction === "left" ? -width : width;
+            slidingRef.current = true;
+            setSliding(true);
+            setAnimated(true);
+            setOffset(out);
+            later(() => {
+                latest.current.onShift(direction);
+                setAnimated(false);
+                setOffset(-out);
+                later(() => {
+                    setAnimated(true);
+                    setOffset(0);
+                    later(() => {
+                        slidingRef.current = false;
+                        setSliding(false);
+                    }, SLIDE_MS);
+                }, SETTLE_MS);
+            }, SLIDE_MS);
+        },
+    });
+
+    const contentStyle: CSSProperties = {
+        transform: offset === 0 ? undefined : `translate3d(${offset}px, 0, 0)`,
+        transition: animated ? `transform ${SLIDE_MS}ms ease-out` : "none",
+    };
+
+    return {
+        handlers: swipe.handlers,
+        /** For the clipping element: `touch-action: pan-y`, and no overflow. */
+        style: swipe.style,
+        contentStyle,
+        ref,
+        /** For a test or a style hook: `"idle"`, `"dragging"` or `"sliding"`. */
+        phase: sliding ? "sliding" : offset !== 0 && !animated ? "dragging" : "idle",
+    };
+}

package/apps/shared/gestures/useWheelPaging.ts

@@ -0,0 +1,107 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, type RefObject } from "react";
+
+/** Wheel movement, in pixels, that steps to the next or previous page when nothing inside scrolls: about one notch of a mouse wheel. */
+export const WHEEL_STEP_PX = 100;
+/** Wheel movement, in pixels, pushed against the top or bottom of what scrolls inside before it steps onto the next or previous page. */
+export const WHEEL_EDGE_PX = 80;
+/** Movement that isn't followed by more within this long starts from nothing again, so an old nudge doesn't add to a new one. */
+export const WHEEL_IDLE_MS = 250;
+/** After a step that starts at an edge, wheel events for this long are left to settle the new page, so one hard push isn't two steps. */
+export const WHEEL_SETTLE_MS = 100;
+
+/** Where the new page's scroll position goes: `"top"` when stepping forward past the bottom, `"bottom"` when stepping back past the top. */
+export type WheelEdge = "top" | "bottom";
+
+export interface UseWheelPagingOptions {
+    /** Nothing is handled while this is `false` (a phone, an event being dragged, a dialog open). */
+    enabled: boolean;
+    /** The element inside that scrolls vertically, if there is one now: the wheel scrolls it as usual and only steps past its ends.
+     * `null` when nothing inside scrolls (a month grid), and then every wheel movement counts towards a step. */
+    getScroller: () => HTMLElement | null;
+    /** Called for each step: `1` towards the next page (the wheel turned down), `-1` towards the previous. `edge` says where in the new
+     * page's scroller to start, when there is one. */
+    onStep: (direction: 1 | -1, edge: WheelEdge | null) => void;
+}
+
+/** A wheel event's vertical movement in pixels, whichever unit the browser reports it in. */
+function pixelsOf(event: WheelEvent, page: number): number {
+    return event.deltaMode === 1 ? event.deltaY * 16 : event.deltaMode === 2 ? event.deltaY * page : event.deltaY;
+}
+
+/**
+ * Turns the mouse wheel over `ref`'s element into stepping through pages - the months, weeks or days of a calendar - without a limit:
+ * keep turning and it keeps stepping, and nothing waits for an animation to end.
+ *
+ * Where nothing inside scrolls, every `WHEEL_STEP_PX` of movement is a step (a bigger turn is several). Where something does, the
+ * wheel scrolls it as it always did and only what is pushed against its top or bottom counts (`WHEEL_EDGE_PX`), so scrolling on
+ * from the last hour of a day carries into the first hours of the next, and back the other way. The event is only cancelled when it
+ * counts towards a step, so the page and whatever scrolls inside keep their own wheel behaviour everywhere else. Zooming
+ * (Ctrl+wheel) and sideways movement are left alone.
+ */
+export function useWheelPaging(ref: RefObject<HTMLElement | null>, { enabled, getScroller, onStep }: UseWheelPagingOptions) {
+    const latest = useRef({ getScroller, onStep });
+    latest.current = { getScroller, onStep };
+    /** Movement collected towards the next step, and when it last grew. */
+    const collected = useRef({ pixels: 0, at: 0 });
+    const settledUntil = useRef(0);
+
+    useEffect(() => {
+        const element = ref.current;
+        if (!enabled || !element) {
+            return;
+        }
+
+        function onWheel(event: WheelEvent) {
+            if (event.ctrlKey || event.defaultPrevented || Math.abs(event.deltaX) > Math.abs(event.deltaY)) {
+                return;
+            }
+            const pixels = pixelsOf(event, element!.clientHeight || 600);
+            if (pixels === 0) {
+                return;
+            }
+            const scroller = latest.current.getScroller();
+            if (scroller) {
+                const room = scroller.scrollHeight - scroller.clientHeight;
+                const canScroll = pixels > 0 ? scroller.scrollTop < room - 1 : scroller.scrollTop > 0;
+                if (room > 0 && canScroll) {
+                    // Still something to scroll that way: the browser does it, and what was pushed against an end is forgotten.
+                    collected.current = { pixels: 0, at: 0 };
+                    return;
+                }
+            }
+
+            event.preventDefault();
+            const now = Date.now();
+            if (scroller && now < settledUntil.current) {
+                return;
+            }
+            const state = collected.current;
+            if (now - state.at > WHEEL_IDLE_MS || Math.sign(state.pixels) !== Math.sign(pixels)) {
+                state.pixels = 0;
+            }
+            state.at = now;
+            state.pixels += pixels;
+
+            const needed = scroller ? WHEEL_EDGE_PX : WHEEL_STEP_PX;
+            while (Math.abs(state.pixels) >= needed) {
+                const direction: 1 | -1 = state.pixels > 0 ? 1 : -1;
+                state.pixels -= direction * needed;
+                latest.current.onStep(direction, scroller ? (direction > 0 ? "top" : "bottom") : null);
+                if (scroller) {
+                    // One push against an end is one step; the next turn of the wheel scrolls the page it arrived at.
+                    state.pixels = 0;
+                    settledUntil.current = now + WHEEL_SETTLE_MS;
+                    break;
+                }
+            }
+        }
+
+        // Not passive: the wheel's default (scrolling the page) has to be cancellable for the steps that replace it.
+        element.addEventListener("wheel", onWheel, { passive: false });
+        return () => element.removeEventListener("wheel", onWheel);
+    }, [enabled, ref]);
+}

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

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