@phis/ui 0.2.1 → 0.3.0

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/tours";
 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";

package/components/controls/phi-theme-scope-control.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+/**
+ * A region drawn in a theme of its own, beside the one the page wears.
+ *
+ * The Theme workspace shows a draft before it is published: the Controls inside this scope take the
+ * draft's tokens and component tokens, everything outside keeps the Site's. Nothing is inherited from the
+ * surrounding theme, so a token the draft leaves out is the primitive's default rather than the live
+ * Site's value bleeding into the preview.
+ *
+ * `scope` names the region in the CSS variable key. The key also hashes the mode and every token, so two
+ * drafts that differ in one value never share cached variables -- the reason a scope must not hand its
+ * own key in.
+ */
+export declare function PhiThemeScopeControl({ scope, mode, token, components, children, }: {
+    scope: string;
+    mode: PhiThemeMode;
+    /** The resolved alias tokens the region is drawn with. */
+    token: Record<string, unknown>;
+    /** Per-component token overrides, as the theme helpers produce them. */
+    components?: Record<string, Record<string, unknown>>;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/components/controls/phi-theme-scope-control.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { ConfigProvider } from "antd";
+import { createPhiAntdThemeCssVarKey } from "../../theme/phi-antd-token-resolver";
+/**
+ * A region drawn in a theme of its own, beside the one the page wears.
+ *
+ * The Theme workspace shows a draft before it is published: the Controls inside this scope take the
+ * draft's tokens and component tokens, everything outside keeps the Site's. Nothing is inherited from the
+ * surrounding theme, so a token the draft leaves out is the primitive's default rather than the live
+ * Site's value bleeding into the preview.
+ *
+ * `scope` names the region in the CSS variable key. The key also hashes the mode and every token, so two
+ * drafts that differ in one value never share cached variables -- the reason a scope must not hand its
+ * own key in.
+ */
+export function PhiThemeScopeControl({ scope, mode, token, components, children, }) {
+    const theme = useMemo(() => ({
+        inherit: false,
+        cssVar: {
+            prefix: "ant",
+            key: createPhiAntdThemeCssVarKey(scope, { mode, token, components }),
+        },
+        token,
+        components: components,
+    }), [components, mode, scope, token]);
+    return _jsx(ConfigProvider, { theme: theme, children: children });
+}

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

@@ -0,0 +1,32 @@
+import type { PhiTimelineTone } from "@phis/contracts/timeline";
+export type PhiTimelineControlItem = {
+    key: string;
+    title?: string;
+    content: string;
+    /**
+     * When it happened, already in words. The Control does not format a date: the Widget or the Module
+     * reading the record knows the locale and how precise the moment has to be.
+     */
+    time?: string;
+    /** A Phi icon name, drawn in place of the dot. */
+    icon?: string;
+    /** What the entry's mark says about it; the Theme decides the colour. Absent is the primary mark. */
+    tone?: PhiTimelineTone;
+    /** Still under way: the mark spins. Ant Design's `pending` is this, on an entry of its own. */
+    pending?: boolean;
+};
+export type PhiTimelineControlProps = {
+    items: readonly PhiTimelineControlItem[];
+    /** Which side the entries stand on; `alternate` takes turns. */
+    placement?: "start" | "end" | "alternate";
+    ariaLabel?: string;
+};
+/**
+ * What happened, in order: a ticket's history, the revisions of a Page, the stages of an order.
+ *
+ * A Control of its own rather than a pass-through: Ant Design's entries take nodes and free colours, and
+ * a Timeline here is a record a Widget stores or a Module reads, so its entries are words and tones.
+ * The time stands in Ant Design's title column when the entry has no title of its own, and in front of
+ * the title otherwise -- one column, so that `alternate` still has a side to put it on.
+ */
+export declare function PhiTimelineControl({ items, placement, ariaLabel, }: PhiTimelineControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,33 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Timeline } from "antd";
+import { PHI_COLOR } from "../../theme/antd-css-var-contract";
+import { PhiIcon } from "../shell/phi-icon";
+/*
+ * Ant Design colours four marks by name and takes anything else as a CSS colour. The Theme's own tokens
+ * go in as that colour, so a tone follows the Theme the way a text tone does.
+ */
+const PHI_TIMELINE_TONE_COLOR = {
+    secondary: PHI_COLOR.textTertiary,
+    success: PHI_COLOR.success,
+    warning: PHI_COLOR.warning,
+    danger: PHI_COLOR.error,
+};
+/**
+ * What happened, in order: a ticket's history, the revisions of a Page, the stages of an order.
+ *
+ * A Control of its own rather than a pass-through: Ant Design's entries take nodes and free colours, and
+ * a Timeline here is a record a Widget stores or a Module reads, so its entries are words and tones.
+ * The time stands in Ant Design's title column when the entry has no title of its own, and in front of
+ * the title otherwise -- one column, so that `alternate` still has a side to put it on.
+ */
+export function PhiTimelineControl({ items, placement = "start", ariaLabel, }) {
+    return (_jsx(Timeline, { "aria-label": ariaLabel, mode: placement, items: items.map((item) => ({
+            key: item.key,
+            title: item.title && item.time ? `${item.time} · ${item.title}` : item.title ?? item.time,
+            content: item.content,
+            icon: item.icon ? _jsx(PhiIcon, { name: item.icon, size: "inherit" }) : undefined,
+            color: item.tone ? PHI_TIMELINE_TONE_COLOR[item.tone] : undefined,
+            loading: item.pending,
+        })) }));
+}

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

@@ -12,6 +12,7 @@ export type PhiToolbarControlItem = {
     type?: PhiButtonType;
     danger?: boolean;
     disabled?: boolean;
+    readOnly?: boolean;
     loading?: boolean;
     visible?: boolean;
     badge?: PhiControlBadgePresentation;

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

@@ -7,7 +7,15 @@ import { PhiCompactGroupControl } from "./phi-compact-group-control";
 export function PhiToolbarControl({ items = [], children, compact = true, wrap = false, showLabels = false, disabled, size, style, onActivate, }) {
     const controls = items
         .filter((item) => item.visible !== false)
-        .map((item) => (_jsx(PhiButtonControl, { ariaLabel: item.ariaLabel, label: (item.showLabel ?? (showLabels || !item.icon)) ? item.label : null, tooltip: item.tooltip, icon: item.icon, type: item.type, danger: item.danger, disabled: disabled || item.disabled, loading: item.loading, size: size, badge: item.badge, onClick: onActivate ? () => onActivate(item.key) : undefined }, item.key)));
+        .map((item) => {
+        const labelShown = item.showLabel ?? (showLabels || !item.icon);
+        return (_jsx(PhiButtonControl, { ariaLabel: item.ariaLabel, label: labelShown ? item.label : null, 
+            /*
+             * A button showing only its icon shows its label on hover: not a tooltip it lacks, but the
+             * words the toolbar is keeping out of sight. A tooltip of its own comes first.
+             */
+            tooltip: item.tooltip ?? (labelShown ? undefined : item.label), icon: item.icon, type: item.type, danger: item.danger, disabled: disabled || item.disabled, readOnly: item.readOnly, loading: item.loading, size: size, badge: item.badge, onClick: onActivate ? () => onActivate(item.key) : undefined }, item.key));
+    });
     /*
      * Compact decides, and `wrap` is the spaced row's question alone.
      *

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

@@ -0,0 +1,41 @@
+import type { PhiTourLabels, PhiTourPlacement } from "../../types/tours";
+/**
+ * One step as it is presented: text already in the viewer's language, and the target already resolved by
+ * the owning Controller (design/TOURS.md).
+ *
+ * `target` is `null` for a step that is deliberately centered -- never for one whose target was not
+ * found; the Controller skips or stops such a step before it gets here.
+ */
+export type PhiTourControlStep = {
+    key: string;
+    title: string;
+    description?: string;
+    target: (() => HTMLElement | null) | null;
+    placement?: PhiTourPlacement;
+};
+export type PhiTourControlProps = {
+    open: boolean;
+    /** Index into `steps`. Presentation order, not identity -- the Controller keeps the step's key. */
+    current: number;
+    steps: readonly PhiTourControlStep[];
+    labels: PhiTourLabels;
+    /** Dim everything but the target. On by default: the point of a step is where it points. */
+    mask?: boolean;
+    /** Whether the highlighted target may be used during the step. */
+    disabledInteraction?: boolean;
+    onStepChange: (index: number) => void;
+    /** Closing by the close button or Escape -- a dismissal, never a completion. */
+    onClose: () => void;
+    onFinish: () => void;
+};
+/**
+ * A guided Tour's presentation, and the only place Ant Design `Tour` is used.
+ *
+ * It holds no workflow. Which step is current, whether the Tour is open, what was completed or dismissed
+ * and whether a target is ready are the owning Controller's; this draws what it is given and reports what
+ * the viewer did. Nothing here resolves an address, navigates or writes progress.
+ *
+ * Every button label is passed in, because Ant Design's own "Next", "Previous" and "Finish" come from its
+ * locale bundle -- a second translation source the Site's label sets cannot reach.
+ */
+export declare function PhiTourControl({ open, current, steps, labels, mask, disabledInteraction, onStepChange, onClose, onFinish, }: PhiTourControlProps): import("react").JSX.Element;