@phis/ui 0.2.1 → 0.3.0

package/components/widgets/config/background.js

@@ -1,11 +1,25 @@
+import { isPhiRecord } from "../../../helpers/is-record";
 import { buildPhiMediaAssetContentDeliveryUrl } from "../../../constants/media";
 import { resolvePhiImagePresentation, } from "../../media/image-presentation";
 import { readPhiMediaImageSourceConfig } from "./image-source-parser";
 import { readBoolean, readNumber, readString } from "./parser-primitives";
-import { isPhiGlassLayoutEffectId, isPhiLayoutEffectId, } from "../../../types/layout-style";
+import { isPhiBackgroundFilter, isPhiGlassLayoutEffectId, } from "../../../types/layout-style";
 import { composePhiLayoutEffectStyle, resolvePhiLayoutEffectStyle } from "../../../helpers/layout-style";
 import { PHI_DEFAULT_BACKGROUND_PATTERN_KEY, isPhiBackgroundPatternKey, } from "./background-pattern-contract";
 import { PHI_BACKGROUND_COLOR_OVERLAY_DEFAULT_INK, resolvePhiBackgroundColorLiveLayer, resolvePhiBackgroundNoiseLiveLayer, resolvePhiBackgroundPatternLiveLayer, } from "./background-pattern-live";
+import { readPhiCssLinearGradient } from "../../../helpers/css-linear-gradient";
+const PHI_BACKGROUND_DIRECTION_DEGREES = {
+    "to top": 0,
+    "to right": 90,
+    "to bottom": 180,
+    "to left": 270,
+};
+/** A direction as degrees, clockwise from the top the way CSS gradients count. */
+export function phiBackgroundDirectionToDegrees(direction) {
+    return direction.endsWith("deg")
+        ? Number.parseFloat(direction)
+        : PHI_BACKGROUND_DIRECTION_DEGREES[direction];
+}
 /**
  * Where an image Base may take its picture from, in authoring order. A surface narrows this list the
  * way it narrows `PHI_BACKGROUND_BASE_KINDS`: the Theme Root Background offers the Media library alone.
@@ -34,7 +48,7 @@ export function resolvePhiBackgroundParallaxDefaultStrength(travel) {
     return travel === "range" ? PHI_BACKGROUND_PARALLAX_DEFAULT_RANGE_STRENGTH : PHI_BACKGROUND_PARALLAX_DEFAULT_STRENGTH;
 }
 function readBackgroundResolvedAsset(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const raw = value;
@@ -60,7 +74,7 @@ function readBackgroundStops(value) {
         return undefined;
     }
     const stops = value.map((stop) => {
-        if (!stop || typeof stop !== "object" || Array.isArray(stop)) {
+        if (!isPhiRecord(stop)) {
             return null;
         }
         const raw = stop;
@@ -73,128 +87,13 @@ function readBackgroundStops(value) {
         ? stops
         : undefined;
 }
-function splitPhiBackgroundGradientStops(input) {
-    const stops = [];
-    let current = "";
-    let depth = 0;
-    for (const char of input) {
-        if (char === "(")
-            depth += 1;
-        if (char === ")")
-            depth = Math.max(0, depth - 1);
-        if (char === "," && depth === 0) {
-            stops.push(current.trim());
-            current = "";
-        }
-        else {
-            current += char;
-        }
-    }
-    if (current.trim())
-        stops.push(current.trim());
-    return stops;
-}
-const PHI_BACKGROUND_CSS_NUMBER = "[-+]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)";
-const PHI_BACKGROUND_CSS_ANGLE = new RegExp(`^(${PHI_BACKGROUND_CSS_NUMBER})(deg|grad|rad|turn)$`, "i");
-const PHI_BACKGROUND_CSS_STOP = new RegExp(`^(.+?)(?:\\s+(${PHI_BACKGROUND_CSS_NUMBER})%)?$`);
-const PHI_BACKGROUND_DEGREES_PER_UNIT = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 };
-/**
- * The first argument, when it is a direction.
- *
- * Only an angle or `to <side>` is one. Everything else is the first colour stop -- `red 0%` included,
- * which read as a direction used to swallow the first stop and fall back to `to right`. A direction the
- * Base cannot hold (a corner, an unreadable angle) is a problem rather than a stop.
- */
-function readPhiBackgroundGradientCssDirection(part) {
-    const side = part.match(/^to\s+(.+)$/i);
-    if (side) {
-        const target = side[1].trim().toLowerCase();
-        return target === "right" || target === "left" || target === "bottom" || target === "top"
-            ? { direction: `to ${target}` }
-            : { problem: `Gradient direction "${part}" is not supported; use an angle or one side.` };
-    }
-    const angle = part.match(PHI_BACKGROUND_CSS_ANGLE);
-    if (!angle) {
-        return null;
-    }
-    const unit = angle[2].toLowerCase();
-    const degrees = Number(angle[1]) * PHI_BACKGROUND_DEGREES_PER_UNIT[unit];
-    return Number.isFinite(degrees)
-        ? { direction: `${Math.round(degrees * 1000) / 1000}deg` }
-        : { problem: `Gradient angle "${part}" is not a number.` };
-}
-function readPhiBackgroundGradientCssStop(part) {
-    const match = part.match(PHI_BACKGROUND_CSS_STOP);
-    const color = match?.[1]?.trim();
-    if (!match || !color) {
-        return null;
-    }
-    // A colour is one token outside its parentheses; anything left over is a second position or a length.
-    let bare = color;
-    while (/\([^()]*\)/.test(bare))
-        bare = bare.replace(/\([^()]*\)/g, "");
-    if (/\s/.test(bare)) {
-        return null;
-    }
-    const percent = match[2] == null ? null : Number(match[2]);
-    return percent == null || Number.isFinite(percent) ? { color, percent } : null;
-}
-/**
- * Positions for stops that name none, the way CSS places them: the first at 0, the last at 100, and
- * any run in between evenly spaced between its neighbours.
- */
-function placePhiBackgroundGradientStops(stops) {
-    const percents = stops.map((stop) => stop.percent);
-    percents[0] ??= 0;
-    percents[percents.length - 1] ??= 100;
-    let previous = 0;
-    while (previous < percents.length - 1) {
-        let next = previous + 1;
-        while (percents[next] == null)
-            next += 1;
-        const start = percents[previous];
-        const end = percents[next];
-        for (let index = previous + 1; index < next; index += 1) {
-            percents[index] = start + ((end - start) * (index - previous)) / (next - previous);
-        }
-        previous = next;
-    }
-    return stops.map((stop, index) => ({ color: stop.color, percent: percents[index] }));
-}
 export function readPhiBackgroundGradientCss(css) {
-    const background = css.trim();
-    const kind = background.match(/^([a-z-]*gradient)\(/i)?.[1]?.toLowerCase();
-    if (!kind) {
+    const reading = readPhiCssLinearGradient(css);
+    if (!reading)
         return null;
-    }
-    if (kind !== "linear-gradient") {
-        return { problem: `A Background gradient is linear; "${kind}" is not supported.` };
-    }
-    if (!background.endsWith(")")) {
-        return { problem: "The gradient is not closed." };
-    }
-    const parts = splitPhiBackgroundGradientStops(background.slice("linear-gradient(".length, -1));
-    const direction = parts.length > 0 ? readPhiBackgroundGradientCssDirection(parts[0]) : null;
-    if (direction && "problem" in direction) {
-        return { problem: direction.problem };
-    }
-    const stopParts = direction ? parts.slice(1) : parts;
-    if (stopParts.length < 2) {
-        return { problem: "A gradient needs at least two colour stops." };
-    }
-    const stops = stopParts.map(readPhiBackgroundGradientCssStop);
-    const unreadable = stops.findIndex((stop) => stop === null);
-    if (unreadable >= 0) {
-        return { problem: `Gradient stop "${stopParts[unreadable]}" is not a colour with a percentage.` };
-    }
-    return {
-        gradient: {
-            kind: "gradient",
-            // What CSS draws when a gradient names no direction.
-            direction: direction?.direction ?? "to bottom",
-            stops: placePhiBackgroundGradientStops(stops),
-        },
-    };
+    return reading.gradient
+        ? { gradient: { kind: "gradient", ...reading.gradient } }
+        : { problem: reading.problem };
 }
 function parsePhiBackgroundImageCss(background) {
     if (!background.startsWith("url("))
@@ -219,7 +118,7 @@ function normalizePhiBackgroundBase(value) {
     if (typeof value === "string") {
         return readPhiBackgroundBaseCss(value);
     }
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return null;
     const raw = value;
     const kind = readString(raw.kind);
@@ -235,7 +134,6 @@ function normalizePhiBackgroundBase(value) {
         const normalized = {
             kind: "image",
             trusted: readBoolean(raw.trusted) ?? false,
-            blurDataUrl: readString(raw.blurDataUrl),
             // The projection wins; the raw value stays readable for content persisted before it existed.
             focalRect: resolvedAsset?.focalRect ?? raw.focalRect,
             resolvedAsset,
@@ -277,7 +175,7 @@ function readBackgroundPatternInk(value) {
         : null;
 }
 function readBackgroundOverlay(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return null;
     const raw = value;
     const kind = readString(raw.kind);
@@ -302,7 +200,7 @@ function readBackgroundOverlay(value) {
     const patternKey = isPhiBackgroundPatternKey(raw.patternKey)
         ? raw.patternKey
         : PHI_DEFAULT_BACKGROUND_PATTERN_KEY;
-    const rawValues = raw.values && typeof raw.values === "object" && !Array.isArray(raw.values)
+    const rawValues = isPhiRecord(raw.values)
         ? raw.values
         : {};
     const values = Object.fromEntries(Object.entries(rawValues).filter((entry) => {
@@ -319,7 +217,7 @@ function readBackgroundOverlay(value) {
     };
 }
 function readBackgroundMotion(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPhiRecord(value))
         return null;
     const raw = value;
     const mode = readString(raw.mode);
@@ -346,19 +244,19 @@ export function normalizePhiBackgroundWidgetConfig(config) {
         return {
             base: readPhiBackgroundBaseCss(config) ?? { kind: "none" },
             overlay: null,
-            effect: null,
+            filter: null,
             motion: null,
         };
     }
-    if (!config || typeof config !== "object" || Array.isArray(config)) {
-        return { base: { kind: "none" }, overlay: null, effect: null, motion: null };
+    if (!isPhiRecord(config)) {
+        return { base: { kind: "none" }, overlay: null, filter: null, motion: null };
     }
     const raw = config;
     const base = normalizePhiBackgroundBase(raw.base) ?? normalizePhiBackgroundBase(raw) ?? { kind: "none" };
     return {
         base,
         overlay: readBackgroundOverlay(raw.overlay),
-        effect: isPhiLayoutEffectId(raw.effect) ? raw.effect : null,
+        filter: isPhiBackgroundFilter(raw.filter) ? raw.filter : null,
         motion: base.kind === "image" ? readBackgroundMotion(raw.motion) : null,
     };
 }
@@ -457,10 +355,18 @@ export function resolvePhiBackgroundWidgetStyle(config) {
             ...baseRepeats,
         ].join(", ");
     }
-    return composePhiLayoutEffectStyle(style, resolvePhiLayoutEffectStyle({
-        effect: resolvePhiBackgroundEffect(normalized),
-        background: style.background ?? style.backgroundColor,
-    }));
+    /*
+     * Only a pane reaches the element. `blur` softens the paint itself, and a filter on the element would
+     * take the content along with it -- so it is applied where the paint has a layer of its own (see
+     * `resolvePhiBackgroundGroundFilter`), and a surface without one simply draws the paint unsoftened.
+     */
+    const filter = resolvePhiBackgroundFilter(normalized);
+    return composePhiLayoutEffectStyle(style, isPhiGlassLayoutEffectId(filter)
+        ? resolvePhiLayoutEffectStyle({
+            effect: filter,
+            background: style.background ?? style.backgroundColor,
+        })
+        : undefined);
 }
 /**
  * Whether this Background actually paints a ground.
@@ -471,8 +377,7 @@ export function resolvePhiBackgroundWidgetStyle(config) {
  * taking the Shell Chrome Overlay and from reading its own Shell-record colour: switching a Header's
  * glass off wrote exactly such a config and locked the Region out of everything.
  *
- * The Effect is not part of the question. A Region carries its own Effect beside the Background, and
- * the Builder nulls the one inside the config when it stores it.
+ * The Filter is not part of the question: a pane over nothing is not a ground somebody painted.
  */
 export function phiBackgroundWidgetConfigPaintsGround(config) {
     if (config == null) {
@@ -488,22 +393,54 @@ export function phiBackgroundWidgetConfigPaintsGround(config) {
  * that lets the layer beneath it come up. Both strengths work by thinning the Base until the filtered
  * backdrop reads through it, so both need a Base there is something to thin. An image or gradient base is not a pane, it is the material
  * itself, and there is nothing of it to see through -- the frost lands behind opaque paint and the
- * glass ground can only ever read as a wash laid over the picture. So the Effect is neither offered
- * nor honoured there. `blur` and `dim` act on the surface itself and stay valid on every base.
+ * glass ground can only ever read as a wash laid over the picture. So the pane is neither offered
+ * nor honoured there.
  */
 export function phiBackgroundBaseSupportsGlassEffect(base) {
     return base.kind !== "image" && base.kind !== "gradient";
 }
 /**
- * The Effect this Background actually renders, which is the configured one unless it is a pane the
- * base cannot express. A stored value is never rewritten; it simply resolves to no Effect.
+ * Whether `blur` has anything to soften: a picture, a gradient, or a patterned Overlay.
+ *
+ * A flat colour blurred is the same flat colour, so the Filter is neither offered nor honoured on one.
  */
-export function resolvePhiBackgroundEffect(config) {
+export function phiBackgroundSupportsBlur(config) {
+    return config.base.kind === "image"
+        || config.base.kind === "gradient"
+        || config.overlay?.kind === "pattern"
+        || config.overlay?.kind === "noise";
+}
+/** Whether this Background can render the given Filter at all; the Control offers what this allows. */
+export function phiBackgroundSupportsFilter(config, filter) {
+    return isPhiGlassLayoutEffectId(filter)
+        ? phiBackgroundBaseSupportsGlassEffect(config.base)
+        : phiBackgroundSupportsBlur(config);
+}
+/**
+ * The Filter this Background actually renders, which is the configured one unless the Background
+ * cannot express it. A stored value is never rewritten; it simply resolves to no Filter.
+ */
+export function resolvePhiBackgroundFilter(config) {
     const normalized = normalizePhiBackgroundWidgetConfig(config);
-    const effect = normalized.effect ?? null;
-    return isPhiGlassLayoutEffectId(effect) && !phiBackgroundBaseSupportsGlassEffect(normalized.base)
-        ? null
-        : effect;
+    const filter = normalized.filter ?? null;
+    return filter && phiBackgroundSupportsFilter(normalized, filter) ? filter : null;
+}
+/** The glass strength this Background frosts its backdrop with, if any. */
+export function resolvePhiBackgroundPane(config) {
+    const filter = resolvePhiBackgroundFilter(config);
+    return isPhiGlassLayoutEffectId(filter) ? filter : null;
+}
+/** How far `blur` softens the paint. One value, so a ground layer and its preview never disagree. */
+export const PHI_BACKGROUND_BLUR_RADIUS_PX = 6;
+export const PHI_BACKGROUND_BLUR_FILTER = `blur(${PHI_BACKGROUND_BLUR_RADIUS_PX}px)`;
+/**
+ * The CSS filter for the layer that carries this Background's paint, or `null` when the paint needs none.
+ *
+ * Never for the element itself: whoever draws the paint on a layer of its own applies this there, and the
+ * content in front stays sharp.
+ */
+export function resolvePhiBackgroundGroundFilter(config) {
+    return resolvePhiBackgroundFilter(config) === "blur" ? PHI_BACKGROUND_BLUR_FILTER : null;
 }
 export function resolvePhiBackgroundMotion(config) {
     const normalized = normalizePhiBackgroundWidgetConfig(config);
@@ -511,6 +448,6 @@ export function resolvePhiBackgroundMotion(config) {
     return motion && motion.mode !== "static" ? motion : null;
 }
 export function resolvePhiBackgroundMotionHostStyle(config) {
-    const normalized = normalizePhiBackgroundWidgetConfig(config);
-    return resolvePhiLayoutEffectStyle({ effect: normalized.effect }) ?? {};
+    const pane = resolvePhiBackgroundPane(config);
+    return pane == null ? {} : resolvePhiLayoutEffectStyle({ effect: pane }) ?? {};
 }

package/components/widgets/config/choice-shared.d.ts

@@ -20,7 +20,7 @@ export declare function buildPhiChoiceControlOptionFields(editorPlacement?: "ins
     key: string;
     type: "collection";
     label: string;
-    editorPlacement: "inspector" | "toolbar";
+    editorPlacement: "toolbar" | "inspector";
     itemKeyField: string;
     itemLabelField: string;
     defaultItem: {
@@ -68,7 +68,7 @@ export declare const PHI_CHOICE_CONTROL_OPTION_FIELDS: ({
     key: string;
     type: "collection";
     label: string;
-    editorPlacement: "inspector" | "toolbar";
+    editorPlacement: "toolbar" | "inspector";
     itemKeyField: string;
     itemLabelField: string;
     defaultItem: {
@@ -135,6 +135,5 @@ export declare const PHI_CHOICE_CONTROL_VALUE_MODE_FIELD: {
         label: string;
     }[];
 };
-export declare function readPhiChoiceValueMode(value: unknown): PhiChoiceValueMode;
 export declare function parsePhiChoiceControlConfig(config: Record<string, unknown>): PhiChoiceControlConfig;
 export declare function parsePhiStackChoiceControlConfig(config: Record<string, unknown>): PhiStackChoiceControlConfig;

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

@@ -46,7 +46,7 @@ export const PHI_CHOICE_CONTROL_VALUE_MODE_FIELD = {
         { value: "stack-slot-index", label: "Stack Slot Index" },
     ],
 };
-export function readPhiChoiceValueMode(value) {
+function readPhiChoiceValueMode(value) {
     return readString(value) === "stack-slot-index" ? "stack-slot-index" : "raw";
 }
 export function parsePhiChoiceControlConfig(config) {

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

@@ -0,0 +1,48 @@
+import type { PhiCommandButtonConfig } from "../../../types/core-widget-placements";
+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[];
+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
+ * number counts on from the list's length, so a button added to three is `button4` unless that is taken.
+ */
+export declare function createPhiCommandButton(buttons: readonly PhiCommandButtonConfig[]): PhiCommandButtonConfig;
+/** The fewest and most buttons a Widget's scaffold offers. */
+export type PhiCommandButtonBounds = {
+    min: number;
+    max: number;
+};
+/**
+ * The buttons at a new count: kept buttons stay as they are, new ones are created after them, a smaller
+ * count drops the last. Held to the Widget's bounds -- a Widget without buttons draws nothing, and an
+ * author has nothing to select it by.
+ */
+export declare function resizePhiCommandButtons(buttons: readonly PhiCommandButtonConfig[], count: number, bounds: PhiCommandButtonBounds): PhiCommandButtonConfig[];
+export type PhiCommandButtonsFieldOptions = {
+    /** Fields a Widget's buttons have no use for: a Float Button knows no danger. */
+    omit?: readonly "danger"[];
+    /** When a button's label is offered: a round Float Button has no room for one. */
+    labelVisibleWhen?: PhiCmsConfigFieldVisibilityRule;
+    /** Fields of the Widget's own, after the icon. */
+    extraItemFields?: readonly PhiCmsConfigField[];
+};
+/**
+ * The buttons, one at a time, picked by a select.
+ *
+ * How many there are is set on the scaffold. The key and what a button sends stay as they were made: the
+ * key is its signal address, and the value is wired from the Signals panel.
+ */
+export declare function buildPhiCommandButtonsField({ omit, labelVisibleWhen, extraItemFields, }?: PhiCommandButtonsFieldOptions): PhiCmsConfigField;
+/** Each button answers at its own address, named in the Signals panel after its label or its action. */
+export declare const PHI_COMMAND_BUTTONS_SIGNAL_SUBCONTROLS: {
+    configKey: string;
+    keyField: string;
+    labelFields: string[];
+    labelFieldValues: {
+        action: {
+            [k: string]: string;
+        };
+    };
+}[];

package/components/widgets/config/command-buttons.js

@@ -0,0 +1,207 @@
+import { isPhiRecord } from "../../../helpers/is-record";
+import { canPhiViewerAccessOwnedPolicy, readPhiViewerAccessPolicy, } from "../../../types/access";
+import { PHI_COMMON_CONTROL_DEFAULT_LABELS, readPhiCommonControlActionKey, } from "../label-types/common-controls";
+import { PHI_BUTTON_VARIANT_FIELD_OPTIONS, readPhiButtonVariant } from "./button-variant";
+import { createPhiCommonActionField, readPhiControlLabel } from "./common-action-field";
+import { PHI_CONTROL_BADGE_FIELDS, parsePhiControlBadgeConfig } from "./control-signal-config";
+import { readBoolean, readNumber, readString } from "./parser-primitives";
+/*
+ * The buttons of a Widget that holds several: the Command Toolbar's row, and the Float Button's corner.
+ *
+ * Each button is a signal subcontrol of its Widget -- its key is its address, what it sends is its first
+ * emit, and the Signals panel wires both. The two Widgets differ in how the buttons stand, never in what
+ * a button is, so the parser, the Inspector fields, the viewer filter and the scaffold's count are one.
+ */
+function readButtonEmitValue(value) {
+    const stringValue = readString(value);
+    if (stringValue !== undefined) {
+        return stringValue;
+    }
+    const numberValue = readNumber(value);
+    if (numberValue !== undefined) {
+        return numberValue;
+    }
+    const booleanValue = readBoolean(value);
+    if (booleanValue !== undefined) {
+        return booleanValue;
+    }
+    if (value == null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        const stringItems = value.filter((item) => typeof item === "string");
+        if (stringItems.length === value.length) {
+            return stringItems;
+        }
+        const numberItems = value.filter((item) => typeof item === "number" && Number.isFinite(item));
+        if (numberItems.length === value.length) {
+            return numberItems;
+        }
+        return undefined;
+    }
+    if (typeof value === "object") {
+        return value;
+    }
+    return undefined;
+}
+function readCommandButtonEmitConfig(value) {
+    if (!isPhiRecord(value)) {
+        return null;
+    }
+    const record = value;
+    const capabilityId = readString(record.capabilityId);
+    if (!capabilityId) {
+        return null;
+    }
+    return {
+        capabilityId,
+        value: readButtonEmitValue(record.value),
+    };
+}
+function readCommandButtonEmits(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map(readCommandButtonEmitConfig)
+        .filter((item) => item != null);
+}
+function readCommandButtonConfig(value) {
+    if (!isPhiRecord(value)) {
+        return null;
+    }
+    const record = value;
+    const key = readString(record.key);
+    const emits = readCommandButtonEmits(record.emits);
+    if (!key || emits.length === 0) {
+        return null;
+    }
+    const hasAccessPolicy = Object.prototype.hasOwnProperty.call(record, "accessPolicy");
+    const accessPolicy = hasAccessPolicy
+        ? readPhiViewerAccessPolicy(record.accessPolicy)
+        : null;
+    if (hasAccessPolicy && !accessPolicy) {
+        return null;
+    }
+    return {
+        key,
+        emits,
+        ...(accessPolicy ? { accessPolicy } : {}),
+        ...parsePhiControlBadgeConfig(record),
+        action: readPhiCommonControlActionKey(readString(record.action)) ?? undefined,
+        label: readPhiControlLabel(record.label),
+        tooltip: readString(record.tooltip),
+        icon: readString(record.icon),
+        display: record.display === "icon" || record.display === "label" || record.display === "icon-label"
+            ? record.display
+            : undefined,
+        danger: readBoolean(record.danger),
+        disabled: readBoolean(record.disabled),
+        readOnly: readBoolean(record.readOnly),
+        variant: readPhiButtonVariant(record.variant),
+    };
+}
+export function readPhiCommandButtons(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map(readCommandButtonConfig)
+        .filter((item) => item != null);
+}
+export function filterPhiCommandButtonsForViewer(buttons, viewer, ownerProviderId) {
+    return buttons.filter((button) => canPhiViewerAccessOwnedPolicy(viewer, button.accessPolicy, ownerProviderId));
+}
+/**
+ * What a new button shows. It has an icon so that Show Labels has something to switch between: a button
+ * without one keeps its label whatever the toolbar says, or it would be an empty box.
+ */
+const PHI_COMMAND_BUTTON_DEFAULT_ICON = "antd:star-outlined";
+/**
+ * A new button: the first free `buttonN` key, labelled after it, sending its key as the command. The
+ * number counts on from the list's length, so a button added to three is `button4` unless that is taken.
+ */
+export function createPhiCommandButton(buttons) {
+    const keys = new Set(buttons.map((button) => button.key));
+    let index = buttons.length + 1;
+    while (keys.has(`button${index}`)) {
+        index += 1;
+    }
+    const key = `button${index}`;
+    return {
+        key,
+        label: `Button ${index}`,
+        icon: PHI_COMMAND_BUTTON_DEFAULT_ICON,
+        emits: [{ capabilityId: "command", value: key }],
+    };
+}
+/**
+ * The buttons at a new count: kept buttons stay as they are, new ones are created after them, a smaller
+ * count drops the last. Held to the Widget's bounds -- a Widget without buttons draws nothing, and an
+ * author has nothing to select it by.
+ */
+export function resizePhiCommandButtons(buttons, count, bounds) {
+    const nextCount = Math.max(bounds.min, Math.min(bounds.max, Math.trunc(count)));
+    const next = buttons.slice(0, nextCount);
+    while (next.length < nextCount) {
+        next.push(createPhiCommandButton(next));
+    }
+    return next;
+}
+/**
+ * The buttons, one at a time, picked by a select.
+ *
+ * How many there are is set on the scaffold. The key and what a button sends stay as they were made: the
+ * key is its signal address, and the value is wired from the Signals panel.
+ */
+export function buildPhiCommandButtonsField({ omit = [], labelVisibleWhen, extraItemFields = [], } = {}) {
+    const omitted = new Set(omit);
+    return {
+        key: "buttons",
+        type: "collection",
+        presentation: "select",
+        label: "Button",
+        itemKeyField: "key",
+        itemLabelField: "label",
+        reorderable: false,
+        itemFields: [
+            /*
+             * What it sends is its first emit; the Signals panel wires it and may change it after. The divider
+             * sets the picked button's own fields apart from the select that picks it.
+             */
+            createPhiCommonActionField({ signalValuePath: "emits.0.value", heading: "Appearance" }),
+            {
+                key: "variant",
+                type: "choice",
+                label: "Variant",
+                options: [...PHI_BUTTON_VARIANT_FIELD_OPTIONS],
+            },
+            {
+                key: "label",
+                type: "string",
+                label: "Label",
+                emptyValue: "",
+                ...(labelVisibleWhen ? { visibleWhen: labelVisibleWhen } : {}),
+            },
+            { key: "tooltip", type: "string", label: "Tooltip" },
+            { key: "icon", type: "icon", label: "Icon" },
+            ...extraItemFields,
+            ...(omitted.has("danger") ? [] : [{ key: "danger", type: "boolean", label: "Danger" }]),
+            { key: "readOnly", type: "boolean", label: "Read only" },
+            { key: "disabled", type: "boolean", label: "Disabled" },
+            ...PHI_CONTROL_BADGE_FIELDS,
+        ],
+    };
+}
+/** Each button answers at its own address, named in the Signals panel after its label or its action. */
+export const PHI_COMMAND_BUTTONS_SIGNAL_SUBCONTROLS = [
+    {
+        configKey: "buttons",
+        keyField: "key",
+        labelFields: ["label", "action"],
+        labelFieldValues: {
+            action: Object.fromEntries(Object.entries(PHI_COMMON_CONTROL_DEFAULT_LABELS.actions)
+                .map(([key, action]) => [key, action.label])),
+        },
+    },
+];