@rapidmx/web-client 0.25.1 → 0.27.0

package/README.md

@@ -355,10 +355,20 @@ any release.
 | `shared/components/admin/layout/AdminShell.js` | Admin console chrome, gated on administrator access - an administrator whose session isn't elevated is sent to auth-server's `/auth/elevate` page and returned. `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. |
+| `shared/plugins/pluginIcons.js` | `PLUGIN_ICONS`, the icon names a nav entry's `icon` can use, and `pluginIcon()`, which resolves one. |
+
+### Page building blocks
+
+| Import | Use |
+| --- | --- |
+| `shared/components/layout/ResponsiveToolbar.js` | A toolbar whose buttons collapse into an overflow menu when space runs out. |
+| `shared/components/admin/usePagedList.js` | Loads a list a page at a time with "Load more", for tables of the plugin's own records. |
+| `shared/notifications/apiErrors.js` | `notifyApiError()`, which shows a failed API call as a notification. |
+| `shared/components/admin/diagnostics/Sparkline.js` and `MetricTile.js` | A small trend line and a labelled figure, for simple dashboards. |
 
 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
+app rail entries of every enabled plugin whose UI built. The shells append those entries after their own, each with the
+icon its manifest names when that name is in `PLUGIN_ICONS`, and a generic puzzle piece otherwise. 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
@@ -397,7 +407,9 @@ section above):
 - `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`.
+- `components/pickers/MiniDatePicker.js`;
+- `components/avatar/ContactAvatar.js`;
+- `util/apiQuery.js`: `buildQuery()`, for paging a list route.
 
 ## Uninstalling a plugin with its data
 

package/apps/shared/components/admin/layout/AdminShell.tsx

@@ -48,6 +48,7 @@ import {
     recordElevationAttempt,
 } from "../elevation.js";
 import { signOutOfConsole } from "../signOut.js";
+import { pluginIcon } from "../../../plugins/pluginIcons.js";
 import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../../plugins/pluginNav.js";
 
 export type AdminSection =
@@ -165,13 +166,13 @@ const SETUP_ITEM: NavItem = { id: "setup", href: "/admin/setup", label: "Setup",
 
 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
+/** `NAV_ITEMS` followed by the plugins' `adminNav` items (their manifest `icon`, or a generic one). 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 }),
+        ({ id, href, label, icon }) => ({ id, href, label, icon: pluginIcon(icon) }),
         OFF_RAIL_ITEMS.map((item) => item.id),
     );
 }

package/apps/shared/components/calendar/EventDetails.tsx

@@ -26,6 +26,7 @@ import { describeTimeZone, deviceTimeZone } from "../../../../lib/util/timeZone.
 import Alert from "../../../../lib/components/feedback/Alert.js";
 import Button from "../../../../lib/components/buttons/Button.js";
 import { joinMeetingUrl } from "../../calendar/calendarReminders.js";
+import ParticipantLink from "../contacts/ParticipantLink.js";
 import EventDescriptionView from "./EventDescriptionView.js";
 import RequestChangeForm from "./RequestChangeForm.js";
 import { BUSY_STATUS_LABEL, RESPONSE_STATUS_LABEL, VISIBILITY_LABEL, describeGuestPermissions, describeReminder, formatStoredWhen, formatStoredWhenInZone } from "./eventFormat.js";
@@ -270,7 +271,9 @@ export default function EventDetails({
                 )}
 
                 <DetailRow icon={<HiOutlineUser size={18} />}>
-                    <div>{organizerName || occurrence.organizer.address}</div>
+                    <div>
+                        <ParticipantLink participant={occurrence.organizer}>{organizerName || occurrence.organizer.address}</ParticipantLink>
+                    </div>
                     <div className="text-text-muted">
                         {organizerName ? `${occurrence.organizer.address} · ` : ""}Organizer
                     </div>
@@ -285,7 +288,7 @@ export default function EventDetails({
                             {guests.map((guest, i) => (
                                 <li key={i} className="flex items-baseline justify-between gap-3">
                                     <span className="min-w-0 truncate">
-                                        {guest.displayName || guest.address}
+                                        <ParticipantLink participant={guest}>{guest.displayName || guest.address}</ParticipantLink>
                                         {ROLE_LABEL[guest.role] && <span className="text-text-muted"> ({ROLE_LABEL[guest.role]})</span>}
                                     </span>
                                     <span className="shrink-0 text-xs text-text-muted">{RESPONSE_STATUS_LABEL[guest.responseStatus]}</span>

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

@@ -0,0 +1,356 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode, useContext, useEffect, useRef, useState } from "react";
+import { type Contact, type ContactAddressKind, contactPhotoUrl, setContactFavorite } from "../../../../lib/contacts/contactsApi.js";
+import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import ContactAvatar from "../../../../lib/components/avatar/ContactAvatar.js";
+import Button from "../../../../lib/components/buttons/Button.js";
+import CopyIconButton from "../../../../lib/components/buttons/CopyIconButton.js";
+import { HiOutlineEnvelope, HiOutlineUserPlus } from "react-icons/hi2";
+import FavoriteStarButton from "./FavoriteStarButton.js";
+import Skeleton from "../../../../lib/components/feedback/Skeleton.js";
+import Modal from "../../../../lib/components/overlays/Modal.js";
+import { formatMailAddress } from "../../../../lib/mail/mailAddress.js";
+import type { ParsedVCardContact } from "../../../../lib/contacts/vcard.js";
+import { type Folder, type Mailbox, listMailboxes } from "../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
+import { MAILBOX_LIST_LIMIT, MailConnectionContext } from "../../mail/useMailConnection.js";
+import { notify } from "../../notifications/store.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
+import { APP_HREFS } from "../../navigation/appHrefs.js";
+import { useCompose } from "../mail/compose/ComposeContext.js";
+import { formatInviteWhen } from "../mail/invite/inviteFormat.js";
+import {
+    type ContactCardContext,
+    contactScope,
+    createContactFor,
+    findContact,
+    loadFolders,
+    loadParticipantCard,
+    loadRecentMessages,
+    loadUpcomingEvents,
+    scopeMailboxes,
+} from "./contactCardData.js";
+import { type Participant, contactInputFor, isExternalAddress, ownDomains, participantName } from "./participantDetails.js";
+
+type Section<T> = { status: "loading" } | { status: "error" } | { status: "ready"; data: T };
+
+/** What creating the contact is made from. */
+interface CreateWith {
+    folders: Folder[];
+    mailboxes: Mailbox[];
+    card: ParsedVCardContact | undefined;
+}
+
+/**
+ * One piece of the card's data. `load` is `undefined` while what it needs is still coming (it stays loading), and runs once when it is there; a
+ * failure is this section's error and nothing else's. `upstream` is the section this one needs: its error is this one's too.
+ */
+function useSection<T>(load: (() => Promise<T>) | undefined, upstream?: Section<unknown>): Section<T> {
+    const [state, setState] = useState<Section<T>>({ status: "loading" });
+    const ready = !!load;
+    useEffect(() => {
+        if (!load) {
+            return;
+        }
+        let cancelled = false;
+        load().then(
+            (data) => !cancelled && setState({ status: "ready", data }),
+            () => !cancelled && setState({ status: "error" }),
+        );
+        return () => {
+            cancelled = true;
+        };
+    }, [ready]);
+    return upstream?.status === "error" ? { status: "error" } : state;
+}
+
+const KIND_LABEL: Record<ContactAddressKind, string> = { work: "Work", home: "Home", other: "" };
+
+function kindLabel(kind: ContactAddressKind): string {
+    return KIND_LABEL[kind];
+}
+
+function Detail({ label, children }: { label: string; children: ReactNode }) {
+    return (
+        <div className="flex gap-3 text-sm">
+            <dt className="w-24 shrink-0 text-text-muted">{label}</dt>
+            <dd className="min-w-0 break-words whitespace-pre-line">{children}</dd>
+        </div>
+    );
+}
+
+/** A card section: its heading, and while loading a skeleton, on failure the reason, when empty the empty text, else what `render` draws. */
+function CardSection<T>({
+    title,
+    section,
+    empty,
+    failure,
+    isEmpty,
+    render,
+}: {
+    title: string;
+    section: Section<T>;
+    empty: string;
+    failure: string;
+    isEmpty: (data: T) => boolean;
+    render: (data: T) => ReactNode;
+}) {
+    return (
+        <section className="mt-5">
+            <h3 className="text-sm font-bold mb-2">{title}</h3>
+            {section.status === "loading" ? (
+                <div role="status" aria-label={`Loading ${title.toLowerCase()}`} className="flex flex-col gap-2">
+                    <Skeleton width="w-3/4" />
+                    <Skeleton width="w-1/2" />
+                </div>
+            ) : section.status === "error" ? (
+                <p role="alert" className="text-sm text-danger">
+                    {failure}
+                </p>
+            ) : isEmpty(section.data) ? (
+                <p className="text-sm text-text-muted">{empty}</p>
+            ) : (
+                render(section.data)
+            )}
+        </section>
+    );
+}
+
+const ACTION_CLASS = "!w-auto !py-1 !px-3 text-xs";
+const ROW_LINK_CLASS = "block rounded-sm px-2 py-1.5 -mx-2 hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary";
+
+export interface ContactCardProps {
+    participant: Participant;
+    context?: ContactCardContext;
+    onClose: () => void;
+    userUid?: string;
+}
+
+/**
+ * A person's contact card, as Outlook's people card: a big avatar, their name, an "External" badge when the address is outside the user's own
+ * domains, the actions (email them, copy the address, create the contact or open it), then their contact details, the last messages to or from
+ * them and the events coming up that they organize or were invited to. Each section loads on its own, with a skeleton, an empty text and an
+ * error that touches nothing else on the card.
+ *
+ * When the address is not in the user's address book the details are what is known: the name and address, and everything a vCard attached to the
+ * message they were met in says. "Create contact" stores that. The lookups are made once, when the card opens.
+ */
+export default function ContactCard({ participant, context = {}, onClose, userUid }: ContactCardProps) {
+    const client = useApiClient();
+    const { openCompose } = useCompose();
+    const connection = useContext(MailConnectionContext);
+    const [listed, setListed] = useState<Section<Mailbox[]>>({ status: "loading" });
+    const [created, setCreated] = useState<Contact | undefined>();
+    const [creating, setCreating] = useState(false);
+    // The contact as last changed from this card (starred or unstarred), which is newer than the one looked up.
+    const [changed, setChanged] = useState<Contact | undefined>();
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => void (mounted.current = false);
+    }, []);
+
+    // The mailboxes come from the app frame's connection when there is one; otherwise (a page rendered outside it) they are asked for.
+    useEffect(() => {
+        if (connection) {
+            return;
+        }
+        listMailboxes({ limit: MAILBOX_LIST_LIMIT }, client).then(
+            (data) => mounted.current && setListed({ status: "ready", data }),
+            () => mounted.current && setListed({ status: "error" }),
+        );
+    }, []);
+    const mailboxes: Section<Mailbox[]> = connection
+        ? connection.status === "ready"
+            ? { status: "ready", data: connection.mailboxes }
+            : connection.status === "error"
+              ? { status: "error" }
+              : { status: "loading" }
+        : listed;
+
+    const scope = mailboxes.status === "ready" ? scopeMailboxes(mailboxes.data, userUid, context.message) : undefined;
+    const now = useRef(new Date());
+    const folders = useSection(scope && (() => loadFolders(scope, client)), mailboxes);
+    const contact = useSection(
+        folders.status === "ready" ? () => findContact(folders.data, participant.address, client) : undefined,
+        folders,
+    );
+    const messages = useSection(scope && (() => loadRecentMessages(scope, participant.address, client)), mailboxes);
+    const events = useSection(
+        folders.status === "ready" ? () => loadUpcomingEvents(folders.data, participant.address, now.current, client) : undefined,
+        folders,
+    );
+    const card = useSection(() => loadParticipantCard(participant, context, client));
+
+    const name = participantName(participant);
+    const stored = changed ?? created ?? (contact.status === "ready" ? contact.data : undefined);
+    const external = mailboxes.status === "ready" && isExternalAddress(participant.address, ownDomains(mailboxes.data));
+    // What is known when there is no contact: the name, the address and the message's vCard.
+    const known = stored ?? contactInputFor(participant, card.status === "ready" ? card.data : undefined, { mailboxUid: "", folderUid: "" });
+    // What "Create contact" needs, once it is all there.
+    const createWith =
+        folders.status === "ready" && mailboxes.status === "ready" && card.status === "ready"
+            ? { folders: folders.data, mailboxes: mailboxes.data, card: card.data }
+            : undefined;
+
+    async function handleCreate({ folders: folderList, mailboxes: mailboxList, card: parsed }: CreateWith) {
+        setCreating(true);
+        try {
+            const target = contactScope(mailboxList, folderList, userUid, context.message);
+            const made = await createContactFor(participant, parsed, target, client);
+            clearPinnedSignerCache();
+            notify({ kind: "success", title: "Contact created", message: `${made.displayName} was added to your contacts.` });
+            if (mounted.current) {
+                setCreated(made);
+            }
+        } catch (err) {
+            notifyApiError(err, "Couldn't create this contact");
+        } finally {
+            if (mounted.current) {
+                setCreating(false);
+            }
+        }
+    }
+
+    async function handleToggleFavorite(current: Contact) {
+        try {
+            const next = await setContactFavorite(current, !current.favorite, client);
+            if (mounted.current) {
+                setChanged(next);
+            }
+        } catch (err) {
+            notifyApiError(err, "Couldn't update this contact");
+        }
+    }
+
+    function handleEmail() {
+        openCompose({ to: formatMailAddress(participant) });
+        onClose();
+    }
+
+    return (
+        <Modal open onClose={onClose} title={name}>
+            <div className="flex items-center gap-4">
+                <ContactAvatar displayName={name} size={72} photoUrl={stored && contactPhotoUrl(stored)} email={participant.address} />
+                <div className="min-w-0 flex-1">
+                    <p className="text-sm text-text-muted break-words">
+                        {participant.address}
+                        <CopyIconButton value={participant.address} label="Copy address" className="ml-1" />
+                    </p>
+                    {external && (
+                        <span className="inline-block mt-1 text-xs font-semibold py-0.5 px-2 rounded-pill bg-warning/15 text-text">External</span>
+                    )}
+                    {(known.jobTitle || known.company) && (
+                        <p className="mt-1 text-sm break-words">{[known.jobTitle, known.company].filter(Boolean).join(", ")}</p>
+                    )}
+                </div>
+                {stored && <FavoriteStarButton favorite={!!stored.favorite} onToggle={() => void handleToggleFavorite(stored)} className="shrink-0 self-start" />}
+            </div>
+            <div className="mt-4 flex flex-wrap items-center gap-2">
+                <Button type="button" variant="secondary" className={`${ACTION_CLASS} inline-flex items-center gap-1.5`} onClick={handleEmail}>
+                    <HiOutlineEnvelope aria-hidden="true" className="size-4" />
+                    Email
+                </Button>
+                {stored ? (
+                    <a
+                        href={`${APP_HREFS.contacts}/${encodeURIComponent(stored.uid)}`}
+                        onClick={onClose}
+                        className="inline-flex items-center text-xs font-semibold py-1 px-3 rounded-sm border border-border hover:border-accent hover:text-accent-dark focus-visible:outline-2 focus-visible:outline-primary"
+                    >
+                        Open contact
+                    </a>
+                ) : (
+                    <Button
+                        type="button"
+                        variant="secondary"
+                        className={`${ACTION_CLASS} inline-flex items-center gap-1.5`}
+                        disabled={!createWith || creating}
+                        loading={creating}
+                        onClick={() => void handleCreate(createWith as CreateWith)}
+                    >
+                        <HiOutlineUserPlus aria-hidden="true" className="size-4" />
+                        Add to contacts
+                    </Button>
+                )}
+            </div>
+
+            <section className="mt-5">
+                <h3 className="text-sm font-bold mb-2">Contact</h3>
+                {!stored && contact.status === "loading" && <Skeleton width="w-1/2" className="mb-2" />}
+                {!stored && contact.status === "error" && (
+                    <p role="alert" className="text-sm text-danger mb-2">
+                        Couldn&rsquo;t check your address book.
+                    </p>
+                )}
+                {!stored && contact.status === "ready" && <p className="text-sm text-text-muted mb-2">Not in your address book.</p>}
+                <dl className="flex flex-col gap-1.5">
+                    {known.emails.map((email) => (
+                        <Detail key={`e:${email.address}`} label={["Email", kindLabel(email.type)].filter(Boolean).join(" ")}>
+                            {email.address}
+                            <CopyIconButton value={email.address} label="Copy email address" className="ml-1" />
+                        </Detail>
+                    ))}
+                    {known.phones.map((phone) => (
+                        <Detail key={`p:${phone.phoneNumber}`} label={["Phone", kindLabel(phone.type)].filter(Boolean).join(" ")}>
+                            {phone.phoneNumber}
+                        </Detail>
+                    ))}
+                    {known.company && <Detail label="Company">{known.company}</Detail>}
+                    {known.jobTitle && <Detail label="Job title">{known.jobTitle}</Detail>}
+                    {known.addresses.map((address, index) => (
+                        <Detail key={`a:${index}`} label={["Address", kindLabel(address.type)].filter(Boolean).join(" ")}>
+                            {[address.street, [address.postalCode, address.city].filter(Boolean).join(" "), address.state, address.country].filter(Boolean).join("\n")}
+                        </Detail>
+                    ))}
+                    {known.notes && <Detail label="Notes">{known.notes}</Detail>}
+                </dl>
+            </section>
+            <CardSection
+                title="Recent messages"
+                section={messages}
+                empty="No recent messages"
+                failure="Couldn't load recent messages."
+                isEmpty={(list) => list.length === 0}
+                render={(list) => (
+                    <ul className="flex flex-col">
+                        {list.map((message) => (
+                            <li key={message.uid}>
+                                <a href={`/messages/${encodeURIComponent(message.uid)}`} onClick={onClose} className={ROW_LINK_CLASS}>
+                                    <span className="flex items-baseline justify-between gap-3 text-sm">
+                                        <span className="font-medium truncate">{message.subject || "(No subject)"}</span>
+                                        <time dateTime={message.receivedDate} className="text-xs text-text-muted shrink-0">
+                                            {new Date(message.receivedDate).toLocaleDateString()}
+                                        </time>
+                                    </span>
+                                    <span className="block text-xs text-text-muted truncate">{message.bodyPreview}</span>
+                                </a>
+                            </li>
+                        ))}
+                    </ul>
+                )}
+            />
+            <CardSection
+                title="Upcoming events"
+                section={events}
+                empty="No upcoming events"
+                failure="Couldn't load upcoming events."
+                isEmpty={(list) => list.length === 0}
+                render={(list) => (
+                    <ul className="flex flex-col">
+                        {list.map((event) => (
+                            <li key={event.occurrenceKey}>
+                                <a href={APP_HREFS.calendar} onClick={onClose} className={ROW_LINK_CLASS}>
+                                    <span className="block text-sm font-medium truncate">{event.title}</span>
+                                    <span className="block text-xs text-text-muted">{formatInviteWhen(event)}</span>
+                                </a>
+                            </li>
+                        ))}
+                    </ul>
+                )}
+            />
+        </Modal>
+    );
+}

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

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren, createContext, useCallback, useContext, useMemo, useState } from "react";
+import { parseVCards } from "../../../../lib/contacts/vcard.js";
+import { type Message, listMailboxes } from "../../../../lib/mail/mailApi.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
+import { MAILBOX_LIST_LIMIT, MailConnectionContext } from "../../mail/useMailConnection.js";
+import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import ContactCard from "./ContactCard.js";
+import { type AddCardsResult, type ContactCardContext, addCardsToAddressBook, contactScope, loadFolders, scopeMailboxes } from "./contactCardData.js";
+import type { Participant } from "./participantDetails.js";
+
+export interface ContactCardValue {
+    /** Opens the contact card of `participant`; `context` is the message they were met in, when there is one (its vCard attachments and mailbox). */
+    show: (participant: Participant, context?: ContactCardContext) => void;
+    /**
+     * Adds every card of a vCard file's `text` to the user's address book - in the default contacts folder of `message`'s mailbox when it is one of
+     * theirs, else of their primary mailbox - skipping the ones whose email is already a contact's. Rejects if a card cannot be stored (an
+     * `AddCardsError`) or the folders cannot be read. Does nothing useful outside a provider (`available` is `false`).
+     */
+    addVCards: (text: string, message?: Message) => Promise<AddCardsResult>;
+    /** `false` outside a `ContactCardProvider`, where `show()` does nothing: a caller then draws plain text instead of a button. */
+    available: boolean;
+}
+
+const CardContext = createContext<ContactCardValue>({ show: () => undefined, addVCards: () => Promise.resolve({ added: 0, skipped: 0 }), available: false });
+
+/** Shows a person's contact card from anywhere inside `AppShell` - see `ContactCard`. */
+export function useContactCard(): ContactCardValue {
+    return useContext(CardContext);
+}
+
+interface Shown {
+    participant: Participant;
+    context?: ContactCardContext;
+    /** A new card each time, so what one card loaded is never shown for the next. */
+    id: number;
+}
+
+/**
+ * Owns the one contact card that can be open. Mounted once in `AppShell` (inside the compose provider, whose windows the card's "Email" opens), so
+ * a participant is clickable in every app. The card is a modal: focus goes into it, and back to the participant that was clicked when it closes.
+ */
+export default function ContactCardProvider({ children, userUid }: PropsWithChildren<{ userUid?: string }>) {
+    const client = useApiClient();
+    const connection = useContext(MailConnectionContext);
+    const [shown, setShown] = useState<Shown | null>(null);
+    const show = useCallback<ContactCardValue["show"]>((participant, context) => {
+        setShown((previous) => ({ participant, context, id: (previous?.id ?? 0) + 1 }));
+    }, []);
+    const addVCards = useCallback<ContactCardValue["addVCards"]>(
+        async (text, message) => {
+            const cards = parseVCards(text);
+            // The frame's mailboxes when it has them; a page rendered outside it asks.
+            const mailboxes = connection?.status === "ready" ? connection.mailboxes : await listMailboxes({ limit: MAILBOX_LIST_LIMIT }, client);
+            const folders = await loadFolders(scopeMailboxes(mailboxes, userUid, message), client);
+            const result = await addCardsToAddressBook(cards, contactScope(mailboxes, folders, userUid, message), client);
+            clearPinnedSignerCache();
+            return result;
+        },
+        [connection, client, userUid],
+    );
+    const value = useMemo(() => ({ show, addVCards, available: true }), [show, addVCards]);
+    return (
+        <CardContext.Provider value={value}>
+            {children}
+            {shown && <ContactCard key={shown.id} participant={shown.participant} context={shown.context} userUid={userUid} onClose={() => setShown(null)} />}
+        </CardContext.Provider>
+    );
+}

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

@@ -3,7 +3,11 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useState } from "react";
-import { Contact } from "../../../../lib/contacts/contactsApi.js";
+import { Contact, contactPhotoUrl, setContactFavorite } from "../../../../lib/contacts/contactsApi.js";
+import CopyIconButton from "../../../../lib/components/buttons/CopyIconButton.js";
+import { useApiClient } from "../../../../lib/util/apiClientContext.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
+import FavoriteStarButton from "./FavoriteStarButton.js";
 import Button from "../../../../lib/components/buttons/Button.js";
 import Alert from "../../../../lib/components/feedback/Alert.js";
 import ContactAvatar from "../../../../lib/components/avatar/ContactAvatar.js";
@@ -37,6 +41,8 @@ export interface ContactDetailPaneProps {
     /** Called after one of the contact's key changes was accepted or kept, or turned out to be stale - the caller
      * re-reads the contact. */
     onKeysChanged?: () => void;
+    /** Called with the contact after the star was toggled, so the caller shows the changed contact. */
+    onChanged?: (contact: Contact) => void;
     /** `false` when the reader is known not to be able to change this contact's keys (the actions are hidden); `undefined`
      * when unknown (they're hidden after a 403). */
     canResolveKeys?: boolean;
@@ -47,13 +53,23 @@ export interface ContactDetailPaneProps {
  * always visible alongside the contact list) and the mobile detail route
  * (`apps/www/contacts/[uid].tsx`, a full page on its own reached by tapping a contact row).
  */
-export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, canResolveKeys }: ContactDetailPaneProps) {
+export default function ContactDetailPane({ contact, onEdit, onDelete, backHref, onKeysChanged, onChanged, canResolveKeys }: ContactDetailPaneProps) {
+    const client = useApiClient();
     // The outcome of the last key decision, kept per contact so selecting another contact doesn't carry it over.
     const [keyNotice, setKeyNotice] = useState<{ contactUid: string; text: string } | null>(null);
     const notice = keyNotice?.contactUid === contact.uid ? keyNotice.text : null;
     const keyConflicts = contact.keyConflicts ?? [];
     const previousKeys = contact.previousKeys ?? [];
 
+    async function handleToggleFavorite() {
+        try {
+            const changed = await setContactFavorite(contact, !contact.favorite, client);
+            onChanged?.(changed);
+        } catch (err) {
+            notifyApiError(err, "Couldn't update this contact");
+        }
+    }
+
     // Pinned signing keys vouch for signatures, so the pinned-signer cache is dropped along with re-reading the contact.
     function refresh(text: string) {
         setKeyNotice({ contactUid: contact.uid, text });
@@ -70,9 +86,12 @@ export default function ContactDetailPane({ contact, onEdit, onDelete, backHref,
             )}
             <div className="flex items-start justify-between gap-4">
                 <div className="flex items-center gap-3">
-                    <ContactAvatar displayName={contact.displayName} size={48} />
+                    <ContactAvatar displayName={contact.displayName} size={48} photoUrl={contactPhotoUrl(contact)} email={contact.emails[0]?.address} />
                     <div>
-                        <h1 className="text-xl font-bold tracking-tight">{contact.displayName}</h1>
+                        <h1 className="text-xl font-bold tracking-tight">
+                            {contact.displayName}
+                            <FavoriteStarButton favorite={!!contact.favorite} onToggle={() => void handleToggleFavorite()} className="ml-1 align-middle" />
+                        </h1>
                         {contact.jobTitle && contact.company && (
                             <p className="text-sm text-text-muted mt-0.5">
                                 {contact.jobTitle} at {contact.company}
@@ -96,7 +115,8 @@ export default function ContactDetailPane({ contact, onEdit, onDelete, backHref,
                         <div className="text-text-muted text-xs font-bold uppercase tracking-wide mb-1">Email</div>
                         {contact.emails.map((e, i) => (
                             <div key={i}>
-                                {e.address} <span className="text-text-muted">({e.type})</span>
+                                {e.address}
+                                <CopyIconButton value={e.address} label="Copy email address" className="mx-0.5" /> <span className="text-text-muted">({e.type})</span>
                             </div>
                         ))}
                     </div>