@phis/ui 0.2.1 → 0.4.0

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;

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

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { PhiFlexControl } from "../../../controls/phi-flex-control";
+import { PhiSegmentedControl } from "../../../controls/phi-segmented-control";
+import { PhiSwitchControl } from "../../../controls/phi-switch-control";
+import { PhiTextControl } from "../../../controls/phi-text-control";
+import { PhiTreeSelectControl } from "../../../controls/phi-tree-select-control";
+import { isPhiStorableExternalHref, readPhiLinkTarget, } from "../../../../types/references";
+/**
+ * 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 function PhiLinkTargetControl({ value, options, labels, area, disabled, newTabRow = (control) => (_jsxs(PhiFlexControl, { align: "center", gap: 8, children: [control, _jsx("span", { children: labels.newTab })] })), onChange, }) {
+    const target = readPhiLinkTarget(value);
+    const [mode, setMode] = useState(target?.kind ?? "none");
+    /*
+     * The address as it is being typed, which the stored value cannot be: a target is only written when
+     * it is storable, so reading the box back out of the value would erase every character before the
+     * first one that makes a whole address.
+     */
+    const [draftHref, setDraftHref] = useState(target?.kind === "external" ? target.href : "");
+    /*
+     * The switch stands from the moment the author answers "Address", not only once an address is
+     * complete: it is part of the question. Until there is a target to carry it, its answer waits here.
+     */
+    const [pendingNewTab, setPendingNewTab] = useState(false);
+    /*
+     * The value can change under this control -- an undo, a Form reset, or the Inspector moving to another
+     * Widget of the same kind without remounting it. What this control wrote itself is already on screen;
+     * anything else replaces the mode and the address being typed, or they would go on showing, and
+     * writing into, the value before.
+     */
+    const valueKey = JSON.stringify(target ?? null);
+    const [syncedValueKey, setSyncedValueKey] = useState(valueKey);
+    const [emittedValueKey, setEmittedValueKey] = useState(null);
+    if (valueKey !== syncedValueKey) {
+        setSyncedValueKey(valueKey);
+        if (valueKey === emittedValueKey) {
+            // This control's own write came back; it is consumed, so a later return to the same value is news.
+            setEmittedValueKey(null);
+        }
+        else {
+            setMode(target?.kind ?? "none");
+            setDraftHref(target?.kind === "external" ? target.href : "");
+            setPendingNewTab(false);
+        }
+    }
+    const emit = (next, none) => {
+        setEmittedValueKey(JSON.stringify(next ?? null));
+        onChange?.(next, none);
+    };
+    const newTab = target ? target.newTab === true : pendingNewTab;
+    const withNewTab = (next) => (newTab ? { ...next, newTab: true } : next);
+    const changeMode = (nextMode) => {
+        setMode(nextMode);
+        setDraftHref("");
+        setPendingNewTab(false);
+        emit(undefined, nextMode === "none");
+    };
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiSegmentedControl, { value: mode, block: true, disabled: disabled || !onChange, options: [
+                    { value: "none", label: labels.none },
+                    { value: "page", label: labels.page },
+                    { value: "external", label: labels.external },
+                ], onChange: changeMode }), mode === "page" ? (_jsx(PhiTreeSelectControl, { value: target?.kind === "page" ? target.reference : null, options: options, placeholder: labels.pagePlaceholder, disabled: disabled || !onChange, allowClear: true, style: { width: "100%" }, onChange: (nextValue) => emit(nextValue
+                    ? { kind: "page", reference: nextValue, ...(area ? { area } : {}) }
+                    : undefined) })) : null, mode === "external" ? (_jsx(PhiTextControl, { value: draftHref, inputType: "url", placeholder: labels.externalPlaceholder, disabled: disabled || !onChange, style: { width: "100%" }, onChange: (nextValue) => {
+                    const href = nextValue ?? "";
+                    setDraftHref(href);
+                    emit(isPhiStorableExternalHref(href)
+                        ? withNewTab({ kind: "external", href: href.trim() })
+                        : undefined);
+                } })) : null, mode === "external" ? newTabRow(_jsx(PhiSwitchControl, { checked: newTab, disabled: disabled || !onChange, onChange: (checked) => {
+                    if (target?.kind !== "external") {
+                        setPendingNewTab(checked);
+                        return;
+                    }
+                    emit(checked ? { ...target, newTab: true } : { ...target, newTab: undefined });
+                } })) : null] }));
+}

package/components/widgets/client/shared/phi-mask-picker.js

@@ -1,29 +1,23 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useState } from "react";
-import { StarOutlined } from "@ant-design/icons";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { PhiMediaAssetFlags, PhiMediaAssetSource, PhiMediaKind } from "../../../../constants/media";
 import { normalizePhiImagePreviewTile } from "../../../media/phi-image-preview-data";
 import { bumpPhiImagePreviewRefreshToken } from "../../../media/phi-image-preview-store";
 import { usePhiMediaPickerBinding } from "../../../media/phi-media-picker-binding";
-import { runPhiMediaUploadSession } from "../../../media/media-upload-flow";
+import { isPhiMediaUploadCancelled, runPhiMediaUploadSession } from "../../../media/media-upload-flow";
 import { PHI_MEDIA_UPLOAD_DEFAULT_LABELS, readPhiMediaUploadErrorMessage, } from "../../../media/phi-media-upload";
 import { PHI_MEDIA_WIDGET_DEFAULT_LABELS } from "../../../media/media-widget-labels";
 import { PHI_SEARCH_WIDGET_DEFAULT_LABELS } from "../../label-types/search";
-import { mergePhiMaskConfigDefaults, } from "../../config/mask";
+import { mergePhiMaskConfigPatch, } from "../../config/mask";
 import { PhiMaskPickerControl } from "../../../controls/phi-mask-picker-control";
 import { usePhiApplicationFeedback } from "../../../runtime/use-phi-application-feedback";
 import { usePhiWidgetScaffoldPopup } from "./phi-widget-scaffold-popup";
+import { usePhiAuthoringToolsLabels } from "./phi-authoring-tools-labels";
 import { createPhiMediaPickerAssetControllerRoutes } from "../../../media/asset-controller-routes";
+import { PhiIcon } from "../../../shell/phi-icon";
 const PHI_MASK_PICKER_MEDIA_ROUTES = createPhiMediaPickerAssetControllerRoutes("mask-picker-media", "area");
 const PHI_MASK_MEDIA_SCOPE_KEY = "image-mask-picker";
-function mergeMask(value, patch) {
-    return {
-        ...mergePhiMaskConfigDefaults(value),
-        ...patch,
-        enabled: patch.enabled ?? true,
-    };
-}
 function parseIconifyIcon(value) {
     if (!value?.startsWith("iconify:"))
         return null;
@@ -44,14 +38,47 @@ function buildIconifySvgUrl(icon) {
 function buildIconifyMaskFilename(icon) {
     return `${icon.iconSet}-${icon.iconName}`.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "icon-mask";
 }
-export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, buttonAriaLabel = "Select mask", buttonIcon = _jsx(StarOutlined, {}), placement = "bottomRight", }) {
+export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, buttonAriaLabel, buttonIcon = _jsx(PhiIcon, { name: "star", size: "inherit" }), placement = "bottomRight", }) {
     const { showMessage } = usePhiApplicationFeedback();
     const popup = usePhiWidgetScaffoldPopup();
+    const toolLabels = usePhiAuthoringToolsLabels();
+    const iconifyRequiredMessage = toolLabels.mask.iconifyRequired;
     const [open, setOpen] = useState(false);
     const [mediaOpen, setMediaOpen] = useState(false);
     const [uploading, setUploading] = useState(false);
     const [uploadProgress, setUploadProgress] = useState(0);
     const [selectedIcon, setSelectedIcon] = useState(null);
+    /*
+     * The value as it stands when an upload lands, not as it stood when the upload began: scale, offset
+     * and rotation can be changed while the file travels, and the Asset is merged into what is there.
+     */
+    const valueRef = useRef(value);
+    useEffect(() => {
+        valueRef.current = value;
+    }, [value]);
+    /*
+     * One upload at a time. A second file or icon while one travels is not taken -- the controls are
+     * disabled, and this holds for a drop that arrives before they re-render -- so two Assets can never
+     * race for the mask. Leaving the picker stops the upload; the Server clears up what arrived.
+     */
+    const uploadRef = useRef(null);
+    useEffect(() => () => uploadRef.current?.abort(), []);
+    const beginUpload = useCallback(() => {
+        if (uploadRef.current)
+            return null;
+        const controller = new AbortController();
+        uploadRef.current = controller;
+        setUploading(true);
+        setUploadProgress(0);
+        return controller;
+    }, []);
+    const endUpload = useCallback((controller) => {
+        if (uploadRef.current !== controller)
+            return;
+        uploadRef.current = null;
+        setUploading(false);
+        setUploadProgress(0);
+    }, []);
     const updateOpen = useCallback((nextOpen) => {
         setOpen(nextOpen);
         if (!nextOpen)
@@ -59,15 +86,15 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
         popup.setOpen(nextOpen);
     }, [popup]);
     const applyAsset = useCallback((asset) => {
-        onChange(mergeMask(value, {
+        onChange(mergePhiMaskConfigPatch(valueRef.current, {
             source: "asset",
             assetId: asset.id,
             assetUrl: asset.deliveryUrl,
         }));
         updateOpen(false);
-    }, [onChange, updateOpen, value]);
+    }, [onChange, updateOpen]);
     const clearAsset = useCallback(() => {
-        onChange(mergeMask(value, {
+        onChange(mergePhiMaskConfigPatch(value, {
             source: "preset",
             preset: "circle",
             assetId: undefined,
@@ -97,33 +124,36 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
         applyAsset(tile);
     }, [applyAsset]);
     const uploadFile = useCallback((file) => {
-        setUploading(true);
-        setUploadProgress(0);
-        void runPhiMediaUploadSession(file, setUploadProgress, { presentationFlags: PhiMediaAssetFlags.Mask }).then((result) => {
+        const controller = beginUpload();
+        if (!controller)
+            return;
+        void runPhiMediaUploadSession(file, setUploadProgress, { presentationFlags: PhiMediaAssetFlags.Mask }, controller.signal).then((result) => {
+            if (controller.signal.aborted)
+                return;
             applyUploadedAsset(result.asset);
             showMessage({ level: "success", content: `Uploaded ${file.name}.` });
         }).catch((error) => {
+            if (controller.signal.aborted || isPhiMediaUploadCancelled(error))
+                return;
             // One reading of every refusal, rather than whatever string the control plane happened to send.
             showMessage({
                 level: "error",
                 content: readPhiMediaUploadErrorMessage(error, PHI_MEDIA_UPLOAD_DEFAULT_LABELS),
             });
-        }).finally(() => {
-            setUploading(false);
-            setUploadProgress(0);
-        });
-    }, [applyUploadedAsset, showMessage]);
+        }).finally(() => endUpload(controller));
+    }, [applyUploadedAsset, beginUpload, endUpload, showMessage]);
     const uploadIconifyMask = useCallback((nextIconValue) => {
         setSelectedIcon(nextIconValue);
         const icon = parseIconifyIcon(nextIconValue);
         if (!icon) {
             if (nextIconValue)
-                showMessage({ level: "error", content: "Select an Iconify icon for mask uploads." });
+                showMessage({ level: "error", content: iconifyRequiredMessage });
             return;
         }
-        setUploading(true);
-        setUploadProgress(0);
-        void fetch(buildIconifySvgUrl(icon), { cache: "force-cache" })
+        const controller = beginUpload();
+        if (!controller)
+            return;
+        void fetch(buildIconifySvgUrl(icon), { cache: "force-cache", signal: controller.signal })
             .then(async (response) => {
             if (!response.ok)
                 throw new Error(`Iconify SVG request failed with ${response.status}.`);
@@ -140,22 +170,23 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
                     },
                     usage: { mask: true },
                 },
-            });
+            }, controller.signal);
         })
             .then((result) => {
+            if (controller.signal.aborted)
+                return;
             applyUploadedAsset(result.asset);
             showMessage({ level: "success", content: `Selected ${icon.iconKey}.` });
         })
             .catch((error) => {
+            if (controller.signal.aborted || isPhiMediaUploadCancelled(error))
+                return;
             showMessage({
                 level: "error",
                 content: readPhiMediaUploadErrorMessage(error, PHI_MEDIA_UPLOAD_DEFAULT_LABELS),
             });
         })
-            .finally(() => {
-            setUploading(false);
-            setUploadProgress(0);
-        });
-    }, [applyUploadedAsset, showMessage]);
-    return (_jsx(PhiMaskPickerControl, { value: value, open: open, placement: placement, buttonAriaLabel: buttonAriaLabel, buttonIcon: buttonIcon, mediaPickerProps: mediaPickerProps, selectedIcon: selectedIcon, uploading: uploading, uploadProgress: uploadProgress, popupRootClassName: popup.rootClassName, getPopupContainer: popup.getPopupContainer, onUploadFile: uploadFile, onIconSelect: uploadIconifyMask, onChange: onChange, onCommit: onCommit, onDiscard: onDiscard, onOpenChange: updateOpen }));
+            .finally(() => endUpload(controller));
+    }, [applyUploadedAsset, beginUpload, endUpload, iconifyRequiredMessage, showMessage]);
+    return (_jsx(PhiMaskPickerControl, { value: value, open: open, placement: placement, buttonAriaLabel: buttonAriaLabel ?? toolLabels.mask.select, buttonIcon: buttonIcon, mediaPickerProps: mediaPickerProps, selectedIcon: selectedIcon, uploading: uploading, uploadProgress: uploadProgress, popupRootClassName: popup.rootClassName, getPopupContainer: popup.getPopupContainer, onUploadFile: uploadFile, onIconSelect: uploadIconifyMask, onChange: onChange, onCommit: onCommit, onDiscard: onDiscard, onOpenChange: updateOpen }));
 }

package/components/widgets/client/shared/phi-page-reference-picker.js

@@ -1,10 +1,10 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { LinkOutlined } from "@ant-design/icons";
 import { createContext, useContext, useState } from "react";
 import { PhiButtonControl } from "../../../controls/phi-button-control";
 import { PhiPopoverControl } from "../../../controls/phi-popover-control";
 import { PhiTreeSelectControl } from "../../../controls/phi-tree-select-control";
+import { PhiIcon } from "../../../shell/phi-icon";
 /*
  * The Pages an authoring surface offers to link to.
  *
@@ -28,5 +28,5 @@ export function PhiPageReferencePicker({ ariaLabel = "Select internal Page", onS
                     return;
                 onSelect(option.meta);
                 setOpen(false);
-            } })), children: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel, icon: _jsx(LinkOutlined, {}), onClick: () => undefined }) }) }));
+            } })), children: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel, icon: _jsx(PhiIcon, { name: "link", size: "inherit" }), onClick: () => undefined }) }) }));
 }

package/components/widgets/client/shared/phi-rendered-value.d.ts

@@ -26,18 +26,4 @@ export type PhiRenderedValueDefinition = {
  * it could not have simply called the table's renderer.
  */
 export type PhiRenderedValuePresentation = "cell" | "block";
-/**
- * **A flag being read is a mark, not a switch.**
- *
- * `switch` and `checkbox` drew the Controls of those names with `readOnly`, which cost twice. A switch
- * nobody can throw still looks like one, and a screen reader announces it as an operable widget; and the
- * import put two editing Controls into the bundle of every Widget that shows a value, which is why
- * `validate-area-client-reach.mjs` could not list the record Widget among the ones that only display.
- *
- * The two renderers draw the same mark here, and that is the truth rather than a loss: read-only, a
- * switch and a checkbox both say the same thing -- this flag is set. Their difference is how you operate
- * them, and where a cell can be operated the table hands it to `EditableTableCell`, which still draws the
- * Control the author asked for.
- */
-export declare function normalizePhiRenderedText(value: unknown): string;
 export declare function renderPhiValueContent(value: unknown, definition: PhiRenderedValueDefinition, presentation?: PhiRenderedValuePresentation): ReactNode;

package/components/widgets/client/shared/phi-rendered-value.js

@@ -21,7 +21,7 @@ import { isPhiRecord } from "../../../../helpers/is-record";
  * them, and where a cell can be operated the table hands it to `EditableTableCell`, which still draws the
  * Control the author asked for.
  */
-export function normalizePhiRenderedText(value) {
+function normalizePhiRenderedText(value) {
     if (value == null)
         return "";
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")