@rapidmx/web-client 0.14.1 → 0.15.1

package/dist/apps/shared/components/mail/invite/inviteFormat.js

@@ -0,0 +1,94 @@
+import { APP_HREFS } from "../../../navigation/appHrefs.js";
+/** Whether an attachment is a calendar file - what tells the pane a message may carry an invitation worth asking the server about. By type
+ * or by name, since mail clients disagree about which one they set (`text/calendar`, `application/ics`, or a bare `.ics` as octet-stream). */
+export function isCalendarAttachment(attachment) {
+    const type = (attachment.mimeType ?? "").split(";")[0].trim().toLowerCase();
+    return type === "text/calendar" || type === "application/ics" || (attachment.filename ?? "").trim().toLowerCase().endsWith(".ics");
+}
+const DAY_FORMAT = { weekday: "short", year: "numeric", month: "short", day: "numeric" };
+const CLOCK_FORMAT = { hour: "numeric", minute: "2-digit" };
+/** `zone` if the browser knows it, else UTC - an all-day date is a calendar day, and needs a fixed zone to stay the same day for every reader. */
+export function allDayZone(zone) {
+    try {
+        new Intl.DateTimeFormat(undefined, { timeZone: zone });
+        return zone ?? "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+/** The instant an ISO string names, or `undefined` when it is missing or unparseable. */
+export function validDate(iso) {
+    const date = iso ? new Date(iso) : undefined;
+    return date && !isNaN(date.getTime()) ? date : undefined;
+}
+/**
+ * When the meeting is, in the reader's own locale and time zone: one date and a time range for a same-day event, both ends in full for
+ * one that spans days, and dates only for an all-day event (drawn in the organizer's zone, since a calendar day is not an instant). `undefined`
+ * when the invitation names no usable start. A missing or unusable end shows the start alone.
+ */
+export function formatInviteWhen(invite) {
+    const start = validDate(invite.startDate);
+    if (!start) {
+        return undefined;
+    }
+    const parsedEnd = validDate(invite.endDate);
+    const end = parsedEnd && parsedEnd > start ? parsedEnd : undefined;
+    if (invite.allDay) {
+        const day = new Intl.DateTimeFormat(undefined, { ...DAY_FORMAT, timeZone: allDayZone(invite.timezone) });
+        const first = day.format(start);
+        // An all-day event's end is the midnight after its last day (iCalendar's DTEND is exclusive), so the last day is a moment before it.
+        const last = end ? day.format(new Date(end.getTime() - 1)) : first;
+        return last === first ? first : `${first} - ${last}`;
+    }
+    const date = new Intl.DateTimeFormat(undefined, DAY_FORMAT);
+    const time = new Intl.DateTimeFormat(undefined, CLOCK_FORMAT);
+    // The zone is named once, after the last time shown: the times are the reader's own, not the organizer's.
+    const timeAndZone = new Intl.DateTimeFormat(undefined, { ...CLOCK_FORMAT, timeZoneName: "short" });
+    const startDay = date.format(start);
+    if (!end) {
+        return `${startDay}, ${timeAndZone.format(start)}`;
+    }
+    return startDay === date.format(end)
+        ? `${startDay}, ${time.format(start)} - ${timeAndZone.format(end)}`
+        : `${startDay}, ${time.format(start)} - ${date.format(end)}, ${timeAndZone.format(end)}`;
+}
+/** The meeting's start the way a list row writes it - `Thu 9/24/2026 1:00 PM` (dates only for an all-day event), in the reader's zone. */
+export function formatRowStart(invite) {
+    const start = validDate(invite.startDate);
+    if (!start) {
+        return undefined;
+    }
+    const zone = invite.allDay ? allDayZone(invite.timezone) : undefined;
+    const weekday = new Intl.DateTimeFormat(undefined, { weekday: "short", timeZone: zone }).format(start);
+    const date = new Intl.DateTimeFormat(undefined, { year: "numeric", month: "numeric", day: "numeric", timeZone: zone }).format(start);
+    return invite.allDay ? `${weekday} ${date}` : `${weekday} ${date} ${new Intl.DateTimeFormat(undefined, CLOCK_FORMAT).format(start)}`;
+}
+/** `YYYY-MM-DD` of an instant in the reader's zone, or in `timeZone` when given (`en-CA` writes a date that way). */
+export function isoDay(date, timeZone) {
+    return new Intl.DateTimeFormat("en-CA", { year: "numeric", month: "2-digit", day: "2-digit", timeZone }).format(date);
+}
+/** Where "Open in Calendar" goes: the day view of the day the meeting starts (the `date`/`view` the calendar page reads), or the calendar itself
+ * when the invitation names no usable start. An all-day event's day is the organizer's; any other is the reader's. */
+export function calendarHref(invite) {
+    const start = validDate(invite.startDate);
+    if (!start) {
+        return APP_HREFS.calendar;
+    }
+    return `${APP_HREFS.calendar}?date=${isoDay(start, invite.allDay ? allDayZone(invite.timezone) : undefined)}&view=day`;
+}
+/** The reader's answer as a list row says it. */
+export const ANSWER_LABEL = {
+    accepted: "Accepted",
+    tentative: "Tentative",
+    declined: "Declined",
+};
+/** The most conflicting events that are named; more are counted. */
+const MAX_NAMED_CONFLICTS = 3;
+/** The titles of the events an invitation conflicts with, as "A, B and 2 more". */
+export function conflictSummary(conflicts) {
+    const titles = conflicts.map((c) => c.title.trim() || "(no title)");
+    return titles.length <= MAX_NAMED_CONFLICTS
+        ? titles.join(", ")
+        : `${titles.slice(0, MAX_NAMED_CONFLICTS).join(", ")} and ${titles.length - MAX_NAMED_CONFLICTS} more`;
+}

package/dist/apps/shared/components/mail/invite/inviteStore.d.ts

@@ -0,0 +1,28 @@
+import { MessageInvite } from "@rapidmx/react-shared/calendar/inviteApi.js";
+/**
+ * A per-message cache of the calendar invitation the server reads out of a message, shared by everything that draws one: the reading pane's
+ * card, the list row's RSVP chip and its popover. They ask for the same message a moment apart (the row's chip, then the pane once it is
+ * opened), and an answer given in one has to show in the others, so a lookup is made once and every answer goes through `storeInvite()`.
+ *
+ * A message with no invitation (`null`, the server's 404) is remembered too. A lookup that fails is not - nothing is cached and the next
+ * thing to ask (a remount, another row) tries again - but nothing retries on its own. An entry goes stale after `INVITE_TTL_MS`, because the
+ * calendar it describes can change elsewhere (the meeting deleted, another device answering); it is refetched when next asked for.
+ */
+/** How long a looked-up invitation is trusted before the next ask reads it again. */
+export declare const INVITE_TTL_MS = 30000;
+/** Reads a message's invitation, from the cache when it is fresh. Rejects when the lookup fails. */
+export declare function loadInvite(uid: string): Promise<MessageInvite | null>;
+/** Records the invitation as it now stands after an answer, so the pane, the chip and the popover all show it. */
+export declare function storeInvite(uid: string, invite: MessageInvite): void;
+/** Forgets everything - for tests, and for a sign-out. */
+export declare function clearInviteCache(): void;
+/**
+ * A message's invitation, looked up once (shared with every other user of the same message) when `enabled`. `invite` is `null` until it is
+ * known, and stays `null` for a message with none or a lookup that failed - nothing to draw either way. `settled` says the lookup is over.
+ * Nothing is asked while disabled, and a failure is never retried from here.
+ */
+export declare function useMessageInvite(uid: string, enabled?: boolean): {
+    invite: MessageInvite | null;
+    settled: boolean;
+    setInvite: (invite: MessageInvite) => void;
+};

package/dist/apps/shared/components/mail/invite/inviteStore.js

@@ -0,0 +1,95 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useReducer } from "react";
+import { getMessageInvite } from "@rapidmx/react-shared/calendar/inviteApi.js";
+/**
+ * A per-message cache of the calendar invitation the server reads out of a message, shared by everything that draws one: the reading pane's
+ * card, the list row's RSVP chip and its popover. They ask for the same message a moment apart (the row's chip, then the pane once it is
+ * opened), and an answer given in one has to show in the others, so a lookup is made once and every answer goes through `storeInvite()`.
+ *
+ * A message with no invitation (`null`, the server's 404) is remembered too. A lookup that fails is not - nothing is cached and the next
+ * thing to ask (a remount, another row) tries again - but nothing retries on its own. An entry goes stale after `INVITE_TTL_MS`, because the
+ * calendar it describes can change elsewhere (the meeting deleted, another device answering); it is refetched when next asked for.
+ */
+/** How long a looked-up invitation is trusted before the next ask reads it again. */
+export const INVITE_TTL_MS = 30000;
+const entries = new Map();
+const listeners = new Map();
+function notify(uid) {
+    listeners.get(uid)?.forEach((listener) => listener());
+}
+/** Older servers, or a partial answer, may leave a list out: a card must never fail to draw over one. */
+function normalize(invite) {
+    if (!invite) {
+        return null;
+    }
+    const partial = invite;
+    return { ...invite, attendees: partial.attendees ?? [], conflicts: partial.conflicts ?? [], schedule: partial.schedule ?? [] };
+}
+/** Reads a message's invitation, from the cache when it is fresh. Rejects when the lookup fails. */
+export function loadInvite(uid) {
+    const existing = entries.get(uid);
+    if (existing && (existing.value === undefined || Date.now() - existing.at < INVITE_TTL_MS)) {
+        return existing.promise;
+    }
+    const entry = {
+        at: Date.now(),
+        promise: getMessageInvite(uid).then((invite) => {
+            entry.value = normalize(invite);
+            entry.at = Date.now();
+            notify(uid);
+            return entry.value;
+        }, (err) => {
+            if (entries.get(uid) === entry) {
+                entries.delete(uid);
+            }
+            throw err;
+        }),
+    };
+    entries.set(uid, entry);
+    return entry.promise;
+}
+/** Records the invitation as it now stands after an answer, so the pane, the chip and the popover all show it. */
+export function storeInvite(uid, invite) {
+    const value = normalize(invite);
+    entries.set(uid, { promise: Promise.resolve(value), value, at: Date.now() });
+    notify(uid);
+}
+/** Forgets everything - for tests, and for a sign-out. */
+export function clearInviteCache() {
+    entries.clear();
+}
+/**
+ * A message's invitation, looked up once (shared with every other user of the same message) when `enabled`. `invite` is `null` until it is
+ * known, and stays `null` for a message with none or a lookup that failed - nothing to draw either way. `settled` says the lookup is over.
+ * Nothing is asked while disabled, and a failure is never retried from here.
+ */
+export function useMessageInvite(uid, enabled = true) {
+    const [, rerender] = useReducer((n) => n + 1, 0);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        let cancelled = false;
+        const update = () => {
+            if (!cancelled) {
+                rerender();
+            }
+        };
+        const set = listeners.get(uid) ?? new Set();
+        set.add(update);
+        listeners.set(uid, set);
+        loadInvite(uid).then(update, () => {
+            // Nothing to show, and nothing worth interrupting the reader with: the message reads the same without it.
+        });
+        return () => {
+            cancelled = true;
+            set.delete(update);
+        };
+    }, [uid, enabled]);
+    const setInvite = useCallback((invite) => storeInvite(uid, invite), [uid]);
+    const value = enabled ? entries.get(uid)?.value : undefined;
+    return { invite: value ?? null, settled: value !== undefined, setInvite };
+}

package/dist/apps/shared/components/mail/layout/MailShell.d.ts

@@ -59,6 +59,11 @@ export interface MailShellContextValue {
      * context value, which is only ever read outside a real shell.
      */
     trackMessageChange: (previous: Message, next: Message | null) => CountTracker;
+    /**
+     * The phone layout's header row beside the folders button, for the page to put its search box in (`createPortal()`): the shell
+     * owns the row, the page owns the search state. `null` until the row has rendered, and on the default context value.
+     */
+    mobileSearchSlot: HTMLElement | null;
 }
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
 export declare function useMailShell(): MailShellContextValue;

package/dist/apps/shared/components/mail/layout/MailShell.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { createContext, useContext, useEffect, useMemo, useState } from "react";
-import { HiOutlineBars3 } from "react-icons/hi2";
+import { HiOutlineBars3, HiOutlinePencilSquare } from "react-icons/hi2";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
@@ -42,6 +42,7 @@ const MailShellContext = createContext({
     noteFolderUids: () => undefined,
     live: NO_LIVE_UPDATES,
     trackMessageChange: () => NO_TRACKER,
+    mobileSearchSlot: null,
 });
 /** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
 export function useMailShell() {
@@ -91,6 +92,14 @@ function ComposeButton({ mailboxUid }) {
     const env = useKeyEnvironment();
     return (_jsx("button", { type: "button", title: withHint("Compose", SHORTCUTS.mail.create, env), "aria-keyshortcuts": ariaKeyShortcuts(SHORTCUTS.mail.create, env), onClick: () => openCompose({ mailboxUid }), onPointerEnter: prefetchComposeWindow, onFocus: prefetchComposeWindow, className: "block text-center w-full py-2.5 px-4 rounded-sm font-semibold text-sm bg-primary text-white hover:bg-primary-dark", children: "Compose" }));
 }
+/**
+ * A small round Compose button floating at the bottom right on a phone, just above the bottom tab bar (which is `h-14`, fixed), for the
+ * layout where the sidebar's Compose button is behind the folders drawer. Opens the same window, for the same mailbox, as that button.
+ */
+function MobileComposeButton({ mailboxUid }) {
+    const { openCompose } = useCompose();
+    return (_jsx("button", { type: "button", "aria-label": "New message", onClick: () => openCompose({ mailboxUid }), onPointerEnter: prefetchComposeWindow, onFocus: prefetchComposeWindow, className: "md:hidden fixed right-4 bottom-[4.5rem] z-30 w-12 h-12 flex items-center justify-center rounded-full bg-primary text-white shadow-lg hover:bg-primary-dark", children: _jsx(HiOutlinePencilSquare, { size: 22, "aria-hidden": "true" }) }));
+}
 /**
  * Mail's keyboard shortcuts that don't belong to a list or a message: "New message". A component of its own for the reason `ComposeButton`
  * is - `useCompose()` only resolves below `ComposeProvider`, i.e. inside the `AppShell` this shell renders - and mounted once, whatever number
@@ -169,7 +178,9 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
     const trackMessageChange = folderCounts.track;
     // `(3) Acme: Mail` in the tab strip while there is unread mail in an Inbox - kept by the frame when there is one.
     useUnreadTitle(inboxUnreadTotal(mailboxFolders, counts), { enabled: !hosted });
-    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange]);
+    // A state rather than a ref: the page reads it during its render, so it has to re-render once the row it names is in the document.
+    const [mobileSearchSlot, setMobileSearchSlot] = useState(null);
+    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange, mobileSearchSlot }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange, mobileSearchSlot]);
     // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else for a
     // mailbox-less caller to do here yet, so the icon rail/header/folder tree don't render at all. Checks
     // `mailboxes.length` directly (not `!mailboxUid`) since `mailboxUid` is legitimately undefined in
@@ -215,7 +226,7 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
                                             ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[folder.type] ?? folder.name }), badge &&
                                                     (folder.type === "outbox" ? (_jsx(OutboxBadge, { total: badge.value, status: outboxStatuses[folder.uid], pendingHere: pendingCountFor(mailbox.uid, pendingSends) })) : (_jsx(FolderBadgeChip, { badge: badge })))] }, folder.uid));
                                     }) })] }, mailbox.uid)))] }))] }));
-        inner = (_jsxs(_Fragment, { children: [_jsx(MailShortcuts, { mailboxUid: defaultMailboxUid }), _jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] })] }));
+        inner = (_jsxs(_Fragment, { children: [_jsx(MailShortcuts, { mailboxUid: defaultMailboxUid }), _jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsxs("div", { className: "md:hidden flex items-center gap-2 p-3", children: [_jsx("button", { type: "button", className: "shrink-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("div", { ref: setMobileSearchSlot, className: "flex-1 min-w-0" })] }), _jsx(MobileComposeButton, { mailboxUid: defaultMailboxUid }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
     // Wraps AppShell unconditionally, at a stable tree position regardless of whether mailboxUid has
     // resolved yet - KeyEnrollmentGate itself passes `children` through untouched until a real

package/dist/apps/shared/components/settings/layout/SettingsShell.js

@@ -16,6 +16,7 @@ import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { mergePluginNavItems } from "../../../plugins/pluginNav.js";
 /** Every settings section with its own sidebar entry. */
 export const SETTINGS_SECTIONS = [
+    { id: "profile", href: "/settings/profile", label: "Profile" },
     { id: "appearance", href: "/settings/appearance", label: "Appearance" },
     { id: "auto-reply", href: "/settings/auto-reply", label: "Automatic Replies" },
     { id: "filters", href: "/settings/filters", label: "Mail Filters" },

package/dist/apps/shared/gestures/useEnterSlide.d.ts

@@ -0,0 +1,14 @@
+import { type CSSProperties } from "react";
+/** How long the new contents take to settle. Short, so a run of steps (a wheel kept turning) never waits on the last one. */
+export declare const ENTER_SLIDE_MS = 140;
+/**
+ * The look of a page that has just been swapped for the next or previous one by a vertical step (the wheel): the new contents start
+ * a little way off in the direction the step went - below for `1` (the next), above for `-1` - and faded, and settle into place.
+ * The old contents are not animated out: the swap is immediate, so a run of steps never queues, and a step in the middle of a
+ * settle just starts the next one from its start. Put `style` on the element that holds the contents and call `enter()` as the
+ * contents change. Nothing moves for someone who asked for less motion.
+ */
+export declare function useEnterSlide(): {
+    style: CSSProperties;
+    enter: (direction: 1 | -1) => void;
+};

package/dist/apps/shared/gestures/useEnterSlide.js

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState } from "react";
+/** How long the new contents take to settle. Short, so a run of steps (a wheel kept turning) never waits on the last one. */
+export const ENTER_SLIDE_MS = 140;
+/** How far off, in pixels, and how faded the new contents start. */
+const ENTER_OFFSET_PX = 56;
+const ENTER_START_OPACITY = 0.35;
+/** The pause that lets the browser draw the contents at their starting place before they move. */
+const ENTER_SETTLE_MS = 20;
+/** Whether the user asked their device for less motion. */
+function prefersReducedMotion() {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
+ * The look of a page that has just been swapped for the next or previous one by a vertical step (the wheel): the new contents start
+ * a little way off in the direction the step went - below for `1` (the next), above for `-1` - and faded, and settle into place.
+ * The old contents are not animated out: the swap is immediate, so a run of steps never queues, and a step in the middle of a
+ * settle just starts the next one from its start. Put `style` on the element that holds the contents and call `enter()` as the
+ * contents change. Nothing moves for someone who asked for less motion.
+ */
+export function useEnterSlide() {
+    const [offset, setOffset] = useState(0);
+    const [animated, setAnimated] = useState(false);
+    const timer = useRef(undefined);
+    useEffect(() => () => window.clearTimeout(timer.current), []);
+    function enter(direction) {
+        if (prefersReducedMotion()) {
+            return;
+        }
+        window.clearTimeout(timer.current);
+        setAnimated(false);
+        setOffset(direction * ENTER_OFFSET_PX);
+        timer.current = window.setTimeout(() => {
+            setAnimated(true);
+            setOffset(0);
+        }, ENTER_SETTLE_MS);
+    }
+    const style = {
+        transform: offset === 0 ? undefined : `translate3d(0, ${offset}px, 0)`,
+        opacity: offset === 0 ? undefined : ENTER_START_OPACITY,
+        transition: animated ? `transform ${ENTER_SLIDE_MS}ms ease-out, opacity ${ENTER_SLIDE_MS}ms ease-out` : "none",
+    };
+    return { style, enter };
+}

package/dist/apps/shared/gestures/useSwipe.d.ts

@@ -0,0 +1,45 @@
+import { type TouchEvent } from "react";
+/** Which way the finger moved: `"left"` is right to left. */
+export type SwipeDirection = "left" | "right";
+export interface UseSwipeOptions {
+    /** Nothing is tracked while this is `false` (a desktop pointer, select mode). Default `true`. */
+    enabled?: boolean;
+    /** The directions that mean something; a drag the other way doesn't move at all. Default both. */
+    directions?: readonly SwipeDirection[];
+    /** How far the finger has to travel to commit, in px. Default `MIN_SWIPE_DISTANCE`, or a third of the element's width when that is more. */
+    distance?: number;
+    /** Called as the finger moves, with the horizontal offset (the direction filter applied), and with `0` once it lifts. */
+    onDrag?: (offset: number) => void;
+    /** Called once when a swipe commits. `onDrag(0)` follows. */
+    onSwipe: (direction: SwipeDirection) => void;
+}
+/** The least distance that commits a swipe, and how far the finger must move before its direction is decided. */
+export declare const MIN_SWIPE_DISTANCE = 80;
+export declare const SWIPE_SLOP = 10;
+/** A quicker flick than this (px per ms) commits after `FLING_MIN_DISTANCE` alone. */
+export declare const FLING_VELOCITY = 0.5;
+export declare const FLING_MIN_DISTANCE = 40;
+/**
+ * A horizontal swipe by one finger, for the touch screens the app's phone layout is for: mouse and pen are left alone.
+ *
+ * Spread the handlers on the element and give it `touch-action: pan-y` (`style`), so the browser keeps scrolling vertically and leaves
+ * the horizontal movement to this. A gesture that starts out mostly vertical is a scroll and is never a swipe, however far it later
+ * strays sideways; one that starts out horizontal is a swipe, and stays one.
+ */
+export declare function useSwipe({ enabled, directions, distance, onDrag, onSwipe }: UseSwipeOptions): {
+    handlers: {
+        onTouchStart: (event: TouchEvent<HTMLElement>) => void;
+        onTouchMove: (event: TouchEvent<HTMLElement>) => void;
+        onTouchEnd: () => void;
+        onTouchCancel: () => void;
+    } | {
+        onTouchStart?: undefined;
+        onTouchMove?: undefined;
+        onTouchEnd?: undefined;
+        onTouchCancel?: undefined;
+    };
+    /** Leaves vertical panning to the browser. */
+    style: {
+        readonly touchAction: "pan-y";
+    } | undefined;
+};

package/dist/apps/shared/gestures/useSwipe.js

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef } from "react";
+/** The least distance that commits a swipe, and how far the finger must move before its direction is decided. */
+export const MIN_SWIPE_DISTANCE = 80;
+export const SWIPE_SLOP = 10;
+/** A quicker flick than this (px per ms) commits after `FLING_MIN_DISTANCE` alone. */
+export const FLING_VELOCITY = 0.5;
+export const FLING_MIN_DISTANCE = 40;
+/**
+ * A horizontal swipe by one finger, for the touch screens the app's phone layout is for: mouse and pen are left alone.
+ *
+ * Spread the handlers on the element and give it `touch-action: pan-y` (`style`), so the browser keeps scrolling vertically and leaves
+ * the horizontal movement to this. A gesture that starts out mostly vertical is a scroll and is never a swipe, however far it later
+ * strays sideways; one that starts out horizontal is a swipe, and stays one.
+ */
+export function useSwipe({ enabled = true, directions = ["left", "right"], distance, onDrag, onSwipe }) {
+    const start = useRef(null);
+    const offset = useRef(0);
+    const latest = useRef({ directions, distance, onDrag, onSwipe });
+    latest.current = { directions, distance, onDrag, onSwipe };
+    function clamp(dx) {
+        const allowed = latest.current.directions;
+        return (dx < 0 && !allowed.includes("left")) || (dx > 0 && !allowed.includes("right")) ? 0 : dx;
+    }
+    function onTouchStart(event) {
+        if (!enabled || event.touches.length !== 1) {
+            start.current = null;
+            return;
+        }
+        const touch = event.touches[0];
+        start.current = { x: touch.clientX, y: touch.clientY, time: Date.now(), width: event.currentTarget.clientWidth };
+        offset.current = 0;
+    }
+    function onTouchMove(event) {
+        const gesture = start.current;
+        if (!gesture || gesture.mode === "scroll") {
+            return;
+        }
+        if (event.touches.length !== 1) {
+            cancel();
+            return;
+        }
+        const dx = event.touches[0].clientX - gesture.x;
+        const dy = event.touches[0].clientY - gesture.y;
+        if (!gesture.mode) {
+            if (Math.max(Math.abs(dx), Math.abs(dy)) < SWIPE_SLOP) {
+                return;
+            }
+            gesture.mode = Math.abs(dx) > Math.abs(dy) * 1.5 ? "swipe" : "scroll";
+            if (gesture.mode === "scroll") {
+                return;
+            }
+        }
+        offset.current = clamp(dx);
+        latest.current.onDrag?.(offset.current);
+    }
+    function onTouchEnd() {
+        const gesture = start.current;
+        start.current = null;
+        if (!gesture || gesture.mode !== "swipe") {
+            return;
+        }
+        const dx = offset.current;
+        offset.current = 0;
+        const travelled = Math.abs(dx);
+        const velocity = travelled / Math.max(1, Date.now() - gesture.time);
+        const needed = latest.current.distance ?? Math.max(MIN_SWIPE_DISTANCE, gesture.width / 3);
+        const committed = dx !== 0 && (travelled >= needed || (velocity >= FLING_VELOCITY && travelled >= FLING_MIN_DISTANCE));
+        if (committed) {
+            latest.current.onSwipe(dx < 0 ? "left" : "right");
+        }
+        latest.current.onDrag?.(0);
+    }
+    function cancel() {
+        const moved = start.current?.mode === "swipe";
+        start.current = null;
+        offset.current = 0;
+        if (moved) {
+            latest.current.onDrag?.(0);
+        }
+    }
+    return {
+        handlers: enabled ? { onTouchStart, onTouchMove, onTouchEnd, onTouchCancel: cancel } : {},
+        /** Leaves vertical panning to the browser. */
+        style: enabled ? { touchAction: "pan-y" } : undefined,
+    };
+}

package/dist/apps/shared/gestures/useSwipeSlide.d.ts

@@ -0,0 +1,40 @@
+import { type CSSProperties } from "react";
+import { SwipeDirection } from "./useSwipe.js";
+/** How long the current contents take to leave, and the new ones to arrive - or the current ones to snap back. */
+export declare const SLIDE_MS = 200;
+export interface UseSwipeSlideOptions {
+    /** Nothing is tracked while this is `false`. */
+    enabled: boolean;
+    /** Changes what is shown to the period the swipe went to - called once the old contents have left, while the new ones wait off-screen. */
+    onShift: (direction: SwipeDirection) => void;
+}
+/**
+ * A swipe between pages of content that visibly moves them, the way a phone calendar does: the contents follow the finger, and once
+ * the swipe commits they carry on out of view in the direction it went while the next ones - `onShift()` changes what is shown at
+ * that moment - slide in from the other side. A swipe that stops short slides back. The animation is timed here (`SLIDE_MS`) rather than
+ * left to `transitionend`, so it can't stall if the browser skips a transition.
+ *
+ * Put `handlers` and `style` on a clipping element (`overflow-hidden`, so the contents don't widen the page while they are off to
+ * the side), the contents inside it in an element of their own with `contentStyle`, and `ref` on the clipping element.
+ */
+export declare function useSwipeSlide({ enabled, onShift }: UseSwipeSlideOptions): {
+    handlers: {
+        onTouchStart: (event: import("react").TouchEvent<HTMLElement>) => void;
+        onTouchMove: (event: import("react").TouchEvent<HTMLElement>) => void;
+        onTouchEnd: () => void;
+        onTouchCancel: () => void;
+    } | {
+        onTouchStart?: undefined;
+        onTouchMove?: undefined;
+        onTouchEnd?: undefined;
+        onTouchCancel?: undefined;
+    };
+    /** For the clipping element: `touch-action: pan-y`, and no overflow. */
+    style: {
+        readonly touchAction: "pan-y";
+    } | undefined;
+    contentStyle: CSSProperties;
+    ref: import("react").RefObject<HTMLDivElement | null>;
+    /** For a test or a style hook: `"idle"`, `"dragging"` or `"sliding"`. */
+    phase: string;
+};

package/dist/apps/shared/gestures/useSwipeSlide.js

@@ -0,0 +1,95 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState } from "react";
+import { useSwipe } from "./useSwipe.js";
+/** How long the current contents take to leave, and the new ones to arrive - or the current ones to snap back. */
+export const SLIDE_MS = 200;
+/** The pause between the new contents being put off-screen and them starting to slide in, long enough for the browser to draw them there. */
+const SETTLE_MS = 30;
+/** How far a slide goes when the element's width can't be measured. */
+const FALLBACK_WIDTH_PX = 320;
+/** Whether the user asked their device for less motion, in which case the change is made at once instead of slid. */
+function prefersReducedMotion() {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
+ * A swipe between pages of content that visibly moves them, the way a phone calendar does: the contents follow the finger, and once
+ * the swipe commits they carry on out of view in the direction it went while the next ones - `onShift()` changes what is shown at
+ * that moment - slide in from the other side. A swipe that stops short slides back. The animation is timed here (`SLIDE_MS`) rather than
+ * left to `transitionend`, so it can't stall if the browser skips a transition.
+ *
+ * Put `handlers` and `style` on a clipping element (`overflow-hidden`, so the contents don't widen the page while they are off to
+ * the side), the contents inside it in an element of their own with `contentStyle`, and `ref` on the clipping element.
+ */
+export function useSwipeSlide({ enabled, onShift }) {
+    const [offset, setOffset] = useState(0);
+    /** Whether a change of `offset` is animated: not while the finger is moving it, yes for everything else. */
+    const [animated, setAnimated] = useState(false);
+    /** A committed slide is under way: further swipes are ignored until it ends. */
+    const [sliding, setSliding] = useState(false);
+    const slidingRef = useRef(false);
+    const ref = useRef(null);
+    const timers = useRef([]);
+    const latest = useRef({ onShift });
+    latest.current = { onShift };
+    useEffect(() => () => {
+        for (const timer of timers.current) {
+            window.clearTimeout(timer);
+        }
+    }, []);
+    function later(work, ms) {
+        timers.current.push(window.setTimeout(work, ms));
+    }
+    const swipe = useSwipe({
+        enabled: enabled && !sliding,
+        onDrag: (dx) => {
+            // `useSwipe()` reports the finger lifting (0) right after a swipe commits: that must not undo the slide out.
+            if (slidingRef.current) {
+                return;
+            }
+            setAnimated(dx === 0);
+            setOffset(dx);
+        },
+        onSwipe: (direction) => {
+            if (prefersReducedMotion()) {
+                latest.current.onShift(direction);
+                return;
+            }
+            const width = ref.current?.clientWidth || FALLBACK_WIDTH_PX;
+            // The finger moved `direction`, so the contents go that way and the next ones come from the opposite side.
+            const out = direction === "left" ? -width : width;
+            slidingRef.current = true;
+            setSliding(true);
+            setAnimated(true);
+            setOffset(out);
+            later(() => {
+                latest.current.onShift(direction);
+                setAnimated(false);
+                setOffset(-out);
+                later(() => {
+                    setAnimated(true);
+                    setOffset(0);
+                    later(() => {
+                        slidingRef.current = false;
+                        setSliding(false);
+                    }, SLIDE_MS);
+                }, SETTLE_MS);
+            }, SLIDE_MS);
+        },
+    });
+    const contentStyle = {
+        transform: offset === 0 ? undefined : `translate3d(${offset}px, 0, 0)`,
+        transition: animated ? `transform ${SLIDE_MS}ms ease-out` : "none",
+    };
+    return {
+        handlers: swipe.handlers,
+        /** For the clipping element: `touch-action: pan-y`, and no overflow. */
+        style: swipe.style,
+        contentStyle,
+        ref,
+        /** For a test or a style hook: `"idle"`, `"dragging"` or `"sliding"`. */
+        phase: sliding ? "sliding" : offset !== 0 && !animated ? "dragging" : "idle",
+    };
+}