@phis/ui 0.4.1 → 0.4.3

package/components/media/phi-site-font-assets.js

@@ -1,10 +1,12 @@
 "use client";
-import { isPhiRecord } from "../../helpers/is-record";
 import { useEffect, useMemo, useState } from "react";
 import { PhiMediaKind } from "../../constants/media";
 import { createPhiAssetUri } from "../../types/references";
 import { usePhiCollectionProvider } from "../widgets/client/shared/phi-collection-provider";
 import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
+import { readPhiFontMetricsFields } from "./media-font-metrics";
+import { readPhiMediaAssetTiles } from "./phi-image-preview-data";
+import { createPhiResponseReader } from "../widgets/config/strict-config-reader";
 /**
  * The typefaces a Site owns, as something a font slot can be set to.
  *
@@ -19,12 +21,9 @@ import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
 /** Enough for any Site's own lettering; a ceiling rather than a page size. */
 const PHI_SITE_FONT_ASSET_LIMIT = 100;
 function readFontAssetMetrics(asset) {
-    const meta = asset.meta?.font;
-    if (!isPhiRecord(meta))
-        return null;
-    const record = meta;
-    // The management tile carries `meta` as stored; only a shape with its unit grid is worth drawing from.
-    return typeof record.unitsPerEm === "number" && record.unitsPerEm > 0 ? record : null;
+    // The management tile carries `meta` as stored, and the server stored every field of the metrics.
+    return createPhiResponseReader(asset.meta ?? {}, `The stored metrics of Asset ${asset.id}`, "meta")
+        .object("font", readPhiFontMetricsFields) ?? null;
 }
 function readFontAssetLabel(asset) {
     const family = readFontAssetMetrics(asset)?.familyName;
@@ -68,7 +67,7 @@ export function usePhiSiteFontAssets(enabled = true) {
                 setError(data.error);
                 return;
             }
-            setAssets(data.items.filter((item) => Boolean(item)));
+            setAssets(readPhiMediaAssetTiles(data.items));
         }).catch((cause) => {
             if (abortController.signal.aborted)
                 return;

package/components/overlays/phi-overlay-container-client.js

@@ -60,6 +60,13 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
     const [runtimeControlSizeOverride, setRuntimeControlSizeOverride] = useState(null);
     const [runtimeSizeOverride, setRuntimeSizeOverride] = useState(null);
     const [runtimeTitleOverride, setRuntimeTitleOverride] = useState(null);
+    /*
+     * Whether work the Overlay holds is under way -- a Form in the Body saving. While it is, a reader's
+     * dismissal (close button, mask, Escape) is not taken: closing would abandon the save's answer. A
+     * `close` sent on purpose still closes, which is how a Form that went through ends its dialog. Told
+     * through the `busy` input by whoever knows, so a dialog needs no Controller to refuse a close.
+     */
+    const [busy, setBusy] = useState(false);
     const runtimeControlSize = runtimeControlSizeOverride?.config === config
         ? runtimeControlSizeOverride.value
         : null;
@@ -106,6 +113,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         // A failed load is forgotten on close, so the next open asks the server again.
         if (!nextOpen)
             setLoadedZones((current) => current && "failure" in current ? null : current);
+        // A closed Overlay holds no work; a busy state left behind would refuse the next dismissal.
+        if (!nextOpen)
+            setBusy(false);
         setOpen(nextOpen);
     }, []);
     /*
@@ -200,6 +210,9 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         else if (route.capabilityId === "close") {
             updateOpen(false);
         }
+        else if (route.capabilityId === "busy" && signal.valueType === "boolean") {
+            setBusy(signal.value === true);
+        }
         else if (route.capabilityId === "toggle") {
             updateOpen(typeof signal.value === "boolean" ? signal.value : !open);
         }
@@ -229,12 +242,14 @@ export function PhiOverlayContainerClient({ overlayId, overlayType, config: rawC
         receiver,
     }), [receiver, signalScope]), receiver);
     const requestClose = useCallback((source) => {
+        if (busy)
+            return;
         if (config.closeMode === "request") {
             emitCapability("closeRequest", { source });
             return;
         }
         updateOpen(false);
-    }, [config.closeMode, emitCapability, updateOpen]);
+    }, [busy, config.closeMode, emitCapability, updateOpen]);
     // An Overlay's window is simply "open", which is why it can share the rule with a Carousel whose
     // window is several slots wide.
     const shouldRenderContent = shouldPhiCmsContentStayMounted({

package/components/regions/presets/phi-settings-page-shell-tree.js

@@ -4,7 +4,7 @@ import { createPhiCmsPresetNodes } from "../../../helpers/cms-preset-nodes";
 import { PHI_SPACE } from "../../../theme/antd-css-var-contract";
 import { PHI_LAYOUT } from "../../../theme/phi-tokens";
 import { createPhiPresetCmsInstanceIdMap } from "../../../types/cms-instance-id";
-import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress } from "../../../types/signals";
+import { PHI_SIGNAL_VALUE_SCHEMAS, createPhiSignalAddress, createPhiSignalSubcontrolAddress, } from "../../../types/signals";
 import { buildPhiBasePageContentScaffold, PHI_BASE_PAGE_LAYOUT_NODE_ID } from "./phi-base-page-layout";
 import { PHI_DIALOG_BODY_CONFIG, PHI_DIALOG_COMMANDS_CONFIG } from "../../../helpers/cms-dialog";
 /**
@@ -252,6 +252,29 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                                     valueType: "none",
                                     receiver: overlayAddress,
                                 },
+                                /*
+                                 * While the save is under way the dialog refuses a reader's dismissal, and the Save
+                                 * button shows that it is working -- the two things a Controller would otherwise be
+                                 * mounted for (OVERLAYS.md, "Runtime and signaling").
+                                 */
+                                {
+                                    routeKey: `${overlay.nodeKey}-busy`,
+                                    capabilityId: "submitting",
+                                    scope: "page",
+                                    channel: "busy",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: overlayAddress,
+                                },
+                                {
+                                    routeKey: `${overlay.nodeKey}-submit-loading`,
+                                    capabilityId: "submitting",
+                                    scope: "page",
+                                    channel: "loading",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: createPhiSignalSubcontrolAddress("cms", widgets[`${overlay.nodeKey}Commands`], "submit"),
+                                },
                                 ...(extraSignalRoutes?.emits ?? []),
                             ],
                             listens: [
@@ -315,6 +338,17 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                                     receiver: formAddress,
                                 },
                             ],
+                            listens: [
+                                {
+                                    routeKey: `${overlay.nodeKey}-commands-submit-loading`,
+                                    capabilityId: "loading",
+                                    scope: "page",
+                                    channel: "loading",
+                                    action: "change",
+                                    valueType: "boolean",
+                                    receiver: createPhiSignalSubcontrolAddress("cms", widgets[`${overlay.nodeKey}Commands`], "submit"),
+                                },
+                            ],
                         },
                     },
                 }),
@@ -344,6 +378,10 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                  * the provider somebody looked at before.
                  */
                 mountPolicy: "remount",
+                /*
+                 * `immediate`, because nothing is mounted to answer a close request; while the Form saves, its
+                 * `submitting` route sets this Overlay `busy`, and a busy Overlay does not take a dismissal.
+                 */
                 closeMode: "immediate",
                 openActionKey: overlay.openActionKey,
                 signalRoutes: {
@@ -371,6 +409,15 @@ export function buildPhiSettingsPageShellTree({ page, ownerModuleId, presetKey,
                             valueType: "none",
                             receiver: createPhiSignalAddress("cms", overlayIds[overlay.nodeKey]),
                         },
+                        {
+                            routeKey: `${overlay.nodeKey}-busy`,
+                            capabilityId: "busy",
+                            scope: "page",
+                            channel: "busy",
+                            action: "change",
+                            valueType: "boolean",
+                            receiver: createPhiSignalAddress("cms", overlayIds[overlay.nodeKey]),
+                        },
                     ],
                 },
             },

package/components/runtime/runtime-controller-materialization.js

@@ -39,7 +39,18 @@ export function materializePhiWidgetRuntimeControllerSettings({ widget, tree, ow
     if (!plugin.requiredRuntimeControllers) {
         return [];
     }
-    const config = plugin.parseConfig(widget.config);
+    /*
+     * A Widget whose config cannot be read asks for no Controller. It is not rendered either: the renderer
+     * meets the same error in the Widget's own place, leaves it out of a live page and shows it in the
+     * Builder. Thrown here, outside any block, it took the whole page with it.
+     */
+    let config;
+    try {
+        config = plugin.parseConfig(widget.config);
+    }
+    catch {
+        return [];
+    }
     const settingsByKey = new Map();
     for (const requirement of plugin.requiredRuntimeControllers({ widget, tree, config })) {
         const setting = {

package/components/state/scoped-state-store.js

@@ -1,5 +1,5 @@
 "use client";
-import { useRef, useSyncExternalStore } from "react";
+import { useCallback, useRef, useSyncExternalStore } from "react";
 const scopedStateStoreKey = "__phiScopedStateStores__";
 function normalizeScopedStateKey(scopeKey) {
     return scopeKey.trim() || "default";
@@ -92,7 +92,12 @@ export function createScopedStateStore(storeId, createDefaultState) {
     }
     function useStore(scopeKey) {
         const normalizedScopeKey = normalizeScopedStateKey(scopeKey);
-        return useSyncExternalStore((listener) => subscribe(normalizedScopeKey, listener), () => getSnapshot(normalizedScopeKey), () => getHydrationSnapshot(normalizedScopeKey));
+        /*
+         * Held per scope. An inline `subscribe` is a new function every render, and `useSyncExternalStore`
+         * unsubscribes and subscribes again for each new one.
+         */
+        const subscribeToScope = useCallback((listener) => subscribe(normalizedScopeKey, listener), [normalizedScopeKey]);
+        return useSyncExternalStore(subscribeToScope, () => getSnapshot(normalizedScopeKey), () => getHydrationSnapshot(normalizedScopeKey));
     }
     function useStoreSelector(scopeKey, selector) {
         const normalizedScopeKey = normalizeScopedStateKey(scopeKey);
@@ -124,14 +129,26 @@ export function createScopedStateStore(storeId, createDefaultState) {
             selectedHydrationSnapshotRef.current = { source, selector, selected };
             return selected;
         };
-        return useSyncExternalStore((listener) => subscribe(normalizedScopeKey, listener), getSelectedSnapshot, getSelectedHydrationSnapshot);
+        const subscribeToScope = useCallback((listener) => subscribe(normalizedScopeKey, listener), [normalizedScopeKey]);
+        return useSyncExternalStore(subscribeToScope, getSelectedSnapshot, getSelectedHydrationSnapshot);
     }
     function reset(scopeKey) {
         patch(scopeKey, () => createDefaultState(normalizeScopedStateKey(scopeKey)));
     }
+    /*
+     * Forgets a scope's state. A component still mounted on it keeps its subscription on the entry it
+     * subscribed to, so dropping that entry left it listening to nothing: the next write went into a new
+     * entry nobody was told about. With listeners, the entry stays and starts over from the default
+     * instead, and they hear it.
+     */
     function deleteScope(scopeKey) {
         const normalizedScopeKey = normalizeScopedStateKey(scopeKey);
         const bucket = getScopedBucket();
+        const entry = bucket.get(normalizedScopeKey);
+        if (entry && entry.listeners.size > 0) {
+            replace(normalizedScopeKey, createDefaultState(normalizedScopeKey));
+            return;
+        }
         bucket.delete(normalizedScopeKey);
     }
     return {

package/components/tables/client/phi-table-binding.d.ts

@@ -22,7 +22,8 @@ export declare function usePhiTableBinding({ source, initialQuery, externalQuery
     resource: PhiTableProviderResourceDescriptor | null;
     bindingError: string | null;
     rows: readonly TableRow[];
-    total: number;
+    total: number | null;
+    hasMore: boolean;
     summary: Readonly<Record<string, PhiTableSummaryValue>>;
     contractError: string | null;
     loading: boolean;

package/components/tables/client/phi-table-binding.js

@@ -76,7 +76,14 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         expandedRowIdentities: initialQuery.expandedRowIdentities,
     }));
     const [rows, setRows] = useState([]);
-    const [total, setTotal] = useState(0);
+    /*
+     * The number of rows the whole query has, where the Provider counts them (`query.total` on its
+     * resource), and `null` where it does not. Counting is a query of its own on a large table, so a
+     * Provider answers it only where a Table shows it; the rows on this page are never put in its place.
+     */
+    const [total, setTotal] = useState(null);
+    /** Whether a page follows this one, for a Table that pages without a count. */
+    const [hasMore, setHasMore] = useState(false);
     const [summary, setSummary] = useState({});
     const [queryLoading, setQueryLoading] = useState(Boolean(source));
     const [pendingMutationTargets, setPendingMutationTargets] = useState(() => new Set());
@@ -102,6 +109,30 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
             controller.abort();
         mutationControllers.current.clear();
     }, []);
+    /*
+     * A new source starts from nothing, and it does so in the render that brought it.
+     *
+     * The reset used to run in a microtask after the effects, so the query effect below had already
+     * fetched the new source with the old page and cursor -- one request thrown away on every source or
+     * `bindingParamsChange`. Adjusting state while rendering is React's way to follow a prop: the effects
+     * of this render see page 1 already. It also leaves the first render alone, so an `initialQuery` page
+     * and `initialExpandedRowIdentities` are no longer reset away on mount.
+     */
+    const [renderedSourceKey, setRenderedSourceKey] = useState(sourceKey);
+    if (renderedSourceKey !== sourceKey) {
+        setRenderedSourceKey(sourceKey);
+        setPendingMutationTargets(new Set());
+        setRows([]);
+        setTotal(null);
+        setHasMore(false);
+        setSummary({});
+        setSelectedRowIdentities([]);
+        setExpandedRowIdentities([]);
+        setQuery((current) => ({ ...current, page: 1, cursor: null }));
+        setQueryLoading(sourceKey !== "null");
+        setError(null);
+    }
+    // What a render cannot reset: requests in flight and the bookkeeping kept beside state.
     useEffect(() => {
         for (const controller of mutationControllers.current)
             controller.abort();
@@ -109,21 +140,6 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         latestMutationByTarget.current.clear();
         pendingMutationCountsByTarget.current.clear();
         rowsRef.current = [];
-        let cancelled = false;
-        queueMicrotask(() => {
-            if (cancelled)
-                return;
-            setPendingMutationTargets(new Set());
-            setRows([]);
-            setTotal(0);
-            setSummary({});
-            setSelectedRowIdentities([]);
-            setExpandedRowIdentities([]);
-            setQuery((current) => ({ ...current, page: 1, cursor: null }));
-            setQueryLoading(sourceKey !== "null");
-            setError(null);
-        });
-        return () => { cancelled = true; };
     }, [sourceKey]);
     /*
      * Held by content, not identity: a caller that writes the object inline hands in a new one every
@@ -158,7 +174,8 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         if (data.rows.some((row) => readPhiTableRowIdentity(row, resource.rowIdentityPath) == null)) {
             setRows([]);
             rowsRef.current = [];
-            setTotal(0);
+            setTotal(null);
+            setHasMore(false);
             setSummary({});
             setQueryLoading(false);
             setError(new PhiTableProviderError("missing-row-identity", `Table Provider row is missing identity field "${resource.rowIdentityPath}".`));
@@ -168,7 +185,8 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         if (summaryError) {
             setRows([]);
             rowsRef.current = [];
-            setTotal(0);
+            setTotal(null);
+            setHasMore(false);
             setSummary({});
             setQueryLoading(false);
             setError(new PhiTableProviderError("invalid-summary", summaryError));
@@ -176,7 +194,11 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         }
         rowsRef.current = data.rows;
         setRows(data.rows);
-        setTotal(data.total ?? data.rows.length);
+        // A resource that does not page answers every row at once, so its rows are its count.
+        const pages = resource.query.pagination === "offset" || resource.query.pagination === "cursor";
+        setTotal(data.total ?? (pages ? null : data.rows.length));
+        const pageSize = data.pageSize ?? resolvedQuery.pageSize;
+        setHasMore(data.nextCursor != null || (data.total == null && pageSize != null && data.rows.length >= pageSize));
         setSummary(data.summary ?? {});
         setQueryLoading(false);
         setError(null);
@@ -188,7 +210,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
             setSelectedRowIdentities((current) => current.filter((identity) => available.has(String(identity))));
         }
         onDataRef.current?.(data);
-    }, [preserveSelectedRowIdentities, resource]);
+    }, [preserveSelectedRowIdentities, resolvedQuery.pageSize, resource]);
     useEffect(() => {
         if (!source || !provider || !resource || resourceError)
             return;
@@ -254,7 +276,8 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
                 if (!background) {
                     setRows([]);
                     rowsRef.current = [];
-                    setTotal(0);
+                    setTotal(null);
+                    setHasMore(false);
                     setSummary({});
                 }
                 setQueryLoading(false);
@@ -505,6 +528,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, f
         bindingError,
         rows,
         total,
+        hasMore,
         summary,
         contractError: resourceError,
         loading: queryLoading && !bindingError && !resourceError,

package/components/trees/client/phi-tree-binding.js

@@ -104,19 +104,27 @@ export function usePhiTreeBinding({ source, initialQuery = PHI_TREE_DEFAULT_INIT
             controllers.clear();
         };
     }, []);
+    /*
+     * A new source, or new defaults, start the tree over -- in the render that brought them, so the query
+     * effect below asks once, with the reset query, instead of first with the old one.
+     *
+     * The search a reader typed stays. Resetting it to the initial query showed the unfiltered tree for a
+     * moment and fetched it, and the Widget's debounce put the search back 250 ms later for a third request:
+     * a new binding parameter narrows what the tree is about, not what the reader is looking for.
+     */
+    const [renderedResetInputs, setRenderedResetInputs] = useState({ sourceKey, initialQuery, defaultExpandedNodeIdentities });
+    if (renderedResetInputs.sourceKey !== sourceKey ||
+        renderedResetInputs.initialQuery !== initialQuery ||
+        renderedResetInputs.defaultExpandedNodeIdentities !== defaultExpandedNodeIdentities) {
+        setRenderedResetInputs({ sourceKey, initialQuery, defaultExpandedNodeIdentities });
+        setNodes([]);
+        setSelectedNodeIdentities([]);
+        setCheckedNodeIdentities([]);
+        setExpandedNodeIdentities(defaultExpandedNodeIdentities);
+        setQuery((current) => (current.search ? { ...initialQuery, search: current.search } : initialQuery));
+    }
     useEffect(() => {
         expandedInitialSnapshot.current = false;
-        let cancelled = false;
-        queueMicrotask(() => {
-            if (cancelled)
-                return;
-            setNodes([]);
-            setSelectedNodeIdentities([]);
-            setCheckedNodeIdentities([]);
-            setExpandedNodeIdentities(defaultExpandedNodeIdentities);
-            setQuery(initialQuery);
-        });
-        return () => { cancelled = true; };
     }, [defaultExpandedNodeIdentities, initialQuery, sourceKey]);
     useEffect(() => {
         if (!source || !provider || !resource)

package/components/widgets/client/bullet-list-entries-editor.d.ts

@@ -0,0 +1,26 @@
+import { type CSSProperties } from "react";
+import { type PhiBulletListEntry, type PhiResolvedBulletListStyle } from "../shared/bullet-list-vocabulary";
+export type PhiBulletListEntriesEditorProps = {
+    entries: readonly PhiBulletListEntry[];
+    listStyle: PhiResolvedBulletListStyle;
+    /** Absent, the entries are only shown: a read-only canvas. */
+    onCommit?: (entries: PhiBulletListEntry[]) => void;
+    /** Whether a click on an entry's marker steps its state on (`PHI_BULLET_LIST_ENTRY_STATES`). */
+    states?: boolean;
+    /** Each entry's field, apart from what every field here is: borderless, its text's own type. */
+    fieldStyle?: CSSProperties;
+};
+/**
+ * A list written in place, entry by entry, as the Widgets that carry one edit it.
+ *
+ * Every entry is a text field standing where the entry stands, so the list is set as it will be read.
+ * What is typed stays here until the field is left, and the Builder's history records one change per
+ * entry rather than one per keystroke. What changes the list's shape is written at once, with what was
+ * typed so far: Enter opens an entry after this one, Backspace in an empty entry removes it, Tab and
+ * Shift+Tab move an entry a level down and up, and -- where the list has `states` -- a click on the
+ * marker steps the entry from included to excluded to neither. Waiting for the blur would let the entry
+ * jump back while the tree is drawn again.
+ *
+ * A list with no entries still offers one empty field, so there is something to type into.
+ */
+export declare function PhiBulletListEntriesEditor({ entries, listStyle, onCommit, states, fieldStyle, }: PhiBulletListEntriesEditorProps): import("react").JSX.Element;

package/components/widgets/client/bullet-list-entries-editor.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { PhiBulletListControl } from "../../controls/phi-bullet-list-control";
+import { PhiTextControl } from "../../controls/phi-text-control";
+import { buildPhiBulletListTree, nextPhiBulletListEntryState, resolvePhiBulletListLevel, } from "../shared/bullet-list-vocabulary";
+/**
+ * A list written in place, entry by entry, as the Widgets that carry one edit it.
+ *
+ * Every entry is a text field standing where the entry stands, so the list is set as it will be read.
+ * What is typed stays here until the field is left, and the Builder's history records one change per
+ * entry rather than one per keystroke. What changes the list's shape is written at once, with what was
+ * typed so far: Enter opens an entry after this one, Backspace in an empty entry removes it, Tab and
+ * Shift+Tab move an entry a level down and up, and -- where the list has `states` -- a click on the
+ * marker steps the entry from included to excluded to neither. Waiting for the blur would let the entry
+ * jump back while the tree is drawn again.
+ *
+ * A list with no entries still offers one empty field, so there is something to type into.
+ */
+export function PhiBulletListEntriesEditor({ entries, listStyle, onCommit, states = false, fieldStyle, }) {
+    const [draftState, setDraftState] = useState(() => ({ source: entries, value: [...entries] }));
+    const draft = draftState.source === entries ? draftState.value : [...entries];
+    const shown = draft.length > 0 || !onCommit ? draft : [{ text: "" }];
+    const listRef = useRef(null);
+    function focusEntry(index) {
+        requestAnimationFrame(() => {
+            const field = listRef.current?.querySelectorAll("textarea")[index];
+            field?.focus();
+            field?.setSelectionRange(field.value.length, field.value.length);
+        });
+    }
+    function commit(next) {
+        // The empty field an empty list offers is not an entry until something is typed into it.
+        if (entries.length === 0 && next.length === 1 && next[0].text === "" && !next[0].state)
+            return;
+        setDraftState({ source: entries, value: next });
+        if (JSON.stringify(next) !== JSON.stringify(entries))
+            onCommit?.(next);
+    }
+    function updateText(index, text) {
+        const next = [...shown];
+        next[index] = { ...next[index], text };
+        setDraftState({ source: entries, value: next });
+    }
+    function shiftLevel(index, delta) {
+        const entry = shown[index];
+        if (!entry)
+            return;
+        const level = resolvePhiBulletListLevel((entry.level ?? 1) + delta);
+        if (level === (entry.level ?? 1))
+            return;
+        const { level: _level, ...rest } = entry;
+        void _level;
+        commit(shown.map((item, itemIndex) => (itemIndex === index ? (level > 1 ? { ...rest, level } : rest) : item)));
+        focusEntry(index);
+    }
+    function insertAfter(index) {
+        const entry = shown[index];
+        const level = entry?.level;
+        commit([...shown.slice(0, index + 1), { text: "", ...(level ? { level } : {}) }, ...shown.slice(index + 1)]);
+        focusEntry(index + 1);
+    }
+    function remove(index) {
+        commit(shown.filter((_, itemIndex) => itemIndex !== index));
+        focusEntry(Math.max(0, index - 1));
+    }
+    function stepState(index) {
+        const entry = shown[index];
+        if (!entry)
+            return;
+        const { state: _state, ...rest } = entry;
+        void _state;
+        const state = nextPhiBulletListEntryState(entry.state);
+        commit(shown.map((item, itemIndex) => (itemIndex === index ? (state === "neutral" ? rest : { ...rest, state }) : item)));
+    }
+    return (_jsx("div", { ref: listRef, style: { width: "100%", minWidth: 0 }, children: _jsx(PhiBulletListControl, { listStyle: listStyle, 
+            // Each entry is a borderless text field, whose first line stands at the field's height.
+            markerLineHeight: "var(--ant-control-height)", items: buildPhiBulletListTree(shown, (item, index) => (_jsx(PhiTextControl, { presentation: "textarea", value: item.text, readOnly: !onCommit, variant: "borderless", placeholder: `Item ${index + 1}`, autoSize: { minRows: 1, maxRows: 6 }, onChange: (value) => updateText(index, value ?? ""), onBlur: () => commit(shown), onKeyDown: (event) => {
+                    if (!onCommit)
+                        return;
+                    if (event.key === "Tab") {
+                        event.preventDefault();
+                        shiftLevel(index, event.shiftKey ? -1 : 1);
+                    }
+                    else if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing) {
+                        event.preventDefault();
+                        insertAfter(index);
+                    }
+                    else if (event.key === "Backspace" && item.text === "" && shown.length > 1) {
+                        event.preventDefault();
+                        remove(index);
+                    }
+                }, style: {
+                    paddingInline: 0,
+                    paddingBlock: 0,
+                    borderRadius: 0,
+                    borderWidth: 0,
+                    backgroundColor: "transparent",
+                    resize: "none",
+                    color: "inherit",
+                    ...fieldStyle,
+                } })), states && onCommit ? (_entry, index) => stepState(index) : undefined) }) }));
+}

package/components/widgets/config/choice-shared.js

@@ -1,5 +1,5 @@
 import { parsePhiControlOptionsProviderConfig, readPhiControlOptions, } from "../../controls/phi-control-options";
-import { readBoolean, readString } from "./parser-primitives";
+import { createPhiConfigReader } from "./strict-config-reader";
 import { PHI_CONTROL_PRESENTATION_FIELDS, PHI_CONTROL_STATE_FIELDS, parsePhiControlConfig, } from "./control-signal-config";
 export function buildPhiChoiceControlOptionFields(editorPlacement = "inspector") {
     return [{
@@ -28,9 +28,10 @@ export function buildPhiChoiceControlOptionFields(editorPlacement = "inspector")
 }
 export const PHI_CHOICE_CONTROL_OPTION_FIELDS = buildPhiChoiceControlOptionFields();
 export function parsePhiChoiceOptionsConfig(config) {
+    const reader = createPhiConfigReader(config);
     return {
-        optionsProvider: parsePhiControlOptionsProviderConfig(config.optionsProvider),
-        options: readPhiControlOptions(config.options),
+        optionsProvider: reader.value("optionsProvider", "an options provider", (value) => parsePhiControlOptionsProviderConfig(value) ?? undefined) ?? null,
+        options: reader.value("options", "a list of options", (value) => (Array.isArray(value) ? readPhiControlOptions(value) : undefined)) ?? readPhiControlOptions(undefined),
     };
 }
 export const PHI_CHOICE_CONTROL_CONFIG_FIELDS = [
@@ -46,27 +47,25 @@ export const PHI_CHOICE_CONTROL_VALUE_MODE_FIELD = {
         { value: "stack-slot-index", label: "Stack Slot Index" },
     ],
 };
-function readPhiChoiceValueMode(value) {
-    return readString(value) === "stack-slot-index" ? "stack-slot-index" : "raw";
-}
 export function parsePhiChoiceControlConfig(config) {
     const controlState = parsePhiControlConfig(config, {
         key: "choice",
     });
+    const reader = createPhiConfigReader(config);
     return {
         ...controlState,
-        label: readString(config.label),
-        description: readString(config.description),
-        value: readString(config.value),
-        placeholder: readString(config.placeholder),
-        presentation: readString(config.presentation) === "autocomplete" ? "autocomplete" : "select",
-        allowCustom: readBoolean(config.allowCustom),
+        label: reader.string("label"),
+        description: reader.string("description"),
+        value: reader.string("value"),
+        placeholder: reader.string("placeholder"),
+        presentation: reader.oneOf("presentation", ["select", "autocomplete"]) ?? "select",
+        allowCustom: reader.boolean("allowCustom"),
         ...parsePhiChoiceOptionsConfig(config),
     };
 }
 export function parsePhiStackChoiceControlConfig(config) {
     return {
         ...parsePhiChoiceControlConfig(config),
-        valueMode: readPhiChoiceValueMode(config.valueMode),
+        valueMode: createPhiConfigReader(config).oneOf("valueMode", ["raw", "stack-slot-index"]) ?? "raw",
     };
 }

package/components/widgets/config/command-buttons.d.ts

@@ -2,7 +2,11 @@ import type { PhiCommandButtonConfig } from "../../../types/core-widget-placemen
 import type { PhiCmsConfigField } from "../../../types";
 import type { PhiCmsConfigFieldVisibilityRule } from "../../../types/cms-plugins";
 import { type PhiAccessViewer, type PhiRoleProviderId } from "../../../types/access";
-export declare function readPhiCommandButtons(value: unknown): PhiCommandButtonConfig[];
+/**
+ * A Widget's buttons. Strict (`strict-config-reader.ts`): a button without a key or without an emit is
+ * an error naming it, not a button left out.
+ */
+export declare function readPhiCommandButtons(value: unknown, path?: string): PhiCommandButtonConfig[];
 export declare function filterPhiCommandButtonsForViewer(buttons: readonly PhiCommandButtonConfig[], viewer: PhiAccessViewer, ownerProviderId?: PhiRoleProviderId | null): PhiCommandButtonConfig[];
 /**
  * A new button: the first free `buttonN` key, labelled after it, sending its key as the command. The