@rapidmx/web-client 0.4.0 → 0.6.0

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -11,6 +11,7 @@ import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
+import { mergePluginNavItems, PluginNav } from "../../../plugins/pluginNav.js";
 
 export interface SettingsSectionDef {
     id: string;
@@ -26,16 +27,26 @@ export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
     { id: "labels", href: "/settings/labels", label: "Labels" },
     { id: "focused-inbox", href: "/settings/focused-inbox", label: "Focused Inbox" },
     { id: "read-receipts", href: "/settings/read-receipts", label: "Read Receipts" },
-    { id: "booking-types", href: "/settings/booking-types", label: "Booking Links" },
     { id: "encryption", href: "/settings/encryption", label: "Encryption" },
     { id: "sharing", href: "/settings/sharing", label: "Sharing" },
     { id: "privacy", href: "/settings/privacy", label: "Privacy & Data" },
 ];
 
-export type SettingsSectionId = (typeof SETTINGS_SECTIONS)[number]["id"];
+/** A `SETTINGS_SECTIONS` id, or a plugin's `settingsSections` item id (see `PluginNav`). */
+export type SettingsSectionId = string;
+
+/** `SETTINGS_SECTIONS` followed by the plugins' `settingsSections` items, core ids winning - see
+ * `mergePluginNavItems`. */
+export function settingsSections(pluginNav?: PluginNav): SettingsSectionDef[] {
+    return mergePluginNavItems<SettingsSectionDef>(SETTINGS_SECTIONS, pluginNav?.settingsSections, ({ id, href, label }) => ({
+        id,
+        href,
+        label,
+    }));
+}
 
 export interface SettingsShellProps extends Omit<AppShellProps, "active"> {
-    /** Which entry in `SETTINGS_SECTIONS` is highlighted in this shell's own sidebar — distinct from
+    /** Which entry in `SETTINGS_SECTIONS` (or plugin `settingsSections` item) is highlighted in this shell's own sidebar — distinct from
      * `AppShell`'s own `active` (always hardcoded to `"settings"` below), since Settings isn't a rail
      * icon (see `AppShell.tsx`'s `AppShellApp` doc comment) but still needs its own section
      * highlighting. Each settings page passes its own section id explicitly, the same "gotcha" this
@@ -74,6 +85,7 @@ export default function SettingsShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    pluginNav,
     children,
 }: PropsWithChildren<SettingsShellProps>) {
     const [status, setStatus] = useState<Status>("checking");
@@ -130,6 +142,7 @@ export default function SettingsShell({
             </div>
         );
     } else if (userUid && status === "ready") {
+        const sections = settingsSections(pluginNav);
         // A function, not a plain JSX constant — same reasoning as ContactsShell's identical comment:
         // rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously mounted, so the
         // `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
@@ -148,11 +161,11 @@ export default function SettingsShell({
                             className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
                             value={mailboxUid}
                             onChange={(e) => {
-                                // `active` always names a real entry in `SETTINGS_SECTIONS` — every settings
-                                // page passes its own section id explicitly (see `SettingsShellProps.active`'s
-                                // own doc comment), so this lookup can't miss.
-                                const section = SETTINGS_SECTIONS.find((s) => s.id === active)!;
-                                window.location.href = `${section.href}?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                // Every core settings page passes its own section id (see
+                                // `SettingsShellProps.active`), but a plugin page's section is missing when the
+                                // server didn't send its nav item, so that falls back to the current path.
+                                const href = sections.find((s) => s.id === active)?.href ?? window.location.pathname;
+                                window.location.href = `${href}?mailboxUid=${encodeURIComponent(e.target.value)}`;
                             }}
                         >
                             {mailboxes.map((mb) => (
@@ -165,7 +178,7 @@ export default function SettingsShell({
                     </div>
                 )}
                 <nav aria-label="Settings sections" className="flex flex-col gap-0.5">
-                    {SETTINGS_SECTIONS.map((section) => (
+                    {sections.map((section) => (
                         <a
                             key={section.id}
                             // `inner` (this whole branch) is only ever computed once `status === "ready"`
@@ -220,6 +233,7 @@ export default function SettingsShell({
             impersonating={impersonating}
             impersonationBaseUrl={impersonationBaseUrl}
             trusted={trusted}
+            pluginNav={pluginNav}
         >
             {inner}
         </AppShell>

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

@@ -1,199 +1,201 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
-import { HiOutlineBars3 } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
-import { Folder, Mailbox, listFolders, 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, { AppShellProps } from "../../layout/AppShell.js";
-import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
-
-export type TasksShellProps = Omit<AppShellProps, "active">;
-
-export interface TasksShellContextValue {
-    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
-    mailboxUid?: string;
-    /** The selected mailbox's single `tasks`-type folder. */
-    folderUid?: string;
-    mailboxes: Mailbox[];
-    /** The caller's own uid — exposed here (rather than only as `AppShell`'s prop) so the page content
-     * can compute "assigned to me" without needing it threaded through separately. */
-    userUid?: string;
-}
-
-const TasksShellContext = createContext<TasksShellContextValue>({ mailboxes: [] });
-
-/** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
-export function useTasksShell(): TasksShellContextValue {
-    return useContext(TasksShellContext);
-}
-
-type Status = "checking" | "error" | "ready";
-
-/**
- * The Tasks app's shell — structurally identical to `ContactsShell` (a mailbox has exactly one
- * well-known `tasks` folder, guaranteed to exist by `BaseMailboxRoute.create()`'s eager provisioning
- * in `@rapidmx/restapi`), just bound to a different folder type. Kept as its own small component
- * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
- * grow its own app-specific controls later without threading extra props through a shared one.
- */
-export default function TasksShell({
-    userUid,
-    authServerUrl,
-    impersonating,
-    impersonationBaseUrl,
-    trusted,
-    children,
-}: PropsWithChildren<TasksShellProps>) {
-    const [status, setStatus] = useState<Status>("checking");
-    const [error, setError] = useState<string | null>(null);
-    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
-    const [folders, setFolders] = useState<Folder[]>([]);
-    const [folderError, setFolderError] = useState<string | null>(null);
-    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
-    const [drawerOpen, setDrawerOpen] = useState(false);
-
-    useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
-
-    useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        listMailboxes({ limit: 100 })
-            .then((result) => {
-                setMailboxes(result);
-                setStatus("ready");
-            })
-            .catch((err) => {
-                setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
-                setStatus("error");
-            });
-    }, [userUid]);
-
-    const mailboxUid: string | undefined =
-        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
-        mailboxes[0]?.uid;
-
-    useEffect(() => {
-        if (!mailboxUid) {
-            setFolders([]);
-            return;
-        }
-        setFolderError(null);
-        listFolders(mailboxUid)
-            .then(setFolders)
-            .catch((err) => setFolderError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox's tasks folder."));
-    }, [mailboxUid]);
-
-    const folderUid: string | undefined = folders.find((f) => f.type === "tasks")?.uid;
-
-    const contextValue = useMemo<TasksShellContextValue>(
-        () => ({ mailboxUid, folderUid, mailboxes, userUid }),
-        [mailboxUid, folderUid, mailboxes, userUid],
-    );
-
-    // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else
-    // for a mailbox-less caller to do here yet, so the icon rail/header don't render at all.
-    if (userUid && status === "ready" && !mailboxUid) {
-        return <MailboxProvisioning />;
-    }
-
-    let inner: ReactNode = null;
-    if (userUid && status === "checking") {
-        // Renders immediately (no network round trip needed) so switching into Tasks never shows a
-        // blank pane while `listMailboxes()` is in flight — the real sidebar (My Day/Important/Planned/
-        // lists) lives in `apps/www/tasks/index.tsx`'s own content, so this mimics its rough shape rather
-        // than the (minimal, mailbox-switcher-only) shape of this shell's own sidebar.
-        inner = (
-            <aside className="w-56 shrink-0 bg-surface border-r border-border flex flex-col p-3 gap-4">
-                <Skeleton height="h-9" />
-                <SkeletonList count={5} />
-            </aside>
-        );
-    } else if (userUid && status === "error") {
-        inner = (
-            <div className="flex-1 flex items-center justify-center p-8">
-                <div className="w-full max-w-md">
-                    <Alert>{error}</Alert>
-                </div>
-            </div>
-        );
-    } else if (userUid && status === "ready") {
-        // A function, not a plain JSX constant — see MailShell/ContactsShell/CalendarShell's identical
-        // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
-        // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
-        const sidebarContent = (idPrefix: string) => (
-            <>
-                {mailboxes.length > 1 && (
-                    <div>
-                        <label
-                            className="block text-xs font-bold uppercase tracking-wide text-text-muted mb-1"
-                            htmlFor={`${idPrefix}-tasks-mailbox-switcher`}
-                        >
-                            Mailbox
-                        </label>
-                        <select
-                            id={`${idPrefix}-tasks-mailbox-switcher`}
-                            className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
-                            value={mailboxUid}
-                            onChange={(e) => {
-                                window.location.href = `/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`;
-                            }}
-                        >
-                            {mailboxes.map((mb) => (
-                                <option key={mb.uid} value={mb.uid}>
-                                    {mb.displayName}
-                                    {mb.ownerUserUid ? "" : " (shared)"}
-                                </option>
-                            ))}
-                        </select>
-                    </div>
-                )}
-                {folderError && <Alert>{folderError}</Alert>}
-            </>
-        );
-
-        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>
-                <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) && (
-                        <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"
-                            aria-label="Open mailbox switcher"
-                            onClick={() => setDrawerOpen(true)}
-                        >
-                            <HiOutlineBars3 size={20} aria-hidden="true" />
-                        </button>
-                    )}
-                    <TasksShellContext.Provider value={contextValue}>{children}</TasksShellContext.Provider>
-                </main>
-            </>
-        );
-    }
-
-    return (
-        <AppShell
-            active="tasks"
-            userUid={userUid}
-            authServerUrl={authServerUrl}
-            impersonating={impersonating}
-            impersonationBaseUrl={impersonationBaseUrl}
-            trusted={trusted}
-        >
-            {inner}
-        </AppShell>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import { HiOutlineBars3 } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { Folder, Mailbox, listFolders, 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, { AppShellProps } from "../../layout/AppShell.js";
+import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
+
+export type TasksShellProps = Omit<AppShellProps, "active">;
+
+export interface TasksShellContextValue {
+    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
+    mailboxUid?: string;
+    /** The selected mailbox's single `tasks`-type folder. */
+    folderUid?: string;
+    mailboxes: Mailbox[];
+    /** The caller's own uid — exposed here (rather than only as `AppShell`'s prop) so the page content
+     * can compute "assigned to me" without needing it threaded through separately. */
+    userUid?: string;
+}
+
+const TasksShellContext = createContext<TasksShellContextValue>({ mailboxes: [] });
+
+/** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
+export function useTasksShell(): TasksShellContextValue {
+    return useContext(TasksShellContext);
+}
+
+type Status = "checking" | "error" | "ready";
+
+/**
+ * The Tasks app's shell — structurally identical to `ContactsShell` (a mailbox has exactly one
+ * well-known `tasks` folder, guaranteed to exist by `BaseMailboxRoute.create()`'s eager provisioning
+ * in `@rapidmx/restapi`), just bound to a different folder type. Kept as its own small component
+ * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
+ * grow its own app-specific controls later without threading extra props through a shared one.
+ */
+export default function TasksShell({
+    userUid,
+    authServerUrl,
+    impersonating,
+    impersonationBaseUrl,
+    trusted,
+    pluginNav,
+    children,
+}: PropsWithChildren<TasksShellProps>) {
+    const [status, setStatus] = useState<Status>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
+    const [folders, setFolders] = useState<Folder[]>([]);
+    const [folderError, setFolderError] = useState<string | null>(null);
+    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
+    const [drawerOpen, setDrawerOpen] = useState(false);
+
+    useEffect(() => {
+        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
+    }, []);
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        listMailboxes({ limit: 100 })
+            .then((result) => {
+                setMailboxes(result);
+                setStatus("ready");
+            })
+            .catch((err) => {
+                setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
+                setStatus("error");
+            });
+    }, [userUid]);
+
+    const mailboxUid: string | undefined =
+        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
+        mailboxes[0]?.uid;
+
+    useEffect(() => {
+        if (!mailboxUid) {
+            setFolders([]);
+            return;
+        }
+        setFolderError(null);
+        listFolders(mailboxUid)
+            .then(setFolders)
+            .catch((err) => setFolderError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox's tasks folder."));
+    }, [mailboxUid]);
+
+    const folderUid: string | undefined = folders.find((f) => f.type === "tasks")?.uid;
+
+    const contextValue = useMemo<TasksShellContextValue>(
+        () => ({ mailboxUid, folderUid, mailboxes, userUid }),
+        [mailboxUid, folderUid, mailboxes, userUid],
+    );
+
+    // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else
+    // for a mailbox-less caller to do here yet, so the icon rail/header don't render at all.
+    if (userUid && status === "ready" && !mailboxUid) {
+        return <MailboxProvisioning />;
+    }
+
+    let inner: ReactNode = null;
+    if (userUid && status === "checking") {
+        // Renders immediately (no network round trip needed) so switching into Tasks never shows a
+        // blank pane while `listMailboxes()` is in flight — the real sidebar (My Day/Important/Planned/
+        // lists) lives in `apps/www/tasks/index.tsx`'s own content, so this mimics its rough shape rather
+        // than the (minimal, mailbox-switcher-only) shape of this shell's own sidebar.
+        inner = (
+            <aside className="w-56 shrink-0 bg-surface border-r border-border flex flex-col p-3 gap-4">
+                <Skeleton height="h-9" />
+                <SkeletonList count={5} />
+            </aside>
+        );
+    } else if (userUid && status === "error") {
+        inner = (
+            <div className="flex-1 flex items-center justify-center p-8">
+                <div className="w-full max-w-md">
+                    <Alert>{error}</Alert>
+                </div>
+            </div>
+        );
+    } else if (userUid && status === "ready") {
+        // A function, not a plain JSX constant — see MailShell/ContactsShell/CalendarShell's identical
+        // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
+        // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
+        const sidebarContent = (idPrefix: string) => (
+            <>
+                {mailboxes.length > 1 && (
+                    <div>
+                        <label
+                            className="block text-xs font-bold uppercase tracking-wide text-text-muted mb-1"
+                            htmlFor={`${idPrefix}-tasks-mailbox-switcher`}
+                        >
+                            Mailbox
+                        </label>
+                        <select
+                            id={`${idPrefix}-tasks-mailbox-switcher`}
+                            className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                            value={mailboxUid}
+                            onChange={(e) => {
+                                window.location.href = `/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                            }}
+                        >
+                            {mailboxes.map((mb) => (
+                                <option key={mb.uid} value={mb.uid}>
+                                    {mb.displayName}
+                                    {mb.ownerUserUid ? "" : " (shared)"}
+                                </option>
+                            ))}
+                        </select>
+                    </div>
+                )}
+                {folderError && <Alert>{folderError}</Alert>}
+            </>
+        );
+
+        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>
+                <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) && (
+                        <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"
+                            aria-label="Open mailbox switcher"
+                            onClick={() => setDrawerOpen(true)}
+                        >
+                            <HiOutlineBars3 size={20} aria-hidden="true" />
+                        </button>
+                    )}
+                    <TasksShellContext.Provider value={contextValue}>{children}</TasksShellContext.Provider>
+                </main>
+            </>
+        );
+    }
+
+    return (
+        <AppShell
+            active="tasks"
+            userUid={userUid}
+            authServerUrl={authServerUrl}
+            impersonating={impersonating}
+            impersonationBaseUrl={impersonationBaseUrl}
+            trusted={trusted}
+            pluginNav={pluginNav}
+        >
+            {inner}
+        </AppShell>
+    );
+}

package/apps/shared/mail/listAllPages.ts

@@ -0,0 +1,39 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** Page size the list pages (Contacts, Tasks) request per call - restapi caps `limit` at 500. */
+export const LIST_PAGE_SIZE = 500;
+
+/** Safety cap on pages fetched - stops a server that ignores `page` (and keeps returning a full first
+ * page) from looping forever. 40 pages x 500 = 20,000 items. */
+export const MAX_LIST_PAGES = 40;
+
+export interface ListAllPagesResult<T> {
+    items: T[];
+    /** `true` when fetching stopped at `maxPages` with the last page still full - there may be more items
+     * the caller isn't showing, so it should say so rather than presenting `items` as the whole list. */
+    truncated: boolean;
+}
+
+/**
+ * Fetches every page of a zero-based `limit`/`page` list endpoint, stopping at the first short page
+ * (fewer than `pageSize` items) - so a folder with more items than one page holds is shown in full
+ * rather than silently cut off at the first page. Stops at `maxPages` regardless, reporting `truncated`.
+ */
+export async function listAllPages<T>(
+    fetchPage: (page: number) => Promise<T[]>,
+    pageSize: number = LIST_PAGE_SIZE,
+    maxPages: number = MAX_LIST_PAGES,
+): Promise<ListAllPagesResult<T>> {
+    const items: T[] = [];
+    for (let page = 0; page < maxPages; page++) {
+        const batch = await fetchPage(page);
+        items.push(...batch);
+        if (batch.length < pageSize) {
+            return { items, truncated: false };
+        }
+    }
+    return { items, truncated: true };
+}

package/apps/shared/plugins/pluginNav.ts

@@ -0,0 +1,73 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * One navigation entry a plugin contributes through its manifest's `ui` field. Structurally identical to
+ * `@rapidmx/restapi`'s `PluginUiNavItem`, defined locally so this package doesn't depend on restapi.
+ */
+export interface PluginUiNavItem {
+    /** Unique within its list. A plugin page passes this as its shell's `active` to highlight the entry. */
+    id: string;
+    label: string;
+    /** A same-origin path under the host's prefix (`/settings/...`, `/admin/...`, `/...`). */
+    href: string;
+}
+
+/**
+ * The navigation every enabled plugin with a successfully built UI contributes, supplied by the server's
+ * `WwwRoute`/`AdminConsoleRoute` `fetchProps` as the `pluginNav` page prop.
+ */
+export interface PluginNav {
+    /** Appended to `SettingsShell`'s section list. */
+    settingsSections?: PluginUiNavItem[];
+    /** Appended to `AdminShell`'s icon rail and mobile tab bar. */
+    adminNav?: PluginUiNavItem[];
+    /** Appended to `AppShell`'s app rail and mobile tab bar. */
+    appRail?: PluginUiNavItem[];
+}
+
+/** The page prop every www and admin page receives - extended by `AppShellProps` and `AdminShellProps`, so
+ * a page that spreads its props onto its shell passes `pluginNav` through with no code of its own. */
+export interface PluginNavProps {
+    pluginNav?: PluginNav;
+}
+
+/** A same-origin absolute path: starts with `/`, but not `//` or `/\` (both of which browsers treat as
+ * protocol-relative URLs to another host). */
+export function isSafePluginHref(href: string): boolean {
+    return /^\/(?![/\\])/.test(href);
+}
+
+/**
+ * Appends a plugin's nav items after the core ones. Skips any item that isn't well-formed, whose `href`
+ * isn't a same-origin path (see `isSafePluginHref`), or whose id is already taken - by a core item or
+ * `reservedIds` (core ids always win) or by an earlier plugin item.
+ */
+export function mergePluginNavItems<T extends { id: string }>(
+    coreItems: T[],
+    pluginItems: PluginUiNavItem[] | undefined,
+    toItem: (item: PluginUiNavItem) => T,
+    reservedIds: string[] = [],
+): T[] {
+    if (!pluginItems?.length) {
+        return coreItems;
+    }
+    const taken = new Set([...coreItems.map((item) => item.id), ...reservedIds]);
+    const merged = [...coreItems];
+    for (const item of pluginItems) {
+        if (
+            typeof item?.id !== "string" ||
+            typeof item.label !== "string" ||
+            typeof item.href !== "string" ||
+            !isSafePluginHref(item.href) ||
+            taken.has(item.id)
+        ) {
+            continue;
+        }
+        taken.add(item.id);
+        merged.push(toItem(item));
+    }
+    return merged;
+}