@rapidmx/web-client 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,88 @@
+# RapidMX: Web Client
+
+[![npm version](https://img.shields.io/npm/v/@rapidmx/web-client)](https://www.npmjs.com/package/@rapidmx/web-client)
+
+RapidMX's webmail (`apps/www`), admin console (`apps/admin`) and escrow console (`apps/escrow`) React UI. The pages are
+served and hydrated by [`rapidmx/server`](https://github.com/RapidMX/server) through `@rapidrest/react`'s file-convention
+routes, and `@rapidmx/electron-client` reuses the same components. Platform-agnostic API clients, hooks and generic UI
+primitives live in [`@rapidmx/react-shared`](https://github.com/RapidMX/react-shared).
+
+## Package layout
+
+The package ships the TSX sources (`apps/`) and a compiled mirror (`dist/apps/`, JavaScript plus `.d.ts` declarations).
+There is no root export. Every module is its own subpath, mapped by `package.json`'s `exports` from
+`@rapidmx/web-client/<path>.js` to `dist/apps/<path>.js`:
+
+```ts
+import SettingsShell from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+```
+
+`@rapidmx/web-client/shared/styles/app.css` is the Tailwind entry point and design tokens.
+
+## Plugin UI surface
+
+Server plugins can ship their own pages (see the plugin manifest's `ui` field in `@rapidmx/restapi`). The server builds
+them together with this package, so they share one React, one `@rapidmx/react-shared` state and one stylesheet. The
+modules below are the **supported surface for plugin pages**. Anything else under `apps/` is internal and may change in
+any release.
+
+### Shells
+
+| Import | Use |
+| --- | --- |
+| `shared/components/layout/AppShell.js` | Chrome for webmail apps: app rail, header, user menu, impersonation banner, compose and unlock providers. `active` is a core app or the plugin's `appRail` item id. |
+| `shared/components/settings/layout/SettingsShell.js` | Settings chrome with the section list and mailbox switcher. `active` is the plugin's `settingsSections` item id. `useSettingsShell()` gives the selected `mailboxUid` and the accessible `mailboxes`. |
+| `shared/components/admin/layout/AdminShell.js` | Admin console chrome, gated on administrator access. `active` is the plugin's `adminNav` item id. |
+| `shared/components/layout/BrandingChrome.js` | `BrandingHeader` and `BrandingFooter`, for pages that don't use a shell, such as public pages. |
+| `shared/plugins/pluginNav.js` | The `PluginNav`, `PluginUiNavItem` and `PluginNavProps` types. |
+
+Every www and admin page receives a `pluginNav` prop from the server. It lists the settings sections, admin sections and
+app rail entries of every enabled plugin whose UI built. The shells append those entries after their own, with a generic
+icon. An entry whose id matches a core entry is skipped, and so is one whose `href` isn't a same-origin path. Pass the
+page props straight to the shell so the navigation shows:
+
+```tsx
+import React from "react";
+import SettingsShell, {
+    SettingsShellProps,
+    useSettingsShell,
+} from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+
+export default function RemindersSettingsPage(props: Omit<SettingsShellProps, "active">) {
+    return (
+        <SettingsShell {...props} active="reminders">
+            <RemindersSettings />
+        </SettingsShell>
+    );
+}
+
+function RemindersSettings() {
+    const { mailboxUid } = useSettingsShell();
+    return <p>Settings for {mailboxUid}</p>;
+}
+```
+
+Public and escrow pages get no `pluginNav`.
+
+### From `@rapidmx/react-shared`
+
+Plugin pages import these directly from `@rapidmx/react-shared`, which the server resolves to the same copy the shells
+use:
+
+- `branding/useBranding.js`: `useBranding()`, for the branding and icon of pages outside a shell;
+- `auth/session.js`: `useRedirectIfUnauthenticated()`, already called by every shell;
+- `util/api.js`: `apiFetch()` and `ApiRequestError`, for calling the plugin's own API routes;
+- `mail/mailApi.js`: mailboxes and folders, such as `listMailboxes()` and `listFolders()`;
+- `components/buttons/Button.js`, `components/feedback/Alert.js` and `components/feedback/Skeleton.js`;
+- `components/forms/FormField.js`;
+- `components/overlays/Modal.js` and `components/overlays/Drawer.js`;
+- `components/pickers/MiniDatePicker.js`.
+
+## Development
+
+```sh
+yarn install
+yarn test        # vitest with coverage gates
+yarn lint
+yarn build       # tsc into dist/apps
+```

package/apps/admin/audit-log/index.tsx

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { AuditLogEntry, AuditLogFilters, listAuditLog } from "@rapidmx/react-shared/admin/auditLogApi.js";
 import AdminShell, { AdminShellProps } from "../../shared/components/admin/layout/AdminShell.js";
@@ -10,6 +10,8 @@ import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 
 const PAGE_SIZE = 25;
+/** How long typing in a filter box has to pause before the log is re-fetched. */
+export const FILTER_DEBOUNCE_MS = 300;
 const FILTER_KEYS: (keyof AuditLogFilters)[] = ["mailboxUid", "actorUserUid", "action", "targetType"];
 
 /** Seeds the filter form from the query string on first render — lets a link (e.g. a future "View audit
@@ -39,29 +41,54 @@ export default function AuditLogPage(props: Omit<AdminShellProps, "active">) {
 }
 
 function AuditLogContent() {
+    // `filters` is what the boxes show; `queryFilters` is what was last fetched - it follows `filters` once typing
+    // pauses, and stays `null` until the URL's filters are read so no unfiltered fetch goes out first.
     const [filters, setFilters] = useState<AuditLogFilters>({});
+    const [queryFilters, setQueryFilters] = useState<AuditLogFilters | null>(null);
     const [page, setPage] = useState(0);
     const [entries, setEntries] = useState<AuditLogEntry[]>([]);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
+    const debounceTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
 
     useEffect(() => {
-        setFilters(readFiltersFromUrl());
+        const initial = readFiltersFromUrl();
+        setFilters(initial);
+        setQueryFilters(initial);
+        return () => clearTimeout(debounceTimer.current);
     }, []);
 
     useEffect(() => {
+        if (!queryFilters) {
+            return;
+        }
+        // Only the latest filters/page's response is applied, so a slow earlier fetch can't overwrite it.
+        let cancelled = false;
         setLoading(true);
         setError(null);
-        listAuditLog(filters, { page, limit: PAGE_SIZE })
-            .then(setEntries)
-            .catch((err) => setError(err instanceof ApiRequestError ? err.message : "Could not load the audit log."))
-            .finally(() => setLoading(false));
-    }, [filters, page]);
+        listAuditLog(queryFilters, { page, limit: PAGE_SIZE })
+            .then((data) => {
+                if (!cancelled) setEntries(data);
+            })
+            .catch((err) => {
+                if (!cancelled) setError(err instanceof ApiRequestError ? err.message : "Could not load the audit log.");
+            })
+            .finally(() => {
+                if (!cancelled) setLoading(false);
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [queryFilters, page]);
 
     function updateFilter(key: keyof AuditLogFilters, value: string) {
         const next: AuditLogFilters = { ...filters, [key]: value || undefined };
         setFilters(next);
-        setPage(0);
+        clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(() => {
+            setQueryFilters(next);
+            setPage(0);
+        }, FILTER_DEBOUNCE_MS);
 
         const params = new URLSearchParams();
         for (const k of FILTER_KEYS) {