@rapidmx/web-client 0.17.0 → 0.18.0

package/dist/apps/shared/components/admin/diagnostics/useLogStream.js

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { LogClient } from "./logClient.js";
+import { LogStore } from "./LogStore.js";
+/** Lines arrive in bursts; the view is redrawn at most this often, however many came. */
+export const LOG_FLUSH_MS = 100;
+function snapshotOf(store) {
+    const capture = store.capture;
+    return {
+        entries: store.entries.slice(),
+        dropped: store.dropped,
+        capture: capture && {
+            active: capture.active,
+            startedAt: capture.startedAt,
+            stoppedAt: capture.stoppedAt,
+            count: capture.entries.length,
+            missed: capture.missed,
+        },
+    };
+}
+/**
+ * The live log stream of the server for the log view: a `LogClient`, and a `LogStore` holding the lines and any capture. Nothing
+ * connects until `start()`. The stream is closed, and the redraw timer cleared, when the component unmounts.
+ */
+export function useLogStream(options = {}) {
+    const [client] = useState(() => new LogClient(options));
+    const [store] = useState(() => new LogStore());
+    const [connection, setConnection] = useState({
+        status: client.status,
+        error: undefined,
+    });
+    const [snapshot, setSnapshot] = useState(() => snapshotOf(store));
+    const timer = useRef(undefined);
+    const flush = useCallback(() => {
+        clearTimeout(timer.current);
+        timer.current = undefined;
+        setSnapshot(snapshotOf(store));
+    }, [store]);
+    useEffect(() => {
+        const stopEntries = client.onEntry((entry) => {
+            store.add(entry);
+            timer.current ?? (timer.current = setTimeout(flush, LOG_FLUSH_MS));
+        });
+        const stopStatus = client.onStatus((status, error) => setConnection({ status, error }));
+        return () => {
+            stopEntries();
+            stopStatus();
+            client.stop();
+            clearTimeout(timer.current);
+            timer.current = undefined;
+        };
+    }, [client, store, flush]);
+    return {
+        status: connection.status,
+        error: connection.error,
+        running: connection.status === "connecting" || connection.status === "live" || connection.status === "reconnecting",
+        entries: snapshot.entries,
+        dropped: snapshot.dropped,
+        capture: snapshot.capture,
+        start: () => client.start(),
+        stop: () => client.stop(),
+        clear: () => {
+            store.clear();
+            flush();
+        },
+        startCapture: () => {
+            store.startCapture(Date.now());
+            flush();
+        },
+        stopCapture: () => {
+            store.stopCapture(Date.now());
+            flush();
+        },
+        captureEntries: () => store.capture?.entries ?? [],
+    };
+}

package/dist/apps/shared/components/admin/diagnostics/useMetricsPolling.d.ts

@@ -0,0 +1,20 @@
+import { DiagnosticsMetrics } from "./diagnosticsApi.js";
+export interface MetricsPolling {
+    /** The last `METRICS_HISTORY_SIZE` samples, oldest first. */
+    history: DiagnosticsMetrics[];
+    /** Why the last request failed, until one succeeds. */
+    error: string | undefined;
+    /** Whether nothing has been answered yet. */
+    loading: boolean;
+    /** Whether polling is stopped by the viewer (Pause), or because the server refused the viewer. */
+    paused: boolean;
+    setPaused: (paused: boolean) => void;
+}
+/**
+ * Samples `getDiagnosticsMetrics()` every `METRICS_POLL_INTERVAL_MS` while `enabled` and not paused, keeping the last
+ * `METRICS_HISTORY_SIZE`. A request is only ever made when the previous one has answered, none is made while the page is
+ * hidden (one is made at once when it is shown again), and polling stops when the component unmounts. A refusal (401/403)
+ * pauses polling, since asking again would only be refused again; Resume tries once more. Any other failure is shown
+ * and polling carries on, so a blip on the server does not need the viewer to do anything.
+ */
+export declare function useMetricsPolling(enabled: boolean): MetricsPolling;

package/dist/apps/shared/components/admin/diagnostics/useMetricsPolling.js

@@ -0,0 +1,69 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { getDiagnosticsMetrics } from "./diagnosticsApi.js";
+import { describeError, isPermissionError } from "./format.js";
+import { appendSample, METRICS_POLL_INTERVAL_MS } from "./metricsHistory.js";
+/**
+ * Samples `getDiagnosticsMetrics()` every `METRICS_POLL_INTERVAL_MS` while `enabled` and not paused, keeping the last
+ * `METRICS_HISTORY_SIZE`. A request is only ever made when the previous one has answered, none is made while the page is
+ * hidden (one is made at once when it is shown again), and polling stops when the component unmounts. A refusal (401/403)
+ * pauses polling, since asking again would only be refused again; Resume tries once more. Any other failure is shown
+ * and polling carries on, so a blip on the server does not need the viewer to do anything.
+ */
+export function useMetricsPolling(enabled) {
+    const [history, setHistory] = useState([]);
+    const [error, setError] = useState();
+    const [loading, setLoading] = useState(true);
+    const [paused, setPaused] = useState(false);
+    useEffect(() => {
+        if (!enabled || paused) {
+            return;
+        }
+        let cancelled = false;
+        let inFlight = false;
+        async function sample() {
+            if (inFlight || document.hidden) {
+                return;
+            }
+            inFlight = true;
+            try {
+                const next = await getDiagnosticsMetrics();
+                if (!cancelled) {
+                    setHistory((previous) => appendSample(previous, next));
+                    setError(undefined);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setError(describeError(err, "Could not read the server's metrics."));
+                    if (isPermissionError(err)) {
+                        setPaused(true);
+                    }
+                }
+            }
+            finally {
+                inFlight = false;
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        }
+        void sample();
+        const timer = setInterval(() => void sample(), METRICS_POLL_INTERVAL_MS);
+        const onVisibilityChange = () => {
+            if (!document.hidden) {
+                void sample();
+            }
+        };
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [enabled, paused]);
+    return { history, error, loading, paused, setPaused };
+}

package/dist/apps/shared/components/admin/layout/AdminShell.d.ts

@@ -2,7 +2,7 @@ import "../../../styles/app.css";
 import React, { PropsWithChildren } from "react";
 import type { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import { PluginNav, PluginNavProps } from "../../../plugins/pluginNav.js";
-export type AdminSection = "mailboxes" | "quarantine" | "ingestQueue" | "domains" | "auditLog" | "distributionLists" | "transportRules" | "escrowScopes" | "retentionPolicy" | "encryptionPolicy" | "mailboxPolicy" | "setup" | "dataRequests" | "plugins" | "branding" | "signingCertificates";
+export type AdminSection = "mailboxes" | "quarantine" | "ingestQueue" | "domains" | "auditLog" | "distributionLists" | "transportRules" | "escrowScopes" | "retentionPolicy" | "encryptionPolicy" | "mailboxPolicy" | "setup" | "dataRequests" | "plugins" | "diagnostics" | "branding" | "signingCertificates";
 /** A core `AdminSection`, or a plugin's `adminNav` item id (see `PluginNav`). */
 export type AdminShellActive = AdminSection | (string & {});
 export interface AdminShellProps extends PluginNavProps {

package/dist/apps/shared/components/admin/layout/AdminShell.js

@@ -6,7 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import "../../../styles/app.css";
 import { useEffect, useState } from "react";
 import { useRouter } from "@rapidrest/react/client";
-import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, } from "react-icons/hi2";
+import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineCpuChip, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, } from "react-icons/hi2";
 import { apiFetch, ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
@@ -78,6 +78,7 @@ const NAV_ITEMS = [
         icon: HiOutlineDocumentCheck,
     },
     { id: "plugins", href: "/admin/plugins", label: "Plugins", icon: HiOutlinePuzzlePiece },
+    { id: "diagnostics", href: "/admin/diagnostics", label: "Diagnostics", icon: HiOutlineCpuChip },
     { id: "branding", href: "/admin/branding", label: "Branding", icon: HiOutlinePaintBrush },
 ];
 /** Mailbox-scoped sections — not part of the global nav rail/tab bar (see `NAV_ITEMS` above), but

package/dist/apps/shared/components/calendar/layout/CalendarShell.js

@@ -10,7 +10,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 { useLocation } from "@rapidrest/react/client";
+import { useLocation } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 const CalendarShellContext = createContext({

package/dist/apps/shared/components/contacts/layout/ContactsShell.js

@@ -11,8 +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 { useLocation } from "@rapidrest/react/client";
-import { useNavigate } from "../../../navigation/index.js";
+import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 const ContactsShellContext = createContext({ mailboxes: [] });

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

@@ -10,8 +10,7 @@ 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 FloatingActionButton from "../../layout/FloatingActionButton.js";
-import { useLocation } from "@rapidrest/react/client";
-import { useNavigate } from "../../../navigation/index.js";
+import { useLocation, useNavigate } from "../../../navigation/index.js";
 import KeyEnrollmentGate from "../../layout/KeyEnrollmentGate.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { prefetchComposeWindow, useCompose } from "../compose/ComposeContext.js";

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

@@ -11,8 +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 { useLocation } from "@rapidrest/react/client";
-import { useNavigate } from "../../../navigation/index.js";
+import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 import { mergePluginNavItems } from "../../../plugins/pluginNav.js";

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

@@ -11,8 +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 { useLocation } from "@rapidrest/react/client";
-import { useNavigate } from "../../../navigation/index.js";
+import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 const TasksShellContext = createContext({ mailboxes: [] });

package/dist/apps/shared/navigation/index.d.ts

@@ -14,3 +14,14 @@ export type NavigateFn = (href: string, options?: NavigateOptions) => void;
  * stable across renders.
  */
 export declare function useNavigate(): NavigateFn;
+/**
+ * Where the page is, as `{ pathname, search, hash }`: the router's location when the page is under a router, else the browser's.
+ * A page a plugin renders has no router (`router = false`), where `@rapidrest/react`'s `useLocation()` is empty and the query a
+ * shell reads its mailbox from (`?mailboxUid=`) would be lost. Without one, the address is the browser's - and empty on the
+ * server and while hydrating, so the page hydrates as it was rendered and then follows the address.
+ */
+export declare function useLocation(): {
+    pathname: string;
+    search: string;
+    hash: string;
+};

package/dist/apps/shared/navigation/index.js

@@ -7,8 +7,8 @@
  * route, the app's `_shell.tsx` as the persistent frame - see `apps/www/_shell.tsx`); this is the one thing on top of it: a
  * `navigate()` that keeps the page when only the query string changes.
  */
-import { useCallback, useRef } from "react";
-import { useRouter } from "@rapidrest/react/client";
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import { useLocation as useRouterLocation, useRouter } from "@rapidrest/react/client";
 /**
  * The function to go somewhere with, for what code decides (after a save, a select, a folder change). `navigate("/calendar")`
  * changes the page and the URL without a page load when the router knows the page (Mail, Calendar, Contacts, Tasks, Settings
@@ -32,3 +32,27 @@ export function useNavigate() {
         void go(href, { replace: options.replace, shallow });
     }, []);
 }
+function subscribeToHistory(onChange) {
+    window.addEventListener("popstate", onChange);
+    return () => window.removeEventListener("popstate", onChange);
+}
+// Joined, not added: a test's stand-in for `window.location` may have no `search`, and `undefined + undefined` is `NaN`.
+const currentAddress = () => [window.location.pathname, window.location.search, window.location.hash].join("");
+const noAddress = () => "";
+/**
+ * Where the page is, as `{ pathname, search, hash }`: the router's location when the page is under a router, else the browser's.
+ * A page a plugin renders has no router (`router = false`), where `@rapidrest/react`'s `useLocation()` is empty and the query a
+ * shell reads its mailbox from (`?mailboxUid=`) would be lost. Without one, the address is the browser's - and empty on the
+ * server and while hydrating, so the page hydrates as it was rendered and then follows the address.
+ */
+export function useLocation() {
+    const routed = useRouterLocation();
+    const own = useSyncExternalStore(subscribeToHistory, currentAddress, noAddress);
+    const ownLocation = useMemo(() => {
+        // Split by hand, not with `URL`: a page that stubs the global `URL` (for `createObjectURL`) must still render.
+        const [beforeHash, ...fragment] = own.split("#");
+        const [pathname, ...query] = beforeHash.split("?");
+        return { pathname, search: query.length ? `?${query.join("?")}` : "", hash: fragment.length ? `#${fragment.join("#")}` : "" };
+    }, [own]);
+    return routed.pathname !== "" ? routed : ownLocation;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",