@phis/ui 0.2.1 → 0.4.0

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;

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

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { PhiBackgroundControl } from "./phi-background-control";
+import { PhiBorderControl } from "./phi-border-control";
+import { PhiFlexControl } from "./phi-flex-control";
+import { PhiSegmentedControl } from "./phi-segmented-control";
+import { PhiShadowControl } from "./phi-shadow-control";
+import { PhiDividerControl } from "./phi-divider-control";
+import { PHI_CMS_BORDER_SOURCES, resolvePhiCmsBorderSource, } from "../../types/cms-border-source";
+import { PHI_SURFACE_TONES } from "../../types/surface";
+import { PHI_SURFACE_PRESET_IDS, PHI_SURFACE_PRESETS, resolvePhiSurfacePresetId, } from "../../helpers/surface-presets";
+const PHI_SURFACE_CONTROL_DEFAULT_LABELS = {
+    style: "Style",
+    styles: { none: "None", card: "Card", wash: "Wash", custom: "Custom" },
+    background: "Background",
+    border: "Border",
+    shadow: "Shadow",
+    tone: "Mode",
+    tones: {
+        inherit: "Page",
+        light: "Light",
+        dark: "Dark",
+        inverse: "Inverse",
+    },
+};
+/** Read only where the Border labels have not arrived; the words themselves live in their label set. */
+const PHI_BORDER_SOURCE_FALLBACK_LABELS = {
+    none: "None",
+    theme: "Theme",
+    custom: "Custom",
+};
+function withPart(current, patch) {
+    const next = { ...current, ...patch };
+    for (const [key, value] of Object.entries(next)) {
+        if (value == null) {
+            delete next[key];
+        }
+    }
+    return Object.keys(next).length > 0 ? next : null;
+}
+/**
+ * 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 function PhiSurfaceControl({ value, onChange, disabled = false, labels = PHI_SURFACE_CONTROL_DEFAULT_LABELS, backgroundLabels, borderLabels, colorPickerLabels, colorPickerPlacement = "left", backgroundFilters, renderMediaPicker, tone = true, }) {
+    const current = value ?? {};
+    const isDisabled = disabled || !onChange;
+    const borderSource = resolvePhiCmsBorderSource(current.borderSource, current.border);
+    const resolvedStyle = resolvePhiSurfacePresetId(value);
+    /*
+     * `custom` is a choice of its own: it opens the parts -- ground, edge, depth -- on the values the
+     * Surface has, so an author can start from a card and change its line. Until a value changes, those
+     * values are still the card's, so the choice is held here; a Surface that arrives from elsewhere (the
+     * next selected node) drops it, one this Control wrote keeps it.
+     */
+    const [customChosen, setCustomChosen] = useState(false);
+    const [seenValue, setSeenValue] = useState(value);
+    const [writtenValue, setWrittenValue] = useState(undefined);
+    if (seenValue !== value) {
+        setSeenValue(value);
+        // Compared by content: the owner may hand back a copy of what was written.
+        if (JSON.stringify(value ?? null) !== JSON.stringify(writtenValue ?? null))
+            setCustomChosen(false);
+    }
+    const style = customChosen ? "custom" : resolvedStyle;
+    const emit = (next) => {
+        setWrittenValue(next);
+        onChange?.(next);
+    };
+    const patch = (part) => emit(withPart(current, part));
+    /*
+     * A named style writes its values and keeps the mode; `none` takes the look away -- the box stays
+     * transparent -- and keeps the mode as well. `custom` writes nothing and shows the parts.
+     */
+    const chooseStyle = (next) => {
+        if (next === "custom") {
+            setCustomChosen(true);
+            return;
+        }
+        setCustomChosen(false);
+        const look = next === "none" ? {} : PHI_SURFACE_PRESETS[next];
+        emit(withPart({ ...look, ...(current.tone ? { tone: current.tone } : {}) }, {}));
+    };
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: "middle", style: { width: "100%", minWidth: 0 }, children: [_jsxs(PhiFlexControl, { vertical: true, gap: "small", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: labels.style }), _jsx(PhiSegmentedControl, { value: style, options: [
+                            { value: "none", label: labels.styles.none },
+                            ...PHI_SURFACE_PRESET_IDS.map((id) => ({ value: id, label: labels.styles[id] })),
+                            { value: "custom", label: labels.styles.custom },
+                        ], block: true, disabled: isDisabled, onChange: chooseStyle })] }), tone ? (_jsxs(PhiFlexControl, { vertical: true, gap: "small", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: labels.tone }), _jsx(PhiSegmentedControl, { value: current.tone ?? "inherit", options: PHI_SURFACE_TONES.map((entry) => ({ value: entry, label: labels.tones[entry] })), block: true, disabled: isDisabled, onChange: (next) => patch({ tone: next === "inherit" ? undefined : next }) })] })) : null, style === "custom" ? (_jsxs(_Fragment, { children: [_jsxs(PhiFlexControl, { vertical: true, gap: "small", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: labels.background }), _jsx(PhiBackgroundControl, { mode: "control", disabled: isDisabled, value: current.background ?? null, onChange: (background) => patch({ background }), labels: backgroundLabels, colorPickerLabels: colorPickerLabels, colorPickerPlacement: colorPickerPlacement, filters: backgroundFilters, renderMediaPicker: renderMediaPicker })] }), _jsxs(PhiFlexControl, { vertical: true, gap: "small", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: labels.border }), _jsx(PhiSegmentedControl, { value: borderSource, options: PHI_CMS_BORDER_SOURCES.map((source) => ({
+                                    value: source,
+                                    label: borderLabels?.sources?.[source] ?? PHI_BORDER_SOURCE_FALLBACK_LABELS[source],
+                                })), block: true, disabled: isDisabled, onChange: (nextSource) => patch({ borderSource: nextSource }) }), borderSource === "custom" ? (_jsx(PhiBorderControl, { mode: "control", disabled: isDisabled, value: current.border ?? null, onChange: (border) => patch({ border, borderSource: "custom" }), labels: borderLabels, colorPickerLabels: colorPickerLabels, colorPickerPlacement: colorPickerPlacement })) : null] }), _jsxs(PhiFlexControl, { vertical: true, gap: "small", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiDividerControl, { titlePlacement: "start", style: { marginBlock: 0 }, children: labels.shadow }), _jsx(PhiShadowControl, { mode: "control", disabled: isDisabled, value: current.shadow ?? null, onChange: (shadow) => patch({ shadow }) })] })] })) : null] }));
+}

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

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Switch } from "antd";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 export function PhiSwitchControl({ id, checked, label, disabled, readOnly, loading, checkedLabel, uncheckedLabel, size, onChange, }) {
-    return (_jsx(PhiLabeledControl, { label: label, children: _jsx(Switch, { id: id, checked: checked, disabled: disabled || readOnly || !onChange, loading: loading, checkedChildren: checkedLabel, unCheckedChildren: uncheckedLabel, size: size, onChange: onChange }) }));
+    const { labelId, labelledBy } = usePhiControlLabel(label);
+    return (_jsx(PhiLabeledControl, { label: label, labelId: labelId, children: _jsx(Switch, { id: id, "aria-labelledby": labelledBy, checked: checked, disabled: disabled || readOnly || !onChange, loading: loading, checkedChildren: checkedLabel, unCheckedChildren: uncheckedLabel, size: size, onChange: onChange }) }));
 }

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

@@ -19,6 +19,8 @@ export type PhiTableControlCellEditor = {
         step?: number;
         precision?: number;
     };
+    /** The unit beside a number editor, already in the reader's language. */
+    prefix?: string;
 };
 export type PhiTableControlColumn<TRow extends Record<string, unknown>> = {
     key: string;

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

@@ -1,6 +1,5 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { CloseOutlined, DownOutlined, EditOutlined, HolderOutlined, LeftOutlined, RightOutlined, SaveOutlined, UpOutlined } from "@ant-design/icons";
 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";
@@ -8,6 +7,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/visual-anchors";
 import { PhiColorControl } from "./phi-color-control";
 import { PhiCheckboxControl } from "./phi-checkbox-control";
 import { PhiCheckboxGroupControl } from "./phi-checkbox-group-control";
@@ -26,6 +26,7 @@ import { usePhiConfig } from "../root/phi-config-provider";
 import { PhiSkeletonControl } from "./phi-skeleton-control";
 import { readPhiDotPath } from "../../helpers/dot-path";
 import { readPhiTableRowIdentity as readIdentity } from "../../helpers/table-binding";
+import { PhiIcon } from "../shell/phi-icon";
 const PhiTableSortableRowContext = createContext(null);
 const PhiTableDragVisualStateContext = createContext({ activeIdentity: null, insertionGapIndex: null, insertionGapHeight: 0 });
 const PHI_TABLE_LOADING_ROW = Symbol("phi-table-loading-row");
@@ -80,10 +81,10 @@ function PhiTableSortableRow({ style, children, ...props }) {
 }
 function PhiTableRowDragHandle({ dragLabel = "Drag row", disabled, }) {
     const sortable = useContext(PhiTableSortableRowContext);
-    return (_jsx(Button, { ...sortable?.attributes, ...sortable?.listeners, ref: sortable?.setActivatorNodeRef, type: "text", size: "small", icon: _jsx(HolderOutlined, {}), "aria-label": dragLabel, disabled: disabled || !sortable, onClick: (event) => event.stopPropagation(), style: { touchAction: "none" } }));
+    return (_jsx(Button, { ...sortable?.attributes, ...sortable?.listeners, ref: sortable?.setActivatorNodeRef, type: "text", size: "small", icon: _jsx(PhiIcon, { name: "holder", size: "inherit" }), "aria-label": dragLabel, disabled: disabled || !sortable, onClick: (event) => event.stopPropagation(), style: { touchAction: "none" } }));
 }
 function PhiTableRowPositionControls({ moveUpLabel = "Move row up", moveDownLabel = "Move row down", canMoveUp, canMoveDown, onMoveUp, onMoveDown, }) {
-    return (_jsxs(Flex, { align: "center", gap: 2, wrap: false, children: [_jsx(Button, { type: "text", size: "small", icon: _jsx(UpOutlined, {}), "aria-label": moveUpLabel, disabled: !canMoveUp, onClick: (event) => { event.stopPropagation(); onMoveUp(); } }), _jsx(Button, { type: "text", size: "small", icon: _jsx(DownOutlined, {}), "aria-label": moveDownLabel, disabled: !canMoveDown, onClick: (event) => { event.stopPropagation(); onMoveDown(); } })] }));
+    return (_jsxs(Flex, { align: "center", gap: 2, wrap: false, children: [_jsx(Button, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "up", size: "inherit" }), "aria-label": moveUpLabel, disabled: !canMoveUp, onClick: (event) => { event.stopPropagation(); onMoveUp(); } }), _jsx(Button, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "down", size: "inherit" }), "aria-label": moveDownLabel, disabled: !canMoveDown, onClick: (event) => { event.stopPropagation(); onMoveDown(); } })] }));
 }
 export function readPhiTableControlValue(row, path) {
     return readPhiDotPath(row, path);
@@ -211,6 +212,16 @@ function buildLoadingSkeletonStyle(width, cellPaddingInline) {
         : `max(24px, calc(${width} - ${cellPaddingInline * 2}px))`;
     return { display: "block", width: contentWidth, minWidth: 24, maxWidth: "100%" };
 }
+/*
+ * A cell keyed by its value starts over when the value changes from outside, which is what keeps a
+ * typed draft from outliving it. A multiple choice commits on every click, so the same key remounted
+ * it per click -- the dropdown closed and the focus went; it reads its value directly instead.
+ */
+function resolveEditableCellKey(identity, columnKey, editor, value) {
+    return editor.type === "enum[]"
+        ? `${String(identity)}:${columnKey}`
+        : `${String(identity)}:${columnKey}:${JSON.stringify(value)}`;
+}
 function EditableTableCell({ value, editor, onCommit }) {
     const [draft, setDraft] = useState(value);
     const draftRef = useRef(value);
@@ -245,7 +256,7 @@ function EditableTableCell({ value, editor, onCommit }) {
         return _jsx(PhiSwitchControl, { checked: draft === true, disabled: editor.disabled, loading: editor.loading, size: "small", onChange: (next) => { draftRef.current = next; setDraft(next); onCommit(next); } });
     }
     if (editor.type === "number") {
-        return _jsx(PhiNumberControl, { value: typeof draft === "number" ? draft : null, min: typeof editor.constraints?.min === "number" ? editor.constraints.min : undefined, max: typeof editor.constraints?.max === "number" ? editor.constraints.max : undefined, step: editor.constraints?.step, precision: editor.constraints?.precision, disabled: disabled, size: "small", variant: variant, style: { width: "100%" }, onChange: (next) => { draftRef.current = next; setDraft(next); }, onBlur: commitOnBlur, onKeyDown: (event) => {
+        return _jsx(PhiNumberControl, { value: typeof draft === "number" ? draft : null, min: typeof editor.constraints?.min === "number" ? editor.constraints.min : undefined, max: typeof editor.constraints?.max === "number" ? editor.constraints.max : undefined, step: editor.constraints?.step, precision: editor.constraints?.precision, prefix: editor.prefix, disabled: disabled, size: "small", variant: variant, style: { width: "100%" }, onChange: (next) => { draftRef.current = next; setDraft(next); }, onBlur: commitOnBlur, onKeyDown: (event) => {
                 if (event.key !== "Enter")
                     return;
                 skipNextBlurRef.current = true;
@@ -312,8 +323,9 @@ function EditableTableCell({ value, editor, onCommit }) {
         return _jsx(PhiSelectControl, { value: enumValue, disabled: disabled, size: "small", variant: variant, options: editor.options ?? [], style: { width: "100%" }, onChange: (next) => { draftRef.current = next; setDraft(next); onCommit(next); } });
     }
     if (editor.type === "enum[]") {
-        const values = Array.isArray(draft)
-            ? draft.filter((entry) => typeof entry === "string" || typeof entry === "number")
+        // Committed per choice, so the value is the state: no draft of its own to fall behind it.
+        const values = Array.isArray(value)
+            ? value.filter((entry) => typeof entry === "string" || typeof entry === "number")
             : [];
         if (editor.control === "checkbox-group") {
             return _jsx(PhiCheckboxGroupControl, { value: values, disabled: disabled, options: editor.options ?? [], onChange: (next) => { draftRef.current = next; setDraft(next); onCommit(next); } });
@@ -344,8 +356,16 @@ function buildRowMove(rows, rowIdentityPath, parentRowIdentityPath, movedRowIden
 }
 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, }) {
     const { token } = usePhiConfig();
-    const [editingRowIdentity, setEditingRowIdentity] = useState(null);
+    const [editingRowIdentityState, setEditingRowIdentity] = useState(null);
     const [rowEditPatch, setRowEditPatch] = useState({});
+    /*
+     * The row being edited, while it is on screen. A page change or a reload can take it away, and a
+     * stored identity that names nothing visible locked every other row's edit button with no Cancel
+     * left to press; once the row is gone, so is the edit.
+     */
+    const editingRowIdentity = editingRowIdentityState != null && rows.some((row) => String(readIdentity(row, rowIdentityPath)) === String(editingRowIdentityState))
+        ? editingRowIdentityState
+        : null;
     const [treeExpandAnimation, setTreeExpandAnimation] = useState(null);
     const [dropTarget, setDropTarget] = useState(null);
     const dropTargetRef = useRef(null);
@@ -546,7 +566,7 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
         const reorderIndex = columnOrder.indexOf(column.key);
         const canReorder = columnReordering && column.fixed === undefined && reorderIndex >= 0;
         const columnStyle = buildColumnStyle(column.sizing);
-        const title = canReorder ? (_jsxs(Flex, { align: "center", gap: 4, children: [_jsx("span", { children: column.title }), _jsx("span", { onClick: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(LeftOutlined, {}), disabled: reorderIndex === 0, ariaLabel: "Move column left", tooltip: "Move column left", onClick: () => onColumnOrderChange?.(moveColumn(columnOrder, column.key, -1)) }) }), _jsx("span", { onClick: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(RightOutlined, {}), disabled: reorderIndex === columnOrder.length - 1, ariaLabel: "Move column right", tooltip: "Move column right", onClick: () => onColumnOrderChange?.(moveColumn(columnOrder, column.key, 1)) }) })] })) : column.title;
+        const title = canReorder ? (_jsxs(Flex, { align: "center", gap: 4, children: [_jsx("span", { children: column.title }), _jsx("span", { onClick: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "left", size: "inherit" }), disabled: reorderIndex === 0, ariaLabel: "Move column left", tooltip: "Move column left", onClick: () => onColumnOrderChange?.(moveColumn(columnOrder, column.key, -1)) }) }), _jsx("span", { onClick: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "right", size: "inherit" }), disabled: reorderIndex === columnOrder.length - 1, ariaLabel: "Move column right", tooltip: "Move column right", onClick: () => onColumnOrderChange?.(moveColumn(columnOrder, column.key, 1)) }) })] })) : column.title;
         return {
             key: column.key,
             columnKey: sortField,
@@ -582,12 +602,15 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                 let content;
                 if (editor && editing?.mode === "row" && identity != null &&
                     String(identity) === String(editingRowIdentity)) {
-                    const editValue = rowEditPatch[column.fieldPath] ?? value;
-                    content = _jsx(EditableTableCell, { value: editValue, editor: editor, onCommit: (next) => setRowEditPatch((current) => ({ ...current, [column.fieldPath]: next })) }, `${String(identity)}:${column.key}:${JSON.stringify(editValue)}`);
+                    // Present in the patch is the answer, `null` included: an emptied date or number is not its old value.
+                    const editValue = Object.prototype.hasOwnProperty.call(rowEditPatch, column.fieldPath)
+                        ? rowEditPatch[column.fieldPath]
+                        : value;
+                    content = _jsx(EditableTableCell, { value: editValue, editor: editor, onCommit: (next) => setRowEditPatch((current) => ({ ...current, [column.fieldPath]: next })) }, resolveEditableCellKey(identity, column.key, editor, editValue));
                 }
                 else {
                     content = editor && column.onCommit
-                        ? _jsx(EditableTableCell, { value: value, editor: editor, onCommit: (next) => column.onCommit?.(row, value, next) }, `${String(identity)}:${column.key}:${JSON.stringify(value)}`)
+                        ? _jsx(EditableTableCell, { value: value, editor: editor, onCommit: (next) => column.onCommit?.(row, value, next) }, resolveEditableCellKey(identity, column.key, editor, value))
                         : column.render
                             ? column.render(value, row)
                             : value;
@@ -610,7 +633,11 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                 }
                 return content;
             },
-            onHeaderCell: () => ({ style: columnStyle }),
+            // The actions column's head is where a Tour points at what a row can do (`row-actions`).
+            onHeaderCell: () => ({
+                style: columnStyle,
+                ...(column.role === "actions" ? { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "row-actions" } : {}),
+            }),
             onCell: () => ({ style: columnStyle }),
         };
     }), [
@@ -643,14 +670,14 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                 const active = identity != null && String(identity) === String(editingRowIdentity);
                 const disabled = editing.isRowDisabled?.(row) ?? false;
                 if (!active) {
-                    return _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(EditOutlined, {}), ariaLabel: editing.editLabel ?? "Edit row", tooltip: editing.editLabel ?? "Edit row", disabled: disabled || identity == null || editingRowIdentity != null, onClick: () => { setEditingRowIdentity(identity); setRowEditPatch({}); } });
+                    return _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "edit", size: "inherit" }), ariaLabel: editing.editLabel ?? "Edit row", tooltip: editing.editLabel ?? "Edit row", disabled: disabled || identity == null || editingRowIdentity != null, onClick: () => { setEditingRowIdentity(identity); setRowEditPatch({}); } });
                 }
-                return _jsxs(Flex, { align: "center", gap: 2, children: [_jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(SaveOutlined, {}), ariaLabel: editing.saveLabel ?? "Save row", tooltip: editing.saveLabel ?? "Save row", disabled: disabled, onClick: () => {
+                return _jsxs(Flex, { align: "center", gap: 2, children: [_jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "save", size: "inherit" }), ariaLabel: editing.saveLabel ?? "Save row", tooltip: editing.saveLabel ?? "Save row", disabled: disabled, onClick: () => {
                                 const originalValues = Object.fromEntries(editableColumns.map((column) => [column.fieldPath, readPhiTableControlValue(row, column.fieldPath)]));
                                 editing.onCommit(row, originalValues, rowEditPatch);
                                 setEditingRowIdentity(null);
                                 setRowEditPatch({});
-                            } }), _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(CloseOutlined, {}), ariaLabel: editing.cancelLabel ?? "Cancel row editing", tooltip: editing.cancelLabel ?? "Cancel row editing", onClick: () => { setEditingRowIdentity(null); setRowEditPatch({}); } })] });
+                            } }), _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "close", size: "inherit" }), ariaLabel: editing.cancelLabel ?? "Cancel row editing", tooltip: editing.cancelLabel ?? "Cancel row editing", onClick: () => { setEditingRowIdentity(null); setRowEditPatch({}); } })] });
             },
         }] : [], [editableColumns, editing, editingRowIdentity, rowEditPatch, rowIdentityPath]);
     const dataSource = useMemo(() => tree
@@ -864,8 +891,10 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
     }, [resolveDndDropTarget, updateDropTarget]);
     const handleRowDragStart = useCallback((event) => {
         const activatorEvent = event.activatorEvent;
-        const activeRow = [...document.querySelectorAll("tr[data-row-key]")]
-            .find((row) => row.getAttribute("data-row-key") === String(event.active.id)) ?? null;
+        // The row the drag began in, found from the handle that began it: a search of the whole document
+        // found the first row with that identity, which in a second Table on the page is someone else's.
+        const handle = activatorEvent.target instanceof Element ? activatorEvent.target : null;
+        const activeRow = handle?.closest("tr[data-row-key]") ?? null;
         dragTableElement.current = activeRow?.closest("table") ?? null;
         setActiveDragRowHeight(activeRow?.getBoundingClientRect().height ?? 0);
         dragRowRects.current = new Map([...(dragTableElement.current?.querySelectorAll("tr[data-row-key]") ?? [])].flatMap((row) => {
@@ -958,18 +987,39 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
      */
     const hasClosingBlock = !loading &&
         (Boolean(footer) || (summary != null && summary.placement !== "sticky-top"));
+    const frameRef = useRef(null);
+    const [headerBox, setHeaderBox] = useState(null);
+    useEffect(() => {
+        const frame = frameRef.current;
+        const head = showHeader === false ? null : frame?.querySelector("thead");
+        if (!frame || !head || typeof ResizeObserver === "undefined") {
+            setHeaderBox(null);
+            return undefined;
+        }
+        const measure = () => {
+            const top = head.getBoundingClientRect().top - frame.getBoundingClientRect().top;
+            const height = head.getBoundingClientRect().height;
+            setHeaderBox((current) => current?.top === top && current.height === height ? current : { top, height });
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(head);
+        observer.observe(frame);
+        return () => observer.disconnect();
+    }, [showHeader, loading]);
     const table = (_jsx(Table, { className: ["phi-table-control", hasClosingBlock ? "phi-table-control--closing-block" : 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 : {
+            ...{ [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "pagination" },
             current: pagination.page,
             pageSize: pagination.pageSize,
             total: pagination.total,
             pageSizeOptions: pagination.pageSizeOptions?.map(String),
             showSizeChanger: pagination.showSizeChanger,
             onChange: pagination.onChange,
-        }, footer: footer && !loading ? () => (_jsx(Flex, { align: "center", justify: footer.align ?? "start", gap: "small", wrap: true, children: footer.content })) : undefined, summary: summaryNode, expandable: tree && !loading ? {
+        }, footer: footer && !loading ? () => (_jsx(Flex, { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "footer", align: "center", justify: footer.align ?? "start", gap: "small", wrap: true, children: footer.content })) : undefined, summary: summaryNode, expandable: tree && !loading ? {
             childrenColumnName: "__phiTableChildren",
             showExpandColumn: false,
             expandedRowKeys: [...tree.expandedRowIdentities],
@@ -1047,7 +1097,7 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                     insertionGapIndex,
                     insertionGapHeight: activeDragRowHeight,
                 }, children: table }) }) })) : table;
-    const constrainedTable = (_jsx("div", { style: { width: "100%", maxWidth: "100%", minWidth: 0, overflow: "hidden" }, children: renderedTable }));
+    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] }));
     return onExternalDragOver || onExternalDrop ? (_jsx("div", { onDragOver: (event) => {
             if (event.defaultPrevented) {
                 setExternalAppendActive(false);

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

@@ -1,8 +1,6 @@
 import type { CSSProperties, FocusEventHandler, KeyboardEventHandler, ReactNode, Ref } from "react";
-import type { InputRef } from "antd/es/input";
-import type { TextAreaRef } from "antd/es/input/TextArea";
 import type { PhiControlSize, PhiControlVariant } from "../../types/control";
-import type { PhiTextInputType } from "./phi-text-types";
+import type { PhiTextControlInputRef, PhiTextControlTextAreaRef, PhiTextInputType } from "./phi-text-types";
 export type PhiTextControlPresentation = "input" | "password" | "textarea" | "hidden";
 export type PhiTextControlProps = {
     /** The DOM id of the input, so a `<label for>` outside the control can name it. */
@@ -33,8 +31,8 @@ export type PhiTextControlProps = {
     tabIndex?: number;
     size?: PhiControlSize;
     variant?: PhiControlVariant;
-    inputRef?: Ref<InputRef>;
-    textareaRef?: Ref<TextAreaRef>;
+    inputRef?: Ref<PhiTextControlInputRef>;
+    textareaRef?: Ref<PhiTextControlTextAreaRef>;
     onChange?: (nextValue: string | null) => void;
     onPressEnter?: () => void;
     onKeyDown?: KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>;

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

@@ -1,8 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Input } from "antd";
-import { CloseOutlined, SearchOutlined } from "@ant-design/icons";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
+import { PhiIcon } from "../shell/phi-icon";
 function resolveTextInputKind(inputType) {
     switch (inputType) {
         case "url":
@@ -23,15 +23,17 @@ function resolveTextInputKind(inputType) {
     }
 }
 export function PhiTextControl({ id, value, label, description, inputType = "text", presentation = "input", disabled = false, readOnly = false, allowClear = true, clearLabel, placeholder, ariaLabel, prefix, autoFocus, autoComplete, minLength, maxLength, rows, cols, autoSize, tabIndex, size, variant, inputRef, textareaRef, onChange, onPressEnter, onKeyDown, onFocus, onBlur, onClear, style, inputStyle, }) {
+    const { labelId, labelledBy } = usePhiControlLabel(label, ariaLabel);
     const resolvedKind = resolveTextInputKind(inputType);
     const stableAllowClear = {
         disabled: !allowClear,
-        clearIcon: (_jsx(CloseOutlined, { "aria-label": clearLabel })),
+        clearIcon: (_jsx(PhiIcon, { name: "close", size: "inherit", ariaLabel: clearLabel })),
     };
     const commonProps = {
         ref: inputRef,
         id,
         "aria-label": ariaLabel,
+        "aria-labelledby": labelledBy,
         autoFocus,
         autoComplete,
         minLength,
@@ -60,7 +62,7 @@ export function PhiTextControl({ id, value, label, description, inputType = "tex
         control = (_jsx(Input.Password, { ...commonProps, styles: inputStyle ? { input: inputStyle } : undefined, allowClear: stableAllowClear, onClear: onClear, prefix: prefix, onPressEnter: onPressEnter }));
     }
     else {
-        control = (_jsx(Input, { ...commonProps, styles: inputStyle ? { input: inputStyle } : undefined, allowClear: stableAllowClear, inputMode: resolvedKind.inputMode, prefix: prefix, suffix: resolvedKind.type === "search" ? _jsx(SearchOutlined, {}) : undefined, type: resolvedKind.type, onClear: onClear, onPressEnter: onPressEnter }));
+        control = (_jsx(Input, { ...commonProps, styles: inputStyle ? { input: inputStyle } : undefined, allowClear: stableAllowClear, inputMode: resolvedKind.inputMode, prefix: prefix, suffix: resolvedKind.type === "search" ? _jsx(PhiIcon, { name: "search", size: "inherit" }) : undefined, type: resolvedKind.type, onClear: onClear, onPressEnter: onPressEnter }));
     }
-    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-text-types.d.ts

@@ -1 +1,9 @@
+import type { InputRef } from "antd/es/input";
+import type { TextAreaRef } from "antd/es/input/TextArea";
+/**
+ * What a ref on PhiTextControl's field reaches: focus, blur, selection. Named here so a Widget holding
+ * one types against the Control rather than against the primitive drawn inside it.
+ */
+export type PhiTextControlInputRef = InputRef;
+export type PhiTextControlTextAreaRef = TextAreaRef;
 export type PhiTextInputType = "text" | "url" | "phone" | "email" | "password" | "search" | "digits";