@rapidmx/web-client 0.10.0 → 0.12.0

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

@@ -0,0 +1,164 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { KeyboardEvent, ReactNode, useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { ResolvedPrincipal } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+
+export interface PrincipalResolverProps {
+    /** Resolves what was typed - a mailbox address, an auth-server username or e-mail alias, or a user uid - to
+     * the one person it names, exact match only. Rejects (typically with an `ApiRequestError`) for nobody. */
+    resolve: (principal: string) => Promise<ResolvedPrincipal>;
+    /** Called once the caller confirms the resolved person is the right one. The box is cleared once this
+     * resolves - throw (or reject) to keep the person on screen and show an error instead. */
+    onResolved: (person: ResolvedPrincipal) => void | Promise<void>;
+    /** Text put in the box to start with - a stored entry being replaced, say - looked up automatically on mount. */
+    initialPrincipal?: string;
+    /** What the box asks for. */
+    placeholder: string;
+    /** The box's accessible name. */
+    ariaLabel: string;
+    /** Extra controls rendered between the text box and the Find button (e.g. a role selector). */
+    children?: ReactNode;
+    /** The confirm button's label (e.g. "Grant", "Use this owner"). */
+    confirmLabel: string;
+    /** What the confirmation row says once a person is found - e.g. "Share with X as Y?". */
+    describeConfirm: (person: ResolvedPrincipal) => ReactNode;
+    /** Shown if `onResolved` rejects, unless it was an `ApiRequestError` (then its own message is shown). */
+    confirmErrorMessage: string;
+    /** Shown as a Cancel button next to the box when set (replacing an entry). */
+    onCancel?: () => void;
+}
+
+/** Who a resolved person is, for a person to check before confirming: their name and address, else their uid. */
+export function describePerson(person: ResolvedPrincipal): string {
+    if (person.displayName && person.address) return `${person.displayName} <${person.address}>`;
+    return person.displayName ?? person.address ?? `user ${person.userUid}`;
+}
+
+/**
+ * "Who?" - anywhere a person is assigned by typed identifier rather than picked from an already-loaded list. What
+ * is typed is RESOLVED by the server (`resolve`) to the person it names before anything is saved, and the person is
+ * shown (name and address) for the caller to confirm; only `onResolved` ever sees the resolved, verified person -
+ * never the free text. This is deliberately exact-match, type-then-confirm - never a live/fuzzy search-as-you-type
+ * autocomplete, which would let anyone with access to the field enumerate the user directory by partial name.
+ *
+ * Parameterized entirely by `resolve`/`onResolved` (and the wording props) so every caller - mailbox sharing
+ * (`PrincipalPicker`, a thin wrapper around this component), mailbox ownership, escrow-scope holders, ... - reuses
+ * the same resolve-then-confirm UX and privacy posture rather than each reimplementing it.
+ *
+ * Deliberately renders no `<form>` of its own (Enter-to-find is wired up by hand instead, see `handleKeyDown()`) -
+ * some callers (`MailboxCreateForm`) use this as one field of their own, larger `<form>`, and a nested `<form>` is
+ * invalid HTML that real browsers mis-handle (an inner Enter keypress can submit the wrong one).
+ */
+export default function PrincipalResolver({
+    resolve,
+    onResolved,
+    initialPrincipal,
+    placeholder,
+    ariaLabel,
+    children,
+    confirmLabel,
+    describeConfirm,
+    confirmErrorMessage,
+    onCancel,
+}: PrincipalResolverProps) {
+    const [typed, setTyped] = useState(initialPrincipal ?? "");
+    const [person, setPerson] = useState<ResolvedPrincipal | null>(null);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    // A stored entry being replaced is looked up straight away, so its person is shown without a click.
+    useEffect(() => {
+        if (initialPrincipal) {
+            void find(initialPrincipal);
+        }
+    }, [initialPrincipal]);
+
+    async function find(principal: string) {
+        setBusy(true);
+        setError(null);
+        setPerson(null);
+        try {
+            setPerson(await resolve(principal));
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not look that person up.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    function submitFind() {
+        const principal = typed.trim();
+        if (principal) {
+            void find(principal);
+        }
+    }
+
+    /** Enter in the text box finds, same as clicking the button - handled here (not a native `<form>` submit,
+     * see this component's own doc comment on why) so it works whether or not a caller nests this inside one of
+     * their own forms (`MailboxCreateForm` does). */
+    function handleKeyDown(e: KeyboardEvent<HTMLInputElement>) {
+        if (e.key === "Enter") {
+            // Stops the keystroke from also submitting an ANCESTOR `<form>` this component happens to be nested in.
+            e.preventDefault();
+            submitFind();
+        }
+    }
+
+    // Only reachable from the confirm button, which only renders once `person` is set.
+    async function handleConfirm() {
+        setBusy(true);
+        setError(null);
+        try {
+            await onResolved(person!);
+            setTyped("");
+            setPerson(null);
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : confirmErrorMessage);
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    return (
+        <div className="flex flex-col gap-2">
+            {error && <Alert>{error}</Alert>}
+            <div className="flex gap-2">
+                <input
+                    type="text"
+                    aria-label={ariaLabel}
+                    placeholder={placeholder}
+                    className="flex-1 text-sm border border-border rounded-sm py-1.5 px-2 bg-surface text-text"
+                    value={typed}
+                    onChange={(e) => {
+                        setTyped(e.target.value);
+                        setPerson(null);
+                    }}
+                    onKeyDown={handleKeyDown}
+                    disabled={busy}
+                />
+                {children}
+                <Button type="button" variant="secondary" loading={busy && !person} disabled={busy} className="!w-auto" onClick={submitFind}>
+                    Find
+                </Button>
+                {onCancel && (
+                    <Button type="button" variant="text" className="!w-auto" onClick={onCancel}>
+                        Cancel
+                    </Button>
+                )}
+            </div>
+            {person && (
+                <div className="flex items-center justify-between gap-3 text-sm py-2 px-3 border border-border rounded-sm">
+                    <span>{describeConfirm(person)}</span>
+                    <Button type="button" loading={busy} disabled={busy} className="!w-auto" onClick={() => void handleConfirm()}>
+                        {confirmLabel}
+                    </Button>
+                </div>
+            )}
+        </div>
+    );
+}

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

@@ -7,6 +7,7 @@ import { HiOutlineBars3 } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { Task, TaskList, createTaskList, listTaskLists } from "@rapidmx/react-shared/tasks/tasksApi.js";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
 
 export type TasksView =
     | { type: "myDay" }
@@ -102,7 +103,8 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
             setNewListName("");
             setAddingList(false);
         } catch (err) {
-            setListsError(err instanceof ApiRequestError ? err.message : "Could not create this list.");
+            // A pop-up: `listsError` is only the lists' own load failure.
+            notifyApiError(err, "Couldn't create the list");
         }
     }
 
@@ -184,13 +186,13 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
         <>
             <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"
+                className="lg:hidden m-3 mb-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
                 aria-label="Open tasks menu"
                 onClick={() => setDrawerOpen(true)}
             >
                 <HiOutlineBars3 size={20} aria-hidden="true" />
             </button>
-            <nav aria-label="Tasks" className="hidden md:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto">
+            <nav aria-label="Tasks" className="hidden lg:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto">
                 {navContent("desktop")}
             </nav>
             <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Tasks">

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

@@ -171,19 +171,23 @@ export default function TasksShell({
             </>
         );
 
+        // With a single mailbox and no error this column would be empty: no 224 px of nothing beside the tasks' own menu.
+        const hasSidebar = mailboxes.length > 1 || !!folderError;
         inner = (
             <>
-                <aside className="hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
-                    {sidebarContent("desktop")}
-                </aside>
+                {hasSidebar && (
+                    <aside className="hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
+                        {sidebarContent("desktop")}
+                    </aside>
+                )}
                 <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Mailbox">
                     <div className="flex flex-col gap-3">{sidebarContent("mobile")}</div>
                 </Drawer>
                 <main className="flex-1 min-w-0 flex flex-col">
-                    {(mailboxes.length > 1 || folderError) && (
+                    {hasSidebar && (
                         <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"
+                            className="lg:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
                             aria-label="Open mailbox switcher"
                             onClick={() => setDrawerOpen(true)}
                         >

package/apps/shared/mail/folderCounts.ts

@@ -132,10 +132,10 @@ export interface FolderCounts {
  * Holds the folder counts overlay for `MailShell`. `folders` is every folder the sidebar lists (the overlay starts from what
  * each was loaded with); `mailboxes` is whose folders to read back. The overlay starts again whenever `mailboxes` does.
  */
-export function useFolderCounts(mailboxes: Mailbox[], folders: Folder[]): FolderCounts {
+export function useFolderCounts(mailboxes: Mailbox[], folders: Folder[], onFoldersListed?: (folders: Folder[]) => void): FolderCounts {
     const [counts, setCounts] = useState<Record<string, FolderCount>>({});
-    const latestRef = useRef({ mailboxes, folders });
-    latestRef.current = { mailboxes, folders };
+    const latestRef = useRef({ mailboxes, folders, onFoldersListed });
+    latestRef.current = { mailboxes, folders, onFoldersListed };
     // Bumped by every change of the overlay this page makes, so a read that started before one can tell it is out of date.
     const changesRef = useRef(0);
     const inFlightRef = useRef(0);
@@ -189,6 +189,12 @@ export function useFolderCounts(mailboxes: Mailbox[], folders: Folder[]): Folder
         if (stoppedRef.current || run !== runRef.current) {
             return;
         }
+        // Whatever the counts' fate below, these are the mailboxes' folders as they are: a folder the sidebar does not have yet is filed now.
+        for (const list of results) {
+            if (list) {
+                latestRef.current.onFoldersListed?.(list);
+            }
+        }
         if (inFlightRef.current > 0 || changesRef.current !== startedAt) {
             // A change of this page's own began or ended while that was being read, so it may predate it: read again.
             refresh();

package/apps/shared/mail/folderTree.ts

@@ -0,0 +1,143 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+
+/**
+ * The sidebar's order of a mailbox's well-known folders; anything else (`user`) follows, alphabetically. Also the order push channels are asked
+ * for (`pushChannelsFor()`), so when the server's channel cap bites it is the folders lowest in this list that go without live updates.
+ */
+export const FOLDER_ORDER = ["inbox", "drafts", "outbox", "sent_items", "deleted_items", "junk", "archive"];
+
+/**
+ * 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 filters down
+ * to just the mail ones itself, or those other apps' folders leak into its sidebar.
+ */
+export const MAIL_FOLDER_TYPES = new Set([...FOLDER_ORDER, "user"]);
+
+/** The well-known folders the server creates lazily around a first send: what the sidebar shows a placeholder for while a message is on its way. */
+export const SEND_FOLDER_TYPES = ["outbox", "sent_items"] as const;
+
+export function isMailFolder(folder: { type: string }): boolean {
+    return MAIL_FOLDER_TYPES.has(folder.type);
+}
+
+function sortKey(type: string): number {
+    const index = FOLDER_ORDER.indexOf(type);
+    return index === -1 ? FOLDER_ORDER.length : index;
+}
+
+/** Well-known folders in `FOLDER_ORDER`, then the rest by name. A new array; the input is left alone. */
+export function sortFolders(folders: Folder[]): Folder[] {
+    return [...folders].sort((a, b) => sortKey(a.type) - sortKey(b.type) || a.name.localeCompare(b.name));
+}
+
+/** What a sidebar row is: a folder that exists, or (`placeholder`) one that is expected to but has not arrived yet. */
+export type FolderRow = { kind: "folder"; folder: Folder } | { kind: "placeholder"; type: string };
+
+/**
+ * The rows of one mailbox's sidebar section, in order: every folder that exists, and - while `sending` messages are on their way and the
+ * server has not made the folder yet - a placeholder for each of the Outbox and Sent Items that is missing. The one place a folder that has not
+ * arrived is drawn, so it can never appear twice: the moment the real folder is in `folders` its placeholder is not built.
+ */
+export function folderRows(folders: Folder[], sending: number): FolderRow[] {
+    const rows: FolderRow[] = sortFolders(folders).map((folder) => ({ kind: "folder", folder }));
+    if (sending > 0) {
+        for (const type of SEND_FOLDER_TYPES) {
+            if (!folders.some((folder) => folder.type === type)) {
+                rows.push({ kind: "placeholder", type });
+            }
+        }
+        rows.sort((a, b) => sortKey(rowType(a)) - sortKey(rowType(b)));
+    }
+    return rows;
+}
+
+function rowType(row: FolderRow): string {
+    return row.kind === "folder" ? row.folder.type : row.type;
+}
+
+/** What a folder can be changed to by an event or a refetch: everything about it except the counts, which the counts overlay owns. */
+export type FolderChange = Partial<Pick<Folder, "name" | "type" | "parentFolderUid" | "color">> & { uid: string; mailboxUid?: string };
+
+const CHANGEABLE = ["name", "type", "parentFolderUid", "color"] as const;
+
+/**
+ * Files `folder` in the tree: added under its mailbox when unknown (a type Mail does not list is ignored), else its name, type, parent and
+ * colour brought up to date (a folder that became a type Mail does not list leaves the tree). Returns `entries` itself - the same array - when
+ * nothing changed, because everything on screen that depends on the tree starts over when it is a new one.
+ */
+export function upsertFolder(entries: MailboxFolders[], folder: Folder | FolderChange): MailboxFolders[] {
+    let changed = false;
+    const next = entries.map((entry) => {
+        const existing = entry.folders.find((f) => f.uid === folder.uid);
+        if (!existing) {
+            // Only a whole folder can be added: an update for one that is not known has nothing to add it with (the refetch it causes will).
+            if (entry.mailbox.uid !== folder.mailboxUid || !isFullFolder(folder) || !isMailFolder(folder)) {
+                return entry;
+            }
+            // A well-known folder is one per mailbox - the server treats the oldest as the real one - so a second of the same type (made by a client that did
+            // not know it existed) is not a second row: the older of the two is the one shown.
+            const sameType = folder.type === "user" ? undefined : entry.folders.find((f) => f.type === folder.type);
+            if (sameType) {
+                if (!isOlder(folder, sameType)) {
+                    return entry;
+                }
+                changed = true;
+                return { ...entry, folders: entry.folders.map((f) => (f === sameType ? folder : f)) };
+            }
+            changed = true;
+            return { ...entry, folders: [...entry.folders, folder] };
+        }
+        const patch: Partial<Folder> = {};
+        for (const key of CHANGEABLE) {
+            if (key in folder && folder[key] !== undefined && folder[key] !== existing[key]) {
+                (patch as Record<string, unknown>)[key] = folder[key];
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            return entry;
+        }
+        changed = true;
+        const updated = { ...existing, ...patch };
+        return { ...entry, folders: isMailFolder(updated) ? entry.folders.map((f) => (f === existing ? updated : f)) : entry.folders.filter((f) => f !== existing) };
+    });
+    return changed ? next : entries;
+}
+
+function isFullFolder(folder: Folder | FolderChange): folder is Folder {
+    return typeof folder.name === "string" && typeof folder.type === "string";
+}
+
+/** Whether `a` was created before `b`: only when both say when. */
+function isOlder(a: Folder, b: Folder): boolean {
+    // (A folder from the network may lack the date: `Date.parse(undefined)` is NaN, which is "cannot tell".)
+    const first = Date.parse(a.dateCreated);
+    const second = Date.parse(b.dateCreated);
+    return Number.isFinite(first) && Number.isFinite(second) && first < second;
+}
+
+/** Takes a deleted folder out of the tree. The same array when it was not in it. */
+export function removeFolder(entries: MailboxFolders[], folderUid: string): MailboxFolders[] {
+    if (!entries.some((entry) => entry.folders.some((folder) => folder.uid === folderUid))) {
+        return entries;
+    }
+    return entries.map((entry) => (entry.folders.some((folder) => folder.uid === folderUid) ? { ...entry, folders: entry.folders.filter((folder) => folder.uid !== folderUid) } : entry));
+}
+
+/**
+ * Brings one mailbox's part of the tree up to date with a listing the server just gave (`listFolders()`): folders it has that the tree lacks
+ * are added, changed names and types are taken. Nothing is removed - a listing that began before a folder was created here would take it out
+ * again, and deletions arrive as events - and the counts are not touched (see `useFolderCounts()`). The same array when there is nothing to do.
+ */
+export function reconcileFolders(entries: MailboxFolders[], listed: Folder[]): MailboxFolders[] {
+    return listed.reduce((tree, folder) => upsertFolder(tree, folder), entries);
+}
+
+/** Every folder uid in the tree. */
+export function knownFolderUids(entries: MailboxFolders[]): Set<string> {
+    return new Set(entries.flatMap((entry) => entry.folders.map((folder) => folder.uid)));
+}

package/apps/shared/mail/outbox/UnlockBridge.tsx

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { useUnlockPrompt } from "../../components/layout/UnlockPromptProvider.js";
+import { registerUnlockOpener } from "./composeBridge.js";
+
+/**
+ * Lets code with no React context - a pop-up's "Unlock" action - open the app's one unlock prompt (`UnlockPromptProvider`). Renders nothing;
+ * mounted once, inside the provider it reaches.
+ */
+export default function UnlockBridge(): null {
+    const { requestUnlock } = useUnlockPrompt();
+    useEffect(
+        () =>
+            registerUnlockOpener(async (mailboxUid, keys) => {
+                await requestUnlock(mailboxUid, keys);
+            }),
+        [requestUnlock],
+    );
+    return null;
+}

package/apps/shared/mail/outbox/composeBridge.ts

@@ -0,0 +1,69 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Attachment, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+
+/**
+ * A compose window to re-open around a message that was already composed: a failed send's "Open draft". The message keeps its uid - the
+ * server draft it was assembled into - and everything the sender had typed comes back exactly as it was, including what could not have
+ * been read back from the server (the plain text of a message that was encrypted before it was stored).
+ */
+export interface ResumeCompose {
+    /** The server draft the window continues - it must be in Drafts (a message that is in Outbox is moved back first). */
+    draft: Message;
+    mailboxUid: string;
+    to: string;
+    cc: string;
+    bcc: string;
+    subject: string;
+    html: string;
+    attachments: Attachment[];
+    requestReceipt: boolean;
+    signEnabled: boolean;
+    encryptRequested: boolean;
+}
+
+/** What the app frame's compose provider offers to code that has no React context (a pop-up's action, a push-event handler). */
+export interface ComposeOpenerInput {
+    mailboxUid?: string;
+    resume?: ResumeCompose;
+}
+
+let opener: ((input: ComposeOpenerInput) => void) | undefined;
+let unlocker: ((mailboxUid: string, keys: PublicKey[]) => Promise<void>) | undefined;
+
+/** Registered by `ComposeProvider`; returns the function that unregisters it. */
+export function registerComposeOpener(open: (input: ComposeOpenerInput) => void): () => void {
+    opener = open;
+    return () => {
+        if (opener === open) {
+            opener = undefined;
+        }
+    };
+}
+
+/** Opens a compose window from outside React. `false` when no compose provider is mounted (nothing was opened). */
+export function openComposeFromOutside(input: ComposeOpenerInput): boolean {
+    if (!opener) {
+        return false;
+    }
+    opener(input);
+    return true;
+}
+
+/** Registered by the unlock prompt's owner; returns the function that unregisters it. */
+export function registerUnlockOpener(unlock: (mailboxUid: string, keys: PublicKey[]) => Promise<void>): () => void {
+    unlocker = unlock;
+    return () => {
+        if (unlocker === unlock) {
+            unlocker = undefined;
+        }
+    };
+}
+
+/** Opens the existing unlock prompt from outside React. Resolves once the keys are unlocked; rejects when the user dismissed it (or there is no prompt). */
+export function requestUnlockFromOutside(mailboxUid: string, keys: PublicKey[]): Promise<void> {
+    return unlocker ? unlocker(mailboxUid, keys) : Promise.reject(new Error("No unlock prompt is available."));
+}

package/apps/shared/mail/outbox/outboxState.ts

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Message } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/**
+ * What a message in Outbox is doing, read from the fields the server keeps on it (`scheduledSend*`):
+ *
+ * These are the server's own definitions (`@rapidmx/restapi`'s background send):
+ *
+ * - `sending`: a lease (`scheduledSendLeaseExpiresAt`) is running, or a *due* `scheduledSendTime` with no failed attempts yet - a message
+ * queued for the server's worker (a background send is queued as an ordinary due message, `scheduledSendTime` = when it was queued);
+ * - `retrying`: `scheduledSendAttempts > 0` with a later `scheduledSendTime` (or a lease on one): a delivery attempt failed and the server
+ * will try again;
+ * - `failed`: `scheduledSendError` set and no `scheduledSendTime` - the server gave up; it stays in Outbox, waiting for the user to retry
+ * (the same send call again) or to open it (back to Drafts is allowed, it is not in flight);
+ * - `scheduled`: a send-later message whose time has not come.
+ *
+ * "Due" is judged against the message's own `dateModified` as well as the clock: a background send's `scheduledSendTime` is set by the server
+ * at the moment it queued the message, so a browser whose clock runs behind must not read it as a send scheduled for the future.
+ */
+export type OutboxItemState = "sending" | "retrying" | "failed" | "scheduled";
+
+export interface OutboxItemStatus {
+    state: OutboxItemState;
+    /** Failed delivery attempts so far (`retrying`). */
+    attempts: number;
+    /** Why it failed (`failed`). */
+    error?: string;
+    /** When it will be sent or tried again (`scheduled`, `retrying`), epoch ms. */
+    at?: number;
+}
+
+/** A `scheduledSendTime` this close to the message's last modification was set by the server as "now": a due message, not a scheduled one. */
+export const DUE_SLACK_MS = 2_000;
+
+export function outboxItemStatus(message: Message, now: number = Date.now()): OutboxItemStatus {
+    const attempts = message.scheduledSendAttempts ?? 0;
+    const lease = message.scheduledSendLeaseExpiresAt ? Date.parse(message.scheduledSendLeaseExpiresAt) : NaN;
+    const at = message.scheduledSendTime ? Date.parse(message.scheduledSendTime) : NaN;
+    if (message.scheduledSendError && !message.scheduledSendTime && !(lease > now)) {
+        return { state: "failed", attempts, error: message.scheduledSendError };
+    }
+    if (lease > now) {
+        return { state: attempts > 0 ? "retrying" : "sending", attempts };
+    }
+    if (attempts > 0) {
+        return { state: "retrying", attempts, at: Number.isNaN(at) ? undefined : at };
+    }
+    const modified = message.dateModified ? Date.parse(message.dateModified) : NaN;
+    const dueWhenModified = at - modified <= DUE_SLACK_MS;
+    if (at > now && !dueWhenModified) {
+        return { state: "scheduled", attempts, at };
+    }
+    return { state: "sending", attempts };
+}
+
+/** How many messages of each kind an Outbox folder holds. */
+export interface OutboxFolderStatus {
+    sending: number;
+    retrying: number;
+    failed: number;
+    scheduled: number;
+}
+
+export const EMPTY_OUTBOX_STATUS: OutboxFolderStatus = { sending: 0, retrying: 0, failed: 0, scheduled: 0 };
+
+export function summarizeOutbox(messages: Message[], now: number = Date.now()): OutboxFolderStatus {
+    const status = { ...EMPTY_OUTBOX_STATUS };
+    for (const message of messages) {
+        status[outboxItemStatus(message, now).state] += 1;
+    }
+    return status;
+}
+
+/** The text a screen reader gets for an Outbox count, and the tooltip: "2 messages sending", "3 messages, 1 failed". */
+export function outboxLabel(total: number, status: OutboxFolderStatus | undefined, pendingHere: number): string {
+    const noun = `${total} ${total === 1 ? "message" : "messages"}`;
+    if (status && status.failed > 0) {
+        return `${noun}, ${status.failed} failed`;
+    }
+    const inFlight = (status ? status.sending + status.retrying : 0) + pendingHere;
+    if (inFlight > 0) {
+        return `${noun} sending`;
+    }
+    return status && status.scheduled > 0 && status.scheduled === total ? `${noun} scheduled` : noun;
+}