@rapidmx/web-client 0.24.0 → 0.26.0

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

@@ -24,6 +24,8 @@ import {
     HiOutlineUserGroup,
     HiOutlineWrenchScrewdriver,
     HiOutlineBars3,
+    HiOutlineChevronDoubleLeft,
+    HiOutlineChevronDoubleRight,
 } from "react-icons/hi2";
 import { apiFetch, ApiRequestError } from "../../../../../lib/util/api.js";
 import { getSetupStatus } from "../../../../../lib/admin/setupApi.js";
@@ -35,6 +37,7 @@ import Drawer from "../../../../../lib/components/overlays/Drawer.js";
 import type { NavItem } from "../../../../../lib/components/navigation/BottomTabBar.js";
 import { FrameBrandingFooter, useBrandingHtml } from "../../layout/BrandingChrome.js";
 import RailIcon from "../../layout/RailIcon.js";
+import { readRailExpanded, writeRailExpanded } from "./railPreference.js";
 import AppearanceProvider from "../../../appearance/AppearanceProvider.js";
 import UserMenu from "../../layout/UserMenu.js";
 import {
@@ -192,6 +195,15 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
     const [menuOpen, setMenuOpen] = useState(false);
+    // The side rail shows icons alone, or icons with their labels. Read after the first render: the page is drawn on the server first, which cannot know.
+    const [railExpanded, setRailExpanded] = useState(false);
+    useEffect(() => setRailExpanded(readRailExpanded()), []);
+    function toggleRail() {
+        setRailExpanded((expanded) => {
+            writeRailExpanded(!expanded);
+            return !expanded;
+        });
+    }
     // `branding` only feeds the footer below: the admin-configured header is for the webmail and public pages, not the
     // console. `useBranding()` is still what injects the custom stylesheet and supplies the rail's icon.
     const { branding, iconSrc } = useBranding();
@@ -309,7 +321,10 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                 <div className="flex-1 flex min-h-0">
                     <nav
                         aria-label="Admin sections"
-                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center pb-3 gap-1"
+                        className={[
+                            "hidden md:flex shrink-0 bg-surface border-r border-border flex-col pb-3 gap-1",
+                            railExpanded ? "w-56 items-stretch" : "w-16 items-center",
+                        ].join(" ")}
                     >
                         <RailIcon src={iconSrc} />
                         {navItems.map(({ id, href, label, icon: Icon }) => (
@@ -318,17 +333,37 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                                 href={href}
                                 aria-label={label}
                                 aria-current={id === active ? "page" : undefined}
-                                title={label}
+                                title={railExpanded ? undefined : label}
                                 className={[
-                                    "w-10 h-10 flex items-center justify-center rounded-sm",
+                                    "h-10 flex items-center rounded-sm",
+                                    railExpanded ? "gap-3 px-3 mx-2 text-sm font-medium" : "w-10 justify-center",
                                     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" />
+                                <Icon size={20} aria-hidden="true" className="shrink-0" />
+                                {railExpanded && <span className="truncate">{label}</span>}
                             </a>
                         ))}
+                        <button
+                            type="button"
+                            aria-expanded={railExpanded}
+                            aria-label={railExpanded ? "Collapse the menu" : "Expand the menu"}
+                            title={railExpanded ? "Collapse the menu" : "Expand the menu"}
+                            onClick={toggleRail}
+                            className={[
+                                "mt-auto h-10 flex items-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text",
+                                railExpanded ? "gap-3 px-3 mx-2 text-sm font-medium" : "w-10 justify-center",
+                            ].join(" ")}
+                        >
+                            {railExpanded ? (
+                                <HiOutlineChevronDoubleLeft size={20} aria-hidden="true" className="shrink-0" />
+                            ) : (
+                                <HiOutlineChevronDoubleRight size={20} aria-hidden="true" className="shrink-0" />
+                            )}
+                            {railExpanded && <span>Collapse</span>}
+                        </button>
                     </nav>
                     {/* Below `md` the sections are a menu that slides in from the left: ten or so of them don't fit a bar along the bottom. */}
                     <Drawer open={menuOpen} onClose={() => setMenuOpen(false)} title="Admin" fullScreen>

package/apps/shared/components/admin/layout/railPreference.ts

@@ -0,0 +1,25 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** Where this browser remembers whether the admin console's side rail is showing its labels. */
+export const RAIL_EXPANDED_KEY = "rapidmx:admin-rail-expanded";
+
+/** Whether the rail was left expanded. A missing or blocked store means collapsed, as it always was. */
+export function readRailExpanded(): boolean {
+    try {
+        return localStorage.getItem(RAIL_EXPANDED_KEY) === "true";
+    } catch {
+        return false;
+    }
+}
+
+/** Remembers the rail's state. Best effort: a blocked store only means it starts collapsed the next time. */
+export function writeRailExpanded(expanded: boolean): void {
+    try {
+        localStorage.setItem(RAIL_EXPANDED_KEY, String(expanded));
+    } catch {
+        // Nothing to do.
+    }
+}

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

@@ -7,6 +7,7 @@ import { CALENDAR_COLOR_PALETTE, accentColorForMailbox, colorForFolder } from ".
 import { Folder, Mailbox } from "../../../../lib/mail/mailApi.js";
 import Alert from "../../../../lib/components/feedback/Alert.js";
 import { notifyApiError } from "../../notifications/apiErrors.js";
+import { SharedMailboxMark } from "../mail/layout/folderIcons.js";
 
 export interface CalendarListSidebarMailbox {
     mailbox: Mailbox;
@@ -108,7 +109,7 @@ export default function CalendarListSidebar({
     return (
         <nav aria-label="My calendars" className="p-3 border-t border-border flex flex-col gap-3">
             {mailboxCalendars.map(({ mailbox, calendarFolders, error: mailboxError }) => {
-                const title = multiple ? `${mailbox.displayName}${mailbox.ownerUserUid ? "" : " (shared)"}` : "My calendars";
+                const title = multiple ? mailbox.displayName : "My calendars";
                 return (
                     <div key={mailbox.uid}>
                         <div className="flex items-center justify-between mb-1 gap-2">
@@ -120,7 +121,10 @@ export default function CalendarListSidebar({
                                         style={{ backgroundColor: accentColorForMailbox(mailbox.uid) }}
                                     />
                                 )}
-                                <span className="truncate">{title}</span>
+                                <span className="truncate">
+                                    {title}
+                                    {multiple && !mailbox.ownerUserUid && <SharedMailboxMark />}
+                                </span>
                             </h2>
                             <button
                                 type="button"

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,330 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode, useContext, useEffect, useRef, useState } from "react";
+import type { Contact, ContactAddressKind } 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 CopyButton from "../../../../lib/components/buttons/CopyButton.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);
+    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 = 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);
+            }
+        }
+    }
+
+    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} />
+                <div className="min-w-0">
+                    <p className="text-sm text-text-muted break-words">{participant.address}</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>
+            </div>
+            <div className="mt-4 flex flex-wrap items-center gap-2">
+                <Button type="button" variant="secondary" className={ACTION_CLASS} onClick={handleEmail}>
+                    Email
+                </Button>
+                <CopyButton value={participant.address} label="Copy address">
+                    Copy address
+                </CopyButton>
+                {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} disabled={!createWith || creating} loading={creating} onClick={() => void handleCreate(createWith as CreateWith)}>
+                        Create contact
+                    </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}
+                        </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/ParticipantLink.tsx

@@ -0,0 +1,42 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+import { useContactCard } from "./ContactCardProvider.js";
+import type { ContactCardContext } from "./contactCardData.js";
+import type { Participant } from "./participantDetails.js";
+
+export interface ParticipantLinkProps {
+    participant: Participant;
+    /** The message the participant was met in - see `ContactCardValue.show`. */
+    context?: ContactCardContext;
+    /** The button's accessible name, when what it shows has none of its own (an avatar). */
+    label?: string;
+    className?: string;
+    children: ReactNode;
+}
+
+/**
+ * A participant of a message or an event (a sender, a recipient, an organizer, a guest) that opens their contact card when clicked: a real
+ * button, underlined on hover and with a visible focus ring, named by what it shows. Outside a `ContactCardProvider` it is plain text. Never
+ * put one inside another button or link.
+ */
+export default function ParticipantLink({ participant, context, label, className, children }: ParticipantLinkProps) {
+    const { show, available } = useContactCard();
+    if (!available) {
+        return <span className={className}>{children}</span>;
+    }
+    return (
+        <button
+            type="button"
+            aria-label={label}
+            onClick={() => show(participant, context)}
+            className={["text-left rounded-sm hover:underline focus-visible:underline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", className]
+                .filter(Boolean)
+                .join(" ")}
+        >
+            {children}
+        </button>
+    );
+}