@rapidmx/web-client 0.2.0

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

@@ -0,0 +1,165 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import "../../styles/app.css";
+import React, { PropsWithChildren, useState } from "react";
+import type { IconType } from "react-icons";
+import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
+import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
+import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
+import ComposeProvider from "../mail/compose/ComposeContext.js";
+import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
+import UserMenu from "./UserMenu.js";
+
+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";
+
+export interface AppShellProps {
+    /** Which icon in the rail is highlighted as the current app — `"settings"` highlights none. */
+    active: AppShellActive;
+    /** 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`. */
+    authServerUrl?: string;
+    /**
+     * `true` when this session is an admin "log in as user" impersonation (a `jwt_impersonator` cookie is
+     * present) — see `MailShell`'s original doc comment, unchanged now that this lives here. Drives the
+     * "you are viewing as this user — stop impersonating" banner below.
+     */
+    impersonating?: boolean;
+    /** Where `mailApi.ts`'s `stopImpersonating()` should call — see `MailShell`'s original doc comment. */
+    impersonationBaseUrl?: string;
+    /** `true` when the caller's JWT carries a trusted role — shows an "Admin" item in the user menu below. */
+    trusted?: boolean;
+}
+
+export interface AppDef {
+    id: AppShellApp;
+    href: string;
+    label: string;
+    icon: IconType;
+}
+
+export const APPS: AppDef[] = [
+    { id: "mail", href: "/", label: "Mail", icon: HiOutlineEnvelope },
+    { id: "calendar", href: "/calendar", label: "Calendar", icon: HiOutlineCalendarDays },
+    { id: "contacts", href: "/contacts", label: "Contacts", icon: HiOutlineUsers },
+    { 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",
+};
+
+/**
+ * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
+ * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
+ * client-side router), a header with the current app's name and `UserMenu`, and the impersonation banner.
+ * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
+ * the area to the right of the icon rail and below the header.
+ */
+export default function AppShell({
+    active,
+    userUid,
+    authServerUrl,
+    impersonating,
+    impersonationBaseUrl,
+    trusted,
+    children,
+}: PropsWithChildren<AppShellProps>) {
+    const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
+    const { branding, iconSrc } = useBranding();
+
+    useRedirectIfUnauthenticated(userUid, authServerUrl);
+
+    function handleSignOut() {
+        window.location.href = authServerUrl ?? "/";
+    }
+
+    async function handleStopImpersonating() {
+        setStoppingImpersonation(true);
+        try {
+            await stopImpersonating(impersonationBaseUrl ?? "");
+        } catch {
+            // Navigate either way: a failed call leaves the impersonator cookie (and this banner) exactly as
+            // they were, so there's nothing else useful to show — matching this app's other network-error
+            // handling, which surfaces via a full reload rather than an inline retry affordance.
+        } finally {
+            window.location.href = "/admin";
+        }
+    }
+
+    if (!userUid) {
+        return <div className="min-h-screen" />;
+    }
+
+    return (
+        <ComposeProvider>
+            <div className="min-h-screen flex flex-col bg-surface-alt">
+                <BrandingHeader branding={branding} />
+                {impersonating && (
+                    <div className="h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4">
+                        <span>
+                            You are viewing as <strong>{userUid}</strong>.
+                        </span>
+                        <button
+                            type="button"
+                            onClick={handleStopImpersonating}
+                            disabled={stoppingImpersonation}
+                            className="underline hover:no-underline disabled:opacity-60"
+                        >
+                            {stoppingImpersonation ? "Returning to admin…" : "Return to admin"}
+                        </button>
+                    </div>
+                )}
+                <div className="flex-1 flex min-h-0">
+                    <nav
+                        aria-label="Apps"
+                        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 }) => (
+                            <a
+                                key={id}
+                                href={href}
+                                aria-label={label}
+                                aria-current={id === active ? "page" : undefined}
+                                title={label}
+                                className={[
+                                    "w-10 h-10 flex items-center justify-center rounded-sm",
+                                    id === active
+                                        ? "bg-primary/10 text-primary-dark"
+                                        : "text-text-muted hover:bg-surface-alt hover:text-text",
+                                ].join(" ")}
+                            >
+                                <Icon size={20} aria-hidden="true" />
+                            </a>
+                        ))}
+                    </nav>
+                    <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>
+                            <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>
+                    </div>
+                </div>
+                <BrandingFooter branding={branding} />
+            </div>
+        </ComposeProvider>
+    );
+}

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

@@ -0,0 +1,25 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+
+/**
+ * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`) — shared by every
+ * chrome in this project (`AppShell`, `AdminShell`, and the public `apps/book` pages) so the setting applies
+ * everywhere its own admin UI copy (`apps/admin/branding/index.tsx`) claims it does.
+ */
+export function BrandingHeader({ branding }: { branding: Branding | null }) {
+    if (!branding?.headerHtml) {
+        return null;
+    }
+    return <div dangerouslySetInnerHTML={{ __html: branding.headerHtml }} />;
+}
+
+export function BrandingFooter({ branding }: { branding: Branding | null }) {
+    if (!branding?.footerHtml) {
+        return null;
+    }
+    return <div dangerouslySetInnerHTML={{ __html: branding.footerHtml }} />;
+}

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

@@ -0,0 +1,110 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { MailboxAutoProvisionAliasOption, autoProvisionMailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+
+type Status = "checking" | "needs_selection" | "creating" | "unavailable";
+
+/**
+ * Rendered by each app's shell (Mail/Calendar/Contacts/Tasks) *instead of* the normal `AppShell`
+ * chrome (icon rail, header, folder tree, ...) when the caller has no mailbox — a full-screen,
+ * 404-style takeover, not a small message nested inside the rest of the client UI, since there's
+ * nothing else in the app for a mailbox-less caller to do yet. Attempts self-service
+ * auto-provisioning — see `BaseMailboxRoute.autoProvision()`'s own doc comment in `@rapidmx/restapi`
+ * for the full contract — which is itself a no-op (a 404) unless an admin has both turned it on
+ * (`mail:auto_provision:enabled`) and configured at least one domain (`mail:domains`). Safe to render
+ * unconditionally in that place: any failure (disabled, no registered username, the identity service
+ * unreachable) just falls back to the same plain "no mailbox" message this replaces.
+ */
+export default function MailboxProvisioning() {
+    const [status, setStatus] = useState<Status>("checking");
+    const [options, setOptions] = useState<MailboxAutoProvisionAliasOption[]>([]);
+    const [selected, setSelected] = useState("");
+    const [error, setError] = useState<string | null>(null);
+
+    useEffect(() => {
+        autoProvisionMailbox()
+            .then((result) => {
+                if (result.status === "needs_selection") {
+                    // `autoProvision()` only ever returns this status with a non-empty cross product of
+                    // the caller's aliases and this server's configured domains (both are checked
+                    // non-empty before it's built) — no fallback needed for an empty list here.
+                    setOptions(result.options);
+                    setSelected(result.options[0].primarySmtpAddress);
+                    setStatus("needs_selection");
+                } else {
+                    // "created" or "existing" — either way the caller now has a mailbox; a full reload is
+                    // this framework's own convention for picking up new server-side state (no client
+                    // router to instead re-fetch just the shell's own data in place).
+                    window.location.reload();
+                }
+            })
+            .catch(() => setStatus("unavailable"));
+    }, []);
+
+    async function handleConfirm() {
+        // `selected` only ever takes a value from `options` itself (the initial default, or the
+        // <select>'s own onChange, which can only report one of its own rendered <option> values), so
+        // this is always found — no defensive fallback needed.
+        const option = options.find((o) => o.primarySmtpAddress === selected)!;
+        setStatus("creating");
+        setError(null);
+        try {
+            await autoProvisionMailbox({ alias: option.alias, domain: option.domain });
+            window.location.reload();
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not create your mailbox.");
+            setStatus("needs_selection");
+        }
+    }
+
+    let content: React.ReactNode;
+    if (status === "checking") {
+        content = <p className="text-sm text-text-muted">Setting up your mailbox&hellip;</p>;
+    } else if (status === "needs_selection" || status === "creating") {
+        const creating = status === "creating";
+        content = (
+            <div className="w-full flex flex-col gap-3">
+                <p className="text-sm text-text-muted text-center">Choose your mailbox address to get started:</p>
+                {error && <Alert>{error}</Alert>}
+                <select
+                    aria-label="Mailbox address"
+                    className="text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                    value={selected}
+                    onChange={(e) => setSelected(e.target.value)}
+                    disabled={creating}
+                >
+                    {options.map((option) => (
+                        <option key={option.primarySmtpAddress} value={option.primarySmtpAddress}>
+                            {option.primarySmtpAddress}
+                        </option>
+                    ))}
+                </select>
+                <Button type="button" onClick={handleConfirm} loading={creating} disabled={creating} className="!w-auto self-center">
+                    Continue
+                </Button>
+            </div>
+        );
+    } else {
+        content = (
+            <>
+                <h1 className="text-lg font-bold uppercase tracking-wide">No mailbox available</h1>
+                <p className="text-sm text-text-muted">Ask an administrator to create one for you.</p>
+            </>
+        );
+    }
+
+    return (
+        <div className="min-h-screen flex items-center justify-center p-8 bg-surface-alt">
+            <div className="w-full max-w-md bg-surface border border-border rounded-md p-8 flex flex-col items-center gap-4 text-center">
+                <img src="/images/wordmark.png" height="128" alt="" />
+                {content}
+            </div>
+        </div>
+    );
+}

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

@@ -0,0 +1,150 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useRef, useState } from "react";
+import { formatProfileName, getMyProfile, Profile, profileInitials } from "@rapidmx/react-shared/auth/profileApi.js";
+
+export interface UserMenuProps {
+    userUid: string;
+    /** auth-server's base URL — where the caller's own profile (name/avatar) is fetched from, if configured. */
+    authServerUrl?: string;
+    onSignOut: () => void;
+    /** Shows an "Admin" item linking to `/admin`, above "Sign Out" — pass only for a trusted-role caller. */
+    showAdminLink?: boolean;
+    /** Shows a "Settings" item, above "Admin"/"Sign Out" — an account-scoped surface (like "Admin"), not
+     * a content-scoped one, so it lives here rather than as a 5th `AppShell` rail icon. Links straight to
+     * `/settings/auto-reply`, the only settings section that exists today; repoint this at a real
+     * `/settings` landing page once a second section (Mail Filters, Signatures) makes one worth building. */
+    showSettingsLink?: boolean;
+}
+
+function Avatar({ profile, initials, large }: { profile?: Profile; initials: string; large?: boolean }) {
+    const sizeClass = large ? "w-10 h-10 text-base" : "w-8 h-8 text-sm";
+    if (profile?.avatar) {
+        return (
+            <img
+                src={profile.avatar}
+                alt=""
+                className={`${sizeClass} rounded-full object-cover shrink-0`}
+            />
+        );
+    }
+    return (
+        <span
+            className={`${sizeClass} rounded-full bg-primary text-white font-semibold flex items-center justify-center shrink-0`}
+        >
+            {initials}
+        </span>
+    );
+}
+
+/**
+ * The top-right "who am I" menu shared by `MailShell` and `AdminShell`: an avatar-button trigger that opens a
+ * dropdown showing the caller's avatar/name, an optional "Admin" link (trusted-role callers only), and
+ * "Sign Out". Name/avatar come from auth-server's own profile endpoint (`GET /api/profiles/me`) — this
+ * service has no local user directory (see `.claude/NOTES.md`) — and fall back to the bare uid/its first
+ * letter when unset or unreachable, which is a fully valid, expected state for most password-registered
+ * accounts (only OIDC sign-in currently populates a real avatar).
+ */
+export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminLink, showSettingsLink }: UserMenuProps) {
+    const [open, setOpen] = useState(false);
+    const [profile, setProfile] = useState<Profile | undefined>(undefined);
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (!authServerUrl) {
+            return;
+        }
+        getMyProfile(authServerUrl)
+            .then(setProfile)
+            .catch(() => undefined);
+    }, [authServerUrl]);
+
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        function handlePointerDown(e: MouseEvent) {
+            if (containerRef.current && e.target instanceof Node && !containerRef.current.contains(e.target)) {
+                setOpen(false);
+            }
+        }
+        function handleKeyDown(e: KeyboardEvent) {
+            if (e.key === "Escape") {
+                setOpen(false);
+            }
+        }
+        document.addEventListener("mousedown", handlePointerDown);
+        document.addEventListener("keydown", handleKeyDown);
+        return () => {
+            document.removeEventListener("mousedown", handlePointerDown);
+            document.removeEventListener("keydown", handleKeyDown);
+        };
+    }, [open]);
+
+    const name = formatProfileName(profile) ?? userUid;
+    const initials = profileInitials(profile, userUid);
+
+    return (
+        <div className="relative" ref={containerRef}>
+            <button
+                type="button"
+                onClick={() => setOpen((o) => !o)}
+                aria-haspopup="true"
+                aria-expanded={open}
+                aria-label="Account menu"
+                className="flex items-center gap-1.5 rounded-pill py-1 pl-1 pr-2 hover:bg-surface-alt"
+            >
+                <Avatar profile={profile} initials={initials} />
+                <svg
+                    width="14"
+                    height="14"
+                    viewBox="0 0 20 20"
+                    fill="none"
+                    className={`text-text-muted transition-transform ${open ? "rotate-180" : ""}`}
+                    aria-hidden="true"
+                >
+                    <path d="M5 7.5L10 12.5L15 7.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+                </svg>
+            </button>
+            {open && (
+                <div
+                    role="menu"
+                    className="absolute right-0 top-full mt-2 w-60 bg-surface border border-border rounded-md shadow-modal py-1.5 z-10"
+                >
+                    <div className="flex items-center gap-3 px-3.5 py-2.5 border-b border-border">
+                        <Avatar profile={profile} initials={initials} large />
+                        <span className="text-sm font-semibold text-text truncate">{name}</span>
+                    </div>
+                    {showSettingsLink && (
+                        <a
+                            role="menuitem"
+                            href="/settings/auto-reply"
+                            className="block px-3.5 py-2 text-sm text-text hover:bg-surface-alt"
+                        >
+                            Settings
+                        </a>
+                    )}
+                    {showAdminLink && (
+                        <a
+                            role="menuitem"
+                            href="/admin"
+                            className="block px-3.5 py-2 text-sm text-text hover:bg-surface-alt"
+                        >
+                            Admin
+                        </a>
+                    )}
+                    <button
+                        role="menuitem"
+                        type="button"
+                        onClick={onSignOut}
+                        className="block w-full text-left px-3.5 py-2 text-sm text-text hover:bg-surface-alt"
+                    >
+                        Sign Out
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+}

package/apps/shared/components/mail/ConversationList.tsx

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+
+export interface ConversationListProps {
+    conversations: ConversationSummary[];
+    selectedId: string | null;
+    onSelect: (conversation: ConversationSummary) => void;
+}
+
+/** The "By conversation" counterpart to the per-message list `apps/www/index.tsx` renders inline for
+ * "By date" — conversations are mailbox-wide (see `conversationsApi.ts`), so there's no per-folder
+ * empty/loading state to distinguish here beyond what the page itself already handles. */
+export default function ConversationList({ conversations, selectedId, onSelect }: ConversationListProps) {
+    if (conversations.length === 0) {
+        return <p className="p-4 text-sm text-text-muted">No conversations in this mailbox.</p>;
+    }
+
+    return (
+        <ul>
+            {conversations.map((conversation) => {
+                const unread = conversation.unreadCount > 0;
+                return (
+                    <li key={conversation.conversationId}>
+                        <button
+                            type="button"
+                            onClick={() => onSelect(conversation)}
+                            className={[
+                                "w-full text-left px-4 py-3 border-b border-border",
+                                conversation.conversationId === selectedId ? "bg-primary/10" : "hover:bg-surface-alt",
+                                unread ? "font-semibold" : "",
+                            ].join(" ")}
+                        >
+                            <div className="flex items-center justify-between gap-2 text-sm">
+                                <span className="truncate">
+                                    {conversation.participants.map((p) => p.displayName || p.address).join(", ")}
+                                </span>
+                                <span className="text-xs text-text-muted shrink-0">
+                                    {new Date(conversation.latestDate).toLocaleDateString()}
+                                </span>
+                            </div>
+                            <div className="text-sm truncate">{conversation.subject || "(no subject)"}</div>
+                            <div className="flex items-center gap-2 mt-1 text-xs text-text-muted font-normal">
+                                {conversation.messageCount > 1 && <span>{conversation.messageCount} messages</span>}
+                                {unread && (
+                                    <span className="py-0.5 px-2 rounded-pill bg-primary/10 text-primary-dark font-semibold">
+                                        {conversation.unreadCount} unread
+                                    </span>
+                                )}
+                                {conversation.hasAttachments && <span aria-label="Has attachments">&#128206;</span>}
+                            </div>
+                        </button>
+                    </li>
+                );
+            })}
+        </ul>
+    );
+}