@rapidmx/web-client 0.9.0 → 0.11.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/notifications/NotificationCenter.tsx

@@ -0,0 +1,215 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect } from "react";
+import type { IconType } from "react-icons";
+import {
+    HiOutlineCheckCircle,
+    HiOutlineEnvelope,
+    HiOutlineExclamationCircle,
+    HiOutlineExclamationTriangle,
+    HiOutlineInformationCircle,
+    HiOutlineXMark,
+} from "react-icons/hi2";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
+import { NotificationAction, NotificationKind, NotificationView, dismiss, setAllPaused, setPaused } from "./store.js";
+import { useNotifications } from "./useNotifications.js";
+import { useSystemErrorNotifications } from "./systemErrors.js";
+
+const KIND_STYLE: Record<NotificationKind, { border: string; icon: string; Icon: IconType; label: string }> = {
+    mail: { border: "border-l-primary", icon: "text-primary-dark", Icon: HiOutlineEnvelope, label: "New message" },
+    info: { border: "border-l-primary", icon: "text-primary-dark", Icon: HiOutlineInformationCircle, label: "Information" },
+    success: { border: "border-l-success", icon: "text-success", Icon: HiOutlineCheckCircle, label: "Success" },
+    warning: { border: "border-l-warning", icon: "text-warning", Icon: HiOutlineExclamationTriangle, label: "Warning" },
+    error: { border: "border-l-danger", icon: "text-danger", Icon: HiOutlineExclamationCircle, label: "Error" },
+};
+
+const ACTION_CLASS =
+    "rounded-sm px-2.5 py-1 text-xs font-semibold text-primary-dark hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary";
+
+/** Stops every clock while the tab is out of view: nobody could have read what is on screen, and it is still there when they come back. */
+function usePauseWhileHidden(): void {
+    useEffect(() => {
+        const update = () => setAllPaused(document.visibilityState === "hidden");
+        update();
+        document.addEventListener("visibilitychange", update);
+        return () => {
+            document.removeEventListener("visibilitychange", update);
+            setAllPaused(false);
+        };
+    }, []);
+}
+
+function ActionButton({ action, id }: { action: NotificationAction; id: string }) {
+    function run() {
+        action.onClick?.();
+        if (!action.keepOpen) {
+            dismiss(id);
+        }
+    }
+    return action.href ? (
+        <a href={action.href} onClick={run} className={ACTION_CLASS}>
+            {action.label}
+        </a>
+    ) : (
+        <button type="button" onClick={run} className={ACTION_CLASS}>
+            {action.label}
+        </button>
+    );
+}
+
+/** The expandable, copyable technical lines behind a notification. */
+function Details({ lines }: { lines: string[] }) {
+    return (
+        <details className="mt-1.5">
+            <summary className="cursor-pointer text-xs font-semibold text-text-muted">Technical details</summary>
+            <ul
+                aria-label="Technical details"
+                className="mt-1.5 max-h-40 overflow-auto rounded-sm border border-border bg-surface-alt p-2 font-mono text-xs text-text select-text"
+            >
+                {lines.map((line, index) => (
+                    <li key={index} className="whitespace-pre-wrap break-words">
+                        {line}
+                    </li>
+                ))}
+            </ul>
+            <div className="mt-1.5">
+                <CopyButton value={lines.join("\n")} label="Copy technical details" />
+            </div>
+        </details>
+    );
+}
+
+/** One pop-up. Its clock (kept by the store) stops while it is hovered or holds the keyboard focus; Escape dismisses it. */
+function NotificationItem({ notification }: { notification: NotificationView }) {
+    const { id, kind, title, subtitle, message, preview, hint, details, actions, href, count } = notification;
+    const style = KIND_STYLE[kind];
+    const body = (
+        <>
+            {kind === "mail" && <span className="block text-xs font-semibold uppercase tracking-wide text-primary-dark">{style.label}</span>}
+            <span className="flex min-w-0 items-baseline gap-1.5 text-sm">
+                <span className={["truncate font-bold", kind === "error" ? "text-danger" : ""].join(" ")}>{title}</span>
+                {count > 1 && (
+                    <span className="shrink-0 rounded-pill bg-surface-alt px-1.5 text-xs font-semibold text-text-muted">
+                        <span aria-hidden="true">&times;{count}</span>
+                        <span className="sr-only"> ({count} times)</span>
+                    </span>
+                )}
+                {subtitle && <span className="truncate text-xs text-text-muted">{subtitle}</span>}
+            </span>
+            {message && <span className={["mt-0.5 block text-sm [overflow-wrap:anywhere]", kind === "mail" ? "truncate font-semibold" : ""].join(" ")}>{message}</span>}
+            {preview && <span className="mt-0.5 block text-xs text-text-muted [overflow-wrap:anywhere]">{preview}</span>}
+        </>
+    );
+    return (
+        <div
+            data-testid="notification"
+            role={kind === "error" ? "alert" : "status"}
+            data-kind={kind}
+            data-notification-id={id}
+            onMouseEnter={() => setPaused(id, true)}
+            onMouseLeave={() => setPaused(id, false)}
+            onFocus={() => setPaused(id, true)}
+            onBlur={(event) => {
+                // Focus moving between this pop-up's own controls is not leaving it.
+                if (!event.currentTarget.contains(event.relatedTarget)) {
+                    setPaused(id, false);
+                }
+            }}
+            onKeyDown={(event) => {
+                if (event.key === "Escape") {
+                    event.preventDefault();
+                    dismiss(id);
+                }
+            }}
+            className={`rr-toast-in pointer-events-auto relative rounded-md border border-border border-l-4 ${style.border} bg-surface text-text shadow-lg`}
+        >
+            <div className="flex items-start gap-2 p-3 pr-10">
+                {kind !== "mail" && <style.Icon size={18} aria-hidden="true" className={`mt-0.5 shrink-0 ${style.icon}`} />}
+                <div className="min-w-0 flex-1">
+                    {href ? (
+                        <a
+                            href={href}
+                            onClick={() => dismiss(id)}
+                            className="-m-1 block rounded-md p-1 hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary"
+                        >
+                            {body}
+                        </a>
+                    ) : (
+                        body
+                    )}
+                    {hint && <p className="mt-1.5 text-xs text-text-muted">{hint}</p>}
+                    {details.length > 0 && <Details lines={details} />}
+                    {actions.length > 0 && (
+                        <div className="-ml-2.5 mt-1.5 flex flex-wrap items-center gap-1">
+                            {actions.map((action, index) => (
+                                <ActionButton key={index} action={action} id={id} />
+                            ))}
+                        </div>
+                    )}
+                </div>
+            </div>
+            <button
+                type="button"
+                onClick={() => dismiss(id)}
+                aria-label={`Dismiss notification: ${title}`}
+                className="absolute right-1.5 top-1.5 flex h-7 w-7 items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text focus-visible:outline-2 focus-visible:outline-primary"
+            >
+                <HiOutlineXMark size={16} aria-hidden="true" />
+            </button>
+        </div>
+    );
+}
+
+/**
+ * The pop-up stack, and the one place the app's notifications (see `store.ts`) are drawn. Mounted once, in the persistent app frame, so
+ * it survives page changes and covers every app.
+ *
+ * **Where it sits.** Top right, *below* the header row: the stack is anchored to a zero-height `sticky` line placed right after the
+ * frame's header, so it starts under the header (and so under the account menu button, whatever height a branded header has) and, as
+ * the page scrolls, sticks just below the header (`--rr-header-h`, published by the title bar / `FrameBrandingHeader` - see `headerOffset.ts`;
+ * never less than 2.5 rem, which clears a full-screen compose sheet's own title bar on a phone).
+ * On a desktop the compose windows are anchored at the bottom right, the far end of the screen from this; it never covers the account menu,
+ * the header's actions or a compose window's title bar and Send button unless the window is stretched over most of the screen height.
+ * It sits above the compose sheet (z-index 60 against 50), so a pop-up is never hidden behind it. Its height is capped and scrolls.
+ *
+ * **Live regions.** Two always-mounted containers with `aria-live` (a live region has to exist before its content changes to be announced):
+ * errors in an assertive one, everything else in a polite one, and each pop-up carries the matching role - `alert` for an error, `status`
+ * for the rest - so it is announced accordingly, and the empty containers add no `alert`/`status` of their own to the page.
+ * `prefers-reduced-motion` switches the entrance animation off (`.rr-toast-in`).
+ */
+export default function NotificationCenter() {
+    const { visible, queued } = useNotifications();
+    usePauseWhileHidden();
+    useSystemErrorNotifications();
+    const errors = visible.filter((notification) => notification.kind === "error");
+    const others = visible.filter((notification) => notification.kind !== "error");
+    return (
+        <div data-testid="notification-anchor" className="sticky top-[max(var(--rr-header-h,0px),2.5rem)] z-[60] h-0 w-full">
+            <div
+                data-testid="notification-stack"
+                // Never taller than the room above the open compose windows (`ComposeProvider` publishes their top edge as `--rr-compose-top`), so
+                // a stack of pop-ups scrolls inside its own box rather than covering a compose window's title bar and buttons.
+                // (The padding is room for the pop-ups' shadow, which the scroll box would otherwise cut off in a visible edge.)
+                className="pointer-events-none absolute right-0 -top-1 flex max-h-[max(8rem,calc(var(--rr-compose-top,100vh)-max(var(--rr-header-h,0px),2.5rem)-2rem))] w-[25rem] max-w-[calc(100vw-0.5rem)] flex-col overflow-y-auto p-4"
+            >
+                <div data-testid="notification-errors" aria-live="assertive" className="flex flex-col gap-2 [&:not(:empty)]:mb-2">
+                    {errors.map((notification) => (
+                        <NotificationItem key={notification.id} notification={notification} />
+                    ))}
+                </div>
+                <div data-testid="notification-others" aria-live="polite" className="flex flex-col gap-2">
+                    {others.map((notification) => (
+                        <NotificationItem key={notification.id} notification={notification} />
+                    ))}
+                    {queued > 0 && (
+                        <p className="rr-solid pointer-events-auto self-end rounded-pill bg-surface px-2.5 py-0.5 text-xs text-text-muted shadow-md">
+                            {queued} more waiting
+                        </p>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+}

package/apps/shared/notifications/NotificationHistoryDialog.tsx

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useRef } from "react";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
+import { HistoryEntry, NotificationKind } from "./store.js";
+import { useNotifications } from "./useNotifications.js";
+
+const KIND_LABEL: Record<NotificationKind, string> = {
+    mail: "New message",
+    info: "Information",
+    success: "Done",
+    warning: "Warning",
+    error: "Error",
+};
+
+function HistoryItem({ entry, unseen }: { entry: HistoryEntry; unseen: boolean }) {
+    return (
+        <li className={["border-b border-border py-2.5 last:border-b-0", unseen ? "-mx-2 rounded-sm bg-danger-bg/60 px-2" : ""].join(" ")}>
+            <div className="flex items-baseline justify-between gap-3 text-xs text-text-muted">
+                <span className={["font-semibold uppercase tracking-wide", entry.kind === "error" ? "text-danger" : ""].join(" ")}>{KIND_LABEL[entry.kind]}</span>
+                <time dateTime={new Date(entry.at).toISOString()}>{new Date(entry.at).toLocaleTimeString()}</time>
+            </div>
+            <p className="mt-0.5 text-sm font-semibold [overflow-wrap:anywhere]">
+                {entry.title}
+                {entry.count > 1 && <span className="ml-1.5 text-xs font-medium text-text-muted">&times;{entry.count}</span>}
+            </p>
+            {entry.message && <p className="text-sm text-text-muted [overflow-wrap:anywhere]">{entry.message}</p>}
+            {entry.details.length > 0 && (
+                <details className="mt-1">
+                    <summary className="cursor-pointer text-xs font-semibold text-text-muted">Technical details</summary>
+                    <ul aria-label="Technical details" className="mt-1.5 max-h-40 overflow-auto rounded-sm border border-border bg-surface-alt p-2 font-mono text-xs select-text">
+                        {entry.details.map((line, index) => (
+                            <li key={index} className="whitespace-pre-wrap break-words">
+                                {line}
+                            </li>
+                        ))}
+                    </ul>
+                    <div className="mt-1.5">
+                        <CopyButton value={entry.details.join("\n")} label="Copy technical details" />
+                    </div>
+                </details>
+            )}
+        </li>
+    );
+}
+
+export interface NotificationHistoryDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+/**
+ * "Recent notifications": the last few pop-ups, newest first, so nothing is lost when one expires. Opening it counts as having seen
+ * them (the unseen-error count on the account menu goes), but the errors that were unseen when it opened stay highlighted until it closes.
+ */
+export default function NotificationHistoryDialog({ open, onClose }: NotificationHistoryDialogProps) {
+    const { history, markHistorySeen, clearHistory } = useNotifications();
+    const unseenAtOpenRef = useRef<Set<string>>(new Set());
+    if (!open) {
+        unseenAtOpenRef.current = new Set(history.filter((entry) => entry.unseen && entry.kind === "error").map((entry) => entry.id));
+    }
+    useEffect(() => {
+        if (open) {
+            markHistorySeen();
+        }
+    }, [open, markHistorySeen]);
+    return (
+        <Modal open={open} onClose={onClose} title="Recent notifications">
+            {history.length === 0 ? (
+                <p className="text-sm text-text-muted">Nothing yet. Errors, sent messages and other pop-ups from this session are listed here.</p>
+            ) : (
+                <>
+                    <ul aria-label="Recent notifications">
+                        {history.map((entry) => (
+                            <HistoryItem key={entry.id} entry={entry} unseen={unseenAtOpenRef.current.has(entry.id)} />
+                        ))}
+                    </ul>
+                    <div className="mt-4">
+                        <button type="button" onClick={clearHistory} className="rounded-sm px-2.5 py-1 text-xs font-semibold text-primary-dark hover:bg-surface-alt">
+                            Clear list
+                        </button>
+                    </div>
+                </>
+            )}
+        </Modal>
+    );
+}

package/apps/shared/notifications/apiErrors.ts

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { describeSendFailure } from "@rapidmx/react-shared/mail/sendFailure.js";
+import { NotificationAction, notify } from "./store.js";
+
+/** Whether `err` is a request that was cancelled (`AbortError`) - by name, since a `DOMException` is not always an `Error` (jsdom's is not). */
+export function isAbortError(err: unknown): boolean {
+    return typeof err === "object" && err !== null && (err as { name?: unknown }).name === "AbortError";
+}
+
+/** Where "Sign in" goes: auth-server's base URL, set once by the app frame. Without one it reloads the page, which redirects when signed out. */
+let signInBaseUrl: string | undefined;
+
+export function setSignInUrl(authServerUrl: string | undefined): void {
+    signInBaseUrl = authServerUrl;
+}
+
+/** The "Your session expired" pop-up: one however many requests noticed, with a "Sign in" action. Returns its id. */
+export function notifySessionExpired(): string {
+    return notify({
+        kind: "error",
+        title: "Your session expired",
+        message: "Sign in again to keep working. Anything not yet saved in this tab is still here until you leave it.",
+        dedupeKey: "session-expired",
+        actions: [
+            {
+                label: "Sign in",
+                onClick: () => {
+                    if (signInBaseUrl) {
+                        window.location.href = `${signInBaseUrl}/auth/signin?return_to=${encodeURIComponent(window.location.href)}`;
+                    } else {
+                        window.location.reload();
+                    }
+                },
+            },
+        ],
+    });
+}
+
+export interface NotifyApiErrorOptions {
+    /** Extra actions (a "Retry"). */
+    actions?: NotificationAction[];
+    /** Replaces the default key (`api:<context>:<status>`): errors with one key are one pop-up with a count. */
+    dedupeKey?: string;
+}
+
+/** Whether `err` is a request that never got an answer (offline, DNS, a dropped connection) rather than an error response. */
+function isNetworkFailure(err: unknown): boolean {
+    return err instanceof TypeError || (err instanceof Error && /network|failed to fetch|load failed/i.test(err.message));
+}
+
+/**
+ * Turns the failure of something the user did into an `error` pop-up and returns its id - or, for a `401`, into "Your session expired"
+ * with a Sign in action, and for a request that was cancelled into nothing (`""`). `context` says what was being attempted, as the
+ * pop-up's title ("Couldn't archive this message"); the message is the server's own, and its technical facts (`describeSendFailure()`'s
+ * lines, the status and code) are the expandable details. The same failing thing repeating is one pop-up with a count.
+ */
+export function notifyApiError(err: unknown, context: string, options: NotifyApiErrorOptions = {}): string {
+    if (isAbortError(err)) {
+        return "";
+    }
+    if (err instanceof ApiRequestError) {
+        if (err.status === 401) {
+            return notifySessionExpired();
+        }
+        const failure = describeSendFailure(err, context);
+        const facts = [`Status: ${err.status}${err.code ? ` (${err.code})` : ""}`, ...failure.lines];
+        return notify({
+            kind: "error",
+            title: context,
+            message: failure.message,
+            details: facts,
+            actions: options.actions,
+            dedupeKey: options.dedupeKey ?? `api:${context}:${err.status}`,
+        });
+    }
+    if (isNetworkFailure(err)) {
+        return notify({
+            kind: "error",
+            title: context,
+            message: "The server couldn't be reached. Check your connection and try again.",
+            details: [(err as Error).message],
+            actions: options.actions,
+            dedupeKey: options.dedupeKey ?? `api:${context}:network`,
+        });
+    }
+    return notify({
+        kind: "error",
+        title: context,
+        message: "Something unexpected went wrong.",
+        details: err instanceof Error ? [`${err.name}: ${err.message}`] : [String(err)],
+        actions: options.actions,
+        dedupeKey: options.dedupeKey ?? `api:${context}:unexpected`,
+    });
+}

package/apps/shared/notifications/headerOffset.ts

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useRef } from "react";
+
+/** The CSS variable (on `<html>`) that holds the height, in px, of the frame's sticky header - its title bar or the branding header. */
+export const HEADER_HEIGHT_VAR = "--rr-header-h";
+
+/**
+ * A ref callback for the frame's sticky `<header>`: publishes its height as `--rr-header-h` (and keeps it current as the header resizes -
+ * a branded header can be any height and wraps on a phone), so the pop-up stack (`NotificationCenter`) can stick just below it instead of
+ * sliding under it or over the account menu. When the header goes (a page without one) the variable is set to 0 rather than left stale.
+ */
+export function useHeaderHeightRef(): (element: HTMLElement | null) => void {
+    const stop = useRef<(() => void) | undefined>(undefined);
+    return useCallback((element: HTMLElement | null) => {
+        stop.current?.();
+        stop.current = undefined;
+        const root = document.documentElement;
+        if (!element) {
+            root.style.setProperty(HEADER_HEIGHT_VAR, "0px");
+            return;
+        }
+        const publish = () => root.style.setProperty(HEADER_HEIGHT_VAR, `${Math.round(element.getBoundingClientRect().height)}px`);
+        publish();
+        const observer = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(publish);
+        observer?.observe(element);
+        window.addEventListener("resize", publish);
+        stop.current = () => {
+            observer?.disconnect();
+            window.removeEventListener("resize", publish);
+        };
+    }, []);
+}

package/apps/shared/notifications/pushStatus.ts

@@ -0,0 +1,56 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { getPushClient, PushStatus } from "@rapidmx/react-shared/mail/pushClient.js";
+import { dismiss, notify } from "./store.js";
+
+/** How long the live connection has to be down before anyone is told: a reconnect within a few seconds is not worth a word. */
+export const PUSH_OFFLINE_NOTICE_MS = 10_000;
+
+export const PUSH_NOTICE_ID = "push-connection";
+
+/**
+ * A subtle info pop-up when the live connection (new mail, folder counts, send results) has been down for more than `PUSH_OFFLINE_NOTICE_MS`,
+ * which goes by itself the moment it is back. Shown once per outage - dismissing it does not bring it back until the connection has
+ * reconnected and dropped again. The page keeps working meanwhile (it polls), which is what the message says.
+ */
+export function usePushConnectionNotice(enabled: boolean): void {
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const client = getPushClient();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let shown = false;
+        const off = client.onStatus((status: PushStatus) => {
+            if (status === "reconnecting") {
+                if (timer === undefined && !shown) {
+                    timer = setTimeout(() => {
+                        shown = true;
+                        notify({
+                            id: PUSH_NOTICE_ID,
+                            kind: "info",
+                            title: "Live updates are paused",
+                            message: "The connection is being restored. The page keeps refreshing on its own, so new mail may take a little longer to appear.",
+                            sticky: true,
+                            history: false,
+                        });
+                    }, PUSH_OFFLINE_NOTICE_MS);
+                }
+            } else {
+                clearTimeout(timer);
+                timer = undefined;
+                if (status === "open" && shown) {
+                    shown = false;
+                    dismiss(PUSH_NOTICE_ID);
+                }
+            }
+        });
+        return () => {
+            off();
+            clearTimeout(timer);
+        };
+    }, [enabled]);
+}