@rapidmx/web-client 0.30.0 → 0.31.0

package/dist/lib/components/menus/MenuButton.js

@@ -0,0 +1,219 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState } from "react";
+import { HiCheck, HiChevronDown, HiChevronLeft, HiChevronRight, HiMinus } from "react-icons/hi2";
+import PopoverPortal from "../overlays/PopoverPortal.js";
+// `PopoverPortal` positions a fixed-size box (it has no auto-height mode), so the menu's height is
+// computed from its own contents rather than measured - from whichever level is *shown*, so a submenu
+// isn't left standing in the parent menu's taller box. These are the exact heights the classes below
+// render at, so the box is never short enough to clip its last row: an item is `h-9`, a group label
+// `h-6`, a note as many `leading-4` lines as it wraps to, a separator a 1px rule inside `my-1`, and the
+// list itself `py-1`.
+const ITEM_HEIGHT = 36;
+const ITEM_DESCRIPTION_HEIGHT = 16;
+const GROUP_LABEL_HEIGHT = 24;
+const NOTE_LINE_HEIGHT = 16;
+const NOTE_PADDING = 4;
+/** A note wraps, so its height depends on how much of it fits a line: `text-xs` averages a little over 6px
+ * a character, and the note sits inside the list's `px-3`. Rounded so the estimate is never *under* the
+ * lines the browser actually draws - a box a few pixels too tall shows blank space, one too short clips. */
+const NOTE_CHAR_WIDTH = 6.4;
+const NOTE_PADDING_X = 24;
+const SEPARATOR_HEIGHT = 9;
+const LIST_PADDING = 8;
+const MENU_MAX_HEIGHT = 460;
+const DEFAULT_MENU_WIDTH = 248;
+/** How tall `note` renders at `width`, wrapped. */
+function noteHeight(note, width) {
+    const charsPerLine = Math.max(1, Math.floor((width - NOTE_PADDING_X) / NOTE_CHAR_WIDTH));
+    return Math.ceil(note.length / charsPerLine) * NOTE_LINE_HEIGHT + NOTE_PADDING;
+}
+/** The height `PopoverPortal` is asked for - exact for a short menu, capped (the list scrolls) for a long one. */
+export function menuHeight(sections, width = DEFAULT_MENU_WIDTH) {
+    let height = LIST_PADDING;
+    sections.forEach((section, index) => {
+        if (index > 0) {
+            height += SEPARATOR_HEIGHT;
+        }
+        if (section.label) {
+            height += GROUP_LABEL_HEIGHT;
+        }
+        for (const item of section.items) {
+            height += ITEM_HEIGHT + (item.description ? ITEM_DESCRIPTION_HEIGHT : 0);
+        }
+        if (section.note) {
+            height += noteHeight(section.note, width);
+        }
+    });
+    return Math.min(height, MENU_MAX_HEIGHT);
+}
+/**
+ * A toolbar button that opens an ARIA menu: `role="menu"` rows with checkmarks for the current choice,
+ * full keyboard support (Enter/Space or Arrow Down to open, arrows/Home/End to move with wrap, Enter/Space
+ * to choose, Escape or Tab to close with focus returning to the trigger) and a click outside to dismiss.
+ *
+ * Rendered through `PopoverPortal` rather than as an absolutely-positioned child: the mail list toolbar
+ * lives inside the list's own `overflow-y-auto` scroll container, which clips an absolute popup however
+ * high its `z-index` - the same reason Compose's own pickers portal out (see `PopoverPortal`'s own doc
+ * comment). The portal supplies the positioning, the outside-click dismissal and the box; the menu
+ * semantics, roving focus and keyboard handling are this component's own.
+ */
+export default function MenuButton({ label, iconOnly = false, icon, disabled, title, sections, width = DEFAULT_MENU_WIDTH, className = "", "aria-label": ariaLabel, onOpenChange, }) {
+    const [open, setOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(0);
+    // The key of the item whose submenu is showing, or `null` at the top level. Held as a key, not as the
+    // item itself, because `sections` is rebuilt on every render.
+    const [submenuKey, setSubmenuKey] = useState(null);
+    const triggerRef = useRef(null);
+    const itemRefs = useRef([]);
+    // State, not a ref: `PopoverPortal` renders nothing at all until its own positioning effect has run, so
+    // the rows don't exist yet when this component's effects first fire. Keying the focus effect on the
+    // menu node itself makes it run again once they do.
+    const [menuNode, setMenuNode] = useState(null);
+    const openSubmenu = sections
+        .flatMap((section) => section.items)
+        .find((item) => item.key === submenuKey && !!item.submenu);
+    /** The row that leaves a submenu again - synthesized rather than asked of the caller, so every submenu
+     * has the same way back however it was built. */
+    const backItem = {
+        key: "__back",
+        label: `Back to ${ariaLabel}`,
+        keepOpen: true,
+        onSelect: () => leaveSubmenu(),
+    };
+    const shownSections = openSubmenu
+        ? [{ key: "__back", items: [backItem] }, ...openSubmenu.submenu]
+        : sections;
+    const items = shownSections.flatMap((section) => section.items);
+    const enabledIndexes = items.map((item, index) => (item.disabled ? -1 : index)).filter((index) => index !== -1);
+    /** The row focus starts on: the current choice where there is one, else the first row that can take focus. */
+    function initialActiveIndex(within) {
+        const checked = within.findIndex((item) => item.checked === true && !item.disabled);
+        const enabled = within.map((item, index) => (item.disabled ? -1 : index)).filter((index) => index !== -1);
+        return checked === -1 ? (enabled[0] ?? 0) : checked;
+    }
+    function openMenu() {
+        setSubmenuKey(null);
+        setActiveIndex(initialActiveIndex(sections.flatMap((section) => section.items)));
+        setOpen(true);
+        onOpenChange?.(true);
+    }
+    function closeMenu(returnFocus) {
+        setOpen(false);
+        setSubmenuKey(null);
+        onOpenChange?.(false);
+        if (returnFocus) {
+            triggerRef.current?.focus();
+        }
+    }
+    function enterSubmenu(item) {
+        setSubmenuKey(item.key);
+        const rows = item.submenu.flatMap((section) => section.items);
+        // Past the Back row, onto the first row of the submenu itself - or, when none of them can take focus (every row is unavailable right now), onto
+        // the Back row, so the keyboard still has a place to be.
+        setActiveIndex(rows.some((row) => !row.disabled) ? 1 + initialActiveIndex(rows) : 0);
+    }
+    function leaveSubmenu() {
+        // Back on the row the submenu was opened from.
+        const parentIndex = sections.flatMap((section) => section.items).findIndex((item) => item.key === submenuKey);
+        setSubmenuKey(null);
+        setActiveIndex(parentIndex);
+    }
+    /** What a row does when it is chosen: open its submenu, or run it and close unless it asked to stay. */
+    function selectItem(item) {
+        if (item.submenu) {
+            enterSubmenu(item);
+            return;
+        }
+        item.onSelect();
+        if (!item.keepOpen) {
+            closeMenu(true);
+        }
+    }
+    // Roving focus: only the active row is tabbable, and it takes DOM focus whenever it changes, so the
+    // arrow keys move the screen reader's cursor too rather than only a visual highlight.
+    useEffect(() => {
+        if (open && menuNode) {
+            // A disabled row can't take focus, so a menu with nothing enabled focuses its own container -
+            // otherwise the keys it handles would go to whatever had focus before it opened.
+            if (enabledIndexes.length === 0) {
+                menuNode.focus();
+            }
+            else {
+                itemRefs.current[activeIndex]?.focus();
+            }
+        }
+        // `submenuKey` too: drilling in or out can land on the same index in the other level's list, and
+        // the row that index *means* is a different button, which the effect must move focus to.
+    }, [open, activeIndex, submenuKey, menuNode]);
+    function moveActive(delta) {
+        if (enabledIndexes.length === 0) {
+            return;
+        }
+        const position = enabledIndexes.indexOf(activeIndex);
+        setActiveIndex(enabledIndexes[(position + delta + enabledIndexes.length) % enabledIndexes.length]);
+    }
+    function handleMenuKeyDown(e) {
+        if (e.key === "Escape") {
+            // Not on to a `Modal` the menu was opened in: Escape closes the menu (or its submenu) only.
+            e.stopPropagation();
+        }
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            moveActive(1);
+        }
+        else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            moveActive(-1);
+        }
+        else if (e.key === "Home") {
+            e.preventDefault();
+            setActiveIndex(enabledIndexes[0] ?? 0);
+        }
+        else if (e.key === "End") {
+            e.preventDefault();
+            setActiveIndex(enabledIndexes[enabledIndexes.length - 1] ?? 0);
+        }
+        else if (e.key === "ArrowRight" && items[activeIndex]?.submenu) {
+            e.preventDefault();
+            enterSubmenu(items[activeIndex]);
+        }
+        else if ((e.key === "ArrowLeft" || e.key === "Escape") && openSubmenu) {
+            // ARIA's own submenu behaviour: Escape leaves the submenu for its parent menu rather than
+            // dismissing the whole thing.
+            e.preventDefault();
+            leaveSubmenu();
+        }
+        else if (e.key === "Escape" || e.key === "Tab") {
+            e.preventDefault();
+            closeMenu(true);
+        }
+    }
+    function handleTriggerKeyDown(e) {
+        if (!open && (e.key === "ArrowDown" || e.key === "ArrowUp")) {
+            e.preventDefault();
+            openMenu();
+        }
+    }
+    let itemIndex = -1;
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { ref: triggerRef, type: "button", "aria-haspopup": "menu", "aria-expanded": open, "aria-label": ariaLabel, title: title, disabled: disabled, onClick: () => (open ? closeMenu(false) : openMenu()), onKeyDown: handleTriggerKeyDown, className: iconOnly
+                    ? className
+                    : [
+                        // `min-w-0` so a long label ("Filter: Has attachments") truncates instead of pushing
+                        // whatever sits beside it in the toolbar off the edge of a 384px list column.
+                        "inline-flex min-w-0 items-center gap-1 px-2 py-1 rounded-md text-sm text-text hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent",
+                        className,
+                    ].join(" "), children: [icon, !iconOnly && _jsx("span", { className: "truncate", children: label }), !iconOnly && _jsx(HiChevronDown, { size: 14, "aria-hidden": "true", className: "shrink-0 text-text-muted" })] }), open && (_jsx(PopoverPortal, { anchorRef: triggerRef, onClose: () => closeMenu(false), width: width, height: menuHeight(shownSections, width), "aria-label": ariaLabel, children: _jsx("div", { ref: setMenuNode, role: "menu", tabIndex: -1, "aria-label": ariaLabel, onKeyDown: handleMenuKeyDown, className: "flex-1 overflow-y-auto py-1", children: shownSections.map((section, sectionIndex) => (_jsxs("div", { role: "group", "aria-label": section.label, className: sectionIndex > 0 ? "border-t border-border mt-1 pt-1" : "", children: [section.label && (_jsx("div", { "aria-hidden": "true", className: "h-6 flex items-center px-3 text-xs font-semibold uppercase tracking-wide text-text-muted", children: section.label })), section.items.map((item) => {
+                                itemIndex += 1;
+                                const index = itemIndex;
+                                const role = item.role ?? "menuitem";
+                                return (_jsxs("button", { ref: (node) => {
+                                        itemRefs.current[index] = node;
+                                    }, type: "button", role: role, disabled: item.disabled, title: item.title, tabIndex: index === activeIndex ? 0 : -1, ...(role === "menuitem"
+                                        ? {}
+                                        : { "aria-checked": item.checked === "mixed" ? "mixed" : !!item.checked }), ...(item.submenu ? { "aria-haspopup": "menu", "aria-expanded": false } : {}), onClick: () => selectItem(item), className: "w-full flex items-start gap-2 px-3 py-2 text-left text-sm text-text hover:bg-surface-alt disabled:opacity-50 disabled:hover:bg-transparent", children: [_jsxs("span", { className: "w-4 shrink-0 flex justify-center pt-0.5", children: [item.key === "__back" && (_jsx(HiChevronLeft, { size: 14, "aria-hidden": "true", className: "text-text-muted" })), item.checked === "mixed" ? (_jsx(HiMinus, { size: 14, "aria-hidden": "true", className: "text-primary-dark" })) : (item.checked && _jsx(HiCheck, { size: 14, "aria-hidden": "true", className: "text-primary-dark" }))] }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsxs("span", { className: "flex h-5 items-center gap-1.5", children: [item.icon && (_jsx("span", { "aria-hidden": "true", className: "shrink-0 text-text-muted", children: item.icon })), item.swatchColor && (_jsx("span", { "aria-hidden": "true", className: "w-2.5 h-2.5 rounded-full shrink-0", style: { backgroundColor: item.swatchColor } })), _jsx("span", { className: "truncate", children: item.label })] }), item.description && (_jsx("span", { className: "block h-4 text-xs leading-4 text-text-muted truncate font-normal", children: item.description }))] }), item.submenu && (_jsx(HiChevronRight, { size: 14, "aria-hidden": "true", className: "shrink-0 mt-0.5 text-text-muted" }))] }, item.key));
+                            }), section.note && _jsx("p", { className: "px-3 py-1 text-xs leading-4 text-text-muted", children: section.note })] }, section.key))) }) }))] }));
+}

package/dist/lib/components/navigation/BottomTabBar.d.ts

@@ -34,6 +34,8 @@ export declare function splitTabs(apps: NavItem[], active: string): {
  * `hidden md:flex` there) — never both hidden or both visible at once.
  *
  * The entries share the width equally and never run off the screen: with more than `MAX_TABS`, the last slot is a "More" (…) button that opens a menu
- * of the others (see `splitTabs()`). The menu closes on Escape, on a click elsewhere and on choosing an entry.
+ * of the others (see `splitTabs()`). That is a plain disclosure - a button (`aria-expanded`, `aria-controls`) and a list of links, all reached by Tab - not an ARIA menu,
+ * which would owe its arrow-key navigation. It closes on Escape, on a click elsewhere, when focus tabs out of it and on choosing an entry; opened from the keyboard,
+ * it moves focus to its first link.
  */
 export default function BottomTabBar({ apps, active }: BottomTabBarProps): React.JSX.Element;

package/dist/lib/components/navigation/BottomTabBar.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import { HiOutlineEllipsisHorizontal } from "react-icons/hi2";
 import NavBadge, { navItemLabel } from "./NavBadge.js";
 /** The most entries the bar shows at once: any more and the last slot becomes "More", holding the rest. */
@@ -32,13 +32,23 @@ const TAB_CLASS = "flex-1 min-w-0 overflow-hidden px-1 flex flex-col items-cente
  * `hidden md:flex` there) — never both hidden or both visible at once.
  *
  * The entries share the width equally and never run off the screen: with more than `MAX_TABS`, the last slot is a "More" (…) button that opens a menu
- * of the others (see `splitTabs()`). The menu closes on Escape, on a click elsewhere and on choosing an entry.
+ * of the others (see `splitTabs()`). That is a plain disclosure - a button (`aria-expanded`, `aria-controls`) and a list of links, all reached by Tab - not an ARIA menu,
+ * which would owe its arrow-key navigation. It closes on Escape, on a click elsewhere, when focus tabs out of it and on choosing an entry; opened from the keyboard,
+ * it moves focus to its first link.
  */
 export default function BottomTabBar({ apps, active }) {
     const { shown, more } = splitTabs(apps, active);
     const [open, setOpen] = useState(false);
     const rootRef = useRef(null);
     const buttonRef = useRef(null);
+    const popupId = useId();
+    // Whether the press that opened it was the keyboard's (a click with no pointer has a `detail` of 0).
+    const openedByKeyboard = useRef(false);
+    useEffect(() => {
+        if (open && openedByKeyboard.current) {
+            rootRef.current.querySelector("a").focus();
+        }
+    }, [open]);
     useEffect(() => {
         if (!open) {
             return;
@@ -65,5 +75,14 @@ export default function BottomTabBar({ apps, active }) {
     }, [open]);
     // The unread count of an entry that is behind "More" is still worth a dot on it.
     const hiddenBadge = more.some((app) => (app.badge ?? 0) > 0);
-    return (_jsxs("nav", { "aria-label": "Mobile navigation", className: "md:hidden fixed bottom-0 inset-x-0 z-30 h-14 bg-surface border-t border-border flex items-stretch", children: [shown.map(({ id, href, label, icon: Icon, badge }) => (_jsxs("a", { href: href, "aria-label": badge ? navItemLabel(label, badge) : undefined, "aria-current": id === active ? "page" : undefined, className: [TAB_CLASS, id === active ? "text-primary-dark" : "text-text-muted"].join(" "), children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), _jsx(NavBadge, { count: badge })] }), label] }, id))), more.length > 0 && (_jsxs("div", { ref: rootRef, className: "flex-1 min-w-0 flex items-stretch relative", children: [_jsxs("button", { ref: buttonRef, type: "button", "aria-label": hiddenBadge ? "More, with unread items" : "More", "aria-haspopup": "menu", "aria-expanded": open, onClick: () => setOpen((value) => !value), className: [TAB_CLASS, "w-full", open ? "text-primary-dark" : "text-text-muted"].join(" "), children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(HiOutlineEllipsisHorizontal, { size: 20, "aria-hidden": "true" }), hiddenBadge && _jsx("span", { "aria-hidden": "true", "data-testid": "more-dot", className: "absolute -top-0.5 -right-1 size-2 rounded-full bg-danger" })] }), _jsx("span", { children: "More" })] }), open && (_jsx("ul", { role: "menu", "aria-label": "More", className: "absolute bottom-full right-1 mb-2 min-w-48 max-w-[calc(100vw-1rem)] rounded-md border border-border bg-surface py-1 shadow-modal", children: more.map(({ id, href, label, icon: Icon, badge }) => (_jsx("li", { role: "none", children: _jsxs("a", { role: "menuitem", href: href, "aria-label": badge ? navItemLabel(label, badge) : undefined, onClick: () => setOpen(false), className: "flex items-center gap-3 px-4 py-3 text-sm text-text hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary", children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), _jsx(NavBadge, { count: badge })] }), label] }) }, id))) }))] }))] }));
+    return (_jsxs("nav", { "aria-label": "Mobile navigation", className: "md:hidden fixed bottom-0 inset-x-0 z-30 h-14 bg-surface border-t border-border flex items-stretch", children: [shown.map(({ id, href, label, icon: Icon, badge }) => (_jsxs("a", { href: href, "aria-label": badge ? navItemLabel(label, badge) : undefined, "aria-current": id === active ? "page" : undefined, className: [TAB_CLASS, id === active ? "text-primary-dark" : "text-text-muted"].join(" "), children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), _jsx(NavBadge, { count: badge })] }), label] }, id))), more.length > 0 && (_jsxs("div", { ref: rootRef, className: "flex-1 min-w-0 flex items-stretch relative", 
+                // Focus moved on to something outside (not merely lost, as a tap on a link does in a browser that does not focus links).
+                onBlur: (event) => {
+                    if (event.relatedTarget instanceof Node && !event.currentTarget.contains(event.relatedTarget)) {
+                        setOpen(false);
+                    }
+                }, children: [_jsxs("button", { ref: buttonRef, type: "button", "aria-label": hiddenBadge ? "More, with unread items" : "More", "aria-expanded": open, "aria-controls": open ? popupId : undefined, onClick: (event) => {
+                            openedByKeyboard.current = event.detail === 0;
+                            setOpen((value) => !value);
+                        }, className: [TAB_CLASS, "w-full", open ? "text-primary-dark" : "text-text-muted"].join(" "), children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(HiOutlineEllipsisHorizontal, { size: 20, "aria-hidden": "true" }), hiddenBadge && _jsx("span", { "aria-hidden": "true", "data-testid": "more-dot", className: "absolute -top-0.5 -right-1 size-2 rounded-full bg-danger" })] }), _jsx("span", { children: "More" })] }), open && (_jsx("ul", { id: popupId, "aria-label": "More", className: "absolute bottom-full right-1 mb-2 min-w-48 max-w-[calc(100vw-1rem)] rounded-md border border-border bg-surface py-1 shadow-modal", children: more.map(({ id, href, label, icon: Icon, badge }) => (_jsx("li", { children: _jsxs("a", { href: href, "aria-label": badge ? navItemLabel(label, badge) : undefined, onClick: () => setOpen(false), className: "flex items-center gap-3 px-4 py-3 text-sm text-text hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary", children: [_jsxs("span", { className: "relative inline-flex", children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), _jsx(NavBadge, { count: badge })] }), label] }) }, id))) }))] }))] }));
 }

package/dist/lib/components/overlays/PopoverPortal.d.ts

@@ -18,6 +18,7 @@ export interface PopoverPortalProps {
  * isn't a stacking-order problem `z-index` can override). Prefers opening *below* the anchor (there's
  * more room in the editor area below the toolbar than above it, where the To/Cc/Subject rows are —
  * confirmed directly: an earlier `absolute`+`overflow-hidden` version of this rendered the popup
- * behind those rows), flipping to *above* only if there isn't enough room below.
+ * behind those rows), flipping to *above* only if there isn't enough room below. Its `z-index` is above a `Modal`/`Drawer` backdrop (`z-[1000]`), so a popover opened from inside
+ * a dialog (the contact card's photo menu) is not hidden behind it.
  */
 export default function PopoverPortal({ anchorRef, onClose, width, height, children, ...rest }: PropsWithChildren<PopoverPortalProps>): React.ReactPortal | null;

package/dist/lib/components/overlays/PopoverPortal.js

@@ -13,7 +13,8 @@ import { createPortal } from "react-dom";
  * isn't a stacking-order problem `z-index` can override). Prefers opening *below* the anchor (there's
  * more room in the editor area below the toolbar than above it, where the To/Cc/Subject rows are —
  * confirmed directly: an earlier `absolute`+`overflow-hidden` version of this rendered the popup
- * behind those rows), flipping to *above* only if there isn't enough room below.
+ * behind those rows), flipping to *above* only if there isn't enough room below. Its `z-index` is above a `Modal`/`Drawer` backdrop (`z-[1000]`), so a popover opened from inside
+ * a dialog (the contact card's photo menu) is not hidden behind it.
  */
 export default function PopoverPortal({ anchorRef, onClose, width, height, children, ...rest }) {
     const containerRef = useRef(null);
@@ -49,5 +50,5 @@ export default function PopoverPortal({ anchorRef, onClose, width, height, child
     if (!style) {
         return null;
     }
-    return createPortal(_jsx("div", { ref: containerRef, role: "dialog", style: style, className: "z-50 flex flex-col bg-surface border border-border rounded-md shadow-modal overflow-hidden", ...rest, children: children }), document.body);
+    return createPortal(_jsx("div", { ref: containerRef, role: "dialog", style: style, className: "z-[1010] flex flex-col bg-surface border border-border rounded-md shadow-modal overflow-hidden", ...rest, children: children }), document.body);
 }

package/dist/lib/components/pickers/TimeZonePicker.js

@@ -50,6 +50,12 @@ export default function TimeZonePicker({ id, "aria-label": label, "aria-describe
         document.addEventListener("pointerdown", outside);
         return () => document.removeEventListener("pointerdown", outside);
     }, [open]);
+    // The arrow keys move `active` (and `aria-activedescendant`) only: the list scrolls, so the zone they reach has to be brought into view.
+    useEffect(() => {
+        if (open && active >= 0) {
+            document.getElementById(`${listId}-${active}`)?.scrollIntoView?.({ block: "nearest" });
+        }
+    }, [open, active]);
     function close(refocus) {
         setOpen(false);
         setQuery("");
@@ -88,7 +94,13 @@ export default function TimeZonePicker({ id, "aria-label": label, "aria-describe
             close(true);
         }
     }
-    return (_jsxs("div", { ref: root, className: "relative inline-block max-w-full", children: [_jsxs("button", { ref: trigger, id: id, type: "button", role: "combobox", "aria-label": label, "aria-describedby": describedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listId : undefined, className: ["flex items-center justify-between gap-2 text-left", className].filter(Boolean).join(" "), onClick: () => setOpen((wasOpen) => !wasOpen), onKeyDown: (event) => {
+    return (_jsxs("div", { ref: root, className: "relative inline-block max-w-full", 
+        // Tabbing away leaves the list open otherwise (only a press outside closed it). Focus that goes nowhere in particular (the window losing it) is not leaving.
+        onBlur: (event) => {
+            if (open && event.relatedTarget instanceof Node && !root.current?.contains(event.relatedTarget)) {
+                close(false);
+            }
+        }, children: [_jsxs("button", { ref: trigger, id: id, type: "button", role: "combobox", "aria-label": label, "aria-describedby": describedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listId : undefined, className: ["flex items-center justify-between gap-2 text-left", className].filter(Boolean).join(" "), onClick: () => setOpen((wasOpen) => !wasOpen), onKeyDown: (event) => {
                     if (event.key === "ArrowDown" && !open) {
                         event.preventDefault();
                         setOpen(true);

package/dist/lib/contacts/contactsApi.d.ts

@@ -156,14 +156,17 @@ export declare function updateContact(patch: ContactPatch, client?: ApiClient):
 export declare function setContactFavorite(contact: Contact, favorite: boolean, client?: ApiClient): Promise<Contact>;
 /**
  * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
- * served from the browser's cache.
+ * served from the browser's cache. Only an `<img src>` of the cookie-authenticated web app can load it: under an explicit `ApiClient` use
+ * `useContactPhotoSrc()` instead.
  */
 export declare function contactPhotoUrl(contact: Pick<Contact, "uid" | "version" | "photoBlobKey">): string | undefined;
 /** The picture types the server accepts for a contact, and the most bytes it takes. */
 export declare const CONTACT_PHOTO_TYPES: string[];
 export declare const CONTACT_PHOTO_MAX_BYTES: number;
 /** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
-export declare function uploadContactPhoto(uid: string, version: number, file: Blob): Promise<Contact>;
+export declare function uploadContactPhoto(uid: string, version: number, file: Blob, client?: ApiClient): Promise<Contact>;
+/** The bytes of a contact's own picture through an explicit `client` - for one that authenticates with a token, whose `<img>` cannot (see `contactPhotoUrl()`). */
+export declare function fetchContactPhoto(uid: string, version: number, client: ApiClient): Promise<Blob>;
 /** Removes a contact's own picture and returns the updated contact. */
 export declare function deleteContactPhoto(uid: string, version: number, client?: ApiClient): Promise<Contact>;
 export declare function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/contacts/contactsApi.js

@@ -4,13 +4,16 @@
 ///////////////////////////////////////////////////////////////////////////////
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
-import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
-import { buildQuery } from "../util/apiQuery.js";
+import { apiUrl, withClient, withClientRaw } from "../util/api.js";
+import { SETTINGS_LIST_LIMIT, buildQuery } from "../util/apiQuery.js";
 import { signingKeyFingerprints, } from "../crypto/keyvaultApi.js";
+/** The order a contacts list is read in: alphabetical, with the `uid` as the tie-breaker so contacts sharing a name keep one fixed order and
+ * a page boundary between them can neither skip nor repeat one. */
+const CONTACT_SORT = JSON.stringify({ displayName: "ASC", uid: "ASC" });
 /** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
  * `listDeletedContacts()` for those. */
 export function listContacts(folderUid, params = {}, client) {
-    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: JSON.stringify({ displayName: "ASC" }) })}`);
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: CONTACT_SORT })}`);
 }
 function contactsMatching(contacts, address) {
     const wanted = address.trim().toLowerCase();
@@ -95,7 +98,7 @@ export async function fetchSignerKeyState(folderUids, address, client) {
  * is browse-only until that lands.
  */
 export function listDeletedContacts(folderUid, params = {}, client) {
-    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: JSON.stringify({ displayName: "ASC" }) })}`);
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: CONTACT_SORT })}`);
 }
 export function getContact(uid, client) {
     return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}`);
@@ -120,7 +123,8 @@ export function setContactFavorite(contact, favorite, client) {
 }
 /**
  * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
- * served from the browser's cache.
+ * served from the browser's cache. Only an `<img src>` of the cookie-authenticated web app can load it: under an explicit `ApiClient` use
+ * `useContactPhotoSrc()` instead.
  */
 export function contactPhotoUrl(contact) {
     return contact.photoBlobKey ? apiUrl(`/mail/contacts/${encodeURIComponent(contact.uid)}/photo?v=${contact.version}`) : undefined;
@@ -129,19 +133,12 @@ export function contactPhotoUrl(contact) {
 export const CONTACT_PHOTO_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
 export const CONTACT_PHOTO_MAX_BYTES = 1024 * 1024;
 /** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
-export async function uploadContactPhoto(uid, version, file) {
-    const res = await fetch(apiUrl(`/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`), {
-        method: "PUT",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": file.type }, "PUT"),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Upload failed.", res.status, body?.code);
-    }
-    return body;
+export function uploadContactPhoto(uid, version, file, client) {
+    return withClientRaw(client, `/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`, "PUT", file);
+}
+/** The bytes of a contact's own picture through an explicit `client` - for one that authenticates with a token, whose `<img>` cannot (see `contactPhotoUrl()`). */
+export function fetchContactPhoto(uid, version, client) {
+    return client.fetchBlob(`/mail/contacts/${encodeURIComponent(uid)}/photo?v=${version}`);
 }
 /** Removes a contact's own picture and returns the updated contact. */
 export function deleteContactPhoto(uid, version, client) {
@@ -152,7 +149,7 @@ export function deleteContact(uid, version, client) {
 }
 /** Lists a mailbox's contact lists (Outlook-style "Your contact lists"), alphabetically by name. */
 export function listContactLists(mailboxUid, params = {}, client) {
-    return withClient(client, `/mail/contact-lists?${buildQuery(params, { mailboxUid, sort: JSON.stringify({ name: "ASC" }) })}`);
+    return withClient(client, `/mail/contact-lists?${buildQuery({ limit: SETTINGS_LIST_LIMIT, ...params }, { mailboxUid, sort: JSON.stringify({ name: "ASC", uid: "ASC" }) })}`);
 }
 export function createContactList(input, client) {
     return withClient(client, "/mail/contact-lists", { method: "POST", body: JSON.stringify(input) });

package/dist/lib/contacts/gravatar.d.ts

@@ -1,10 +1,21 @@
-/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+/** The `localStorage` key of the privacy preference: `"on"` lets contact avatars ask Gravatar for a picture; anything else (including unset or an old `"off"`) does not. */
 export declare const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+/** Fired on `window` when this tab changes the preference (the `storage` event covers other tabs). */
+export declare const GRAVATAR_PREFERENCE_EVENT = "rapidmx:gravatar-changed";
 /**
- * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
- * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). Off unless the reader turned it on
+ * in Settings > Privacy (`localStorage["rapidmx:gravatar"] = "on"`): it tells gravatar.com the hash and the reader's IP address. A browser without
+ * storage stays off.
  */
 export declare function gravatarEnabled(): boolean;
+/** Turns the Gravatar lookup on or off and tells every subscriber (`subscribeGravatarPreference()`) in this tab. */
+export declare function setGravatarEnabled(enabled: boolean): void;
+/** Calls `listener` whenever the preference changes in this tab or another; returns the unsubscribe function. Shaped for `useSyncExternalStore`. */
+export declare function subscribeGravatarPreference(listener: () => void): () => void;
+/** Remembers that Gravatar has no picture at `url`. */
+export declare function markGravatarMissing(url: string): void;
+/** Whether Gravatar already answered with no picture at `url`. */
+export declare function isGravatarMissing(url: string): boolean;
 /**
  * The Gravatar picture URL for `email`, `size` pixels square. It answers `404` (`d=404`) for a person with no Gravatar, so an `<img>` fails to load
  * and the caller falls back to initials rather than showing Gravatar's placeholder. `undefined` for an empty address or without Web Crypto.

package/dist/lib/contacts/gravatar.js

@@ -2,20 +2,57 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+/** The `localStorage` key of the privacy preference: `"on"` lets contact avatars ask Gravatar for a picture; anything else (including unset or an old `"off"`) does not. */
 export const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+/** Fired on `window` when this tab changes the preference (the `storage` event covers other tabs). */
+export const GRAVATAR_PREFERENCE_EVENT = "rapidmx:gravatar-changed";
 /**
- * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
- * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). Off unless the reader turned it on
+ * in Settings > Privacy (`localStorage["rapidmx:gravatar"] = "on"`): it tells gravatar.com the hash and the reader's IP address. A browser without
+ * storage stays off.
  */
 export function gravatarEnabled() {
     try {
-        return globalThis.localStorage?.getItem(GRAVATAR_PREFERENCE_KEY) !== "off";
+        return globalThis.localStorage.getItem(GRAVATAR_PREFERENCE_KEY) === "on";
     }
     catch {
-        return true;
+        return false;
     }
 }
+/** Turns the Gravatar lookup on or off and tells every subscriber (`subscribeGravatarPreference()`) in this tab. */
+export function setGravatarEnabled(enabled) {
+    try {
+        globalThis.localStorage.setItem(GRAVATAR_PREFERENCE_KEY, enabled ? "on" : "off");
+    }
+    catch {
+        // Storage is unavailable: the preference cannot be kept, so it stays off.
+    }
+    globalThis.dispatchEvent(new Event(GRAVATAR_PREFERENCE_EVENT));
+}
+/** Calls `listener` whenever the preference changes in this tab or another; returns the unsubscribe function. Shaped for `useSyncExternalStore`. */
+export function subscribeGravatarPreference(listener) {
+    const onStorage = (event) => {
+        if (event.key === null || event.key === GRAVATAR_PREFERENCE_KEY) {
+            listener();
+        }
+    };
+    globalThis.addEventListener(GRAVATAR_PREFERENCE_EVENT, listener);
+    globalThis.addEventListener("storage", onStorage);
+    return () => {
+        globalThis.removeEventListener(GRAVATAR_PREFERENCE_EVENT, listener);
+        globalThis.removeEventListener("storage", onStorage);
+    };
+}
+/** Gravatar URLs that answered with nothing, so a list that shows the same person again does not ask again for the page's lifetime. */
+const missing = new Set();
+/** Remembers that Gravatar has no picture at `url`. */
+export function markGravatarMissing(url) {
+    missing.add(url);
+}
+/** Whether Gravatar already answered with no picture at `url`. */
+export function isGravatarMissing(url) {
+    return missing.has(url);
+}
 const hashes = new Map();
 /** The lowercase-hex SHA-256 of a trimmed, lowercased `email`, or `undefined` where the browser has no Web Crypto (an insecure page). */
 function hashOf(email) {

package/dist/lib/contacts/preparePhoto.d.ts

@@ -0,0 +1,24 @@
+/** The longest side (in pixels) an accepted picture may have and still be sent as it is. */
+export declare const CONTACT_PHOTO_MAX_SIDE = 1024;
+/** The side (in pixels) of the square picture made from one that has to be changed - an avatar is shown at 72 pixels at most, 512 covers a high-density screen. */
+export declare const CONTACT_PHOTO_OUTPUT_SIDE = 512;
+/** JPEG qualities tried in turn until the picture fits `CONTACT_PHOTO_MAX_BYTES`. */
+export declare const CONTACT_PHOTO_QUALITIES: number[];
+/** The most pixels (width x height) a picture may have to be decoded: a few kilobytes of PNG can say 30000 x 30000, which takes gigabytes of memory to decode. */
+export declare const CONTACT_PHOTO_MAX_PIXELS = 16000000;
+export declare const CONTACT_PHOTO_UNSUPPORTED_MESSAGE = "This picture's format isn't supported by your browser \u2014 choose a JPEG or PNG instead.";
+export declare const CONTACT_PHOTO_TOO_LARGE_MESSAGE = "This picture could not be made small enough \u2014 choose another one.";
+/** Why a chosen picture cannot be used (a format the browser cannot decode, such as HEIC, or one that stays too large); its `message` is fit to show the user. */
+export declare class ContactPhotoError extends Error {
+    constructor(message?: string);
+}
+/**
+ * The picture to upload for `file`. A picture the server already takes (an accepted type within the byte limit and at most `CONTACT_PHOTO_MAX_SIDE` pixels a
+ * side) is returned as it is - an animated GIF stays animated - unless it is a JPEG, which is always drawn again to drop its EXIF. Anything else (a phone's 6 MB photo, a HEIC, a huge PNG) is decoded with its EXIF orientation applied,
+ * cropped to the centered square - avatars are circular, so the corners are never seen - scaled down to at most `CONTACT_PHOTO_OUTPUT_SIDE` pixels and encoded as a
+ * JPEG (transparent parts on white, quality lowered step by step until it fits), or kept as PNG/WebP when it has transparency and still fits.
+ *
+ * @throws ContactPhotoError when the browser cannot decode it (HEIC, or not a picture at all), it says it has more than `CONTACT_PHOTO_MAX_PIXELS` pixels
+ * (it is not decoded at all then) or it cannot be made small enough.
+ */
+export declare function prepareContactPhoto(file: File): Promise<File>;