@phis/ui 0.2.1 → 0.3.0

package/components/widgets/client/shared/phi-timeline-provider.js

@@ -0,0 +1,115 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { readPhiTimelineEntries } from "@phis/contracts/timeline";
+import { isPhiRuntimeDataProviderKey, } from "../../../../types/runtime-data-provider";
+const EMPTY_TIMELINE_PROVIDER_REGISTRY = new Map();
+const PhiTimelineProviderRegistryContext = createContext(EMPTY_TIMELINE_PROVIDER_REGISTRY);
+function assertPhiTimelineProviderRegistration(registration) {
+    if (!isPhiRuntimeDataProviderKey(registration.key)) {
+        throw new Error(`Invalid Timeline provider key "${registration.key}".`);
+    }
+}
+export function createPhiTimelineProviderClient(registration) {
+    assertPhiTimelineProviderRegistration(registration);
+    return function PhiBoundTimelineProviderClient({ children }) {
+        return _jsx(PhiTimelineProviderClient, { registration: registration, children: children });
+    };
+}
+export function PhiTimelineProviderClient({ registration, children, }) {
+    const parent = useContext(PhiTimelineProviderRegistryContext);
+    const registry = useMemo(() => {
+        assertPhiTimelineProviderRegistration(registration);
+        if (parent.has(registration.key)) {
+            throw new Error(`Duplicate active Timeline provider "${registration.key}".`);
+        }
+        const next = new Map(parent);
+        next.set(registration.key, registration);
+        return next;
+    }, [parent, registration]);
+    return createElement(PhiTimelineProviderRegistryContext.Provider, { value: registry }, children);
+}
+export function PhiTimelineProviderIsolationBoundary({ children }) {
+    return createElement(PhiTimelineProviderRegistryContext.Provider, { value: EMPTY_TIMELINE_PROVIDER_REGISTRY }, children);
+}
+/* One request in flight per Provider and load key, shared by every Widget that asks it at once. */
+const pendingLoads = new WeakMap();
+function loadEntries(registration, request, loadKey) {
+    const byKey = pendingLoads.get(registration) ?? new Map();
+    pendingLoads.set(registration, byKey);
+    const pending = byKey.get(loadKey);
+    if (pending)
+        return pending;
+    const next = registration.load(request)
+        /* The answer is read as the contract spells it: whatever else a Provider sends is not an entry. */
+        .then((result) => readPhiTimelineEntries(result?.entries))
+        .finally(() => byKey.delete(loadKey));
+    byKey.set(loadKey, next);
+    return next;
+}
+const NO_ENTRIES = [];
+/** The entries a bound Timeline Provider answers; `null` binding is no Provider and no entries. */
+export function usePhiTimelineProviderEntries(binding) {
+    const registry = useContext(PhiTimelineProviderRegistryContext);
+    const provider = binding ? registry.get(binding.providerKey) ?? null : null;
+    const [revision, setRevision] = useState(0);
+    const scopeKey = binding?.scopeKey;
+    const params = binding?.params;
+    const request = useMemo(() => ({
+        ...(scopeKey ? { scopeKey } : {}),
+        ...(params ? { params } : {}),
+    }), [params, scopeKey]);
+    const loadKey = provider
+        ? [
+            provider.key,
+            JSON.stringify(request),
+            provider.resolveLoadKey?.(request) ?? "",
+            revision,
+        ].join(":")
+        : null;
+    const [state, setState] = useState({
+        key: null,
+        entries: NO_ENTRIES,
+        error: null,
+    });
+    useEffect(() => {
+        if (!provider || !loadKey)
+            return;
+        let cancelled = false;
+        loadEntries(provider, request, loadKey).then((entries) => {
+            if (!cancelled)
+                setState({ key: loadKey, entries, error: null });
+        }, (error) => {
+            if (!cancelled) {
+                setState({
+                    key: loadKey,
+                    entries: NO_ENTRIES,
+                    error: `Timeline provider "${provider.key}" failed to load: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [loadKey, provider, request]);
+    const reload = useCallback(() => setRevision((current) => current + 1), [setRevision]);
+    if (!binding) {
+        return { entries: NO_ENTRIES, loading: false, error: null, reload };
+    }
+    if (!provider) {
+        return {
+            entries: NO_ENTRIES,
+            loading: false,
+            error: `Timeline provider "${binding.providerKey}" is not available from the active runtime modules.`,
+            reload,
+        };
+    }
+    const settled = state.key === loadKey;
+    /* While a reload runs, the entries it replaces stay drawn rather than the list going blank. */
+    return {
+        entries: state.entries,
+        loading: !settled,
+        error: settled ? state.error : null,
+        reload,
+    };
+}

package/components/widgets/client/shared/phi-widget-image-tool-button.d.ts

@@ -4,7 +4,6 @@ type PhiWidgetImageToolButtonCommonPatch = {
     trusted?: boolean;
     /** Cleared when the image changes: a fixed size chosen for one image is no answer for the next. */
     imageSize?: undefined;
-    blurDataUrl?: string;
 };
 export type PhiWidgetImageToolButtonPatch = PhiWidgetImageToolButtonCommonPatch & ({
     sourceKind: "asset";

package/components/widgets/client/shared/phi-widget-image-tool-button.js

@@ -1,6 +1,5 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { PictureOutlined } from "@ant-design/icons";
 import { PhiImageAssetVariantKey, PhiMediaKind, } from "../../../../constants/media";
 import { PhiMediaPickerBinding } from "../../../media/phi-media-picker-binding";
 import { PHI_MEDIA_WIDGET_DEFAULT_LABELS } from "../../../media/media-widget-labels";
@@ -9,6 +8,7 @@ import { usePhiWidgetScaffoldPopup } from "./phi-widget-scaffold-popup";
 import { usePhiAuthoringToolsLabels } from "./phi-authoring-tools-labels";
 import { PhiButtonControl } from "../../../controls/phi-button-control";
 import { createPhiMediaPickerAssetControllerRoutes } from "../../../media/asset-controller-routes";
+import { PhiIcon } from "../../../shell/phi-icon";
 export function PhiInternalAssetReferencePickerButton({ blockId, ariaLabel, onSelect, onClear, }) {
     const labels = usePhiAuthoringToolsLabels();
     const popup = usePhiWidgetScaffoldPopup();
@@ -19,7 +19,7 @@ export function PhiInternalAssetReferencePickerButton({ blockId, ariaLabel, onSe
             showGroupFilter: true,
             showSearchBar: true,
             signalRoutes: createPhiMediaPickerAssetControllerRoutes(`internal-asset-reference-${blockId}`, "area"),
-        }, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, onPopupOpenChange: popup.setOpen, trigger: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PictureOutlined, {}), ariaLabel: ariaLabel ?? labels.fallbacks.selectImage, style: { width: 24, minWidth: 24, height: 24, padding: 0 }, onClick: () => undefined }) }), onAssetSelect: onSelect, onAssetClear: onClear }));
+        }, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, onPopupOpenChange: popup.setOpen, trigger: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", icon: _jsx(PhiIcon, { name: "picture", size: "inherit" }), ariaLabel: ariaLabel ?? labels.fallbacks.selectImage, style: { width: 24, minWidth: 24, height: 24, padding: 0 }, onClick: () => undefined }) }), onAssetSelect: onSelect, onAssetClear: onClear }));
 }
 export function PhiWidgetImageToolButton({ blockId, onChange, }) {
     const selectAsset = (asset) => {
@@ -30,7 +30,6 @@ export function PhiWidgetImageToolButton({ blockId, onChange, }) {
             variantVersion: asset.variantVersion ?? null,
             trusted: false,
             imageSize: undefined,
-            blurDataUrl: asset.blurDataUrl ?? undefined,
         });
     };
     return (_jsx(PhiInternalAssetReferencePickerButton, { blockId: blockId, onSelect: selectAsset, onClear: () => {
@@ -38,7 +37,6 @@ export function PhiWidgetImageToolButton({ blockId, onChange, }) {
                 sourceKind: "url",
                 sourceUrl: undefined,
                 imageSize: undefined,
-                blurDataUrl: undefined,
             });
         } }));
 }

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

@@ -1,5 +1,6 @@
 import type { PhiWidgetFontFamilyKey, PhiWidgetFontSizeKey } from "../../../../types/site-theme";
 import type { PhiCmsInstanceId } from "../../../../types/cms-instance-id";
+import type { PhiBulletListEntry } from "../../shared/bullet-list-vocabulary";
 export type PhiWidgetIconToolButtonProps = {
     value?: string | null;
     ariaLabel?: string;
@@ -30,8 +31,22 @@ export declare function PhiHtmlWidgetToolbarTools({ blockId, }: PhiHtmlWidgetToo
 export declare function PhiMarkdownWidgetToolbarTools({ blockId, }: {
     blockId: PhiCmsInstanceId;
 }): import("react").JSX.Element;
+export type PhiWidgetCountToolButtonProps = {
+    /** How many there are now; the button shows it. */
+    count: number;
+    min: number;
+    max: number;
+    /** The button's tooltip and the caption over the field. */
+    label: string;
+    onChange: (count: number) => void;
+};
+/**
+ * How many of something a Widget has, set from its scaffold: a button showing the number, and a field
+ * behind it. The Description's items and the Command Toolbar's buttons are counted this way.
+ */
+export declare function PhiWidgetCountToolButton({ count, min, max, label, onChange, }: PhiWidgetCountToolButtonProps): import("react").JSX.Element;
 export type PhiDescriptionWidgetItemsToolButtonProps = {
-    value?: string[] | null;
-    onChange: (value: string[]) => void;
+    value?: PhiBulletListEntry[] | null;
+    onChange: (value: PhiBulletListEntry[]) => void;
 };
 export declare function PhiDescriptionWidgetItemsToolButton({ value, onChange, }: PhiDescriptionWidgetItemsToolButtonProps): import("react").JSX.Element;

package/components/widgets/client/shared/phi-widget-tool-buttons.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { stopPhiOverlayEvent } from "../../../../helpers/overlay-events";
 import { useEffect, useState } from "react";
-import { AlignCenterOutlined, AlignLeftOutlined, AlignRightOutlined, BgColorsOutlined, FontSizeOutlined, FormatPainterOutlined, LinkOutlined, MenuOutlined, } from "@ant-design/icons";
 import { formatUrl } from "@lexical/link";
 import { PHI_WIDGET_FONT_FAMILY_OPTIONS } from "../../helpers/font-family";
 import { PHI_WIDGET_FONT_SIZE_OPTIONS } from "../../helpers/font-size";
@@ -23,13 +23,9 @@ import { usePhiWidgetScaffoldPopup } from "./phi-widget-scaffold-popup";
 import { PhiInternalAssetReferencePickerButton } from "./phi-widget-image-tool-button";
 import { PHI_Z_INDEX } from "../../../../theme/phi-tokens";
 import { PhiFlexControl } from "../../../controls/phi-flex-control";
+import { PHI_HTML_LINK_SCHEMES } from "../../../../constants/html-link-schemes";
 import { PhiTypographyControl } from "../../../controls/phi-typography-control";
-function stopOverlayEvent(event) {
-    event.stopPropagation();
-}
-function stopOverlayMouseEvent(event) {
-    event.stopPropagation();
-}
+import { PhiIcon } from "../../../shell/phi-icon";
 function preserveEditorSelectionMouseEvent(event) {
     event.preventDefault?.();
     event.stopPropagation();
@@ -47,7 +43,7 @@ function resolveExternalOrFragmentLink(value) {
     const formatted = formatUrl(normalized);
     try {
         const url = new URL(formatted);
-        return ["http:", "https:", "mailto:", "sms:", "tel:"].includes(url.protocol)
+        return PHI_HTML_LINK_SCHEMES.includes(url.protocol.slice(0, -1))
             ? formatted
             : null;
     }
@@ -57,32 +53,32 @@ function resolveExternalOrFragmentLink(value) {
 }
 export function PhiWidgetIconToolButton({ value, ariaLabel, onChange, }) {
     const labels = usePhiAuthoringToolsLabels();
-    return (_jsx(PhiWidgetIconPickerButton, { value: value ?? null, buttonAriaLabel: ariaLabel ?? labels.iconPicker.buttonAriaLabel, labels: labels.iconPicker, onChange: onChange }));
+    return (_jsx(PhiWidgetIconPickerButton, { value: value ?? null, buttonAriaLabel: ariaLabel ?? labels.iconPicker.buttonAriaLabel, labels: labels.iconPicker, placement: "left", onChange: onChange }));
 }
 export function PhiWidgetColorToolButton({ value, ariaLabel, onChange, }) {
     const labels = usePhiAuthoringToolsLabels();
     const currentColor = typeof value === "string" && value.trim().length > 0 ? value : undefined;
     const popup = usePhiWidgetScaffoldPopup();
-    return (_jsx(PhiColorFieldControl, { value: currentColor, defaultValue: currentColor ?? "#1677ff", allowClear: true, getPopupContainer: popup.getPopupContainer, popupClassName: popup.rootClassName, onOpenChange: popup.setOpen, renderPanel: (panel) => (_jsx("div", { onClick: stopOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopOverlayEvent, onKeyDown: stopOverlayEvent, children: panel })), onChange: (css) => {
+    return (_jsx(PhiColorFieldControl, { value: currentColor, defaultValue: currentColor ?? "#1677ff", allowClear: true, getPopupContainer: popup.getPopupContainer, popupClassName: popup.rootClassName, onOpenChange: popup.setOpen, renderPanel: (panel) => (_jsx("div", { onClick: stopPhiOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopPhiOverlayEvent, onKeyDown: stopPhiOverlayEvent, children: panel })), onChange: (css) => {
             onChange(css);
         }, onClear: () => {
             onChange(null);
-        }, children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel ?? labels.fallbacks.widgetColor, icon: _jsx(BgColorsOutlined, { style: currentColor ? { color: currentColor } : undefined }), onClick: () => undefined }) }) }));
+        }, children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel ?? labels.fallbacks.widgetColor, icon: _jsx(PhiIcon, { name: "bg-colors", size: "inherit", style: currentColor ? { color: currentColor } : undefined }), onClick: () => undefined }) }) }));
 }
 export function PhiWidgetTypographyToolButton({ fontFamily, fontSize, defaultFontSize = "inherit", ariaLabel, onChange, }) {
     const labels = usePhiAuthoringToolsLabels();
     const currentFontFamily = fontFamily ?? "inherit";
     const currentFontSize = fontSize ?? defaultFontSize;
     const popup = usePhiWidgetScaffoldPopup();
-    return (_jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: popup.getPopupContainer, rootClassName: popup.rootClassName, onOpenChange: popup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { minWidth: 220 }, onClick: stopOverlayEvent, onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, children: [_jsxs("label", { children: [_jsx(PhiTypographyControl, { style: { display: "block", marginBottom: 4 }, children: "Font" }), _jsx(PhiSelectControl, { value: currentFontFamily, options: PHI_WIDGET_FONT_FAMILY_OPTIONS, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, popupZIndex: PHI_Z_INDEX.authoringPopupNested, onChange: (nextValue) => {
+    return (_jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: popup.getPopupContainer, rootClassName: popup.rootClassName, onOpenChange: popup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { minWidth: 220 }, onClick: stopPhiOverlayEvent, onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, children: [_jsxs("label", { children: [_jsx(PhiTypographyControl, { style: { display: "block", marginBottom: 4 }, children: labels.text.font }), _jsx(PhiSelectControl, { value: currentFontFamily, options: PHI_WIDGET_FONT_FAMILY_OPTIONS, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, popupZIndex: PHI_Z_INDEX.authoringPopupNested, onChange: (nextValue) => {
                                 onChange({
                                     fontFamily: nextValue,
                                 });
-                            }, style: { width: "100%" } })] }), _jsxs("label", { children: [_jsx(PhiTypographyControl, { style: { display: "block", marginBottom: 4 }, children: "Size" }), _jsx(PhiSelectControl, { value: currentFontSize, options: PHI_WIDGET_FONT_SIZE_OPTIONS, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, popupZIndex: PHI_Z_INDEX.authoringPopupNested, onChange: (nextValue) => {
+                            }, style: { width: "100%" } })] }), _jsxs("label", { children: [_jsx(PhiTypographyControl, { style: { display: "block", marginBottom: 4 }, children: labels.text.size }), _jsx(PhiSelectControl, { value: currentFontSize, options: PHI_WIDGET_FONT_SIZE_OPTIONS, getPopupContainer: popup.getPopupContainer, popupRootClassName: popup.rootClassName, popupZIndex: PHI_Z_INDEX.authoringPopupNested, onChange: (nextValue) => {
                                 onChange({
                                     fontSize: nextValue,
                                 });
-                            }, style: { width: "100%" } })] })] }), children: _jsx("span", { onMouseDown: stopOverlayMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel ?? labels.fallbacks.widgetTypography, icon: _jsx(FontSizeOutlined, {}), onClick: () => undefined }) }) }));
+                            }, style: { width: "100%" } })] })] }), children: _jsx("span", { onMouseDown: stopPhiOverlayEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel ?? labels.fallbacks.widgetTypography, icon: _jsx(PhiIcon, { name: "font-size", size: "inherit" }), onClick: () => undefined }) }) }));
 }
 const PHI_HTML_WIDGET_BLOCK_OPTIONS = [
     { value: "paragraph", label: "P" },
@@ -92,21 +88,23 @@ const PHI_HTML_WIDGET_BLOCK_OPTIONS = [
     { value: "bullet", label: "UL" },
     { value: "number", label: "OL" },
 ];
+// Captions come from the authoring tools' label set by `labelKey`, in the author's language.
 const PHI_HTML_WIDGET_ALIGNMENT_OPTIONS = [
-    { value: "left", label: "Align left", icon: _jsx(AlignLeftOutlined, {}) },
-    { value: "center", label: "Align center", icon: _jsx(AlignCenterOutlined, {}) },
-    { value: "right", label: "Align right", icon: _jsx(AlignRightOutlined, {}) },
-    { value: "justify", label: "Justify", icon: _jsx(MenuOutlined, {}) },
+    { value: "left", labelKey: "alignLeft", icon: _jsx(PhiIcon, { name: "align-left", size: "inherit" }) },
+    { value: "center", labelKey: "alignCenter", icon: _jsx(PhiIcon, { name: "align-center", size: "inherit" }) },
+    { value: "right", labelKey: "alignRight", icon: _jsx(PhiIcon, { name: "align-right", size: "inherit" }) },
+    { value: "justify", labelKey: "justify", icon: _jsx(PhiIcon, { name: "menu", size: "inherit" }) },
 ];
 function resolvePhiHtmlWidgetAlignmentIcon(alignment) {
-    return PHI_HTML_WIDGET_ALIGNMENT_OPTIONS.find((option) => option.value === alignment)?.icon ?? _jsx(AlignLeftOutlined, {});
+    return PHI_HTML_WIDGET_ALIGNMENT_OPTIONS.find((option) => option.value === alignment)?.icon ?? _jsx(PhiIcon, { name: "align-left", size: "inherit" });
 }
+// The key is also the caption's key in the label set.
 const PHI_HTML_WIDGET_STYLE_TOGGLES = [
-    { key: "bold", format: "bold", label: "Bold" },
-    { key: "italic", format: "italic", label: "Italic" },
-    { key: "underline", format: "underline", label: "Underline" },
-    { key: "strike", format: "strikethrough", label: "Strike" },
-    { key: "code", format: "code", label: "Code" },
+    { key: "bold", format: "bold" },
+    { key: "italic", format: "italic" },
+    { key: "underline", format: "underline" },
+    { key: "strike", format: "strikethrough" },
+    { key: "code", format: "code" },
 ];
 function usePhiHtmlWidgetEditorState(blockId) {
     const [state, setState] = useState(() => resolvePhiHtmlWidgetEditorBridge(blockId)?.getState() ?? null);
@@ -135,12 +133,12 @@ export function PhiHtmlWidgetToolbarTools({ blockId, }) {
             setLinkDraft(state?.linkUrl ?? "");
         }
     };
-    return (_jsxs(_Fragment, { children: [_jsx("span", { onClick: stopOverlayEvent, onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex", minWidth: 84 }, children: _jsx(PhiSelectControl, { size: "small", value: state?.blockType ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.blockType, options: PHI_HTML_WIDGET_BLOCK_OPTIONS, disabled: !bridge, popupMatchSelectWidth: false, getPopupContainer: blockPopup.getPopupContainer, popupRootClassName: blockPopup.rootClassName, popupZIndex: PHI_HTML_WIDGET_TOOL_POPUP_Z_INDEX, onOpenChange: blockPopup.setOpen, onChange: (value) => {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { onClick: stopPhiOverlayEvent, onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex", minWidth: 84 }, children: _jsx(PhiSelectControl, { size: "small", value: state?.blockType ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.blockType, options: PHI_HTML_WIDGET_BLOCK_OPTIONS, disabled: !bridge, popupMatchSelectWidth: false, getPopupContainer: blockPopup.getPopupContainer, popupRootClassName: blockPopup.rootClassName, popupZIndex: PHI_HTML_WIDGET_TOOL_POPUP_Z_INDEX, onOpenChange: blockPopup.setOpen, onChange: (value) => {
                         bridge?.setBlockType(value);
-                    }, style: { minWidth: 84 } }) }), _jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: alignmentPopup.getPopupContainer, rootClassName: alignmentPopup.rootClassName, onOpenChange: alignmentPopup.setOpen, zIndex: PHI_WIDGET_OVERLAY_Z_INDEX, content: _jsx(PhiFlexControl, { gap: 4, onClick: stopOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopOverlayEvent, children: PHI_HTML_WIDGET_ALIGNMENT_OPTIONS.map((option) => (_jsx(PhiButtonControl, { type: (state?.alignment ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.alignment) === option.value ? "primary" : "text", size: "small", ariaLabel: option.label, tooltip: option.label, icon: option.icon, disabled: !bridge, onClick: () => {
+                    }, style: { minWidth: 84 } }) }), _jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: alignmentPopup.getPopupContainer, rootClassName: alignmentPopup.rootClassName, onOpenChange: alignmentPopup.setOpen, zIndex: PHI_WIDGET_OVERLAY_Z_INDEX, content: _jsx(PhiFlexControl, { gap: 4, onClick: stopPhiOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopPhiOverlayEvent, children: PHI_HTML_WIDGET_ALIGNMENT_OPTIONS.map((option) => (_jsx(PhiButtonControl, { type: (state?.alignment ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.alignment) === option.value ? "primary" : "text", size: "small", ariaLabel: labels.richText[option.labelKey], tooltip: labels.richText[option.labelKey], icon: option.icon, disabled: !bridge, onClick: () => {
                             bridge?.setAlignment(option.value);
                             bridge?.focus();
-                        } }, option.value))) }), children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: labels.richText.alignment, tooltip: labels.richText.alignment, icon: resolvePhiHtmlWidgetAlignmentIcon(state?.alignment ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.alignment), disabled: !bridge, onClick: () => undefined }) }) }), _jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: stylePopup.getPopupContainer, rootClassName: stylePopup.rootClassName, onOpenChange: stylePopup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsx(PhiFlexControl, { vertical: true, gap: 8, onClick: stopOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopOverlayEvent, children: PHI_HTML_WIDGET_STYLE_TOGGLES.map((toggle) => (_jsx("div", { onMouseDown: preserveEditorSelectionMouseEvent, children: _jsx(PhiCheckboxControl, { checked: toggle.key === "bold"
+                        } }, option.value))) }), children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: labels.richText.alignment, tooltip: labels.richText.alignment, icon: resolvePhiHtmlWidgetAlignmentIcon(state?.alignment ?? PHI_HTML_WIDGET_EDITOR_EMPTY_STATE.alignment), disabled: !bridge, onClick: () => undefined }) }) }), _jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: stylePopup.getPopupContainer, rootClassName: stylePopup.rootClassName, onOpenChange: stylePopup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsx(PhiFlexControl, { vertical: true, gap: 8, onClick: stopPhiOverlayEvent, onMouseDown: preserveEditorSelectionMouseEvent, onPointerDown: stopPhiOverlayEvent, children: PHI_HTML_WIDGET_STYLE_TOGGLES.map((toggle) => (_jsx("div", { onMouseDown: preserveEditorSelectionMouseEvent, children: _jsx(PhiCheckboxControl, { checked: toggle.key === "bold"
                                 ? state?.bold
                                 : toggle.key === "italic"
                                     ? state?.italic
@@ -148,20 +146,20 @@ export function PhiHtmlWidgetToolbarTools({ blockId, }) {
                                         ? state?.underline
                                         : toggle.key === "strike"
                                             ? state?.strike
-                                            : state?.code, disabled: !bridge, label: toggle.label, onChange: () => {
+                                            : state?.code, disabled: !bridge, label: labels.richText[toggle.key], onChange: () => {
                                 bridge?.toggleFormat(toggle.format);
                                 bridge?.focus();
-                            } }) }, toggle.key))) }), children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: hasActiveTextStyle ? "primary" : "text", size: "small", ariaLabel: labels.richText.styles, icon: _jsx(FormatPainterOutlined, {}), disabled: !bridge, onClick: () => undefined }) }) }), _jsx(PhiWidgetColorToolButton, { value: state?.textColor ?? null, ariaLabel: labels.richText.color, onChange: (color) => {
+                            } }) }, toggle.key))) }), children: _jsx("span", { onMouseDown: preserveEditorSelectionMouseEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: hasActiveTextStyle ? "primary" : "text", size: "small", ariaLabel: labels.richText.styles, icon: _jsx(PhiIcon, { name: "format-painter", size: "inherit" }), disabled: !bridge, onClick: () => undefined }) }) }), _jsx(PhiWidgetColorToolButton, { value: state?.textColor ?? null, ariaLabel: labels.richText.color, onChange: (color) => {
                     bridge?.setTextColor(color);
                     bridge?.focus();
                 } }), _jsx(PhiInternalAssetReferencePickerButton, { blockId: blockId, ariaLabel: labels.richText.insertAsset, onSelect: (asset) => {
                     bridge?.insertImage(createPhiAssetUri(asset.id), asset.altText?.trim() || asset.title?.trim() || asset.originalName);
                     bridge?.focus();
-                } }), _jsx(PhiPopoverControl, { open: linkPopoverOpen, trigger: "click", placement: "bottomRight", onOpenChange: handleLinkPopoverOpenChange, getPopupContainer: linkPopup.getPopupContainer, rootClassName: linkPopup.rootClassName, zIndex: PHI_WIDGET_OVERLAY_Z_INDEX, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, onClick: stopOverlayEvent, onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, children: [_jsx(PhiPageReferencePicker, { onSelect: (selection) => {
+                } }), _jsx(PhiPopoverControl, { open: linkPopoverOpen, trigger: "click", placement: "bottomRight", onOpenChange: handleLinkPopoverOpenChange, getPopupContainer: linkPopup.getPopupContainer, rootClassName: linkPopup.rootClassName, zIndex: PHI_WIDGET_OVERLAY_Z_INDEX, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, onClick: stopPhiOverlayEvent, onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, children: [_jsx(PhiPageReferencePicker, { onSelect: (selection) => {
                                 bridge?.setLink(createPhiPageUri(selection.reference));
                                 bridge?.focus();
                                 handleLinkPopoverOpenChange(false);
-                            } }), _jsx(PhiTextControl, { size: "small", value: linkDraft, placeholder: "https://example.com", onChange: (nextValue) => setLinkDraft(nextValue ?? ""), onKeyDown: stopOverlayEvent }), _jsxs(PhiFlexControl, { gap: 8, justify: "space-between", children: [_jsx(PhiButtonControl, { size: "small", disabled: !bridge || !state?.linkUrl, label: labels.richText.linkRemove, onClick: () => {
+                            } }), _jsx(PhiTextControl, { size: "small", value: linkDraft, placeholder: "https://example.com", onChange: (nextValue) => setLinkDraft(nextValue ?? ""), onKeyDown: stopPhiOverlayEvent }), _jsxs(PhiFlexControl, { gap: 8, justify: "space-between", children: [_jsx(PhiButtonControl, { size: "small", disabled: !bridge || !state?.linkUrl, label: labels.richText.linkRemove, onClick: () => {
                                         bridge?.setLink(null);
                                         bridge?.focus();
                                         handleLinkPopoverOpenChange(false);
@@ -173,7 +171,7 @@ export function PhiHtmlWidgetToolbarTools({ blockId, }) {
                                         bridge?.setLink(nextUrl);
                                         bridge?.focus();
                                         handleLinkPopoverOpenChange(false);
-                                    } })] })] }), children: _jsx("span", { onMouseDown: stopOverlayMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: state?.linkUrl ? "primary" : "text", size: "small", ariaLabel: labels.richText.link, icon: _jsx(LinkOutlined, {}), disabled: !bridge, onClick: () => undefined }) }) })] }));
+                                    } })] })] }), children: _jsx("span", { onMouseDown: stopPhiOverlayEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: state?.linkUrl ? "primary" : "text", size: "small", ariaLabel: labels.richText.link, icon: _jsx(PhiIcon, { name: "link", size: "inherit" }), disabled: !bridge, onClick: () => undefined }) }) })] }));
 }
 export function PhiMarkdownWidgetToolbarTools({ blockId, }) {
     const labels = usePhiAuthoringToolsLabels();
@@ -189,31 +187,41 @@ export function PhiMarkdownWidgetToolbarTools({ blockId, }) {
                     bridge?.insert(`![${alt}](${createPhiAssetUri(asset.id)})`);
                 } })] }));
 }
-export function PhiDescriptionWidgetItemsToolButton({ value, onChange, }) {
-    const labels = usePhiAuthoringToolsLabels();
-    const itemCount = Array.isArray(value) ? value.length : 0;
+/**
+ * How many of something a Widget has, set from its scaffold: a button showing the number, and a field
+ * behind it. The Description's items and the Command Toolbar's buttons are counted this way.
+ */
+export function PhiWidgetCountToolButton({ count, min, max, label, onChange, }) {
     const popup = usePhiWidgetScaffoldPopup();
     /*
      * What is being typed, apart from what is stored. The field reported every keystroke, and each one
      * resized the list: typing "10" committed "1" first and dropped entries two onwards before the "0"
      * arrived. The number is taken when the field is left or Enter is pressed.
      */
-    const [draft, setDraft] = useState({ stored: itemCount, count: itemCount });
-    if (draft.stored !== itemCount) {
+    const [draft, setDraft] = useState({ stored: count, count: count });
+    if (draft.stored !== count) {
         // A change from elsewhere -- an undo, another editor -- replaces what was being typed, adjusted
         // during render so the field never shows the stale number for a frame.
-        setDraft({ stored: itemCount, count: itemCount });
+        setDraft({ stored: count, count });
     }
-    const draftCount = draft.stored === itemCount ? draft.count : itemCount;
-    const setDraftCount = (count) => setDraft({ stored: itemCount, count });
+    const draftCount = draft.stored === count ? draft.count : count;
+    const setDraftCount = (next) => setDraft({ stored: count, count: next });
+    /* An emptied field on the way to a new number is not a count; out of range is held to the range. */
     const commit = () => {
-        if (draftCount === itemCount)
+        if (draftCount == null || !Number.isFinite(draftCount))
+            return;
+        const nextCount = Math.max(min, Math.min(max, Math.trunc(draftCount)));
+        if (nextCount === count)
             return;
-        onChange(resizePhiDescriptionItems(value, draftCount));
+        onChange(nextCount);
     };
-    return (_jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: popup.getPopupContainer, rootClassName: popup.rootClassName, onOpenChange: popup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, onClick: stopOverlayEvent, onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, children: [_jsx(PhiTypographyControl, { type: "secondary", children: "Items" }), _jsx(PhiNumberControl, { min: 0, max: 12, precision: 0, value: draftCount, onChange: setDraftCount, onBlur: commit, onKeyDown: (event) => {
-                        stopOverlayEvent(event);
+    return (_jsx(PhiPopoverControl, { trigger: "click", placement: "bottomRight", getPopupContainer: popup.getPopupContainer, rootClassName: popup.rootClassName, onOpenChange: popup.setOpen, zIndex: PHI_Z_INDEX.authoringPopup, content: _jsxs(PhiFlexControl, { vertical: true, gap: 8, onClick: stopPhiOverlayEvent, onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, children: [_jsx(PhiTypographyControl, { type: "secondary", children: label }), _jsx(PhiNumberControl, { min: min, max: max, precision: 0, value: draftCount, onChange: setDraftCount, onBlur: commit, onKeyDown: (event) => {
+                        stopPhiOverlayEvent(event);
                         if (event.key === "Enter")
                             commit();
-                    } })] }), children: _jsx("span", { onMouseDown: stopOverlayMouseEvent, onClick: stopOverlayEvent, onPointerDown: stopOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: labels.descriptions.items, tooltip: labels.descriptions.items, label: itemCount, onClick: () => undefined }) }) }));
+                    } })] }), children: _jsx("span", { onMouseDown: stopPhiOverlayEvent, onClick: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: label, tooltip: label, label: count, onClick: () => undefined }) }) }));
+}
+export function PhiDescriptionWidgetItemsToolButton({ value, onChange, }) {
+    const labels = usePhiAuthoringToolsLabels();
+    return (_jsx(PhiWidgetCountToolButton, { count: Array.isArray(value) ? value.length : 0, min: 0, max: 12, label: labels.descriptions.items, onChange: (count) => onChange(resizePhiDescriptionItems(value, count)) }));
 }

package/components/widgets/config/background-pattern-live.js

@@ -1,3 +1,4 @@
+import { phiBackgroundDirectionToDegrees } from "./background";
 import { PHI_CORE_BACKGROUND_PATTERN_KEYS, } from "./background-pattern-contract";
 /**
  * The rendered form of a Pattern Overlay.
@@ -43,24 +44,13 @@ function resolveDirection(values) {
         ? value
         : "45deg";
 }
-function directionToDegrees(direction) {
-    if (direction.endsWith("deg"))
-        return Number.parseFloat(direction);
-    if (direction === "to top")
-        return 0;
-    if (direction === "to right")
-        return 90;
-    if (direction === "to bottom")
-        return 180;
-    return 270;
-}
 function resolvePatternShapeFamilies(patternKey, values) {
     const scale = resolveScale(values);
     if (patternKey === PHI_CORE_BACKGROUND_PATTERN_KEYS.stripes) {
         const lineWidth = Math.max(1, scale / 4);
         return [{
                 tile: scale,
-                rotate: directionToDegrees(resolveDirection(values)),
+                rotate: phiBackgroundDirectionToDegrees(resolveDirection(values)),
                 shapes: `<rect width="${scale}" height="${lineWidth}" fill="#fff"/>`,
             }];
     }
@@ -88,7 +78,7 @@ function resolvePatternShapeFamilies(patternKey, values) {
             }];
     }
     if (patternKey === PHI_CORE_BACKGROUND_PATTERN_KEYS.crosshatch) {
-        const degrees = directionToDegrees(resolveDirection(values));
+        const degrees = phiBackgroundDirectionToDegrees(resolveDirection(values));
         return [degrees, degrees + 90].map((rotate) => ({
             tile: scale,
             rotate,
@@ -107,7 +97,7 @@ function resolvePatternInkPaint(ink) {
     if (ink.kind === "color") {
         return { defs: "", paint: ink.color };
     }
-    const radians = (directionToDegrees(ink.direction) * Math.PI) / 180;
+    const radians = (phiBackgroundDirectionToDegrees(ink.direction) * Math.PI) / 180;
     const dx = Math.sin(radians) / 2;
     const dy = Math.cos(radians) / 2;
     const stops = ink.stops

package/components/widgets/config/background.d.ts

@@ -1,10 +1,12 @@
 import type { CSSProperties } from "react";
 import type { PhiMediaImageSourceConfig } from "../../../types/media";
 import { type PhiImageDeliveryProjection } from "../../media/image-presentation";
-import { type PhiLayoutEffectId } from "../../../types/layout-style";
+import { type PhiBackgroundFilter, type PhiGlassLayoutEffectId } from "../../../types/layout-style";
 import { type PhiBackgroundNoiseGrain, type PhiBackgroundPatternInk, type PhiBackgroundPatternKey, type PhiBackgroundPatternValues } from "./background-pattern-contract";
 export type { PhiBackgroundNoiseGrain } from "./background-pattern-contract";
 export type PhiBackgroundDirection = "to right" | "to left" | "to bottom" | "to top" | `${number}deg`;
+/** A direction as degrees, clockwise from the top the way CSS gradients count. */
+export declare function phiBackgroundDirectionToDegrees(direction: PhiBackgroundDirection): number;
 export type PhiBackgroundGradientStop = {
     color: string;
     percent: number;
@@ -88,8 +90,9 @@ export type PhiBackgroundNoiseOverlay = {
  *
  * It carries the same ink a Pattern does, so a flat colour and a directional fade -- dark at the
  * bottom, clear at the top -- are the same Overlay with a different paint. This is what darkens a
- * photograph enough to carry text, and it does so as a layer rather than as a filter: `dim` acts on
- * the element and takes the content rendered inside it along, a wash only covers the paint.
+ * photograph enough to carry text, and it does so as a layer rather than as a filter: a filter on the
+ * element takes the content rendered inside it along, a wash only covers the paint. There is no `dim`
+ * filter for that reason -- this Overlay in black at an opacity is what darkening is.
  */
 export type PhiBackgroundColorOverlay = {
     kind: "color";
@@ -102,7 +105,7 @@ export declare const PHI_BACKGROUND_OVERLAY_DEFAULT_OPACITY = 0.14;
 export type PhiCmsBackgroundWidgetConfig = {
     base: PhiBackgroundBaseColor | PhiBackgroundBaseGradient | PhiBackgroundBaseImage | PhiBackgroundBaseNone;
     overlay?: PhiBackgroundOverlay | null;
-    effect?: PhiLayoutEffectId | null;
+    filter?: PhiBackgroundFilter | null;
     motion?: PhiBackgroundMotion | null;
 };
 export declare const PHI_BACKGROUND_PARALLAX_DEFAULT_STRENGTH = 0.2;
@@ -156,8 +159,7 @@ export declare function resolvePhiBackgroundWidgetStyle(config: unknown): CSSPro
  * 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 declare function phiBackgroundWidgetConfigPaintsGround(config: unknown): boolean;
 /**
@@ -167,14 +169,34 @@ export declare function phiBackgroundWidgetConfigPaintsGround(config: unknown):
  * 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 declare function phiBackgroundBaseSupportsGlassEffect(base: PhiCmsBackgroundWidgetConfig["base"]): boolean;
 /**
- * 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 declare function phiBackgroundSupportsBlur(config: PhiCmsBackgroundWidgetConfig): boolean;
+/** Whether this Background can render the given Filter at all; the Control offers what this allows. */
+export declare function phiBackgroundSupportsFilter(config: PhiCmsBackgroundWidgetConfig, filter: PhiBackgroundFilter): boolean;
+/**
+ * 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 declare function resolvePhiBackgroundFilter(config: unknown): PhiBackgroundFilter | null;
+/** The glass strength this Background frosts its backdrop with, if any. */
+export declare function resolvePhiBackgroundPane(config: unknown): PhiGlassLayoutEffectId | null;
+/** How far `blur` softens the paint. One value, so a ground layer and its preview never disagree. */
+export declare const PHI_BACKGROUND_BLUR_RADIUS_PX = 6;
+export declare const PHI_BACKGROUND_BLUR_FILTER = "blur(6px)";
+/**
+ * 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 declare function resolvePhiBackgroundEffect(config: unknown): PhiLayoutEffectId | null;
+export declare function resolvePhiBackgroundGroundFilter(config: unknown): string | null;
 export declare function resolvePhiBackgroundMotion(config: unknown): PhiBackgroundMotion | null;
 export declare function resolvePhiBackgroundMotionHostStyle(config: unknown): CSSProperties;