@phis/ui 0.2.1 → 0.4.0

package/components/widgets/builder/phi-static-rows-editor.js

@@ -0,0 +1,190 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { stopPhiOverlayEvent } from "../../../helpers/overlay-events";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { PhiButtonControl } from "../../controls/phi-button-control";
+import { PhiAlertControl } from "../../controls/phi-alert-control";
+import { PhiDialogControl } from "../../controls/phi-dialog-control";
+import { PhiIcon } from "../../shell/phi-icon";
+import { PhiWidgetIconPickerButton } from "../client/shared/phi-widget-icon-picker";
+import { usePhiWidgetScaffoldPopup } from "../client/shared/phi-widget-scaffold-popup";
+import { formatPhiAuthoringToolsLabel } from "../label-types/authoring-tools";
+import { PhiTableProviderClient } from "../client/shared/phi-table-provider";
+import { usePhiTableBinding } from "../../tables/client/phi-table-binding";
+import { PhiTableBindingControl } from "../../tables/client/phi-table-binding-control";
+import { PhiFlexControl } from "../../controls/phi-flex-control";
+import { PhiCollectionHeaderControl } from "../../controls/phi-collection-header-control";
+import { PhiToolbarControl } from "../../controls/phi-toolbar-control";
+import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
+const ROW_ID = "rowId";
+function readRowName(row, spec) {
+    return String(row[spec.nameField] || row[spec.keyField] || "");
+}
+function PhiStaticRowsTableProvider({ spec, providerKey, resource, rows, setRows, nextRowId, children, }) {
+    const registration = useMemo(() => ({
+        key: providerKey,
+        resources: [resource],
+        query: async () => ({ rows, total: rows.length }),
+        mutate: async (request) => {
+            if (request.kind === "field") {
+                const rowId = String(request.rowIdentity);
+                if (request.fieldKey === spec.keyField) {
+                    const key = String(request.proposedValue ?? "").trim();
+                    if (!key || rows.some((row) => row[ROW_ID] !== rowId && String(row[spec.keyField] ?? "").trim() === key)) {
+                        return { status: "rejected", invalidation: "none", errorCode: "duplicate-value", message: spec.duplicateKeyMessage };
+                    }
+                }
+                setRows((current) => current.map((row) => row[ROW_ID] === rowId
+                    ? { ...row, [request.fieldKey]: request.proposedValue }
+                    : row));
+                return { status: "accepted", invalidation: "none", canonicalValue: request.proposedValue };
+            }
+            if (request.kind === "row-move") {
+                setRows((current) => {
+                    const sourceIndex = current.findIndex((row) => row[ROW_ID] === String(request.movedRowIdentity));
+                    const targetIdentity = request.beforeRowIdentity ?? request.afterRowIdentity;
+                    const targetIndex = current.findIndex((row) => row[ROW_ID] === String(targetIdentity));
+                    if (sourceIndex < 0 || targetIndex < 0)
+                        return current;
+                    const next = [...current];
+                    const [moved] = next.splice(sourceIndex, 1);
+                    const resolvedTargetIndex = next.findIndex((row) => row[ROW_ID] === String(targetIdentity));
+                    next.splice(resolvedTargetIndex + (request.afterRowIdentity == null ? 0 : 1), 0, moved);
+                    return next;
+                });
+                return { status: "accepted", invalidation: "view" };
+            }
+            if (request.kind === "action" && request.actionKey === "add") {
+                setRows((current) => [...current, { ...spec.createRow(current), [ROW_ID]: nextRowId() }]);
+                return { status: "accepted", invalidation: "view" };
+            }
+            if (request.kind === "action" && request.rowIdentity != null &&
+                (request.actionKey === "toggle" || request.actionKey === "delete")) {
+                const rowId = String(request.rowIdentity);
+                if (request.actionKey === "delete") {
+                    setRows((current) => current.filter((row) => row[ROW_ID] !== rowId));
+                    return { status: "accepted", invalidation: "view" };
+                }
+                const toggleField = spec.toggleField;
+                if (!toggleField) {
+                    return { status: "rejected", invalidation: "none", errorCode: "unsupported-mutation" };
+                }
+                const row = rows.find((candidate) => candidate[ROW_ID] === rowId);
+                setRows((current) => current.map((candidate) => candidate[ROW_ID] === rowId
+                    ? { ...candidate, [toggleField]: !candidate[toggleField] }
+                    : candidate));
+                return { status: "accepted", invalidation: "none", rowPatch: { [toggleField]: !row?.[toggleField] } };
+            }
+            return { status: "rejected", invalidation: "none", errorCode: "unsupported-mutation" };
+        },
+    }), [nextRowId, providerKey, resource, rows, setRows, spec]);
+    return _jsx(PhiTableProviderClient, { registration: registration, children: children });
+}
+function PhiStaticRowsTable({ spec, providerKey, resource, disabled, }) {
+    const { labels, toggleField } = spec;
+    const source = useMemo(() => ({ providerKey, resourceKey: resource.resourceKey }), [providerKey, resource]);
+    const binding = usePhiTableBinding({ source, defaultPageSize: 100 });
+    const columns = useMemo(() => {
+        const rowLocked = (row) => disabled || (toggleField != null && row[toggleField] === true);
+        const commit = (row, fieldKey, originalValue, proposedValue) => {
+            void binding.commitField({ kind: "field", rowIdentity: String(row[ROW_ID]), fieldKey, originalValue, proposedValue });
+        };
+        const fieldColumns = spec.columns.map((column) => {
+            const sizing = column.width === "fill" ? { mode: "fill" } : { mode: "fixed", width: column.width };
+            if (column.editor === "icon") {
+                return {
+                    title: column.title, key: column.key, fieldPath: column.key, sizing,
+                    render: (_value, row) => (_jsx(PhiWidgetIconPickerButton, { value: typeof row[column.key] === "string" ? String(row[column.key]) : undefined, buttonAriaLabel: `${column.title}: ${readRowName(row, spec)}`, buttonIcon: row[column.key] ? _jsx(PhiIcon, { name: String(row[column.key]) }) : _jsx(PhiIcon, { name: "appstore", size: "inherit" }), placement: "right", disabled: rowLocked(row), onChange: (icon) => commit(row, column.key, row[column.key], icon ?? "") })),
+                };
+            }
+            return {
+                title: column.title, key: column.key, fieldPath: column.key, sizing,
+                editor: {
+                    type: column.editor,
+                    ...(column.required ? { required: true } : {}),
+                    ...(column.options ? { options: column.options } : {}),
+                },
+                isEditorDisabled: rowLocked,
+                onCommit: (row, originalValue, proposedValue) => commit(row, column.key, originalValue, proposedValue),
+            };
+        });
+        const actions = {
+            title: labels.columnActions, key: "actions", role: "actions", fieldPath: ROW_ID,
+            sizing: { mode: "fixed", width: toggleField ? 72 : 40 }, fixed: "right",
+            render: (_value, row) => (_jsxs(PhiFlexControl, { align: "center", gap: 0, style: { display: "inline-flex" }, children: [toggleField ? (_jsx(PhiButtonControl, { type: "text", size: "small", icon: row[toggleField] ? _jsx(PhiIcon, { name: "eye-invisible", size: "inherit" }) : _jsx(PhiIcon, { name: "eye", size: "inherit" }), ariaLabel: formatPhiAuthoringToolsLabel((row[toggleField] ? labels.enableRow : labels.disableRow) ?? "", readRowName(row, spec)), disabled: disabled, tooltip: row[toggleField] ? labels.enable : labels.disable, onClick: () => { void binding.executeAction({ kind: "action", actionKey: "toggle", rowIdentity: String(row[ROW_ID]), selectedRowIdentities: [], query: binding.resolvedQuery }); } })) : null, _jsx(PhiButtonControl, { type: "text", danger: true, size: "small", icon: _jsx(PhiIcon, { name: "delete", size: "inherit" }), ariaLabel: formatPhiAuthoringToolsLabel(labels.deleteRow, readRowName(row, spec)), disabled: disabled, tooltip: labels.delete, onClick: () => { void binding.executeAction({ kind: "action", actionKey: "delete", rowIdentity: String(row[ROW_ID]), selectedRowIdentities: [], query: binding.resolvedQuery }); } })] })),
+        };
+        return [...fieldColumns, actions];
+    }, [binding, disabled, labels, spec, toggleField]);
+    /*
+     * Add stands over the table, as every collection's tools do (TABLES.md, "Collection Header"): a
+     * compact toolbar on the right, `space.sm` above the table.
+     */
+    return _jsxs(_Fragment, { children: [binding.error ? _jsx(PhiAlertControl, { level: "error", showIcon: true, title: binding.error.message }) : null, _jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.sm, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiCollectionHeaderControl, { toolbar: (_jsx(PhiToolbarControl, { compact: true, size: "small", disabled: disabled, items: [{ key: "add", label: labels.add, showLabel: true, icon: _jsx(PhiIcon, { name: "plus", size: "inherit" }) }], onActivate: () => { void binding.executeAction({ kind: "action", actionKey: "add", selectedRowIdentities: [], query: binding.resolvedQuery }); } })) }), _jsx(PhiTableBindingControl, { rows: binding.rows, fields: binding.resource?.fields ?? [], columns: columns, rowIdentityPath: ROW_ID, columnOrder: [...spec.columns.map((column) => column.key), "actions"], sortingMode: "none", sorts: [], pagination: false, size: "small", emptyText: labels.empty, layout: { mode: "fixed", overflowX: "auto" }, loading: binding.loading, rowReordering: { enabled: !disabled, onMove: (move) => { void binding.moveRow({ kind: "row-move", ...move }); } } })] })] });
+}
+/** A Widget's static rows: a tool button that opens them in a dialog and hands back the applied rows. */
+export function PhiStaticRowsToolButton({ spec, rows: storedRows, disabled = false, onApply, }) {
+    const { labels } = spec;
+    const popup = usePhiWidgetScaffoldPopup();
+    const { providerKey } = spec;
+    const resource = useMemo(() => ({
+        resourceKey: spec.resourceKey,
+        title: labels.title,
+        rowIdentityPath: ROW_ID,
+        fields: [
+            { key: ROW_ID, title: "ID", type: "string", required: true },
+            ...spec.columns.map((column) => ({
+                key: column.key,
+                title: column.title,
+                type: column.editor === "icon" ? "string" : column.editor,
+                mutable: true,
+                ...(column.required ? { required: true } : {}),
+            })),
+        ],
+        query: { sorting: "none", pagination: "none" },
+        actions: [
+            { key: "add", title: labels.add, scope: "resource" },
+            ...(spec.toggleField ? [{ key: "toggle", title: labels.disable ?? "", scope: "row" }] : []),
+            { key: "delete", title: labels.delete, scope: "row" },
+        ],
+        rowOrdering: "flat",
+    }), [labels, spec.columns, spec.resourceKey, spec.toggleField]);
+    const rowSequenceRef = useRef(storedRows.length);
+    const [open, setOpen] = useState(false);
+    const [rows, setRows] = useState([]);
+    const [error, setError] = useState(null);
+    const createEditorRows = useCallback(() => storedRows.map((row, index) => ({
+        ...row,
+        [ROW_ID]: `static-${spec.resourceKey}-${index + 1}`,
+    })), [spec.resourceKey, storedRows]);
+    const nextRowId = useCallback(() => {
+        rowSequenceRef.current += 1;
+        return `static-${spec.resourceKey}-${rowSequenceRef.current}`;
+    }, [spec.resourceKey]);
+    const closeEditor = () => {
+        setOpen(false);
+        setError(null);
+    };
+    const discardEditor = () => {
+        rowSequenceRef.current = storedRows.length;
+        setRows(createEditorRows());
+        closeEditor();
+    };
+    const applyEditor = () => {
+        const nextError = spec.validate(rows);
+        if (nextError) {
+            setError(nextError);
+            return;
+        }
+        onApply(rows.map(({ [ROW_ID]: _rowId, ...row }) => spec.normalizeRow(row)));
+        closeEditor();
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(PhiButtonControl, { ariaLabel: labels.edit, icon: _jsx(PhiIcon, { name: spec.buttonIcon, size: "inherit" }), type: "text", size: "small", disabled: disabled, style: { width: 24, minWidth: 24, height: 24, padding: 0 }, onClick: () => {
+                    setError(null);
+                    rowSequenceRef.current = storedRows.length;
+                    setRows(createEditorRows());
+                    setOpen(true);
+                } }), _jsx(PhiDialogControl, { open: open, title: labels.title, controlSize: "large", mask: { appearance: "normal", allowOutsideInteraction: false, closable: false }, mountPolicy: "remount", rootClassName: popup.rootClassName, onDismiss: discardEditor, alert: error ? { level: "error", showIcon: true, title: error } : null, actions: [
+                    { key: "cancel", label: labels.cancel, onClick: discardEditor },
+                    { key: "apply", label: labels.apply, type: "primary", onClick: applyEditor },
+                ], children: _jsx("div", { onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { minWidth: 0 }, children: _jsx(PhiStaticRowsTableProvider, { spec: spec, providerKey: providerKey, resource: resource, rows: rows, setRows: setRows, nextRowId: nextRowId, children: _jsx(PhiStaticRowsTable, { spec: spec, providerKey: providerKey, resource: resource, disabled: disabled }) }) }) })] }));
+}

package/components/widgets/builder/phi-static-timeline-picker.d.ts

@@ -0,0 +1,7 @@
+import { type PhiTimelineEntry } from "@phis/contracts/timeline";
+/** A Timeline's static entries, edited in a dialog from its scaffold toolbar. */
+export declare function PhiStaticTimelineToolButton({ entries, disabled, onApply, }: {
+    entries: readonly PhiTimelineEntry[];
+    disabled?: boolean;
+    onApply: (entries: PhiTimelineEntry[]) => void;
+}): import("react").JSX.Element;

package/components/widgets/builder/phi-static-timeline-picker.js

@@ -0,0 +1,91 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { isPhiTimelineTone, readPhiTimelineEntry } from "@phis/contracts/timeline";
+import { usePhiAuthoringToolsLabels } from "../client/shared/phi-authoring-tools-labels";
+import { createPhiSharedRuntimeDataProviderKey } from "../../../constants/runtime-data-provider-key";
+import { PhiStaticRowsToolButton, } from "./phi-static-rows-editor";
+const PHI_STATIC_TIMELINE_TABLE_PROVIDER_KEY = createPhiSharedRuntimeDataProviderKey("tables", "static-timeline-editor");
+function readText(row, key) {
+    return typeof row[key] === "string" ? row[key].trim() : "";
+}
+function createStaticTimelineSpec(labels) {
+    return {
+        providerKey: PHI_STATIC_TIMELINE_TABLE_PROVIDER_KEY,
+        resourceKey: "timeline",
+        keyField: "key",
+        nameField: "title",
+        buttonIcon: "history",
+        duplicateKeyMessage: labels.keysUnique,
+        columns: [
+            { key: "icon", title: labels.columnIcon, editor: "icon", width: 48 },
+            { key: "key", title: labels.columnKey, editor: "string", required: true, width: 112 },
+            /* A date the Widget formats for the reader, or words of the author's own beside it. */
+            { key: "at", title: labels.columnAt, editor: "date", width: 152 },
+            { key: "time", title: labels.columnTime, editor: "string", width: 128 },
+            { key: "title", title: labels.columnTitle, editor: "string", width: 160 },
+            { key: "content", title: labels.columnContent, editor: "string", width: "fill" },
+            {
+                key: "tone",
+                title: labels.columnTone,
+                editor: "enum",
+                width: 128,
+                options: [
+                    { value: "", label: labels.toneDefault },
+                    { value: "secondary", label: labels.toneSecondary },
+                    { value: "success", label: labels.toneSuccess },
+                    { value: "warning", label: labels.toneWarning },
+                    { value: "danger", label: labels.toneDanger },
+                ],
+            },
+            { key: "pending", title: labels.columnPending, editor: "boolean", width: 96 },
+        ],
+        createRow: (rows) => {
+            const keys = new Set(rows.map((row) => row.key));
+            let index = rows.length + 1;
+            while (keys.has(`entry${index}`))
+                index += 1;
+            return { key: `entry${index}`, content: "" };
+        },
+        /* Read as the contract reads a stored entry, so what the editor applies is what the Widget keeps. */
+        normalizeRow: (row) => readPhiTimelineEntry({
+            ...row,
+            tone: isPhiTimelineTone(row.tone) ? row.tone : undefined,
+        }) ?? { key: readText(row, "key"), content: "" },
+        validate: (rows) => {
+            if (rows.some((row) => !readText(row, "key")))
+                return labels.keyRequired;
+            const keys = rows.map((row) => readText(row, "key"));
+            return new Set(keys).size === keys.length ? null : labels.keysUnique;
+        },
+        labels: {
+            edit: labels.edit,
+            title: labels.title,
+            add: labels.addEntry,
+            delete: labels.deleteEntry,
+            cancel: "",
+            apply: "",
+            empty: labels.empty,
+            columnActions: "",
+            deleteRow: labels.deleteRow,
+        },
+    };
+}
+/** A Timeline's static entries, edited in a dialog from its scaffold toolbar. */
+export function PhiStaticTimelineToolButton({ entries, disabled = false, onApply, }) {
+    const toolsLabels = usePhiAuthoringToolsLabels();
+    const spec = useMemo(() => {
+        const base = createStaticTimelineSpec(toolsLabels.staticTimeline);
+        /* Cancel, Apply and the actions column read as they do in the options dialog beside it. */
+        return {
+            ...base,
+            labels: {
+                ...base.labels,
+                cancel: toolsLabels.staticOptions.cancel,
+                apply: toolsLabels.staticOptions.apply,
+                columnActions: toolsLabels.staticOptions.columnActions,
+            },
+        };
+    }, [toolsLabels]);
+    return _jsx(PhiStaticRowsToolButton, { spec: spec, rows: entries, disabled: disabled, onApply: onApply });
+}

package/components/widgets/client/description-editor-sections.d.ts

@@ -15,7 +15,7 @@ export type PhiDescriptionEditorStoredText = {
     title: string;
     description: string;
     asideTitle: string;
-    asideItems: readonly string[];
+    asideItems: readonly unknown[];
 };
 export type PhiDescriptionEditorSections = {
     /** The eyebrow sits in its pill; otherwise it is a plain field. */

package/components/widgets/client/external-document-editor.js

@@ -1,16 +1,22 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
+import { useEffect, useEffectEvent } from "react";
+import { logRuntimeEvent } from "../../../net/log";
 import { PhiAlertControl } from "../../controls/phi-alert-control";
 import { PhiFlexControl } from "../../controls/phi-flex-control";
 import { PhiTypographyControl } from "../../controls/phi-typography-control";
 export function PhiExternalDocumentEditor({ format, sourceUrl, sourceLocale, onSourceLocaleChange, }) {
-    const detectionUrlRef = useRef("");
+    /*
+     * The answer goes to whatever callback stands when it arrives. The callback is a new function on every
+     * render of the caller, and as an effect dependency it aborted the request each time -- with a ref
+     * that then refused to ask again, the locale was never set, under StrictMode not once.
+     */
+    const reportSourceLocale = useEffectEvent((detected) => onSourceLocaleChange?.(detected));
+    const canReport = onSourceLocaleChange != null;
     useEffect(() => {
-        if (!sourceUrl || sourceLocale?.trim() || !onSourceLocaleChange || detectionUrlRef.current === sourceUrl) {
+        if (!sourceUrl || sourceLocale?.trim() || !canReport) {
             return;
         }
-        detectionUrlRef.current = sourceUrl;
         const controller = new AbortController();
         void fetch("/api/site/translation/detect", {
             method: "POST",
@@ -19,14 +25,23 @@ export function PhiExternalDocumentEditor({ format, sourceUrl, sourceLocale, onS
             body: JSON.stringify({ sourceUrl, format }),
             signal: controller.signal,
         }).then(async (response) => {
-            if (!response.ok)
-                return;
+            if (!response.ok) {
+                throw new Error(`Source locale detection answered ${response.status}.`);
+            }
             const payload = await response.json();
-            onSourceLocaleChange(typeof payload.sourceLocale === "string" && payload.sourceLocale.trim()
+            reportSourceLocale(typeof payload.sourceLocale === "string" && payload.sourceLocale.trim()
                 ? payload.sourceLocale.trim()
                 : "und");
-        }).catch(() => undefined);
+        }).catch((error) => {
+            if (controller.signal.aborted)
+                return;
+            // Nothing is set, and the field stays open for the author; the reason is in the log.
+            logRuntimeEvent("warn", "translation.detect.failed", {
+                message: "The source locale of an external document could not be detected.",
+                error,
+            });
+        });
         return () => controller.abort();
-    }, [format, onSourceLocaleChange, sourceLocale, sourceUrl]);
+    }, [canReport, format, sourceLocale, sourceUrl]);
     return (_jsx("div", { style: { width: 520, height: 260, maxWidth: "100%", minWidth: 0, minHeight: 0, display: "flex" }, children: _jsx(PhiAlertControl, { level: "info", showIcon: true, title: `External ${format} source`, description: _jsxs(PhiFlexControl, { vertical: true, gap: "var(--ant-padding-xs)", style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiTypographyControl, { children: "This widget renders the configured external document. Edit its URL and source locale in the widget settings." }), _jsx(PhiTypographyControl, { code: true, copyable: { text: sourceUrl }, style: { wordBreak: "break-all" }, children: sourceUrl || "No Source URL configured." })] }) }) }));
 }

package/components/widgets/client/html-editor-image-node.d.ts

@@ -9,13 +9,6 @@ export type SerializedPhiHtmlImageNode = Spread<{
     width?: PhiCssLength | null;
     height?: PhiCssLength | null;
 }, SerializedLexicalNode>;
-/**
- * The stored `src` stays the `phis:asset/<id>` reference the server resolves at render time; a browser
- * cannot load that scheme, so the authoring DOM shows the same Asset through the authorized delivery
- * endpoint the other authoring surfaces already read. Nothing here resolves a reference for a rendered
- * page.
- */
-export declare function resolvePhiHtmlImageAuthoringSrc(src: string): string;
 export declare class PhiHtmlImageNode extends DecoratorNode<ReactNode> {
     __src: string;
     __alt: string;
@@ -43,4 +36,3 @@ export declare class PhiHtmlImageNode extends DecoratorNode<ReactNode> {
     decorate(): import("react").JSX.Element;
 }
 export declare function $createPhiHtmlImageNode(src: string, alt?: string, attributes?: Partial<Omit<PhiHtmlImageAttributes, "alt">>): PhiHtmlImageNode;
-export declare function $isPhiHtmlImageNode(node: unknown): node is PhiHtmlImageNode;

package/components/widgets/client/html-editor-image-node.js

@@ -20,7 +20,7 @@ import { PhiFlexControl } from "../../controls/phi-flex-control";
  * endpoint the other authoring surfaces already read. Nothing here resolves a reference for a rendered
  * page.
  */
-export function resolvePhiHtmlImageAuthoringSrc(src) {
+function resolvePhiHtmlImageAuthoringSrc(src) {
     const reference = readPhiInternalReference(src);
     return reference?.kind === "asset" ? buildPhiMediaAssetContentDeliveryUrl(reference.assetId) ?? src : src;
 }
@@ -315,6 +315,6 @@ function PhiHtmlImageDecorator({ nodeKey, src, alt, title, width, height, }) {
 export function $createPhiHtmlImageNode(src, alt = "", attributes) {
     return $applyNodeReplacement(new PhiHtmlImageNode(src, alt, attributes));
 }
-export function $isPhiHtmlImageNode(node) {
+function $isPhiHtmlImageNode(node) {
     return node instanceof PhiHtmlImageNode;
 }

package/components/widgets/client/html-editor.js

@@ -216,7 +216,18 @@ function PhiHtmlWidgetEditorContentSyncPlugin({ html, latestHtmlRef, }) {
  */
 function PhiHtmlWidgetEditorChangePlugin({ html, latestHtmlRef, onChange, }) {
     const [editor] = useLexicalComposerContext();
+    /*
+     * The state the editor last reached, kept and not yet read. Serialising it to HTML and sanitising that
+     * twice is the expensive half of every update, and the result was wanted only on blur -- so it is made
+     * there, once, from the last state, and a keystroke costs the editor nothing beyond itself.
+     */
+    const pendingStateRef = useRef(null);
     const emitChange = useEffectEvent(() => {
+        const pendingState = pendingStateRef.current;
+        if (pendingState) {
+            pendingStateRef.current = null;
+            latestHtmlRef.current = pendingState.read(() => sanitizePhiHtmlWidgetMarkup($generateHtmlFromNodes(editor), { allowInternalReferences: true }));
+        }
         const nextHtml = latestHtmlRef.current;
         if (nextHtml === html) {
             return;
@@ -225,9 +236,9 @@ function PhiHtmlWidgetEditorChangePlugin({ html, latestHtmlRef, onChange, }) {
     });
     useEffect(() => {
         return editor.registerUpdateListener(({ editorState }) => {
-            latestHtmlRef.current = editorState.read(() => sanitizePhiHtmlWidgetMarkup($generateHtmlFromNodes(editor), { allowInternalReferences: true }));
+            pendingStateRef.current = editorState;
         });
-    }, [editor, latestHtmlRef]);
+    }, [editor]);
     useEffect(() => {
         return editor.registerCommand(BLUR_COMMAND, () => {
             emitChange();

package/components/widgets/client/shared/core-options-providers.js

@@ -1,14 +1,11 @@
 "use client";
 import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../../../../constants/core-data-provider-keys";
-import { buildPhiSpacingScaleOptions, } from "../../config/spacing-options";
-import { createPhiStaticControlOptionsProviderClient, readPhiControlOptionsProviderParam, } from "../../../controls/phi-options-provider";
+import { buildPhiSpacingScaleOptions } from "../../config/spacing-options";
+import { createPhiStaticControlOptionsProviderClient, } from "../../../controls/phi-options-provider";
 import { readPhiSiteLocaleOptions } from "../../../forms/site-locales-config";
-function resolveSpacingScaleOptionsProvider(context) {
-    const family = readPhiControlOptionsProviderParam(context.optionsProvider, "family") === "margin"
-        ? "margin"
-        : "padding";
+function resolveSpacingScaleOptionsProvider() {
     return {
-        options: buildPhiSpacingScaleOptions(family),
+        options: buildPhiSpacingScaleOptions(),
     };
 }
 export const PhiSpacingScaleOptionsProviderClient = createPhiStaticControlOptionsProviderClient({

package/components/widgets/client/shared/description-items.d.ts

@@ -1,6 +1,7 @@
+import type { PhiBulletListEntry } from "../../shared/bullet-list-vocabulary";
 /**
- * The item list at a new length: kept entries stay, new ones start empty, a shorter list drops its tail.
- * Out-of-range and empty input answers with the list unchanged -- clearing the field on the way to
- * typing a new number must not be read as "no items".
+ * The item list at a new length: kept entries stay, new ones start empty at the level of the entry before
+ * them, a shorter list drops its tail. Out-of-range and empty input answers with the list unchanged --
+ * clearing the field on the way to typing a new number must not be read as "no items".
  */
-export declare function resizePhiDescriptionItems(items: readonly string[] | null | undefined, count: number | null | undefined): any[];
+export declare function resizePhiDescriptionItems(items: readonly PhiBulletListEntry[] | null | undefined, count: number | null | undefined): PhiBulletListEntry[];

package/components/widgets/client/shared/description-items.js

@@ -1,12 +1,17 @@
 /**
- * The item list at a new length: kept entries stay, new ones start empty, a shorter list drops its tail.
- * Out-of-range and empty input answers with the list unchanged -- clearing the field on the way to
- * typing a new number must not be read as "no items".
+ * The item list at a new length: kept entries stay, new ones start empty at the level of the entry before
+ * them, a shorter list drops its tail. Out-of-range and empty input answers with the list unchanged --
+ * clearing the field on the way to typing a new number must not be read as "no items".
  */
 export function resizePhiDescriptionItems(items, count) {
     const current = Array.isArray(items) ? [...items] : [];
     if (count == null || !Number.isFinite(count))
         return current;
     const nextCount = Math.max(0, Math.min(12, Math.trunc(count)));
-    return Array.from({ length: nextCount }, (_, index) => current[index] ?? "");
+    return Array.from({ length: nextCount }, (_, index) => {
+        if (current[index])
+            return current[index];
+        const level = current[current.length - 1]?.level;
+        return level ? { text: "", level } : { text: "" };
+    });
 }

package/components/widgets/client/shared/phi-choice-controller.d.ts

@@ -1,7 +1,7 @@
 import type { PhiSignalAddress } from "../../../../types";
 import { type PhiControlOption } from "../../../controls/phi-control-options";
 import type { PhiChoiceControlConfig, PhiStackChoiceControlConfig } from "../../config/choice-shared";
-export type PhiChoiceControlTypeKey = "select-box" | "segmented" | "tab-bar";
+export type PhiChoiceControlTypeKey = "select-box" | "segmented" | "steps" | "tab-bar";
 export type PhiChoiceControllerOptions<TConfig extends PhiChoiceControlConfig> = {
     config?: TConfig | null;
     signalsEnabled?: boolean;

package/components/widgets/client/shared/phi-choice-controller.js

@@ -1,8 +1,9 @@
 "use client";
+import { isPhiRecord } from "../../../../helpers/is-record";
 import { useEffect, useMemo, useState } from "react";
 import { findPhiSignalRoutesByCapabilityId } from "../../../../types/signals";
 import { readPhiControlOptions } from "../../../controls/phi-control-options";
-import { isPhiStackSignalMessage, PHI_STACK_META_SIGNAL_CHANNEL, resolvePhiStackSignalMessage, } from "../../../layouts/stack-signals";
+import { isPhiStackSignalMessage, PHI_STACK_META_SIGNAL_CHANNEL, readPhiStackSignalAddressKey, resolvePhiStackSignalMessage, } from "../../../layouts/stack-signals";
 import { usePhiSignalListener } from "../../../runtime/runtime-signal-bus";
 import { usePhiControlSignalController } from "./phi-control-signals";
 import { usePhiControlOptionsProvider } from "../../../controls/phi-options-provider";
@@ -42,7 +43,7 @@ export function usePhiChoiceController({ config, signalsEnabled = true, typeKey,
             if (capabilityId !== "options") {
                 return false;
             }
-            const value = signal.value && typeof signal.value === "object" && !Array.isArray(signal.value)
+            const value = isPhiRecord(signal.value)
                 ? signal.value.options
                 : undefined;
             setSentOptions({ source: configuredOptions, options: readPhiControlOptions(value) });
@@ -97,6 +98,12 @@ export function usePhiStackChoiceController({ config, signalsEnabled = true, typ
     const [stackOptions, setStackOptions] = useState([]);
     const value = state.source === fallbackValue ? state.value : fallbackValue;
     const stackMetaListenRoute = findPhiSignalRoutesByCapabilityId(config?.signalRoutes?.listens, "stackMeta")[0] ?? null;
+    /*
+     * The Stack this Choice follows: the one its `stackMeta` request is addressed to. Every Stack answers
+     * on the same broadcast, so without it two Stacks on one page would each overwrite the other's options
+     * and index here. A Choice whose request names no Stack follows none.
+     */
+    const followedStackKey = readPhiStackSignalAddressKey(findPhiSignalRoutesByCapabilityId(config?.signalRoutes?.emits, "stackMeta")[0]?.receiver);
     const controlSignals = usePhiControlSignalController({
         key: config?.key ?? defaultKey,
         sender,
@@ -118,7 +125,7 @@ export function usePhiStackChoiceController({ config, signalsEnabled = true, typ
         emitControlCapability("stackMeta", null);
     }, [emitControlCapability, signalsEnabled, stackMode]);
     usePhiSignalListener((signal) => {
-        if (!signalsEnabled || !stackMode || !stackMetaListenRoute) {
+        if (!signalsEnabled || !stackMode || !stackMetaListenRoute || !followedStackKey) {
             return;
         }
         if (signal.scope !== stackMetaListenRoute.scope ||
@@ -128,7 +135,7 @@ export function usePhiStackChoiceController({ config, signalsEnabled = true, typ
             return;
         }
         const message = resolvePhiStackSignalMessage(signal);
-        if (!isPhiStackSignalMessage(message) || signal.receiver !== "broadcast") {
+        if (!isPhiStackSignalMessage(message) || signal.receiver !== "broadcast" || message.key !== followedStackKey) {
             return;
         }
         setStackOptions(mapPhiStackSlotsToChoiceOptions(message) ?? []);

package/components/widgets/client/shared/phi-command-buttons-authoring-tools.d.ts

@@ -0,0 +1,11 @@
+import type { PhiCommandButtonConfig } from "../../../../types/core-widget-placements";
+import { type PhiCommandButtonBounds } from "../../config/command-buttons";
+/**
+ * The scaffold's tools for a Widget's command buttons: how many there are, and their order. The Command
+ * Toolbar and the Float Button count them alike and differ only in how many they allow.
+ */
+export declare function PhiCommandButtonsAuthoringTools({ buttons, bounds, onChange, }: {
+    buttons: readonly PhiCommandButtonConfig[];
+    bounds: PhiCommandButtonBounds;
+    onChange: (buttons: PhiCommandButtonConfig[]) => void;
+}): import("react").JSX.Element;

package/components/widgets/client/shared/phi-command-buttons-authoring-tools.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PhiButtonControl } from "../../../controls/phi-button-control";
+import { PhiPopoverControl } from "../../../controls/phi-popover-control";
+import { usePhiConfig } from "../../../root/phi-config-provider";
+import { PHI_COMMON_CONTROL_DEFAULT_LABELS } from "../../label-types/common-controls";
+import { usePhiWidgetScaffoldPopup } from "./phi-widget-scaffold-popup";
+import { usePhiAuthoringToolsLabels } from "./phi-authoring-tools-labels";
+import { PhiFlexControl } from "../../../controls/phi-flex-control";
+import { PhiTypographyControl } from "../../../controls/phi-typography-control";
+import { PhiCompactGroupControl } from "../../../controls/phi-compact-group-control";
+import { PhiIcon } from "../../../shell/phi-icon";
+import { PhiWidgetCountToolButton } from "./phi-widget-tool-buttons";
+import { resizePhiCommandButtons } from "../../config/command-buttons";
+function stopToolEvent(event) {
+    event.stopPropagation();
+}
+/* What a button is called here: its own label, else its action's, else its key. */
+function readButtonName(button) {
+    return button.label || (button.action ? PHI_COMMON_CONTROL_DEFAULT_LABELS.actions[button.action].label : "") || button.key;
+}
+function moveButton(buttons, index, direction) {
+    const targetIndex = index + direction;
+    if (targetIndex < 0 || targetIndex >= buttons.length) {
+        return buttons;
+    }
+    const nextButtons = [...buttons];
+    [nextButtons[index], nextButtons[targetIndex]] = [nextButtons[targetIndex], nextButtons[index]];
+    return nextButtons;
+}
+/**
+ * The scaffold's tools for a Widget's command buttons: how many there are, and their order. The Command
+ * Toolbar and the Float Button count them alike and differ only in how many they allow.
+ */
+export function PhiCommandButtonsAuthoringTools({ buttons, bounds, onChange, }) {
+    const labels = usePhiAuthoringToolsLabels();
+    const { token } = usePhiConfig();
+    const popup = usePhiWidgetScaffoldPopup();
+    return (_jsxs(PhiCompactGroupControl, { children: [_jsx(PhiWidgetCountToolButton, { count: buttons.length, min: bounds.min, max: bounds.max, label: labels.commands.buttons, onChange: (count) => onChange(resizePhiCommandButtons(buttons, count, bounds)) }), _jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: popup.getPopupContainer, rootClassName: popup.rootClassName, onOpenChange: popup.setOpen, content: (_jsx(PhiFlexControl, { vertical: true, gap: token.paddingXXS, style: { minWidth: 240 }, onClick: stopToolEvent, onPointerDown: stopToolEvent, children: buttons.length === 0 ? (_jsx(PhiTypographyControl, { type: "secondary", children: "No buttons" })) : buttons.map((button, index) => (_jsxs(PhiFlexControl, { align: "center", gap: token.paddingXXS, children: [_jsx(PhiTypographyControl, { ellipsis: true, style: { flex: "1 1 auto", minWidth: 0 }, children: readButtonName(button) }), _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: `Move ${readButtonName(button)} earlier`, disabled: index === 0, icon: _jsx(PhiIcon, { name: "arrow-up", size: "inherit" }), onClick: () => onChange([...moveButton(buttons, index, -1)]) }), _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: `Move ${readButtonName(button)} later`, disabled: index === buttons.length - 1, icon: _jsx(PhiIcon, { name: "arrow-down", size: "inherit" }), onClick: () => onChange([...moveButton(buttons, index, 1)]) }), _jsx(PhiButtonControl, { type: "text", size: "small", danger: true, ariaLabel: `Remove ${readButtonName(button)}`, disabled: buttons.length <= bounds.min, icon: _jsx(PhiIcon, { name: "delete", size: "inherit" }), onClick: () => onChange(buttons.filter((_, candidateIndex) => candidateIndex !== index)) })] }, button.key))) })), children: _jsx("span", { onClick: stopToolEvent, onPointerDown: stopToolEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: labels.commands.manageButtons, tooltip: labels.commands.manageButtons, disabled: buttons.length === 0, icon: _jsx(PhiIcon, { name: "menu", size: "inherit" }), onClick: () => undefined }) }) })] }));
+}

package/components/widgets/client/shared/phi-command-buttons.d.ts

@@ -0,0 +1,20 @@
+import type { PhiCmsInstanceId } from "../../../../types/cms-instance-id";
+import type { PhiCommandButtonConfig } from "../../../../types/core-widget-placements";
+import { type PhiSignalRouteSet } from "../../../../types/signals";
+import type { PhiToolbarControlItem } from "../../../controls/phi-toolbar-control";
+import type { PhiCommonControlLabels } from "../../label-types/common-controls";
+export type PhiCommandButtonsOptions = {
+    buttons: readonly PhiCommandButtonConfig[];
+    signalRoutes?: PhiSignalRouteSet | null;
+    blockId?: PhiCmsInstanceId | null;
+    labels?: PhiCommonControlLabels | null;
+    disabled?: boolean;
+    signalsEnabled?: boolean;
+};
+export type PhiCommandButtonsResult = {
+    items: PhiToolbarControlItem[];
+    /** The whole Widget's answer: disabled from outside, or switched off by `enabled/change`. */
+    disabled: boolean;
+    activate: (buttonKey: string) => void;
+};
+export declare function usePhiCommandButtons({ buttons, signalRoutes, blockId, labels, disabled, signalsEnabled, }: PhiCommandButtonsOptions): PhiCommandButtonsResult;