@phis/ui 0.2.1 → 0.4.0

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

@@ -37,13 +37,32 @@ const PHI_MODAL_WIDTH_BY_CONTROL_SIZE = {
     medium: 720,
     large: 960,
 };
+/** What a dialog opens on: the first thing to type into or choose from, never a button or a hint. */
+const PHI_MODAL_FIRST_FIELD_SELECTOR = [
+    "input:not([type=hidden]):not(:disabled)",
+    "textarea:not(:disabled)",
+    "select:not(:disabled)",
+    "[contenteditable=true]",
+].join(", ");
+const PHI_MODAL_TAB_STOP_SELECTOR = [
+    "a[href]",
+    "button:not(:disabled)",
+    "input:not([type=hidden]):not(:disabled)",
+    "textarea:not(:disabled)",
+    "select:not(:disabled)",
+    "[contenteditable=true]",
+    "[tabindex]:not([tabindex='-1'])",
+].join(", ");
+/** 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);
     const bodyMeasureRef = useRef(null);
     const bodyContentRef = useRef(null);
+    const dialogRef = useRef(null);
     const resizeAnimationRef = useRef(null);
     useEffect(() => {
         const bodyMeasure = bodyMeasureRef.current;
@@ -87,6 +106,41 @@ export function PhiModalControlAdapter({ open, title, header, body, footer, clos
             resizeAnimationRef.current = null;
         };
     }, [open, size?.height, token.motionDurationMid, token.motionEaseInOut]);
+    /*
+     * Ant Design's lock moves the focus to the first focusable element, which is the close button, so a
+     * dialog with a Form could not be typed into until Tab was pressed. The field may mount a few frames
+     * late, and once the person has pressed a key or the pointer the focus is theirs.
+     */
+    useEffect(() => {
+        if (!open)
+            return undefined;
+        let frame = 0;
+        let frames = 0;
+        let settled = false;
+        const settle = () => { settled = true; };
+        window.addEventListener("keydown", settle, true);
+        window.addEventListener("pointerdown", settle, true);
+        const tryFocus = () => {
+            if (settled)
+                return;
+            const content = bodyContentRef.current;
+            const field = content?.querySelector(PHI_MODAL_FIRST_FIELD_SELECTOR);
+            if (field != null && !content?.contains(document.activeElement)) {
+                field.focus({ preventScroll: true });
+            }
+            if (field != null || content?.contains(document.activeElement))
+                return;
+            frames += 1;
+            if (frames < PHI_MODAL_FIRST_FIELD_MAX_FRAMES)
+                frame = window.requestAnimationFrame(tryFocus);
+        };
+        frame = window.requestAnimationFrame(tryFocus);
+        return () => {
+            window.cancelAnimationFrame(frame);
+            window.removeEventListener("keydown", settle, true);
+            window.removeEventListener("pointerdown", settle, true);
+        };
+    }, [open]);
     const resolvedMask = resolvePhiOverlayMaskPresentation(mask);
     const renderedTitle = header == null ? title : (_jsxs("div", { style: {
             display: "grid",
@@ -151,7 +205,18 @@ export function PhiModalControlAdapter({ open, title, header, body, footer, clos
                 padding: 0,
                 background: "transparent",
             },
-        }, onCancel: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, modalRender: (node) => (_jsx("div", { onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: _jsx("div", { ref: bodyMeasureRef, "data-phi-modal-body-measure": "true", style: {
+        }, 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;
+                        const stops = [...dialog.querySelectorAll(PHI_MODAL_TAB_STOP_SELECTOR)]
+                            .filter((stop) => stop !== event.currentTarget && stop.checkVisibility());
+                        const forward = event.relatedTarget instanceof Node && dialog.contains(event.relatedTarget);
+                        (forward ? stops[0] : stops[stops.length - 1])?.focus({ preventScroll: true });
+                    } })] })), children: _jsx("div", { ref: bodyMeasureRef, "data-phi-modal-body-measure": "true", style: {
                 minWidth: 0,
                 overflow: "hidden",
                 width: "100%",

package/components/controls/phi-multi-select-control.js

@@ -3,8 +3,9 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Select } from "antd";
 import { PhiControlOptionContent } from "./phi-control-option-content";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 export function PhiMultiSelectControl({ id, value, label, description, placeholder, disabled, readOnly, allowCustom, allowClear, options, maxTagCount, size, variant, popupMatchSelectWidth = false, style, onFocus, onBlur, onChange, }) {
+    const { labelId, labelledBy } = usePhiControlLabel(label);
     const selectOptions = useMemo(() => options.map((option) => ({
         value: option.value,
         // Keep labels non-primitive so rc-select cannot add native HTML titles.
@@ -13,14 +14,20 @@ export function PhiMultiSelectControl({ id, value, label, description, placehold
         option,
         disabled: option.disabled,
     })), [options]);
-    const control = (_jsx(Select, { id: id, mode: allowCustom ? "tags" : "multiple", allowClear: allowClear, value: [...(value ?? [])], placeholder: placeholder, disabled: disabled || readOnly || !onChange, options: selectOptions, optionFilterProp: ["searchLabel", "value"], optionRender: (option) => {
+    const control = (_jsx(Select, { id: id, "aria-labelledby": labelledBy, mode: allowCustom ? "tags" : "multiple", allowClear: allowClear, value: [...(value ?? [])], placeholder: placeholder, disabled: disabled || readOnly || !onChange, options: selectOptions, optionFilterProp: ["searchLabel", "value"], optionRender: (option) => {
+            /*
+             * With `allowCustom` the Select offers what is being typed as an option of its own, and that one
+             * carries no Phi option: it is a value nobody declared yet, drawn as the text it is.
+             */
             const item = option.data.option;
-            return _jsx(PhiControlOptionContent, { option: item, presentation: "dropdown" });
+            return item
+                ? _jsx(PhiControlOptionContent, { option: item, presentation: "dropdown" })
+                : _jsx(_Fragment, { children: String(option.value ?? "") });
         }, labelRender: (selectedOption) => {
             const selected = options.find((option) => option.value === selectedOption.value);
             return selected
                 ? _jsx(PhiControlOptionContent, { option: selected, presentation: "selection" })
                 : selectedOption.label;
         }, maxTagCount: maxTagCount, popupMatchSelectWidth: popupMatchSelectWidth, size: size, variant: variant, onFocus: onFocus, onBlur: onBlur, onChange: onChange, style: style }));
-    return _jsx(PhiLabeledControl, { label: label, description: description, fill: style?.width === "100%", children: control });
+    return _jsx(PhiLabeledControl, { label: label, labelId: labelId, description: description, fill: style?.width === "100%", children: control });
 }

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

@@ -2,13 +2,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { InputNumber } from "antd";
 import { PHI_LAYOUT } from "../../theme/phi-tokens";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 export function PhiNumberControl({ id, value, label, prefix, placeholder, min, max, step, precision, disabled, readOnly, size, variant, style, onChange, onBlur, onKeyDown, }) {
-    const control = (_jsx(InputNumber, { id: id, value: value, prefix: prefix, placeholder: placeholder, min: min, max: max, step: step, precision: precision, disabled: disabled || (!onChange && !readOnly), readOnly: readOnly, size: size, variant: variant, 
+    const { labelId, labelledBy } = usePhiControlLabel(label);
+    const control = (_jsx(InputNumber, { id: id, "aria-labelledby": labelledBy, value: value, prefix: prefix, placeholder: placeholder, min: min, max: max, step: step, precision: precision, disabled: disabled || (!onChange && !readOnly), readOnly: readOnly, size: size, variant: variant, 
         /*
          * The ceiling first, so a caller's own `maxWidth` replaces it rather than fighting it. A field
          * that needs to be wider than a number ever is says so, and says it in one place.
          */
         style: { maxWidth: PHI_LAYOUT.numberControlMax, ...style }, onChange: onChange, onBlur: onBlur, onKeyDown: onKeyDown }));
-    return _jsx(PhiLabeledControl, { label: label, fill: style?.width === "100%", children: control });
+    return _jsx(PhiLabeledControl, { label: label, labelId: labelId, fill: style?.width === "100%", children: control });
 }

package/components/controls/phi-options-provider.js

@@ -1,4 +1,5 @@
 "use client";
+import { readPhiDotPath } from "../../helpers/dot-path";
 import { createContext, createElement, useContext, useEffect, useEffectEvent, useMemo, useState, useSyncExternalStore, } from "react";
 import { isPhiRuntimeDataProviderKey, } from "../../types/runtime-data-provider";
 const EMPTY_OPTIONS_PROVIDER_REGISTRY = new Map();
@@ -62,9 +63,7 @@ export function resolvePhiControlOptionsDependencies(dependencies, sources) {
     let satisfied = true;
     for (const dependency of dependencies) {
         const source = dependency.source === "form" ? sources.form : sources.config;
-        const value = dependency.valuePath.split(".").filter(Boolean).reduce((current, segment) => current && typeof current === "object" && !Array.isArray(current)
-            ? current[segment]
-            : undefined, source ?? undefined);
+        const value = readPhiDotPath(source ?? undefined, dependency.valuePath);
         // An empty string is no value: a cleared select reports one, and asking the route with it would
         // narrow to nothing rather than to the parent that is missing.
         const present = value != null && value !== "";
@@ -80,9 +79,7 @@ export function readPhiControlOptionsProviderSourceValue(context, paramKey) {
     if (!path) {
         return undefined;
     }
-    return path.split(".").filter(Boolean).reduce((current, segment) => current && typeof current === "object" && !Array.isArray(current)
-        ? current[segment]
-        : undefined, context.sourceConfig);
+    return readPhiDotPath(context.sourceConfig, path);
 }
 function subscribeEmptyProvider() {
     return () => undefined;

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

@@ -2,10 +2,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useImperativeHandle, useRef } from "react";
 import { Input } from "antd";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 const DIGITS_ONLY = /\D/gu;
 const NOT_ALPHANUMERIC = /[^0-9a-zA-Z]/gu;
 export function PhiOtpControl({ value, label, description, ariaLabel, length = 6, characters = "digits", mask, disabled = false, readOnly = false, autoFocus, size, variant, onChange, onComplete, onFocus, onBlur, handleRef, }) {
+    const { labelId, labelledBy } = usePhiControlLabel(label, ariaLabel);
     const otpRef = useRef(null);
     useImperativeHandle(handleRef, () => ({
         focus: () => otpRef.current?.focus(),
@@ -17,12 +18,12 @@ export function PhiOtpControl({ value, label, description, ariaLabel, length = 6
         if (autoFocus && !disabled)
             otpRef.current?.focus();
     }, [autoFocus, disabled]);
-    const control = (_jsx(Input.OTP, { ref: otpRef, "aria-label": ariaLabel, length: length, mask: mask, size: size, variant: variant, disabled: disabled || (!onChange && !onComplete && !readOnly), autoComplete: "one-time-code", inputMode: characters === "digits" ? "numeric" : "text", formatter: (next) => next.replace(characters === "digits" ? DIGITS_ONLY : NOT_ALPHANUMERIC, ""), value: value ?? "", onInput: (cells) => {
+    const control = (_jsx(Input.OTP, { ref: otpRef, "aria-label": ariaLabel, "aria-labelledby": labelledBy, length: length, mask: mask, size: size, variant: variant, disabled: disabled || (!onChange && !onComplete && !readOnly), autoComplete: "one-time-code", inputMode: characters === "digits" ? "numeric" : "text", formatter: (next) => next.replace(characters === "digits" ? DIGITS_ONLY : NOT_ALPHANUMERIC, ""), value: value ?? "", onInput: (cells) => {
             if (!readOnly)
                 onChange?.(cells.join(""));
         }, onChange: (complete) => {
             if (!readOnly)
                 onComplete?.(complete);
         }, onFocus: onFocus ? () => onFocus() : undefined, onBlur: onBlur ? () => onBlur() : undefined }));
-    return _jsx(PhiLabeledControl, { label: label, description: description, children: control });
+    return _jsx(PhiLabeledControl, { label: label, labelId: labelId, description: description, children: control });
 }

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

@@ -1,6 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { PhiCmsMountPolicy } from "../../types/cms-mount-policy";
-import type { PhiCmsOverlayMaskConfig, PhiCmsOverlaySize, PhiOverlayCloseSource } from "../../types/cms-overlay";
+import type { PhiCmsOverlaySize, PhiOverlayCloseSource, PhiOverlayMaskBehaviour } from "../../types/cms-overlay";
 import { type PhiResolvedResponsiveValue, type PhiResponsiveValue } from "../../types/responsive";
 export type PhiOverlayControlDismissEvent = {
     target: EventTarget | null;
@@ -14,11 +14,16 @@ export type PhiOverlayControlCommonProps = {
     footer?: ReactNode;
     closable?: boolean;
     keyboard?: boolean;
-    mask?: PhiCmsOverlayMaskConfig;
+    mask?: PhiOverlayMaskBehaviour;
     mountPolicy?: PhiCmsMountPolicy;
     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";
@@ -36,7 +41,7 @@ export declare const PHI_OVERLAY_DEFAULT_MASK: {
  * Modal stands in a wrapper that covers the viewport and takes the outside click itself, so a Modal that
  * lets the pointer through has to open that wrapper too -- the mask style alone left it a wall.
  */
-export declare function resolvePhiOverlayMaskPresentation(mask: PhiCmsOverlayMaskConfig): {
+export declare function resolvePhiOverlayMaskPresentation(mask: PhiOverlayMaskBehaviour): {
     capturesOutsidePointer: boolean;
     adapterMask: {
         enabled: boolean;

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

@@ -1,8 +1,6 @@
 import { type PhiCmsPaddingWidgetConfig } from "../../types/cms-config";
 import { type PhiPaddingWidgetLabels } from "../widgets/label-types/padding";
 import type { PhiWidgetControlMode } from "../../types/widget-ui";
-import { type PhiSpacingScaleKey } from "../widgets/config/spacing-options";
-export type PhiPaddingScaleKey = PhiSpacingScaleKey;
 export type PhiPaddingControlProps = {
     value?: PhiCmsPaddingWidgetConfig | null;
     config?: PhiCmsPaddingWidgetConfig | null;

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

@@ -7,14 +7,12 @@ import { PHI_PADDING_WIDGET_DEFAULT_LABELS, } from "../widgets/label-types/paddi
 import { usePhiConfig } from "../root/phi-config-provider";
 import { PhiLabeledControl } from "./phi-labeled-control";
 import { PHI_SPACING_SCALE_KEYS, resolvePhiSpacingScaleKey, resolvePhiSpacingScaleValue, } from "../widgets/config/spacing-options";
-function resolvePaddingScaleValue(key, value) {
-    return resolvePhiSpacingScaleValue(value, key === "gap" ? "margin" : "padding");
-}
-function normalizePaddingScaleKey(value, family) {
-    return resolvePhiSpacingScaleKey(value, family);
+function normalizePaddingScaleKey(value) {
+    return resolvePhiSpacingScaleKey(value);
 }
 function resolveNextPadding(currentValue, key, value) {
-    const nextValue = resolvePaddingScaleValue(key, value);
+    // A padding and a gap are steps of the same scale (theme/phi-tokens.ts).
+    const nextValue = resolvePhiSpacingScaleValue(value);
     const nextPadding = {
         ...(currentValue ?? {}),
         [key]: nextValue ?? undefined,
@@ -47,8 +45,8 @@ function renderPaddingGridCell(content, style) {
             ...style,
         }, children: content }));
 }
-function renderPaddingInput(label, value, family, disabled, options, onChange) {
-    return (_jsx(PhiLabeledControl, { description: label, fill: true, children: _jsx(Select, { "aria-label": label, disabled: disabled, value: normalizePaddingScaleKey(value, family) ?? "none", onChange: onChange, options: [...options], style: { width: "100%", minWidth: 0 } }) }));
+function renderPaddingInput(label, value, disabled, options, onChange) {
+    return (_jsx(PhiLabeledControl, { description: label, fill: true, children: _jsx(Select, { "aria-label": label, disabled: disabled, value: normalizePaddingScaleKey(value) ?? "none", onChange: onChange, options: [...options], style: { width: "100%", minWidth: 0 } }) }));
 }
 export function PhiPaddingControl({ value, config, disabled = false, mode = "control", labels = PHI_PADDING_WIDGET_DEFAULT_LABELS, showGap = true, onChange, }) {
     const { token } = usePhiConfig();
@@ -68,25 +66,25 @@ export function PhiPaddingControl({ value, config, disabled = false, mode = "con
             gap: token.paddingXS,
             width: "100%",
             alignItems: "stretch",
-        }, children: [renderPaddingGridCell(null), renderPaddingInput(labels.fields.top, resolvedDisplayValue?.paddingTop ?? resolvedDisplayValue?.padding, "padding", isDisabled, scaleOptions, (next) => {
+        }, children: [renderPaddingGridCell(null), renderPaddingInput(labels.fields.top, resolvedDisplayValue?.paddingTop ?? resolvedDisplayValue?.padding, isDisabled, scaleOptions, (next) => {
                 const nextPadding = resolveNextPadding(resolvedDisplayValue, "paddingTop", next);
                 setDisplayState({ source: currentValue, value: nextPadding });
                 emit(nextPadding);
-            }), renderPaddingGridCell(null), renderPaddingInput(labels.fields.left, resolvedDisplayValue?.paddingLeft ?? resolvedDisplayValue?.padding, "padding", isDisabled, scaleOptions, (next) => {
+            }), renderPaddingGridCell(null), renderPaddingInput(labels.fields.left, resolvedDisplayValue?.paddingLeft ?? resolvedDisplayValue?.padding, isDisabled, scaleOptions, (next) => {
                 const nextPadding = resolveNextPadding(resolvedDisplayValue, "paddingLeft", next);
                 setDisplayState({ source: currentValue, value: nextPadding });
                 emit(nextPadding);
             }), showGap
-                ? renderPaddingInput(labels.fields.gap, resolvedGapValue, "margin", isDisabled, scaleOptions, (next) => {
+                ? renderPaddingInput(labels.fields.gap, resolvedGapValue, isDisabled, scaleOptions, (next) => {
                     const nextPadding = resolveNextPadding(resolvedDisplayValue, "gap", next);
                     setDisplayState({ source: currentValue, value: nextPadding });
                     emit(nextPadding);
                 })
-                : renderPaddingGridCell(null), renderPaddingInput(labels.fields.right, resolvedDisplayValue?.paddingRight ?? resolvedDisplayValue?.padding, "padding", isDisabled, scaleOptions, (next) => {
+                : renderPaddingGridCell(null), renderPaddingInput(labels.fields.right, resolvedDisplayValue?.paddingRight ?? resolvedDisplayValue?.padding, isDisabled, scaleOptions, (next) => {
                 const nextPadding = resolveNextPadding(resolvedDisplayValue, "paddingRight", next);
                 setDisplayState({ source: currentValue, value: nextPadding });
                 emit(nextPadding);
-            }), renderPaddingGridCell(null), renderPaddingInput(labels.fields.bottom, resolvedDisplayValue?.paddingBottom ?? resolvedDisplayValue?.padding, "padding", isDisabled, scaleOptions, (next) => {
+            }), renderPaddingGridCell(null), renderPaddingInput(labels.fields.bottom, resolvedDisplayValue?.paddingBottom ?? resolvedDisplayValue?.padding, isDisabled, scaleOptions, (next) => {
                 const nextPadding = resolveNextPadding(resolvedDisplayValue, "paddingBottom", next);
                 setDisplayState({ source: currentValue, value: nextPadding });
                 emit(nextPadding);

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-rate-control.js

@@ -2,10 +2,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Rate } from "antd";
 import { PhiIcon } from "../shell/phi-icon";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 import { normalizePhiRateCount, normalizePhiRateValue, } from "./phi-rate-control-contract";
 export function PhiRateControl({ value, count, allowHalf = false, allowClear = true, icon, label, description, ariaLabel, size, disabled, readOnly, onChange, onFocus, onBlur, }) {
+    const { labelId, labelledBy } = usePhiControlLabel(label, ariaLabel);
     const normalizedCount = normalizePhiRateCount(count);
     const normalizedValue = normalizePhiRateValue(value, normalizedCount, allowHalf);
-    return (_jsx(PhiLabeledControl, { label: label, description: description, children: _jsx(Rate, { "aria-label": ariaLabel ?? (typeof label === "string" ? label : undefined), value: normalizedValue, count: normalizedCount, allowHalf: allowHalf, allowClear: allowClear, character: icon ? _jsx(PhiIcon, { name: icon, size: "inherit" }) : undefined, size: size, disabled: disabled || readOnly || !onChange, keyboard: true, onChange: (nextValue) => onChange?.(normalizePhiRateValue(nextValue, normalizedCount, allowHalf)), onFocus: onFocus, onBlur: onBlur }) }));
+    return (_jsx(PhiLabeledControl, { label: label, labelId: labelId, description: description, children: _jsx(Rate, { "aria-label": ariaLabel, "aria-labelledby": labelledBy, value: normalizedValue, count: normalizedCount, allowHalf: allowHalf, allowClear: allowClear, character: icon ? _jsx(PhiIcon, { name: icon, size: "inherit" }) : undefined, size: size, disabled: disabled || readOnly || !onChange, keyboard: true, onChange: (nextValue) => onChange?.(normalizePhiRateValue(nextValue, normalizedCount, allowHalf)), onFocus: onFocus, onBlur: onBlur }) }));
 }

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

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+import type { PhiResultWidgetVisualStatus } from "../../types/result-widget";
+export type PhiResultControlProps = {
+    status: PhiResultWidgetVisualStatus;
+    title: ReactNode;
+    subTitle?: ReactNode;
+    /** What the reader can do next, drawn under the message -- usually one button. */
+    extra?: ReactNode;
+};
+/**
+ * The end of a journey on a page: an outcome, what happened, and what to do now.
+ *
+ * The status picks the illustration; the words are the caller's.
+ */
+export declare function PhiResultControl({ status, title, subTitle, extra }: PhiResultControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Result } from "antd";
+/**
+ * The end of a journey on a page: an outcome, what happened, and what to do now.
+ *
+ * The status picks the illustration; the words are the caller's.
+ */
+export function PhiResultControl({ status, title, subTitle, extra }) {
+    return _jsx(Result, { status: status, title: title, subTitle: subTitle, extra: extra });
+}

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

@@ -1,13 +1,20 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Segmented } from "antd";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 export function PhiSegmentedControl({ value, label, options, disabled, readOnly, block, size, onFocus, onBlur, onChange, }) {
-    const control = (_jsx(Segmented, { block: block, value: value, disabled: disabled || readOnly || !onChange, options: options.map((option) => ({
+    const { labelId, labelledBy } = usePhiControlLabel(label);
+    const control = (_jsx(Segmented, { "aria-labelledby": labelledBy, block: block, value: value, disabled: disabled || readOnly || !onChange, options: options.map((option) => ({
             value: option.value,
             label: option.label,
             disabled: option.disabled,
-            tooltip: option.description,
+            /*
+             * No browser tooltip: left out, the Segmented writes the label into `title` and every segment
+             * repeats its own text on hover. What a segment has to say beyond its label is its description,
+             * shown as a real tooltip.
+             */
+            title: "",
+            tooltip: option.description || undefined,
         })), size: size, onChange: (nextValue) => onChange?.(nextValue), onFocus: onFocus, onBlur: onBlur, style: { minWidth: 0, width: block ? "100%" : undefined } }));
-    return _jsx(PhiLabeledControl, { label: label, fill: block, children: control });
+    return _jsx(PhiLabeledControl, { label: label, labelId: labelId, fill: block, children: control });
 }

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

@@ -1,18 +1,49 @@
 "use client";
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { AutoComplete, Select } from "antd";
 import { PhiControlOptionContent } from "./phi-control-option-content";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
+const PHI_SELECT_SEPARATOR_STYLE = { minHeight: 0, padding: 0, cursor: "default" };
+function isPhiSelectSeparatorEntry(entry) {
+    return typeof entry === "object" && entry != null && "separator" in entry;
+}
+function renderPhiSelectSeparator() {
+    return _jsx("div", { role: "separator", style: { borderTop: "1px solid var(--ant-color-split)", marginBlock: 4 } });
+}
+/* The options with a line where one asks for it -- once, where an option after and one before agree. */
+function separatePhiSelectOptions(resolved) {
+    const entries = [];
+    resolved.forEach((entry, index) => {
+        const lineBefore = index > 0 &&
+            (entry.option.separator === "before" || resolved[index - 1]?.option.separator === "after");
+        if (lineBefore) {
+            entries.push({
+                value: `\u0000separator-${index}`,
+                label: null,
+                searchLabel: "",
+                disabled: true,
+                style: PHI_SELECT_SEPARATOR_STYLE,
+                separator: true,
+            });
+        }
+        entries.push(entry);
+    });
+    return entries;
+}
 /*
  * Consecutive options that name the same group, under one heading. Options without a group stay at the
  * top level, and a list that names no group at all comes back unchanged.
  */
 function groupPhiSelectOptions(resolved) {
-    if (!resolved.some((entry) => entry.option.group)) {
+    if (!resolved.some((entry) => !isPhiSelectSeparatorEntry(entry) && entry.option.group)) {
         return resolved;
     }
     const grouped = [];
     for (const entry of resolved) {
+        if (isPhiSelectSeparatorEntry(entry)) {
+            grouped.push(entry);
+            continue;
+        }
         const group = entry.option.group;
         const last = grouped.at(-1);
         if (!group) {
@@ -28,7 +59,8 @@ function groupPhiSelectOptions(resolved) {
     return grouped;
 }
 export function PhiSelectControl({ id, value, label, description, ariaLabel, placeholder, disabled, readOnly, presentation = "select", allowCustom, allowClear, options, size, variant, popupMatchSelectWidth = false, getPopupContainer, popupRootClassName, popupZIndex, style, onFocus, onBlur, onOpenChange, onSearch, filterOptionsLocally = true, onChange, }) {
-    const resolvedOptions = groupPhiSelectOptions(options.map((option) => ({
+    const { labelId, labelledBy } = usePhiControlLabel(label, ariaLabel);
+    const resolvedOptions = groupPhiSelectOptions(separatePhiSelectOptions(options.map((option) => ({
         value: option.value,
         // rc-select synthesizes native HTML title attributes from primitive labels.
         // Phi owns option descriptions through PhiControlOptionContent instead.
@@ -36,13 +68,13 @@ export function PhiSelectControl({ id, value, label, description, ariaLabel, pla
         searchLabel: option.label,
         disabled: option.disabled,
         option,
-    })));
+    }))));
     const controlDisabled = disabled || readOnly;
     const canUseTextEntry = (presentation === "autocomplete" || allowCustom) &&
         (value === undefined || typeof value === "string") &&
         options.every((option) => typeof option.value === "string");
     if (canUseTextEntry) {
-        const control = (_jsx(AutoComplete, { "aria-label": ariaLabel, value: value, placeholder: placeholder, disabled: controlDisabled, allowClear: allowClear, options: resolvedOptions, optionRender: (resolvedOption) => (_jsx(PhiControlOptionContent, { option: resolvedOption.data.option, presentation: "dropdown" })), size: size, variant: variant, popupMatchSelectWidth: popupMatchSelectWidth, getPopupContainer: getPopupContainer, classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined, styles: popupZIndex == null ? undefined : { popup: { root: { zIndex: popupZIndex } } }, filterOption: !filterOptionsLocally
+        const control = (_jsx(AutoComplete, { "aria-label": ariaLabel, "aria-labelledby": labelledBy, value: value, placeholder: placeholder, disabled: controlDisabled, allowClear: allowClear, options: resolvedOptions, optionRender: (resolvedOption) => isPhiSelectSeparatorEntry(resolvedOption.data) ? renderPhiSelectSeparator() : (_jsx(PhiControlOptionContent, { option: resolvedOption.data.option, presentation: "dropdown" })), size: size, variant: variant, popupMatchSelectWidth: popupMatchSelectWidth, getPopupContainer: getPopupContainer, classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined, styles: popupZIndex == null ? undefined : { popup: { root: { zIndex: popupZIndex } } }, filterOption: !filterOptionsLocally
                 ? false
                 : (inputValue, option) => {
                     // A group heading has no search label of its own; antd filters the options inside it.
@@ -51,13 +83,13 @@ export function PhiSelectControl({ id, value, label, description, ariaLabel, pla
                         .toLowerCase()
                         .includes(inputValue.toLowerCase());
                 }, onSearch: onSearch, onFocus: onFocus, onBlur: onBlur, onOpenChange: onOpenChange, onChange: (nextValue) => onChange(nextValue), style: style }));
-        return _jsx(PhiLabeledControl, { label: label, description: description, fill: style?.width === "100%", children: control });
+        return _jsx(PhiLabeledControl, { label: label, labelId: labelId, description: description, fill: style?.width === "100%", children: control });
     }
-    const control = (_jsx(Select, { id: id, "aria-label": ariaLabel, value: value ?? undefined, placeholder: placeholder, disabled: controlDisabled, allowClear: allowClear, options: resolvedOptions, optionRender: (resolvedOption) => (_jsx(PhiControlOptionContent, { option: resolvedOption.data.option, presentation: "dropdown" })), labelRender: (selectedOption) => {
+    const control = (_jsx(Select, { id: id, "aria-label": ariaLabel, "aria-labelledby": labelledBy, value: value ?? undefined, placeholder: placeholder, disabled: controlDisabled, allowClear: allowClear, options: resolvedOptions, optionRender: (resolvedOption) => isPhiSelectSeparatorEntry(resolvedOption.data) ? renderPhiSelectSeparator() : (_jsx(PhiControlOptionContent, { option: resolvedOption.data.option, presentation: "dropdown" })), labelRender: (selectedOption) => {
             const selected = options.find((option) => option.value === selectedOption.value);
             return selected
                 ? _jsx(PhiControlOptionContent, { option: selected, presentation: "selection" })
                 : selectedOption.label;
         }, size: size, variant: variant, popupMatchSelectWidth: popupMatchSelectWidth, getPopupContainer: getPopupContainer, classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined, styles: popupZIndex == null ? undefined : { popup: { root: { zIndex: popupZIndex } } }, showSearch: true, optionFilterProp: ["searchLabel", "value"], filterOption: filterOptionsLocally ? undefined : false, onSearch: onSearch, onFocus: onFocus, onBlur: onBlur, onOpenChange: onOpenChange, onChange: onChange, style: style }));
-    return _jsx(PhiLabeledControl, { label: label, description: description, fill: style?.width === "100%", children: control });
+    return _jsx(PhiLabeledControl, { label: label, labelId: labelId, description: description, fill: style?.width === "100%", children: control });
 }

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

@@ -56,7 +56,7 @@ export function PhiShadowControl({ value, disabled = false, mode = "control", on
                                 return;
                             }
                             onChange?.(nextPreset);
-                        } }), selectedPreset === "custom" ? (_jsxs("div", { style: { display: "grid", gap: token.paddingXS }, children: [_jsx(Typography.Text, { type: "secondary", style: { fontSize: 12 }, children: "CSS `box-shadow`" }), _jsx(PhiTextControl, { value: displayedCustomValue, disabled: isDisabled, allowClear: true, clearLabel: "Clear shadow", placeholder: "0 12px 32px rgba(0, 0, 0, 0.14)", ariaLabel: "Shadow", onChange: (nextValue) => {
+                        } }), selectedPreset === "custom" ? (_jsxs("div", { style: { display: "grid", gap: token.paddingXS }, children: [_jsx(Typography.Text, { type: "secondary", children: "CSS `box-shadow`" }), _jsx(PhiTextControl, { value: displayedCustomValue, disabled: isDisabled, allowClear: true, clearLabel: "Clear shadow", placeholder: "0 12px 32px rgba(0, 0, 0, 0.14)", ariaLabel: "Shadow", onChange: (nextValue) => {
                                     setCustomValue(nextValue ?? "");
                                     const normalized = nextValue?.trim() ?? "";
                                     if (normalized.length > 0) {
@@ -69,6 +69,10 @@ export function PhiShadowControl({ value, disabled = false, mode = "control", on
                                     setEditingCustomValue(false);
                                     const normalized = customValue.trim();
                                     setCustomValue(normalized);
+                                    // Leaving the field unchanged is no edit; an emptied field is a shadow taken away.
+                                    if (normalized === displayedCustomValue.trim()) {
+                                        return;
+                                    }
                                     onChange?.(normalized.length > 0 ? { kind: "custom", value: normalized } : "none");
                                 } })] })) : null] })] }));
 }

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

@@ -1,7 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { PhiSliderTooltipMode } from "./phi-slider-control-contract";
-export type PhiSliderControlProps = {
-    value?: number;
+type PhiSliderControlBaseProps = {
     label?: ReactNode;
     ariaLabel?: string;
     min?: number;
@@ -15,7 +14,21 @@ export type PhiSliderControlProps = {
     disabled?: boolean;
     readOnly?: boolean;
     style?: CSSProperties;
+};
+export type PhiSliderControlProps = PhiSliderControlBaseProps & ({
+    range?: false;
+    value?: number;
     onChange?: (value: number) => void;
     onChangeComplete?: (value: number) => void;
-};
-export declare function PhiSliderControl({ value, label, ariaLabel, min, max, step, dots, included, reverse, tooltipMode, tooltipSuffix, disabled, readOnly, style, onChange, onChangeComplete, }: PhiSliderControlProps): import("react").JSX.Element;
+} | {
+    /**
+     * Two handles, a start and an end; the track between them can be dragged as a whole, which moves
+     * the pair without changing the distance. The two never meet: a range is at least one `step`.
+     */
+    range: true;
+    value?: readonly [number, number];
+    onChange?: (value: [number, number]) => void;
+    onChangeComplete?: (value: [number, number]) => void;
+});
+export declare function PhiSliderControl(props: PhiSliderControlProps): import("react").JSX.Element;
+export {};