@rapidmx/web-client 0.10.0 → 0.12.0

package/dist/apps/shared/notifications/NotificationHistoryDialog.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { 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 { useNotifications } from "./useNotifications.js";
+const KIND_LABEL = {
+    mail: "New message",
+    info: "Information",
+    success: "Done",
+    warning: "Warning",
+    error: "Error",
+};
+function HistoryItem({ entry, unseen }) {
+    return (_jsxs("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(" "), children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-xs text-text-muted", children: [_jsx("span", { className: ["font-semibold uppercase tracking-wide", entry.kind === "error" ? "text-danger" : ""].join(" "), children: KIND_LABEL[entry.kind] }), _jsx("time", { dateTime: new Date(entry.at).toISOString(), children: new Date(entry.at).toLocaleTimeString() })] }), _jsxs("p", { className: "mt-0.5 text-sm font-semibold [overflow-wrap:anywhere]", children: [entry.title, entry.count > 1 && _jsxs("span", { className: "ml-1.5 text-xs font-medium text-text-muted", children: ["\u00D7", entry.count] })] }), entry.message && _jsx("p", { className: "text-sm text-text-muted [overflow-wrap:anywhere]", children: entry.message }), entry.details.length > 0 && (_jsxs("details", { className: "mt-1", children: [_jsx("summary", { className: "cursor-pointer text-xs font-semibold text-text-muted", children: "Technical details" }), _jsx("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", children: entry.details.map((line, index) => (_jsx("li", { className: "whitespace-pre-wrap break-words", children: line }, index))) }), _jsx("div", { className: "mt-1.5", children: _jsx(CopyButton, { value: entry.details.join("\n"), label: "Copy technical details" }) })] }))] }));
+}
+/**
+ * "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 }) {
+    const { history, markHistorySeen, clearHistory } = useNotifications();
+    const unseenAtOpenRef = useRef(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 (_jsx(Modal, { open: open, onClose: onClose, title: "Recent notifications", children: history.length === 0 ? (_jsx("p", { className: "text-sm text-text-muted", children: "Nothing yet. Errors, sent messages and other pop-ups from this session are listed here." })) : (_jsxs(_Fragment, { children: [_jsx("ul", { "aria-label": "Recent notifications", children: history.map((entry) => (_jsx(HistoryItem, { entry: entry, unseen: unseenAtOpenRef.current.has(entry.id) }, entry.id))) }), _jsx("div", { className: "mt-4", children: _jsx("button", { type: "button", onClick: clearHistory, className: "rounded-sm px-2.5 py-1 text-xs font-semibold text-primary-dark hover:bg-surface-alt", children: "Clear list" }) })] })) }));
+}

package/dist/apps/shared/notifications/apiErrors.d.ts

@@ -0,0 +1,19 @@
+import { NotificationAction } 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 declare function isAbortError(err: unknown): boolean;
+export declare function setSignInUrl(authServerUrl: string | undefined): void;
+/** The "Your session expired" pop-up: one however many requests noticed, with a "Sign in" action. Returns its id. */
+export declare function notifySessionExpired(): string;
+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;
+}
+/**
+ * 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 declare function notifyApiError(err: unknown, context: string, options?: NotifyApiErrorOptions): string;

package/dist/apps/shared/notifications/apiErrors.js

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { 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) {
+    return typeof err === "object" && err !== null && err.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;
+export function setSignInUrl(authServerUrl) {
+    signInBaseUrl = authServerUrl;
+}
+/** The "Your session expired" pop-up: one however many requests noticed, with a "Sign in" action. Returns its id. */
+export function notifySessionExpired() {
+    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();
+                    }
+                },
+            },
+        ],
+    });
+}
+/** Whether `err` is a request that never got an answer (offline, DNS, a dropped connection) rather than an error response. */
+function isNetworkFailure(err) {
+    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, context, options = {}) {
+    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.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/dist/apps/shared/notifications/headerOffset.d.ts

@@ -0,0 +1,8 @@
+/** 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 declare 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 declare function useHeaderHeightRef(): (element: HTMLElement | null) => void;

package/dist/apps/shared/notifications/headerOffset.js

@@ -0,0 +1,33 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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() {
+    const stop = useRef(undefined);
+    return useCallback((element) => {
+        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/dist/apps/shared/notifications/pushStatus.d.ts

@@ -0,0 +1,9 @@
+/** 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 declare const PUSH_OFFLINE_NOTICE_MS = 10000;
+export declare 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 declare function usePushConnectionNotice(enabled: boolean): void;

package/dist/apps/shared/notifications/pushStatus.js

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+import { getPushClient } 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 = 10000;
+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) {
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const client = getPushClient();
+        let timer;
+        let shown = false;
+        const off = client.onStatus((status) => {
+            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]);
+}

package/dist/apps/shared/notifications/store.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The app's one notification store: every pop-up - new mail, a failed send, an API error, an expired session - goes through
+ * `notify()`. It is deliberately framework-free (no React, no DOM beyond `sessionStorage`/timers), so it can be called from a hook,
+ * a plain function or an `apiFetch` error path alike; `NotificationCenter` (the view, mounted once in the app frame) and
+ * `useNotifications()` only *read* it.
+ *
+ * Rules, all enforced here rather than by the view so they hold whoever renders:
+ *
+ * - **At most `MAX_VISIBLE` (3) are visible**; the rest wait in a queue and appear as room is made. A sticky notification (an error, or
+ * anything with actions) that finds the stack full pushes out the oldest one that would have gone by itself, rather than waiting behind
+ * it. A queued notification that has waited `QUEUE_STALE_MS` is dropped (it would be news from the past) - it is still in the history.
+ * - **Sticky until dismissed or resolved**: errors and notifications with actions never expire (`update()` or `dismiss()` resolve them).
+ * Everything else goes by itself after its kind's default time, or `timeoutMs`. `sticky` overrides both ways.
+ * - **A clock that stops**: a notification's remaining time stops while it is hovered or focused (`setPaused()`) and while the tab is
+ * hidden (`setAllPaused()`), and continues from where it was.
+ * - **Deduplicated by `dedupeKey`**: a second notification with a key that is still on screen (or waiting) does not stack - it replaces
+ * the first one's content, restarts its clock and raises its `count`, so a flapping error is one pop-up saying "x3".
+ * - **Nothing is lost when one goes**: the last `HISTORY_LIMIT` (30, except new-mail pop-ups, which the inbox already holds) are
+ * kept, in memory and in `sessionStorage`, with which errors nobody has seen yet.
+ *
+ * Nothing is stored where there is no `window` (server-side rendering): the module state is shared between requests there, so
+ * `notify()` only hands back an id.
+ */
+export type NotificationKind = "mail" | "info" | "success" | "warning" | "error";
+export interface NotificationAction {
+    label: string;
+    /** Runs when the action is used. */
+    onClick?: () => void;
+    /** Or a link to follow (a plain `<a>`, so the router's link handling applies). */
+    href?: string;
+    /** Leave the notification on screen after the action ran. By default an action resolves (dismisses) it. */
+    keepOpen?: boolean;
+}
+export interface NotifyInput {
+    /** Reuse an id to replace a notification (it is the same one: its content is swapped and its clock restarted). Generated when absent. */
+    id?: string;
+    kind: NotificationKind;
+    title: string;
+    /** A second, muted line next to the title (a mail pop-up's sender address). */
+    subtitle?: string;
+    message?: string;
+    /** A mail pop-up's preview text, under `message` (its subject). */
+    preview?: string;
+    /** A small muted explanation above the actions (the desktop-notification offer). */
+    hint?: string;
+    /** Technical detail: a list of lines, or one block of text. Shown collapsed, monospace, with a copy button. */
+    details?: string[] | string;
+    actions?: NotificationAction[];
+    /** The whole pop-up is a link to this (new mail opens the message). */
+    href?: string;
+    /** Never expires by itself. Default: errors and anything with actions. */
+    sticky?: boolean;
+    /** How long it stays, in ms. Default by kind, see `DEFAULT_TIMEOUT_MS`. Ignored for a sticky one. */
+    timeoutMs?: number;
+    /** Notifications with the same key that are still showing are one: see the module doc comment. */
+    dedupeKey?: string;
+    /** Keep it out of the history (default: kept, except `mail`). */
+    history?: boolean;
+}
+/** A notification as a view renders it. */
+export interface NotificationView {
+    id: string;
+    kind: NotificationKind;
+    title: string;
+    subtitle?: string;
+    message?: string;
+    preview?: string;
+    hint?: string;
+    details: string[];
+    actions: NotificationAction[];
+    href?: string;
+    /** How many times this one was raised (`dedupeKey`), 1 for a single one. */
+    count: number;
+    sticky: boolean;
+    createdAt: number;
+}
+export interface HistoryEntry {
+    id: string;
+    kind: NotificationKind;
+    title: string;
+    message?: string;
+    details: string[];
+    count: number;
+    /** When it was last raised (epoch ms). */
+    at: number;
+    /** Nobody has opened the history since it arrived. */
+    unseen: boolean;
+}
+export interface NotificationsSnapshot {
+    /** What is on screen, oldest first. */
+    visible: NotificationView[];
+    /** How many are waiting for room. */
+    queued: number;
+    /** The last `HISTORY_LIMIT`, newest first. */
+    history: HistoryEntry[];
+    /** Errors in the history that nobody has looked at. */
+    unseenErrors: number;
+}
+export declare const MAX_VISIBLE = 3;
+export declare const MAX_QUEUED = 20;
+export declare const QUEUE_STALE_MS = 30000;
+export declare const HISTORY_LIMIT = 30;
+export declare const HISTORY_STORAGE_KEY = "rapidmx-notification-history";
+/** The most technical lines and the longest line kept per notification - a transport error can carry a whole SMTP transcript. */
+export declare const MAX_DETAIL_LINES = 50;
+export declare const MAX_DETAIL_LINE_LENGTH = 500;
+/** How long a non-sticky notification stays, by kind. Errors are sticky, so theirs is only for an explicit `sticky: false`. */
+export declare const DEFAULT_TIMEOUT_MS: Record<NotificationKind, number>;
+/**
+ * Raises a notification and returns its id. See the module doc comment for what happens to it. Usable from anywhere - a component, a
+ * hook, a plain function, an `apiFetch` error path - and safe where there is no window (it does nothing there).
+ */
+export declare function notify(input: NotifyInput): string;
+/**
+ * Changes a notification that is still showing or waiting - the way to resolve it ("Sending..." becoming "Sent"). Only the given
+ * fields change. Its clock restarts, and it may become sticky or stop being so with its new kind. Returns `false` when there is no such
+ * notification any more (it was dismissed or expired); its history entry is updated all the same.
+ */
+export declare function update(id: string, patch: Partial<Omit<NotifyInput, "id" | "dedupeKey">>): boolean;
+/** Removes a notification from the screen (or the queue). Its history entry stays. Does nothing for an unknown id. */
+export declare function dismiss(id: string): void;
+/** Removes everything showing and waiting. */
+export declare function dismissAll(): void;
+/** Stops (or restarts) one notification's clock: it is being hovered or holds the keyboard focus. */
+export declare function setPaused(id: string, paused: boolean): void;
+/** Stops (or restarts) every clock: the tab is hidden, so nobody could have read what is on screen. */
+export declare function setAllPaused(paused: boolean): void;
+/** Marks every history entry as seen - the user has opened the history. */
+export declare function markHistorySeen(): void;
+/** Empties the history. */
+export declare function clearHistory(): void;
+export declare function subscribeNotifications(listener: () => void): () => void;
+export declare function getNotificationsSnapshot(): NotificationsSnapshot;
+export declare function getServerNotificationsSnapshot(): NotificationsSnapshot;
+/** Forgets everything and stops every clock - for a test, or a page that outlives its session. */
+export declare function resetNotifications(): void;