@phis/ui 0.2.1 → 0.3.0

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,7 +14,7 @@ export type PhiOverlayControlCommonProps = {
     footer?: ReactNode;
     closable?: boolean;
     keyboard?: boolean;
-    mask?: PhiCmsOverlayMaskConfig;
+    mask?: PhiOverlayMaskBehaviour;
     mountPolicy?: PhiCmsMountPolicy;
     containerStyle?: CSSProperties;
     onDismiss?: (source: PhiOverlayCloseSource) => void;
@@ -36,7 +36,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-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 {};

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

@@ -1,12 +1,37 @@
 "use client";
 import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Slider } from "antd";
-import { PhiLabeledControl } from "./phi-labeled-control";
-export function PhiSliderControl({ value, label, ariaLabel, min, max, step, dots, included, reverse, tooltipMode = "auto", tooltipSuffix, disabled, readOnly, style, onChange, onChangeComplete, }) {
-    return (_jsx(PhiLabeledControl, { label: label, fill: style?.width === "100%", children: _jsx(Slider, { "aria-label": ariaLabel ?? (typeof label === "string" ? label : undefined), value: value, min: min, max: max, step: step, dots: dots, included: included, reverse: reverse, disabled: disabled || readOnly || !onChange, tooltip: {
-                open: tooltipMode === "always" ? true : tooltipMode === "hidden" ? false : undefined,
-                formatter: tooltipSuffix == null
-                    ? undefined
-                    : (nextValue) => nextValue == null ? null : _jsxs(_Fragment, { children: [nextValue, tooltipSuffix] }),
-            }, style: { minWidth: 0, flex: label == null ? undefined : "1 1 auto", ...style }, onChange: onChange, onChangeComplete: onChangeComplete }) }));
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
+/** A pair whose handles met or crossed, pushed one `step` apart on the side that has room. */
+function separatePhiSliderRange(values, step, min, max) {
+    const [start = min, end = max] = values;
+    if (end - start >= step)
+        return [start, end];
+    return start + step <= max ? [start, start + step] : [end - step, end];
+}
+export function PhiSliderControl(props) {
+    const { label, ariaLabel, min, max, step, dots, included, reverse, tooltipMode = "auto", tooltipSuffix, disabled, readOnly, style, } = props;
+    const { labelId, labelledBy } = usePhiControlLabel(label, ariaLabel);
+    const shared = {
+        "aria-label": ariaLabel,
+        ariaLabelledByForHandle: labelledBy,
+        min,
+        max,
+        step,
+        dots,
+        included,
+        reverse,
+        disabled: disabled || readOnly || !props.onChange,
+        tooltip: {
+            open: tooltipMode === "always" ? true : tooltipMode === "hidden" ? false : undefined,
+            formatter: tooltipSuffix == null
+                ? undefined
+                : (nextValue) => nextValue == null ? null : _jsxs(_Fragment, { children: [nextValue, tooltipSuffix] }),
+        },
+        style: { minWidth: 0, flex: label == null ? undefined : "1 1 auto", ...style },
+    };
+    const separate = (values) => separatePhiSliderRange(values, step ?? 1, min ?? 0, max ?? 100);
+    return (_jsx(PhiLabeledControl, { label: label, labelId: labelId, fill: style?.width === "100%", children: props.range ? (_jsx(Slider, { ...shared, range: { draggableTrack: true }, value: props.value ? [...props.value] : undefined, onChange: props.onChange ? (values) => props.onChange?.(separate(values)) : undefined, onChangeComplete: props.onChangeComplete
+                ? (values) => props.onChangeComplete?.(separate(values))
+                : undefined })) : (_jsx(Slider, { ...shared, value: props.value, onChange: props.onChange, onChangeComplete: props.onChangeComplete })) }));
 }

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

@@ -0,0 +1,40 @@
+import type { PhiControlSize } from "../../types/control";
+/**
+ * One step: what it is called, a line under it, and its own icon where it has one.
+ *
+ * `status` is for the step that differs from what its position says -- the one that failed. Left out,
+ * the Control derives it: before `current` is done, `current` is in progress, after it waits.
+ */
+export type PhiStepsControlItem = {
+    key: string;
+    title: string;
+    description?: string;
+    /** A Phi icon name, never a node: the item is data a Widget stores. */
+    icon?: string;
+    status?: "wait" | "process" | "finish" | "error";
+    disabled?: boolean;
+};
+export type PhiStepsControlProps = {
+    items: readonly PhiStepsControlItem[];
+    /** The index of the step in progress. Past the last, every step is done. */
+    current: number;
+    orientation?: "horizontal" | "vertical";
+    /** `dot` draws the steps as points on a line, for a sequence the eye only follows. */
+    presentation?: "default" | "dot";
+    size?: PhiControlSize;
+    ariaLabel?: string;
+    /**
+     * Going to a step. Without it the steps are an indicator and nothing about them is clickable -- the
+     * Widget decides whether they navigate, never the Control by default.
+     */
+    onChange?: (index: number) => void;
+};
+/**
+ * Where a sequence stands: a checkout, a sign-up, the slots of a Stack walked one after another.
+ *
+ * A Control of its own rather than a pass-through. Ant Design's items take nodes for their title, icon and
+ * content, and a Steps that navigates is a navigation primitive like Menu and Tabs: its item shape stays
+ * here and does not become the package's. `content` is not offered -- a step says what it is in a line,
+ * and what belongs under it in full is the Stack slot it stands for.
+ */
+export declare function PhiStepsControl({ items, current, orientation, presentation, size, ariaLabel, onChange, }: PhiStepsControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Steps } from "antd";
+import { PhiIcon } from "../shell/phi-icon";
+/**
+ * Where a sequence stands: a checkout, a sign-up, the slots of a Stack walked one after another.
+ *
+ * A Control of its own rather than a pass-through. Ant Design's items take nodes for their title, icon and
+ * content, and a Steps that navigates is a navigation primitive like Menu and Tabs: its item shape stays
+ * here and does not become the package's. `content` is not offered -- a step says what it is in a line,
+ * and what belongs under it in full is the Stack slot it stands for.
+ */
+export function PhiStepsControl({ items, current, orientation = "horizontal", presentation = "default", size, ariaLabel, onChange, }) {
+    return (_jsx(Steps, { "aria-label": ariaLabel, current: current, orientation: orientation, type: presentation === "dot" ? "dot" : "default", 
+        /* Steps knows no large; a large Control stands at the medium size beside it. */
+        size: size === "small" ? "small" : "medium", items: items.map((item) => ({
+            key: item.key,
+            title: item.title,
+            content: item.description,
+            icon: item.icon ? _jsx(PhiIcon, { name: item.icon, size: "inherit" }) : undefined,
+            status: item.status,
+            disabled: item.disabled,
+        })), onChange: onChange }));
+}

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

@@ -0,0 +1,56 @@
+import { type PhiBackgroundControlProps } from "./phi-background-control";
+import type { PhiBackgroundWidgetLabels } from "../widgets/label-types/background";
+import type { PhiBorderWidgetLabels } from "../widgets/label-types/border";
+import type { PhiColorPickerLabels } from "../widgets/label-types/color-picker";
+import type { PhiPickerPlacement } from "./phi-picker-control-contract";
+import type { PhiBackgroundFilter } from "../../types/layout-style";
+import { type PhiSurface, type PhiSurfaceTone } from "../../types/surface";
+import { type PhiSurfacePresetId } from "../../helpers/surface-presets";
+export type PhiSurfaceControlLabels = {
+    /** The style switch: no look, a named look, or values of the author's own. */
+    style: string;
+    styles: Record<PhiSurfacePresetId | "none" | "custom", string>;
+    background: string;
+    border: string;
+    shadow: string;
+    tone: string;
+    tones: Record<PhiSurfaceTone, string>;
+};
+export type PhiSurfaceControlProps = {
+    value?: PhiSurface | null;
+    /** The whole next Surface, or `null` once nothing is left in it. */
+    onChange?: (next: PhiSurface | null) => void;
+    disabled?: boolean;
+    /** The headings of the three parts. */
+    labels?: PhiSurfaceControlLabels;
+    backgroundLabels?: PhiBackgroundWidgetLabels;
+    borderLabels?: PhiBorderWidgetLabels;
+    colorPickerLabels?: PhiColorPickerLabels;
+    colorPickerPlacement?: PhiPickerPlacement;
+    /** The Filters the box can render; see `PhiBackgroundControlProps["filters"]`. */
+    backgroundFilters?: readonly PhiBackgroundFilter[];
+    renderMediaPicker?: PhiBackgroundControlProps["renderMediaPicker"];
+    /** Whether the mode is offered, for a box that can have one; a list entry's cannot. */
+    tone?: boolean;
+};
+/**
+ * A Surface (`PhiSurface`) as one Control: its ground, its edge and its depth, each drawn by the Control
+ * that owns that part.
+ *
+ * The style switch on top picks a look: `none` leaves the box transparent, a named look
+ * (`helpers/surface-presets.ts`) writes its values -- `card` the Theme's container ground, `wash` its
+ * quietest filling -- and `custom` opens the parts, which edit the values the Surface has. The mode stands
+ * beside every look.
+ *
+ * Every box that has a look is edited with it -- a Region, a Layout, a Widget -- so the three parts read
+ * the same everywhere, and each change hands on the whole Surface with the other parts untouched.
+ *
+ * The mode asks which colours the box and its content are drawn in: the page's (`inherit`), one fixed
+ * mode, or the other one than the page's (`inverse`).
+ *
+ * The edge asks where the line comes from before it asks what the line is: `theme` takes the Site's own
+ * line and follows the Theme, and the line's fields appear only under `custom`, the one source that
+ * reads them. The question is answered by the same resolver the drawing asks
+ * (`resolvePhiCmsBorderSource`), so a configured line reads as `custom` here as it does on the page.
+ */
+export declare function PhiSurfaceControl({ value, onChange, disabled, labels, backgroundLabels, borderLabels, colorPickerLabels, colorPickerPlacement, backgroundFilters, renderMediaPicker, tone, }: PhiSurfaceControlProps): import("react").JSX.Element;