@rapidmx/web-client 0.24.0 → 0.26.0

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -3,7 +3,22 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
-import { HiOutlineBars3 } from "react-icons/hi2";
+import type { IconType } from "react-icons";
+import {
+    HiOutlineArrowUturnLeft,
+    HiOutlineBars3,
+    HiOutlineEnvelopeOpen,
+    HiOutlineFunnel,
+    HiOutlineLockClosed,
+    HiOutlineNoSymbol,
+    HiOutlinePaintBrush,
+    HiOutlinePencilSquare,
+    HiOutlinePuzzlePiece,
+    HiOutlineShieldCheck,
+    HiOutlineTag,
+    HiOutlineUserCircle,
+    HiOutlineUsers,
+} from "react-icons/hi2";
 import { ApiRequestError } from "../../../../../lib/util/api.js";
 import Drawer from "../../../../../lib/components/overlays/Drawer.js";
 import { Mailbox, listMailboxes } from "../../../../../lib/mail/mailApi.js";
@@ -20,21 +35,23 @@ export interface SettingsSectionDef {
     id: string;
     href: string;
     label: string;
+    /** Drawn beside the label in the sidebar. */
+    icon: IconType;
 }
 
 /** Every settings section with its own sidebar entry. */
 export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
-    { id: "profile", href: "/settings/profile", label: "Profile" },
-    { id: "appearance", href: "/settings/appearance", label: "Appearance" },
-    { id: "auto-reply", href: "/settings/auto-reply", label: "Automatic Replies" },
-    { id: "filters", href: "/settings/filters", label: "Mail Filters" },
-    { id: "blocked-senders", href: "/settings/blocked-senders", label: "Blocked & Safe Senders" },
-    { id: "signatures", href: "/settings/signatures", label: "Signatures" },
-    { id: "labels", href: "/settings/labels", label: "Labels" },
-    { id: "read-receipts", href: "/settings/read-receipts", label: "Read Receipts" },
-    { id: "encryption", href: "/settings/encryption", label: "Encryption" },
-    { id: "sharing", href: "/settings/sharing", label: "Sharing" },
-    { id: "privacy", href: "/settings/privacy", label: "Privacy & Data" },
+    { id: "profile", href: "/settings/profile", label: "Profile", icon: HiOutlineUserCircle },
+    { id: "appearance", href: "/settings/appearance", label: "Appearance", icon: HiOutlinePaintBrush },
+    { id: "auto-reply", href: "/settings/auto-reply", label: "Automatic Replies", icon: HiOutlineArrowUturnLeft },
+    { id: "filters", href: "/settings/filters", label: "Mail Filters", icon: HiOutlineFunnel },
+    { id: "blocked-senders", href: "/settings/blocked-senders", label: "Blocked & Safe Senders", icon: HiOutlineNoSymbol },
+    { id: "signatures", href: "/settings/signatures", label: "Signatures", icon: HiOutlinePencilSquare },
+    { id: "labels", href: "/settings/labels", label: "Labels", icon: HiOutlineTag },
+    { id: "read-receipts", href: "/settings/read-receipts", label: "Read Receipts", icon: HiOutlineEnvelopeOpen },
+    { id: "encryption", href: "/settings/encryption", label: "Encryption", icon: HiOutlineLockClosed },
+    { id: "sharing", href: "/settings/sharing", label: "Sharing", icon: HiOutlineUsers },
+    { id: "privacy", href: "/settings/privacy", label: "Privacy & Data", icon: HiOutlineShieldCheck },
 ];
 
 /** A `SETTINGS_SECTIONS` id, or a plugin's `settingsSections` item id (see `PluginNav`). */
@@ -47,6 +64,7 @@ export function settingsSections(pluginNav?: PluginNav): SettingsSectionDef[] {
         id,
         href,
         label,
+        icon: HiOutlinePuzzlePiece,
     }));
 }
 
@@ -207,10 +225,11 @@ export default function SettingsShell({
                             href={`${section.href}?mailboxUid=${encodeURIComponent(mailboxUid!)}`}
                             aria-current={section.id === active ? "page" : undefined}
                             className={[
-                                "block px-2.5 py-1.5 rounded-sm text-sm",
+                                "flex items-center gap-2.5 px-2.5 py-1.5 rounded-sm text-sm",
                                 section.id === active ? "bg-primary/10 text-primary-dark font-medium" : "text-text hover:bg-surface-alt",
                             ].join(" ")}
                         >
+                            <section.icon size={18} aria-hidden="true" className="shrink-0" />
                             {section.label}
                         </a>
                     ))}

package/apps/shared/navigation/appHrefs.ts

@@ -12,10 +12,10 @@ export const APP_HREFS = {
 } as const;
 
 /**
- * Settings is reached from the account menu, not the rail. It links straight to the first settings section, the only one that always
- * exists - repoint this at a real `/settings` landing page once there is one.
+ * Settings is reached from the account menu, not the rail. It links straight to the Profile section, the first of them and the one that
+ * always exists - repoint this at a real `/settings` landing page once there is one.
  */
-export const SETTINGS_HREF = "/settings/auto-reply";
+export const SETTINGS_HREF = "/settings/profile";
 
 /** Whether `pathname` is a page of Settings (any section), which is what "already there" means for it. */
 export function isSettingsPath(pathname: string): boolean {

package/dist/apps/shared/components/admin/layout/AdminShell.js

@@ -6,7 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import "../../../styles/app.css";
 import { useEffect, useState } from "react";
 import { useRouter } from "@rapidrest/react/client";
-import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineCpuChip, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, } from "react-icons/hi2";
+import { HiOutlineClipboardDocumentList, HiOutlineClock, HiOutlineCpuChip, HiOutlineDocumentArrowDown, HiOutlineDocumentCheck, HiOutlineGlobeAlt, HiOutlineInboxStack, HiOutlineKey, HiOutlineLockClosed, HiOutlinePaintBrush, HiOutlinePuzzlePiece, HiOutlineQueueList, HiOutlineRocketLaunch, HiOutlineShieldCheck, HiOutlineShieldExclamation, HiOutlineUserGroup, HiOutlineWrenchScrewdriver, HiOutlineBars3, HiOutlineChevronDoubleLeft, HiOutlineChevronDoubleRight, } from "react-icons/hi2";
 import { apiFetch, ApiRequestError } from "../../../../../lib/util/api.js";
 import { getSetupStatus } from "../../../../../lib/admin/setupApi.js";
 import { useSessionRefresh } from "../../../../../lib/auth/session.js";
@@ -16,6 +16,7 @@ import Button from "../../../../../lib/components/buttons/Button.js";
 import Drawer from "../../../../../lib/components/overlays/Drawer.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 { clearElevationAttempt, elevationAttemptedRecently, elevationUrl, isElevationRequired, recordElevationAttempt, } from "../elevation.js";
@@ -114,6 +115,15 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(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();
@@ -198,12 +208,19 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     else {
         const navItems = adminNavItems(pluginNav);
         const activeItem = [...navItems, ...OFF_RAIL_ITEMS].find((item) => item.id === active);
-        content = (_jsx("div", { className: "rr-frame-bg min-h-screen flex flex-col", children: _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("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", children: [_jsx(RailIcon, { src: iconSrc }), navItems.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
-                                    "w-10 h-10 flex items-center justify-center rounded-sm",
+        content = (_jsx("div", { className: "rr-frame-bg min-h-screen flex flex-col", children: _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Admin sections", 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(" "), children: [_jsx(RailIcon, { src: iconSrc }), navItems.map(({ id, href, label, icon: Icon }) => (_jsxs("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: railExpanded ? undefined : label, className: [
+                                    "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(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(Drawer, { open: menuOpen, onClose: () => setMenuOpen(false), title: "Admin", fullScreen: true, children: _jsx("nav", { "aria-label": "Admin menu", className: "flex flex-col gap-1 -mx-2", children: navItems.map(({ id, href, label, icon: Icon }) => (_jsxs("a", { href: href, "aria-current": id === active ? "page" : undefined, onClick: () => setMenuOpen(false), className: [
+                                ].join(" "), children: [_jsx(Icon, { size: 20, "aria-hidden": "true", className: "shrink-0" }), railExpanded && _jsx("span", { className: "truncate", children: label })] }, id))), _jsxs("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(" "), children: [railExpanded ? (_jsx(HiOutlineChevronDoubleLeft, { size: 20, "aria-hidden": "true", className: "shrink-0" })) : (_jsx(HiOutlineChevronDoubleRight, { size: 20, "aria-hidden": "true", className: "shrink-0" })), railExpanded && _jsx("span", { children: "Collapse" })] })] }), _jsx(Drawer, { open: menuOpen, onClose: () => setMenuOpen(false), title: "Admin", fullScreen: true, children: _jsx("nav", { "aria-label": "Admin menu", className: "flex flex-col gap-1 -mx-2", children: navItems.map(({ id, href, label, icon: Icon }) => (_jsxs("a", { href: href, "aria-current": id === active ? "page" : undefined, onClick: () => setMenuOpen(false), className: [
                                     "flex items-center gap-3 px-3 py-2.5 rounded-sm text-sm font-medium",
                                     id === active ? "bg-primary/10 text-primary-dark" : "text-text hover:bg-surface-alt",
                                 ].join(" "), children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), label] }, id))) }) }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-4 md:px-6", children: [_jsxs("div", { className: "flex items-center gap-2 min-w-0", children: [_jsx("button", { type: "button", className: "md:hidden shrink-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open menu", onClick: () => setMenuOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide truncate", children: activeItem?.label })] }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showMailLink: true })] }), _jsx("div", { id: "app-content", className: "flex-1", children: _jsx("main", { className: "max-w-6xl mx-auto px-6 py-8", children: children }) })] })] }) }));

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

@@ -0,0 +1,6 @@
+/** Where this browser remembers whether the admin console's side rail is showing its labels. */
+export declare 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 declare function readRailExpanded(): boolean;
+/** Remembers the rail's state. Best effort: a blocked store only means it starts collapsed the next time. */
+export declare function writeRailExpanded(expanded: boolean): void;

package/dist/apps/shared/components/admin/layout/railPreference.js

@@ -0,0 +1,24 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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() {
+    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) {
+    try {
+        localStorage.setItem(RAIL_EXPANDED_KEY, String(expanded));
+    }
+    catch {
+        // Nothing to do.
+    }
+}

package/dist/apps/shared/components/calendar/CalendarListSidebar.js

@@ -7,6 +7,7 @@ import { useState } from "react";
 import { CALENDAR_COLOR_PALETTE, accentColorForMailbox, colorForFolder } from "../../../../lib/calendar/calendarColors.js";
 import Alert from "../../../../lib/components/feedback/Alert.js";
 import { notifyApiError } from "../../notifications/apiErrors.js";
+import { SharedMailboxMark } from "../mail/layout/folderIcons.js";
 /**
  * Calendar's left-sidebar checklist of calendars — one row per `calendar`-type folder, a color swatch,
  * and a checkbox controlling whether that calendar's events are currently shown (the checked set is owned
@@ -49,7 +50,7 @@ export default function CalendarListSidebar({ mailboxCalendars, checkedFolderUid
     }
     const addForm = (_jsxs("form", { onSubmit: handleAdd, className: "flex flex-col gap-1.5 mt-2", children: [_jsx("input", { type: "text", autoFocus: true, "aria-label": "New calendar name", value: name, onChange: (e) => setName(e.target.value), className: "text-xs py-1 px-1.5 border border-border rounded-sm bg-surface" }), _jsx("div", { className: "flex items-center gap-1", role: "radiogroup", "aria-label": "Calendar color", children: CALENDAR_COLOR_PALETTE.map((swatch) => (_jsx("button", { type: "button", "aria-label": `Color ${swatch}`, "aria-pressed": color === swatch, onClick: () => setColor(swatch), className: ["w-4 h-4 rounded-full shrink-0", color === swatch ? "ring-2 ring-offset-1 ring-text" : ""].join(" "), style: { backgroundColor: swatch } }, swatch))) }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("button", { type: "submit", disabled: saving, className: "text-xs font-semibold text-primary-dark", children: "Add" }), _jsx("button", { type: "button", onClick: () => setAddingFor(null), className: "text-xs text-text-muted", children: "Cancel" })] })] }));
     return (_jsx("nav", { "aria-label": "My calendars", className: "p-3 border-t border-border flex flex-col gap-3", children: mailboxCalendars.map(({ mailbox, calendarFolders, error: mailboxError }) => {
-            const title = multiple ? `${mailbox.displayName}${mailbox.ownerUserUid ? "" : " (shared)"}` : "My calendars";
-            return (_jsxs("div", { children: [_jsxs("div", { className: "flex items-center justify-between mb-1 gap-2", children: [_jsxs("h2", { className: "flex items-center gap-1.5 text-xs font-bold uppercase tracking-wide text-text-muted min-w-0", children: [multiple && (_jsx("span", { "aria-hidden": "true", className: "w-2 h-2 rounded-full shrink-0", style: { backgroundColor: accentColorForMailbox(mailbox.uid) } })), _jsx("span", { className: "truncate", children: title })] }), _jsx("button", { type: "button", onClick: () => startAdding(mailbox.uid), "aria-label": multiple ? `Add calendar to ${mailbox.displayName}` : "Add calendar", className: "text-xs font-bold text-primary-dark hover:underline shrink-0", children: "+" })] }), mailboxError && (_jsx("div", { className: "mb-1", children: _jsx(Alert, { children: mailboxError }) })), _jsx("div", { className: "flex flex-col gap-0.5", children: calendarFolders.map((folder) => (_jsxs("label", { className: "flex items-center gap-2 text-sm px-1 py-1 rounded-sm hover:bg-surface-alt cursor-pointer", children: [_jsx("input", { type: "checkbox", checked: checkedFolderUids.has(folder.uid), onChange: () => onToggle(folder.uid), style: { accentColor: colorFor(folder) } }), _jsx("span", { "aria-hidden": "true", className: "w-2.5 h-2.5 rounded-full shrink-0", style: { backgroundColor: colorFor(folder) } }), _jsx("span", { className: "truncate", children: folder.name })] }, folder.uid))) }), addingFor === mailbox.uid && addForm] }, mailbox.uid));
+            const title = multiple ? mailbox.displayName : "My calendars";
+            return (_jsxs("div", { children: [_jsxs("div", { className: "flex items-center justify-between mb-1 gap-2", children: [_jsxs("h2", { className: "flex items-center gap-1.5 text-xs font-bold uppercase tracking-wide text-text-muted min-w-0", children: [multiple && (_jsx("span", { "aria-hidden": "true", className: "w-2 h-2 rounded-full shrink-0", style: { backgroundColor: accentColorForMailbox(mailbox.uid) } })), _jsxs("span", { className: "truncate", children: [title, multiple && !mailbox.ownerUserUid && _jsx(SharedMailboxMark, {})] })] }), _jsx("button", { type: "button", onClick: () => startAdding(mailbox.uid), "aria-label": multiple ? `Add calendar to ${mailbox.displayName}` : "Add calendar", className: "text-xs font-bold text-primary-dark hover:underline shrink-0", children: "+" })] }), mailboxError && (_jsx("div", { className: "mb-1", children: _jsx(Alert, { children: mailboxError }) })), _jsx("div", { className: "flex flex-col gap-0.5", children: calendarFolders.map((folder) => (_jsxs("label", { className: "flex items-center gap-2 text-sm px-1 py-1 rounded-sm hover:bg-surface-alt cursor-pointer", children: [_jsx("input", { type: "checkbox", checked: checkedFolderUids.has(folder.uid), onChange: () => onToggle(folder.uid), style: { accentColor: colorFor(folder) } }), _jsx("span", { "aria-hidden": "true", className: "w-2.5 h-2.5 rounded-full shrink-0", style: { backgroundColor: colorFor(folder) } }), _jsx("span", { className: "truncate", children: folder.name })] }, folder.uid))) }), addingFor === mailbox.uid && addForm] }, mailbox.uid));
         }) }));
 }

package/dist/apps/shared/components/calendar/EventDetails.js

@@ -16,6 +16,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";
@@ -121,7 +122,7 @@ export default function EventDetails({ occurrence, isInvited, myResponse, isOwnA
         { response: "tentative", label: "Tentative" },
         { response: "declined", label: "Decline" },
     ];
-    return (_jsxs("div", { className: "flex flex-col", children: [_jsxs("div", { className: "flex items-start gap-3 px-5 pt-4", children: [_jsx("span", { "aria-hidden": "true", className: "w-3.5 h-3.5 rounded-full shrink-0 mt-2", style: { backgroundColor: calendarColor } }), _jsx("h2", { className: "flex-1 min-w-0 text-xl font-semibold break-words", children: occurrence.title || "(no title)" }), _jsx("button", { type: "button", "aria-label": "Close details", onClick: onClose, className: "w-8 h-8 shrink-0 flex items-center justify-center rounded-full text-text-muted hover:bg-surface-alt hover:text-text", children: _jsx(HiOutlineXMark, { size: 20, "aria-hidden": "true" }) })] }), _jsxs("div", { className: "flex flex-col gap-3 px-5 pt-3 pb-4 text-sm", children: [error && _jsx(Alert, { children: error }), _jsxs(DetailRow, { icon: _jsx(HiOutlineClock, { size: 18 }), children: [!occurrence.allDay && eventZone && eventZone !== deviceTimeZone() ? (_jsxs(_Fragment, { children: [_jsxs("div", { children: [formatStoredWhen(occurrence.startDate, occurrence.endDate, false), " \u2022 ", describeTimeZone(deviceTimeZone(), new Date(occurrence.startDate))] }), _jsxs("div", { className: "text-text-muted", children: [formatStoredWhenInZone(occurrence.startDate, occurrence.endDate, eventZone), " \u2022 ", describeTimeZone(eventZone, new Date(occurrence.startDate))] })] })) : (_jsx("div", { children: formatStoredWhen(occurrence.startDate, occurrence.endDate, occurrence.allDay) })), occurrence.recurrenceRule && _jsxs("div", { className: "text-text-muted", children: ["Repeats ", describeRecurrence(occurrence.recurrenceRule)] })] }), occurrence.location && (_jsx(DetailRow, { icon: _jsx(HiOutlineMapPin, { size: 18 }), children: _jsx("div", { children: occurrence.location }) })), hasDescription && (_jsx(DetailRow, { icon: _jsx(HiOutlineBars3BottomLeft, { size: 18 }), children: _jsx(EventDescriptionView, { html: occurrence.descriptionHtml, text: occurrence.description }) })), videoMeetingUid && (_jsx(DetailRow, { icon: _jsx(HiOutlineVideoCamera, { size: 18 }), children: _jsxs("div", { className: "flex items-center gap-3 flex-wrap", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: !joinUrl, onClick: () => window.open(joinUrl, "_blank", "noopener,noreferrer"), children: "Join video call" }), !joinUrl && (_jsx("span", { className: "text-xs text-text-muted", children: organizerJoinUrl === undefined ? "Loading the join link…" : "This meeting’s join link isn’t available." }))] }) })), _jsxs(DetailRow, { icon: _jsx(HiOutlineUser, { size: 18 }), children: [_jsx("div", { children: organizerName || occurrence.organizer.address }), _jsxs("div", { className: "text-text-muted", children: [organizerName ? `${occurrence.organizer.address} · ` : "", "Organizer"] })] }), (guests.length > 0 || hiddenList) && (_jsxs(DetailRow, { icon: _jsx(HiOutlineUserGroup, { size: 18 }), children: [_jsx("div", { className: "font-medium mb-1", children: hiddenList ? "The organizer has hidden the guest list" : guests.length === 1 ? "1 guest" : `${guests.length} guests` }), _jsx("ul", { className: "flex flex-col gap-1", children: guests.map((guest, i) => (_jsxs("li", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("span", { className: "min-w-0 truncate", children: [guest.displayName || guest.address, ROLE_LABEL[guest.role] && _jsxs("span", { className: "text-text-muted", children: [" (", ROLE_LABEL[guest.role], ")"] })] }), _jsx("span", { className: "shrink-0 text-xs text-text-muted", children: RESPONSE_STATUS_LABEL[guest.responseStatus] })] }, i))) }), !isInvited && _jsx("div", { className: "text-xs text-text-muted mt-1", children: describeGuestPermissions(permissions) })] })), _jsxs(DetailRow, { icon: _jsx(HiOutlineBriefcase, { size: 18 }), children: [_jsx("div", { children: BUSY_STATUS_LABEL[occurrence.busyStatus] }), _jsx("div", { className: "text-text-muted", children: VISIBILITY_LABEL[visibilityOf(occurrence)] }), occurrence.autoReplyEnabled && (_jsx("div", { className: "text-text-muted", children: "Sends an automatic reply while this event is happening" }))] }), _jsx(DetailRow, { icon: _jsx(HiOutlineBell, { size: 18 }), children: _jsx("div", { children: describeReminder(occurrence.reminderMinutesBeforeStart) }) }), calendarName && (_jsxs("div", { className: "flex items-center gap-3 text-text-muted", children: [_jsx("span", { "aria-hidden": "true", className: "w-3 h-3 ml-[3px] rounded-full shrink-0", style: { backgroundColor: calendarColor } }), _jsx("span", { className: "truncate", children: calendarName })] })), isInvited && (_jsxs("p", { className: "text-xs text-text-muted", children: ["You were invited to this event. Only the organizer can change its details", canChange || canInvite ? ", but you can ask them to." : "."] }))] }), requesting && (_jsx("div", { className: "mx-5 mb-3 p-3 rounded-md bg-surface-alt", children: _jsx(RequestChangeForm, { subject: {
+    return (_jsxs("div", { className: "flex flex-col", children: [_jsxs("div", { className: "flex items-start gap-3 px-5 pt-4", children: [_jsx("span", { "aria-hidden": "true", className: "w-3.5 h-3.5 rounded-full shrink-0 mt-2", style: { backgroundColor: calendarColor } }), _jsx("h2", { className: "flex-1 min-w-0 text-xl font-semibold break-words", children: occurrence.title || "(no title)" }), _jsx("button", { type: "button", "aria-label": "Close details", onClick: onClose, className: "w-8 h-8 shrink-0 flex items-center justify-center rounded-full text-text-muted hover:bg-surface-alt hover:text-text", children: _jsx(HiOutlineXMark, { size: 20, "aria-hidden": "true" }) })] }), _jsxs("div", { className: "flex flex-col gap-3 px-5 pt-3 pb-4 text-sm", children: [error && _jsx(Alert, { children: error }), _jsxs(DetailRow, { icon: _jsx(HiOutlineClock, { size: 18 }), children: [!occurrence.allDay && eventZone && eventZone !== deviceTimeZone() ? (_jsxs(_Fragment, { children: [_jsxs("div", { children: [formatStoredWhen(occurrence.startDate, occurrence.endDate, false), " \u2022 ", describeTimeZone(deviceTimeZone(), new Date(occurrence.startDate))] }), _jsxs("div", { className: "text-text-muted", children: [formatStoredWhenInZone(occurrence.startDate, occurrence.endDate, eventZone), " \u2022 ", describeTimeZone(eventZone, new Date(occurrence.startDate))] })] })) : (_jsx("div", { children: formatStoredWhen(occurrence.startDate, occurrence.endDate, occurrence.allDay) })), occurrence.recurrenceRule && _jsxs("div", { className: "text-text-muted", children: ["Repeats ", describeRecurrence(occurrence.recurrenceRule)] })] }), occurrence.location && (_jsx(DetailRow, { icon: _jsx(HiOutlineMapPin, { size: 18 }), children: _jsx("div", { children: occurrence.location }) })), hasDescription && (_jsx(DetailRow, { icon: _jsx(HiOutlineBars3BottomLeft, { size: 18 }), children: _jsx(EventDescriptionView, { html: occurrence.descriptionHtml, text: occurrence.description }) })), videoMeetingUid && (_jsx(DetailRow, { icon: _jsx(HiOutlineVideoCamera, { size: 18 }), children: _jsxs("div", { className: "flex items-center gap-3 flex-wrap", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: !joinUrl, onClick: () => window.open(joinUrl, "_blank", "noopener,noreferrer"), children: "Join video call" }), !joinUrl && (_jsx("span", { className: "text-xs text-text-muted", children: organizerJoinUrl === undefined ? "Loading the join link…" : "This meeting’s join link isn’t available." }))] }) })), _jsxs(DetailRow, { icon: _jsx(HiOutlineUser, { size: 18 }), children: [_jsx("div", { children: _jsx(ParticipantLink, { participant: occurrence.organizer, children: organizerName || occurrence.organizer.address }) }), _jsxs("div", { className: "text-text-muted", children: [organizerName ? `${occurrence.organizer.address} · ` : "", "Organizer"] })] }), (guests.length > 0 || hiddenList) && (_jsxs(DetailRow, { icon: _jsx(HiOutlineUserGroup, { size: 18 }), children: [_jsx("div", { className: "font-medium mb-1", children: hiddenList ? "The organizer has hidden the guest list" : guests.length === 1 ? "1 guest" : `${guests.length} guests` }), _jsx("ul", { className: "flex flex-col gap-1", children: guests.map((guest, i) => (_jsxs("li", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("span", { className: "min-w-0 truncate", children: [_jsx(ParticipantLink, { participant: guest, children: guest.displayName || guest.address }), ROLE_LABEL[guest.role] && _jsxs("span", { className: "text-text-muted", children: [" (", ROLE_LABEL[guest.role], ")"] })] }), _jsx("span", { className: "shrink-0 text-xs text-text-muted", children: RESPONSE_STATUS_LABEL[guest.responseStatus] })] }, i))) }), !isInvited && _jsx("div", { className: "text-xs text-text-muted mt-1", children: describeGuestPermissions(permissions) })] })), _jsxs(DetailRow, { icon: _jsx(HiOutlineBriefcase, { size: 18 }), children: [_jsx("div", { children: BUSY_STATUS_LABEL[occurrence.busyStatus] }), _jsx("div", { className: "text-text-muted", children: VISIBILITY_LABEL[visibilityOf(occurrence)] }), occurrence.autoReplyEnabled && (_jsx("div", { className: "text-text-muted", children: "Sends an automatic reply while this event is happening" }))] }), _jsx(DetailRow, { icon: _jsx(HiOutlineBell, { size: 18 }), children: _jsx("div", { children: describeReminder(occurrence.reminderMinutesBeforeStart) }) }), calendarName && (_jsxs("div", { className: "flex items-center gap-3 text-text-muted", children: [_jsx("span", { "aria-hidden": "true", className: "w-3 h-3 ml-[3px] rounded-full shrink-0", style: { backgroundColor: calendarColor } }), _jsx("span", { className: "truncate", children: calendarName })] })), isInvited && (_jsxs("p", { className: "text-xs text-text-muted", children: ["You were invited to this event. Only the organizer can change its details", canChange || canInvite ? ", but you can ask them to." : "."] }))] }), requesting && (_jsx("div", { className: "mx-5 mb-3 p-3 rounded-md bg-surface-alt", children: _jsx(RequestChangeForm, { subject: {
                         uid: occurrence.uid,
                         title: occurrence.title,
                         location: occurrence.location,

package/dist/apps/shared/components/contacts/ContactCard.d.ts

@@ -0,0 +1,19 @@
+import React from "react";
+import { type ContactCardContext } from "./contactCardData.js";
+import { type Participant } from "./participantDetails.js";
+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): React.JSX.Element;

package/dist/apps/shared/components/contacts/ContactCard.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useContext, useEffect, useRef, useState } from "react";
+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 { 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 { contactScope, createContactFor, findContact, loadFolders, loadParticipantCard, loadRecentMessages, loadUpcomingEvents, scopeMailboxes, } from "./contactCardData.js";
+import { contactInputFor, isExternalAddress, ownDomains, participantName } from "./participantDetails.js";
+/**
+ * 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(load, upstream) {
+    const [state, setState] = useState({ 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 = { work: "Work", home: "Home", other: "" };
+function kindLabel(kind) {
+    return KIND_LABEL[kind];
+}
+function Detail({ label, children }) {
+    return (_jsxs("div", { className: "flex gap-3 text-sm", children: [_jsx("dt", { className: "w-24 shrink-0 text-text-muted", children: label }), _jsx("dd", { className: "min-w-0 break-words whitespace-pre-line", children: children })] }));
+}
+/** 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({ title, section, empty, failure, isEmpty, render, }) {
+    return (_jsxs("section", { className: "mt-5", children: [_jsx("h3", { className: "text-sm font-bold mb-2", children: title }), section.status === "loading" ? (_jsxs("div", { role: "status", "aria-label": `Loading ${title.toLowerCase()}`, className: "flex flex-col gap-2", children: [_jsx(Skeleton, { width: "w-3/4" }), _jsx(Skeleton, { width: "w-1/2" })] })) : section.status === "error" ? (_jsx("p", { role: "alert", className: "text-sm text-danger", children: failure })) : isEmpty(section.data) ? (_jsx("p", { className: "text-sm text-text-muted", children: empty })) : (render(section.data))] }));
+}
+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";
+/**
+ * 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 }) {
+    const client = useApiClient();
+    const { openCompose } = useCompose();
+    const connection = useContext(MailConnectionContext);
+    const [listed, setListed] = useState({ status: "loading" });
+    const [created, setCreated] = useState();
+    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 = 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 }) {
+        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 (_jsxs(Modal, { open: true, onClose: onClose, title: name, children: [_jsxs("div", { className: "flex items-center gap-4", children: [_jsx(ContactAvatar, { displayName: name, size: 72 }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "text-sm text-text-muted break-words", children: participant.address }), external && (_jsx("span", { className: "inline-block mt-1 text-xs font-semibold py-0.5 px-2 rounded-pill bg-warning/15 text-text", children: "External" })), (known.jobTitle || known.company) && (_jsx("p", { className: "mt-1 text-sm break-words", children: [known.jobTitle, known.company].filter(Boolean).join(", ") }))] })] }), _jsxs("div", { className: "mt-4 flex flex-wrap items-center gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: ACTION_CLASS, onClick: handleEmail, children: "Email" }), _jsx(CopyButton, { value: participant.address, label: "Copy address", children: "Copy address" }), stored ? (_jsx("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", children: "Open contact" })) : (_jsx(Button, { type: "button", variant: "secondary", className: ACTION_CLASS, disabled: !createWith || creating, loading: creating, onClick: () => void handleCreate(createWith), children: "Create contact" }))] }), _jsxs("section", { className: "mt-5", children: [_jsx("h3", { className: "text-sm font-bold mb-2", children: "Contact" }), !stored && contact.status === "loading" && _jsx(Skeleton, { width: "w-1/2", className: "mb-2" }), !stored && contact.status === "error" && (_jsx("p", { role: "alert", className: "text-sm text-danger mb-2", children: "Couldn\u2019t check your address book." })), !stored && contact.status === "ready" && _jsx("p", { className: "text-sm text-text-muted mb-2", children: "Not in your address book." }), _jsxs("dl", { className: "flex flex-col gap-1.5", children: [known.emails.map((email) => (_jsx(Detail, { label: ["Email", kindLabel(email.type)].filter(Boolean).join(" "), children: email.address }, `e:${email.address}`))), known.phones.map((phone) => (_jsx(Detail, { label: ["Phone", kindLabel(phone.type)].filter(Boolean).join(" "), children: phone.phoneNumber }, `p:${phone.phoneNumber}`))), known.company && _jsx(Detail, { label: "Company", children: known.company }), known.jobTitle && _jsx(Detail, { label: "Job title", children: known.jobTitle }), known.addresses.map((address, index) => (_jsx(Detail, { label: ["Address", kindLabel(address.type)].filter(Boolean).join(" "), children: [address.street, [address.postalCode, address.city].filter(Boolean).join(" "), address.state, address.country].filter(Boolean).join("\n") }, `a:${index}`))), known.notes && _jsx(Detail, { label: "Notes", children: known.notes })] })] }), _jsx(CardSection, { title: "Recent messages", section: messages, empty: "No recent messages", failure: "Couldn't load recent messages.", isEmpty: (list) => list.length === 0, render: (list) => (_jsx("ul", { className: "flex flex-col", children: list.map((message) => (_jsx("li", { children: _jsxs("a", { href: `/messages/${encodeURIComponent(message.uid)}`, onClick: onClose, className: ROW_LINK_CLASS, children: [_jsxs("span", { className: "flex items-baseline justify-between gap-3 text-sm", children: [_jsx("span", { className: "font-medium truncate", children: message.subject || "(No subject)" }), _jsx("time", { dateTime: message.receivedDate, className: "text-xs text-text-muted shrink-0", children: new Date(message.receivedDate).toLocaleDateString() })] }), _jsx("span", { className: "block text-xs text-text-muted truncate", children: message.bodyPreview })] }) }, message.uid))) })) }), _jsx(CardSection, { title: "Upcoming events", section: events, empty: "No upcoming events", failure: "Couldn't load upcoming events.", isEmpty: (list) => list.length === 0, render: (list) => (_jsx("ul", { className: "flex flex-col", children: list.map((event) => (_jsx("li", { children: _jsxs("a", { href: APP_HREFS.calendar, onClick: onClose, className: ROW_LINK_CLASS, children: [_jsx("span", { className: "block text-sm font-medium truncate", children: event.title }), _jsx("span", { className: "block text-xs text-text-muted", children: formatInviteWhen(event) })] }) }, event.occurrenceKey))) })) })] }));
+}

package/dist/apps/shared/components/contacts/ContactCardProvider.d.ts

@@ -0,0 +1,25 @@
+import React, { PropsWithChildren } from "react";
+import { type Message } from "../../../../lib/mail/mailApi.js";
+import { type AddCardsResult, type ContactCardContext } 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;
+}
+/** Shows a person's contact card from anywhere inside `AppShell` - see `ContactCard`. */
+export declare function useContactCard(): ContactCardValue;
+/**
+ * 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;
+}>): React.JSX.Element;

package/dist/apps/shared/components/contacts/ContactCardProvider.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { parseVCards } from "../../../../lib/contacts/vcard.js";
+import { 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 { addCardsToAddressBook, contactScope, loadFolders, scopeMailboxes } from "./contactCardData.js";
+const CardContext = createContext({ 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() {
+    return useContext(CardContext);
+}
+/**
+ * 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 }) {
+    const client = useApiClient();
+    const connection = useContext(MailConnectionContext);
+    const [shown, setShown] = useState(null);
+    const show = useCallback((participant, context) => {
+        setShown((previous) => ({ participant, context, id: (previous?.id ?? 0) + 1 }));
+    }, []);
+    const addVCards = useCallback(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 (_jsxs(CardContext.Provider, { value: value, children: [children, shown && _jsx(ContactCard, { participant: shown.participant, context: shown.context, userUid: userUid, onClose: () => setShown(null) }, shown.id)] }));
+}

package/dist/apps/shared/components/contacts/ParticipantLink.d.ts

@@ -0,0 +1,18 @@
+import React, { ReactNode } from "react";
+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): React.JSX.Element;

package/dist/apps/shared/components/contacts/ParticipantLink.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContactCard } from "./ContactCardProvider.js";
+/**
+ * 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 }) {
+    const { show, available } = useContactCard();
+    if (!available) {
+        return _jsx("span", { className: className, children: children });
+    }
+    return (_jsx("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: children }));
+}

package/dist/apps/shared/components/contacts/contactCardData.d.ts

@@ -0,0 +1,69 @@
+import { type CalendarOccurrence } from "../../../../lib/calendar/recurrence.js";
+import { type Contact } from "../../../../lib/contacts/contactsApi.js";
+import { type ParsedVCardContact } from "../../../../lib/contacts/vcard.js";
+import { type Attachment, type Folder, type Mailbox, type Message } from "../../../../lib/mail/mailApi.js";
+import { type ApiClient } from "../../../../lib/util/api.js";
+import { type Participant } from "./participantDetails.js";
+/** What the card is opened for besides who: the message the participant was met in, and that message's attachments when the caller already has them. */
+export interface ContactCardContext {
+    message?: Message;
+    attachments?: Attachment[];
+}
+/** How many recent messages and upcoming events the card lists. */
+export declare const CARD_LIST_SIZE = 5;
+/** How far ahead "upcoming" looks, in days. */
+export declare const UPCOMING_DAYS = 60;
+/** The most vCard attachments and the most bytes of one that are read to fill a contact in. */
+export declare const MAX_VCARD_FILES = 3;
+export declare const MAX_VCARD_BYTES: number;
+/** The mailboxes whose data the card reads: the user's own, else the primary/first one, plus the message's mailbox when it is one they can reach. */
+export declare function scopeMailboxes(mailboxes: readonly Mailbox[], userUid: string | undefined, message?: Message): Mailbox[];
+/** Every folder of `mailboxes`. A mailbox whose folders cannot be listed is left out rather than failing the rest. */
+export declare function loadFolders(mailboxes: readonly Mailbox[], client?: ApiClient): Promise<Folder[]>;
+/** The contact the address belongs to in `folders`' contacts folders, if any. */
+export declare function findContact(folders: readonly Folder[], address: string, client?: ApiClient): Promise<Contact | undefined>;
+/** The last `CARD_LIST_SIZE` messages to or from `address` in `mailboxes`, newest first. */
+export declare function loadRecentMessages(mailboxes: readonly Mailbox[], address: string, client?: ApiClient): Promise<Message[]>;
+/** The next `CARD_LIST_SIZE` events within `UPCOMING_DAYS` from `now` that `address` organizes or is invited to, soonest first. */
+export declare function loadUpcomingEvents(folders: readonly Folder[], address: string, now: Date, client?: ApiClient): Promise<CalendarOccurrence[]>;
+/** A vCard attachment's text. */
+export declare function fetchVCardText(attachmentUid: string): Promise<string>;
+/**
+ * The vCard of the context message that describes `participant`: the first attachment holding a card with their address, else - only for the
+ * message's sender, whose own vCard it presumably is - the first card there is. `undefined` when there is none, and for any failure to read one:
+ * a vCard only adds detail, it is never needed.
+ */
+export declare function loadParticipantCard(participant: Participant, context: ContactCardContext, client?: ApiClient): Promise<ParsedVCardContact | undefined>;
+/** Where a new contact goes: the message's mailbox when it is one of the user's own, else their primary mailbox - in that mailbox's contacts folder. */
+export declare function contactScope(mailboxes: readonly Mailbox[], folders: readonly Folder[], userUid: string | undefined, message?: Message): {
+    mailboxUid: string;
+    folderUid: string;
+};
+/** Stores a contact for `participant` with everything known - the name, the address and whatever `card` says. */
+export declare function createContactFor(participant: Participant, card: ParsedVCardContact | undefined, scope: {
+    mailboxUid: string;
+    folderUid: string;
+}, client?: ApiClient): Promise<Contact>;
+/**
+ * The sender's own contact card as a file to attach, `<display name>.vcf`: the mailbox being sent from (its name and primary address) with the phones, company and
+ * title of the user's own contact entry for that address, when they have one in their own mailboxes' address books. A lookup that fails just leaves those out.
+ */
+export declare function buildOwnCardFile(mailbox: Mailbox, mailboxes: readonly Mailbox[], userUid: string | undefined, client?: ApiClient): Promise<File>;
+/** The outcome of adding a vCard file's cards to the address book. */
+export interface AddCardsResult {
+    added: number;
+    skipped: number;
+}
+/**
+ * Adds every card of a vCard file to the contacts folder `scope` names, skipping the ones whose email is already a stored contact's (or an earlier
+ * card's in the same file). A card that cannot be stored fails the whole call after the earlier ones were added - `AddCardsError` says how many.
+ */
+export declare function addCardsToAddressBook(cards: readonly ParsedVCardContact[], scope: {
+    mailboxUid: string;
+    folderUid: string;
+}, client?: ApiClient): Promise<AddCardsResult>;
+/** A card failed to store: the message is the failure's and `added` how many cards were stored before it. */
+export declare class AddCardsError extends Error {
+    readonly added: number;
+    constructor(failure: unknown, added: number);
+}