@phis/ui 0.3.0 → 0.4.1

package/components/controls/phi-tour-viewport.js

@@ -0,0 +1,86 @@
+/**
+ * Where a Tour step's target is brought into view: below whatever stays stuck at the top of the window.
+ *
+ * Ant Design's Tour knows neither. It scrolls only when the target is not wholly inside the window, so a
+ * target taller than the window is scrolled on every step and every scroll event -- to the middle, its
+ * top under the Header -- and a target under a sticky Header counts as seen and is not scrolled at all.
+ * So the owning Controller sets the window's scroll padding to the cover before the step is presented
+ * (design/TOURS.md, Target readiness), `PhiTourControl` hands Ant Design the alignment that fits the
+ * target, and once the step stands it brings in a target Ant Design took for seen. Every scroll then
+ * aims at the same place, and the one Ant Design repeats on every scroll event moves nothing.
+ *
+ * Not while the previous step is still shown: Ant Design scrolls back to a shown target that leaves the
+ * window, so a scroll begun before the new step is presented is undone by the old one.
+ *
+ * The cover is found from the target outwards, not by searching the document: the Shell's Header bands
+ * and a Page's sticky band are siblings of something the target stands in, so the bands are found among
+ * the earlier siblings of the target's ancestors that are stuck, sit at the top, and stand over the target.
+ */
+/** Whether the viewer asked for less motion: the Tour then jumps rather than glides. */
+function prefersPhiTourReducedMotion() {
+    return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+}
+export function resolvePhiTourScrollBehavior() {
+    return prefersPhiTourReducedMotion() ? "auto" : "smooth";
+}
+/** Air between the cover and the target, so a highlighted edge is not drawn against the Header. */
+const PHI_TOUR_VIEWPORT_GAP = 8;
+function isStuck(element) {
+    const { position } = getComputedStyle(element);
+    return position === "sticky" || position === "fixed";
+}
+/** How far down from the window's top the bands that stay put over `target` reach, in pixels. */
+function readPhiTourTopCover(target) {
+    const viewHeight = window.innerHeight;
+    const targetRect = target.getBoundingClientRect();
+    let cover = 0;
+    for (let node = target; node && node !== document.body; node = node.parentElement) {
+        for (let sibling = node.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+            if (!isStuck(sibling))
+                continue;
+            const rect = sibling.getBoundingClientRect();
+            const atTop = rect.height > 0 && rect.top < viewHeight / 2 && rect.height < viewHeight / 2;
+            const overTarget = rect.left < targetRect.right && rect.right > targetRect.left;
+            if (atTop && overTarget)
+                cover = Math.max(cover, rect.bottom);
+        }
+    }
+    return Math.max(0, Math.round(cover));
+}
+/**
+ * Centered where the target fits below the cover, top-aligned under it where it does not: a target
+ * taller than what is left of the window is read from its top.
+ */
+export function resolvePhiTourScrollBlock(target, cover = readPhiTourTopCover(target)) {
+    const free = window.innerHeight - cover - PHI_TOUR_VIEWPORT_GAP * 2;
+    return target.getBoundingClientRect().height <= free ? "center" : "start";
+}
+/**
+ * Keeps the window's scroll padding at the cover over `target`, so every `scrollIntoView` -- Ant
+ * Design's included -- aligns below it. Returns the cover.
+ */
+export function holdPhiTourViewport(target) {
+    const cover = readPhiTourTopCover(target);
+    document.documentElement.style.scrollPaddingTop = `${cover + PHI_TOUR_VIEWPORT_GAP}px`;
+    return cover;
+}
+/**
+ * Brings `target` into the part of the window nothing covers. A target already wholly in that part --
+ * or, taller than it, already standing at its top -- is left where it is. Returns whether it scrolled.
+ */
+export function bringPhiTourTargetIntoView(target, behavior) {
+    const cover = holdPhiTourViewport(target);
+    const rect = target.getBoundingClientRect();
+    const block = resolvePhiTourScrollBlock(target, cover);
+    const inView = block === "center"
+        ? rect.top >= cover && rect.bottom <= window.innerHeight
+        : Math.abs(rect.top - cover - PHI_TOUR_VIEWPORT_GAP) <= 1;
+    if (inView)
+        return false;
+    target.scrollIntoView({ block, inline: "nearest", behavior });
+    return true;
+}
+/** The window's scroll padding as it was before a Tour set it. */
+export function releasePhiTourViewport() {
+    document.documentElement.style.scrollPaddingTop = "";
+}

package/components/controls/phi-zoom-image-overlay.d.ts

@@ -0,0 +1,17 @@
+export type PhiZoomImageOverlayProps = {
+    open: boolean;
+    src: string;
+    alt: string;
+    title?: string;
+    onClose: () => void;
+};
+/**
+ * A picture scaled to the viewport over the page, and nothing else: no toolbar, no zoom steps, no
+ * rotation -- that is the lightbox's (`PhiLightboxImageControl`). A click anywhere closes it, as does
+ * Escape, and the focus goes back to where it was.
+ *
+ * On `document.body`, at the layer a Modal stands on, for the reason `PhiFloatButtonPortal` gives: a
+ * picture's slot and Region open stacking contexts of their own, and an overlay left inside them would be
+ * painted under the Header. The server draws nothing; it opens only on a click.
+ */
+export declare function PhiZoomImageOverlay({ open, src, alt, title, onClose }: PhiZoomImageOverlayProps): import("react").ReactPortal | null;

package/components/controls/phi-zoom-image-overlay.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { usePhiConfig } from "../root/phi-config-provider";
+const subscribeNever = () => () => { };
+/** Ant Design's `zIndexPopupBase`, the layer its Modal stands on; the Phi token set does not carry it. */
+const PHI_ZOOM_OVERLAY_Z_INDEX = 1000;
+/**
+ * A picture scaled to the viewport over the page, and nothing else: no toolbar, no zoom steps, no
+ * rotation -- that is the lightbox's (`PhiLightboxImageControl`). A click anywhere closes it, as does
+ * Escape, and the focus goes back to where it was.
+ *
+ * On `document.body`, at the layer a Modal stands on, for the reason `PhiFloatButtonPortal` gives: a
+ * picture's slot and Region open stacking contexts of their own, and an overlay left inside them would be
+ * painted under the Header. The server draws nothing; it opens only on a click.
+ */
+export function PhiZoomImageOverlay({ open, src, alt, title, onClose }) {
+    const { token } = usePhiConfig();
+    const mounted = useSyncExternalStore(subscribeNever, () => true, () => false);
+    const overlayRef = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return undefined;
+        const previousFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        overlayRef.current?.focus();
+        const closeOnEscape = (event) => {
+            if (event.key === "Escape")
+                onClose();
+        };
+        document.addEventListener("keydown", closeOnEscape);
+        return () => {
+            document.removeEventListener("keydown", closeOnEscape);
+            previousFocus?.focus();
+        };
+    }, [onClose, open]);
+    if (!mounted || !open)
+        return null;
+    return createPortal(_jsx("div", { ref: overlayRef, role: "dialog", "aria-modal": "true", "aria-label": alt || title, tabIndex: -1, 
+        /*
+         * The portal leaves the DOM, not the React tree: a click here would bubble on to the picture's box,
+         * which opens it again. It stops at the overlay.
+         */
+        onClick: (event) => {
+            event.stopPropagation();
+            onClose();
+        }, onKeyDown: (event) => event.stopPropagation(), style: {
+            position: "fixed",
+            inset: 0,
+            zIndex: PHI_ZOOM_OVERLAY_Z_INDEX,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: token.colorBgMask,
+            cursor: "zoom-out",
+            outline: "none",
+        }, children: _jsx("img", { alt: alt, src: src, title: title, style: { display: "block", width: "100vw", height: "100dvh", objectFit: "contain" } }) }), document.body);
+}

package/components/layouts/layout-definitions.d.ts

@@ -429,15 +429,6 @@ export declare const PHI_CAROUSEL_LAYOUT_DEFINITION: {
         step: number;
         prefix: string;
         options?: undefined;
-    } | {
-        key: string;
-        type: "string";
-        label: string;
-        min?: undefined;
-        max?: undefined;
-        options?: undefined;
-        step?: undefined;
-        prefix?: undefined;
     } | {
         key: string;
         type: "boolean";
@@ -492,7 +483,7 @@ export declare const PHI_GRID_LAYOUT_DEFINITION: {
     kind: "layout";
     pluginKey: string;
     typeKey: string;
-    slotSizePolicy: "fill";
+    slotSizePolicy: "fill-inline";
     title: string;
     description: string;
     category: "structure";
@@ -1132,15 +1123,6 @@ export declare const PHI_CORE_LAYOUT_DEFINITIONS: readonly [{
         step: number;
         prefix: string;
         options?: undefined;
-    } | {
-        key: string;
-        type: "string";
-        label: string;
-        min?: undefined;
-        max?: undefined;
-        options?: undefined;
-        step?: undefined;
-        prefix?: undefined;
     } | {
         key: string;
         type: "boolean";
@@ -1194,7 +1176,7 @@ export declare const PHI_CORE_LAYOUT_DEFINITIONS: readonly [{
     kind: "layout";
     pluginKey: string;
     typeKey: string;
-    slotSizePolicy: "fill";
+    slotSizePolicy: "fill-inline";
     title: string;
     description: string;
     category: "structure";

package/components/layouts/layout-definitions.js

@@ -7,6 +7,7 @@ import { PHI_RENDERABLE_BLOCK_DEFAULT_ANCHOR } from "../../helpers/renderable-bl
 import { PHI_LAYOUT_PADDING_FIELDS } from "../../helpers/layout-padding-field";
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../types/signals";
 import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../../constants/core-data-provider-keys";
+import { PHI_SPACING_SCALE_KEYS } from "../widgets/config/spacing-options";
 const PHI_COLLAPSIBLE_SLOT_OPTIONS = PHI_CMS_COLLAPSIBLE_LAYOUT_SLOTS.map((slot) => ({
     value: slot.key,
     label: slot.label,
@@ -358,7 +359,12 @@ export const PHI_CAROUSEL_LAYOUT_DEFINITION = {
             label: "Easing",
             options: [...PHI_MOTION_EASING_FIELD_OPTIONS],
         },
-        { key: "slotGap", type: "string", label: "Slot Gap" },
+        {
+            key: "slotGap",
+            type: "choice",
+            label: "Slot Gap",
+            options: PHI_SPACING_SCALE_KEYS.map((key) => ({ value: key, label: key })),
+        },
         {
             key: "controls",
             type: "choice",
@@ -409,7 +415,12 @@ export const PHI_GRID_LAYOUT_DEFINITION = {
     kind: "layout",
     pluginKey: resolvePhiCmsLayoutPluginKey("grid"),
     typeKey: "grid",
-    slotSizePolicy: "fill",
+    /*
+     * As wide as its slot, as tall as its rows. A Grid is content in flow: filling the block axis as well
+     * let a vertical stack share its height out among the Grids in it, and each one, held to its share,
+     * spilled its rows over the next section.
+     */
+    slotSizePolicy: "fill-inline",
     title: "Grid",
     description: "Slots in rows, as many to a row as the Grid's own width allows.",
     category: "structure",

package/components/layouts/plugins/carousel-layout-plugin.js

@@ -6,11 +6,12 @@ import { PhiCarouselLayout } from "../phi-carousel-layout";
 import { definePhiLayoutRenderers } from "../layout-plugin-renderers";
 import { resolvePhiLayoutSlotMeta } from "../layout-slot-meta";
 import { PHI_CAROUSEL_LAYOUT_DEFINITION } from "../layout-definitions";
+import { resolvePhiSpacingScaleValue } from "../../widgets/config/spacing-options";
 function resolvePhiCarouselSlotKeys() {
     return PHI_CMS_CAROUSEL_LAYOUT_SLOTS.map((slot) => slot.key);
 }
 export const PHI_CAROUSEL_LAYOUT_PLUGIN = {
     ...PHI_CAROUSEL_LAYOUT_DEFINITION,
     parseConfig: parsePhiCmsCarouselLayoutConfig,
-    ...definePhiLayoutRenderers(({ node, config, renderSequentialSlotChildren }, renderMode) => (_jsx(PhiCarouselLayout, { blockId: node.id, layoutKind: "carousel", slots: renderSequentialSlotChildren(node), slotKeys: resolvePhiCarouselSlotKeys(), slotMeta: resolvePhiLayoutSlotMeta(node, PHI_CMS_CAROUSEL_LAYOUT_SLOTS), renderMode: renderMode, defaultActiveSlotKey: config.defaultActiveSlotKey, visibleSlots: config.visibleSlots, windowAnchor: config.windowAnchor, transition: config.transition, transitionDurationMs: config.transitionDurationMs, transitionEasing: config.transitionEasing, slotGap: config.slotGap, controls: config.controls, loop: config.loop, autoplayMs: config.autoplayMs, lookahead: config.lookahead, slotAnchor: resolvePhiLayoutAnchor(config.anchor, PHI_CAROUSEL_LAYOUT_DEFINITION.defaultAnchor), editSlotAnchor: resolvePhiLayoutAnchor(config.anchor, PHI_CAROUSEL_LAYOUT_DEFINITION.defaultAnchor), zIndex: config.zIndex, surface: config.surface, padding: config.padding, paddingTop: config.paddingTop, paddingRight: config.paddingRight, paddingBottom: config.paddingBottom, paddingLeft: config.paddingLeft, labelEnd: config.labelEnd, size: config.size, minSize: config.minSize, maxSize: config.maxSize, collapsedSizeHint: config.collapsedSizeHint }, `layout-${node.id}`))),
+    ...definePhiLayoutRenderers(({ node, config, renderSequentialSlotChildren }, renderMode) => (_jsx(PhiCarouselLayout, { blockId: node.id, layoutKind: "carousel", slots: renderSequentialSlotChildren(node), slotKeys: resolvePhiCarouselSlotKeys(), slotMeta: resolvePhiLayoutSlotMeta(node, PHI_CMS_CAROUSEL_LAYOUT_SLOTS), renderMode: renderMode, defaultActiveSlotKey: config.defaultActiveSlotKey, visibleSlots: config.visibleSlots, windowAnchor: config.windowAnchor, transition: config.transition, transitionDurationMs: config.transitionDurationMs, transitionEasing: config.transitionEasing, slotGap: resolvePhiSpacingScaleValue(config.slotGap ?? "none"), controls: config.controls, loop: config.loop, autoplayMs: config.autoplayMs, lookahead: config.lookahead, slotAnchor: resolvePhiLayoutAnchor(config.anchor, PHI_CAROUSEL_LAYOUT_DEFINITION.defaultAnchor), editSlotAnchor: resolvePhiLayoutAnchor(config.anchor, PHI_CAROUSEL_LAYOUT_DEFINITION.defaultAnchor), zIndex: config.zIndex, surface: config.surface, padding: config.padding, paddingTop: config.paddingTop, paddingRight: config.paddingRight, paddingBottom: config.paddingBottom, paddingLeft: config.paddingLeft, labelEnd: config.labelEnd, size: config.size, minSize: config.minSize, maxSize: config.maxSize, collapsedSizeHint: config.collapsedSizeHint }, `layout-${node.id}`))),
 };

package/components/media/aspect-ratios.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The proportions a frame for pictures is offered in, stored as `width:height`.
+ *
+ * A closed list rather than a text box: a ratio somebody types is a ratio nobody checks, and the few a
+ * page actually needs are the ones a camera, a screen and a print already use.
+ */
+export declare const PHI_MEDIA_ASPECT_RATIOS: readonly ["16:9", "3:2", "4:3", "1:1", "3:4", "2:3", "9:16", "21:9"];
+export type PhiMediaAspectRatio = (typeof PHI_MEDIA_ASPECT_RATIOS)[number];
+export declare const PHI_MEDIA_ASPECT_RATIO_OPTIONS: {
+    value: "16:9" | "3:2" | "4:3" | "1:1" | "3:4" | "2:3" | "9:16" | "21:9";
+    label: "16:9" | "3:2" | "4:3" | "1:1" | "3:4" | "2:3" | "9:16" | "21:9";
+}[];
+/** The ratio as CSS `aspect-ratio` writes it. */
+export declare function resolvePhiMediaAspectRatioCss(ratio: PhiMediaAspectRatio): string;

package/components/media/aspect-ratios.js

@@ -0,0 +1,13 @@
+/**
+ * The proportions a frame for pictures is offered in, stored as `width:height`.
+ *
+ * A closed list rather than a text box: a ratio somebody types is a ratio nobody checks, and the few a
+ * page actually needs are the ones a camera, a screen and a print already use.
+ */
+export const PHI_MEDIA_ASPECT_RATIOS = ["16:9", "3:2", "4:3", "1:1", "3:4", "2:3", "9:16", "21:9"];
+export const PHI_MEDIA_ASPECT_RATIO_OPTIONS = PHI_MEDIA_ASPECT_RATIOS.map((ratio) => ({ value: ratio, label: ratio }));
+/** The ratio as CSS `aspect-ratio` writes it. */
+export function resolvePhiMediaAspectRatioCss(ratio) {
+    const [width, height] = ratio.split(":");
+    return `${width} / ${height}`;
+}

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 { useEffect, 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.
      *
@@ -91,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%"
@@ -112,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 &&
@@ -129,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,
@@ -139,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",
@@ -177,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}`)))] }) }));
 }