@phis/ui 0.2.1 → 0.4.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.d.ts

@@ -1,2 +1,2 @@
 import type { PhiDrawerControlProps } from "./phi-drawer-control";
-export declare function PhiDrawerControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, placement, size, maxSize, resizable, push, zIndex, containerStyle, onDismiss, afterOpenChange, }: PhiDrawerControlProps): import("react").JSX.Element;
+export declare function PhiDrawerControlAdapter({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, placement, size, maxSize, resizable, push, zIndex, containerStyle, onDismiss, afterOpenChange, panelRef, }: PhiDrawerControlProps): import("react").JSX.Element;

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

@@ -12,7 +12,7 @@ const subscribeHydration = () => () => undefined;
 const PHI_DRAWER_HEADER_MIN_BLOCK_SIZE = `calc(var(--ant-control-height) + ${PHI_SPACE.xs} + ${PHI_SPACE.xs})`;
 /** Where a title starts when the close button stands before it: past the button, not beneath it. */
 const PHI_DRAWER_TITLE_AFTER_CLOSE = `calc(${PHI_SPACE.sm} + var(--ant-control-height) + ${PHI_SPACE.xs})`;
-export function PhiDrawerControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", placement = "right", size, maxSize, resizable = false, push = false, zIndex, containerStyle, onDismiss, afterOpenChange, }) {
+export function PhiDrawerControlAdapter({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", placement = "right", size, maxSize, resizable = false, push = false, zIndex, containerStyle, onDismiss, afterOpenChange, panelRef, }) {
     const hydrated = useSyncExternalStore(subscribeHydration, () => true, () => false);
     const resolvedMask = resolvePhiOverlayMaskPresentation(mask);
     const closeAtInlineStart = placement === "right";
@@ -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", { ref: panelRef, 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,57 @@
+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;
+    /**
+     * Scales the picture to the viewport over the page when clicked, with nothing around it; another click
+     * closes it. The plain counterpart of `preview`, which brings the lightbox's tools.
+     */
+    zoom?: 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, zoom, style, imageStyle, }: PhiImageControlProps): import("react").JSX.Element | null;