@phis/ui 0.3.0 → 0.4.1

package/components/cms/phi-cms-layout-renderer.js

@@ -3,7 +3,7 @@ import { cloneElement, isValidElement } from "react";
 import { readPhiCmsRegionPageScope, resolvePhiCmsRegionPageScope } from "../../helpers/region-page-scope";
 import { isPhiCmsWidgetContentUnpublished } from "../../helpers/cms-content-binding";
 import { comparePhiCmsInstanceIds } from "../../types/cms-instance-id";
-import { readPhiVisualAnchorOwner } from "../../types/tours";
+import { readPhiVisualAnchorOwner } from "../../types/visual-anchors";
 import { hasPhiFlag } from "../../helpers/flags";
 import { PhiCmsFlags } from "../../constants/phi-cms";
 import { PhiFlexVerticalLayout } from "../layouts/phi-flex-vertical-layout";

package/components/controls/phi-collection-header-control.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Typography } from "antd";
 import { usePhiConfig } from "../root/phi-config-provider";
-import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/tours";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/visual-anchors";
 import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
 export function PhiCollectionHeaderControl({ title, description, filters, toolbar, }) {
     const { token } = usePhiConfig();

package/components/controls/phi-collection-view-control.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/visual-anchors";
 import { usePhiConfig } from "../root/phi-config-provider";
 import { PhiCollectionHeaderControl } from "./phi-collection-header-control";
 import { PhiCollectionLayoutControl } from "./phi-collection-layout-control";
@@ -8,7 +9,7 @@ import { PhiSkeletonControl } from "./phi-skeleton-control";
 export function PhiCollectionViewControl({ title, description, filters, toolbar, panel, diagnostics, body, items, mode = "grid", gap, minColumnWidth, pagination, }) {
     const { token } = usePhiConfig();
     const resolvedGap = gap ?? token.paddingSM;
-    return (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%", minWidth: 0 }, children: [_jsx(PhiCollectionHeaderControl, { title: title, description: description, filters: filters, toolbar: toolbar }), panel, diagnostics, body ?? (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: resolvedGap, minColumnWidth: minColumnWidth ?? 102, items: [...(items ?? [])] })), pagination ? (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", width: "100%", minWidth: 0 }, children: _jsx(PhiPaginationControl, { page: pagination.page, pageSize: pagination.pageSize, total: pagination.total, simple: pagination.simple, showSizeChanger: pagination.showSizeChanger, pageSizeOptions: pagination.pageSizeOptions, size: pagination.size, onChange: (value) => pagination.onChange(value.page, value.pageSize) }) })) : null] }));
+    return (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%", minWidth: 0 }, children: [_jsx(PhiCollectionHeaderControl, { title: title, description: description, filters: filters, toolbar: toolbar }), panel, diagnostics, _jsx("div", { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "items", style: { width: "100%", minWidth: 0 }, children: body ?? (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: resolvedGap, minColumnWidth: minColumnWidth ?? 102, items: [...(items ?? [])] })) }), pagination ? (_jsx("div", { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "pagination", style: { display: "flex", justifyContent: "flex-end", width: "100%", minWidth: 0 }, children: _jsx(PhiPaginationControl, { page: pagination.page, pageSize: pagination.pageSize, total: pagination.total, simple: pagination.simple, showSizeChanger: pagination.showSizeChanger, pageSizeOptions: pagination.pageSizeOptions, size: pagination.size, onChange: (value) => pagination.onChange(value.page, value.pageSize) }) })) : null] }));
 }
 export function PhiCollectionViewSkeletonControl({ mode = "grid", gap, minColumnWidth, active = true, count = 8, }) {
     const { token } = usePhiConfig();

package/components/controls/phi-drawer-control-adapter.d.ts

@@ -1,2 +1,2 @@
 import type { PhiDrawerControlProps } from "./phi-drawer-control";
-export declare function PhiDrawerControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, placement, size, maxSize, resizable, push, zIndex, containerStyle, onDismiss, afterOpenChange, }: PhiDrawerControlProps): import("react").JSX.Element;
+export declare function PhiDrawerControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, placement, size, maxSize, resizable, push, zIndex, containerStyle, onDismiss, afterOpenChange, panelRef, }: PhiDrawerControlProps): import("react").JSX.Element;

package/components/controls/phi-drawer-control-adapter.js

@@ -12,7 +12,7 @@ const subscribeHydration = () => () => undefined;
 const PHI_DRAWER_HEADER_MIN_BLOCK_SIZE = `calc(var(--ant-control-height) + ${PHI_SPACE.xs} + ${PHI_SPACE.xs})`;
 /** Where a title starts when the close button stands before it: past the button, not beneath it. */
 const PHI_DRAWER_TITLE_AFTER_CLOSE = `calc(${PHI_SPACE.sm} + var(--ant-control-height) + ${PHI_SPACE.xs})`;
-export function PhiDrawerControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", placement = "right", size, maxSize, resizable = false, push = false, zIndex, containerStyle, onDismiss, afterOpenChange, }) {
+export function PhiDrawerControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", placement = "right", size, maxSize, resizable = false, push = false, zIndex, containerStyle, onDismiss, afterOpenChange, panelRef, }) {
     const hydrated = useSyncExternalStore(subscribeHydration, () => true, () => false);
     const resolvedMask = resolvePhiOverlayMaskPresentation(mask);
     const closeAtInlineStart = placement === "right";
@@ -71,5 +71,5 @@ export function PhiDrawerControlAdapter({ open, title, header, body, footer, clo
                 background: "transparent",
             },
             footer: { flex: "0 0 auto", padding: 0, background: "transparent" },
-        }, onClose: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, drawerRender: (node) => (_jsx("div", { style: { display: "flex", flexDirection: "column", blockSize: "100%", minBlockSize: 0 }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: _jsx("div", { "data-phi-drawer-body-content": "true", style: { display: "contents" }, children: body }) }));
+        }, onClose: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, drawerRender: (node) => (_jsx("div", { ref: panelRef, style: { display: "flex", flexDirection: "column", blockSize: "100%", minBlockSize: 0 }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: _jsx("div", { "data-phi-drawer-body-content": "true", style: { display: "contents" }, children: body }) }));
 }

package/components/controls/phi-image-control.d.ts

@@ -32,6 +32,11 @@ export type PhiImageControlProps = {
     loading?: "eager" | "lazy";
     /** Opens the picture larger over the page when clicked. */
     preview?: boolean;
+    /**
+     * Scales the picture to the viewport over the page when clicked, with nothing around it; another click
+     * closes it. The plain counterpart of `preview`, which brings the lightbox's tools.
+     */
+    zoom?: boolean;
     /** The box around the picture: size, corners, mask. */
     style?: CSSProperties;
     /** Added to the picture's own style after the framing. */
@@ -49,4 +54,4 @@ export type PhiImageControlProps = {
  *
  * `preview` hands the picture to `PhiLightboxImageControl`, the one place the lightbox lives.
  */
-export declare function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable, sizes, preload, loading, preview, style, imageStyle, }: PhiImageControlProps): import("react").JSX.Element | null;
+export declare function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable, sizes, preload, loading, preview, zoom, style, imageStyle, }: PhiImageControlProps): import("react").JSX.Element | null;

package/components/controls/phi-image-control.js

@@ -1,8 +1,9 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import NextImage from "next/image";
 import { useState } from "react";
 import { PhiLightboxImageControl } from "./phi-lightbox-image-control";
+import { PhiZoomImageOverlay } from "./phi-zoom-image-overlay";
 function toCssSize(value) {
     if (typeof value === "number" && Number.isFinite(value))
         return `${value}px`;
@@ -22,8 +23,9 @@ function toCssSize(value) {
  *
  * `preview` hands the picture to `PhiLightboxImageControl`, the one place the lightbox lives.
  */
-export function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable = false, sizes, preload = false, loading, preview = false, style, imageStyle, }) {
+export function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable = false, sizes, preload = false, loading, preview = false, zoom = false, style, imageStyle, }) {
     const [loadedUrl, setLoadedUrl] = useState(null);
+    const [zoomed, setZoomed] = useState(false);
     const url = presentation.url;
     if (!url) {
         return null;
@@ -40,8 +42,25 @@ export function PhiImageControl({ presentation, source, alt, title, width, heigh
         lineHeight: 0,
         overflow: presentation.simulatedCropStyle ? "hidden" : undefined,
         ...(loaded || blur ? {} : { backgroundColor: "var(--ant-color-fill-quaternary)" }),
+        ...(zoom ? { cursor: "zoom-in" } : {}),
         ...style,
     };
+    // The box is what is clicked: the picture itself may be `next/image`, which hands out no handler of ours.
+    const zoomTrigger = zoom
+        ? {
+            role: "button",
+            tabIndex: 0,
+            "aria-label": alt || title,
+            onClick: () => setZoomed(true),
+            onKeyDown: (event) => {
+                if (event.key !== "Enter" && event.key !== " ")
+                    return;
+                event.preventDefault();
+                setZoomed(true);
+            },
+        }
+        : {};
+    const zoomOverlay = zoom ? (_jsx(PhiZoomImageOverlay, { open: zoomed, src: url, alt: alt, title: title, onClose: () => setZoomed(false) })) : null;
     const pictureStyle = {
         objectFit: presentation.fit,
         objectPosition: presentation.objectPosition,
@@ -63,7 +82,7 @@ export function PhiImageControl({ presentation, source, alt, title, width, heigh
         return (_jsx("div", { style: boxStyle, children: _jsx(PhiLightboxImageControl, { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, style: pictureStyle }) }));
     }
     if (source !== "url" && numericWidth != null && numericHeight != null) {
-        return (_jsx("div", { style: boxStyle, children: _jsx(NextImage, { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, sizes: sizes?.trim() || undefined, unoptimized: !optimizable, placeholder: blur ? "blur" : undefined, blurDataURL: blur ?? undefined, preload: preload, loading: loading, onLoad: markLoaded, style: pictureStyle }) }));
+        return (_jsxs("div", { style: boxStyle, ...zoomTrigger, children: [_jsx(NextImage, { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, sizes: sizes?.trim() || undefined, unoptimized: !optimizable, placeholder: blur ? "blur" : undefined, blurDataURL: blur ?? undefined, preload: preload, loading: loading, onLoad: markLoaded, style: pictureStyle }), zoomOverlay] }));
     }
-    return (_jsx("div", { style: boxStyle, children: _jsx("img", { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, loading: loading ?? (preload ? "eager" : "lazy"), ref: noticeLoaded, onLoad: markLoaded, style: pictureStyle }) }));
+    return (_jsxs("div", { style: boxStyle, ...zoomTrigger, children: [_jsx("img", { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, loading: loading ?? (preload ? "eager" : "lazy"), ref: noticeLoaded, onLoad: markLoaded, style: pictureStyle }), zoomOverlay] }));
 }

package/components/controls/phi-lightbox-image-control-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { PhiLightboxImageControlProps } from "./phi-lightbox-image-control";
+export declare function PhiLightboxImageControlAdapter({ src, alt, title, width, height, style }: PhiLightboxImageControlProps): import("react").JSX.Element;

package/components/controls/phi-lightbox-image-control-adapter.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Ant Design's Image, behind `PhiLightboxImageControl`, which loads this file where a picture is drawn
+ * with its lightbox. The primitive brings its preview -- the overlay, the toolbar, zoom and rotation --
+ * whether or not a page shows one, so every page that draws a card or a picture would carry it.
+ */
+import { Image } from "antd";
+export function PhiLightboxImageControlAdapter({ src, alt, title, width, height, style }) {
+    return _jsx(Image, { alt: alt, src: src, title: title, width: width, height: height, style: style, preview: true });
+}

package/components/controls/phi-lightbox-image-control.d.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties } from "react";
+import { type CSSProperties } from "react";
 export type PhiLightboxImageControlProps = {
     src: string;
     alt: string;
@@ -12,5 +12,6 @@ export type PhiLightboxImageControlProps = {
  *
  * Only for that: an image that is just shown is an `<img>` or `next/image` in the Widget that places it.
  * The lightbox is what needs a primitive -- the overlay, the zoom, the close -- and so it is a Control.
+ * Until the primitive has loaded, the picture stands there plainly, at the same size.
  */
-export declare function PhiLightboxImageControl({ src, alt, title, width, height, style }: PhiLightboxImageControlProps): import("react").JSX.Element;
+export declare function PhiLightboxImageControl(props: PhiLightboxImageControlProps): import("react").JSX.Element;

package/components/controls/phi-lightbox-image-control.js

@@ -1,12 +1,16 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Image } from "antd";
+import { lazy, Suspense } from "react";
+const PhiLightboxImageControlAdapter = lazy(() => import("./phi-lightbox-image-control-adapter")
+    .then((module) => ({ default: module.PhiLightboxImageControlAdapter })));
 /**
  * An image that opens larger over the page when clicked.
  *
  * Only for that: an image that is just shown is an `<img>` or `next/image` in the Widget that places it.
  * The lightbox is what needs a primitive -- the overlay, the zoom, the close -- and so it is a Control.
+ * Until the primitive has loaded, the picture stands there plainly, at the same size.
  */
-export function PhiLightboxImageControl({ src, alt, title, width, height, style }) {
-    return _jsx(Image, { alt: alt, src: src, title: title, width: width, height: height, style: style, preview: true });
+export function PhiLightboxImageControl(props) {
+    const { src, alt, title, width, height, style } = props;
+    return (_jsx(Suspense, { fallback: _jsx("img", { alt: alt, src: src, title: title, width: width, height: height, style: style }), children: _jsx(PhiLightboxImageControlAdapter, { ...props }) }));
 }

package/components/controls/phi-modal-control-adapter.d.ts

@@ -1,2 +1,2 @@
 import type { PhiModalControlProps } from "./phi-modal-control";
-export declare function PhiModalControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, centered, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, }: PhiModalControlProps): import("react").JSX.Element;
+export declare function PhiModalControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, centered, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, panelRef, }: PhiModalControlProps): import("react").JSX.Element;

package/components/controls/phi-modal-control-adapter.js

@@ -56,7 +56,7 @@ const PHI_MODAL_TAB_STOP_SELECTOR = [
 /** About a second: a Form that loads its descriptor late still gets the focus, a slower one does not. */
 const PHI_MODAL_FIRST_FIELD_MAX_FRAMES = 60;
 const PHI_MODAL_HEADER_MIN_BLOCK_SIZE = `calc(${PHI_CONTROL.md} + ${PHI_SPACE.xs} + ${PHI_SPACE.xs})`;
-export function PhiModalControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", centered = false, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, }) {
+export function PhiModalControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", centered = false, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, panelRef, }) {
     const { token } = usePhiConfig();
     const hydrated = useSyncExternalStore(subscribeHydration, () => true, () => false);
     const mode = useSyncExternalStore(subscribeModalMode, readModalMode, readServerModalMode);
@@ -205,7 +205,10 @@ export function PhiModalControlAdapter({ open, title, header, body, footer, clos
                 padding: 0,
                 background: "transparent",
             },
-        }, onCancel: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, modalRender: (node) => (_jsxs("div", { ref: dialogRef, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: [node, _jsx("span", { tabIndex: 0, "data-phi-modal-focus-wrap": "true", style: { position: "fixed", inlineSize: 0, blockSize: 0, overflow: "hidden" }, onFocus: (event) => {
+        }, onCancel: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, modalRender: (node) => (_jsxs("div", { ref: (element) => {
+                dialogRef.current = element;
+                panelRef?.(element);
+            }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: [node, _jsx("span", { tabIndex: 0, "data-phi-modal-focus-wrap": "true", style: { position: "fixed", inlineSize: 0, blockSize: 0, overflow: "hidden" }, onFocus: (event) => {
                         const dialog = dialogRef.current;
                         if (dialog == null)
                             return;

package/components/controls/phi-overlay-control-contract.d.ts

@@ -19,6 +19,11 @@ export type PhiOverlayControlCommonProps = {
     containerStyle?: CSSProperties;
     onDismiss?: (source: PhiOverlayCloseSource) => void;
     afterOpenChange?: (open: boolean) => void;
+    /**
+     * The element the Overlay is drawn as, handed out while it is mounted -- what a Tour points at when it
+     * names the Overlay (design/TOURS.md, Visual-anchor registration). Never an Ant Design ref.
+     */
+    panelRef?: (element: HTMLElement | null) => void;
 };
 export declare const PHI_OVERLAY_DEFAULT_MASK: {
     readonly appearance: "normal";

package/components/controls/phi-pagination-control-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { PhiPaginationControlProps } from "./phi-pagination-control";
+export declare function PhiPaginationControlAdapter({ page, pageSize, total, disabled, readOnly, simple, showSizeChanger, pageSizeOptions, size, getPopupContainer, popupRootClassName, onPopupOpenChange, onChange, }: PhiPaginationControlProps): import("react").JSX.Element;

package/components/controls/phi-pagination-control-adapter.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Ant Design's Pagination, behind `PhiPaginationControl`, which loads this file where a list is drawn
+ * page by page. A Collection that shows everything at once -- a Dashboard's cards, a short Entry list --
+ * would otherwise carry the pager, its size changer and its Select all the same.
+ */
+import { Pagination } from "antd";
+export function PhiPaginationControlAdapter({ page, pageSize, total, disabled = false, readOnly = false, simple, showSizeChanger, pageSizeOptions, size, getPopupContainer, popupRootClassName, onPopupOpenChange, onChange, }) {
+    return (_jsx(Pagination, { current: page, pageSize: pageSize, total: total, disabled: disabled || readOnly, simple: simple, size: size, pageSizeOptions: pageSizeOptions ? [...pageSizeOptions] : undefined, showSizeChanger: showSizeChanger ? {
+            getPopupContainer,
+            classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined,
+            onOpenChange: onPopupOpenChange,
+        } : false, onChange: (nextPage, nextPageSize) => onChange?.({ page: nextPage, pageSize: nextPageSize, total }) }));
+}

package/components/controls/phi-pagination-control.d.ts

@@ -22,4 +22,5 @@ export type PhiPaginationControlProps = PhiPaginationControlValue & {
     onPopupOpenChange?: (open: boolean) => void;
     onChange?: (value: PhiPaginationControlValue) => void;
 };
-export declare function PhiPaginationControl({ page, pageSize, total, disabled, readOnly, simple, showSizeChanger, pageSizeOptions, size, getPopupContainer, popupRootClassName, onPopupOpenChange, onChange, }: PhiPaginationControlProps): import("react").JSX.Element;
+/** The pager. Until the primitive has loaded, its row is held at the height it will take. */
+export declare function PhiPaginationControl(props: PhiPaginationControlProps): import("react").JSX.Element;

package/components/controls/phi-pagination-control.js

@@ -1,10 +1,14 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Pagination } from "antd";
-export function PhiPaginationControl({ page, pageSize, total, disabled = false, readOnly = false, simple, showSizeChanger, pageSizeOptions, size, getPopupContainer, popupRootClassName, onPopupOpenChange, onChange, }) {
-    return (_jsx(Pagination, { current: page, pageSize: pageSize, total: total, disabled: disabled || readOnly, simple: simple, size: size, pageSizeOptions: pageSizeOptions ? [...pageSizeOptions] : undefined, showSizeChanger: showSizeChanger ? {
-            getPopupContainer,
-            classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined,
-            onOpenChange: onPopupOpenChange,
-        } : false, onChange: (nextPage, nextPageSize) => onChange?.({ page: nextPage, pageSize: nextPageSize, total }) }));
+import { lazy, Suspense } from "react";
+import { usePhiConfig } from "../root/phi-config-provider";
+const PhiPaginationControlAdapter = lazy(() => import("./phi-pagination-control-adapter")
+    .then((module) => ({ default: module.PhiPaginationControlAdapter })));
+/** The pager. Until the primitive has loaded, its row is held at the height it will take. */
+export function PhiPaginationControl(props) {
+    const { token } = usePhiConfig();
+    const height = props.size === "small"
+        ? token.controlHeightSM
+        : props.size === "large" ? token.controlHeightLG : token.controlHeight;
+    return (_jsx(Suspense, { fallback: _jsx("div", { style: { minHeight: height } }), children: _jsx(PhiPaginationControlAdapter, { ...props }) }));
 }

package/components/controls/phi-table-control.d.ts

@@ -122,6 +122,11 @@ export type PhiTableControlProps<TRow extends Record<string, unknown>> = {
     bordered?: boolean;
     striped?: boolean;
     showHeader?: boolean;
+    /**
+     * The header row stays at the top while the rows scroll under it: under the Shell's Header on a page,
+     * at the top edge of a Modal's or Drawer's body. `styles/controls.css` places it.
+     */
+    stickyHeader?: boolean;
     footer?: PhiTableControlFooter;
     summary?: PhiTableControlSummary;
     size?: PhiControlSize;
@@ -141,4 +146,4 @@ export type PhiTableControlProps<TRow extends Record<string, unknown>> = {
     onExternalDrop?: (event: DragEvent<HTMLDivElement>) => void;
 };
 export declare function readPhiTableControlValue(row: Record<string, unknown>, path: string): unknown;
-export declare function PhiTableControl<TRow extends Record<string, unknown>>({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering, onColumnOrderChange, rowSelection, pagination, tree, rowReordering, editing, loading, bordered, striped, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }: PhiTableControlProps<TRow>): import("react").JSX.Element;
+export declare function PhiTableControl<TRow extends Record<string, unknown>>({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering, onColumnOrderChange, rowSelection, pagination, tree, rowReordering, editing, loading, bordered, striped, stickyHeader, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }: PhiTableControlProps<TRow>): import("react").JSX.Element;

package/components/controls/phi-table-control.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePhiShellStickyTop } from "../shell/use-phi-shell-sticky-top";
 import { Button, Flex, Table } from "antd";
 import { DndContext, KeyboardSensor, PointerSensor, closestCenter, useSensor, useSensors, } from "@dnd-kit/core";
 import { SortableContext, sortableKeyboardCoordinates, useSortable, } from "@dnd-kit/sortable";
@@ -7,7 +8,7 @@ import { CSS } from "@dnd-kit/utilities";
 import { flushSync } from "react-dom";
 import { Children, cloneElement, createContext, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { PHI_GREGORY_CALENDAR_ADAPTER_KEY } from "../../types/calendar-keys";
-import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/tours";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/visual-anchors";
 import { PhiColorControl } from "./phi-color-control";
 import { PhiCheckboxControl } from "./phi-checkbox-control";
 import { PhiCheckboxGroupControl } from "./phi-checkbox-group-control";
@@ -354,7 +355,7 @@ function buildRowMove(rows, rowIdentityPath, parentRowIdentityPath, movedRowIden
         afterRowIdentity: placement === "after" ? targetRowIdentity : null,
     };
 }
-export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering = false, onColumnOrderChange, rowSelection, pagination = false, tree, rowReordering, editing, loading = false, bordered, striped = false, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }) {
+export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering = false, onColumnOrderChange, rowSelection, pagination = false, tree, rowReordering, editing, loading = false, bordered, striped = false, stickyHeader = false, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }) {
     const { token } = usePhiConfig();
     const [editingRowIdentityState, setEditingRowIdentity] = useState(null);
     const [rowEditPatch, setRowEditPatch] = useState({});
@@ -988,6 +989,8 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
     const hasClosingBlock = !loading &&
         (Boolean(footer) || (summary != null && summary.placement !== "sticky-top"));
     const frameRef = useRef(null);
+    // Where the Shell's Header ends, which is where a sticky header row stops (`styles/controls.css`).
+    usePhiShellStickyTop({ active: stickyHeader && showHeader !== false, elementRef: frameRef });
     const [headerBox, setHeaderBox] = useState(null);
     useEffect(() => {
         const frame = frameRef.current;
@@ -1007,11 +1010,15 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
         observer.observe(frame);
         return () => observer.disconnect();
     }, [showHeader, loading]);
-    const table = (_jsx(Table, { className: ["phi-table-control", hasClosingBlock ? "phi-table-control--closing-block" : null]
+    const table = (_jsx(Table, { className: [
+            "phi-table-control",
+            hasClosingBlock ? "phi-table-control--closing-block" : null,
+            stickyHeader && showHeader !== false ? "phi-table-control--sticky-header" : null,
+        ]
             .filter(Boolean)
             .join(" "), style: { "--phi-table-striped-row-background": token.colorFillAlter }, rowKey: (row) => loading
             ? `__phi_table_loading_${String(row[PHI_TABLE_LOADING_ROW])}`
-            : String(readIdentity(row, rowIdentityPath)), columns: renderedColumns, dataSource: loading ? loadingRows : dataSource, bordered: bordered, showHeader: showHeader, tableLayout: layout.mode, size: size, rowClassName: (_row, index) => striped && index % 2 === 1 ? "phi-table-control__row--striped" : "", rowSelection: loading ? undefined : antdRowSelection, components: rowReordering?.enabled && !loading ? { body: { row: PhiTableSortableRow } } : undefined, scroll: layout.overflowX === "auto" ? { x: true } : undefined, pagination: pagination === false ? false : {
+            : String(readIdentity(row, rowIdentityPath)), columns: renderedColumns, dataSource: loading ? loadingRows : dataSource, bordered: bordered, showHeader: showHeader, tableLayout: layout.mode, size: size, rowClassName: (_row, index) => striped && index % 2 === 1 ? "phi-table-control__row--striped" : "", rowSelection: loading ? undefined : antdRowSelection, components: rowReordering?.enabled && !loading ? { body: { row: PhiTableSortableRow } } : undefined, scroll: layout.overflowX === "auto" ? { x: true } : undefined, sticky: stickyHeader && showHeader !== false ? true : undefined, pagination: pagination === false ? false : {
             ...{ [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "pagination" },
             current: pagination.page,
             pageSize: pagination.pageSize,
@@ -1097,7 +1104,12 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                     insertionGapIndex,
                     insertionGapHeight: activeDragRowHeight,
                 }, children: table }) }) })) : table;
-    const constrainedTable = (_jsxs("div", { ref: frameRef, style: { position: "relative", width: "100%", maxWidth: "100%", minWidth: 0, overflow: "hidden" }, children: [renderedTable, headerBox ? (_jsx("div", { "aria-hidden": true, [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "header", style: { position: "absolute", left: 0, right: 0, top: headerBox.top, height: headerBox.height, pointerEvents: "none" } })) : null] }));
+    /*
+     * Clipped, not hidden: `hidden` makes the frame a scroll container, and a sticky header row then sticks
+     * to the frame's own top -- pushed down inside the Table by the Shell's Header height -- instead of to
+     * the page. `clip` cuts off the same overflow and leaves the page the one that scrolls.
+     */
+    const constrainedTable = (_jsxs("div", { ref: frameRef, style: { position: "relative", width: "100%", maxWidth: "100%", minWidth: 0, overflow: "clip" }, children: [renderedTable, headerBox ? (_jsx("div", { "aria-hidden": true, [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "header", style: { position: "absolute", left: 0, right: 0, top: headerBox.top, height: headerBox.height, pointerEvents: "none" } })) : null] }));
     return onExternalDragOver || onExternalDrop ? (_jsx("div", { onDragOver: (event) => {
             if (event.defaultPrevented) {
                 setExternalAppendActive(false);

package/components/controls/phi-timeline-control-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { PhiTimelineControlProps } from "./phi-timeline-control";
+export declare function PhiTimelineControlAdapter({ items, placement, ariaLabel, }: PhiTimelineControlProps): import("react").JSX.Element;

package/components/controls/phi-timeline-control-adapter.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Ant Design's Timeline, behind `PhiTimelineControl`, which loads this file where a Timeline is drawn.
+ */
+import { Timeline } from "antd";
+import { PHI_COLOR } from "../../theme/antd-css-var-contract";
+import { PhiIcon } from "../shell/phi-icon";
+/*
+ * Ant Design colours four marks by name and takes anything else as a CSS colour. The Theme's own tokens
+ * go in as that colour, so a tone follows the Theme the way a text tone does.
+ */
+const PHI_TIMELINE_TONE_COLOR = {
+    secondary: PHI_COLOR.textTertiary,
+    success: PHI_COLOR.success,
+    warning: PHI_COLOR.warning,
+    danger: PHI_COLOR.error,
+};
+export function PhiTimelineControlAdapter({ items, placement = "start", ariaLabel, }) {
+    return (_jsx(Timeline, { "aria-label": ariaLabel, mode: placement, items: items.map((item) => ({
+            key: item.key,
+            title: item.title && item.time ? `${item.time} · ${item.title}` : item.title ?? item.time,
+            content: item.content,
+            icon: item.icon ? _jsx(PhiIcon, { name: item.icon, size: "inherit" }) : undefined,
+            color: item.tone ? PHI_TIMELINE_TONE_COLOR[item.tone] : undefined,
+            loading: item.pending,
+        })) }));
+}

package/components/controls/phi-timeline-control.d.ts

@@ -28,5 +28,7 @@ export type PhiTimelineControlProps = {
  * a Timeline here is a record a Widget stores or a Module reads, so its entries are words and tones.
  * The time stands in Ant Design's title column when the entry has no title of its own, and in front of
  * the title otherwise -- one column, so that `alternate` still has a side to put it on.
+ *
+ * Until the primitive has loaded, the entries stand there as a plain list, in the same words.
  */
-export declare function PhiTimelineControl({ items, placement, ariaLabel, }: PhiTimelineControlProps): import("react").JSX.Element;
+export declare function PhiTimelineControl(props: PhiTimelineControlProps): import("react").JSX.Element;

package/components/controls/phi-timeline-control.js

@@ -1,18 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Timeline } from "antd";
-import { PHI_COLOR } from "../../theme/antd-css-var-contract";
-import { PhiIcon } from "../shell/phi-icon";
-/*
- * Ant Design colours four marks by name and takes anything else as a CSS colour. The Theme's own tokens
- * go in as that colour, so a tone follows the Theme the way a text tone does.
- */
-const PHI_TIMELINE_TONE_COLOR = {
-    secondary: PHI_COLOR.textTertiary,
-    success: PHI_COLOR.success,
-    warning: PHI_COLOR.warning,
-    danger: PHI_COLOR.error,
-};
+import { lazy, Suspense } from "react";
+const PhiTimelineControlAdapter = lazy(() => import("./phi-timeline-control-adapter")
+    .then((module) => ({ default: module.PhiTimelineControlAdapter })));
 /**
  * What happened, in order: a ticket's history, the revisions of a Page, the stages of an order.
  *
@@ -20,14 +10,10 @@ const PHI_TIMELINE_TONE_COLOR = {
  * a Timeline here is a record a Widget stores or a Module reads, so its entries are words and tones.
  * The time stands in Ant Design's title column when the entry has no title of its own, and in front of
  * the title otherwise -- one column, so that `alternate` still has a side to put it on.
+ *
+ * Until the primitive has loaded, the entries stand there as a plain list, in the same words.
  */
-export function PhiTimelineControl({ items, placement = "start", ariaLabel, }) {
-    return (_jsx(Timeline, { "aria-label": ariaLabel, mode: placement, items: items.map((item) => ({
-            key: item.key,
-            title: item.title && item.time ? `${item.time} · ${item.title}` : item.title ?? item.time,
-            content: item.content,
-            icon: item.icon ? _jsx(PhiIcon, { name: item.icon, size: "inherit" }) : undefined,
-            color: item.tone ? PHI_TIMELINE_TONE_COLOR[item.tone] : undefined,
-            loading: item.pending,
-        })) }));
+export function PhiTimelineControl(props) {
+    const fallback = (_jsx("ol", { "aria-label": props.ariaLabel, style: { listStyle: "none", margin: 0, padding: 0 }, children: props.items.map((item) => (_jsx("li", { children: [item.time, item.title, item.content].filter(Boolean).join(" · ") }, item.key))) }));
+    return (_jsx(Suspense, { fallback: fallback, children: _jsx(PhiTimelineControlAdapter, { ...props }) }));
 }

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

@@ -1,10 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { Tour } from "antd";
-function prefersReducedMotion() {
-    return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
-}
+import { PhiCompactGroupControl } from "./phi-compact-group-control";
+import { bringPhiTourTargetIntoView, resolvePhiTourScrollBehavior, resolvePhiTourScrollBlock, } from "./phi-tour-viewport";
 /**
  * A guided Tour's presentation, and the only place Ant Design `Tour` is used.
  *
@@ -22,8 +21,27 @@ export function PhiTourControl({ open, current, steps, labels, mask = true, disa
         // Ant Design types the getter as one that always finds its element; a target can leave mid-step.
         target: (step.target ?? null),
         placement: step.target ? step.placement : undefined,
-        prevButtonProps: { children: labels.previous },
-        nextButtonProps: { children: index === steps.length - 1 ? labels.finish : labels.next },
+        // Ant Design spaces the two buttons apart; joined, the seam between them is drawn once instead.
+        prevButtonProps: { children: labels.previous, style: { marginInlineStart: 0 } },
+        nextButtonProps: { children: index === steps.length - 1 ? labels.finish : labels.next, style: { marginInlineStart: 0 } },
     })), [labels.finish, labels.next, labels.previous, steps]);
-    return (_jsx(Tour, { open: open && steps.length > 0, current: current, steps: tourSteps, mask: mask, disabledInteraction: disabledInteraction, keyboard: true, scrollIntoViewOptions: { block: "center", behavior: prefersReducedMotion() ? "auto" : "smooth" }, onChange: onStepChange, onClose: onClose, onFinish: onFinish }));
+    /*
+     * The shown step scrolls the way its Controller already brought it in (`phi-tour-viewport.ts`): Ant
+     * Design scrolls again whenever the target is not wholly inside the window, which a tall one never is,
+     * and the same alignment under the same scroll padding lands where the target already stands.
+     */
+    const shownTarget = open ? steps[current]?.target?.() ?? null : null;
+    const shownSteps = shownTarget
+        ? tourSteps.map((step, index) => index === current
+            ? { ...step, scrollIntoViewOptions: { block: resolvePhiTourScrollBlock(shownTarget), inline: "nearest", behavior: resolvePhiTourScrollBehavior() } }
+            : step)
+        : tourSteps;
+    // A target under a sticky band is inside the window, so Ant Design leaves it there; this brings it out.
+    useEffect(() => {
+        if (shownTarget)
+            bringPhiTourTargetIntoView(shownTarget, resolvePhiTourScrollBehavior());
+    }, [current, shownTarget]);
+    return (_jsx(Tour, { open: open && steps.length > 0, current: current, steps: shownSteps, mask: mask, disabledInteraction: disabledInteraction, keyboard: true, 
+        // Previous and Next as one bar: two steps of one way through, not two separate commands.
+        actionsRender: (actions) => _jsx(PhiCompactGroupControl, { size: "small", children: actions }), scrollIntoViewOptions: { block: "center", behavior: resolvePhiTourScrollBehavior() }, onChange: onStepChange, onClose: onClose, onFinish: onFinish }));
 }

package/components/controls/phi-tour-viewport.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export declare function resolvePhiTourScrollBehavior(): ScrollBehavior;
+/**
+ * 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 declare function resolvePhiTourScrollBlock(target: HTMLElement, cover?: number): Extract<ScrollLogicalPosition, "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 declare function holdPhiTourViewport(target: HTMLElement): number;
+/**
+ * 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 declare function bringPhiTourTargetIntoView(target: HTMLElement, behavior: ScrollBehavior): boolean;
+/** The window's scroll padding as it was before a Tour set it. */
+export declare function releasePhiTourViewport(): void;