@phis/ui 0.2.0 → 0.3.0

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;

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

@@ -0,0 +1,286 @@
+"use client";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { createPhiSignalSubcontrolAddress, findPhiSignalRoutesByCapabilityId, } from "../../../../types/signals";
+import { usePhiSignalListener } from "../../../runtime/runtime-signal-bus";
+import { usePhiSignalEmitter, usePhiSignalIdentity } from "../../../runtime/runtime-signal-identity";
+import { registerPhiSignalInstance } from "../../../runtime/runtime-signal-registry";
+import { usePhiSignalRuntimePartition } from "../../../runtime/runtime-signal-partition";
+import { resolvePhiButtonVariantType } from "../../config/button-variant";
+import { resolvePhiCommonControlAction } from "./phi-common-controls";
+import { resolvePhiButtonIcon } from "./phi-button-icons";
+function resolveButtonSubcontrolAddress(blockId, key) {
+    return blockId == null ? null : createPhiSignalSubcontrolAddress("cms", blockId, key);
+}
+function readButtonSignalValue(signal) {
+    if (signal.valueType === "string") {
+        return typeof signal.value === "string" ? signal.value : signal.value == null ? "" : String(signal.value);
+    }
+    if (signal.valueType === "number") {
+        return typeof signal.value === "number" && Number.isFinite(signal.value) ? signal.value : null;
+    }
+    if (signal.valueType === "boolean") {
+        return typeof signal.value === "boolean" ? signal.value : null;
+    }
+    if (signal.valueType === "icon") {
+        return typeof signal.value === "string" ? signal.value : null;
+    }
+    return null;
+}
+/**
+ * The badge a button shows: what a signal last said, else what its config states.
+ *
+ * A signal switches the badge on by speaking -- the toolbar's buttons had no badge fields, and a count
+ * sent to one was the only way it ever had a badge. The stated one is drawn only where its config
+ * enables it, as on the Button Widget.
+ */
+function resolveButtonBadge(button, runtimeBadge) {
+    if (runtimeBadge != null) {
+        return {
+            enabled: true,
+            value: runtimeBadge,
+            color: button.badgeColor,
+            overflowCount: button.badgeOverflowCount,
+            showZero: button.badgeShowZero,
+        };
+    }
+    if (button.badgeEnabled !== true) {
+        return undefined;
+    }
+    return {
+        enabled: true,
+        value: button.badgeText ?? button.badgeCount ?? null,
+        color: button.badgeColor,
+        overflowCount: button.badgeOverflowCount,
+        showZero: button.badgeShowZero,
+    };
+}
+export function usePhiCommandButtons({ buttons, signalRoutes, blockId, labels, disabled, signalsEnabled = true, }) {
+    const signalIdentity = usePhiSignalIdentity();
+    const signalPartition = usePhiSignalRuntimePartition();
+    const emitSignal = usePhiSignalEmitter(null);
+    const emitRoutes = useMemo(() => signalRoutes?.emits ?? [], [signalRoutes?.emits]);
+    const listenRoutes = useMemo(() => signalRoutes?.listens ?? [], [signalRoutes?.listens]);
+    const [commandDisabled, setCommandDisabled] = useState(null);
+    const [buttonStateByKey, setButtonStateByKey] = useState({});
+    const resolvedDisabled = disabled === true || commandDisabled === true;
+    const widgetReceiver = signalIdentity.sender;
+    const buttonAddresses = useMemo(() => new Map(buttons.map((button) => [button.key, resolveButtonSubcontrolAddress(blockId, button.key)])), [blockId, buttons]);
+    useEffect(() => {
+        /*
+         * A subcontrol only receives what its address is registered for, in the signal's own scope. The
+         * identity context supplies a scope only inside an Overlay, so every toolbar outside one left its
+         * buttons unregistered and every signal aimed at them was dropped before delivery -- which is why
+         * Undo and Redo stayed clickable on an empty history. The scope a button is addressed in is the one
+         * declared by the routes that address it; the identity scope stands in where no route names it.
+         */
+        const scopeByAddress = new Map();
+        for (const route of listenRoutes) {
+            if (typeof route.receiver !== "string" || route.receiver === "broadcast")
+                continue;
+            if (!scopeByAddress.has(route.receiver))
+                scopeByAddress.set(route.receiver, route.scope);
+        }
+        const unregister = Array.from(buttonAddresses.values()).flatMap((address) => {
+            const scope = address == null ? null : scopeByAddress.get(address) ?? signalIdentity.scope;
+            return address == null || !scope
+                ? []
+                : [registerPhiSignalInstance(signalPartition, {
+                        address,
+                        scope,
+                    })];
+        });
+        return () => {
+            for (const dispose of unregister)
+                dispose();
+        };
+    }, [buttonAddresses, listenRoutes, signalIdentity.scope, signalPartition]);
+    const readButtonKeyFromReceiver = useCallback((receiver) => {
+        if (typeof receiver !== "string") {
+            return null;
+        }
+        for (const [buttonKey, address] of buttonAddresses) {
+            if (address === receiver) {
+                return buttonKey;
+            }
+        }
+        return null;
+    }, [buttonAddresses]);
+    function activate(buttonKey) {
+        if (!signalsEnabled) {
+            return;
+        }
+        const button = buttons.find((candidate) => candidate.key === buttonKey);
+        if (!button || button.readOnly) {
+            return;
+        }
+        const sender = buttonAddresses.get(button.key) ?? widgetReceiver;
+        for (const buttonEmit of button.emits) {
+            for (const route of findPhiSignalRoutesByCapabilityId(emitRoutes, buttonEmit.capabilityId)) {
+                if (route.receiver == null || (route.valueType === "json" && !route.valueSchema)) {
+                    continue;
+                }
+                emitSignal({
+                    sender,
+                    scope: route.scope,
+                    channel: route.channel,
+                    action: route.action,
+                    value: route.valueType === "none" ? null : buttonEmit.value,
+                    valueType: route.valueType,
+                    valueSchema: route.valueSchema ?? null,
+                    receiver: route.receiver,
+                });
+            }
+        }
+    }
+    const handleSignal = useCallback((signal) => {
+        if (!signalsEnabled || listenRoutes.length === 0) {
+            return;
+        }
+        const route = listenRoutes.find((candidate) => candidate.channel === signal.channel &&
+            candidate.action === signal.action &&
+            candidate.valueType === signal.valueType &&
+            (candidate.valueType !== "json" ||
+                (candidate.valueSchema != null && candidate.valueSchema === signal.valueSchema)) &&
+            candidate.receiver !== null);
+        if (!route) {
+            return;
+        }
+        const targetsWidget = signal.receiver === "broadcast" || (widgetReceiver != null && signal.receiver === widgetReceiver);
+        const buttonKey = readButtonKeyFromReceiver(signal.receiver);
+        if (!targetsWidget && !buttonKey) {
+            return;
+        }
+        /*
+         * What the signal sets is the capability its route names, not the channel it came in on: a route
+         * chooses its channel freely -- a Save button's `loading` arrives on `pageMetaSubmitting` or
+         * `submitting` -- and comparing the channel left every such button without its loading state.
+         */
+        const capability = route.capabilityId;
+        if (targetsWidget) {
+            if (capability === "enabled") {
+                setCommandDisabled(typeof signal.value === "boolean" ? !signal.value : false);
+            }
+            return;
+        }
+        if (!buttonKey) {
+            return;
+        }
+        const value = readButtonSignalValue(signal);
+        setButtonStateByKey((current) => {
+            const previous = current[buttonKey] ?? {};
+            if (capability === "enabled") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        enabled: typeof value === "boolean" ? value : undefined,
+                    },
+                };
+            }
+            if (capability === "visibility") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        visible: typeof value === "boolean" ? value : undefined,
+                    },
+                };
+            }
+            if (capability === "loading") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        loading: typeof value === "boolean" ? value : undefined,
+                    },
+                };
+            }
+            if ((capability === "badgeText" || capability === "badgeCount")) {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        badge: typeof value === "string" || typeof value === "number" ? value : null,
+                    },
+                };
+            }
+            if (capability === "icon") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        icon: typeof value === "string" ? value : null,
+                    },
+                };
+            }
+            if (capability === "label") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        label: typeof value === "string" ? value : null,
+                    },
+                };
+            }
+            if (capability === "tooltip") {
+                return {
+                    ...current,
+                    [buttonKey]: {
+                        ...previous,
+                        tooltip: typeof value === "string" && value ? value : null,
+                    },
+                };
+            }
+            return current;
+        });
+    }, [listenRoutes, readButtonKeyFromReceiver, signalsEnabled, widgetReceiver]);
+    const signalFilter = useMemo(() => {
+        if (listenRoutes.length === 0) {
+            return null;
+        }
+        const valueSchemas = Array.from(new Set(listenRoutes.map((route) => route.valueSchema).filter((schema) => Boolean(schema))));
+        return {
+            scopes: Array.from(new Set(listenRoutes.map((route) => route.scope))),
+            channels: Array.from(new Set(listenRoutes.map((route) => route.channel))),
+            ...(valueSchemas.length > 0 ? { valueSchemas } : null),
+        };
+    }, [listenRoutes]);
+    /*
+     * The addresses this one listener answers for: the Widget, and every button in it.
+     *
+     * Registering the buttons as instances was only half of it. A receiver with an instance and no
+     * listener counted for it is not wrong, it is "not ready yet", so an addressed signal was held and
+     * never delivered -- the Save button in the Page dialog never learned it should read "Create", and
+     * Undo never learned it was disabled. Both were sent, both waited.
+     */
+    const answeredAddresses = useMemo(() => [widgetReceiver, ...buttonAddresses.values()]
+        .filter((address) => typeof address === "string"), [buttonAddresses, widgetReceiver]);
+    usePhiSignalListener(handleSignal, signalFilter, answeredAddresses);
+    const items = buttons.map((button) => {
+        const buttonState = buttonStateByKey[button.key] ?? {};
+        /*
+         * An action answers for the words and the look; the icon stays the button's to swap, and the
+         * tooltip is only ever its own. What a signal says at runtime -- "Create" for "Save", or the step
+         * Undo would take back -- still wins.
+         */
+        const action = resolvePhiCommonControlAction(labels, button.action);
+        const resolvedIcon = resolvePhiButtonIcon(buttonState.icon ?? button.icon ?? action?.icon);
+        const label = buttonState.label ?? (action ? action.label : button.label) ?? button.key;
+        return {
+            key: button.key,
+            ariaLabel: label || button.tooltip || button.key,
+            label,
+            tooltip: buttonState.tooltip ?? button.tooltip,
+            showLabel: button.display == null ? undefined : button.display !== "icon",
+            type: resolvePhiButtonVariantType(action ? action.variant : button.variant) ?? "default",
+            danger: action ? action.danger === true : button.danger === true,
+            disabled: button.disabled === true || buttonState.enabled === false,
+            readOnly: button.readOnly === true,
+            loading: buttonState.loading,
+            icon: button.display === "label" ? null : resolvedIcon,
+            visible: buttonState.visible,
+            badge: resolveButtonBadge(button, buttonState.badge),
+        };
+    });
+    return { items, disabled: resolvedDisabled, activate };
+}

package/components/widgets/client/shared/phi-link-target-control.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+import type { PhiCmsAreaKey } from "../../../../constants/cms-areas";
+import { type PhiLinkTarget } from "../../../../types/references";
+import type { PhiTreeOption } from "../../../../types/tree";
+import type { PhiPageReferenceSelection } from "./phi-page-reference-picker";
+export type PhiLinkTargetControlLabels = {
+    none: string;
+    page: string;
+    external: string;
+    pagePlaceholder: string;
+    externalPlaceholder: string;
+    newTab: string;
+};
+/**
+ * One link, chosen rather than typed, with the two answers it may have kept apart (`REFERENCES.md`).
+ *
+ * **The mode is held here and the value is not.** A target is written only once it is one: a Page with
+ * nothing picked yet and a half-typed address are both states somebody is passing through, and storing
+ * them would put a target in the config that resolves to nothing, index a reference that is not one, and
+ * draw a dead link between two keystrokes. So the segmented control remembers what the author is
+ * answering, and the value gets a target when the answer is complete -- or `undefined`, which is no link.
+ *
+ * Switching modes drops what the other one held rather than keeping it aside. A hidden address that
+ * returns when somebody flips back is a value nobody can see and nobody agreed to, and `REFERENCES.md`
+ * has no shape for a target that is two things at once.
+ *
+ * Which Pages it offers is the surface's knowledge: the Builder hands in its Area's catalog, a Form the
+ * tree `/api/site/page-references` answered. `area` is written into a Page target where the link leads
+ * out of the Area asking -- an Editor Form linking a Public Page.
+ */
+export declare function PhiLinkTargetControl({ value, options, labels, area, disabled, newTabRow, onChange, }: {
+    value: unknown;
+    options: PhiTreeOption<PhiPageReferenceSelection>[];
+    labels: PhiLinkTargetControlLabels;
+    area?: PhiCmsAreaKey;
+    disabled?: boolean;
+    /** How the new-tab switch stands beside its words; the Inspector puts it in its own field row. */
+    newTabRow?: (control: ReactNode) => ReactNode;
+    /**
+     * The target as it now stands. `none` is set when the author answered "None" -- the link is gone, not
+     * only incomplete -- so what depends on a link can go with it.
+     */
+    onChange?: (next: PhiLinkTarget | undefined, none?: boolean) => void;
+}): import("react").JSX.Element;