@rapidmx/web-client 0.14.1 → 0.16.0

package/apps/shared/components/tasks/layout/TasksShell.tsx

@@ -1,217 +1,218 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
-import { HiOutlineBars3 } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
-import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
-import AppShell, { AppShellProps } from "../../layout/AppShell.js";
-import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
-import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
-
-export type TasksShellProps = Omit<AppShellProps, "active">;
-
-export interface TasksShellContextValue {
-    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
-    mailboxUid?: string;
-    /** The selected mailbox's single `tasks`-type folder. */
-    folderUid?: string;
-    mailboxes: Mailbox[];
-    /** The caller's own uid — exposed here (rather than only as `AppShell`'s prop) so the page content
-     * can compute "assigned to me" without needing it threaded through separately. */
-    userUid?: string;
-}
-
-const TasksShellContext = createContext<TasksShellContextValue>({ mailboxes: [] });
-
-/** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
-export function useTasksShell(): TasksShellContextValue {
-    return useContext(TasksShellContext);
-}
-
-type Status = "checking" | "error" | "ready";
-
-/**
- * The Tasks app's shell — structurally identical to `ContactsShell` (a mailbox has exactly one
- * well-known `tasks` folder, guaranteed to exist by `BaseMailboxRoute.create()`'s eager provisioning
- * in `@rapidmx/restapi`), just bound to a different folder type. Kept as its own small component
- * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
- * grow its own app-specific controls later without threading extra props through a shared one.
- */
-export default function TasksShell({
-    userUid,
-    authServerUrl,
-    impersonating,
-    impersonationBaseUrl,
-    trusted,
-    trustedRoles,
-    pluginNav,
-    children,
-}: PropsWithChildren<TasksShellProps>) {
-    const [status, setStatus] = useState<Status>("checking");
-    const [error, setError] = useState<string | null>(null);
-    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
-    const [folders, setFolders] = useState<Folder[]>([]);
-    const [folderError, setFolderError] = useState<string | null>(null);
-    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
-    const [drawerOpen, setDrawerOpen] = useState(false);
-
-    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
-    // effect, not during render, so the server render and the hydrating render agree.
-    const search = useLocationSearch();
-    const navigate = useNavigate();
-    useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
-    }, [search]);
-    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
-    // with the page - is closed here.
-    useEffect(() => {
-        setDrawerOpen(false);
-    }, [search]);
-
-    useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        listMailboxes({ limit: 100 })
-            .then((result) => {
-                setMailboxes(result);
-                setStatus("ready");
-            })
-            .catch((err) => {
-                setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
-                setStatus("error");
-            });
-    }, [userUid]);
-
-    const mailboxUid: string | undefined =
-        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
-        mailboxes[0]?.uid;
-
-    useEffect(() => {
-        if (!mailboxUid) {
-            setFolders([]);
-            return;
-        }
-        setFolderError(null);
-        listFolders(mailboxUid)
-            .then(setFolders)
-            .catch((err) => setFolderError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox's tasks folder."));
-    }, [mailboxUid]);
-
-    const folderUid: string | undefined = folders.find((f) => f.type === "tasks")?.uid;
-
-    const contextValue = useMemo<TasksShellContextValue>(
-        () => ({ mailboxUid, folderUid, mailboxes, userUid }),
-        [mailboxUid, folderUid, mailboxes, userUid],
-    );
-
-    // 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 don't render at all.
-    if (userUid && status === "ready" && !mailboxUid) {
-        return <MailboxProvisioning />;
-    }
-
-    let inner: ReactNode = null;
-    if (userUid && status === "checking") {
-        // Renders immediately (no network round trip needed) so switching into Tasks never shows a
-        // blank pane while `listMailboxes()` is in flight — the real sidebar (My Day/Important/Planned/
-        // lists) lives in `apps/www/tasks/index.tsx`'s own content, so this mimics its rough shape rather
-        // than the (minimal, mailbox-switcher-only) shape of this shell's own sidebar.
-        inner = (
-            <aside className="w-56 shrink-0 bg-surface border-r border-border flex flex-col p-3 gap-4">
-                <Skeleton height="h-9" />
-                <SkeletonList count={5} />
-            </aside>
-        );
-    } else if (userUid && status === "error") {
-        inner = (
-            <div className="flex-1 flex items-center justify-center p-8">
-                <div className="w-full max-w-md">
-                    <Alert>{error}</Alert>
-                </div>
-            </div>
-        );
-    } else if (userUid && status === "ready") {
-        // A function, not a plain JSX constant — see MailShell/ContactsShell/CalendarShell's identical
-        // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
-        // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
-        const sidebarContent = (idPrefix: string) => (
-            <>
-                {mailboxes.length > 1 && (
-                    <div>
-                        <label
-                            className="block text-xs font-bold uppercase tracking-wide text-text-muted mb-1"
-                            htmlFor={`${idPrefix}-tasks-mailbox-switcher`}
-                        >
-                            Mailbox
-                        </label>
-                        <select
-                            id={`${idPrefix}-tasks-mailbox-switcher`}
-                            className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
-                            value={mailboxUid}
-                            onChange={(e) => {
-                                navigate(`/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`);
-                            }}
-                        >
-                            {mailboxes.map((mb) => (
-                                <option key={mb.uid} value={mb.uid}>
-                                    {mb.displayName}
-                                    {mb.ownerUserUid ? "" : " (shared)"}
-                                </option>
-                            ))}
-                        </select>
-                    </div>
-                )}
-                {folderError && <Alert>{folderError}</Alert>}
-            </>
-        );
-
-        // With a single mailbox and no error this column would be empty: no 224 px of nothing beside the tasks' own menu.
-        const hasSidebar = mailboxes.length > 1 || !!folderError;
-        inner = (
-            <>
-                {hasSidebar && (
-                    <aside className="hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
-                        {sidebarContent("desktop")}
-                    </aside>
-                )}
-                <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Mailbox">
-                    <div className="flex flex-col gap-3">{sidebarContent("mobile")}</div>
-                </Drawer>
-                <main className="flex-1 min-w-0 flex flex-col">
-                    {hasSidebar && (
-                        <button
-                            type="button"
-                            className="lg: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 mailbox switcher"
-                            onClick={() => setDrawerOpen(true)}
-                        >
-                            <HiOutlineBars3 size={20} aria-hidden="true" />
-                        </button>
-                    )}
-                    <TasksShellContext.Provider value={contextValue}>{children}</TasksShellContext.Provider>
-                </main>
-            </>
-        );
-    }
-
-    return (
-        <AppShell
-            active="tasks"
-            userUid={userUid}
-            authServerUrl={authServerUrl}
-            impersonating={impersonating}
-            impersonationBaseUrl={impersonationBaseUrl}
-            trusted={trusted}
-            trustedRoles={trustedRoles}
-            pluginNav={pluginNav}
-        >
-            {inner}
-        </AppShell>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { createContext, PropsWithChildren, ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import { HiOutlineBars3 } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import AppShell, { AppShellProps } from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
+import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
+import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
+
+export type TasksShellProps = Omit<AppShellProps, "active">;
+
+export interface TasksShellContextValue {
+    /** The mailbox currently selected (`?mailboxUid=`, or the caller's first accessible mailbox). */
+    mailboxUid?: string;
+    /** The selected mailbox's single `tasks`-type folder. */
+    folderUid?: string;
+    mailboxes: Mailbox[];
+    /** The caller's own uid — exposed here (rather than only as `AppShell`'s prop) so the page content
+     * can compute "assigned to me" without needing it threaded through separately. */
+    userUid?: string;
+}
+
+const TasksShellContext = createContext<TasksShellContextValue>({ mailboxes: [] });
+
+/** Reads the mailbox/folder Tasks is currently showing, as resolved by the enclosing `TasksShell`. */
+export function useTasksShell(): TasksShellContextValue {
+    return useContext(TasksShellContext);
+}
+
+type Status = "checking" | "error" | "ready";
+
+/**
+ * The Tasks app's shell — structurally identical to `ContactsShell` (a mailbox has exactly one
+ * well-known `tasks` folder, guaranteed to exist by `BaseMailboxRoute.create()`'s eager provisioning
+ * in `@rapidmx/restapi`), just bound to a different folder type. Kept as its own small component
+ * (rather than a single generic "SingleFolderShell" parameterized by type) so each app's sidebar can
+ * grow its own app-specific controls later without threading extra props through a shared one.
+ */
+export default function TasksShell({
+    userUid,
+    authServerUrl,
+    impersonating,
+    impersonationBaseUrl,
+    trusted,
+    trustedRoles,
+    pluginNav,
+    children,
+}: PropsWithChildren<TasksShellProps>) {
+    const [status, setStatus] = useState<Status>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
+    const [folders, setFolders] = useState<Folder[]>([]);
+    const [folderError, setFolderError] = useState<string | null>(null);
+    const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
+    const [drawerOpen, setDrawerOpen] = useState(false);
+
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
+    useEffect(() => {
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        listMailboxes({ limit: 100 })
+            .then((result) => {
+                setMailboxes(orderMailboxes(result, userUid));
+                setStatus("ready");
+            })
+            .catch((err) => {
+                setError(err instanceof ApiRequestError ? err.message : "Could not load your mailboxes.");
+                setStatus("error");
+            });
+    }, [userUid]);
+
+    const mailboxUid: string | undefined =
+        (requestedMailboxUid && mailboxes.some((mb) => mb.uid === requestedMailboxUid) ? requestedMailboxUid : undefined) ??
+        primaryMailboxUid(mailboxes, userUid);
+
+    useEffect(() => {
+        if (!mailboxUid) {
+            setFolders([]);
+            return;
+        }
+        setFolderError(null);
+        listFolders(mailboxUid)
+            .then(setFolders)
+            .catch((err) => setFolderError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox's tasks folder."));
+    }, [mailboxUid]);
+
+    const folderUid: string | undefined = folders.find((f) => f.type === "tasks")?.uid;
+
+    const contextValue = useMemo<TasksShellContextValue>(
+        () => ({ mailboxUid, folderUid, mailboxes, userUid }),
+        [mailboxUid, folderUid, mailboxes, userUid],
+    );
+
+    // 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 don't render at all.
+    if (userUid && status === "ready" && !mailboxUid) {
+        return <MailboxProvisioning />;
+    }
+
+    let inner: ReactNode = null;
+    if (userUid && status === "checking") {
+        // Renders immediately (no network round trip needed) so switching into Tasks never shows a
+        // blank pane while `listMailboxes()` is in flight — the real sidebar (My Day/Important/Planned/
+        // lists) lives in `apps/www/tasks/index.tsx`'s own content, so this mimics its rough shape rather
+        // than the (minimal, mailbox-switcher-only) shape of this shell's own sidebar.
+        inner = (
+            <aside className="w-56 shrink-0 bg-surface border-r border-border flex flex-col p-3 gap-4">
+                <Skeleton height="h-9" />
+                <SkeletonList count={5} />
+            </aside>
+        );
+    } else if (userUid && status === "error") {
+        inner = (
+            <div className="flex-1 flex items-center justify-center p-8">
+                <div className="w-full max-w-md">
+                    <Alert>{error}</Alert>
+                </div>
+            </div>
+        );
+    } else if (userUid && status === "ready") {
+        // A function, not a plain JSX constant — see MailShell/ContactsShell/CalendarShell's identical
+        // comment: it's rendered twice (desktop `<aside>` + mobile `Drawer`), possibly simultaneously
+        // mounted, so the `<select>`'s `id`/its `<label>`'s `htmlFor` need a distinct value per instance.
+        const sidebarContent = (idPrefix: string) => (
+            <>
+                {mailboxes.length > 1 && (
+                    <div>
+                        <label
+                            className="block text-xs font-bold uppercase tracking-wide text-text-muted mb-1"
+                            htmlFor={`${idPrefix}-tasks-mailbox-switcher`}
+                        >
+                            Mailbox
+                        </label>
+                        <select
+                            id={`${idPrefix}-tasks-mailbox-switcher`}
+                            className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
+                            value={mailboxUid}
+                            onChange={(e) => {
+                                navigate(`/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`);
+                            }}
+                        >
+                            {mailboxes.map((mb) => (
+                                <option key={mb.uid} value={mb.uid}>
+                                    {mb.displayName}
+                                    {mb.ownerUserUid ? "" : " (shared)"}
+                                </option>
+                            ))}
+                        </select>
+                    </div>
+                )}
+                {folderError && <Alert>{folderError}</Alert>}
+            </>
+        );
+
+        // With a single mailbox and no error this column would be empty: no 224 px of nothing beside the tasks' own menu.
+        const hasSidebar = mailboxes.length > 1 || !!folderError;
+        inner = (
+            <>
+                {hasSidebar && (
+                    <aside className="hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
+                        {sidebarContent("desktop")}
+                    </aside>
+                )}
+                <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Mailbox" fullScreen>
+                    <div className="flex flex-col gap-3">{sidebarContent("mobile")}</div>
+                </Drawer>
+                <main className="flex-1 min-w-0 flex flex-col">
+                    {hasSidebar && (
+                        <button
+                            type="button"
+                            className="lg: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 mailbox switcher"
+                            onClick={() => setDrawerOpen(true)}
+                        >
+                            <HiOutlineBars3 size={20} aria-hidden="true" />
+                        </button>
+                    )}
+                    <TasksShellContext.Provider value={contextValue}>{children}</TasksShellContext.Provider>
+                </main>
+            </>
+        );
+    }
+
+    return (
+        <AppShell
+            active="tasks"
+            userUid={userUid}
+            authServerUrl={authServerUrl}
+            impersonating={impersonating}
+            impersonationBaseUrl={impersonationBaseUrl}
+            trusted={trusted}
+            trustedRoles={trustedRoles}
+            pluginNav={pluginNav}
+        >
+            {inner}
+        </AppShell>
+    );
+}

package/apps/shared/gestures/useEnterSlide.ts

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState, 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 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(): boolean {
+    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<number | undefined>(undefined);
+
+    useEffect(() => () => window.clearTimeout(timer.current), []);
+
+    function enter(direction: 1 | -1) {
+        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: CSSProperties = {
+        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/apps/shared/gestures/useSwipe.ts

@@ -0,0 +1,114 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef, 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 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 }: UseSwipeOptions) {
+    const start = useRef<{ x: number; y: number; time: number; width: number; mode?: "swipe" | "scroll" } | null>(null);
+    const offset = useRef(0);
+    const latest = useRef({ directions, distance, onDrag, onSwipe });
+    latest.current = { directions, distance, onDrag, onSwipe };
+
+    function clamp(dx: number): number {
+        const allowed = latest.current.directions;
+        return (dx < 0 && !allowed.includes("left")) || (dx > 0 && !allowed.includes("right")) ? 0 : dx;
+    }
+
+    function onTouchStart(event: TouchEvent<HTMLElement>) {
+        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: TouchEvent<HTMLElement>) {
+        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" } as const) : undefined,
+    };
+}