@rapidmx/web-client 0.5.0 → 0.6.0

package/apps/shared/components/contacts/layout/ContactsShell.tsx

@@ -1,197 +1,199 @@
-///////////////////////////////////////////////////////////////////////////////
-// 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 ContactsShellProps = Omit<AppShellProps, "active">;
-
-export interface ContactsShellContextValue {
-    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
-    mailboxUid?: string;
-    /** The selected mailbox's single `contacts`-type folder. */
-    folderUid?: string;
-    mailboxes: Mailbox[];
-}
-
-const ContactsShellContext = createContext<ContactsShellContextValue>({ mailboxes: [] });
-
-/** Reads the mailbox/folder Contacts is currently showing, as resolved by the enclosing `ContactsShell`. */
-export function useContactsShell(): ContactsShellContextValue {
-    return useContext(ContactsShellContext);
-}
-
-type Status = "checking" | "error" | "ready";
-
-/**
- * The Contacts app's shell: unlike `MailShell` (a folder tree, since a mailbox has many mail folders),
- * a mailbox has exactly one well-known `contacts` folder — see `BaseMailboxRoute.create()`'s eager
- * provisioning in `@rapidmx/restapi`, which guarantees it exists for every mailbox. This shell's own
- * sidebar is therefore just a mailbox switcher (when the caller has more than one); the actual contact
- * list/detail UI is `apps/www/contacts/index.tsx`'s own content, rendered as `children` here.
- */
-export default function ContactsShell({
-    userUid,
-    authServerUrl,
-    impersonating,
-    impersonationBaseUrl,
-    trusted,
-    children,
-}: PropsWithChildren<ContactsShellProps>) {
-    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 contacts folder."));
-    }, [mailboxUid]);
-
-    const folderUid: string | undefined = folders.find((f) => f.type === "contacts")?.uid;
-
-    const contextValue = useMemo<ContactsShellContextValue>(
-        () => ({ mailboxUid, folderUid, mailboxes }),
-        [mailboxUid, folderUid, mailboxes],
-    );
-
-    // 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 Contacts never shows a
-        // blank pane while `listMailboxes()` is in flight — the real sidebar (favorites/lists/categories)
-        // lives in `apps/www/contacts/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 = (
-            <div className="w-56 shrink-0 border-r border-border flex flex-col gap-4 p-3">
-                <Skeleton height="h-9" />
-                <SkeletonList count={5} />
-            </div>
-        );
-    } 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'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 to avoid a duplicate-id
-        // label-association break.
-        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}-contacts-mailbox-switcher`}
-                        >
-                            Mailbox
-                        </label>
-                        <select
-                            id={`${idPrefix}-contacts-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 = `/contacts?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>
-                    )}
-                    <ContactsShellContext.Provider value={contextValue}>{children}</ContactsShellContext.Provider>
-                </main>
-            </>
-        );
-    }
-
-    return (
-        <AppShell
-            active="contacts"
-            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 ContactsShellProps = Omit<AppShellProps, "active">;
+
+export interface ContactsShellContextValue {
+    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
+    mailboxUid?: string;
+    /** The selected mailbox's single `contacts`-type folder. */
+    folderUid?: string;
+    mailboxes: Mailbox[];
+}
+
+const ContactsShellContext = createContext<ContactsShellContextValue>({ mailboxes: [] });
+
+/** Reads the mailbox/folder Contacts is currently showing, as resolved by the enclosing `ContactsShell`. */
+export function useContactsShell(): ContactsShellContextValue {
+    return useContext(ContactsShellContext);
+}
+
+type Status = "checking" | "error" | "ready";
+
+/**
+ * The Contacts app's shell: unlike `MailShell` (a folder tree, since a mailbox has many mail folders),
+ * a mailbox has exactly one well-known `contacts` folder — see `BaseMailboxRoute.create()`'s eager
+ * provisioning in `@rapidmx/restapi`, which guarantees it exists for every mailbox. This shell's own
+ * sidebar is therefore just a mailbox switcher (when the caller has more than one); the actual contact
+ * list/detail UI is `apps/www/contacts/index.tsx`'s own content, rendered as `children` here.
+ */
+export default function ContactsShell({
+    userUid,
+    authServerUrl,
+    impersonating,
+    impersonationBaseUrl,
+    trusted,
+    pluginNav,
+    children,
+}: PropsWithChildren<ContactsShellProps>) {
+    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 contacts folder."));
+    }, [mailboxUid]);
+
+    const folderUid: string | undefined = folders.find((f) => f.type === "contacts")?.uid;
+
+    const contextValue = useMemo<ContactsShellContextValue>(
+        () => ({ mailboxUid, folderUid, mailboxes }),
+        [mailboxUid, folderUid, mailboxes],
+    );
+
+    // 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 Contacts never shows a
+        // blank pane while `listMailboxes()` is in flight — the real sidebar (favorites/lists/categories)
+        // lives in `apps/www/contacts/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 = (
+            <div className="w-56 shrink-0 border-r border-border flex flex-col gap-4 p-3">
+                <Skeleton height="h-9" />
+                <SkeletonList count={5} />
+            </div>
+        );
+    } 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'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 to avoid a duplicate-id
+        // label-association break.
+        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}-contacts-mailbox-switcher`}
+                        >
+                            Mailbox
+                        </label>
+                        <select
+                            id={`${idPrefix}-contacts-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 = `/contacts?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>
+                    )}
+                    <ContactsShellContext.Provider value={contextValue}>{children}</ContactsShellContext.Provider>
+                </main>
+            </>
+        );
+    }
+
+    return (
+        <AppShell
+            active="contacts"
+            userUid={userUid}
+            authServerUrl={authServerUrl}
+            impersonating={impersonating}
+            impersonationBaseUrl={impersonationBaseUrl}
+            trusted={trusted}
+            pluginNav={pluginNav}
+        >
+            {inner}
+        </AppShell>
+    );
+}

package/apps/shared/components/layout/AppShell.tsx

@@ -5,7 +5,13 @@
 import "../../styles/app.css";
 import React, { PropsWithChildren, useEffect, useRef, useState } from "react";
 import type { IconType } from "react-icons";
-import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import {
+    HiOutlineCalendarDays,
+    HiOutlineClipboardDocumentList,
+    HiOutlineEnvelope,
+    HiOutlinePuzzlePiece,
+    HiOutlineUsers,
+} from "react-icons/hi2";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
@@ -13,7 +19,7 @@ import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
 import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeout.js";
 import ComposeProvider from "../mail/compose/ComposeContext.js";
 import { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
-import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
 import UserMenu from "./UserMenu.js";
 import { UnlockPromptProvider } from "./UnlockPromptProvider.js";
@@ -21,6 +27,7 @@ import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localInde
 import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
 import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
 
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export const LOGOUT_TIMEOUT_MS = 3_000;
@@ -49,11 +56,13 @@ export type AppShellApp = "mail" | "calendar" | "contacts" | "tasks";
 
 /** `"settings"` is a valid `active` value but deliberately has no entry in `APPS` below — Settings is
  * reached via a `UserMenu` item, not a 5th rail icon (see `SettingsShell.tsx`), so it highlights no
- * rail/tab icon at all; only the header title (`ACTIVE_LABELS` below) needs to account for it. */
-export type AppShellActive = AppShellApp | "settings";
+ * rail/tab icon at all; only the header title needs to account for it. Any other string is a plugin's
+ * `appRail` item id (see `PluginNav`). */
+export type AppShellActive = AppShellApp | "settings" | (string & {});
 
-export interface AppShellProps {
-    /** Which icon in the rail is highlighted as the current app — `"settings"` highlights none. */
+export interface AppShellProps extends PluginNavProps {
+    /** Which icon in the rail is highlighted as the current app — `"settings"` highlights none, and a plugin
+     * app page passes its own `appRail` item id. */
     active: AppShellActive;
     /** Populated automatically by the framework from an authenticated request (e.g. a valid `jwt` cookie). */
     userUid?: string;
@@ -85,15 +94,19 @@ export const APPS: AppDef[] = [
     { id: "tasks", href: "/tasks", label: "Tasks", icon: HiOutlineClipboardDocumentList },
 ];
 
-/** The header title for every valid `active` value — a superset of `APPS`' own labels since `"settings"`
- * has no rail icon (and so no `AppDef`) but still needs a header title. */
-const ACTIVE_LABELS: Record<AppShellActive, string> = {
-    mail: "Mail",
-    calendar: "Calendar",
-    contacts: "Contacts",
-    tasks: "Tasks",
-    settings: "Settings",
-};
+/** Ids plugin `appRail` items can't take besides `APPS`' own - `"settings"` has no rail icon but is still a
+ * core `active` value. */
+const RESERVED_APP_IDS = ["settings"];
+
+/** `APPS` followed by the plugins' `appRail` items (generic icon), core ids winning - see `mergePluginNavItems`. */
+export function appRailItems(pluginNav?: PluginNav): NavItem[] {
+    return mergePluginNavItems<NavItem>(
+        APPS,
+        pluginNav?.appRail,
+        ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }),
+        RESERVED_APP_IDS,
+    );
+}
 
 /**
  * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
@@ -109,6 +122,7 @@ export default function AppShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    pluginNav,
     children,
 }: PropsWithChildren<AppShellProps>) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
@@ -204,6 +218,10 @@ export default function AppShell({
         return <div className="min-h-screen" />;
     }
 
+    const apps = appRailItems(pluginNav);
+    // The header title: "settings" has no rail item, everything else is labelled by its own rail item.
+    const activeLabel = active === "settings" ? "Settings" : apps.find((app) => app.id === active)?.label;
+
     return (
         // Mounted here, not scoped to Mail/Settings, for the same reason as useIdleKeyTimeout() above -
         // ComposeWindow's sign/encrypt toggles and MessageDetailPane's encrypted-message view (both Mail)
@@ -235,7 +253,7 @@ export default function AppShell({
                         className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
                     >
                         <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
-                        {APPS.map(({ id, href, label, icon: Icon }) => (
+                        {apps.map(({ id, href, label, icon: Icon }) => (
                             <a
                                 key={id}
                                 href={href}
@@ -253,10 +271,10 @@ export default function AppShell({
                             </a>
                         ))}
                     </nav>
-                    <BottomTabBar apps={APPS} active={active} />
+                    <BottomTabBar apps={apps} active={active} />
                     <div className="flex-1 flex flex-col min-w-0">
                         <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
-                            <span className="font-display font-bold text-lg uppercase tracking-wide">{ACTIVE_LABELS[active]}</span>
+                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeLabel}</span>
                             <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} showAdminLink={trusted} showSettingsLink />
                         </header>
                         <div className="flex-1 flex min-h-0 pb-14 md:pb-0">{children}</div>