@rapidmx/web-client 0.9.0 → 0.10.0

package/apps/shared/navigation/routerContext.tsx

@@ -0,0 +1,83 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What the client-side router (`AppRouter.tsx`) offers to the tree under it - the location and a way to navigate - and the hooks that read
+ * it. Kept apart from the router itself so that the app frame (`AppShell`), which the router renders, can use `useNavigate()` without a
+ * circular import. `AppRouter.tsx` re-exports everything here, so callers keep importing from there.
+ */
+import { createContext, useContext, useEffect, useState } from "react";
+
+export interface RouterLocation {
+    pathname: string;
+    /** With the leading `?`, or `""`. */
+    search: string;
+    /** With the leading `#`, or `""`. */
+    hash: string;
+}
+
+export interface NavigateOptions {
+    /** Replaces the current history entry instead of adding one (a redirect, or a state change that isn't a "place"). */
+    replace?: boolean;
+}
+
+/** Goes to `href`: without a page load when it is a route of the app, else as an ordinary navigation. */
+export type NavigateFn = (href: string, options?: NavigateOptions) => void;
+
+export interface RouterContextValue {
+    location: RouterLocation;
+    navigate: NavigateFn;
+}
+
+export const RouterContext = createContext<RouterContextValue | null>(null);
+
+/** Before the browser's own location has been read (the server render and the first client render, which must match). */
+export const UNKNOWN_LOCATION: RouterLocation = { pathname: "", search: "", hash: "" };
+
+export function readWindowLocation(): RouterLocation {
+    const { pathname, search, hash } = window.location;
+    return { pathname, search, hash };
+}
+
+/** What `useNavigate()` does outside a router: an ordinary navigation, exactly as `window.location.href = href` always was. */
+function navigateWithBrowser(href: string, options: NavigateOptions = {}): void {
+    if (options.replace) {
+        window.location.replace(href);
+    } else {
+        window.location.href = href;
+    }
+}
+
+/**
+ * The function to go somewhere with. `navigate("/calendar")` and `navigate("/?mailboxUid=a&folderUid=b")` change the page and
+ * the URL without a page load when the router knows the route (Mail, Calendar, Contacts, Tasks, Settings and their subpages),
+ * and load the page normally otherwise; outside the router it is always a normal navigation. Prefer a plain `<a href>` for
+ * anything the user clicks - the router intercepts it, and it stays a real link - and this for what code decides (after a
+ * save, a delete, a select). The returned function is stable across renders.
+ */
+export function useNavigate(): NavigateFn {
+    const router = useContext(RouterContext);
+    return router ? router.navigate : navigateWithBrowser;
+}
+
+/**
+ * Where the app is now, as `{ pathname, search, hash }`, updating as the router navigates (folder changes are `search`
+ * changes, not page changes). Empty until the browser's location has been read in an effect after the first render, so that
+ * the server render and the first client render agree - read query parameters from it in an effect, not during render.
+ */
+export function useLocation(): RouterLocation {
+    const router = useContext(RouterContext);
+    const [own, setOwn] = useState<RouterLocation>(UNKNOWN_LOCATION);
+    useEffect(() => {
+        if (!router) {
+            setOwn(readWindowLocation());
+        }
+    }, [router]);
+    return router ? router.location : own;
+}
+
+/** `useLocation().search` - what the shells read `?mailboxUid=` and the like from. */
+export function useLocationSearch(): string {
+    return useLocation().search;
+}

package/apps/shared/navigation/routes.ts

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ComponentType } from "react";
+
+/**
+ * One page the client-side router (`AppRouter`) can show without a page load. The table of them (`apps/www/_routes.ts`)
+ * mirrors the files under `apps/www`: what isn't in it (the admin and escrow consoles, plugin pages, anything else) is
+ * reached by a normal navigation.
+ */
+export interface RouteDefinition {
+    /** The route template: literal segments and `:name` parameters, the same shape as the file path (`/messages/:uid`
+     * for `messages/[uid].tsx`). The first entry that matches a URL wins, so list literal routes before parameterized
+     * ones (`/settings/filters/new` before `/settings/filters/:uid`). */
+    path: string;
+    /** The app-rail entry (or `"settings"`) highlighted while this page shows - what the page's shell passes as `active`. */
+    active: string;
+    /**
+     * Loads the page's module, which must have a `routedPage()` component as its default export. Written as
+     * `() => import("./calendar/index.js")` so the bundler makes the page its own chunk; it is called the first time the
+     * page is shown or prefetched (pointer over or focus on a link to it, or when the browser is idle).
+     */
+    load: () => Promise<{ default: ComponentType<any> }>;
+    /** Downloaded when the browser is idle after the first page has loaded - the app rail's own pages, which are the
+     * likeliest next click. */
+    idlePrefetch?: boolean;
+}
+
+export interface RouteMatch {
+    route: RouteDefinition;
+    /** The values of the template's `:name` segments, decoded. */
+    params: Record<string, string>;
+}
+
+/** Splits a path into segments, ignoring a trailing slash: `/` and `""` have none. */
+function segmentsOf(path: string): string[] {
+    return path.split("/").filter((segment) => segment !== "");
+}
+
+/** Matches `pathname` against one route template - `undefined` when it doesn't, or a parameter isn't valid percent-encoding. */
+function matchTemplate(template: string, pathname: string): Record<string, string> | undefined {
+    const expected = segmentsOf(template);
+    const actual = segmentsOf(pathname);
+    if (expected.length !== actual.length) {
+        return undefined;
+    }
+    const params: Record<string, string> = {};
+    for (let i = 0; i < expected.length; i++) {
+        if (expected[i].startsWith(":")) {
+            try {
+                params[expected[i].slice(1)] = decodeURIComponent(actual[i]);
+            } catch {
+                return undefined;
+            }
+        } else if (expected[i] !== actual[i]) {
+            return undefined;
+        }
+    }
+    return params;
+}
+
+/** The first route in `routes` whose template matches `pathname`, with its parameters. */
+export function matchRoute(routes: readonly RouteDefinition[], pathname: string): RouteMatch | undefined {
+    for (const route of routes) {
+        const params = matchTemplate(route.path, pathname);
+        if (params) {
+            return { route, params };
+        }
+    }
+    return undefined;
+}

package/apps/shared/search/LocalIndexLifecycle.tsx

@@ -1,98 +1,114 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-/**
- * Mounts the Tier 2 local index's lifecycle: starts the background build for the active mailbox once it's
- * unlocked, and destroys an index on the same events that destroy that mailbox's unlocked keys (spec §11
- * "MUST be destroyed on the same events that destroy private keys: explicit logout, session revocation,
- * and the configurable idle timeout").
- *
- * **Why polling, not hooking the existing destroy call sites directly**: `destroyUnlockedKeys()`
- * (`react-shared/src/crypto/keySession.ts`) has no observer/callback hook. Watching `getUnlockedKeys()`
- * for a present-to-absent transition catches *every* destroy path uniformly - idle timeout, the manual
- * button, or anything else that calls it - without needing to know which one fired.
- *
- * Every mailbox this component has seen unlocked is tracked for the life of the mount - not just whichever
- * is active right now - so switching mailboxes (or a folders-list refresh re-running the build effect)
- * can never lose a pending unlocked-to-locked transition for a mailbox whose index was already built.
- *
- * **Explicit logout** navigates away immediately, which may not leave time for a poll tick - `AppShell.tsx`
- * handles that case itself via `destroyAllLocalIndexes()`.
- */
-import { useEffect, useRef } from "react";
-import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
-import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
-import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
-import { buildLocalIndex, cancelLocalIndexBuild } from "./localIndexBuilder.js";
-import { destroyLocalIndex, pruneInaccessibleLocalIndexes } from "./localIndexRpcClient.js";
-
-export const POLL_INTERVAL_MS = 5_000;
-
-export interface LocalIndexLifecycleProps {
-    mailboxUid?: string;
-    mailboxKeys?: PublicKey[];
-    folders: Folder[];
-    /** Every mailbox the signed-in user can currently access. Once known, indexes on this device for any
-     * other mailbox (e.g. left behind by a different user who never signed out) are removed. */
-    accessibleMailboxUids?: string[];
-}
-
-/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
-export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }: LocalIndexLifecycleProps) {
-    // mailboxUid -> whether it was unlocked at the last check. An entry exists for every mailbox whose
-    // build this component started; only ever changed by a real observed transition, never reset by an
-    // effect re-run.
-    const trackedRef = useRef(new Map<string, boolean>());
-    // The latest props, for the long-lived polling interval below.
-    const latestRef = useRef({ mailboxUid, folders });
-    latestRef.current = { mailboxUid, folders };
-
-    function startBuildIfUnlocked(targetMailboxUid: string, targetFolders: Folder[]) {
-        const unlocked = getUnlockedKeys(targetMailboxUid);
-        if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
-            return;
-        }
-        trackedRef.current.set(targetMailboxUid, true);
-        // Never an unhandled rejection - a broken local index is best-effort infrastructure, not a build
-        // the rest of the app depends on.
-        buildLocalIndex(targetMailboxUid, unlocked, targetFolders).catch(() => undefined);
-    }
-
-    useEffect(() => {
-        if (mailboxUid) {
-            startBuildIfUnlocked(mailboxUid, folders);
-        }
-    }, [mailboxUid, folders]);
-
-    useEffect(() => {
-        const interval = setInterval(() => {
-            for (const [trackedUid, wasUnlocked] of trackedRef.current) {
-                if (wasUnlocked && !getUnlockedKeys(trackedUid)) {
-                    // A present-to-absent transition: something just destroyed this mailbox's keys.
-                    trackedRef.current.set(trackedUid, false);
-                    // Stop the pass still running with the now-destroyed keys; the destroy itself also makes
-                    // the Worker reject anything that pass still sends.
-                    void cancelLocalIndexBuild(trackedUid);
-                    void destroyLocalIndex(trackedUid);
-                }
-            }
-            // The active mailbox was (re-)unlocked since the last check, e.g. via an on-demand unlock prompt.
-            const { mailboxUid: activeUid, folders: activeFolders } = latestRef.current;
-            if (activeUid) {
-                startBuildIfUnlocked(activeUid, activeFolders);
-            }
-        }, POLL_INTERVAL_MS);
-        return () => clearInterval(interval);
-    }, []);
-
-    // A stable string key so a re-render with an equal-but-new array doesn't re-scan OPFS.
-    const accessibleKey = accessibleMailboxUids && accessibleMailboxUids.length > 0 ? JSON.stringify([...accessibleMailboxUids].sort()) : "";
-    useEffect(() => {
-        if (accessibleKey) {
-            void pruneInaccessibleLocalIndexes(JSON.parse(accessibleKey) as string[]);
-        }
-    }, [accessibleKey]);
-
-    return null;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Mounts the Tier 2 local index's lifecycle: starts the background build for the active mailbox once it's
+ * unlocked, and destroys an index on the same events that destroy that mailbox's unlocked keys (spec §11
+ * "MUST be destroyed on the same events that destroy private keys: explicit logout, session revocation,
+ * and the configurable idle timeout").
+ *
+ * **Why polling, not hooking the existing destroy call sites directly**: `destroyUnlockedKeys()`
+ * (`react-shared/src/crypto/keySession.ts`) has no observer/callback hook. Watching `getUnlockedKeys()`
+ * for a present-to-absent transition catches *every* destroy path uniformly - idle timeout, the manual
+ * button, or anything else that calls it - without needing to know which one fired.
+ *
+ * Every mailbox this component has seen unlocked is tracked for the life of the mount - not just whichever
+ * is active right now - so switching mailboxes (or a folders-list refresh re-running the build effect)
+ * can never lose a pending unlocked-to-locked transition for a mailbox whose index was already built.
+ *
+ * **Explicit logout** navigates away immediately, which may not leave time for a poll tick - `AppShell.tsx`
+ * handles that case itself via `destroyAllLocalIndexes()`.
+ */
+import { useEffect, useRef } from "react";
+import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/**
+ * The index builder (with the message security code it decrypts through - PKI.js and the ASN.1/X.509 libraries, over half a
+ * megabyte) is loaded only once a mailbox is actually unlocked and a build is due, so an inbox that never unlocks - the
+ * common case - never downloads it.
+ */
+let builder: Promise<typeof import("./localIndexBuilder.js")> | undefined;
+const loadBuilder = () =>
+    (builder ??= import("./localIndexBuilder.js").catch((err) => {
+        // A failed download is tried again the next time one is due.
+        builder = undefined;
+        throw err;
+    }));
+import { destroyLocalIndex, pruneInaccessibleLocalIndexes } from "./localIndexRpcClient.js";
+
+export const POLL_INTERVAL_MS = 5_000;
+
+export interface LocalIndexLifecycleProps {
+    mailboxUid?: string;
+    mailboxKeys?: PublicKey[];
+    folders: Folder[];
+    /** Every mailbox the signed-in user can currently access. Once known, indexes on this device for any
+     * other mailbox (e.g. left behind by a different user who never signed out) are removed. */
+    accessibleMailboxUids?: string[];
+}
+
+/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
+export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }: LocalIndexLifecycleProps) {
+    // mailboxUid -> whether it was unlocked at the last check. An entry exists for every mailbox whose
+    // build this component started; only ever changed by a real observed transition, never reset by an
+    // effect re-run.
+    const trackedRef = useRef(new Map<string, boolean>());
+    // The latest props, for the long-lived polling interval below.
+    const latestRef = useRef({ mailboxUid, folders });
+    latestRef.current = { mailboxUid, folders };
+
+    function startBuildIfUnlocked(targetMailboxUid: string, targetFolders: Folder[]) {
+        const unlocked = getUnlockedKeys(targetMailboxUid);
+        if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
+            return;
+        }
+        trackedRef.current.set(targetMailboxUid, true);
+        // Never an unhandled rejection - a broken local index is best-effort infrastructure, not a build
+        // the rest of the app depends on.
+        loadBuilder()
+            .then(({ buildLocalIndex }) => buildLocalIndex(targetMailboxUid, unlocked, targetFolders))
+            .catch(() => undefined);
+    }
+
+    useEffect(() => {
+        if (mailboxUid) {
+            startBuildIfUnlocked(mailboxUid, folders);
+        }
+    }, [mailboxUid, folders]);
+
+    useEffect(() => {
+        const interval = setInterval(() => {
+            for (const [trackedUid, wasUnlocked] of trackedRef.current) {
+                if (wasUnlocked && !getUnlockedKeys(trackedUid)) {
+                    // A present-to-absent transition: something just destroyed this mailbox's keys.
+                    trackedRef.current.set(trackedUid, false);
+                    // Stop the pass still running with the now-destroyed keys; the destroy itself also makes
+                    // the Worker reject anything that pass still sends.
+                    loadBuilder()
+                        .then(({ cancelLocalIndexBuild }) => cancelLocalIndexBuild(trackedUid))
+                        .catch(() => undefined);
+                    void destroyLocalIndex(trackedUid);
+                }
+            }
+            // The active mailbox was (re-)unlocked since the last check, e.g. via an on-demand unlock prompt.
+            const { mailboxUid: activeUid, folders: activeFolders } = latestRef.current;
+            if (activeUid) {
+                startBuildIfUnlocked(activeUid, activeFolders);
+            }
+        }, POLL_INTERVAL_MS);
+        return () => clearInterval(interval);
+    }, []);
+
+    // A stable string key so a re-render with an equal-but-new array doesn't re-scan OPFS.
+    const accessibleKey = accessibleMailboxUids && accessibleMailboxUids.length > 0 ? JSON.stringify([...accessibleMailboxUids].sort()) : "";
+    useEffect(() => {
+        if (accessibleKey) {
+            void pruneInaccessibleLocalIndexes(JSON.parse(accessibleKey) as string[]);
+        }
+    }, [accessibleKey]);
+
+    return null;
+}

package/apps/shared/styles/app.css

@@ -276,13 +276,31 @@ h5,
 h6 {
     font-family: var(--rr-font-display);
 }
-
-/* The compose editor's quoted original (`composeQuoting.ts`'s blockquote). TipTap keeps the element but not the
- * inline style it was seeded with, and Tailwind's preflight resets the browser's own blockquote indent - without
- * this the quote under a reply reads as if it were part of the new message. */
-.tiptap blockquote {
-    margin: 0;
-    padding-left: 1em;
-    border-left: 2px solid var(--rr-color-border);
-    color: var(--rr-color-text-muted);
-}
+
+/* The compose editor's quoted original (`composeQuoting.ts`'s blockquote). TipTap keeps the element but not the
+ * inline style it was seeded with, and Tailwind's preflight resets the browser's own blockquote indent - without
+ * this the quote under a reply reads as if it were part of the new message. */
+.tiptap blockquote {
+    margin: 0;
+    padding-left: 1em;
+    border-left: 2px solid var(--rr-color-border);
+    color: var(--rr-color-text-muted);
+}
+
+/* A new-mail pop-up (`NewMailToasts.tsx`) eases in from just above its place. Only for readers who have not asked their system
+ * for less motion: with `prefers-reduced-motion: reduce` it simply appears. */
+@media (prefers-reduced-motion: no-preference) {
+    .rr-toast-in {
+        animation: rr-toast-in 0.18s ease-out;
+    }
+}
+@keyframes rr-toast-in {
+    from {
+        opacity: 0;
+        transform: translateY(-0.5rem);
+    }
+    to {
+        opacity: 1;
+        transform: none;
+    }
+}

package/apps/www/_routedPage.tsx

@@ -0,0 +1,24 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ComponentType } from "react";
+import AppRouter, { RoutedPageComponent } from "../shared/navigation/AppRouter.js";
+import { wwwRoutes } from "./_routes.js";
+
+/**
+ * Makes a `www` page the entry of the client-side router: the page's default export is `routedPage("/its/route", Page)`.
+ * `@rapidrest/react` server-renders and hydrates exactly that component, so what it renders - the router, with the persistent
+ * app frame (`AppChrome`) and `Page` inside it - is the whole client tree, and later pages replace `Page` without a page load.
+ * `path` is the page's route template, the same as its entry in `_routes.ts`.
+ *
+ * The result carries the plain `Page` as `.page`, which is what the router shows when it loads this module for a navigation
+ * (rendering the wrapped default export there would nest a second router).
+ */
+export function routedPage<P extends object>(path: string, Page: ComponentType<P>): RoutedPageComponent<P> {
+    function RoutedPage(props: P) {
+        return <AppRouter routes={wwwRoutes} initialPath={path} initialPage={Page} pageProps={props} />;
+    }
+    RoutedPage.page = Page;
+    return RoutedPage;
+}

package/apps/www/_routes.ts

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { RouteDefinition } from "../shared/navigation/routes.js";
+
+/**
+ * Every `apps/www` page the client-side router can show without a page load (see `apps/shared/navigation/AppRouter.tsx`), in
+ * the order they are matched: literal routes before the parameterized ones that would also match them. Each page loads with a
+ * dynamic `import()`, which is what makes it a chunk of its own - only the page a document was rendered for is in its first
+ * JavaScript. Keep it in step with the files under `apps/www`; a page missing from here still works, it is just reached with a
+ * page load. (The file starts with `_` so `@rapidrest/react` doesn't treat it as a page.)
+ *
+ * The four app-rail pages are `idlePrefetch`ed: downloaded when the browser is idle after the first page has loaded.
+ */
+export const wwwRoutes: readonly RouteDefinition[] = [
+    { path: "/", active: "mail", load: () => import("./index.js"), idlePrefetch: true },
+    { path: "/messages/:uid", active: "mail", load: () => import("./messages/[uid].js") },
+    { path: "/calendar", active: "calendar", load: () => import("./calendar/index.js"), idlePrefetch: true },
+    { path: "/contacts", active: "contacts", load: () => import("./contacts/index.js"), idlePrefetch: true },
+    { path: "/contacts/:uid", active: "contacts", load: () => import("./contacts/[uid].js") },
+    { path: "/tasks", active: "tasks", load: () => import("./tasks/index.js"), idlePrefetch: true },
+    { path: "/settings/auto-reply", active: "settings", load: () => import("./settings/auto-reply/index.js") },
+    { path: "/settings/encryption", active: "settings", load: () => import("./settings/encryption/index.js") },
+    { path: "/settings/filters", active: "settings", load: () => import("./settings/filters/index.js") },
+    { path: "/settings/filters/new", active: "settings", load: () => import("./settings/filters/new/index.js") },
+    { path: "/settings/filters/:uid", active: "settings", load: () => import("./settings/filters/[uid].js") },
+    { path: "/settings/labels", active: "settings", load: () => import("./settings/labels/index.js") },
+    { path: "/settings/privacy", active: "settings", load: () => import("./settings/privacy/index.js") },
+    { path: "/settings/read-receipts", active: "settings", load: () => import("./settings/read-receipts/index.js") },
+    { path: "/settings/sharing", active: "settings", load: () => import("./settings/sharing/index.js") },
+    { path: "/settings/signatures", active: "settings", load: () => import("./settings/signatures/index.js") },
+    { path: "/settings/signatures/new", active: "settings", load: () => import("./settings/signatures/new/index.js") },
+    { path: "/settings/signatures/:uid", active: "settings", load: () => import("./settings/signatures/[uid].js") },
+];

package/apps/www/calendar/index.tsx

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
+import { routedPage } from "../_routedPage.js";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import { DndContext, DragEndEvent, MouseSensor, TouchSensor, useSensor, useSensors } from "@dnd-kit/core";
 import { HiOutlineBars3 } from "react-icons/hi2";
@@ -36,8 +37,11 @@ import SplitDayView from "../../shared/components/calendar/SplitDayView.js";
 import TimeGridView from "../../shared/components/calendar/TimeGridView.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { SHORTCUTS, ShortcutDef } from "../../shared/keyboard/keymap.js";
+import { useShortcut } from "../../shared/keyboard/useShortcut.js";
+import { useShortcutProps } from "../../shared/keyboard/useShortcutProps.js";
 
-export default function CalendarPage(props: CalendarShellProps) {
+function CalendarPage(props: CalendarShellProps) {
     return (
         <CalendarShell {...props}>
             <CalendarContent userUid={props.userUid} />
@@ -48,6 +52,35 @@ export default function CalendarPage(props: CalendarShellProps) {
 type ViewType = "month" | "week" | "workWeek" | "day" | "split";
 const VIEW_TYPES: ViewType[] = ["month", "week", "workWeek", "day", "split"];
 const VIEW_LABELS: Record<ViewType, string> = { month: "Month", week: "Week", workWeek: "Work Week", day: "Day", split: "Split" };
+/** The shortcut that switches to a view (Outlook's Ctrl+Alt+1-4); the split view has none. */
+const VIEW_SHORTCUTS: Partial<Record<ViewType, ShortcutDef>> = {
+    day: SHORTCUTS.calendar.day,
+    workWeek: SHORTCUTS.calendar.workWeek,
+    week: SHORTCUTS.calendar.week,
+    month: SHORTCUTS.calendar.month,
+};
+
+/** One of the view switcher's buttons, with its shortcut in the tooltip. */
+function ViewButton({ view, current, onSelect }: { view: ViewType; current: ViewType; onSelect: (view: ViewType) => void }) {
+    const shortcut = VIEW_SHORTCUTS[view];
+    const hint = useShortcutProps(VIEW_LABELS[view], shortcut ?? SHORTCUTS.calendar.day, !!shortcut);
+    return (
+        <button
+            type="button"
+            onClick={() => onSelect(view)}
+            {...hint}
+            className={[
+                "px-3 h-7 text-sm rounded-sm whitespace-nowrap",
+                current === view ? "bg-primary text-white" : "hover:bg-surface-alt",
+                (view === "workWeek" || view === "split") && "hidden md:inline-block",
+            ]
+                .filter(Boolean)
+                .join(" ")}
+        >
+            {VIEW_LABELS[view]}
+        </button>
+    );
+}
 
 interface ModalState {
     occurrence: CalendarOccurrence | null;
@@ -254,6 +287,20 @@ function CalendarContent({ userUid }: { userUid?: string }) {
         setModal(null);
     }
 
+    // Keyboard shortcuts - the toolbar's own actions. (A dialog open - the event editor - silences them.)
+    useShortcut(SHORTCUTS.calendar.create, () => openNewEvent(), { enabled: !!mailboxUid && !!folderUid });
+    useShortcut(SHORTCUTS.calendar.today, goToday);
+    useShortcut(SHORTCUTS.calendar.previous, () => shiftView(-1));
+    useShortcut(SHORTCUTS.calendar.next, () => shiftView(1));
+    useShortcut(SHORTCUTS.calendar.day, () => setView("day"));
+    useShortcut(SHORTCUTS.calendar.workWeek, () => setView("workWeek"));
+    useShortcut(SHORTCUTS.calendar.week, () => setView("week"));
+    useShortcut(SHORTCUTS.calendar.month, () => setView("month"));
+    const newEventHint = useShortcutProps("New event", SHORTCUTS.calendar.create, !!mailboxUid && !!folderUid);
+    const previousHint = useShortcutProps("Previous", SHORTCUTS.calendar.previous);
+    const todayHint = useShortcutProps("Today", SHORTCUTS.calendar.today);
+    const nextHint = useShortcutProps("Next", SHORTCUTS.calendar.next);
+
     function handleSaved() {
         setModal(null);
         reload();
@@ -333,37 +380,24 @@ function CalendarContent({ userUid }: { userUid?: string }) {
                     >
                         <HiOutlineBars3 size={20} aria-hidden="true" />
                     </button>
-                    <Button type="button" onClick={() => openNewEvent()} className="!w-auto shrink-0">
+                    <Button type="button" onClick={() => openNewEvent()} className="!w-auto shrink-0" {...newEventHint}>
                         + New event
                     </Button>
                     <div className="flex items-center gap-1">
-                        <button type="button" onClick={() => shiftView(-1)} aria-label="Previous" className="w-7 h-7 text-sm rounded-sm hover:bg-surface-alt">
+                        <button type="button" onClick={() => shiftView(-1)} aria-label="Previous" {...previousHint} className="w-7 h-7 text-sm rounded-sm hover:bg-surface-alt">
                             &lsaquo;
                         </button>
-                        <button type="button" onClick={goToday} className="px-2 h-7 text-sm rounded-sm hover:bg-surface-alt">
+                        <button type="button" onClick={goToday} {...todayHint} className="px-2 h-7 text-sm rounded-sm hover:bg-surface-alt">
                             Today
                         </button>
-                        <button type="button" onClick={() => shiftView(1)} aria-label="Next" className="w-7 h-7 text-sm rounded-sm hover:bg-surface-alt">
+                        <button type="button" onClick={() => shiftView(1)} aria-label="Next" {...nextHint} className="w-7 h-7 text-sm rounded-sm hover:bg-surface-alt">
                             &rsaquo;
                         </button>
                     </div>
                     <h1 className="hidden md:block text-lg font-bold tracking-tight">{title}</h1>
                     <div className="ml-auto flex gap-1 overflow-x-auto">
                         {VIEW_TYPES.map((v) => (
-                            <button
-                                key={v}
-                                type="button"
-                                onClick={() => setView(v)}
-                                className={[
-                                    "px-3 h-7 text-sm rounded-sm whitespace-nowrap",
-                                    view === v ? "bg-primary text-white" : "hover:bg-surface-alt",
-                                    (v === "workWeek" || v === "split") && "hidden md:inline-block",
-                                ]
-                                    .filter(Boolean)
-                                    .join(" ")}
-                            >
-                                {VIEW_LABELS[v]}
-                            </button>
+                            <ViewButton key={v} view={v} current={view} onSelect={setView} />
                         ))}
                     </div>
                 </div>
@@ -436,3 +470,5 @@ function CalendarContent({ userUid }: { userUid?: string }) {
         </div>
     );
 }
+
+export default routedPage("/calendar", CalendarPage);