@rapidmx/web-client 0.30.0 → 0.32.0

package/dist/lib/calendar/recurrence.js

@@ -42,10 +42,35 @@ const WEEKDAY_OBJECT = {
     SA: RRule.SA,
     SU: RRule.SU,
 };
+/** A rule's interval as `rrule` can take it: a whole number of at least 1. A zero, negative, fractional or missing one (an
+ * imported or hand-edited rule) would make `rrule` loop forever, or expand to nothing, so it counts as the default 1. */
+function normalizedInterval(interval) {
+    return Number.isFinite(interval) && interval >= 1 ? Math.floor(interval) : 1;
+}
+/** The most days each month (January first) can ever have, counting February as a leap year's. */
+const MAX_DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Throws for a rule that can never produce an occurrence: a month outside 1-12, a day of the month outside 1-31 (or -1 to -31), or days
+ * that no listed month has (the 30th of February). `rrule` has no way to know that, so `between()` walks every day up to the year 9999
+ * looking for one, which freezes the tab for seconds each time such an event is drawn.
+ */
+function assertSatisfiable(rule) {
+    const months = rule.byMonth ?? [];
+    const days = rule.byMonthDay ?? [];
+    if (months.some((m) => !Number.isInteger(m) || m < 1 || m > 12)) {
+        throw new Error("The recurrence rule has a month that does not exist");
+    }
+    if (days.some((d) => !Number.isInteger(d) || d === 0 || Math.abs(d) > 31)) {
+        throw new Error("The recurrence rule has a day of the month that does not exist");
+    }
+    if (months.length > 0 && days.length > 0 && !months.some((m) => days.some((d) => Math.abs(d) <= MAX_DAYS_IN_MONTH[m - 1]))) {
+        throw new Error("The recurrence rule names days that none of its months have");
+    }
+}
 function createRRule(rule, dtstart, until, tzid) {
     return new RRule({
         freq: FREQ_MAP[rule.freq],
-        interval: rule.interval,
+        interval: normalizedInterval(rule.interval),
         dtstart,
         tzid,
         byweekday: rule.byDay?.map((code) => WEEKDAY_OBJECT[code]),
@@ -150,6 +175,20 @@ export function toEventWallClock(instantMs, timezone, allDay) {
 export function fromEventWallClock(wallMs, timezone, allDay) {
     return (allDay ? UTC_ZONE : resolveZone(timezone)).fromWall(wallMs);
 }
+/**
+ * `startWall` moved forward by whole repeat periods to just before `from`, for a daily or weekly rule that has no `count`: `rrule`
+ * walks every occurrence from the start, so a series that began centuries ago would cost a hundred thousand steps each time it is
+ * drawn. A multiple of the period lands on the same days, so the occurrences from `from` on are exactly those of the original.
+ * Anything else is returned as it is.
+ */
+function advancedStart(rule, startWall, from) {
+    if (rule.count !== undefined || (rule.freq !== "daily" && rule.freq !== "weekly")) {
+        return startWall;
+    }
+    const period = normalizedInterval(rule.interval) * (rule.freq === "weekly" ? 7 : 1) * MS_PER_DAY;
+    const periods = Math.floor((from - startWall) / period) - 1;
+    return periods > 0 ? startWall + periods * period : startWall;
+}
 /**
  * Expands `event` into every occurrence whose interval overlaps `[rangeStart, rangeEnd]`. A
  * non-recurring event yields itself (in a one-element array) if it overlaps, or `[]` otherwise —
@@ -172,17 +211,18 @@ export function expandOccurrences(event, rangeStart, rangeEnd) {
         const overlaps = start < rangeEnd && end > rangeStart;
         return overlaps ? [{ ...event, occurrenceKey: event.uid, isRecurringOccurrence: false }] : [];
     }
+    assertSatisfiable(event.recurrenceRule);
     const zone = event.allDay ? UTC_ZONE : resolveZone(event.timezone);
     const startWall = zone.toWall(start.getTime());
     // The duration in wall-clock terms, so an occurrence also keeps its local end time across DST.
     const wallDurationMs = zone.toWall(end.getTime()) - startWall;
     const { until } = event.recurrenceRule;
-    const rule = createRRule(event.recurrenceRule, new Date(startWall), until ? new Date(zone.toWall(new Date(until).getTime())) : null, null);
     // Query in the wall-clock frame, widened by one occurrence's duration (so an occurrence that started
     // before `rangeStart` but is still in progress isn't missed) plus a day on each side to absorb the
     // zone's offset; the exact instant-based overlap filter at the end trims the excess.
     const queryStart = new Date(zone.toWall(rangeStart.getTime()) - wallDurationMs - MS_PER_DAY);
     const queryEnd = new Date(zone.toWall(rangeEnd.getTime()) + MS_PER_DAY);
+    const rule = createRRule(event.recurrenceRule, new Date(advancedStart(event.recurrenceRule, startWall, queryStart.getTime())), until ? new Date(zone.toWall(new Date(until).getTime())) : null, null);
     const occurrenceStarts = rule
         .between(queryStart, queryEnd, true)
         .map((occWall) => ({ start: new Date(zone.fromWall(occWall.getTime())), wall: occWall.getTime() }));
@@ -206,7 +246,15 @@ export function expandOccurrences(event, rangeStart, rangeEnd) {
 }
 /** Expands every event in `events` and flattens the result — the usual entry point for a grid view. */
 export function expandAllOccurrences(events, rangeStart, rangeEnd) {
-    return events.flatMap((event) => expandOccurrences(event, rangeStart, rangeEnd));
+    return events.flatMap((event) => {
+        try {
+            return expandOccurrences(event, rangeStart, rangeEnd);
+        }
+        catch {
+            // One event whose rule or dates cannot be expanded must not blank the whole grid: it is shown once, as the stored event.
+            return expandOccurrences({ ...event, recurrenceRule: undefined }, rangeStart, rangeEnd);
+        }
+    });
 }
 /** A human-readable summary of `rule` (e.g. "every 2 weeks on Monday, Wednesday until Jan 1, 2027"). */
 export function describeRecurrence(rule) {

package/dist/lib/calendar/useDayKey.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Today's local date as `YYYY-MM-DD`, kept current: it ticks over at the next local midnight, so a page left open overnight stops treating yesterday
+ * as today (use it as a dependency of whatever was worked out from "now"). It is also re-read when the tab becomes visible again or the window is focused or shown
+ * again, as a hidden tab's timers are throttled or suspended (a sleeping laptop, which may wake with the tab still "visible" and so with no `visibilitychange`).
+ * Every re-read sets the timer again from the real clock, so a timer that fired a day late cannot leave the key behind.
+ */
+export declare function useDayKey(): string;

package/dist/lib/calendar/useDayKey.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { addDays, format, startOfDay } from "date-fns";
+/** How long past local midnight the key is re-read, so a timer that fires a hair early does not land on the day that is ending. */
+const MIDNIGHT_SLACK_MS = 1000;
+/**
+ * Today's local date as `YYYY-MM-DD`, kept current: it ticks over at the next local midnight, so a page left open overnight stops treating yesterday
+ * as today (use it as a dependency of whatever was worked out from "now"). It is also re-read when the tab becomes visible again or the window is focused or shown
+ * again, as a hidden tab's timers are throttled or suspended (a sleeping laptop, which may wake with the tab still "visible" and so with no `visibilitychange`).
+ * Every re-read sets the timer again from the real clock, so a timer that fired a day late cannot leave the key behind.
+ */
+export function useDayKey() {
+    const [dayKey, setDayKey] = useState(() => format(new Date(), "yyyy-MM-dd"));
+    useEffect(() => {
+        let timer;
+        // Re-reads the day and sets the timer for the midnight after it, replacing any that is pending.
+        function arm() {
+            clearTimeout(timer);
+            const now = new Date();
+            setDayKey(format(now, "yyyy-MM-dd"));
+            timer = setTimeout(arm, addDays(startOfDay(now), 1).getTime() - now.getTime() + MIDNIGHT_SLACK_MS);
+        }
+        function onVisible() {
+            if (document.visibilityState === "visible") {
+                arm();
+            }
+        }
+        arm();
+        document.addEventListener("visibilitychange", onVisible);
+        window.addEventListener("focus", arm);
+        window.addEventListener("pageshow", arm);
+        return () => {
+            clearTimeout(timer);
+            document.removeEventListener("visibilitychange", onVisible);
+            window.removeEventListener("focus", arm);
+            window.removeEventListener("pageshow", arm);
+        };
+    }, []);
+    return dayKey;
+}

package/dist/lib/components/avatar/ContactAvatar.d.ts

@@ -4,11 +4,15 @@ export interface ContactAvatarProps {
     size?: number;
     /** The contact's own picture (see `contactPhotoUrl()`); shown in preference to anything else. */
     photoUrl?: string;
-    /** The contact's address: without a picture of their own, its Gravatar is shown when there is one (and the reader hasn't turned that off). */
+    /** The contact's address: without a picture of their own, its Gravatar is shown when there is one (and the reader turned that on in Settings > Privacy). */
     email?: string;
+    /** The contact's own picture exists but has not arrived (it is being fetched): Gravatar is not asked about an address whose owner has a picture of their own. */
+    photoPending?: boolean;
+    /** Called once, when the avatar scrolls into view - for a picture that is only fetched by then. */
+    onVisible?: () => void;
 }
 /**
  * A small circular avatar for a contact, matching Outlook People's: the contact's own picture when they have one, else their Gravatar (when `email`
  * is given), else initials on a color that is deterministic per name. A picture that fails to load falls through to the next.
  */
-export default function ContactAvatar({ displayName, size, photoUrl, email }: ContactAvatarProps): React.JSX.Element;
+export default function ContactAvatar({ displayName, size, photoUrl, email, photoPending, onVisible }: ContactAvatarProps): React.JSX.Element;

package/dist/lib/components/avatar/ContactAvatar.js

@@ -3,8 +3,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useState } from "react";
-import { gravatarEnabled, gravatarUrl } from "../../contacts/gravatar.js";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { gravatarEnabled, gravatarUrl, isGravatarMissing, markGravatarMissing, subscribeGravatarPreference } from "../../contacts/gravatar.js";
 /** A fixed palette of background colors, cycled by a hash of the contact's name, for the initials shown when there is no picture. */
 const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
 function initialsOf(displayName) {
@@ -27,23 +27,52 @@ function colorOf(displayName) {
  * A small circular avatar for a contact, matching Outlook People's: the contact's own picture when they have one, else their Gravatar (when `email`
  * is given), else initials on a color that is deterministic per name. A picture that fails to load falls through to the next.
  */
-export default function ContactAvatar({ displayName, size = 32, photoUrl, email }) {
+export default function ContactAvatar({ displayName, size = 32, photoUrl, email, photoPending, onVisible }) {
     const [gravatar, setGravatar] = useState();
     const [failed, setFailed] = useState([]);
+    const enabled = useSyncExternalStore(subscribeGravatarPreference, gravatarEnabled, () => false);
+    // Without IntersectionObserver there is no telling what is on screen, so look up at once.
+    const [visible, setVisible] = useState(() => typeof IntersectionObserver === "undefined");
+    const placeholder = useRef(null);
+    const ownPicture = photoPending || (!!photoUrl && !failed.includes(photoUrl));
+    // A new picture gets a fresh start, whatever failed to load before.
+    useEffect(() => {
+        setFailed((list) => (list.length ? [] : list));
+    }, [photoUrl]);
+    // Only an avatar that is on screen (and has no picture of its own to show) asks Gravatar, so a long list does not send a request per row.
+    useEffect(() => {
+        const element = placeholder.current;
+        if (visible || !element || !(onVisible || (enabled && email && !ownPicture))) {
+            return;
+        }
+        const observer = new IntersectionObserver((entries) => {
+            if (entries.some((entry) => entry.isIntersecting)) {
+                setVisible(true);
+                onVisible?.();
+            }
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [visible, enabled, email, ownPicture, onVisible]);
     useEffect(() => {
         setGravatar(undefined);
-        if (!email || !gravatarEnabled()) {
+        if (!email || !enabled || !visible || ownPicture) {
             return;
         }
         let cancelled = false;
-        void gravatarUrl(email, size * 2).then((url) => !cancelled && setGravatar(url));
+        void gravatarUrl(email, size * 2).then((url) => !cancelled && setGravatar(url && !isGravatarMissing(url) ? url : undefined));
         return () => {
             cancelled = true;
         };
-    }, [email, size]);
+    }, [email, size, enabled, visible, ownPicture]);
     const src = [photoUrl, gravatar].find((url) => url && !failed.includes(url));
     if (src) {
-        return (_jsx("img", { src: src, alt: "", "aria-hidden": "true", width: size, height: size, referrerPolicy: "no-referrer", onError: () => setFailed((list) => [...list, src]), className: "inline-block rounded-full object-cover shrink-0", style: { width: size, height: size } }));
+        return (_jsx("img", { src: src, alt: "", "aria-hidden": "true", width: size, height: size, referrerPolicy: "no-referrer", loading: "lazy", decoding: "async", onError: () => {
+                if (src === gravatar) {
+                    markGravatarMissing(src);
+                }
+                setFailed((list) => [...list, src]);
+            }, className: "inline-block rounded-full object-cover shrink-0", style: { width: size, height: size } }));
     }
-    return (_jsx("span", { "aria-hidden": "true", style: { width: size, height: size, backgroundColor: colorOf(displayName), fontSize: size * 0.4 }, className: "inline-flex items-center justify-center rounded-full text-white font-semibold shrink-0", children: initialsOf(displayName) }));
+    return (_jsx("span", { ref: placeholder, "aria-hidden": "true", style: { width: size, height: size, backgroundColor: colorOf(displayName), fontSize: size * 0.4 }, className: "inline-flex items-center justify-center rounded-full text-white font-semibold shrink-0", children: initialsOf(displayName) }));
 }

package/dist/lib/components/avatar/ContactPhotoAvatar.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import type { Contact } from "../../contacts/contactsApi.js";
+import { type ContactAvatarProps } from "./ContactAvatar.js";
+export interface ContactPhotoAvatarProps extends Omit<ContactAvatarProps, "photoUrl"> {
+    /** The stored contact whose own picture is shown, if any. */
+    contact?: Pick<Contact, "uid" | "version" | "photoBlobKey">;
+    /** For a row of a long list: a picture that has to be fetched (a token-authenticated app) is only fetched once the avatar scrolls into view. */
+    lazy?: boolean;
+}
+/** A `ContactAvatar` showing a stored contact's own picture the way the current app can load it - see `useContactPhotoSrc()`. */
+export default function ContactPhotoAvatar({ contact, lazy, ...rest }: ContactPhotoAvatarProps): React.JSX.Element;

package/dist/lib/components/avatar/ContactPhotoAvatar.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useState } from "react";
+import { useContactPhoto } from "../../contacts/useContactPhotoSrc.js";
+import { useApiClient } from "../../util/apiClientContext.js";
+import ContactAvatar from "./ContactAvatar.js";
+/** A `ContactAvatar` showing a stored contact's own picture the way the current app can load it - see `useContactPhotoSrc()`. */
+export default function ContactPhotoAvatar({ contact, lazy, ...rest }) {
+    // Without IntersectionObserver there is no telling what is on screen, so the picture is fetched at once.
+    const [visible, setVisible] = useState(() => !lazy || typeof IntersectionObserver === "undefined");
+    const show = useCallback(() => setVisible(true), []);
+    const { src, failed } = useContactPhoto(contact, useApiClient(), visible);
+    // A picture that exists but is not here yet - not fetched yet or on its way - keeps Gravatar from being asked; one that could not be fetched does not.
+    return _jsx(ContactAvatar, { ...rest, photoUrl: src, photoPending: !!contact?.photoBlobKey && !src && !failed, onVisible: visible ? undefined : show });
+}

package/dist/lib/components/forms/CameraCaptureModal.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+export interface CameraCaptureModalProps {
+    /** Called with the captured picture (a JPEG of the frame on screen); the camera is already released. The caller closes the dialog. */
+    onCapture: (file: File) => void;
+    onClose: () => void;
+    /** Also told why the camera could not be used or the picture not captured (the dialog shows it itself too). */
+    onError?: (message: string) => void;
+}
+export declare const CAMERA_BLOCKED_MESSAGE = "Camera access was blocked - allow it in your browser's settings, or choose Upload file.";
+export declare const CAMERA_MISSING_MESSAGE = "No camera was found on this device - choose Upload file instead.";
+export declare const CAMERA_FAILED_MESSAGE = "The camera could not be started - choose Upload file instead.";
+/**
+ * A dialog with the live picture of the device's camera (the front one where there is a choice) and a Capture button, for a computer with a webcam - a phone's own
+ * camera is reached through a file input's `capture` attribute instead. Asking for the camera is what makes the browser prompt for permission; every track is
+ * stopped again when the dialog goes away (captured, cancelled, or the page left), which is what turns the camera's light off.
+ */
+export default function CameraCaptureModal({ onCapture, onClose, onError }: CameraCaptureModalProps): React.JSX.Element;

package/dist/lib/components/forms/CameraCaptureModal.js

@@ -0,0 +1,88 @@
+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 Button from "../buttons/Button.js";
+import Alert from "../feedback/Alert.js";
+import Modal from "../overlays/Modal.js";
+export const CAMERA_BLOCKED_MESSAGE = "Camera access was blocked - allow it in your browser's settings, or choose Upload file.";
+export const CAMERA_MISSING_MESSAGE = "No camera was found on this device - choose Upload file instead.";
+export const CAMERA_FAILED_MESSAGE = "The camera could not be started - choose Upload file instead.";
+/** The friendly reason a `getUserMedia()` rejection gives (`NotAllowedError`/`SecurityError`: the user or the page's policy said no; `NotFoundError`/`OverconstrainedError`: no camera). */
+function cameraErrorMessage(err) {
+    const name = err?.name;
+    if (name === "NotAllowedError" || name === "SecurityError") {
+        return CAMERA_BLOCKED_MESSAGE;
+    }
+    if (name === "NotFoundError" || name === "OverconstrainedError" || name === "DevicesNotFoundError") {
+        return CAMERA_MISSING_MESSAGE;
+    }
+    return CAMERA_FAILED_MESSAGE;
+}
+/**
+ * A dialog with the live picture of the device's camera (the front one where there is a choice) and a Capture button, for a computer with a webcam - a phone's own
+ * camera is reached through a file input's `capture` attribute instead. Asking for the camera is what makes the browser prompt for permission; every track is
+ * stopped again when the dialog goes away (captured, cancelled, or the page left), which is what turns the camera's light off.
+ */
+export default function CameraCaptureModal({ onCapture, onClose, onError }) {
+    const video = useRef(null);
+    const stream = useRef(null);
+    // Cleared when the dialog is cancelled or gone: a frame still being encoded then must not reach `onCapture` of a caller that has moved on.
+    const open = useRef(true);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    // From pressing Capture until the frame is encoded: a second press then would hand the caller a second picture.
+    const [capturing, setCapturing] = useState(false);
+    function fail(message) {
+        setError(message);
+        onError?.(message);
+    }
+    function stop() {
+        stream.current?.getTracks().forEach((track) => track.stop());
+        stream.current = null;
+    }
+    useEffect(() => {
+        let cancelled = false;
+        navigator.mediaDevices.getUserMedia({ video: { facingMode: "user", width: { ideal: 1280 }, height: { ideal: 1280 } } }).then((media) => {
+            if (cancelled) {
+                media.getTracks().forEach((track) => track.stop());
+                return;
+            }
+            stream.current = media;
+            video.current.srcObject = media;
+        }, (err) => !cancelled && fail(cameraErrorMessage(err)));
+        return () => {
+            cancelled = true;
+            open.current = false;
+            stop();
+        };
+    }, []);
+    function close() {
+        open.current = false;
+        stop();
+        onClose();
+    }
+    function capture() {
+        setCapturing(true);
+        const element = video.current;
+        const canvas = document.createElement("canvas");
+        canvas.width = element.videoWidth;
+        canvas.height = element.videoHeight;
+        canvas.getContext("2d").drawImage(element, 0, 0, canvas.width, canvas.height);
+        canvas.toBlob((blob) => {
+            if (!open.current) {
+                return;
+            }
+            if (!blob) {
+                setCapturing(false);
+                fail("The picture could not be captured - try again.");
+                return;
+            }
+            stop();
+            onCapture(new File([blob], "photo.jpg", { type: "image/jpeg" }));
+        }, "image/jpeg", 0.92);
+    }
+    return (_jsxs(Modal, { open: true, onClose: close, title: "Take photo", children: [error && _jsx(Alert, { children: error }), _jsx("video", { ref: video, autoPlay: true, playsInline: true, muted: true, "aria-label": "Camera preview", onLoadedMetadata: () => setReady(true), className: `w-full aspect-square object-cover rounded-sm bg-black -scale-x-100 ${error ? "hidden" : ""}` }), _jsxs("div", { className: "mt-5 flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: close, children: "Cancel" }), _jsx(Button, { type: "button", className: "!w-auto", disabled: !ready || !!error || capturing, onClick: capture, children: "Capture" })] })] }));
+}

package/dist/lib/components/forms/ImageEditBadge.d.ts

@@ -0,0 +1,28 @@
+import React from "react";
+export interface ImageEditBadgeProps {
+    /** Where the badge sits on the picture it edits: the lower right of an avatar, the upper right of a banner. */
+    position: "bottom-right" | "top-right";
+    /** Whether there is a picture to remove: "Remove photo" is in the menu only then. */
+    hasImage: boolean;
+    /** `"sm"` (20px) for a picture too small for the default 28px badge, such as a 48px avatar. */
+    size?: "sm" | "md";
+    /** Disables the badge while a chosen picture is being worked on. */
+    busy?: boolean;
+    /** The badge's accessible name, which also names its menu ("Change contact photo", "Change banner"). */
+    label: string;
+    /** The accessible name of the (hidden) file input "Upload file" opens. The camera input is named "<this> (camera)". */
+    fileInputLabel?: string;
+    /** Called with the picture as it was chosen or captured; the caller makes it fit what it stores. */
+    onFile: (file: File) => void;
+    /** Called by "Remove photo". Without it there is no such row. */
+    onRemove?: () => void;
+    /** Told why the camera could not be used (the camera dialog shows it too). */
+    onError?: (message: string) => void;
+}
+/**
+ * A round camera badge laid over the corner of a picture - an avatar or a banner - that opens a menu to change it: "Upload file", "Take photo" and, when there is a
+ * picture, "Remove photo". The badge is `position: absolute`, so the caller wraps the picture in a `relative` element (`relative inline-block` for an avatar) and puts this
+ * inside it. The menu is `MenuButton`'s: arrow keys, Enter, Escape and a click outside close it, focus returns to the badge. "Take photo" opens the device's camera app through
+ * an input's `capture` on a phone or tablet, and a live preview dialog (`getUserMedia`) on a computer; it is disabled, with a title that says why, where there is neither.
+ */
+export default function ImageEditBadge({ position, hasImage, busy, size, label, fileInputLabel, onFile, onRemove, onError }: ImageEditBadgeProps): React.JSX.Element;

package/dist/lib/components/forms/ImageEditBadge.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef, useState } from "react";
+import { HiArrowUpTray, HiCamera, HiTrash } from "react-icons/hi2";
+import MenuButton from "../menus/MenuButton.js";
+import CameraCaptureModal from "./CameraCaptureModal.js";
+/** How "Take photo" reaches the camera on this device, or why it cannot: a touch device (a phone or tablet) hands the picking to its own camera app through an input's
+ * `capture`; anything else with `getUserMedia` gets the live preview dialog. */
+function cameraAccess() {
+    if (typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches) {
+        return { mode: "capture" };
+    }
+    if (typeof navigator.mediaDevices?.getUserMedia === "function") {
+        return { mode: "preview" };
+    }
+    return {
+        unavailable: window.isSecureContext === false ? "The camera needs a secure (https) connection." : "This browser cannot use the camera - choose Upload file instead.",
+    };
+}
+const POSITIONS = { "bottom-right": "bottom-0 right-0", "top-right": "top-2 right-2" };
+const SIZES = { sm: { box: "h-5 w-5", icon: 12 }, md: { box: "h-7 w-7", icon: 14 } };
+/**
+ * A round camera badge laid over the corner of a picture - an avatar or a banner - that opens a menu to change it: "Upload file", "Take photo" and, when there is a
+ * picture, "Remove photo". The badge is `position: absolute`, so the caller wraps the picture in a `relative` element (`relative inline-block` for an avatar) and puts this
+ * inside it. The menu is `MenuButton`'s: arrow keys, Enter, Escape and a click outside close it, focus returns to the badge. "Take photo" opens the device's camera app through
+ * an input's `capture` on a phone or tablet, and a live preview dialog (`getUserMedia`) on a computer; it is disabled, with a title that says why, where there is neither.
+ */
+export default function ImageEditBadge({ position, hasImage, busy, size = "md", label, fileInputLabel = "Image file", onFile, onRemove, onError }) {
+    const fileInput = useRef(null);
+    const captureInput = useRef(null);
+    const [cameraOpen, setCameraOpen] = useState(false);
+    function fileChanged(e) {
+        const file = e.target.files?.[0];
+        if (file) {
+            onFile(file);
+        }
+        // The same file can be chosen again.
+        e.target.value = "";
+    }
+    const camera = cameraAccess();
+    const items = [
+        { key: "upload", label: "Upload file", icon: _jsx(HiArrowUpTray, { size: 14 }), onSelect: () => fileInput.current?.click() },
+        {
+            key: "camera",
+            label: "Take photo",
+            icon: _jsx(HiCamera, { size: 14 }),
+            disabled: !camera.mode,
+            title: camera.unavailable,
+            onSelect: () => (camera.mode === "capture" ? captureInput.current?.click() : setCameraOpen(true)),
+        },
+    ];
+    if (hasImage && onRemove) {
+        items.push({ key: "remove", label: "Remove photo", icon: _jsx(HiTrash, { size: 14 }), onSelect: onRemove });
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(MenuButton, { iconOnly: true, label: label, "aria-label": label, title: label, icon: _jsx(HiCamera, { size: SIZES[size].icon, "aria-hidden": "true" }), disabled: busy, width: 192, sections: [{ key: "image", items }], className: `absolute ${POSITIONS[position]} flex ${SIZES[size].box} items-center justify-center rounded-full bg-black/70 text-white ring-2 ring-surface hover:bg-black/80 disabled:opacity-50` }), _jsx("input", { ref: fileInput, type: "file", accept: "image/*", "aria-label": fileInputLabel, className: "sr-only", tabIndex: -1, onChange: fileChanged }), _jsx("input", { ref: captureInput, type: "file", accept: "image/*", capture: "user", "aria-label": `${fileInputLabel} (camera)`, className: "sr-only", tabIndex: -1, onChange: fileChanged }), cameraOpen && (_jsx(CameraCaptureModal, { onClose: () => setCameraOpen(false), onError: onError, onCapture: (file) => {
+                    setCameraOpen(false);
+                    onFile(file);
+                } }))] }));
+}

package/dist/lib/components/menus/MenuButton.d.ts

@@ -0,0 +1,78 @@
+import React, { ReactNode } from "react";
+/** What every row has. `checked` turns it into a radio/checkbox item (the caller says which via `role`) and
+ * draws the checkmark column; without it the row is a plain command. */
+interface MenuItemBase {
+    key: string;
+    label: string;
+    /** A one-line explanation under the label, for an item whose effect isn't obvious from its name. */
+    description?: string;
+    role?: "menuitem" | "menuitemradio" | "menuitemcheckbox";
+    /** `"mixed"` is ARIA's third checkbox state - some of the things this row acts on have it and some
+     * don't, which is what a label applied to only part of a multi-message selection looks like. */
+    checked?: boolean | "mixed";
+    /** A colour swatch before the label - a label's own colour. */
+    swatchColor?: string;
+    /** An icon before the label, for a menu whose rows are commands (the reading pane's "More actions"). */
+    icon?: ReactNode;
+    /** A tooltip for the row - the full text of a label the row truncates. */
+    title?: string;
+    disabled?: boolean;
+    /** Leaves the menu open after choosing this row, for a multi-select list where several rows are ticked
+     * before one command commits them all. */
+    keepOpen?: boolean;
+}
+/** A row that does something when chosen. */
+export interface MenuCommandSpec extends MenuItemBase {
+    onSelect: () => void;
+    submenu?: never;
+}
+/** A row that opens a submenu instead: choosing it replaces the menu's contents with these sections, under
+ * a Back row. One level deep, which is all any menu here needs - so it has nothing of its own to do. */
+export interface MenuSubmenuSpec extends MenuItemBase {
+    submenu: MenuSectionSpec[];
+    onSelect?: never;
+}
+export type MenuItemSpec = MenuCommandSpec | MenuSubmenuSpec;
+/** A labelled group of items. Groups after the first are drawn with a separator above them. */
+export interface MenuSectionSpec {
+    key: string;
+    label?: string;
+    /** A short note under the group's items - e.g. why some of them are unavailable right now. */
+    note?: string;
+    items: MenuItemSpec[];
+}
+/** The height `PopoverPortal` is asked for - exact for a short menu, capped (the list scrolls) for a long one. */
+export declare function menuHeight(sections: MenuSectionSpec[], width?: number): number;
+export interface MenuButtonProps {
+    /** The trigger's visible label. Not drawn (nor is the chevron) with `iconOnly`, where `aria-label` is all the trigger says. */
+    label: ReactNode;
+    /** The trigger is just its `icon` - a round icon button like the reading pane's own command row, whose `className` it takes over
+     * completely. `aria-label` (and `title`) name it. */
+    iconOnly?: boolean;
+    /** The trigger's accessible name, which also names the menu itself - includes the current selection
+     * where there is one ("Filter: Unread"), so the button says what it's set to, not just what it does. */
+    "aria-label": string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    title?: string;
+    sections: MenuSectionSpec[];
+    width?: number;
+    /** Extra classes for the trigger, on top of the shared toolbar-button styling. */
+    className?: string;
+    /** Told whenever the menu opens or closes - how a caller resets a draft it keeps for the menu's own
+     * multi-select rows (see `useLabelDraft()`). */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * 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, icon, disabled, title, sections, width, className, "aria-label": ariaLabel, onOpenChange, }: MenuButtonProps): React.JSX.Element;
+export {};