@rapidmx/web-client 0.30.0 → 0.32.0

package/lib/calendar/calendarApi.ts

@@ -151,6 +151,8 @@ export interface CalendarEvent {
 
 const LIST_PAGE_SIZE = 500;
 const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
+/** Without an order, a page boundary can skip or repeat an event: the `uid` is a fixed one. */
+const EVENT_SORT = JSON.stringify({ uid: "ASC" });
 
 /**
  * Lists every event in a folder (same "fetch the flat list, filter client-side" contract as
@@ -173,7 +175,7 @@ export async function listCalendarEvents(folderUid: string, client?: ApiClient):
     for (let page = 0; page < LIST_CALENDAR_EVENTS_MAX_PAGES; page++) {
         const batch = await withClient<CalendarEvent[]>(
             client,
-            `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid })}`,
+            `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid, sort: EVENT_SORT })}`,
         );
         events.push(...batch);
         if (batch.length < LIST_PAGE_SIZE) {

package/lib/calendar/eventSearch.ts

@@ -75,6 +75,37 @@ export function allOccurrences(events: CalendarEvent[], now: Date = new Date()):
     return occurrencesOf(events, () => true, now);
 }
 
+/**
+ * The `count` occurrences of `chronological` (a series, in order of start, as `expandOccurrences()` returns it) that start nearest `now`, still in order. They
+ * are the run around `now`, so that is grown from it a side at a time (the nearer side first, the earlier one on a tie) rather than sorting the whole series.
+ */
+function nearest(chronological: CalendarOccurrence[], now: number, count: number): CalendarOccurrence[] {
+    const startOf = (o: CalendarOccurrence) => new Date(o.startDate).getTime();
+    // The first that starts at or after now.
+    let low = 0;
+    let high = chronological.length;
+    while (low < high) {
+        const middle = (low + high) >> 1;
+        if (startOf(chronological[middle]) < now) {
+            low = middle + 1;
+        } else {
+            high = middle;
+        }
+    }
+    let from = low;
+    let to = low;
+    while (to - from < count) {
+        const before = from > 0 ? now - startOf(chronological[from - 1]) : Infinity;
+        const after = to < chronological.length ? startOf(chronological[to]) - now : Infinity;
+        if (before <= after) {
+            from--;
+        } else {
+            to++;
+        }
+    }
+    return chronological.slice(from, to);
+}
+
 /** The chronological occurrences of the `events` that `include` accepts (see `searchOccurrences()` for how a series is bounded). */
 function occurrencesOf(events: CalendarEvent[], include: (event: CalendarEvent) => boolean, now: Date): CalendarOccurrence[] {
     const from = addYears(now, -SEARCH_WINDOW_YEARS);
@@ -84,16 +115,25 @@ function occurrencesOf(events: CalendarEvent[], include: (event: CalendarEvent)
         if (!include(event)) {
             continue;
         }
+        const once = (): CalendarOccurrence[] =>
+            expandOccurrences(
+                { ...event, recurrenceRule: undefined },
+                new Date(new Date(event.startDate).getTime() - 1),
+                new Date(new Date(event.endDate).getTime() + 1),
+            );
         if (!event.recurrenceRule) {
-            found.push(...expandOccurrences(event, new Date(new Date(event.startDate).getTime() - 1), new Date(new Date(event.endDate).getTime() + 1)));
+            found.push(...once());
             continue;
         }
-        const occurrences = expandOccurrences(event, from, to);
-        if (occurrences.length > SEARCH_MAX_OCCURRENCES_PER_SERIES) {
-            const distance = (o: CalendarOccurrence) => Math.abs(new Date(o.startDate).getTime() - now.getTime());
-            occurrences.sort((a, b) => distance(a) - distance(b)).length = SEARCH_MAX_OCCURRENCES_PER_SERIES;
+        let occurrences: CalendarOccurrence[];
+        try {
+            occurrences = expandOccurrences(event, from, to);
+        } catch {
+            // One event whose rule or dates cannot be expanded must not fail the whole search or agenda: it counts once, as the stored event.
+            found.push(...once());
+            continue;
         }
-        found.push(...occurrences);
+        found.push(...(occurrences.length > SEARCH_MAX_OCCURRENCES_PER_SERIES ? nearest(occurrences, now.getTime(), SEARCH_MAX_OCCURRENCES_PER_SERIES) : occurrences));
     }
     return found.sort(byStart);
 }

package/lib/calendar/freeBusyApi.ts

@@ -78,18 +78,24 @@ export interface PersonAvailability {
 /** What a person's calendar says about a stretch of time. `"unknown"` is any person the server did not (or would not) tell about - never free. */
 export type AvailabilityState = "free" | "tentative" | "busy" | "unknown";
 
-/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). */
+/** The response's results with their times as milliseconds (a person who isn't `"available"` has no blocks whatever the server sent). A window
+ * whose start or end can't be read is busy for all time - never silently free, which is what comparing `NaN` would make it. */
 export function availabilityOf(response: FreeBusyResponse): PersonAvailability[] {
     return response.results.map((result) => ({
         address: result.address,
         status: result.status,
-        busy:
-            result.status === "available"
-                ? result.busy.map((window) => ({ startMs: Date.parse(window.start), endMs: Date.parse(window.end), tentative: window.tentative }))
-                : [],
+        busy: result.status === "available" ? result.busy.map(toBusyBlock) : [],
     }));
 }
 
+function toBusyBlock(window: { start: string; end: string; tentative: boolean }): BusyBlock {
+    const startMs = Date.parse(window.start);
+    const endMs = Date.parse(window.end);
+    return Number.isFinite(startMs) && Number.isFinite(endMs)
+        ? { startMs, endMs, tentative: window.tentative }
+        : { startMs: Number.NEGATIVE_INFINITY, endMs: Number.POSITIVE_INFINITY, tentative: window.tentative };
+}
+
 /** Whether a block overlaps the stretch from `startMs` to `endMs` (touching ends do not overlap). */
 function overlaps(block: BusyBlock, startMs: number, endMs: number): boolean {
     return block.startMs < endMs && block.endMs > startMs;
@@ -165,6 +171,8 @@ export interface SuggestTimesOptions {
 }
 
 const DEFAULT_STEP_MS = 30 * 60_000;
+/** The finest step `suggestTimes()` takes: a zero or negative one would never advance, a tiny one would test millions of slots. */
+const MIN_STEP_MS = 60_000;
 const DEFAULT_SUGGESTIONS = 5;
 
 /**
@@ -177,7 +185,7 @@ export function suggestTimes(people: PersonAvailability[], options: SuggestTimes
     if (known.length === 0 || options.durationMs <= 0) {
         return [];
     }
-    const step = options.stepMs ?? DEFAULT_STEP_MS;
+    const step = Number.isFinite(options.stepMs) ? Math.max(MIN_STEP_MS, options.stepMs!) : DEFAULT_STEP_MS;
     const limit = options.limit ?? DEFAULT_SUGGESTIONS;
     const found: number[] = [];
     for (const window of [...options.windows].sort((a, b) => a.startMs - b.startMs)) {

package/lib/calendar/recurrence.ts

@@ -50,10 +50,38 @@ const WEEKDAY_OBJECT: Record<WeekdayCode, Weekday> = {
     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: number): number {
+    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: RecurrenceRule): void {
+    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: RecurrenceRule, dtstart: Date, until: Date | null, tzid: string | null): RRuleNS.RRule {
     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]),
@@ -199,6 +227,21 @@ export function fromEventWallClock(wallMs: number, timezone: string | undefined,
     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: RecurrenceRule, startWall: number, from: number): number {
+    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 —
@@ -223,22 +266,23 @@ export function expandOccurrences(event: CalendarEvent, rangeStart: Date, rangeE
         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() }));
@@ -264,7 +308,14 @@ export function expandOccurrences(event: CalendarEvent, rangeStart: Date, rangeE
 
 /** Expands every event in `events` and flattens the result — the usual entry point for a grid view. */
 export function expandAllOccurrences(events: CalendarEvent[], rangeStart: Date, rangeEnd: Date): CalendarOccurrence[] {
-    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"). */

package/lib/calendar/useDayKey.ts

@@ -0,0 +1,45 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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(): string {
+    const [dayKey, setDayKey] = useState(() => format(new Date(), "yyyy-MM-dd"));
+    useEffect(() => {
+        let timer: ReturnType<typeof setTimeout>;
+        // 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/lib/components/avatar/ContactAvatar.tsx

@@ -2,16 +2,20 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React, { useEffect, useState } from "react";
-import { gravatarEnabled, gravatarUrl } from "../../contacts/gravatar.js";
+import React, { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { gravatarEnabled, gravatarUrl, isGravatarMissing, markGravatarMissing, subscribeGravatarPreference } from "../../contacts/gravatar.js";
 
 export interface ContactAvatarProps {
     displayName: string;
     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 fixed palette of background colors, cycled by a hash of the contact's name, for the initials shown when there is no picture. */
@@ -39,21 +43,47 @@ function colorOf(displayName: string): string {
  * 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 }: ContactAvatarProps) {
+export default function ContactAvatar({ displayName, size = 32, photoUrl, email, photoPending, onVisible }: ContactAvatarProps) {
     const [gravatar, setGravatar] = useState<string | undefined>();
     const [failed, setFailed] = useState<string[]>([]);
+    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<HTMLSpanElement>(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) {
@@ -65,7 +95,14 @@ export default function ContactAvatar({ displayName, size = 32, photoUrl, email
                 width={size}
                 height={size}
                 referrerPolicy="no-referrer"
-                onError={() => setFailed((list) => [...list, src])}
+                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 }}
             />
@@ -73,6 +110,7 @@ export default function ContactAvatar({ displayName, size = 32, photoUrl, email
     }
     return (
         <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"

package/lib/components/avatar/ContactPhotoAvatar.tsx

@@ -0,0 +1,26 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useCallback, useState } from "react";
+import type { Contact } from "../../contacts/contactsApi.js";
+import { useContactPhoto } from "../../contacts/useContactPhotoSrc.js";
+import { useApiClient } from "../../util/apiClientContext.js";
+import ContactAvatar, { 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) {
+    // 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 <ContactAvatar {...rest} photoUrl={src} photoPending={!!contact?.photoBlobKey && !src && !failed} onVisible={visible ? undefined : show} />;
+}

package/lib/components/forms/CameraCaptureModal.tsx

@@ -0,0 +1,133 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useRef, useState } from "react";
+import Button from "../buttons/Button.js";
+import Alert from "../feedback/Alert.js";
+import Modal from "../overlays/Modal.js";
+
+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 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: unknown): string {
+    const name = (err as { name?: string } | null)?.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 }: CameraCaptureModalProps) {
+    const video = useRef<HTMLVideoElement>(null);
+    const stream = useRef<MediaStream | null>(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<string | null>(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: string) {
+        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 (
+        <Modal open onClose={close} title="Take photo">
+            {error && <Alert>{error}</Alert>}
+            {/* Mirrored like a mirror, which is what looking at yourself expects; the picture that is kept is not. */}
+            <video
+                ref={video}
+                autoPlay
+                playsInline
+                muted
+                aria-label="Camera preview"
+                onLoadedMetadata={() => setReady(true)}
+                className={`w-full aspect-square object-cover rounded-sm bg-black -scale-x-100 ${error ? "hidden" : ""}`}
+            />
+            <div className="mt-5 flex justify-end gap-2">
+                <Button type="button" variant="secondary" className="!w-auto" onClick={close}>
+                    Cancel
+                </Button>
+                <Button type="button" className="!w-auto" disabled={!ready || !!error || capturing} onClick={capture}>
+                    Capture
+                </Button>
+            </div>
+        </Modal>
+    );
+}