@phis/ui 0.2.1 → 0.4.0

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;