@rapidmx/web-client 0.5.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/shared/components/admin/layout/AdminShell.tsx

@@ -30,6 +30,7 @@ import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigati
 import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
 import UserMenu from "../../layout/UserMenu.js";
 import { signOutOfConsole } from "../signOut.js";
+import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../../plugins/pluginNav.js";
 
 export type AdminSection =
     | "mailboxes"
@@ -48,9 +49,13 @@ export type AdminSection =
     | "plugins"
     | "branding";
 
-export interface AdminShellProps {
-    /** Which icon in the rail is highlighted as the current section. */
-    active: AdminSection;
+/** A core `AdminSection`, or a plugin's `adminNav` item id (see `PluginNav`). */
+export type AdminShellActive = AdminSection | (string & {});
+
+export interface AdminShellProps extends PluginNavProps {
+    /** Which icon in the rail is highlighted as the current section - a plugin admin page passes its own
+     * `adminNav` item id. */
+    active: AdminShellActive;
     /** Populated automatically by the framework from an authenticated request (e.g. a valid `jwt` cookie). */
     userUid?: string;
     /** auth-server's base URL, injected via the route's `fetchProps` — see `src/mongo/routes/AdminConsoleRoute.ts`. */
@@ -129,7 +134,18 @@ const MAILBOX_SCOPED_ITEMS: NavItem[] = [
 /** The setup wizard - reached by redirect or from the Mailboxes page, not from the rail. */
 const SETUP_ITEM: NavItem = { id: "setup", href: "/admin/setup", label: "Setup", icon: HiOutlineRocketLaunch };
 
-const ALL_ITEMS: NavItem[] = [...NAV_ITEMS, ...MAILBOX_SCOPED_ITEMS, SETUP_ITEM];
+const OFF_RAIL_ITEMS: NavItem[] = [...MAILBOX_SCOPED_ITEMS, SETUP_ITEM];
+
+/** `NAV_ITEMS` followed by the plugins' `adminNav` items (generic icon). Core ids win, including the
+ * off-rail sections' - see `mergePluginNavItems`. */
+export function adminNavItems(pluginNav?: PluginNav): NavItem[] {
+    return mergePluginNavItems<NavItem>(
+        NAV_ITEMS,
+        pluginNav?.adminNav,
+        ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }),
+        OFF_RAIL_ITEMS.map((item) => item.id),
+    );
+}
 
 /**
  * Gates every `apps/admin` page behind the `admin` trusted role. Uses `GET /api/admin/release-notes` (any
@@ -137,7 +153,7 @@ const ALL_ITEMS: NavItem[] = [...NAV_ITEMS, ...MAILBOX_SCOPED_ITEMS, SETUP_ITEM]
  * caller's JWT carries a trusted role, a 403 means it doesn't. There is no local step-up/elevation flow
  * (that would need a cross-origin call to auth-server's own elevation endpoint — not wired up yet).
  */
-export default function AdminShell({ active, userUid, authServerUrl, children }: PropsWithChildren<AdminShellProps>) {
+export default function AdminShell({ active, userUid, authServerUrl, pluginNav, children }: PropsWithChildren<AdminShellProps>) {
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
     const { branding, iconSrc } = useBranding();
@@ -199,7 +215,8 @@ export default function AdminShell({ active, userUid, authServerUrl, children }:
             </div>
         );
     } else {
-        const activeItem = ALL_ITEMS.find((item) => item.id === active);
+        const navItems = adminNavItems(pluginNav);
+        const activeItem = [...navItems, ...OFF_RAIL_ITEMS].find((item) => item.id === active);
         content = (
             <div className="min-h-screen flex flex-col bg-surface-alt">
                 <div className="flex-1 flex min-h-0">
@@ -208,7 +225,7 @@ export default function AdminShell({ active, userUid, authServerUrl, children }:
                         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" />
-                        {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
+                        {navItems.map(({ id, href, label, icon: Icon }) => (
                             <a
                                 key={id}
                                 href={href}
@@ -226,7 +243,7 @@ export default function AdminShell({ active, userUid, authServerUrl, children }:
                             </a>
                         ))}
                     </nav>
-                    <BottomTabBar apps={NAV_ITEMS} active={active} />
+                    <BottomTabBar apps={navItems} 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">{activeItem?.label}</span>

package/apps/shared/components/calendar/layout/CalendarShell.tsx

@@ -1,192 +1,194 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React, { createContext, PropsWithChildren, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { accentColorForMailbox, colorForFolder } from "@rapidmx/react-shared/calendar/calendarColors.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 CalendarShellProps = Omit<AppShellProps, "active">;
-
-/** One mailbox's own `calendar`-type folders. `error` is set (and `calendarFolders` left empty) when that
- * mailbox's own `listFolders()` failed - one mailbox's failure never hides every other mailbox's calendars. */
-export interface MailboxCalendars {
-    mailbox: Mailbox;
-    calendarFolders: Folder[];
-    error?: string;
-}
-
-export interface CalendarShellContextValue {
-    /** The default mailbox for "+ New event" (`?mailboxUid=` if accessible, else the caller's own mailbox,
-     * else the first accessible one) - every accessible mailbox's calendars are shown regardless. */
-    mailboxUid?: string;
-    /** `mailboxUid`'s first `calendar`-type folder - the default target for "+ New event". */
-    folderUid?: string;
-    /** Every accessible mailbox's `calendar`-type folders, flattened - the set of calendars that can be
-     * checked/shown (see `CalendarListSidebar`). Each folder's own `mailboxUid` says which mailbox it's in. */
-    calendarFolders: Folder[];
-    /** The same folders, grouped per mailbox, for the sidebar's per-mailbox sections. */
-    mailboxCalendars: MailboxCalendars[];
-    mailboxes: Mailbox[];
-    /** Re-fetches every mailbox's folders (e.g. after creating a new calendar) without a full reload. */
-    reloadFolders: () => void;
-    /** The display color for a calendar folder: its own `color`, else the default for the caller's own
-     * mailbox, else its mailbox's `accentColorForMailbox()` - so a shared mailbox's calendar is visually
-     * distinct from the caller's own even when neither has a color set. */
-    colorFor: (folder: Folder) => string;
-}
-
-const CalendarShellContext = createContext<CalendarShellContextValue>({
-    calendarFolders: [],
-    mailboxCalendars: [],
-    mailboxes: [],
-    reloadFolders: () => undefined,
-    colorFor: (folder) => colorForFolder(folder),
-});
-
-/** Reads the calendars the Calendar is currently showing, as resolved by the enclosing `CalendarShell`. */
-export function useCalendarShell(): CalendarShellContextValue {
-    return useContext(CalendarShellContext);
-}
-
-type Status = "checking" | "error" | "ready";
-
-/**
- * The Calendar app's shell. Fetches every accessible mailbox's calendar folders in parallel so shared
- * mailboxes' calendars show alongside the caller's own, each mailbox color-coded (see `colorFor`) - there
- * is no mailbox switcher. The actual view being looked at (month/week/day, and which one) is *not* shell
- * state — it lives in `apps/www/calendar/index.tsx`'s own local state, since navigating between
- * views/dates must be instant (no full page reload) and this framework has no client-side router.
- */
-export default function CalendarShell({
-    userUid,
-    authServerUrl,
-    impersonating,
-    impersonationBaseUrl,
-    trusted,
-    children,
-}: PropsWithChildren<CalendarShellProps>) {
-    const [status, setStatus] = useState<Status>("checking");
-    const [error, setError] = useState<string | null>(null);
-    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
-    const [mailboxCalendars, setMailboxCalendars] = useState<MailboxCalendars[]>([]);
-    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
-    const [folderRefreshToken, setFolderRefreshToken] = useState(0);
-
-    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 ownMailboxUid = mailboxes.find((mb) => mb.ownerUserUid === userUid)?.uid ?? mailboxes[0]?.uid;
-    const mailboxUid: string | undefined =
-        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
-        ownMailboxUid;
-
-    useEffect(() => {
-        if (mailboxes.length === 0) {
-            setMailboxCalendars([]);
-            return;
-        }
-        let cancelled = false;
-        void Promise.all(
-            mailboxes.map((mailbox) =>
-                listFolders(mailbox.uid)
-                    .then((folders): MailboxCalendars => ({ mailbox, calendarFolders: folders.filter((f) => f.type === "calendar") }))
-                    .catch(
-                        (err): MailboxCalendars => ({
-                            mailbox,
-                            calendarFolders: [],
-                            error: err instanceof ApiRequestError ? err.message : "Could not load this mailbox's calendar folder.",
-                        }),
-                    ),
-            ),
-        ).then((result) => {
-            if (!cancelled) {
-                setMailboxCalendars(result);
-            }
-        });
-        return () => {
-            cancelled = true;
-        };
-    }, [mailboxes, folderRefreshToken]);
-
-    const calendarFolders = useMemo(() => mailboxCalendars.flatMap((mc) => mc.calendarFolders), [mailboxCalendars]);
-    const folderUid: string | undefined = calendarFolders.find((f) => f.mailboxUid === mailboxUid)?.uid;
-
-    const colorFor = useCallback(
-        (folder: Folder) => colorForFolder(folder, folder.mailboxUid === ownMailboxUid ? undefined : accentColorForMailbox(folder.mailboxUid)),
-        [ownMailboxUid],
-    );
-    const reloadFolders = useCallback(() => setFolderRefreshToken((t) => t + 1), []);
-
-    const contextValue = useMemo<CalendarShellContextValue>(
-        () => ({ mailboxUid, folderUid, calendarFolders, mailboxCalendars, mailboxes, reloadFolders, colorFor }),
-        [mailboxUid, folderUid, calendarFolders, mailboxCalendars, mailboxes, reloadFolders, colorFor],
-    );
-
-    // 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" && mailboxes.length === 0) {
-        return <MailboxProvisioning />;
-    }
-
-    let inner: ReactNode = null;
-    if (userUid && status === "checking") {
-        // Renders immediately (no network round trip needed) so switching into Calendar never shows a
-        // blank pane while `listMailboxes()` is in flight — mimics the rough shape of the real sidebar
-        // (mini date-picker + calendar list) that `apps/www/calendar/index.tsx` renders.
-        inner = (
-            <div className="w-56 shrink-0 bg-surface border-r border-border p-3 flex flex-col gap-4">
-                <Skeleton height="h-40" className="rounded-md" />
-                <SkeletonList count={4} />
-            </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") {
-        inner = (
-            <div className="flex-1 min-w-0 flex flex-col">
-                <CalendarShellContext.Provider value={contextValue}>{children}</CalendarShellContext.Provider>
-            </div>
-        );
-    }
-
-    return (
-        <AppShell
-            active="calendar"
-            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, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { accentColorForMailbox, colorForFolder } from "@rapidmx/react-shared/calendar/calendarColors.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 CalendarShellProps = Omit<AppShellProps, "active">;
+
+/** One mailbox's own `calendar`-type folders. `error` is set (and `calendarFolders` left empty) when that
+ * mailbox's own `listFolders()` failed - one mailbox's failure never hides every other mailbox's calendars. */
+export interface MailboxCalendars {
+    mailbox: Mailbox;
+    calendarFolders: Folder[];
+    error?: string;
+}
+
+export interface CalendarShellContextValue {
+    /** The default mailbox for "+ New event" (`?mailboxUid=` if accessible, else the caller's own mailbox,
+     * else the first accessible one) - every accessible mailbox's calendars are shown regardless. */
+    mailboxUid?: string;
+    /** `mailboxUid`'s first `calendar`-type folder - the default target for "+ New event". */
+    folderUid?: string;
+    /** Every accessible mailbox's `calendar`-type folders, flattened - the set of calendars that can be
+     * checked/shown (see `CalendarListSidebar`). Each folder's own `mailboxUid` says which mailbox it's in. */
+    calendarFolders: Folder[];
+    /** The same folders, grouped per mailbox, for the sidebar's per-mailbox sections. */
+    mailboxCalendars: MailboxCalendars[];
+    mailboxes: Mailbox[];
+    /** Re-fetches every mailbox's folders (e.g. after creating a new calendar) without a full reload. */
+    reloadFolders: () => void;
+    /** The display color for a calendar folder: its own `color`, else the default for the caller's own
+     * mailbox, else its mailbox's `accentColorForMailbox()` - so a shared mailbox's calendar is visually
+     * distinct from the caller's own even when neither has a color set. */
+    colorFor: (folder: Folder) => string;
+}
+
+const CalendarShellContext = createContext<CalendarShellContextValue>({
+    calendarFolders: [],
+    mailboxCalendars: [],
+    mailboxes: [],
+    reloadFolders: () => undefined,
+    colorFor: (folder) => colorForFolder(folder),
+});
+
+/** Reads the calendars the Calendar is currently showing, as resolved by the enclosing `CalendarShell`. */
+export function useCalendarShell(): CalendarShellContextValue {
+    return useContext(CalendarShellContext);
+}
+
+type Status = "checking" | "error" | "ready";
+
+/**
+ * The Calendar app's shell. Fetches every accessible mailbox's calendar folders in parallel so shared
+ * mailboxes' calendars show alongside the caller's own, each mailbox color-coded (see `colorFor`) - there
+ * is no mailbox switcher. The actual view being looked at (month/week/day, and which one) is *not* shell
+ * state — it lives in `apps/www/calendar/index.tsx`'s own local state, since navigating between
+ * views/dates must be instant (no full page reload) and this framework has no client-side router.
+ */
+export default function CalendarShell({
+    userUid,
+    authServerUrl,
+    impersonating,
+    impersonationBaseUrl,
+    trusted,
+    pluginNav,
+    children,
+}: PropsWithChildren<CalendarShellProps>) {
+    const [status, setStatus] = useState<Status>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
+    const [mailboxCalendars, setMailboxCalendars] = useState<MailboxCalendars[]>([]);
+    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
+    const [folderRefreshToken, setFolderRefreshToken] = useState(0);
+
+    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 ownMailboxUid = mailboxes.find((mb) => mb.ownerUserUid === userUid)?.uid ?? mailboxes[0]?.uid;
+    const mailboxUid: string | undefined =
+        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
+        ownMailboxUid;
+
+    useEffect(() => {
+        if (mailboxes.length === 0) {
+            setMailboxCalendars([]);
+            return;
+        }
+        let cancelled = false;
+        void Promise.all(
+            mailboxes.map((mailbox) =>
+                listFolders(mailbox.uid)
+                    .then((folders): MailboxCalendars => ({ mailbox, calendarFolders: folders.filter((f) => f.type === "calendar") }))
+                    .catch(
+                        (err): MailboxCalendars => ({
+                            mailbox,
+                            calendarFolders: [],
+                            error: err instanceof ApiRequestError ? err.message : "Could not load this mailbox's calendar folder.",
+                        }),
+                    ),
+            ),
+        ).then((result) => {
+            if (!cancelled) {
+                setMailboxCalendars(result);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [mailboxes, folderRefreshToken]);
+
+    const calendarFolders = useMemo(() => mailboxCalendars.flatMap((mc) => mc.calendarFolders), [mailboxCalendars]);
+    const folderUid: string | undefined = calendarFolders.find((f) => f.mailboxUid === mailboxUid)?.uid;
+
+    const colorFor = useCallback(
+        (folder: Folder) => colorForFolder(folder, folder.mailboxUid === ownMailboxUid ? undefined : accentColorForMailbox(folder.mailboxUid)),
+        [ownMailboxUid],
+    );
+    const reloadFolders = useCallback(() => setFolderRefreshToken((t) => t + 1), []);
+
+    const contextValue = useMemo<CalendarShellContextValue>(
+        () => ({ mailboxUid, folderUid, calendarFolders, mailboxCalendars, mailboxes, reloadFolders, colorFor }),
+        [mailboxUid, folderUid, calendarFolders, mailboxCalendars, mailboxes, reloadFolders, colorFor],
+    );
+
+    // 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" && mailboxes.length === 0) {
+        return <MailboxProvisioning />;
+    }
+
+    let inner: ReactNode = null;
+    if (userUid && status === "checking") {
+        // Renders immediately (no network round trip needed) so switching into Calendar never shows a
+        // blank pane while `listMailboxes()` is in flight — mimics the rough shape of the real sidebar
+        // (mini date-picker + calendar list) that `apps/www/calendar/index.tsx` renders.
+        inner = (
+            <div className="w-56 shrink-0 bg-surface border-r border-border p-3 flex flex-col gap-4">
+                <Skeleton height="h-40" className="rounded-md" />
+                <SkeletonList count={4} />
+            </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") {
+        inner = (
+            <div className="flex-1 min-w-0 flex flex-col">
+                <CalendarShellContext.Provider value={contextValue}>{children}</CalendarShellContext.Provider>
+            </div>
+        );
+    }
+
+    return (
+        <AppShell
+            active="calendar"
+            userUid={userUid}
+            authServerUrl={authServerUrl}
+            impersonating={impersonating}
+            impersonationBaseUrl={impersonationBaseUrl}
+            trusted={trusted}
+            pluginNav={pluginNav}
+        >
+            {inner}
+        </AppShell>
+    );
+}