@phis/ui 0.3.0 → 0.4.0

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";
@@ -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";

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",

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}`)))] }) }));
 }

package/components/overlays/phi-overlay-container-client.js

@@ -12,6 +12,7 @@ import { emitPhiSignalCapability, usePhiSignalEmitter, PhiSignalIdentityProvider
 import { usePhiSignalListener } from "../runtime/runtime-signal-bus";
 import { registerPhiSignalInstance } from "../runtime/runtime-signal-registry";
 import { usePhiSignalRuntimePartition } from "../runtime/runtime-signal-partition";
+import { usePhiVisualAnchor } from "../runtime/runtime-visual-anchors";
 import { PhiModalControl } from "../controls/phi-modal-control";
 import { PhiDrawerControl } from "../controls/phi-drawer-control";
 import { PhiAlertControl } from "../controls/phi-alert-control";
@@ -72,6 +73,8 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const openedAtPathname = useRef(null);
     const pathname = usePhiPathname();
     const emitSignal = usePhiSignalEmitter(receiver);
+    // The Overlay's panel, found by a Tour under the Overlay's own address while it is drawn.
+    const panelRef = usePhiVisualAnchor(receiver);
     const loadZones = usePhiOverlayZonesLoaderIfAny();
     const [loadedZones, setLoadedZones] = useState(null);
     const listenRoutes = useMemo(() => config.signalRoutes?.listens ?? [], [config.signalRoutes?.listens]);
@@ -261,7 +264,7 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
      */
     const surfaceStyle = { ...resolvePhiCmsContainerSurface(config).style, padding: 0 };
     if (overlayType === "drawer") {
-        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: behaviour.resizable, push: behaviour.push, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+        return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiDrawerControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, placement: config.placement, size: config.size, maxSize: config.maxSize, resizable: behaviour.resizable, push: behaviour.push, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
     }
-    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body == null ? null : _jsx(PhiDialogBodyProvider, { children: zones.body })), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, centered: behaviour.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose })] }));
+    return (_jsxs(_Fragment, { children: [zoneControllers, _jsx(PhiModalControl, { open: open, title: runtimeTitle, header: renderZone(zones?.header), body: renderZone(zones?.body == null ? null : _jsx(PhiDialogBodyProvider, { children: zones.body })), footer: renderZone(zones?.footer), closable: behaviour.closable, keyboard: behaviour.keyboard, mask: behaviour.mask, mountPolicy: config.mountPolicy, centered: behaviour.centered, controlSize: runtimeControlSize ?? config.controlSize, size: runtimeSize, width: config.width, containerStyle: surfaceStyle, onDismiss: requestClose, panelRef: panelRef })] }));
 }

package/components/runtime/runtime-visual-anchors.d.ts

@@ -1,4 +1,4 @@
-import { type PhiVisualAnchorAddress } from "../../types/tours";
+import { type PhiVisualAnchorAddress } from "../../types/visual-anchors";
 import { type PhiSignalRuntimePartition } from "./runtime-signal-partition";
 /**
  * One registration. The element is reached through a getter rather than held as a value, so whoever reads
@@ -16,7 +16,9 @@ export type PhiVisualAnchorEntry = {
 export declare function registerPhiVisualAnchor(partition: PhiSignalRuntimePartition, entry: PhiVisualAnchorEntry): () => void;
 /**
  * The element an address is drawn as, in this partition and nowhere else, or `null` when it is not there
- * to point at: not mounted, mounted twice, detached, or rendered without a box (hidden, `display: none`).
+ * to point at: not mounted, mounted twice, detached, rendered without a box (hidden, `display: none`), or
+ * with a box of no area -- a slot that hides itself because it has nothing to show still lays out at zero
+ * height, and a Tour pointing at it pointed at nothing.
  */
 export declare function readPhiVisualAnchor(partition: PhiSignalRuntimePartition, address: PhiVisualAnchorAddress): HTMLElement | null;
 /**
@@ -28,6 +30,15 @@ export declare function waitForPhiVisualAnchor(partition: PhiSignalRuntimePartit
     timeoutMs: number;
     signal?: AbortSignal;
 }): Promise<HTMLElement | null>;
+/**
+ * Waits until a found target stops moving -- a Drawer sliding in, a slot opening -- and answers whether it
+ * did before `timeoutMs`. Whoever points at a target measures it once: measured mid-motion, the pointer
+ * stays where the target was on its way, off screen for a Drawer that is still coming in.
+ */
+export declare function waitForPhiVisualAnchorToSettle(element: HTMLElement, { timeoutMs, signal }: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<boolean>;
 /**
  * Registers the element a ref lands on as the visual anchor of `address` in the surrounding partition.
  *

package/components/runtime/runtime-visual-anchors.js

@@ -1,6 +1,6 @@
 "use client";
 import { useCallback, useEffect, useRef } from "react";
-import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/tours";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/visual-anchors";
 import { usePhiSignalRuntimePartition } from "./runtime-signal-partition";
 function notify(partition) {
     for (const subscriber of partition.visualAnchorSubscribers) {
@@ -33,7 +33,9 @@ export function registerPhiVisualAnchor(partition, entry) {
 }
 /**
  * The element an address is drawn as, in this partition and nowhere else, or `null` when it is not there
- * to point at: not mounted, mounted twice, detached, or rendered without a box (hidden, `display: none`).
+ * to point at: not mounted, mounted twice, detached, rendered without a box (hidden, `display: none`), or
+ * with a box of no area -- a slot that hides itself because it has nothing to show still lays out at zero
+ * height, and a Tour pointing at it pointed at nothing.
  */
 export function readPhiVisualAnchor(partition, address) {
     const entries = partition.visualAnchors.get(address);
@@ -41,7 +43,8 @@ export function readPhiVisualAnchor(partition, address) {
     if (!element || !element.isConnected || element.getClientRects().length === 0) {
         return null;
     }
-    return element;
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.height > 0 ? element : null;
 }
 /** How often a wait looks again for a target that is registered but not yet laid out. */
 const WAIT_POLL_INTERVAL_MS = 100;
@@ -76,6 +79,49 @@ export function waitForPhiVisualAnchor(partition, address, { timeoutMs, signal }
         signal?.addEventListener("abort", abort, { once: true });
     });
 }
+/**
+ * How many frames in a row a target has to stand still before it counts as placed. More than two: an
+ * opening slot or Drawer often holds still for a frame or two before its motion starts, and measured
+ * then, the pointer is fixed to where it started.
+ */
+const SETTLE_STILL_FRAMES = 8;
+/**
+ * Waits until a found target stops moving -- a Drawer sliding in, a slot opening -- and answers whether it
+ * did before `timeoutMs`. Whoever points at a target measures it once: measured mid-motion, the pointer
+ * stays where the target was on its way, off screen for a Drawer that is still coming in.
+ */
+export function waitForPhiVisualAnchorToSettle(element, { timeoutMs, signal }) {
+    return new Promise((resolve) => {
+        let last = "";
+        let still = 0;
+        let frame = 0;
+        const finish = (settled) => {
+            window.cancelAnimationFrame(frame);
+            window.clearTimeout(timeout);
+            signal?.removeEventListener("abort", abort);
+            resolve(settled);
+        };
+        const abort = () => finish(false);
+        const look = () => {
+            const box = element.getBoundingClientRect();
+            const next = `${box.x},${box.y},${box.width},${box.height}`;
+            still = next === last ? still + 1 : 0;
+            last = next;
+            if (still >= SETTLE_STILL_FRAMES) {
+                finish(true);
+                return;
+            }
+            frame = window.requestAnimationFrame(look);
+        };
+        const timeout = window.setTimeout(() => finish(false), timeoutMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) {
+            finish(false);
+            return;
+        }
+        frame = window.requestAnimationFrame(look);
+    });
+}
 /**
  * Registers the element a ref lands on as the visual anchor of `address` in the surrounding partition.
  *