@rapidmx/web-client 0.9.0 → 0.10.0

package/dist/apps/shared/components/mail/layout/MailShell.js

@@ -3,19 +3,26 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { createContext, 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 { 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 AppShell from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import KeyEnrollmentGate from "../../layout/KeyEnrollmentGate.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
-import { useCompose } from "../compose/ComposeContext.js";
+import { prefetchComposeWindow, useCompose } from "../compose/ComposeContext.js";
 import LocalIndexLifecycle from "../../../search/LocalIndexLifecycle.js";
-import { NO_LIVE_UPDATES, useMailLiveUpdates } from "../../../mail/useMailLiveUpdates.js";
+import { NO_LIVE_UPDATES } from "../../../mail/useMailLiveUpdates.js";
+import { FOLDER_ORDER, MAILBOX_LIST_LIMIT, MailConnectionContext, useMailConnection } from "../../../mail/useMailConnection.js";
+import { badgeFor, badgeLabel, countOfFolder, inboxUnreadTotal, } from "../../../mail/folderCounts.js";
+import { useUnreadTitle } from "../../../mail/useUnreadTitle.js";
+import NewMailToasts from "../NewMailToasts.js";
+import { ariaKeyShortcuts, withHint } from "../../../keyboard/format.js";
+import { SHORTCUTS } from "../../../keyboard/keymap.js";
+import { useKeyEnvironment } from "../../../keyboard/ShortcutProvider.js";
+import { useShortcut } from "../../../keyboard/useShortcut.js";
 /** The well-known mail folder types an "aggregate" pseudo-folder can merge across every accessible
  * mailbox - a fixed, small set: `outbox` is deliberately excluded (transient per-mailbox send-queue
  * state, not a "merge across mailboxes" concept), and there's no aggregate concept for `calendar`/
@@ -25,11 +32,13 @@ export const AGGREGATE_FOLDER_TYPES = ["inbox", "sent_items", "drafts", "deleted
 function isAggregateFolderType(value) {
     return !!value && AGGREGATE_FOLDER_TYPES.includes(value);
 }
+const NO_TRACKER = { settle: () => undefined, revert: () => undefined };
 const MailShellContext = createContext({
     mailboxes: [],
     mailboxFolders: [],
     onFolderCreated: () => undefined,
     live: NO_LIVE_UPDATES,
+    trackMessageChange: () => NO_TRACKER,
 });
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
 export function useMailShell() {
@@ -44,15 +53,6 @@ const FOLDER_LABELS = {
     archive: "Archive",
     deleted_items: "Deleted Items",
 };
-/** Well-known folders sort first, in Gmail/Outlook's conventional order; anything else (incl. `user`) sorts after, alphabetically. */
-const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "junk", "archive", "deleted_items"];
-/**
- * A mailbox's `calendar`/`contacts`/`tasks`/`notes` folders back their own dedicated apps (see
- * `CalendarShell`/`ContactsShell`/`TasksShell`), not Mail — `listFolders()` returns every well-known
- * folder for the mailbox regardless of which app owns it, so Mail's own folder tree must filter down
- * to just the mail ones itself, or those other apps' folders leak into this sidebar.
- */
-const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
 function folderSortKey(folder) {
     const idx = FOLDER_ORDER.indexOf(folder.type);
     return idx === -1 ? FOLDER_ORDER.length : idx;
@@ -60,18 +60,23 @@ function folderSortKey(folder) {
 function sortedFoldersOf(folders) {
     return [...folders].sort((a, b) => folderSortKey(a) - folderSortKey(b) || a.name.localeCompare(b.name));
 }
-/** A folder's unread count: the refreshed one when live updates have read it since load, else the one it was listed with. */
-function unreadOf(folder, unreadCounts) {
-    return unreadCounts[folder.uid] ?? folder.unreadCount;
-}
-function aggregateUnreadCount(mailboxFolders, type, unreadCounts) {
-    return mailboxFolders.reduce((total, mf) => {
+/** The badge an "All Mailboxes" entry shows: the folders of that type, summed across every mailbox, under the same rules as a single folder's. */
+function aggregateBadge(mailboxFolders, type, counts) {
+    const sum = mailboxFolders.reduce((total, mf) => {
         const folder = mf.folders.find((f) => f.type === type);
-        return total + (folder ? unreadOf(folder, unreadCounts) : 0);
-    }, 0);
+        const count = folder ? countOfFolder(folder, counts) : { unread: 0, total: 0 };
+        return { unread: total.unread + count.unread, total: total.total + count.total };
+    }, { unread: 0, total: 0 });
+    return badgeFor(type, sum);
 }
-/** Page size of the one `listMailboxes()` call this shell makes. */
-export const MAILBOX_LIST_LIMIT = 100;
+/** A folder's badge: an accent pill with the unread count, or - for the folders that show how many they hold - plain muted text. */
+function FolderBadgeChip({ badge }) {
+    return (_jsxs("span", { className: [
+            "text-xs rounded-pill py-0.5 px-1.5",
+            badge.kind === "unread" ? "font-bold bg-primary/15 text-primary-dark" : "font-medium text-text-muted",
+        ].join(" "), children: [_jsx("span", { "aria-hidden": "true", children: badge.value }), _jsxs("span", { className: "sr-only", children: [" ", badgeLabel(badge)] })] }));
+}
+export { MAILBOX_LIST_LIMIT };
 /**
  * A separate component (not inlined into `MailShell`'s own render) so `useCompose()` resolves against
  * `ComposeProvider` correctly: that provider is rendered *inside* the `AppShell` that `MailShell` itself
@@ -80,12 +85,25 @@ export const MAILBOX_LIST_LIMIT = 100;
  * its own descendants creates. This button, rendered as part of `AppShell`'s `children`, sits correctly
  * inside that subtree.
  *
- * Opens with no mailbox: a fresh message defaults to the caller's own mailbox, and the compose window's
- * own From field is where the sender is chosen.
+ * Opens with the caller's own mailbox (the shell has already listed them), so the window can start on its
+ * signature, draft and encryption lookups straight away instead of first asking which mailbox that is; the
+ * compose window's own From field is where the sender is chosen. Fetches the window's code as the pointer or
+ * keyboard reaches the button, so the click finds it already here.
  */
-function ComposeButton() {
+function ComposeButton({ mailboxUid }) {
     const { openCompose } = useCompose();
-    return (_jsx("button", { type: "button", onClick: () => openCompose({}), className: "block text-center w-full py-2.5 px-4 rounded-sm font-semibold text-sm bg-primary text-white hover:bg-primary-dark", children: "Compose" }));
+    const env = useKeyEnvironment();
+    return (_jsx("button", { type: "button", title: withHint("Compose", SHORTCUTS.mail.create, env), "aria-keyshortcuts": ariaKeyShortcuts(SHORTCUTS.mail.create, env), onClick: () => openCompose({ mailboxUid }), onPointerEnter: prefetchComposeWindow, onFocus: prefetchComposeWindow, className: "block text-center w-full py-2.5 px-4 rounded-sm font-semibold text-sm bg-primary text-white hover:bg-primary-dark", children: "Compose" }));
+}
+/**
+ * Mail's keyboard shortcuts that don't belong to a list or a message: "New message". A component of its own for the reason `ComposeButton`
+ * is - `useCompose()` only resolves below `ComposeProvider`, i.e. inside the `AppShell` this shell renders - and mounted once, whatever number
+ * of Compose buttons (the sidebar, the folders drawer) are on screen. Opens the same window, for the same mailbox, as the button.
+ */
+function MailShortcuts({ mailboxUid }) {
+    const { openCompose } = useCompose();
+    useShortcut(SHORTCUTS.mail.create, () => openCompose({ mailboxUid }));
+    return null;
 }
 /**
  * Mail's own contextual sidebar (every accessible mailbox's own folder tree, plus a merged "All Mailboxes"
@@ -103,36 +121,33 @@ function ComposeButton() {
  * aggregate section) simultaneously, matching the shared-mailbox feature's own "display as a separate set
  * of folders" requirement.
  */
-export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
-    const [status, setStatus] = useState("checking");
-    const [error, setError] = useState(null);
-    const [mailboxes, setMailboxes] = useState([]);
-    const [mailboxFolders, setMailboxFolders] = useState([]);
-    const [foldersLoading, setFoldersLoading] = useState(true);
+export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
+    // The mailboxes, their folders and the live connection come from the persistent app frame when there is one (`AppChrome` owns them, so
+    // they survive Mail -> Calendar -> Mail and the push socket, pop-ups, counters and tab title work in every app). A page rendered
+    // outside the frame - a test, a plugin page - has no frame to ask, so this shell runs the same hook for itself, and renders the pop-ups.
+    const navigate = useNavigate();
+    const hosted = useContext(MailConnectionContext);
+    const own = useMailConnection({ userUid, enabled: !hosted, open: navigate });
+    const { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, live, folderCounts, notifications } = hosted ?? own;
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [requestedFolderUid, setRequestedFolderUid] = useState(null);
     const [requestedAggregateType, setRequestedAggregateType] = useState(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
+    // The selection lives in the URL, and the router (`AppRouter`) changes the URL without a page load when a folder link is
+    // clicked - so it is read from the router's location, which updates, rather than once from `window.location`. Still read
+    // in an effect, never during the first render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
     useEffect(() => {
-        const params = new URLSearchParams(window.location.search);
+        const params = new URLSearchParams(search);
         setRequestedMailboxUid(params.get("mailboxUid"));
         setRequestedFolderUid(params.get("folderUid"));
         setRequestedAggregateType(params.get("aggregate"));
-    }, []);
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
     useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        listMailboxes({ limit: MAILBOX_LIST_LIMIT })
-            .then((result) => {
-            setMailboxes(result);
-            setStatus("ready");
-        })
-            .catch((err) => {
-            setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
-            setStatus("error");
-        });
-    }, [userUid]);
+        setDrawerOpen(false);
+    }, [search]);
     const aggregateFolderType = isAggregateFolderType(requestedAggregateType)
         ? requestedAggregateType
         : undefined;
@@ -140,29 +155,6 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         ? undefined
         : (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
             mailboxes[0]?.uid;
-    // Fans out one listFolders() call per accessible mailbox in parallel - each call catches its own
-    // failure into an MailboxFolders.error rather than letting Promise.all reject, so one mailbox's fetch
-    // failure renders that section's own inline Alert instead of blanking out every other mailbox's
-    // folder tree.
-    useEffect(() => {
-        if (mailboxes.length === 0) {
-            // Deliberately leaves foldersLoading as-is: this also runs once before listMailboxes() has
-            // resolved, and clearing it here would briefly render an empty sidebar the moment mailboxes
-            // arrive, before their folders do. A genuinely mailbox-less caller gets MailboxProvisioning.
-            setMailboxFolders([]);
-            return;
-        }
-        setFoldersLoading(true);
-        void Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid)
-            .then((result) => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
-            .catch((err) => ({
-            mailbox,
-            folders: [],
-            error: err instanceof ApiRequestError ? err.message : "Could not load folders.",
-        }))))
-            .then(setMailboxFolders)
-            .finally(() => setFoldersLoading(false));
-    }, [mailboxes]);
     const selectedMailboxFolders = mailboxFolders.find((mf) => mf.mailbox.uid === mailboxUid)?.folders ?? [];
     const folderUid = aggregateFolderType
         ? undefined
@@ -175,23 +167,11 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
     // mailbox may still need that mailbox's own folder view opened directly to unlock/decrypt it.
     const defaultMailboxUid = mailboxes.find((mb) => mb.ownerUserUid === userUid)?.uid ?? mailboxes[0]?.uid;
     const activeMailboxUid = mailboxUid ?? defaultMailboxUid;
-    /** Files a newly created folder under its own mailbox, leaving every other mailbox's list untouched -
-     * and ignoring a type this sidebar doesn't list at all, the same filter the fetch above applies. */
-    const onFolderCreated = useCallback((folder) => {
-        if (!MAIL_FOLDER_TYPES.has(folder.type)) {
-            return;
-        }
-        setMailboxFolders((prev) => prev.map((entry) => 
-        // Not one already there: another client's create event can arrive after (or twice, or alongside) our own.
-        entry.mailbox.uid === folder.mailboxUid && !entry.folders.some((existing) => existing.uid === folder.uid)
-            ? { ...entry, folders: [...entry.folders, folder] }
-            : entry));
-    }, []);
-    // New mail without a reload: push events for every folder, plus a safety-net poll. Held in state beside `mailboxFolders`
-    // rather than written into it, so a refreshed unread count never looks like a change of folders to the list on screen
-    // (which reloads, and forgets its selection, whenever the folders do).
-    const { live, unreadCounts } = useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated });
-    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live]);
+    const counts = folderCounts.counts;
+    const trackMessageChange = folderCounts.track;
+    // `(3) Acme: Mail` in the tab strip while there is unread mail in an Inbox - kept by the frame when there is one.
+    useUnreadTitle(inboxUnreadTotal(mailboxFolders, counts), { enabled: !hosted });
+    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange]);
     // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else for a
     // mailbox-less caller to do here yet, so the icon rail/header/folder tree don't render at all. Checks
     // `mailboxes.length` directly (not `!mailboxUid`) since `mailboxUid` is legitimately undefined in
@@ -212,24 +192,24 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         // A function, not a plain JSX constant — it's rendered twice (desktop `<aside>` + mobile
         // `Drawer`), possibly *simultaneously* mounted (the aside is only CSS-hidden below `md`, not
         // unmounted).
-        const sidebarContent = () => (_jsxs(_Fragment, { children: [_jsx("div", { className: "p-3", children: _jsx(ComposeButton, {}) }), foldersLoading ? (_jsx("div", { className: "flex-1 overflow-y-auto px-3 pb-3", children: _jsx(SkeletonList, { count: 6, className: "pt-1" }) })) : (_jsxs("nav", { className: "flex-1 overflow-y-auto px-3 pb-3 flex flex-col gap-3", children: [mailboxes.length > 1 && (_jsxs("div", { children: [_jsx("div", { className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-1 px-2.5", children: "All Mailboxes" }), _jsx("div", { className: "flex flex-col gap-0.5", children: AGGREGATE_FOLDER_TYPES.map((type) => {
-                                        const unread = aggregateUnreadCount(mailboxFolders, type, unreadCounts);
+        const sidebarContent = () => (_jsxs(_Fragment, { children: [_jsx("div", { className: "p-3", children: _jsx(ComposeButton, { mailboxUid: defaultMailboxUid }) }), foldersLoading ? (_jsx("div", { className: "flex-1 overflow-y-auto px-3 pb-3", children: _jsx(SkeletonList, { count: 6, className: "pt-1" }) })) : (_jsxs("nav", { className: "flex-1 overflow-y-auto px-3 pb-3 flex flex-col gap-3", children: [mailboxes.length > 1 && (_jsxs("div", { children: [_jsx("div", { className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-1 px-2.5", children: "All Mailboxes" }), _jsx("div", { className: "flex flex-col gap-0.5", children: AGGREGATE_FOLDER_TYPES.map((type) => {
+                                        const badge = aggregateBadge(mailboxFolders, type, counts);
                                         return (_jsxs("a", { href: `/?aggregate=${encodeURIComponent(type)}`, className: [
                                                 "flex items-center justify-between text-sm rounded-sm py-1.5 px-2.5",
                                                 aggregateFolderType === type
                                                     ? "bg-primary/10 text-primary-dark font-semibold"
                                                     : "text-text hover:bg-surface-alt",
-                                            ].join(" "), children: [_jsx("span", { children: FOLDER_LABELS[type] }), unread > 0 && (_jsx("span", { className: "text-xs font-bold rounded-pill py-0.5 px-1.5 bg-surface-alt text-text-muted", children: unread }))] }, type));
+                                            ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[type] }), badge && _jsx(FolderBadgeChip, { badge: badge })] }, type));
                                     }) })] })), mailboxFolders.map(({ mailbox, folders, error: mailboxError }) => (_jsxs("div", { children: [_jsxs("div", { className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-1 px-2.5 truncate", children: [mailbox.displayName, mailbox.ownerUserUid ? "" : " (shared)"] }), mailboxError && (_jsx("div", { className: "px-2.5 pb-1", children: _jsx(Alert, { children: mailboxError }) })), _jsx("div", { className: "flex flex-col gap-0.5", children: sortedFoldersOf(folders).map((folder) => {
-                                        const unread = unreadOf(folder, unreadCounts);
+                                        const badge = badgeFor(folder.type, countOfFolder(folder, counts));
                                         return (_jsxs("a", { href: `/?mailboxUid=${encodeURIComponent(mailbox.uid)}&folderUid=${encodeURIComponent(folder.uid)}`, className: [
                                                 "flex items-center justify-between text-sm rounded-sm py-1.5 px-2.5",
                                                 folder.uid === folderUid
                                                     ? "bg-primary/10 text-primary-dark font-semibold"
                                                     : "text-text hover:bg-surface-alt",
-                                            ].join(" "), children: [_jsx("span", { children: FOLDER_LABELS[folder.type] ?? folder.name }), unread > 0 && (_jsx("span", { className: "text-xs font-bold rounded-pill py-0.5 px-1.5 bg-surface-alt text-text-muted", children: unread }))] }, folder.uid));
+                                            ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[folder.type] ?? folder.name }), badge && _jsx(FolderBadgeChip, { badge: badge })] }, folder.uid));
                                     }) })] }, mailbox.uid)))] }))] }));
-        inner = (_jsxs(_Fragment, { children: [_jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] })] }));
+        inner = (_jsxs(_Fragment, { children: [_jsx(MailShortcuts, { mailboxUid: defaultMailboxUid }), _jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] }), !hosted && (_jsx(NewMailToasts, { toasts: notifications.toasts, onDismiss: notifications.dismiss, offerDesktop: notifications.offerDesktop, onEnableDesktop: () => void notifications.enableDesktop(), onDeclineDesktop: notifications.declineDesktop }))] }));
     }
     // Wraps AppShell unconditionally, at a stable tree position regardless of whether mailboxUid has
     // resolved yet - KeyEnrollmentGate itself passes `children` through untouched until a real
@@ -251,5 +231,5 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         canProvision: !impersonating && activeMailbox?.ownerUserUid === userUid, children: [_jsx(LocalIndexLifecycle, { mailboxUid: activeMailboxUid, mailboxKeys: activeMailbox?.keys, folders: mailboxFolders.find((mf) => mf.mailbox.uid === activeMailboxUid)?.folders ?? [], 
                 // A full page may be truncated - pruning against it would delete indexes of accessible mailboxes
                 // beyond the limit, so it's only trusted as the complete list when it came back short.
-                accessibleMailboxUids: status === "ready" && mailboxes.length < MAILBOX_LIST_LIMIT ? mailboxes.map((mb) => mb.uid) : undefined }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner })] }));
+                accessibleMailboxUids: status === "ready" && mailboxes.length < MAILBOX_LIST_LIMIT ? mailboxes.map((mb) => mb.uid) : undefined }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner })] }));
 }

package/dist/apps/shared/components/mail/unreadStyle.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+/**
+ * How an unread message looks in every list of mail (the message list, the conversation list and its child rows, the
+ * thread pane's message headers, the folder badges), in one place so they can't drift apart. Modelled on Outlook:
+ *
+ * **Unread**: an accent bar down the row's left edge, a faint accent tint on the row, the sender and subject in bold and the
+ * date in the accent colour - plus a visually-hidden "Unread" in the row's text, so it never relies on colour alone.
+ *
+ * **Read**: normal weight, the sender and preview muted.
+ *
+ * **Hover, selected and focused** are their own states and look nothing like unread: hover is a plain grey (an accent tint on
+ * an unread row, so the row doesn't seem to lose its state), the open row has a stronger accent fill and an inset outline, and
+ * keyboard focus is a solid outline drawn inside the row.
+ *
+ * All of it is built from the theme's own tokens (`primary`, `text`, `text-muted`, `surface-alt`), so it follows light and
+ * dark mode and a branding stylesheet's palette.
+ */
+/** Whether a message is unread: `flags.read` isn't `true`. A message with no `read` flag at all counts as unread. */
+export declare function isUnread(message: Pick<Message, "flags"> | undefined | null): boolean;
+/**
+ * The classes of a row's outer element (`li`, or the row's wrapping `div`): the positioning the bar needs, and its one
+ * background - the open row's accent fill and inset outline, else an unread row's faint tint (a little stronger on hover),
+ * else a read row's plain grey hover. One element owns all of it so the states can't fight over the same property.
+ */
+export declare function rowClass(state: {
+    unread: boolean;
+    selected: boolean;
+}, extra?: string): string;
+/** Keyboard focus on a row's button: a solid outline drawn inside the row, unlike anything unread/selected/hover does. */
+export declare const ROW_FOCUS_CLASS = "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary";
+/** The sender line: bold and full-strength while unread, normal and muted once read. */
+export declare function senderClass(unread: boolean): string;
+/** The subject line. */
+export declare function subjectClass(unread: boolean): string;
+/** The date beside the sender: the accent colour while unread. */
+export declare function dateClass(unread: boolean): string;
+/** The accent bar down a row's left edge - only for an unread row. The row's outer element must be `relative`. */
+export declare function UnreadBar({ unread }: {
+    unread: boolean;
+}): React.JSX.Element | null;
+/** "Unread." in the row's text for assistive technology (and for anything that reads the DOM without styles). */
+export declare function UnreadLabel({ unread }: {
+    unread: boolean;
+}): React.JSX.Element | null;

package/dist/apps/shared/components/mail/unreadStyle.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * How an unread message looks in every list of mail (the message list, the conversation list and its child rows, the
+ * thread pane's message headers, the folder badges), in one place so they can't drift apart. Modelled on Outlook:
+ *
+ * **Unread**: an accent bar down the row's left edge, a faint accent tint on the row, the sender and subject in bold and the
+ * date in the accent colour - plus a visually-hidden "Unread" in the row's text, so it never relies on colour alone.
+ *
+ * **Read**: normal weight, the sender and preview muted.
+ *
+ * **Hover, selected and focused** are their own states and look nothing like unread: hover is a plain grey (an accent tint on
+ * an unread row, so the row doesn't seem to lose its state), the open row has a stronger accent fill and an inset outline, and
+ * keyboard focus is a solid outline drawn inside the row.
+ *
+ * All of it is built from the theme's own tokens (`primary`, `text`, `text-muted`, `surface-alt`), so it follows light and
+ * dark mode and a branding stylesheet's palette.
+ */
+/** Whether a message is unread: `flags.read` isn't `true`. A message with no `read` flag at all counts as unread. */
+export function isUnread(message) {
+    return !!message && message.flags.read !== true;
+}
+/**
+ * The classes of a row's outer element (`li`, or the row's wrapping `div`): the positioning the bar needs, and its one
+ * background - the open row's accent fill and inset outline, else an unread row's faint tint (a little stronger on hover),
+ * else a read row's plain grey hover. One element owns all of it so the states can't fight over the same property.
+ */
+export function rowClass(state, extra = "") {
+    return [
+        "relative border-b border-border",
+        state.selected
+            ? "bg-primary/20 ring-1 ring-inset ring-primary/50"
+            : state.unread
+                ? "bg-primary/[0.07] hover:bg-primary/10"
+                : "hover:bg-surface-alt",
+        extra,
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+/** Keyboard focus on a row's button: a solid outline drawn inside the row, unlike anything unread/selected/hover does. */
+export const ROW_FOCUS_CLASS = "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary";
+/** The sender line: bold and full-strength while unread, normal and muted once read. */
+export function senderClass(unread) {
+    return unread ? "font-bold text-text" : "font-normal text-text-muted";
+}
+/** The subject line. */
+export function subjectClass(unread) {
+    return unread ? "font-semibold text-text" : "font-normal text-text";
+}
+/** The date beside the sender: the accent colour while unread. */
+export function dateClass(unread) {
+    return unread ? "font-semibold text-primary-dark" : "font-normal text-text-muted";
+}
+/** The accent bar down a row's left edge - only for an unread row. The row's outer element must be `relative`. */
+export function UnreadBar({ unread }) {
+    return unread ? _jsx("span", { "aria-hidden": "true", "data-unread-bar": true, className: "absolute inset-y-0 left-0 w-1 bg-primary" }) : null;
+}
+/** "Unread." in the row's text for assistive technology (and for anything that reads the DOM without styles). */
+export function UnreadLabel({ unread }) {
+    return unread ? _jsx("span", { className: "sr-only", children: "Unread. " }) : null;
+}

package/dist/apps/shared/components/settings/layout/SettingsShell.d.ts

@@ -38,4 +38,4 @@ export declare function useSettingsShell(): SettingsShellContextValue;
  * settings sections (`SETTINGS_SECTIONS`) — full-page navigation between them, same as the top-level
  * app rail, since this framework has no client-side router.
  */
-export default function SettingsShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<SettingsShellProps>): React.JSX.Element;
+export default function SettingsShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }: PropsWithChildren<SettingsShellProps>): React.JSX.Element;

package/dist/apps/shared/components/settings/layout/SettingsShell.js

@@ -11,6 +11,7 @@ import { 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 AppShell from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { mergePluginNavItems } from "../../../plugins/pluginNav.js";
 /** Every settings section with its own sidebar entry. */
@@ -46,15 +47,24 @@ export function useSettingsShell() {
  * settings sections (`SETTINGS_SECTIONS`) — full-page navigation between them, same as the top-level
  * app rail, since this framework has no client-side router.
  */
-export default function SettingsShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export default function SettingsShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
     useEffect(() => {
         if (!userUid) {
             return;
@@ -94,7 +104,7 @@ export default function SettingsShell({ active, userUid, authServerUrl, imperson
                                 // `SettingsShellProps.active`), but a plugin page's section is missing when the
                                 // server didn't send its nav item, so that falls back to the current path.
                                 const href = sections.find((s) => s.id === active)?.href ?? window.location.pathname;
-                                window.location.href = `${href}?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                navigate(`${href}?mailboxUid=${encodeURIComponent(e.target.value)}`);
                             }, children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) })] })), _jsx("nav", { "aria-label": "Settings sections", className: "flex flex-col gap-0.5", children: sections.map((section) => (_jsx("a", { 
                         // `inner` (this whole branch) is only ever computed once `status === "ready"`
                         // and `mailboxUid` has already resolved truthy — a falsy `mailboxUid` returns
@@ -109,5 +119,5 @@ export default function SettingsShell({ active, userUid, authServerUrl, imperson
                         ].join(" "), children: section.label }, section.id))) })] }));
         inner = (_jsxs(_Fragment, { children: [_jsx("aside", { className: "hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Settings", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [_jsx("button", { type: "button", className: "md:hidden m-3 self-start w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open settings menu", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(SettingsShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
-    return (_jsx(AppShell, { active: "settings", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner }));
+    return (_jsx(AppShell, { active: "settings", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner }));
 }

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

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

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

@@ -11,6 +11,7 @@ import { listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.j
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 const TasksShellContext = createContext({ mailboxes: [] });
 /** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
@@ -24,7 +25,7 @@ export function useTasksShell() {
  * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
  * grow its own app-specific controls later without threading extra props through a shared one.
  */
-export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export default function TasksShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
@@ -32,9 +33,18 @@ export default function TasksShell({ userUid, authServerUrl, impersonating, impe
     const [folderError, setFolderError] = useState(null);
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
     useEffect(() => {
         if (!userUid) {
             return;
@@ -84,9 +94,9 @@ export default function TasksShell({ userUid, authServerUrl, impersonating, impe
         // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
         // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
         const sidebarContent = (idPrefix) => (_jsxs(_Fragment, { children: [mailboxes.length > 1 && (_jsxs("div", { children: [_jsx("label", { className: "block text-xs font-bold uppercase tracking-wide text-text-muted mb-1", htmlFor: `${idPrefix}-tasks-mailbox-switcher`, children: "Mailbox" }), _jsx("select", { id: `${idPrefix}-tasks-mailbox-switcher`, className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: mailboxUid, onChange: (e) => {
-                                window.location.href = `/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                navigate(`/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`);
                             }, children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) })] })), folderError && _jsx(Alert, { children: folderError })] }));
         inner = (_jsxs(_Fragment, { children: [_jsx("aside", { className: "hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Mailbox", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [(mailboxes.length > 1 || folderError) && (_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open mailbox switcher", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) })), _jsx(TasksShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
-    return (_jsx(AppShell, { active: "tasks", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner }));
+    return (_jsx(AppShell, { active: "tasks", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner }));
 }

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

@@ -0,0 +1,14 @@
+export interface GlobalShortcutsProps {
+    /** auth-server's base URL - "Go to Account" is offered only when it is set. */
+    authServerUrl?: string;
+    /** Opens the keyboard shortcuts dialog, or closes it if it is open. */
+    onToggleHelp: () => void;
+}
+/**
+ * The shortcuts that work in every view: the "Go to ..." navigation set and the keyboard help. Mounted once by `AppChrome`, next to the
+ * `ShortcutProvider`, so it works from Settings and every app alike. Renders nothing.
+ *
+ * In-app places go through the client-side router (`useNavigate()`); Account is another origin, so it is a plain navigation. Asking for the
+ * page you are already on does nothing - but the key is still taken, so the browser doesn't act on it either.
+ */
+export declare function GlobalShortcuts({ authServerUrl, onToggleHelp }: GlobalShortcutsProps): null;

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

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

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

@@ -0,0 +1,20 @@
+import React, { PropsWithChildren } from "react";
+import { KeyEnvironment } from "./platform.js";
+import { Registration, ShortcutRegistry } from "./registry.js";
+/**
+ * The web client's one keyboard layer. Mounted once, by `AppChrome` (the frame that stays mounted as the router swaps pages), so shortcuts
+ * work in every view - mail, calendar, contacts, tasks, settings - and a page change only changes which handlers are registered.
+ *
+ * One `keydown` listener on `document` (bubbling, so what a widget handles itself and `preventDefault()`s is left alone) hands each key to
+ * `dispatchKeyEvent()`. Views claim keys with `useShortcut()`. Outside a provider - an admin page, a component rendered on its own - that
+ * hook does nothing.
+ *
+ * The platform (macOS, the desktop client) is read after mount, never during render, so the server render and hydration agree.
+ */
+export declare function ShortcutProvider({ children }: PropsWithChildren): React.JSX.Element;
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export declare function useShortcutRegistry(): ShortcutRegistry | null;
+/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
+export declare function useKeyEnvironment(): KeyEnvironment;
+/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
+export declare function useRegisteredShortcuts(): readonly Registration[];