@rapidmx/web-client 0.25.1 → 0.26.0

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>
+    );
+}