@rapidmx/web-client 0.22.0 → 0.24.0

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

@@ -0,0 +1,100 @@
+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, useId, useMemo, useRef, useState } from "react";
+import { compareTimeZones, describeTimeZone } from "../../util/timeZone.js";
+/**
+ * A time zone chooser that lists zones as "Los Angeles, America (GMT-07:00)", west to east and then by city, and has a search box in the list: typing narrows it to the zones whose
+ * name or offset contains every word typed ("berlin", "gmt+9", "america indiana"). A button showing the chosen zone opens it; the arrow keys move
+ * through the list, Enter chooses, and Escape (or a click elsewhere) closes it without changing anything.
+ */
+export default function TimeZonePicker({ id, "aria-label": label, "aria-describedby": describedBy, value, zones, onChange, at, className }) {
+    const listId = useId();
+    const root = useRef(null);
+    const trigger = useRef(null);
+    const search = useRef(null);
+    const selected = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    const [active, setActive] = useState(-1);
+    // Listed by the offsets shown (which move with daylight saving): west to east, then by city.
+    const entries = useMemo(() => [...zones]
+        .sort((a, b) => compareTimeZones(a, b, at))
+        .map((zone) => ({ zone, text: describeTimeZone(zone, at), haystack: `${describeTimeZone(zone, at)} ${zone.replace(/_/g, " ")}`.toLowerCase() })), [zones, at]);
+    const shown = useMemo(() => {
+        const words = query.toLowerCase().replace(/_/g, " ").split(/\s+/).filter(Boolean);
+        return words.length === 0 ? entries : entries.filter((entry) => words.every((word) => entry.haystack.includes(word)));
+    }, [entries, query]);
+    useEffect(() => {
+        if (!open) {
+            return undefined;
+        }
+        search.current?.focus();
+        selected.current?.scrollIntoView?.({ block: "center" });
+        const outside = (event) => {
+            if (!root.current?.contains(event.target)) {
+                close(false);
+            }
+        };
+        document.addEventListener("pointerdown", outside);
+        return () => document.removeEventListener("pointerdown", outside);
+    }, [open]);
+    function close(refocus) {
+        setOpen(false);
+        setQuery("");
+        setActive(-1);
+        if (refocus) {
+            trigger.current?.focus();
+        }
+    }
+    function choose(zone) {
+        if (zone !== value) {
+            onChange(zone);
+        }
+        close(true);
+    }
+    function move(step) {
+        setActive((index) => {
+            const from = index < 0 ? shown.findIndex((entry) => entry.zone === value) : index;
+            return Math.min(Math.max(from + step, 0), shown.length - 1);
+        });
+    }
+    function handleSearchKeyDown(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            move(event.key === "ArrowDown" ? 1 : -1);
+        }
+        else if (event.key === "Enter") {
+            // Never the form's own submit.
+            event.preventDefault();
+            const entry = shown[active >= 0 ? active : 0];
+            if (entry && (active >= 0 || shown.length === 1)) {
+                choose(entry.zone);
+            }
+        }
+        else if (event.key === "Escape") {
+            event.stopPropagation();
+            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) => {
+                    if (event.key === "ArrowDown" && !open) {
+                        event.preventDefault();
+                        setOpen(true);
+                    }
+                }, children: [_jsx("span", { className: "truncate", children: describeTimeZone(value, at) }), _jsx("span", { "aria-hidden": "true", className: "shrink-0 text-text-muted", children: "\u25BE" })] }), open && (_jsxs("div", { className: "absolute left-0 top-full z-30 mt-1 w-80 max-w-[90vw] rounded-md border border-border bg-surface shadow-lg", children: [_jsx("div", { className: "p-2", children: _jsx("input", { ref: search, type: "text", role: "searchbox", "aria-label": "Search time zones", "aria-controls": listId, "aria-activedescendant": active >= 0 ? `${listId}-${active}` : undefined, autoComplete: "off", placeholder: "Search", className: "w-full rounded-md border border-border bg-surface-alt px-3 py-1.5 text-sm text-text focus:border-primary focus:outline-none", value: query, onChange: (event) => {
+                                setQuery(event.target.value);
+                                setActive(-1);
+                            }, onKeyDown: handleSearchKeyDown }) }), _jsxs("ul", { id: listId, role: "listbox", "aria-label": "Time zones", className: "max-h-60 overflow-y-auto pb-1", children: [shown.map((entry, index) => (_jsx("li", { id: `${listId}-${index}`, ref: entry.zone === value ? selected : undefined, role: "option", "aria-selected": entry.zone === value, 
+                                // Before the search box's blur or the outside-click check, which would otherwise close the list first.
+                                onMouseDown: (event) => {
+                                    event.preventDefault();
+                                    choose(entry.zone);
+                                }, className: [
+                                    "cursor-pointer px-3 py-1.5 text-sm hover:bg-surface-alt",
+                                    entry.zone === value ? "font-semibold text-primary-dark" : "",
+                                    index === active ? "bg-surface-alt" : "",
+                                ].join(" "), children: entry.text }, entry.zone))), shown.length === 0 && _jsx("li", { className: "px-3 py-1.5 text-sm text-text-muted", children: "No time zones match." })] })] }))] }));
+}

package/dist/lib/util/api.d.ts

@@ -68,6 +68,12 @@ export declare function withCsrfHeader(headers: Record<string, string>, method?:
  * in one place, rather than repeated at every call site.
  */
 export declare function apiFetch<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+/**
+ * Registers what `apiFetch()` does when the server answers `401`: try to renew the signed-in session and, when that worked, send the request once
+ * more. `recovery` resolves whether the session was renewed. The app frame registers it while a session is open (`useSessionRefresh()`); pass
+ * `undefined` to remove it. A rejection counts as "not renewed".
+ */
+export declare function setApiSessionRecovery(recovery: (() => Promise<boolean>) | undefined): void;
 /**
  * `fetch()` against auth-server's API — a *different* origin than this app, unlike `apiFetch()` above. Used
  * only for the handful of actions that must be issued by auth-server itself (e.g. admin impersonation, which

package/dist/lib/util/api.js

@@ -137,9 +137,30 @@ export async function apiFetch(path, init = {}) {
     headers.set("Content-Type", "application/json");
     applyCsrfHeader(headers, init.method);
     const credentials = apiBaseUrl ? "include" : init.credentials;
-    const res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    let res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    // The access token has run out (a sleeping tab or laptop stops the timer that renews it in time): renew the session, and ask again once.
+    if (res.status === 401 && sessionRecovery && (await recoverSession())) {
+        res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    }
     return decodeApiResponse(res, (error) => unauthorizedObserver?.(error));
 }
+let sessionRecovery;
+/**
+ * Registers what `apiFetch()` does when the server answers `401`: try to renew the signed-in session and, when that worked, send the request once
+ * more. `recovery` resolves whether the session was renewed. The app frame registers it while a session is open (`useSessionRefresh()`); pass
+ * `undefined` to remove it. A rejection counts as "not renewed".
+ */
+export function setApiSessionRecovery(recovery) {
+    sessionRecovery = recovery;
+}
+async function recoverSession() {
+    try {
+        return await sessionRecovery();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * `fetch()` against auth-server's API — a *different* origin than this app, unlike `apiFetch()` above. Used
  * only for the handful of actions that must be issued by auth-server itself (e.g. admin impersonation, which

package/dist/lib/util/timeZone.d.ts

@@ -6,7 +6,25 @@ export declare const DEFAULT_TIME_ZONE = "UTC";
  */
 export declare function deviceTimeZone(): string;
 /**
- * Every time zone the browser can name, for a picker: `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
+ * What `zone`'s clock is called and how far it is from UTC at `at`: `{ abbreviation: "PDT", offset: "-07:00" }`. `null` for a zone the runtime doesn't
+ * know. The abbreviation is the runtime's own (`GMT+1` where it has no name for a zone), the offset counts daylight saving on that date.
+ */
+export declare function zoneClock(zone: string, at?: Date): {
+    abbreviation: string;
+    offset: string;
+} | null;
+/**
+ * A zone as a list or a line of text names it, city first, with how far its clock is from UTC: "Los Angeles, America (GMT-07:00)". Daylight saving
+ * is read at `at` (now, unless a date matters). A zone the runtime doesn't know is just its name.
+ */
+export declare function describeTimeZone(zone: string, at?: Date): string;
+/**
+ * Orders zones for a list: by how far their clocks are from UTC at `at` (the westernmost first), then by city, then by id. A zone the runtime
+ * doesn't know comes last.
+ */
+export declare function compareTimeZones(a: string, b: string, at?: Date): number;
+/**
+ * Every time zone the browser can name, for a picker (sorted by offset from UTC as it is now, then by city): `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
  * which is added), else just `extra` - the zones the caller already holds, such as a mailbox's current one.
  */
 export declare function timeZoneOptions(...extra: string[]): string[];

package/dist/lib/util/timeZone.js

@@ -17,7 +17,50 @@ export function deviceTimeZone() {
     }
 }
 /**
- * Every time zone the browser can name, for a picker: `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
+ * What `zone`'s clock is called and how far it is from UTC at `at`: `{ abbreviation: "PDT", offset: "-07:00" }`. `null` for a zone the runtime doesn't
+ * know. The abbreviation is the runtime's own (`GMT+1` where it has no name for a zone), the offset counts daylight saving on that date.
+ */
+export function zoneClock(zone, at = new Date()) {
+    try {
+        const part = (style) => new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: style }).formatToParts(at).find((p) => p.type === "timeZoneName").value;
+        return { abbreviation: part("short"), offset: part("longOffset").replace("GMT", "") || "+00:00" };
+    }
+    catch {
+        return null;
+    }
+}
+/** A zone id split into its city and the region it is in: "America/Argentina/Buenos_Aires" is "Buenos Aires" in "America/Argentina"; "UTC" is in none. */
+function zoneNames(zone) {
+    const parts = zone.split("/");
+    const city = parts.pop().replace(/_/g, " ");
+    return { city, region: parts.join("/").replace(/_/g, " ") };
+}
+/**
+ * A zone as a list or a line of text names it, city first, with how far its clock is from UTC: "Los Angeles, America (GMT-07:00)". Daylight saving
+ * is read at `at` (now, unless a date matters). A zone the runtime doesn't know is just its name.
+ */
+export function describeTimeZone(zone, at = new Date()) {
+    const clock = zoneClock(zone, at);
+    if (!clock) {
+        return zone.replace(/_/g, " ");
+    }
+    const { city, region } = zoneNames(zone);
+    return `${city}${region ? `, ${region}` : ""} (GMT${clock.offset})`;
+}
+/**
+ * Orders zones for a list: by how far their clocks are from UTC at `at` (the westernmost first), then by city, then by id. A zone the runtime
+ * doesn't know comes last.
+ */
+export function compareTimeZones(a, b, at = new Date()) {
+    const minutes = (zone) => {
+        const offset = zoneClock(zone, at)?.offset;
+        return offset ? (offset.startsWith("-") ? -1 : 1) * (Number(offset.slice(1, 3)) * 60 + Number(offset.slice(4, 6))) : Number.POSITIVE_INFINITY;
+    };
+    const byOffset = minutes(a) - minutes(b);
+    return (Number.isNaN(byOffset) ? 0 : byOffset) || zoneNames(a).city.localeCompare(zoneNames(b).city) || a.localeCompare(b);
+}
+/**
+ * Every time zone the browser can name, for a picker (sorted by offset from UTC as it is now, then by city): `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
  * which is added), else just `extra` - the zones the caller already holds, such as a mailbox's current one.
  */
 export function timeZoneOptions(...extra) {
@@ -28,5 +71,6 @@ export function timeZoneOptions(...extra) {
     catch {
         zones = [];
     }
-    return [...new Set([DEFAULT_TIME_ZONE, ...zones, ...extra.filter(Boolean)])].sort((a, b) => a.localeCompare(b));
+    const now = new Date();
+    return [...new Set([DEFAULT_TIME_ZONE, ...zones, ...extra.filter(Boolean)])].sort((a, b) => compareTimeZones(a, b, now));
 }

package/lib/auth/session.ts

@@ -15,7 +15,7 @@
  * sign-out already has.
  */
 import { useEffect, useRef } from "react";
-import { ApiRequestError, authApiFetch } from "../util/api.js";
+import { ApiRequestError, authApiFetch, setApiSessionRecovery } from "../util/api.js";
 import { useApiClient } from "../util/apiClientContext.js";
 
 /** An access token's age at which it is refreshed. The token lives an hour; the margin leaves time to retry a failed refresh. */
@@ -76,6 +76,45 @@ export async function refreshSession(authServerUrl: string, force = false): Prom
     return locks ? locks.request(LOCK_NAME, run) : run();
 }
 
+/** How long the outcome of a recovery is reused for: requests that fail together share one refresh, and a session that will not come back is not asked again at once. */
+export const SESSION_RECOVERY_COOLDOWN_MS = 10 * 1000;
+
+let recovery: Promise<boolean> | undefined;
+let lastRecovery: { at: number; renewed: boolean } | undefined;
+
+/**
+ * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says. Every request
+ * refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`. A refusal also clears the record of
+ * the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
+ *
+ * @returns Whether the session was renewed.
+ */
+export function recoverSession(authServerUrl: string): Promise<boolean> {
+    if (lastRecovery && Date.now() - lastRecovery.at < SESSION_RECOVERY_COOLDOWN_MS) {
+        return Promise.resolve(lastRecovery.renewed);
+    }
+    recovery ??= refreshSession(authServerUrl, true)
+        .then(
+            () => true,
+            () => {
+                writeTimestamp(() => localStorage, REFRESHED_AT_KEY, 0);
+                return false;
+            },
+        )
+        .then((renewed) => {
+            lastRecovery = { at: Date.now(), renewed };
+            recovery = undefined;
+            return renewed;
+        });
+    return recovery;
+}
+
+/** Forgets what recoveries have done (for tests). */
+export function resetSessionRecovery(): void {
+    recovery = undefined;
+    lastRecovery = undefined;
+}
+
 /** Whether `err` says auth-server rejected the refresh token itself, as opposed to a failure worth retrying. */
 function isAuthRejection(err: unknown): boolean {
     return err instanceof ApiRequestError && (err.status === 401 || err.status === 403);
@@ -129,7 +168,8 @@ export interface SessionRefreshOptions {
  * lifetime, or reopened later): attempts one silent refresh and reloads so the server renders the page with the new
  * cookie. If the refresh is refused (the refresh token expired or was revoked, or there was none), or a reload just
  * made still found no session, redirects to sign-in as `useRedirectIfUnauthenticated()` does.
- * - `userUid` set: refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
+ * - `userUid` set: also renews the session when a request is refused for lack of one (`apiFetch()` asks `recoverSession()` and sends the request
+ * again), so a token that ran out while timers were stopped costs nothing. Refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
  * record of a recent refresh, since the page's token age is unknown), checked every `SESSION_REFRESH_CHECK_MS` and
  * whenever the tab becomes visible or the network returns, because a sleeping laptop stops timers. A failure that is
  * not a rejection is simply retried at the next check. A rejection (`401`/`403`: the refresh token expired or was
@@ -169,7 +209,8 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
                 window.location.href = signInUrl(authServerUrl);
                 return;
             }
-            refreshSession(authServerUrl)
+            // Forced: the page has no session, so what this browser remembers of the last refresh says nothing about whether one is due.
+            refreshSession(authServerUrl, true)
                 .then(() => {
                     if (!cancelled) {
                         writeTimestamp(() => sessionStorage, RELOADED_AT_KEY, Date.now());
@@ -190,6 +231,9 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
             return;
         }
 
+        // A request the server refuses for lack of a session renews it (see `apiFetch()`), instead of waiting for the next check.
+        setApiSessionRecovery(() => recoverSession(authServerUrl));
+
         let leaving = false;
         let inFlight = false;
         const leave = async () => {
@@ -230,6 +274,7 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
         window.addEventListener("online", check);
         return () => {
             cancelled = true;
+            setApiSessionRecovery(undefined);
             window.clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
             window.removeEventListener("online", check);

package/lib/components/pickers/TimeZonePicker.tsx

@@ -0,0 +1,180 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { KeyboardEvent, useEffect, useId, useMemo, useRef, useState } from "react";
+import { compareTimeZones, describeTimeZone } from "../../util/timeZone.js";
+
+export interface TimeZonePickerProps {
+    id?: string;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    /** The chosen zone (an IANA id). */
+    value: string;
+    /** The zones to choose between; the list orders them itself. */
+    zones: string[];
+    onChange: (zone: string) => void;
+    /** The date each zone's offset is read on (daylight saving); now unless a date matters. */
+    at?: Date;
+    className?: string;
+}
+
+/**
+ * A time zone chooser that lists zones as "Los Angeles, America (GMT-07:00)", west to east and then by city, and has a search box in the list: typing narrows it to the zones whose
+ * name or offset contains every word typed ("berlin", "gmt+9", "america indiana"). A button showing the chosen zone opens it; the arrow keys move
+ * through the list, Enter chooses, and Escape (or a click elsewhere) closes it without changing anything.
+ */
+export default function TimeZonePicker({ id, "aria-label": label, "aria-describedby": describedBy, value, zones, onChange, at, className }: TimeZonePickerProps) {
+    const listId = useId();
+    const root = useRef<HTMLDivElement>(null);
+    const trigger = useRef<HTMLButtonElement>(null);
+    const search = useRef<HTMLInputElement>(null);
+    const selected = useRef<HTMLLIElement>(null);
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    const [active, setActive] = useState(-1);
+
+    // Listed by the offsets shown (which move with daylight saving): west to east, then by city.
+    const entries = useMemo(
+        () =>
+            [...zones]
+                .sort((a, b) => compareTimeZones(a, b, at))
+                .map((zone) => ({ zone, text: describeTimeZone(zone, at), haystack: `${describeTimeZone(zone, at)} ${zone.replace(/_/g, " ")}`.toLowerCase() })),
+        [zones, at],
+    );
+    const shown = useMemo(() => {
+        const words = query.toLowerCase().replace(/_/g, " ").split(/\s+/).filter(Boolean);
+        return words.length === 0 ? entries : entries.filter((entry) => words.every((word) => entry.haystack.includes(word)));
+    }, [entries, query]);
+
+    useEffect(() => {
+        if (!open) {
+            return undefined;
+        }
+        search.current?.focus();
+        selected.current?.scrollIntoView?.({ block: "center" });
+        const outside = (event: PointerEvent) => {
+            if (!root.current?.contains(event.target as Node)) {
+                close(false);
+            }
+        };
+        document.addEventListener("pointerdown", outside);
+        return () => document.removeEventListener("pointerdown", outside);
+    }, [open]);
+
+    function close(refocus: boolean) {
+        setOpen(false);
+        setQuery("");
+        setActive(-1);
+        if (refocus) {
+            trigger.current?.focus();
+        }
+    }
+
+    function choose(zone: string) {
+        if (zone !== value) {
+            onChange(zone);
+        }
+        close(true);
+    }
+
+    function move(step: number) {
+        setActive((index) => {
+            const from = index < 0 ? shown.findIndex((entry) => entry.zone === value) : index;
+            return Math.min(Math.max(from + step, 0), shown.length - 1);
+        });
+    }
+
+    function handleSearchKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            move(event.key === "ArrowDown" ? 1 : -1);
+        } else if (event.key === "Enter") {
+            // Never the form's own submit.
+            event.preventDefault();
+            const entry = shown[active >= 0 ? active : 0];
+            if (entry && (active >= 0 || shown.length === 1)) {
+                choose(entry.zone);
+            }
+        } else if (event.key === "Escape") {
+            event.stopPropagation();
+            close(true);
+        }
+    }
+
+    return (
+        <div ref={root} className="relative inline-block max-w-full">
+            <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);
+                    }
+                }}
+            >
+                <span className="truncate">{describeTimeZone(value, at)}</span>
+                <span aria-hidden="true" className="shrink-0 text-text-muted">
+                    &#9662;
+                </span>
+            </button>
+            {open && (
+                <div className="absolute left-0 top-full z-30 mt-1 w-80 max-w-[90vw] rounded-md border border-border bg-surface shadow-lg">
+                    <div className="p-2">
+                        <input
+                            ref={search}
+                            type="text"
+                            role="searchbox"
+                            aria-label="Search time zones"
+                            aria-controls={listId}
+                            aria-activedescendant={active >= 0 ? `${listId}-${active}` : undefined}
+                            autoComplete="off"
+                            placeholder="Search"
+                            className="w-full rounded-md border border-border bg-surface-alt px-3 py-1.5 text-sm text-text focus:border-primary focus:outline-none"
+                            value={query}
+                            onChange={(event) => {
+                                setQuery(event.target.value);
+                                setActive(-1);
+                            }}
+                            onKeyDown={handleSearchKeyDown}
+                        />
+                    </div>
+                    <ul id={listId} role="listbox" aria-label="Time zones" className="max-h-60 overflow-y-auto pb-1">
+                        {shown.map((entry, index) => (
+                            <li
+                                key={entry.zone}
+                                id={`${listId}-${index}`}
+                                ref={entry.zone === value ? selected : undefined}
+                                role="option"
+                                aria-selected={entry.zone === value}
+                                // Before the search box's blur or the outside-click check, which would otherwise close the list first.
+                                onMouseDown={(event) => {
+                                    event.preventDefault();
+                                    choose(entry.zone);
+                                }}
+                                className={[
+                                    "cursor-pointer px-3 py-1.5 text-sm hover:bg-surface-alt",
+                                    entry.zone === value ? "font-semibold text-primary-dark" : "",
+                                    index === active ? "bg-surface-alt" : "",
+                                ].join(" ")}
+                            >
+                                {entry.text}
+                            </li>
+                        ))}
+                        {shown.length === 0 && <li className="px-3 py-1.5 text-sm text-text-muted">No time zones match.</li>}
+                    </ul>
+                </div>
+            )}
+        </div>
+    );
+}

package/lib/util/api.ts

@@ -157,10 +157,33 @@ export async function apiFetch<T = unknown>(path: string, init: RequestInit = {}
     applyCsrfHeader(headers, init.method);
     const credentials = apiBaseUrl ? "include" : init.credentials;
 
-    const res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    let res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    // The access token has run out (a sleeping tab or laptop stops the timer that renews it in time): renew the session, and ask again once.
+    if (res.status === 401 && sessionRecovery && (await recoverSession())) {
+        res = await fetch(apiUrl(path), { ...init, headers, credentials });
+    }
     return decodeApiResponse<T>(res, (error) => unauthorizedObserver?.(error));
 }
 
+let sessionRecovery: (() => Promise<boolean>) | undefined;
+
+/**
+ * Registers what `apiFetch()` does when the server answers `401`: try to renew the signed-in session and, when that worked, send the request once
+ * more. `recovery` resolves whether the session was renewed. The app frame registers it while a session is open (`useSessionRefresh()`); pass
+ * `undefined` to remove it. A rejection counts as "not renewed".
+ */
+export function setApiSessionRecovery(recovery: (() => Promise<boolean>) | undefined): void {
+    sessionRecovery = recovery;
+}
+
+async function recoverSession(): Promise<boolean> {
+    try {
+        return await sessionRecovery!();
+    } catch {
+        return false;
+    }
+}
+
 /**
  * `fetch()` against auth-server's API — a *different* origin than this app, unlike `apiFetch()` above. Used
  * only for the handful of actions that must be issued by auth-server itself (e.g. admin impersonation, which

package/lib/util/timeZone.ts

@@ -19,7 +19,54 @@ export function deviceTimeZone(): string {
 }
 
 /**
- * Every time zone the browser can name, for a picker: `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
+ * What `zone`'s clock is called and how far it is from UTC at `at`: `{ abbreviation: "PDT", offset: "-07:00" }`. `null` for a zone the runtime doesn't
+ * know. The abbreviation is the runtime's own (`GMT+1` where it has no name for a zone), the offset counts daylight saving on that date.
+ */
+export function zoneClock(zone: string, at: Date = new Date()): { abbreviation: string; offset: string } | null {
+    try {
+        const part = (style: "short" | "longOffset") =>
+            new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: style }).formatToParts(at).find((p) => p.type === "timeZoneName")!.value;
+        return { abbreviation: part("short"), offset: part("longOffset").replace("GMT", "") || "+00:00" };
+    } catch {
+        return null;
+    }
+}
+
+/** A zone id split into its city and the region it is in: "America/Argentina/Buenos_Aires" is "Buenos Aires" in "America/Argentina"; "UTC" is in none. */
+function zoneNames(zone: string): { city: string; region: string } {
+    const parts = zone.split("/");
+    const city = parts.pop()!.replace(/_/g, " ");
+    return { city, region: parts.join("/").replace(/_/g, " ") };
+}
+
+/**
+ * A zone as a list or a line of text names it, city first, with how far its clock is from UTC: "Los Angeles, America (GMT-07:00)". Daylight saving
+ * is read at `at` (now, unless a date matters). A zone the runtime doesn't know is just its name.
+ */
+export function describeTimeZone(zone: string, at: Date = new Date()): string {
+    const clock = zoneClock(zone, at);
+    if (!clock) {
+        return zone.replace(/_/g, " ");
+    }
+    const { city, region } = zoneNames(zone);
+    return `${city}${region ? `, ${region}` : ""} (GMT${clock.offset})`;
+}
+
+/**
+ * Orders zones for a list: by how far their clocks are from UTC at `at` (the westernmost first), then by city, then by id. A zone the runtime
+ * doesn't know comes last.
+ */
+export function compareTimeZones(a: string, b: string, at: Date = new Date()): number {
+    const minutes = (zone: string) => {
+        const offset = zoneClock(zone, at)?.offset;
+        return offset ? (offset.startsWith("-") ? -1 : 1) * (Number(offset.slice(1, 3)) * 60 + Number(offset.slice(4, 6))) : Number.POSITIVE_INFINITY;
+    };
+    const byOffset = minutes(a) - minutes(b);
+    return (Number.isNaN(byOffset) ? 0 : byOffset) || zoneNames(a).city.localeCompare(zoneNames(b).city) || a.localeCompare(b);
+}
+
+/**
+ * Every time zone the browser can name, for a picker (sorted by offset from UTC as it is now, then by city): `Intl.supportedValuesOf("timeZone")` where there is one (it leaves out `UTC`,
  * which is added), else just `extra` - the zones the caller already holds, such as a mailbox's current one.
  */
 export function timeZoneOptions(...extra: string[]): string[] {
@@ -29,5 +76,6 @@ export function timeZoneOptions(...extra: string[]): string[] {
     } catch {
         zones = [];
     }
-    return [...new Set([DEFAULT_TIME_ZONE, ...zones, ...extra.filter(Boolean)])].sort((a, b) => a.localeCompare(b));
+    const now = new Date();
+    return [...new Set([DEFAULT_TIME_ZONE, ...zones, ...extra.filter(Boolean)])].sort((a, b) => compareTimeZones(a, b, now));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",