@rapidmx/web-client 0.2.0

package/apps/shared/components/contacts/ContactsSidebar.tsx

@@ -0,0 +1,242 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { FormEvent, useEffect, useMemo, useState } from "react";
+import { HiOutlineBars3 } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { Contact, ContactList, createContactList, listContactLists } from "@rapidmx/react-shared/contacts/contactsApi.js";
+import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+
+export type ContactsView =
+    | { type: "all" }
+    | { type: "favorites" }
+    | { type: "list"; uid: string; name: string }
+    | { type: "deleted" }
+    | { type: "category"; name: string };
+
+export function contactsViewKey(view: ContactsView): string {
+    switch (view.type) {
+        case "list":
+            return `list:${view.uid}`;
+        case "category":
+            return `category:${view.name}`;
+        default:
+            return view.type;
+    }
+}
+
+/** A fixed palette of colors for category swatches, cycled by name — Outlook's own categories are
+ * user-assigned colors, but nothing server-side models a color for a category (it's a plain string label
+ * on `Contact.categories`), so this is a deterministic client-side stand-in, same idea as `ContactAvatar`'s
+ * per-name color. */
+const CATEGORY_PALETTE = ["#dc2626", "#d97706", "#059669", "#2563eb", "#7c3aed", "#db2777"];
+
+function categoryColor(name: string): string {
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        hash = (hash * 31 + name.charCodeAt(i)) | 0;
+    }
+    return CATEGORY_PALETTE[Math.abs(hash) % CATEGORY_PALETTE.length];
+}
+
+export interface ContactsSidebarProps {
+    mailboxUid?: string;
+    /** The caller's own (non-deleted) contacts — used to compute counts and the distinct category list.
+     * Deliberately not fetched again here; the parent already has this loaded for the main table. */
+    contacts: Contact[];
+    active: ContactsView;
+    onSelect: (view: ContactsView) => void;
+    /** Bumped by the parent whenever a contact-list membership changes, so a newly-created/renamed list
+     * shows up without a full page reload. */
+    refreshToken?: number;
+}
+
+function NavItem({
+    label,
+    count,
+    active,
+    onClick,
+    swatch,
+}: {
+    label: string;
+    count?: number;
+    active: boolean;
+    onClick: () => void;
+    swatch?: string;
+}) {
+    return (
+        <button
+            type="button"
+            onClick={onClick}
+            aria-current={active ? "true" : undefined}
+            className={[
+                "w-full flex items-center justify-between gap-2 text-sm text-left px-2.5 py-1.5 rounded-sm",
+                active ? "bg-primary/10 text-primary-dark font-semibold" : "text-text hover:bg-surface-alt",
+            ].join(" ")}
+        >
+            <span className="flex items-center gap-2 min-w-0">
+                {swatch && <span aria-hidden="true" className="w-2.5 h-2.5 rounded-full shrink-0" style={{ backgroundColor: swatch }} />}
+                <span className="truncate">{label}</span>
+            </span>
+            {count !== undefined && <span className="text-xs text-text-muted shrink-0">{count}</span>}
+        </button>
+    );
+}
+
+/**
+ * Contacts' Outlook-style left sidebar: "Your contacts" (all, with count), "Favorites", "Your contact
+ * lists" (real `ContactList` records, fetched here), "Deleted", and "Categories" (derived from the
+ * distinct `categories` values across the loaded contacts — no separate category registry exists
+ * server-side). Owns its own contact-list data-fetching, per this app's convention of keeping
+ * `ContactsShellContext` itself minimal (mailbox/folder resolution only).
+ */
+export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect, refreshToken }: ContactsSidebarProps) {
+    const [lists, setLists] = useState<ContactList[]>([]);
+    const [listsError, setListsError] = useState<string | null>(null);
+    const [addingList, setAddingList] = useState(false);
+    const [newListName, setNewListName] = useState("");
+    const [drawerOpen, setDrawerOpen] = useState(false);
+
+    useEffect(() => {
+        if (!mailboxUid) {
+            setLists([]);
+            return;
+        }
+        setListsError(null);
+        listContactLists(mailboxUid, { limit: 200 })
+            .then(setLists)
+            .catch((err) => setListsError(err instanceof ApiRequestError ? err.message : "Could not load contact lists."));
+    }, [mailboxUid, refreshToken]);
+
+    const favoriteCount = useMemo(() => contacts.filter((c) => c.favorite).length, [contacts]);
+    const listCounts = useMemo(() => {
+        const counts = new Map<string, number>();
+        for (const c of contacts) {
+            if (c.contactListUid) {
+                counts.set(c.contactListUid, (counts.get(c.contactListUid) ?? 0) + 1);
+            }
+        }
+        return counts;
+    }, [contacts]);
+    const categories = useMemo(() => {
+        const names = new Set<string>();
+        for (const c of contacts) {
+            for (const category of c.categories ?? []) {
+                names.add(category);
+            }
+        }
+        return Array.from(names).sort((a, b) => a.localeCompare(b));
+    }, [contacts]);
+
+    async function handleAddList(e: FormEvent) {
+        e.preventDefault();
+        if (!mailboxUid || !newListName.trim()) {
+            return;
+        }
+        try {
+            const created = await createContactList({ mailboxUid, name: newListName.trim() });
+            setLists((prev) => [...prev, created].sort((a, b) => a.name.localeCompare(b.name)));
+            setNewListName("");
+            setAddingList(false);
+        } catch (err) {
+            setListsError(err instanceof ApiRequestError ? err.message : "Could not create this list.");
+        }
+    }
+
+    function handleSelect(view: ContactsView) {
+        onSelect(view);
+        setDrawerOpen(false);
+    }
+
+    // A function, not a plain JSX constant — rendered both in the desktop `<nav>` and the mobile
+    // `Drawer` (see MailShell/ContactsShell for the identical pattern and the duplicate-id reasoning
+    // behind the `idPrefix`).
+    const navContent = (idPrefix: string) => (
+        <>
+            <div className="flex flex-col gap-0.5">
+                <NavItem label="Your contacts" count={contacts.length} active={active.type === "all"} onClick={() => handleSelect({ type: "all" })} />
+                <NavItem label="Favorites" count={favoriteCount} active={active.type === "favorites"} onClick={() => handleSelect({ type: "favorites" })} />
+                <NavItem label="Deleted" active={active.type === "deleted"} onClick={() => handleSelect({ type: "deleted" })} />
+            </div>
+
+            <div>
+                <div className="flex items-center justify-between px-2.5 mb-1">
+                    <h2 className="text-xs font-bold uppercase tracking-wide text-text-muted">Your contact lists</h2>
+                    <button
+                        type="button"
+                        onClick={() => setAddingList(true)}
+                        aria-label="New contact list"
+                        className="text-xs font-bold text-primary-dark hover:underline"
+                    >
+                        +
+                    </button>
+                </div>
+                {listsError && <p className="px-2.5 text-xs text-danger">{listsError}</p>}
+                <div className="flex flex-col gap-0.5">
+                    {lists.map((list) => (
+                        <NavItem
+                            key={list.uid}
+                            label={list.name}
+                            count={listCounts.get(list.uid) ?? 0}
+                            active={active.type === "list" && active.uid === list.uid}
+                            onClick={() => handleSelect({ type: "list", uid: list.uid, name: list.name })}
+                        />
+                    ))}
+                </div>
+                {addingList && (
+                    <form onSubmit={handleAddList} className="flex items-center gap-1 px-2.5 mt-1">
+                        <input
+                            type="text"
+                            autoFocus
+                            aria-label="New list name"
+                            id={`${idPrefix}-new-list-name`}
+                            value={newListName}
+                            onChange={(e) => setNewListName(e.target.value)}
+                            className="flex-1 text-xs py-1 px-1.5 border border-border rounded-sm bg-surface"
+                        />
+                        <button type="submit" className="text-xs font-semibold text-primary-dark">
+                            Add
+                        </button>
+                    </form>
+                )}
+            </div>
+
+            {categories.length > 0 && (
+                <div>
+                    <h2 className="text-xs font-bold uppercase tracking-wide text-text-muted px-2.5 mb-1">Categories</h2>
+                    <div className="flex flex-col gap-0.5">
+                        {categories.map((name) => (
+                            <NavItem
+                                key={name}
+                                label={name}
+                                swatch={categoryColor(name)}
+                                active={active.type === "category" && active.name === name}
+                                onClick={() => handleSelect({ type: "category", name })}
+                            />
+                        ))}
+                    </div>
+                </div>
+            )}
+        </>
+    );
+
+    return (
+        <>
+            <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 contacts menu"
+                onClick={() => setDrawerOpen(true)}
+            >
+                <HiOutlineBars3 size={20} aria-hidden="true" />
+            </button>
+            <nav aria-label="Contacts" className="hidden md:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto">
+                {navContent("desktop")}
+            </nav>
+            <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Contacts">
+                <div className="flex flex-col gap-4">{navContent("mobile")}</div>
+            </Drawer>
+        </>
+    );
+}

package/apps/shared/components/contacts/ContactsToolbar.tsx

@@ -0,0 +1,115 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ChangeEvent, useRef } from "react";
+import type { IconType } from "react-icons";
+import {
+    HiOutlineArrowDownTray,
+    HiOutlineArrowUpTray,
+    HiOutlineEnvelope,
+    HiOutlinePencil,
+    HiOutlineStar,
+    HiOutlineTag,
+    HiOutlineTrash,
+    HiOutlineUserPlus,
+    HiStar,
+} from "react-icons/hi2";
+
+export interface ContactsToolbarProps {
+    selectedCount: number;
+    /** `true` only when every currently-selected contact is already favorited — flips the "favorite" button
+     * to act (and read) as a removal instead of an addition. */
+    allSelectedFavorited: boolean;
+    onNewContact: () => void;
+    onEdit: () => void;
+    onDelete: () => void;
+    onEmail: () => void;
+    onToggleFavorite: () => void;
+    onAddCategory: () => void;
+    onExportVCard: () => void;
+    /** A `.vcf` file the user picked via the toolbar's own hidden file input — parsing/import is the
+     * page's responsibility (it has the mailbox/folder context and the actual `createContact` calls). */
+    onImportFile: (file: File) => void;
+}
+
+function ToolbarButton({
+    label,
+    icon: Icon,
+    disabled,
+    onClick,
+}: {
+    label: string;
+    icon: IconType;
+    disabled?: boolean;
+    onClick: () => void;
+}) {
+    return (
+        <button
+            type="button"
+            onClick={onClick}
+            disabled={disabled}
+            className="flex flex-col items-center gap-1 text-xs text-text-muted hover:text-text disabled:opacity-40 disabled:cursor-not-allowed px-2.5 py-1.5 rounded-sm hover:not-disabled:bg-surface-alt"
+        >
+            <Icon size={18} aria-hidden="true" />
+            <span>{label}</span>
+        </button>
+    );
+}
+
+function Divider() {
+    return <div className="w-px self-stretch my-1 bg-border" aria-hidden="true" />;
+}
+
+/**
+ * Contacts' Outlook-style ribbon toolbar. Deliberately presentational — every action is a callback the
+ * page (`apps/www/contacts/index.tsx`) implements, since it owns the actual contact data, the current
+ * selection, and the mailbox/folder context every real action (create/delete/email/favorite/category)
+ * needs. "New contact list" isn't duplicated here — `ContactsSidebar` already has its own inline
+ * "+ New list" affordance next to the "Your contact lists" heading.
+ */
+export default function ContactsToolbar({
+    selectedCount,
+    allSelectedFavorited,
+    onNewContact,
+    onEdit,
+    onDelete,
+    onEmail,
+    onToggleFavorite,
+    onAddCategory,
+    onExportVCard,
+    onImportFile,
+}: ContactsToolbarProps) {
+    const importInputRef = useRef<HTMLInputElement | null>(null);
+    const hasSelection = selectedCount > 0;
+
+    function handleImportFileChosen(e: ChangeEvent<HTMLInputElement>) {
+        const file = e.target.files?.[0];
+        e.target.value = "";
+        if (file) {
+            onImportFile(file);
+        }
+    }
+
+    return (
+        <div role="toolbar" aria-label="Contacts actions" className="border-b border-border bg-surface-alt flex items-center gap-0.5 px-2 py-1">
+            <ToolbarButton label="New contact" icon={HiOutlineUserPlus} onClick={onNewContact} />
+            <Divider />
+            <ToolbarButton label="Edit" icon={HiOutlinePencil} disabled={selectedCount !== 1} onClick={onEdit} />
+            <ToolbarButton label="Delete" icon={HiOutlineTrash} disabled={!hasSelection} onClick={onDelete} />
+            <Divider />
+            <ToolbarButton label="Email" icon={HiOutlineEnvelope} disabled={!hasSelection} onClick={onEmail} />
+            <ToolbarButton
+                label={allSelectedFavorited ? "Unfavorite" : "Favorite"}
+                icon={allSelectedFavorited ? HiStar : HiOutlineStar}
+                disabled={!hasSelection}
+                onClick={onToggleFavorite}
+            />
+            <ToolbarButton label="Add category" icon={HiOutlineTag} disabled={!hasSelection} onClick={onAddCategory} />
+            <Divider />
+            <ToolbarButton label="Export" icon={HiOutlineArrowUpTray} disabled={!hasSelection} onClick={onExportVCard} />
+            <ToolbarButton label="Import" icon={HiOutlineArrowDownTray} onClick={() => importInputRef.current?.click()} />
+            <input ref={importInputRef} type="file" accept=".vcf" className="sr-only" aria-label="Import contacts file" onChange={handleImportFileChosen} />
+        </div>
+    );
+}

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

@@ -0,0 +1,197 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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>
+    );
+}