@phis/ui 0.2.0 → 0.3.0

package/components/controls/phi-control-option-content.js

@@ -8,8 +8,12 @@ import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
  * One option, drawn the same way wherever options are drawn.
  *
  * `presentation` says where the option sits, not how it should look: `dropdown` is a row in an open list,
- * `option` is an option standing on its own next to its siblings -- a checkbox, a radio -- and `selection`
- * is the chosen one shown inside a closed Control.
+ * `tree` is a row in an open tree, `option` is an option standing on its own next to its siblings -- a
+ * checkbox, a radio -- and `selection` is the chosen one shown inside a closed Control.
+ *
+ * A tree row is a list row in everything but its box: the tree draws the row's height and its hover
+ * ground around the title by line height, so a title that sets its own line height -- as a list row does
+ * to fill the option's box -- stands above the ground the tree paints for it.
  *
  * **Where the description hangs follows from that, and only from that.** In a list a person scans,
  * pointing at a row is already the cursor, and a hint that fires on every row passed over is noise, so
@@ -22,15 +26,16 @@ import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
 export function PhiControlOptionContent({ option, presentation, }) {
     const { token } = usePhiConfig();
     const standing = presentation === "option";
+    const row = presentation === "dropdown" || presentation === "tree";
     const content = (_jsxs("span", { style: {
-            display: standing ? "inline-flex" : "flex",
+            display: standing || presentation === "tree" ? "inline-flex" : "flex",
             alignItems: "center",
             gap: standing ? token.paddingXXS : token.paddingXS,
             ...(presentation === "dropdown" ? { height: "100%", lineHeight: 1 } : {}),
             minWidth: 0,
             maxWidth: "100%",
             ...(standing ? {} : { overflow: "hidden", whiteSpace: "nowrap" }),
-        }, children: [presentation === "dropdown" && option.description ? (_jsx(PhiDescriptionHint, { description: option.description })) : null, option.preview?.kind === "background" ? (_jsx("span", { "aria-hidden": "true", style: {
+        }, children: [row && option.description ? (_jsx(PhiDescriptionHint, { description: option.description })) : null, option.preview?.kind === "background" ? (_jsx("span", { "aria-hidden": "true", style: {
                     width: 24,
                     height: 20,
                     flex: "0 0 24px",

package/components/controls/phi-date-picker-control.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { usePhiCalendarAdapterClient } from "../runtime/runtime-module-calendar-adapter-client-manifest";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
 export function PhiDatePickerControl({ adapterKey, label, ...props }) {
     const adapter = usePhiCalendarAdapterClient(adapterKey);
-    return (_jsx(PhiLabeledControl, { label: label, fill: true, children: adapter.renderDatePicker(props) }));
+    const { labelId, labelledBy } = usePhiControlLabel(label);
+    return (_jsx(PhiLabeledControl, { label: label, labelId: labelId, fill: true, children: adapter.renderDatePicker({ ...props, ariaLabelledBy: labelledBy }) }));
 }

package/components/controls/phi-description-tooltip-icon.js

@@ -1,10 +1,10 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { InfoCircleOutlined } from "@ant-design/icons";
 import { usePhiConfig } from "../root/phi-config-provider";
 import { PhiNameControl } from "./phi-name-control";
+import { PhiIcon } from "../shell/phi-icon";
 /** Canonical icon for Control and collection descriptions. */
-const PHI_DESCRIPTION_TOOLTIP_ICON = _jsx(InfoCircleOutlined, {});
+const PHI_DESCRIPTION_TOOLTIP_ICON = _jsx(PhiIcon, { name: "info", size: "inherit" });
 /**
  * The glyph that carries a description, wherever a surface has a label and no room for a second line.
  *

package/components/controls/phi-dialog-control.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { PhiCmsMountPolicy } from "../../types/cms-mount-policy";
-import type { PhiCmsOverlayMaskConfig, PhiOverlayCloseSource } from "../../types/cms-overlay";
+import type { PhiOverlayCloseSource, PhiOverlayMaskBehaviour } from "../../types/cms-overlay";
 import type { PhiControlSize } from "../../types/control";
 import { type PhiAlertControlProps } from "./phi-alert-control";
 import type { PhiButtonType } from "./phi-button-types";
@@ -23,7 +23,7 @@ import type { PhiButtonType } from "./phi-button-types";
  * The shape it renders is the one OVERLAYS.md describes for a tree Overlay, so the two paths land on the
  * same thing rather than on something similar: the Body is a vertical flex one `base` apart and one
  * `base` in from every edge, holding the notice first and the subject under it; the Footer anchors its
- * actions right, `xs` apart, `xs` from the fold and `base` from the sides. Both sides derive that from
+ * actions right as one compact group, `xs` from the fold and `base` from the sides. Both sides derive that from
  * the same tokens rather than from each other -- the Layout presets are creation defaults a Builder may
  * edit afterwards, which is not a constant to depend on.
  *
@@ -66,7 +66,7 @@ export type PhiDialogControlProps = {
     centered?: boolean;
     closable?: boolean;
     keyboard?: boolean;
-    mask?: PhiCmsOverlayMaskConfig;
+    mask?: PhiOverlayMaskBehaviour;
     mountPolicy?: PhiCmsMountPolicy;
     /** A styling hook for a surface that mounts the Dialog inside its own popup container. */
     rootClassName?: string;

package/components/controls/phi-dialog-control.js

@@ -3,13 +3,20 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { PHI_SPACE } from "../../theme/antd-css-var-contract";
 import { PhiAlertControl } from "./phi-alert-control";
 import { PhiButtonControl } from "./phi-button-control";
+import { PhiCompactGroupControl } from "./phi-compact-group-control";
 import { PhiFlexControl } from "./phi-flex-control";
 import { PhiModalControl } from "./phi-modal-control";
 export function PhiDialogControl({ open, title, children, alert, actions, controlSize = "medium", centered, closable, keyboard, mask, mountPolicy, rootClassName, onDismiss, afterOpenChange, }) {
-    return (_jsx(PhiModalControl, { open: open, title: title, closable: closable, keyboard: keyboard, mask: mask, mountPolicy: mountPolicy, centered: centered, controlSize: controlSize, rootClassName: rootClassName, onDismiss: onDismiss, afterOpenChange: afterOpenChange, body: _jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, style: { padding: PHI_SPACE.base, width: "100%", minWidth: 0 }, children: [alert == null ? null : _jsx(PhiAlertControl, { ...alert }), children] }), footer: actions == null || actions.length === 0 ? null : (_jsx(PhiFlexControl, { align: "center", justify: "end", wrap: true, gap: PHI_SPACE.xs, style: {
+    return (_jsx(PhiModalControl, { open: open, title: title, closable: closable, keyboard: keyboard, mask: mask, mountPolicy: mountPolicy, centered: centered, controlSize: controlSize, rootClassName: rootClassName, onDismiss: onDismiss, afterOpenChange: afterOpenChange, body: _jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, style: { padding: PHI_SPACE.base, width: "100%", minWidth: 0 }, children: [alert == null ? null : _jsx(PhiAlertControl, { ...alert }), children] }), 
+        /*
+         * The actions are one compact group, as a tree Overlay's footer is (OVERLAYS.md): Cancel and Apply
+         * are the two ends of one decision, and a gap between them read as two unrelated offers. A compact
+         * group does not wrap.
+         */
+        footer: actions == null || actions.length === 0 ? null : (_jsx(PhiFlexControl, { align: "center", justify: "end", style: {
                 paddingBlock: PHI_SPACE.xs,
                 paddingInline: PHI_SPACE.base,
                 width: "100%",
                 minWidth: 0,
-            }, children: actions.map((action) => (_jsx(PhiButtonControl, { label: action.label, icon: action.icon, type: action.type, danger: action.danger, disabled: action.disabled, loading: action.loading, onClick: action.onClick }, action.key))) })) }));
+            }, children: _jsx(PhiCompactGroupControl, { children: actions.map((action) => (_jsx(PhiButtonControl, { label: action.label, icon: action.icon, type: action.type, danger: action.danger, disabled: action.disabled, loading: action.loading, onClick: action.onClick }, action.key))) }) })) }));
 }

package/components/controls/phi-drag-handle-control.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Button } from "antd";
-import { HolderOutlined } from "@ant-design/icons";
+import { PhiIcon } from "../shell/phi-icon";
 const PHI_DRAG_HANDLE_LISTENER_KEYS = ["onPointerDown", "onMouseDown", "onTouchStart", "onKeyDown"];
 const PHI_DRAG_HANDLE_ATTRIBUTE_KEYS = [
     "role",
@@ -27,7 +27,7 @@ export function PhiDragHandleControl({ ariaLabel, setActivatorRef, listeners: li
         ? {}
         : pick(libraryListeners, PHI_DRAG_HANDLE_LISTENER_KEYS));
     const attributes = pick(libraryAttributes, PHI_DRAG_HANDLE_ATTRIBUTE_KEYS);
-    return (_jsx(Button, { ref: setActivatorRef, className: className, "aria-label": ariaLabel, icon: icon ?? _jsx(HolderOutlined, {}), type: "text", size: size, disabled: disabled, ...attributes, ...listeners, 
+    return (_jsx(Button, { ref: setActivatorRef, className: className, "aria-label": ariaLabel, icon: icon ?? _jsx(PhiIcon, { name: "holder", size: "inherit" }), type: "text", size: size, disabled: disabled, ...attributes, ...listeners, 
         /*
          * A click is the end of a drag that never started, and the handle sits on a node that selects on a
          * press; neither the click nor its default belongs to anything else.

package/components/controls/phi-drawer-control-adapter.js

@@ -71,5 +71,5 @@ export function PhiDrawerControlAdapter({ open, title, header, body, footer, clo
                 background: "transparent",
             },
             footer: { flex: "0 0 auto", padding: 0, background: "transparent" },
-        }, onClose: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, drawerRender: (node) => (_jsx("div", { style: { display: "flex", flexDirection: "column", blockSize: "100%", minBlockSize: 0 }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: body }));
+        }, onClose: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, drawerRender: (node) => (_jsx("div", { style: { display: "flex", flexDirection: "column", blockSize: "100%", minBlockSize: 0 }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: _jsx("div", { "data-phi-drawer-body-content": "true", style: { display: "contents" }, children: body }) }));
 }

package/components/controls/phi-drawer-control.d.ts

@@ -1,11 +1,11 @@
-import type { PhiCmsOverlayConfig, PhiCmsOverlaySize } from "../../types/cms-overlay";
+import type { PhiCmsOverlayConfig, PhiCmsOverlaySize, PhiOverlayPushBehaviour } from "../../types/cms-overlay";
 import type { PhiOverlayControlCommonProps } from "./phi-overlay-control-contract";
 export type PhiDrawerControlProps = PhiOverlayControlCommonProps & {
     placement?: PhiCmsOverlayConfig["placement"];
     size?: PhiCmsOverlaySize;
     maxSize?: number;
-    resizable?: PhiCmsOverlayConfig["resizable"];
-    push?: PhiCmsOverlayConfig["push"];
+    resizable?: boolean;
+    push?: PhiOverlayPushBehaviour;
     zIndex?: number;
 };
 /**

package/components/controls/phi-expand-indicator.js

@@ -1,16 +1,17 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { RightOutlined } from "@ant-design/icons";
 import { usePhiConfig } from "../root/phi-config-provider";
+import { PhiIcon } from "../shell/phi-icon";
 export function PhiExpandIndicator({ expanded, animationFromExpanded, onAnimationEnd, }) {
     const { token } = usePhiConfig();
     const animated = animationFromExpanded !== undefined;
-    return (_jsx(RightOutlined, { className: animated ? "phi-expand-indicator--animated" : undefined, style: {
+    return (_jsx("span", { className: animated ? "phi-expand-indicator--animated" : undefined, style: {
             "--phi-expand-indicator-from": animationFromExpanded ? "90deg" : "0deg",
             "--phi-expand-indicator-to": expanded ? "90deg" : "0deg",
             "--phi-expand-indicator-duration": token.motionDurationMid,
             "--phi-expand-indicator-easing": token.motionEaseInOut,
+            display: "inline-flex",
             transform: expanded ? "rotate(90deg)" : "rotate(0deg)",
             transition: `transform ${token.motionDurationMid} ${token.motionEaseInOut}`,
-        }, onAnimationEnd: onAnimationEnd }));
+        }, onAnimationEnd: onAnimationEnd, children: _jsx(PhiIcon, { name: "right", size: "inherit" }) }));
 }

package/components/controls/phi-float-button-control.d.ts

@@ -0,0 +1,39 @@
+import type { PhiToolbarControlItem } from "./phi-toolbar-control";
+export type PhiFloatButtonControlPlacement = "bottom-end" | "bottom-start" | "top-end" | "top-start";
+export type PhiFloatButtonControlGroup = {
+    /** How the group opens. Left out, it is always open: every button stands in the corner. */
+    trigger?: "click" | "hover";
+    /** The Phi icon of the button that opens it. */
+    icon?: string;
+    /** Which way the buttons unfold from that button; left out, away from the edge it sits at. */
+    direction?: "top" | "bottom" | "left" | "right";
+};
+export type PhiFloatButtonControlProps = {
+    /** The Toolbar's buttons, as the Toolbar takes them. One is a Float Button, more are its group. */
+    items: readonly PhiToolbarControlItem[];
+    placement?: PhiFloatButtonControlPlacement;
+    /** The distance from the corner, as CSS lengths. Left out, Ant Design's own corner distance. */
+    offset?: {
+        block?: string;
+        inline?: string;
+    };
+    shape?: "circle" | "square";
+    group?: PhiFloatButtonControlGroup;
+    /**
+     * Drawn where it stands rather than fixed to the viewport -- in the Builder's canvas, where a button
+     * floating over the editor could neither be seen in its slot nor selected there.
+     */
+    inPlace?: boolean;
+    disabled?: boolean;
+    onActivate?: (key: string) => void;
+};
+/**
+ * A button that stays in a corner of the viewport while the Page scrolls under it -- one, or a group.
+ *
+ * It takes the Toolbar's items so that the Widgets around both share one button: its icon, its badge,
+ * whether it is read-only or hidden. A label shows on a square button only; a round one is its icon,
+ * and the label becomes its tooltip and accessible name. Two things a Toolbar button has do not exist
+ * on a Float Button and are not imitated: `danger`, and `loading`, which disables the button instead of
+ * spinning.
+ */
+export declare function PhiFloatButtonControl({ items, placement, offset, shape, group, inPlace, disabled, onActivate, }: PhiFloatButtonControlProps): import("react").JSX.Element | null;

package/components/controls/phi-float-button-control.js

@@ -0,0 +1,73 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { FloatButton } from "antd";
+import { PhiIcon } from "../shell/phi-icon";
+const subscribeNever = () => () => { };
+/**
+ * Where a fixed button is drawn: on `document.body`, outside every box of the page.
+ *
+ * Fixed positioning places the button against the viewport, but the order it paints in is still its
+ * ancestors'. A slot child and a Region shell each open a stacking context of their own, so a button
+ * left inside its slot was painted under the Footer while the page scrolled and under the Header in the
+ * top corners -- its z-index counted only among its slot's siblings. On the body it stacks with the
+ * page's other overlays, as an Ant Design Modal does. The server draws nothing for it: there is no body
+ * to portal into, and a fixed button needs none of the page's flow.
+ */
+function PhiFloatButtonPortal({ children }) {
+    const mounted = useSyncExternalStore(subscribeNever, () => true, () => false);
+    return mounted ? createPortal(children, document.body) : null;
+}
+/* Ant Design's own corner distance (`floatButtonInsetInlineEnd`, `floatButtonInsetBlockEnd`). */
+const PHI_FLOAT_BUTTON_DEFAULT_INLINE = "24px";
+const PHI_FLOAT_BUTTON_DEFAULT_BLOCK = "48px";
+function resolveCornerStyle(placement, offset, inPlace) {
+    if (inPlace) {
+        return { position: "relative", inset: "auto" };
+    }
+    const block = offset?.block ?? PHI_FLOAT_BUTTON_DEFAULT_BLOCK;
+    const inline = offset?.inline ?? PHI_FLOAT_BUTTON_DEFAULT_INLINE;
+    const top = placement.startsWith("top");
+    const start = placement.endsWith("start");
+    /* Ant Design states `bottom` and `insetInlineEnd`; the two it does not state are cleared with them. */
+    return {
+        top: top ? block : "auto",
+        bottom: top ? "auto" : block,
+        insetInlineStart: start ? inline : "auto",
+        insetInlineEnd: start ? "auto" : inline,
+    };
+}
+/**
+ * A button that stays in a corner of the viewport while the Page scrolls under it -- one, or a group.
+ *
+ * It takes the Toolbar's items so that the Widgets around both share one button: its icon, its badge,
+ * whether it is read-only or hidden. A label shows on a square button only; a round one is its icon,
+ * and the label becomes its tooltip and accessible name. Two things a Toolbar button has do not exist
+ * on a Float Button and are not imitated: `danger`, and `loading`, which disables the button instead of
+ * spinning.
+ */
+export function PhiFloatButtonControl({ items, placement = "bottom-end", offset, shape = "circle", group, inPlace = false, disabled, onActivate, }) {
+    const visibleItems = items.filter((item) => item.visible !== false);
+    if (visibleItems.length === 0) {
+        return null;
+    }
+    const cornerStyle = resolveCornerStyle(placement, offset, inPlace);
+    const buttons = visibleItems.map((item, index) => {
+        const labelShown = shape === "square" && (item.showLabel ?? !item.icon);
+        const inert = disabled || item.disabled || item.loading === true;
+        return (_jsx(FloatButton, { "aria-label": item.ariaLabel ?? (typeof item.label === "string" ? item.label : undefined), icon: item.icon ?? undefined, content: labelShown ? item.label : undefined, tooltip: item.tooltip ?? (labelShown ? undefined : item.label), type: item.type === "primary" ? "primary" : "default", shape: shape, disabled: inert, badge: item.badge?.enabled
+                ? {
+                    count: item.badge.value ?? 0,
+                    color: item.badge.color,
+                    overflowCount: item.badge.overflowCount,
+                    showZero: item.badge.showZero,
+                }
+                : undefined, 
+            /* A single button carries the corner itself; inside a group, the group does. */
+            style: visibleItems.length === 1 && index === 0 ? cornerStyle : undefined, onClick: item.readOnly || !onActivate ? undefined : () => onActivate(item.key) }, item.key));
+    });
+    const placed = buttons.length === 1 ? buttons[0] : (_jsx(FloatButton.Group, { trigger: group?.trigger, icon: group?.icon ? _jsx(PhiIcon, { name: group.icon, size: "inherit" }) : undefined, placement: group?.direction ?? (placement.startsWith("top") ? "bottom" : "top"), shape: shape, style: cornerStyle, children: buttons }));
+    /* In place it stays in its slot, where the Builder's canvas can show and select it. */
+    return inPlace ? placed : _jsx(PhiFloatButtonPortal, { children: placed });
+}

package/components/controls/phi-form-control-contract.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "antd/es/form";
+/**
+ * One validation rule as PhiFormControl applies it to a field.
+ *
+ * A validation provider builds these from a rule descriptor, and the form draws them through its
+ * primitive. Named here so the registry that holds the providers types against the Control rather than
+ * against the primitive's form library.
+ */
+export type PhiFormControlRule = Rule;

package/components/controls/phi-form-control.js

@@ -1,9 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Fragment, forwardRef, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from "react";
+import { Fragment, forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from "react";
 import { Form, theme as antdTheme, } from "antd";
 import { PHI_FORM_GRID_TRACKS } from "../../types/form-descriptor";
-import { evaluatePhiRuntimeConditionExpression } from "../../types/runtime-condition";
+import { collectPhiRuntimeValueConditions, evaluatePhiRuntimeConditionExpression, } from "../../types/runtime-condition";
 import { extendPhiFormProviderRegistry, usePhiFormProviderRegistry, } from "../forms/form-provider-registry";
 import { PhiAlertControl } from "./phi-alert-control";
 import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
@@ -40,6 +40,38 @@ function resolveHoneypotStyle(presentation) {
         overflow: "hidden",
     };
 }
+/**
+ * The form fields whose values the descriptor reads: everything a `visibleWhen` or `disabledWhen` asks
+ * of the form, and every options dependency that points into it. Top-level keys, because that is what
+ * a form store is keyed by and what a watch can be narrowed to.
+ */
+function collectPhiFormWatchedKeys(fields) {
+    const keys = new Set();
+    for (const field of fields) {
+        for (const expression of [field.visibleWhen, field.disabledWhen]) {
+            if (!expression)
+                continue;
+            for (const condition of collectPhiRuntimeValueConditions(expression)) {
+                if (condition.source === "form")
+                    keys.add(condition.valuePath.split(".")[0] ?? "");
+            }
+        }
+        for (const dependency of field.optionsProvider?.dependencies ?? []) {
+            if (dependency.source === "form")
+                keys.add(dependency.valuePath.split(".")[0] ?? "");
+        }
+    }
+    keys.delete("");
+    return [...keys].sort();
+}
+function pickPhiFormWatchedValues(values, keys) {
+    const picked = {};
+    for (const key of keys) {
+        if (values && key in values)
+            picked[key] = values[key];
+    }
+    return picked;
+}
 function PhiResolvedFormFieldControl({ id, provider, field, label, description, labels, formConfig, placeholder, disabled, readOnly, value, checked, onChange, formContext, formValues, }) {
     const staticOptions = useMemo(() => field.options?.map((option) => ({
         ...option,
@@ -197,7 +229,18 @@ export const PhiFormControl = forwardRef(function PhiFormControl({ descriptor, r
             .map((field) => [field.key, resolvedInitialValues[field.key]]));
         form.setFieldsValue(fieldValues);
     }, [descriptor.fields, form, initialValuesKey, resolvedInitialValues]);
+    /*
+     * Fields whose value is not complete yet, and what each says about it (`formContext.holdSubmit`).
+     * A ref and not state: it is read at the moment of a submit, and holding one must not render the form.
+     */
+    const submitHoldsRef = useRef(new Map());
     async function submit(values) {
+        const holds = [...submitHoldsRef.current];
+        if (holds.length > 0) {
+            form.setFields(holds.map(([name, reason]) => ({ name, errors: [reason] })));
+            onValidationFailed?.({ valid: false, errors: Object.fromEntries(holds.map(([name, reason]) => [name, [reason]])) });
+            return;
+        }
         setSubmitting(true);
         onSubmittingChange?.(true);
         try {
@@ -226,9 +269,31 @@ export const PhiFormControl = forwardRef(function PhiFormControl({ descriptor, r
          */
         onValidationFailed?.({ valid: false, errors });
     };
-    const formValues = Form.useWatch((values) => values, { form, preserve: true }) ?? resolvedInitialValues;
+    /*
+     * Only what the descriptor reads is watched. `useWatch` re-renders this whole form -- and with it every
+     * field, its rules and its options resolution -- whenever the selected value changes, compared as JSON.
+     * Watching every value made each keystroke in any field a render of all of them; watching the handful
+     * of keys that conditions and options dependencies name makes it a render only when one of those moves.
+     */
+    const watchedFormKeys = useMemo(() => collectPhiFormWatchedKeys(descriptor.fields), [descriptor.fields]);
+    const selectWatchedFormValues = useCallback((values) => pickPhiFormWatchedValues(values, watchedFormKeys), [watchedFormKeys]);
+    const watchedFormValues = Form.useWatch(selectWatchedFormValues, { form, preserve: true });
+    const formValues = useMemo(() => watchedFormValues ?? pickPhiFormWatchedValues(resolvedInitialValues, watchedFormKeys), [resolvedInitialValues, watchedFormKeys, watchedFormValues]);
     const fieldFormContext = useMemo(() => ({
         getValues: () => form.getFieldsValue(true),
+        holdSubmit: (fieldKey, reason) => {
+            const holds = submitHoldsRef.current;
+            const held = holds.get(fieldKey);
+            if (reason == null) {
+                holds.delete(fieldKey);
+                // The sentence a refused submit left on the field goes with the hold; any other error stays.
+                if (held != null && form.getFieldError(fieldKey).includes(held)) {
+                    form.setFields([{ name: fieldKey, errors: [] }]);
+                }
+                return;
+            }
+            holds.set(fieldKey, reason);
+        },
         setValues: (values) => {
             form.setFields(Object.entries(values).map(([name, value]) => ({ name, value, touched: true })));
             onValuesChange?.(values, form.getFieldsValue(true));

package/components/controls/phi-icon-picker-control.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef, useState } from "react";
-import { AppstoreOutlined } from "@ant-design/icons";
+import { stopPhiOverlayEvent } from "../../helpers/overlay-events";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { Flex, Typography } from "antd";
 import { PhiIcon } from "../shell/phi-icon";
 import { usePhiConfig } from "../root/phi-config-provider";
@@ -96,12 +96,6 @@ const ICON_BUTTON_GRID_STYLE = {
     gap: 4,
     width: "100%",
 };
-function stopOverlayEvent(event) {
-    event.stopPropagation();
-}
-function stopOverlayMouseEvent(event) {
-    event.stopPropagation();
-}
 function parseIconValue(value) {
     if (typeof value === "string" && value.startsWith("iconify:")) {
         const [, setKey, ...rest] = value.split(":");
@@ -134,7 +128,7 @@ export function PhiIconPickerControl({ value, onChange, buttonAriaLabel, buttonI
     const open = picker.open;
     const resolvedButtonIcon = buttonIcon ?? (picker.value?.trim()
         ? _jsx(PhiIcon, { name: picker.value, size: "1em" })
-        : _jsx(AppstoreOutlined, {}));
+        : _jsx(PhiIcon, { name: "appstore", size: "inherit" }));
     const [mode, setMode] = useState(parsedCurrentIcon.mode);
     const [iconifySet, setIconifySet] = useState(parsedCurrentIcon.setKey);
     const [iconifyQuery, setIconifyQuery] = useState(parsedCurrentIcon.query);
@@ -145,6 +139,17 @@ export function PhiIconPickerControl({ value, onChange, buttonAriaLabel, buttonI
     const [iconifySearchStart, setIconifySearchStart] = useState(0);
     const iconifySearchRequestKeyRef = useRef(null);
     const iconifySearchTimeoutRef = useRef(null);
+    /*
+     * Leaving takes the search along: a pending debounce would otherwise still fire, and an answer still
+     * on its way would set state on a picker that is gone.
+     */
+    useEffect(() => () => {
+        iconifySearchRequestKeyRef.current = null;
+        if (iconifySearchTimeoutRef.current != null) {
+            window.clearTimeout(iconifySearchTimeoutRef.current);
+            iconifySearchTimeoutRef.current = null;
+        }
+    }, []);
     const resetIconifySearchState = () => {
         iconifySearchRequestKeyRef.current = null;
         if (iconifySearchTimeoutRef.current != null) {
@@ -255,7 +260,7 @@ export function PhiIconPickerControl({ value, onChange, buttonAriaLabel, buttonI
         scheduleInitialIconifySearch(nextParsedIcon.setKey, nextParsedIcon.query);
         picker.openPicker();
     };
-    const triggerButton = (_jsx("span", { onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, onClick: stopOverlayEvent, style: { display: "inline-flex", width: buttonBlock ? "100%" : undefined }, children: _jsx(PhiButtonControl, { type: buttonType, size: buttonSize, block: buttonBlock, disabled: disabled, ariaLabel: buttonAriaLabel ?? labels.buttonAriaLabel, icon: resolvedButtonIcon, label: buttonLabel, onClick: () => {
+    const triggerButton = (_jsx("span", { onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, onClick: stopPhiOverlayEvent, style: { display: "inline-flex", width: buttonBlock ? "100%" : undefined }, children: _jsx(PhiButtonControl, { type: buttonType, size: buttonSize, block: buttonBlock, disabled: disabled, ariaLabel: buttonAriaLabel ?? labels.buttonAriaLabel, icon: resolvedButtonIcon, label: buttonLabel, onClick: () => {
                 if (!open)
                     openPicker();
             }, style: buttonStyle }) }));
@@ -271,7 +276,7 @@ export function PhiIconPickerControl({ value, onChange, buttonAriaLabel, buttonI
                 resetIconifySearchState();
             }
             picker.handleOpenChange(nextOpen);
-        }, getPopupContainer: getPopupContainer, rootClassName: rootClassName, zIndex: PHI_Z_INDEX.authoringPopup, content: (_jsxs(Flex, { vertical: true, gap: token.paddingXS, onClick: stopOverlayEvent, onMouseDown: stopOverlayMouseEvent, onPointerDown: stopOverlayEvent, style: { width: 280 }, children: [_jsx(PhiSegmentedControl, { block: true, size: "small", value: mode, disabled: disabled, onChange: (nextMode) => {
+        }, getPopupContainer: getPopupContainer, rootClassName: rootClassName, zIndex: PHI_Z_INDEX.authoringPopup, content: (_jsxs(Flex, { vertical: true, gap: token.paddingXS, onClick: stopPhiOverlayEvent, onMouseDown: stopPhiOverlayEvent, onPointerDown: stopPhiOverlayEvent, style: { width: 280 }, children: [_jsx(PhiSegmentedControl, { block: true, size: "small", value: mode, disabled: disabled, onChange: (nextMode) => {
                         setMode(nextMode);
                         if (nextMode === "iconify" && open) {
                             scheduleInitialIconifySearch(iconifySet, iconifyQuery);
@@ -317,7 +322,7 @@ export function PhiIconPickerControl({ value, onChange, buttonAriaLabel, buttonI
                                         const entryValue = `iconify:${iconName}`;
                                         const shortName = iconName.split(":").pop() ?? iconName;
                                         return (_jsx(PhiButtonControl, { type: picker.value === entryValue ? "primary" : "default", size: "small", disabled: disabled, ariaLabel: shortName, tooltip: entryValue, icon: _jsx(PhiIcon, { name: entryValue, size: 16 }), onClick: () => applyIcon(entryValue), style: { width: "100%", height: 36, padding: 0 } }, entryValue));
-                                    }) })) : iconifySearchLoading ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 24 }, children: _jsx(Typography.Text, { type: "secondary", children: labels.status.loading }) })) : iconifySearchError ? (_jsx(PhiAlertControl, { level: "error", showIcon: true, title: iconifySearchError })) : (_jsx(PhiEmptyControl, { description: labels.empty.search })), iconifySearchLoading && iconifySearchResults.length > 0 ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 12 }, children: _jsx(Typography.Text, { type: "secondary", style: { fontSize: 12 }, children: labels.status.loadingMore }) })) : null, !iconifySearchLoading && iconifySearchHasMore ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 12 }, children: _jsx(Typography.Text, { type: "secondary", style: { fontSize: 12 }, children: labels.status.scrollMore }) })) : null] }))] })), _jsxs(Flex, { align: "center", justify: "space-between", gap: 8, children: [_jsx(Typography.Text, { type: "secondary", style: { fontSize: 12 }, children: picker.value ?? labels.hints.noneSelected }), _jsx(PhiButtonControl, { size: "small", disabled: disabled, label: labels.actions.clear, onClick: () => {
+                                    }) })) : iconifySearchLoading ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 24 }, children: _jsx(Typography.Text, { type: "secondary", children: labels.status.loading }) })) : iconifySearchError ? (_jsx(PhiAlertControl, { level: "error", showIcon: true, title: iconifySearchError })) : (_jsx(PhiEmptyControl, { description: labels.empty.search })), iconifySearchLoading && iconifySearchResults.length > 0 ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 12 }, children: _jsx(Typography.Text, { type: "secondary", children: labels.status.loadingMore }) })) : null, !iconifySearchLoading && iconifySearchHasMore ? (_jsx(Flex, { justify: "center", style: { paddingBlock: 12 }, children: _jsx(Typography.Text, { type: "secondary", children: labels.status.scrollMore }) })) : null] }))] })), _jsxs(Flex, { align: "center", justify: "space-between", gap: 8, children: [_jsx(Typography.Text, { type: "secondary", children: picker.value ?? labels.hints.noneSelected }), _jsx(PhiButtonControl, { size: "small", disabled: disabled, label: labels.actions.clear, onClick: () => {
                                 setIconifyQuery("");
                                 resetIconifySearchState();
                                 applyIcon(null, { close: false });

package/components/controls/phi-image-control.d.ts

@@ -0,0 +1,52 @@
+import { type CSSProperties } from "react";
+import type { PhiImagePresentation } from "../media/image-presentation";
+/**
+ * Where a picture comes from, which decides what may be done with it.
+ *
+ * - `asset` -- the Site's own Media: `next/image` draws it, and its blur stands in while it loads.
+ * - `trusted-url` -- a foreign address a Preset vouched for: `next/image` may draw it, but it has no blur
+ *   of its own, so a plain placeholder stands in.
+ * - `url` -- any other address: a plain `<img>`, with the same plain placeholder.
+ */
+export type PhiImageControlSource = "asset" | "trusted-url" | "url";
+export type PhiImageControlProps = {
+    /** The shared resolver's answer (`resolvePhiImagePresentation`): address, framing, intrinsic size. */
+    presentation: PhiImagePresentation;
+    source: PhiImageControlSource;
+    alt: string;
+    title?: string;
+    /** The box the picture is drawn at, where it is not the presentation's own size. */
+    width?: number | string | null;
+    height?: number | string | null;
+    /** The Asset's blur. Only an `asset` has one; an address on somebody else's server never does. */
+    blurDataUrl?: string | null;
+    /** Whether the optimiser may take the bytes -- a public Asset, and not an SVG original. */
+    optimizable?: boolean;
+    sizes?: string;
+    preload?: boolean;
+    /**
+     * Whether the browser may wait with the bytes. Absent, it decides by distance to the viewport, which
+     * is right for a picture in flow and wrong on a track, where the next picture is off to the side and
+     * would load as it arrives; a Gallery says `eager` for what its window is about to show.
+     */
+    loading?: "eager" | "lazy";
+    /** Opens the picture larger over the page when clicked. */
+    preview?: boolean;
+    /** The box around the picture: size, corners, mask. */
+    style?: CSSProperties;
+    /** Added to the picture's own style after the framing. */
+    imageStyle?: CSSProperties;
+};
+/**
+ * One picture, drawn the way the house draws pictures.
+ *
+ * The framing is not decided here: `presentation` already says which bytes, how they meet the box and
+ * where the focal point sits, so every surface that shows a picture -- the Image Widget, a card's cover
+ * -- frames it alike. This decides only how it arrives: `next/image` where the source allows it, the
+ * Asset's blur while an Asset loads, and a plain placeholder for everything else, because a foreign
+ * picture has no blur and inventing one would mean fetching it twice. The placeholder goes once the
+ * picture has loaded, so a transparent picture does not keep a grey ground behind it.
+ *
+ * `preview` hands the picture to `PhiLightboxImageControl`, the one place the lightbox lives.
+ */
+export declare function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable, sizes, preload, loading, preview, style, imageStyle, }: PhiImageControlProps): import("react").JSX.Element | null;

package/components/controls/phi-image-control.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import NextImage from "next/image";
+import { useState } from "react";
+import { PhiLightboxImageControl } from "./phi-lightbox-image-control";
+function toCssSize(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return `${value}px`;
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    return undefined;
+}
+/**
+ * One picture, drawn the way the house draws pictures.
+ *
+ * The framing is not decided here: `presentation` already says which bytes, how they meet the box and
+ * where the focal point sits, so every surface that shows a picture -- the Image Widget, a card's cover
+ * -- frames it alike. This decides only how it arrives: `next/image` where the source allows it, the
+ * Asset's blur while an Asset loads, and a plain placeholder for everything else, because a foreign
+ * picture has no blur and inventing one would mean fetching it twice. The placeholder goes once the
+ * picture has loaded, so a transparent picture does not keep a grey ground behind it.
+ *
+ * `preview` hands the picture to `PhiLightboxImageControl`, the one place the lightbox lives.
+ */
+export function PhiImageControl({ presentation, source, alt, title, width, height, blurDataUrl, optimizable = false, sizes, preload = false, loading, preview = false, style, imageStyle, }) {
+    const [loadedUrl, setLoadedUrl] = useState(null);
+    const url = presentation.url;
+    if (!url) {
+        return null;
+    }
+    const drawnWidth = width ?? presentation.width;
+    const drawnHeight = height ?? presentation.height;
+    const blur = source === "asset" ? blurDataUrl ?? null : null;
+    const loaded = loadedUrl === url;
+    const boxStyle = {
+        position: presentation.simulatedCropStyle ? "relative" : undefined,
+        width: toCssSize(drawnWidth) ?? "100%",
+        height: toCssSize(drawnHeight),
+        maxWidth: "100%",
+        lineHeight: 0,
+        overflow: presentation.simulatedCropStyle ? "hidden" : undefined,
+        ...(loaded || blur ? {} : { backgroundColor: "var(--ant-color-fill-quaternary)" }),
+        ...style,
+    };
+    const pictureStyle = {
+        objectFit: presentation.fit,
+        objectPosition: presentation.objectPosition,
+        display: "block",
+        width: "100%",
+        height: toCssSize(drawnHeight) ? "100%" : "auto",
+        ...presentation.simulatedCropStyle,
+        ...imageStyle,
+    };
+    const numericWidth = typeof drawnWidth === "number" ? drawnWidth : undefined;
+    const numericHeight = typeof drawnHeight === "number" ? drawnHeight : undefined;
+    const markLoaded = () => setLoadedUrl(url);
+    // A picture the browser had before hydration has loaded already and fires no `load` any more.
+    const noticeLoaded = (node) => {
+        if (node?.complete && node.naturalWidth > 0 && !loaded)
+            markLoaded();
+    };
+    if (preview) {
+        return (_jsx("div", { style: boxStyle, children: _jsx(PhiLightboxImageControl, { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, style: pictureStyle }) }));
+    }
+    if (source !== "url" && numericWidth != null && numericHeight != null) {
+        return (_jsx("div", { style: boxStyle, children: _jsx(NextImage, { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, sizes: sizes?.trim() || undefined, unoptimized: !optimizable, placeholder: blur ? "blur" : undefined, blurDataURL: blur ?? undefined, preload: preload, loading: loading, onLoad: markLoaded, style: pictureStyle }) }));
+    }
+    return (_jsx("div", { style: boxStyle, children: _jsx("img", { alt: alt, src: url, title: title, width: numericWidth, height: numericHeight, loading: loading ?? (preload ? "eager" : "lazy"), ref: noticeLoaded, onLoad: markLoaded, style: pictureStyle }) }));
+}

package/components/controls/phi-inline-text-editor.d.ts

@@ -30,6 +30,11 @@ export type PhiInlineTextEditorProps = {
      * less on an `i`, so a counted width cuts the tail off the very text it was counted from.
      */
     fitContent?: boolean;
+    /**
+     * An × at the end that empties the text. Emptied is written at once: the × can be pressed without the
+     * field having the focus, and then no blur would ever come to write it.
+     */
+    allowClear?: boolean;
 };
 /**
  * Text edited where it is read, inside a surface that is itself selectable.
@@ -40,4 +45,4 @@ export type PhiInlineTextEditorProps = {
  * The props are a closed list rather than whatever an input accepts, which is what lets the field be
  * the shared text Control.
  */
-export declare function PhiInlineTextEditor({ value, onChange, onCommit, onCancel, onFocus, onBlur, ariaLabel, placeholder, autoFocus, readOnly, variant, size, style, inputStyle, collapsibleTitleControl, fitContent, }: PhiInlineTextEditorProps): import("react").JSX.Element;
+export declare function PhiInlineTextEditor({ value, onChange, onCommit, onCancel, onFocus, onBlur, ariaLabel, placeholder, autoFocus, readOnly, variant, size, style, inputStyle, collapsibleTitleControl, fitContent, allowClear, }: PhiInlineTextEditorProps): import("react").JSX.Element;