@phis/ui 0.2.1 → 0.4.0

package/components/media/phi-media-upload.js

@@ -1,7 +1,7 @@
 "use client";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { PhiMediaKind, resolvePhiMediaKindFromContentType } from "../../constants/media";
-import { PhiMediaUploadError, runPhiMediaUploadSession, } from "./media-upload-flow";
+import { PhiMediaUploadError, isPhiMediaUploadCancelled, runPhiMediaUploadSession, } from "./media-upload-flow";
 /**
  * Text for a surface that has no label set of its own.
  *
@@ -108,12 +108,30 @@ export function readPhiMediaUploadErrorMessage(error, labels) {
  * What it deliberately does not own is what happens afterwards -- appending a tile, binding an avatar,
  * replacing a preview. That is the only part that differs between the surfaces, so it stays with them
  * and arrives through `onUploaded`.
+ *
+ * An upload belongs to the surface that started it. When that surface goes away -- an Overlay closed, a
+ * form unmounted -- every upload still running is stopped and reported `cancelled`, so no Asset is
+ * finalized that nobody will enter anywhere. `cancel()` does the same while the surface stays. A stopped
+ * upload leaves the list and calls neither `onUploaded` nor `onRejected`: nobody is waiting for it.
+ *
+ * `uploading` is true while any file is still on its way. A surface whose value is only complete once the
+ * upload settled -- a form field that receives the Asset id in `onUploaded` -- reads it to hold back
+ * whatever would act on the incomplete value.
  */
 export function usePhiMediaUpload(input) {
     const { labels, acceptance, initOptions, onUploaded, onRejected } = input;
     const runSession = input.runSession ?? runPhiMediaUploadSession;
     const [items, setItems] = useState([]);
     const sequence = useRef(0);
+    const running = useRef(new Set());
+    useEffect(() => {
+        const controllers = running.current;
+        return () => {
+            for (const controller of controllers)
+                controller.abort();
+            controllers.clear();
+        };
+    }, []);
     const accept = useMemo(() => resolvePhiMediaUploadAccept(acceptance), [acceptance]);
     const patch = useCallback((localId, next) => {
         setItems((current) => current.map((item) => item.localId === localId ? { ...item, ...next } : item));
@@ -130,19 +148,45 @@ export function usePhiMediaUpload(input) {
             { localId, file, progress: 0, status: "uploading", error: null, assetId: null },
             ...current,
         ]);
+        const controller = new AbortController();
+        running.current.add(controller);
+        let asset;
         try {
-            const { asset } = await runSession(file, (progress) => patch(localId, { progress }), initOptions);
-            patch(localId, { progress: 100, status: "done", assetId: asset.id });
-            await onUploaded?.(asset, file);
-            return asset;
+            ({ asset } = await runSession(file, (progress) => patch(localId, { progress }), initOptions, controller.signal));
         }
         catch (error) {
+            if (controller.signal.aborted || isPhiMediaUploadCancelled(error)) {
+                setItems((current) => current.filter((item) => item.localId !== localId));
+                return null;
+            }
             const message = readPhiMediaUploadErrorMessage(error, labels);
             patch(localId, { progress: 100, status: "error", error: message });
             onRejected?.(message, file);
             return null;
         }
+        finally {
+            running.current.delete(controller);
+        }
+        // Stopped while finalize was answering: the Asset exists, but nobody is waiting to enter it.
+        if (controller.signal.aborted)
+            return null;
+        patch(localId, { progress: 100, status: "done", assetId: asset.id });
+        try {
+            await onUploaded?.(asset, file);
+        }
+        catch (error) {
+            const message = readPhiMediaUploadErrorMessage(error, labels);
+            patch(localId, { status: "error", error: message });
+            onRejected?.(message, file);
+            return null;
+        }
+        return asset;
     }, [acceptance, initOptions, labels, onRejected, onUploaded, patch, runSession]);
+    const cancel = useCallback(() => {
+        for (const controller of running.current)
+            controller.abort();
+    }, []);
     const reset = useCallback(() => setItems([]), []);
-    return { accept, items, upload, reset };
+    const uploading = items.some((item) => item.status === "uploading");
+    return { accept, items, uploading, upload, cancel, reset };
 }

package/components/media/phi-site-font-assets.d.ts

@@ -1,5 +1,5 @@
 import type { PhiFontMetrics } from "../../types/media";
-export type PhiSiteFontAssetOption = {
+type PhiSiteFontAssetOption = {
     assetId: number;
     /** What a Theme writes into the slot. */
     value: string;
@@ -11,7 +11,14 @@ export type PhiSiteFontAssetOption = {
     contentType: string;
     metrics: PhiFontMetrics | null;
 };
+/**
+ * `error` is the library saying it could not be read: the catalogue families are still a usable list,
+ * but a Site typeface that is not in it is not "gone", and a picker that showed the list without a word
+ * let an author believe their upload had failed.
+ */
 export declare function usePhiSiteFontAssets(enabled?: boolean): {
     options: readonly PhiSiteFontAssetOption[];
     loading: boolean;
+    error: string | null;
 };
+export {};

package/components/media/phi-site-font-assets.js

@@ -1,4 +1,5 @@
 "use client";
+import { isPhiRecord } from "../../helpers/is-record";
 import { useEffect, useMemo, useState } from "react";
 import { PhiMediaKind } from "../../constants/media";
 import { createPhiAssetUri } from "../../types/references";
@@ -19,7 +20,7 @@ import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
 const PHI_SITE_FONT_ASSET_LIMIT = 100;
 function readFontAssetMetrics(asset) {
     const meta = asset.meta?.font;
-    if (!meta || typeof meta !== "object" || Array.isArray(meta))
+    if (!isPhiRecord(meta))
         return null;
     const record = meta;
     // The management tile carries `meta` as stored; only a shape with its unit grid is worth drawing from.
@@ -31,10 +32,16 @@ function readFontAssetLabel(asset) {
         return family.trim();
     return asset.title?.trim() || asset.originalName.trim();
 }
+/**
+ * `error` is the library saying it could not be read: the catalogue families are still a usable list,
+ * but a Site typeface that is not in it is not "gone", and a picker that showed the list without a word
+ * let an author believe their upload had failed.
+ */
 export function usePhiSiteFontAssets(enabled = true) {
     const { provider } = usePhiCollectionProvider(PHI_ASSET_COLLECTION_DATA_SOURCE);
     const [assets, setAssets] = useState([]);
     const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
     useEffect(() => {
         if (!enabled || !provider)
             return;
@@ -42,6 +49,7 @@ export function usePhiSiteFontAssets(enabled = true) {
         // The request is the external state this mirrors; loading starts with it, inside the same effect.
         // eslint-disable-next-line react-hooks/set-state-in-effect
         setLoading(true);
+        setError(null);
         void provider.query({
             resourceKey: PHI_ASSET_COLLECTION_DATA_SOURCE.resourceKey,
             query: {
@@ -55,11 +63,17 @@ export function usePhiSiteFontAssets(enabled = true) {
         }).then((data) => {
             if (abortController.signal.aborted)
                 return;
-            setAssets(data.items.filter((item) => Boolean(item)));
-        }).catch(() => {
-            // A library that cannot be read leaves the catalogue families, which is a usable list.
-            if (!abortController.signal.aborted)
+            if (data.error) {
                 setAssets([]);
+                setError(data.error);
+                return;
+            }
+            setAssets(data.items.filter((item) => Boolean(item)));
+        }).catch((cause) => {
+            if (abortController.signal.aborted)
+                return;
+            setAssets([]);
+            setError(cause instanceof Error && cause.message ? cause.message : "The Media library could not be read.");
         }).finally(() => {
             if (!abortController.signal.aborted)
                 setLoading(false);
@@ -77,5 +91,5 @@ export function usePhiSiteFontAssets(enabled = true) {
         contentType: asset.contentType,
         metrics: readFontAssetMetrics(asset),
     })), [assets]);
-    return { options, loading };
+    return { options, loading, error };
 }

package/components/motion/phi-sequence-run.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type PhiSequenceSettings } from "../widgets/config/sequence-settings";
+import type { PhiSequenceControlLabels } from "../widgets/label-types/sequence";
+/** How many items stand in the window: never more than there are, never fewer than one. */
+export declare function resolvePhiSequenceRunSpan(visibleCount: number | undefined, itemCount: number): number;
+/**
+ * A run of items shown a few at a time, and the two things the browser will not do for us.
+ *
+ * The first is knowing which item is next. Native lazy loading decides from an element's distance to
+ * the viewport, so on a fade -- where every item sits in the same place -- it loads all of them at once,
+ * and on a slide it loads the next one as it arrives, during the transition. So the window says what
+ * loads: what is mounted is wanted, and an item that loads anything should load it eagerly.
+ *
+ * The second is stopping: `usePhiSequenceAutoplay` holds every way to decline movement nobody asked
+ * for, and the Pause button is the one a finger has, since a finger neither hovers nor tabs. Where
+ * the window stops -- the last window rather than the last multiple of the window -- is the Carousel
+ * Layout's list of stops (`phi-carousel-pages.ts`), read by the arrows, the dots and the timer alike.
+ *
+ * What the items are is the caller's: the Gallery's pictures, the Entries list's cards.
+ */
+export declare function PhiSequenceRun({ items, settings, labels, itemStyle, }: {
+    /** Keyed by the caller; the run neither wraps nor rekeys them. */
+    items: readonly ReactNode[];
+    settings: PhiSequenceSettings | undefined;
+    labels: PhiSequenceControlLabels;
+    itemStyle?: CSSProperties;
+}): import("react").JSX.Element | null;

package/components/motion/phi-sequence-run.js

@@ -0,0 +1,87 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useState } from "react";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { PhiButtonControl } from "../controls/phi-button-control";
+import { resolvePhiCarouselCurrentPage, resolvePhiCarouselPageStarts, resolvePhiCarouselStep, } from "../layouts/phi-carousel-pages";
+import { PhiIcon } from "../shell/phi-icon";
+import { resolvePhiSpacingScaleValue } from "../widgets/config/spacing-options";
+import { PHI_SEQUENCE_SETTINGS_DEFAULTS, } from "../widgets/config/sequence-settings";
+import { PhiSequenceViewport, resolvePhiSequenceWindowStart } from "./phi-sequence-viewport";
+import { usePhiSequenceAutoplay } from "./use-phi-sequence-autoplay";
+import { usePhiSequenceGestures } from "./use-phi-sequence-gestures";
+/** The dots' label, `%1` the first and `%2` the last item a page shows. */
+function formatPageLabel(template, from, to) {
+    return template.replace("%1", String(from)).replace("%2", String(to));
+}
+/** How many items stand in the window: never more than there are, never fewer than one. */
+export function resolvePhiSequenceRunSpan(visibleCount, itemCount) {
+    return Math.min(visibleCount ?? PHI_SEQUENCE_SETTINGS_DEFAULTS.visibleCount, Math.max(itemCount, 1));
+}
+/**
+ * A run of items shown a few at a time, and the two things the browser will not do for us.
+ *
+ * The first is knowing which item is next. Native lazy loading decides from an element's distance to
+ * the viewport, so on a fade -- where every item sits in the same place -- it loads all of them at once,
+ * and on a slide it loads the next one as it arrives, during the transition. So the window says what
+ * loads: what is mounted is wanted, and an item that loads anything should load it eagerly.
+ *
+ * The second is stopping: `usePhiSequenceAutoplay` holds every way to decline movement nobody asked
+ * for, and the Pause button is the one a finger has, since a finger neither hovers nor tabs. Where
+ * the window stops -- the last window rather than the last multiple of the window -- is the Carousel
+ * Layout's list of stops (`phi-carousel-pages.ts`), read by the arrows, the dots and the timer alike.
+ *
+ * What the items are is the caller's: the Gallery's pictures, the Entries list's cards.
+ */
+export function PhiSequenceRun({ items, settings, labels, itemStyle, }) {
+    const { token } = usePhiConfig();
+    const defaults = PHI_SEQUENCE_SETTINGS_DEFAULTS;
+    const loop = settings?.loop ?? defaults.loop;
+    const controls = settings?.controls ?? defaults.controls;
+    const autoplayMs = settings?.autoplayMs ?? defaults.autoplayMs;
+    const itemCount = items.length;
+    const [activeIndex, setActiveIndex] = useState(0);
+    const span = resolvePhiSequenceRunSpan(settings?.visibleCount, itemCount);
+    const pageStarts = useMemo(() => resolvePhiCarouselPageStarts(itemCount, span), [itemCount, span]);
+    const lastStart = pageStarts[pageStarts.length - 1] ?? 0;
+    const step = useCallback((direction) => {
+        setActiveIndex((current) => resolvePhiCarouselStep(pageStarts, current, direction, loop));
+    }, [loop, pageStarts]);
+    const advance = useCallback(() => step(1), [step]);
+    const autoplay = usePhiSequenceAutoplay({ intervalMs: autoplayMs, active: itemCount > span, advance });
+    // A step somebody took: the next automatic one is a whole interval away again.
+    const stepByHand = useCallback((direction) => {
+        step(direction);
+        autoplay.restart();
+    }, [autoplay, step]);
+    const gestures = usePhiSequenceGestures({ step: stepByHand });
+    if (itemCount === 0) {
+        return null;
+    }
+    const windowStart = resolvePhiSequenceWindowStart({
+        activeIndex,
+        visibleCount: span,
+        itemCount,
+        anchor: "start",
+    });
+    const pageCount = pageStarts.length;
+    const currentPage = resolvePhiCarouselCurrentPage(pageStarts, windowStart);
+    const atStart = windowStart <= 0;
+    const atEnd = windowStart >= lastStart;
+    // Two disabled arrows over a single item say nothing; the dots already know to stay away.
+    const showArrows = (controls === "arrows" || controls === "both") && itemCount > span;
+    const showDots = (controls === "dots" || controls === "both") && pageCount > 1;
+    return (_jsxs("div", { role: "region", "aria-roledescription": "carousel", "aria-label": labels.region, style: { display: "flex", flexDirection: "column", gap: token.marginXS, width: "100%", minWidth: 0, ...gestures.style }, ...autoplay.holdHandlers, ...gestures.handlers, children: [_jsxs("div", { style: { position: "relative", minWidth: 0 }, "aria-live": autoplay.running ? "off" : "polite", children: [_jsx(PhiSequenceViewport, { items: [...items], activeIndex: activeIndex, visibleCount: span, anchor: "start", transition: settings?.transition ?? defaults.transition, ...(settings?.durationMs === undefined ? {} : { durationMs: settings.durationMs }), ...(settings?.easing === undefined ? {} : { easing: settings.easing }), lookahead: settings?.lookahead ?? defaults.lookahead, mountPolicy: settings?.mountPolicy ?? defaults.mountPolicy, gap: resolvePhiSpacingScaleValue(settings?.gap ?? defaults.gap), itemStyle: itemStyle }), showArrows ? (_jsxs(_Fragment, { children: [_jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineStart: token.marginXS, transform: "translateY(-50%)" }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: "left", size: "inherit" }), ariaLabel: labels.previous, shape: "circle", disabled: atStart && !loop, onClick: () => stepByHand(-1) }) }), _jsx("div", { style: { position: "absolute", insetBlockStart: "50%", insetInlineEnd: token.marginXS, transform: "translateY(-50%)" }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: "right", size: "inherit" }), ariaLabel: labels.next, shape: "circle", disabled: atEnd && !loop, onClick: () => stepByHand(1) }) })] })) : null, autoplay.offered ? (_jsx("div", { style: { position: "absolute", insetBlockEnd: token.marginXS, insetInlineEnd: token.marginXS }, children: _jsx(PhiButtonControl, { icon: _jsx(PhiIcon, { name: autoplay.stopped ? "play-circle" : "pause-circle", size: "inherit" }), ariaLabel: autoplay.stopped ? labels.play : labels.pause, ariaPressed: autoplay.stopped, shape: "circle", onClick: autoplay.toggleStopped }) })) : null] }), showDots ? (_jsx("div", { role: "group", "aria-label": labels.pages, style: { display: "flex", justifyContent: "center", gap: token.marginXXS }, children: Array.from({ length: pageCount }, (_, page) => (_jsx("button", { type: "button", "aria-label": formatPageLabel(labels.page, (pageStarts[page] ?? 0) + 1, Math.min((pageStarts[page] ?? 0) + span, itemCount)), "aria-current": page === currentPage || undefined, onClick: () => {
+                        setActiveIndex(pageStarts[page] ?? 0);
+                        autoplay.restart();
+                    }, style: {
+                        width: page === currentPage ? token.controlHeightXS : token.marginXS,
+                        height: token.marginXS,
+                        padding: 0,
+                        border: "none",
+                        cursor: "pointer",
+                        borderRadius: token.borderRadiusSM,
+                        background: page === currentPage ? token.colorPrimary : token.colorFill,
+                        transition: `width ${token.motionDurationMid}, background ${token.motionDurationMid}`,
+                    } }, page))) })) : null] }));
+}

package/components/motion/phi-sequence-viewport.d.ts

@@ -1,6 +1,22 @@
 import { type CSSProperties, type ReactNode } from "react";
 import { type PhiMotionEasing, type PhiSequenceAnchor, type PhiSequenceTransition } from "../../helpers/motion";
 import { type PhiCmsMountPolicy } from "../../types/cms-mount-policy";
+/**
+ * A window onto a sequence, and the movement from one window to the next.
+ *
+ * This is the piece a Stack, a Carousel and an image gallery have in common, and it is deliberately
+ * the thinnest of the three layers: it takes already-rendered children, an index and a shape, and it
+ * knows nothing about slots, signals, the Builder or where the pictures came from. Whoever owns the
+ * index -- a signal channel, a pair of arrows, a timer -- owns it outside.
+ *
+ * Two geometries, chosen by the transition, because the two ways of showing a sequence are genuinely
+ * different acts. `slide` lays the items out side by side on a track and moves the track: the
+ * neighbours exist next to the window and arrive from the direction they were in. `fade`, `diagonal`
+ * and `none` keep the window where it is and exchange what stands in its places -- the Stack's way.
+ * A fade crosses the leaving items over into the coming ones; a diagonal leaves the old ones standing
+ * and slides each new one over its place from the corner it comes from, below and after it going
+ * forward, above and before it going back. Nothing travels sideways.
+ */
 export type PhiSequenceViewportProps = {
     items: readonly ReactNode[];
     /**

package/components/motion/phi-sequence-viewport.js

@@ -1,26 +1,8 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from "react";
-import { clampPhiSequenceTransitionMs, } from "../../helpers/motion";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { clampPhiSequenceTransitionMs, PHI_SEQUENCE_DEFAULT_DURATION_MS, PHI_SEQUENCE_DEFAULT_EASING, } from "../../helpers/motion";
 import { shouldPhiCmsContentStayMounted, } from "../../types/cms-mount-policy";
-/**
- * A window onto a sequence, and the movement from one window to the next.
- *
- * This is the piece a Stack, a Carousel and an image gallery have in common, and it is deliberately
- * the thinnest of the three layers: it takes already-rendered children, an index and a shape, and it
- * knows nothing about slots, signals, the Builder or where the pictures came from. Whoever owns the
- * index -- a signal channel, a pair of arrows, a timer -- owns it outside.
- *
- * Two geometries, chosen by the transition, because the two ways of showing a sequence are genuinely
- * different acts. `slide` and `diagonal` lay the items out side by side on a track and move the track:
- * the neighbours exist next to the window and arrive from the direction they were in. `fade` and
- * `none` put the window's items in flow and cross-fade the ones that are leaving over the top, which
- * is what the Stack has always done -- the items do not travel, they exchange places.
- */
-/** How far a diagonal leaves the horizontal, as a share of the travel it is already making. */
-const DIAGONAL_RISE = 0.35;
-/** What a caller who says nothing gets: long enough to read as movement, short enough to ignore. */
-const DEFAULT_SEQUENCE_DURATION_MS = 320;
 function toCssLength(value) {
     if (value === undefined)
         return "0px";
@@ -41,7 +23,7 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
     // whole number is a caller's mistake, and the type says so rather than this line rescuing it.
     const span = Math.min(visibleCount, Math.max(itemCount, 1));
     const start = resolvePhiSequenceWindowStart({ activeIndex, visibleCount: span, itemCount, anchor });
-    const onTrack = transition === "slide" || transition === "diagonal";
+    const onTrack = transition === "slide";
     /*
      * Which items have ever been inside the window, which is what `lazy-keep` keeps.
      *
@@ -68,9 +50,22 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
     if (fadeState.start !== start) {
         setFadeState({ start, outgoingStart: onTrack || transition === "none" ? null : fadeState.start });
     }
-    const reducedMotion = typeof window !== "undefined" &&
-        typeof window.matchMedia === "function" &&
-        window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    /*
+     * Read in an effect, not during render: the server cannot know the preference, and a first client
+     * pass that already knew it drew different transition styles than the HTML it was hydrating --
+     * React then rebuilt the tree, which read as a jump on every page with a sequence under reduced
+     * motion. The first pass agrees with the server; the preference arrives one render later.
+     */
+    const [reducedMotion, setReducedMotion] = useState(false);
+    useEffect(() => {
+        if (typeof window.matchMedia !== "function")
+            return undefined;
+        const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+        const sync = () => setReducedMotion(query.matches);
+        sync();
+        query.addEventListener("change", sync);
+        return () => query.removeEventListener("change", sync);
+    }, []);
     /*
      * Reduced motion means none of it rather than less of it. Somebody who has asked for no movement
      * has not asked for shorter movement, so the duration is taken to zero instead of being shortened.
@@ -78,9 +73,9 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
     const resolvedDurationMs = reducedMotion || transition === "none"
         ? 0
         : durationMs === undefined
-            ? DEFAULT_SEQUENCE_DURATION_MS
+            ? PHI_SEQUENCE_DEFAULT_DURATION_MS
             : clampPhiSequenceTransitionMs(durationMs);
-    const resolvedEasing = easing ?? "ease-in-out";
+    const resolvedEasing = easing ?? PHI_SEQUENCE_DEFAULT_EASING;
     const gapLength = toCssLength(gap);
     const slice = span === 1
         ? "100%"
@@ -99,9 +94,70 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
             mountedIndices.add(index);
         }
     }
-    const trackTransform = onTrack
-        ? `translate3d(calc(-1 * ${start} * ${step}), ${transition === "diagonal" ? `calc(-1 * ${start} * ${step} * ${DIAGONAL_RISE})` : "0px"}, 0)`
-        : undefined;
+    const trackTransform = onTrack ? `translate3d(calc(-1 * ${start} * ${step}), 0px, 0)` : undefined;
+    /*
+     * The exchange between two windows off the track, played after the new window is laid out and before
+     * it is painted, so the first frame already starts where the movement does.
+     *
+     * At the tail the last window overlaps the one before it -- five pictures three at a time go one to
+     * three, then three to five -- so an item can be in both windows at another place. It cannot leave
+     * where it was and arrive where it goes as one element, and moving it at once read as the one picture
+     * that changed without a transition. So it arrives at its new place like any other, and a copy of it
+     * stands in its old place until the leaving window is let go.
+     */
+    const leavingStart = onTrack ? null : fadeState.outgoingStart;
+    const movedIndices = leavingStart === null
+        ? []
+        : Array.from({ length: span }, (_, offset) => leavingStart + offset)
+            // In the window it left and in the one it enters: a new start puts it at another place.
+            .filter((index) => index >= start && index < start + span);
+    const itemElements = useRef([]);
+    const trackElement = useRef(null);
+    const previousStart = useRef(start);
+    const runningAnimations = useRef([]);
+    useLayoutEffect(() => {
+        const from = previousStart.current;
+        previousStart.current = start;
+        if (from === start || onTrack || resolvedDurationMs === 0)
+            return;
+        /*
+         * A step taken while the last one is still moving -- a click on top of autoplay, an interval as
+         * short as the movement -- starts from a window that has arrived. Left running, the half-arrived
+         * items became the leaving ones over nothing, because what stood under them was let go.
+         */
+        for (const animation of runningAnimations.current)
+            animation.finish();
+        runningAnimations.current = [];
+        const timing = { duration: resolvedDurationMs, easing: resolvedEasing };
+        const windowIndices = Array.from({ length: span }, (_, offset) => start + offset);
+        const moved = windowIndices.filter((index) => index >= from && index < from + span);
+        const copyOf = (index) => trackElement.current?.querySelector(`[data-phi-sequence-leaving="${index}"]`);
+        if (transition === "fade") {
+            for (const index of moved) {
+                // Not held at the end: the item's own opacity is 1 already, and a held animation would outlast
+                // the next fade that wants to take it away.
+                const arriving = itemElements.current[index]?.animate?.([{ opacity: 0 }, { opacity: 1 }], timing);
+                // The copy is held at nothing until it goes, which is when the leaving window is let go.
+                const leaving = copyOf(index)?.animate?.([{ opacity: 1 }, { opacity: 0 }], { ...timing, fill: "forwards" });
+                runningAnimations.current.push(...[arriving, leaving].filter((animation) => animation !== undefined));
+            }
+            return;
+        }
+        if (transition === "diagonal") {
+            /*
+             * A whole place's width and height, as a percentage of the item itself: every new item starts one
+             * box off its place, so each comes in from outside the window's corner, whatever its proportion.
+             */
+            const offset = start > from ? "100%" : "-100%";
+            const animations = windowIndices.flatMap((index) => {
+                const animation = itemElements.current[index]?.animate?.([{ translate: `${offset} ${offset}` }, { translate: "0 0" }], timing);
+                return animation ? [animation] : [];
+            });
+            runningAnimations.current = animations;
+            // Nothing fades here, so no transition ends to say so: the window is let go when the last item is in.
+            void Promise.all(animations.map((animation) => animation.finished)).then(() => setFadeState((current) => (current.start === start ? { ...current, outgoingStart: null } : current)), () => undefined);
+        }
+    }, [start, span, onTrack, transition, resolvedDurationMs, resolvedEasing]);
     const renderedItems = items.map((item, index) => {
         const visible = index >= start && index < start + span;
         const outgoing = !visible && fadeState.outgoingStart !== null &&
@@ -116,7 +172,8 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
             ? { flex: `0 0 ${slice}`, minWidth: 0 }
             : {
                 ...(visible
-                    ? { flex: `0 0 ${slice}`, minWidth: 0 }
+                    // Above what leaves, so a diagonal's new items cover the old ones they slide over.
+                    ? { flex: `0 0 ${slice}`, minWidth: 0, position: "relative", zIndex: 1 }
                     : {
                         position: "absolute",
                         insetBlockStart: 0,
@@ -126,17 +183,26 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
                             : 0,
                         width: slice,
                     }),
-                opacity: visible ? 1 : 0,
-                transition: resolvedDurationMs > 0
+                // A diagonal's leaving items stand until the new ones cover them; a fade's go out.
+                opacity: visible || (outgoing && transition === "diagonal" && resolvedDurationMs > 0) ? 1 : 0,
+                transition: resolvedDurationMs > 0 && transition === "fade"
                     ? `opacity ${resolvedDurationMs}ms ${resolvedEasing}`
                     : undefined,
             };
+        const ref = (element) => {
+            itemElements.current[index] = element;
+        };
         if (!mounted && !visible && !outgoing) {
-            return _jsx("div", { "aria-hidden": true, style: { ...box, pointerEvents: "none" } }, index);
+            return _jsx("div", { ref: ref, "aria-hidden": true, style: { ...box, pointerEvents: "none" } }, index);
         }
-        return (_jsx("div", { "data-phi-sequence-item-state": visible ? "visible" : outgoing ? "outgoing" : "waiting", inert: !visible, "aria-hidden": !visible || undefined, style: { ...box, ...itemStyle }, children: mounted ? (renderItem ? renderItem(item, { index, visible }) : item) : null }, index));
+        return (_jsx("div", { ref: ref, "data-phi-sequence-item-state": visible ? "visible" : outgoing ? "outgoing" : "waiting", inert: !visible, "aria-hidden": !visible || undefined, style: { ...box, ...itemStyle }, children: mounted ? (renderItem ? renderItem(item, { index, visible }) : item) : null }, index));
     });
-    return (_jsx("div", { className: className, "data-phi-sequence-transition": transition, style: { position: "relative", overflow: "hidden", minWidth: 0, ...style }, children: _jsx("div", { style: {
+    return (_jsx("div", { className: className, "data-phi-sequence-transition": transition, 
+        /*
+         * Its own stacking context: the items it raises over the leaving ones are raised inside it, never
+         * over the arrows and buttons a caller lays over the viewport.
+         */
+        style: { position: "relative", overflow: "hidden", isolation: "isolate", minWidth: 0, ...style }, children: _jsxs("div", { ref: trackElement, style: {
                 position: "relative",
                 display: "flex",
                 alignItems: "stretch",
@@ -164,5 +230,15 @@ export function PhiSequenceViewport({ items, activeIndex, visibleCount = 1, anch
                     : {}),
             }, onTransitionEnd: fadeState.outgoingStart === null
                 ? undefined
-                : () => setFadeState((current) => ({ ...current, outgoingStart: null })), children: renderedItems }) }));
+                : () => setFadeState((current) => ({ ...current, outgoingStart: null })), children: [renderedItems, leavingStart === null ? null : movedIndices.map((index) => (_jsx("div", { "data-phi-sequence-leaving": index, "aria-hidden": true, inert: true, style: {
+                        position: "absolute",
+                        insetBlockStart: 0,
+                        insetBlockEnd: 0,
+                        insetInlineStart: `calc(${index - leavingStart} * ${step})`,
+                        width: slice,
+                        // Under the window's own items, which arrive over it.
+                        zIndex: 0,
+                        pointerEvents: "none",
+                        ...itemStyle,
+                    }, children: items[index] }, `leaving-${index}`)))] }) }));
 }

package/components/motion/use-phi-sequence-autoplay.d.ts

@@ -0,0 +1,26 @@
+export type PhiSequenceAutoplayOptions = {
+    /** Absent or zero means it does not move on its own. */
+    intervalMs?: number;
+    /** Whether there is anything to move -- more items than the window shows, and not the canvas. */
+    active: boolean;
+    advance: () => void;
+};
+export type PhiSequenceAutoplay = {
+    /** Whether the sequence is told to move at all, before anybody declined it. */
+    offered: boolean;
+    /** Whether the timer is running right now. */
+    running: boolean;
+    /** Whether a person pressed Pause; the one stop that outlives the pointer leaving. */
+    stopped: boolean;
+    toggleStopped: () => void;
+    /** After a manual step, so the next automatic one is a whole interval away. */
+    restart: () => void;
+    /** Spread onto the box: pointing at it or tabbing into it holds the timer. */
+    holdHandlers: {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+        onFocusCapture: () => void;
+        onBlurCapture: () => void;
+    };
+};
+export declare function usePhiSequenceAutoplay({ intervalMs, active, advance }: PhiSequenceAutoplayOptions): PhiSequenceAutoplay;

package/components/motion/use-phi-sequence-autoplay.js

@@ -0,0 +1,52 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+function readDocumentHidden() {
+    return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+export function usePhiSequenceAutoplay({ intervalMs = 0, active, advance }) {
+    const [held, setHeld] = useState(false);
+    const [stopped, setStopped] = useState(false);
+    const [hidden, setHidden] = useState(false);
+    // Read in an effect rather than during render, so the server's markup and the browser's first pass agree.
+    const [reducedMotion, setReducedMotion] = useState(false);
+    const [epoch, setEpoch] = useState(0);
+    useEffect(() => {
+        if (typeof window.matchMedia !== "function")
+            return undefined;
+        const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+        const sync = () => setReducedMotion(query.matches);
+        sync();
+        query.addEventListener("change", sync);
+        return () => query.removeEventListener("change", sync);
+    }, []);
+    useEffect(() => {
+        const sync = () => setHidden(readDocumentHidden());
+        sync();
+        document.addEventListener("visibilitychange", sync);
+        return () => document.removeEventListener("visibilitychange", sync);
+    }, []);
+    const offered = intervalMs > 0 && active;
+    const running = offered && !held && !stopped && !hidden && !reducedMotion;
+    useEffect(() => {
+        if (!running)
+            return undefined;
+        const timer = window.setInterval(advance, intervalMs);
+        return () => window.clearInterval(timer);
+        // `epoch` is here on purpose: bumping it is how a manual step restarts the interval.
+    }, [advance, epoch, intervalMs, running]);
+    const restart = useCallback(() => setEpoch((current) => current + 1), []);
+    const toggleStopped = useCallback(() => setStopped((current) => !current), []);
+    return {
+        offered,
+        running,
+        stopped,
+        toggleStopped,
+        restart,
+        holdHandlers: {
+            onMouseEnter: () => setHeld(true),
+            onMouseLeave: () => setHeld(false),
+            onFocusCapture: () => setHeld(true),
+            onBlurCapture: () => setHeld(false),
+        },
+    };
+}

package/components/motion/use-phi-sequence-gestures.d.ts

@@ -0,0 +1,24 @@
+import { type CSSProperties, type DragEvent, type KeyboardEvent, type PointerEvent } from "react";
+/**
+ * Which way a swipe moves the sequence, or `null` where it was a tap, a scroll or too short.
+ *
+ * A finger going left pulls the next item in, so left is forward. Vertical travel that outweighs the
+ * sideways travel is the page scrolling, and is left to it.
+ */
+export declare function resolvePhiSwipeStep(deltaX: number, deltaY: number, threshold?: number): 1 | -1 | null;
+export type PhiSequenceGestures = {
+    /** Spread onto the box that holds the items. */
+    handlers: {
+        onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+        onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+        onPointerCancel: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+        /** A mouse dragging a picture starts the browser's own drag of it, which cancels the pointer. */
+        onDragStart: (event: DragEvent<HTMLElement>) => void;
+    };
+    /** Lets the page keep scrolling vertically over the box while a sideways swipe is the sequence's. */
+    style: Pick<CSSProperties, "touchAction">;
+};
+export declare function usePhiSequenceGestures({ step }: {
+    step: (direction: 1 | -1) => void;
+}): PhiSequenceGestures;