@phis/ui 0.1.0

package/components/controls/phi-media-asset-tile-control.js

@@ -0,0 +1,155 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DeleteOutlined } from "@ant-design/icons";
+import { Flex, Skeleton, Typography } from "antd";
+import NextImage from "next/image";
+import { PhiMediaKind, isPhiMediaAssetOriginalOptimizable, isPhiMediaAssetPublic } from "../../constants/media";
+import { resolvePhiMediaAssetDisplayDimensions } from "../media/phi-image-preview-data";
+import { PhiMediaKindIcon } from "../media/phi-media-kind-icon";
+import { PhiMediaRestrictedIcon } from "../media/phi-media-restricted-icon";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { PhiButtonControl } from "./phi-button-control";
+import { PhiCollectionLayoutControl, } from "./phi-collection-layout-control";
+function resolveAssetTypeLabel(kind, contentType, originalName) {
+    const normalizedContentType = contentType.trim().toLowerCase();
+    if (kind === PhiMediaKind.Image) {
+        const subtype = normalizedContentType.startsWith("image/")
+            ? normalizedContentType.split("/", 2)[1]
+            : null;
+        if (subtype) {
+            return subtype.split(";")[0].trim();
+        }
+        return normalizedContentType || "image";
+    }
+    const extension = originalName.trim().split(".").pop()?.trim().toLowerCase();
+    if (extension && extension !== originalName.trim().toLowerCase()) {
+        return extension;
+    }
+    const [, subtype] = normalizedContentType.split("/", 2);
+    if (subtype) {
+        return subtype.split(";")[0].trim();
+    }
+    return kind;
+}
+export function PhiMediaAssetTileControl({ asset, minColumnWidth, selected = false, mode = "grid", size = "medium", disabled = false, onSelect, onDelete, deleteLabel, showTypeLabel = true, showDeleteAction = false, showDimensions = true, showIdLabel = false, }) {
+    const { token } = usePhiConfig();
+    const compact = size === "small";
+    const assetTileIconSize = compact ? 20 : 24;
+    const assetTileLabelFontSize = compact ? token.fontSizeSM : token.fontSize;
+    const isSelectable = Boolean(onSelect) && !disabled;
+    const isPublic = isPhiMediaAssetPublic(asset.deliveryPolicy, asset.lifecycleStatus);
+    const isRestricted = !isPublic;
+    const displayDimensions = resolvePhiMediaAssetDisplayDimensions(asset);
+    const imageUrl = asset.thumbnailUrl ?? asset.previewUrl ?? asset.deliveryUrl;
+    // The thumbnail and the preview are raster variants; only the original can be an SVG the optimiser refuses.
+    const optimizable = imageUrl === asset.deliveryUrl ? isPhiMediaAssetOriginalOptimizable(asset) : isPublic;
+    const cardStyle = {
+        border: `1px solid ${selected ? token.colorPrimary : token.colorBorderSecondary}`,
+        borderRadius: token.borderRadiusLG,
+        overflow: "hidden",
+        padding: 0,
+        cursor: isSelectable ? "pointer" : "default",
+        background: selected ? token.colorFillQuaternary : token.colorBgContainer,
+        boxShadow: selected ? token.boxShadowTertiary : "none",
+        opacity: disabled ? 0.65 : undefined,
+        textAlign: "left",
+        width: "100%",
+        height: mode === "stack" ? "100%" : undefined,
+        position: "relative",
+        isolation: "isolate",
+    };
+    return (_jsxs("div", { role: isSelectable ? "button" : undefined, "aria-pressed": isSelectable ? selected : undefined, "aria-disabled": disabled || undefined, tabIndex: isSelectable ? 0 : undefined, style: cardStyle, onClick: isSelectable ? () => onSelect?.(asset) : undefined, onKeyDown: isSelectable
+            ? (event) => {
+                if (event.key !== "Enter" && event.key !== " ") {
+                    return;
+                }
+                event.preventDefault();
+                onSelect?.(asset);
+            }
+            : undefined, children: [_jsxs("div", { style: {
+                    position: "relative",
+                    width: "100%",
+                    aspectRatio: "1 / 1",
+                    background: token.colorFillTertiary,
+                    overflow: "hidden",
+                }, children: [asset.kind === PhiMediaKind.Image ? (_jsx(NextImage, { alt: asset.altText ?? asset.title ?? asset.originalName, src: imageUrl, fill: true, unoptimized: !optimizable, sizes: typeof minColumnWidth === "number" ? `${minColumnWidth}px` : minColumnWidth, placeholder: asset.blurDataUrl ? "blur" : "empty", blurDataURL: asset.blurDataUrl ?? undefined, style: { objectFit: "cover" } })) : isRestricted ? (_jsx(Flex, { align: "center", justify: "center", style: { width: "100%", height: "100%" }, children: _jsx(PhiMediaRestrictedIcon, { size: assetTileIconSize, title: "restricted" }) })) : (_jsx(Flex, { align: "center", justify: "center", style: { width: "100%", height: "100%" }, children: _jsx(PhiMediaKindIcon, { kind: asset.kind, size: assetTileIconSize }) })), showDimensions && asset.kind === PhiMediaKind.Image && displayDimensions ? (_jsxs(Typography.Text, { style: {
+                            position: "absolute",
+                            left: "0.375rem",
+                            top: "0.375rem",
+                            color: "#fff",
+                            fontSize: assetTileLabelFontSize,
+                            lineHeight: 1,
+                            textShadow: "0 1px 2px rgba(0, 0, 0, 0.95), 0 0 4px rgba(0, 0, 0, 0.85)",
+                            pointerEvents: "none",
+                        }, children: [displayDimensions.width, "x", displayDimensions.height] })) : null, showIdLabel && asset.id != null ? (_jsxs(Typography.Text, { style: {
+                            position: "absolute",
+                            top: "0.375rem",
+                            right: "0.375rem",
+                            color: "#fff",
+                            fontSize: assetTileLabelFontSize,
+                            lineHeight: 1,
+                            textShadow: "0 1px 2px rgba(0, 0, 0, 0.95), 0 0 4px rgba(0, 0, 0, 0.85)",
+                            pointerEvents: "none",
+                        }, children: ["#", asset.id] })) : null, _jsx("div", { style: {
+                            position: "absolute",
+                            zIndex: 1,
+                            right: 0,
+                            bottom: 0,
+                            left: 0,
+                            paddingBlock: token.paddingXXS,
+                            paddingInline: token.paddingXS,
+                            background: token.colorBgMask,
+                        }, children: _jsx(Typography.Text, { strong: true, ellipsis: true, title: asset.title ?? asset.originalName, style: {
+                                display: "block",
+                                color: token.colorTextLightSolid,
+                                fontSize: assetTileLabelFontSize,
+                                lineHeight: 1,
+                            }, children: asset.title ?? asset.originalName }) })] }), showTypeLabel || showDeleteAction ? (_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingXS, wrap: true, style: {
+                    minHeight: token.controlHeightSM,
+                    paddingInline: compact ? token.paddingXS : token.paddingSM,
+                    background: "rgba(255, 255, 255, 0.78)",
+                }, children: [showTypeLabel ? (_jsx(Typography.Text, { ellipsis: true, style: {
+                            display: "block",
+                            minWidth: 0,
+                            color: "rgba(0, 0, 0, 0.88)",
+                            fontSize: assetTileLabelFontSize,
+                        }, children: resolveAssetTypeLabel(asset.kind, asset.contentType, asset.originalName) })) : _jsx("span", {}), showDeleteAction && onDelete ? (_jsx("span", { onClick: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { ariaLabel: deleteLabel, icon: _jsx(DeleteOutlined, {}), type: "text", size: "small", danger: true, disabled: disabled, onClick: () => onDelete(asset) }) })) : null] })) : null] }));
+}
+export function PhiMediaAssetCollectionSkeletonControl({ mode, gap, minColumnWidth, active = true, count = 10, size = "medium", }) {
+    const { token } = usePhiConfig();
+    const compact = size === "small";
+    const items = Array.from({ length: count }, (_, index) => (_jsxs("div", { style: {
+            border: `1px solid ${token.colorBorderSecondary}`,
+            borderRadius: token.borderRadiusLG,
+            overflow: "hidden",
+            background: token.colorBgContainer,
+            width: "100%",
+            minWidth: 0,
+            position: "relative",
+            isolation: "isolate",
+        }, children: [_jsx("div", { style: {
+                    width: "100%",
+                    minWidth: 0,
+                    aspectRatio: "1 / 1",
+                }, children: _jsx(Skeleton.Input, { active: active, block: true, style: {
+                        display: "block",
+                        width: "100%",
+                        minWidth: 0,
+                        maxWidth: "100%",
+                        height: "100%",
+                        borderRadius: 0,
+                    } }) }), _jsxs(Flex, { style: {
+                    minHeight: token.controlHeightSM,
+                    paddingInline: compact ? token.paddingXS : token.paddingSM,
+                    background: "rgba(255, 255, 255, 0.78)",
+                }, align: "center", justify: "space-between", gap: token.paddingXS, children: [_jsx(Skeleton.Input, { active: active, size: "small", style: {
+                            width: "55%",
+                            minWidth: 0,
+                            height: token.fontSize * token.lineHeight,
+                        } }), _jsx(Skeleton.Button, { active: active, size: "small", shape: "circle", style: {
+                            width: token.controlHeightSM,
+                            minWidth: token.controlHeightSM,
+                            height: token.controlHeightSM,
+                        } })] })] }, index)));
+    return (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: gap, minColumnWidth: minColumnWidth, items: items }));
+}

package/components/controls/phi-media-picker-control-contract.d.ts

@@ -0,0 +1,5 @@
+export declare const PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH = 80;
+export declare const PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH = 240;
+export declare const PHI_MEDIA_PICKER_COLUMN_WIDTH_STEP = 8;
+export declare const PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH = 96;
+export declare function normalizePhiMediaPickerMinColumnWidth(value: unknown): number;

package/components/controls/phi-media-picker-control-contract.js

@@ -0,0 +1,10 @@
+export const PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH = 80;
+export const PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH = 240;
+export const PHI_MEDIA_PICKER_COLUMN_WIDTH_STEP = 8;
+export const PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH = 96;
+export function normalizePhiMediaPickerMinColumnWidth(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH;
+    }
+    return Math.min(PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH, Math.max(PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH, Math.round(value)));
+}

package/components/controls/phi-media-picker-control.d.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+import type { PhiMediaAssetTile } from "../../types/media";
+import type { PhiControlOption } from "./phi-control-options";
+import type { PhiPickerPlacement, PhiPickerTransactionCallbacks } from "./phi-picker-control-contract";
+export type PhiMediaPickerControlProps = PhiPickerTransactionCallbacks<number | null> & {
+    open?: boolean;
+    value?: number | null;
+    assets: readonly PhiMediaAssetTile[];
+    /**
+     * The Spaces this viewer may work in. Empty unless the surface is one that may name a Space at all,
+     * so an authoring picker never renders the selector.
+     */
+    spaces?: readonly PhiControlOption[];
+    spaceValue?: string | null;
+    folders?: readonly PhiControlOption[];
+    folderValue?: string;
+    query?: string;
+    page?: number;
+    pageSize?: number;
+    total?: number;
+    minColumnWidth?: number;
+    loading?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    placement?: PhiPickerPlacement;
+    showSearchBar?: boolean;
+    showFolderFilter?: boolean;
+    showPagination?: boolean;
+    trigger?: ReactNode;
+    labels?: Partial<{
+        trigger: string;
+        title: string;
+        search: string;
+        folder: string;
+        space: string;
+        empty: string;
+        clear: string;
+        reload: string;
+        tileSize: string;
+    }>;
+    getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;
+    popupRootClassName?: string;
+    onQueryChange?: (query: string) => void;
+    onSpaceChange?: (space: string) => void;
+    onFolderChange?: (folder: string) => void;
+    onPageChange?: (page: number, pageSize: number) => void;
+    onMinColumnWidthChange?: (minColumnWidth: number) => void;
+    onReload?: () => void;
+};
+export declare function PhiMediaPickerControl({ open, value, assets, spaces, spaceValue, folders, folderValue, query, page, pageSize, total, minColumnWidth, loading, disabled, readOnly, placement, showSearchBar, showFolderFilter, showPagination, trigger, labels, getPopupContainer, popupRootClassName, onOpenChange, onQueryChange, onSpaceChange, onFolderChange, onPageChange, onMinColumnWidthChange, onReload, onChange, onCommit, onDiscard, }: PhiMediaPickerControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Empty, Flex, Typography } from "antd";
+import { PictureOutlined, ReloadOutlined } from "@ant-design/icons";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { PhiButtonControl } from "./phi-button-control";
+import { PhiCascaderControl } from "./phi-cascader-control";
+import { PhiSelectControl } from "./phi-select-control";
+import { PhiCollectionLayoutControl } from "./phi-collection-layout-control";
+import { PhiMediaAssetCollectionSkeletonControl, PhiMediaAssetTileControl, } from "./phi-media-asset-tile-control";
+import { PHI_MEDIA_PICKER_COLUMN_WIDTH_STEP, PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH, PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH, PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH, normalizePhiMediaPickerMinColumnWidth, } from "./phi-media-picker-control-contract";
+import { PhiPaginationControl } from "./phi-pagination-control";
+import { PhiPopoverControl } from "./phi-popover-control";
+import { PhiSliderControl } from "./phi-slider-control";
+import { PhiTextControl } from "./phi-text-control";
+import { usePhiImmediatePicker } from "./use-phi-immediate-picker";
+export function PhiMediaPickerControl({ open, value = null, assets, spaces = [], spaceValue = null, folders = [], folderValue = "/", query = "", page = 1, pageSize = 20, total = assets.length, minColumnWidth = PHI_MEDIA_PICKER_DEFAULT_COLUMN_WIDTH, loading, disabled, readOnly, placement = "left", showSearchBar = true, showFolderFilter = true, showPagination = true, trigger, labels, getPopupContainer, popupRootClassName, onOpenChange, onQueryChange, onSpaceChange, onFolderChange, onPageChange, onMinColumnWidthChange, onReload, onChange, onCommit, onDiscard, }) {
+    const { token } = usePhiConfig();
+    const locked = disabled || readOnly;
+    const resolvedMinColumnWidth = normalizePhiMediaPickerMinColumnWidth(minColumnWidth);
+    const picker = usePhiImmediatePicker({
+        value,
+        open,
+        disabled: locked,
+        onChange,
+        onCommit,
+        onDiscard,
+        onOpenChange,
+    });
+    const selected = assets.find((asset) => asset.id === picker.value) ?? null;
+    const tileItems = assets.map((asset) => (_jsx(PhiMediaAssetTileControl, { asset: asset, minColumnWidth: resolvedMinColumnWidth, selected: asset.id === picker.value, size: "small", disabled: locked, showTypeLabel: false, showDeleteAction: false, showDimensions: false, showIdLabel: false, onSelect: (nextAsset) => {
+            picker.changeValue(nextAsset.id);
+            picker.closePicker("commit");
+        } }, asset.id)));
+    const content = (_jsxs(Flex, { vertical: true, gap: token.paddingSM, style: {
+            width: "min(560px, calc(100vw - 48px))",
+            height: "min(480px, calc(100dvh - 48px))",
+            minHeight: 0,
+        }, children: [_jsx(Typography.Text, { strong: true, children: labels?.title ?? "Select media" }), _jsxs(Flex, { gap: token.paddingSM, align: "center", wrap: true, children: [showSearchBar ? (_jsx("div", { style: { flex: "1 1 220px" }, children: _jsx(PhiTextControl, { inputType: "search", value: query, size: "small", placeholder: labels?.search ?? "Search", disabled: locked, onChange: (next) => onQueryChange?.(next ?? "") }) })) : null, spaces.length > 1 ? (_jsx("div", { style: { flex: "0 1 160px" }, children: _jsx(PhiSelectControl, { value: spaceValue ?? undefined, options: spaces, size: "small", placeholder: labels?.space ?? "Space", disabled: locked, getPopupContainer: getPopupContainer, popupRootClassName: popupRootClassName, onChange: (next) => { if (typeof next === "string" && next)
+                                onSpaceChange?.(next); } }) })) : null, showFolderFilter ? (_jsx("div", { style: { flex: "1 1 180px" }, children: _jsx(PhiCascaderControl, { value: folderValue, options: folders, allowRoot: true, rootValue: "/", separator: "/", size: "small", placeholder: labels?.folder ?? "Folder", disabled: locked, getPopupContainer: getPopupContainer, classNames: popupRootClassName ? { popup: { root: popupRootClassName } } : undefined, onChange: (next) => onFolderChange?.(next ?? "/") }) })) : null, _jsx(PhiButtonControl, { ariaLabel: labels?.reload ?? "Reload", tooltip: labels?.reload ?? "Reload", icon: _jsx(ReloadOutlined, {}), size: "small", disabled: locked, onClick: onReload })] }), _jsx("div", { style: { flex: "1 1 auto", minHeight: 0, overflow: "auto" }, children: loading && assets.length === 0 ? (_jsx(PhiMediaAssetCollectionSkeletonControl, { mode: "grid", gap: token.paddingSM, minColumnWidth: resolvedMinColumnWidth, count: Math.min(pageSize, 12), size: "small" })) : assets.length === 0 ? (_jsx(Empty, { description: labels?.empty ?? "No media" })) : (_jsx(PhiCollectionLayoutControl, { mode: "grid", gap: token.paddingSM, minColumnWidth: resolvedMinColumnWidth, items: tileItems })) }), _jsxs(Flex, { align: "center", gap: token.paddingSM, style: { flex: "0 0 auto", minWidth: 0 }, children: [_jsx(Typography.Text, { type: "secondary", ellipsis: true, style: { flex: "0 1 180px", minWidth: 0 }, children: selected?.title || selected?.originalName || "" }), _jsxs(Flex, { align: "center", gap: token.paddingXS, style: { flex: "1 1 160px", minWidth: 120 }, children: [_jsx(PhiSliderControl, { ariaLabel: labels?.tileSize ?? "Tile size", value: resolvedMinColumnWidth, min: PHI_MEDIA_PICKER_MIN_COLUMN_WIDTH, max: PHI_MEDIA_PICKER_MAX_COLUMN_WIDTH, step: PHI_MEDIA_PICKER_COLUMN_WIDTH_STEP, tooltipSuffix: " px", disabled: locked, style: { flex: "1 1 auto", minWidth: 0 }, onChange: onMinColumnWidthChange }), _jsxs(Typography.Text, { type: "secondary", style: { fontSize: token.fontSizeSM, whiteSpace: "nowrap" }, children: [resolvedMinColumnWidth, "px"] })] }), _jsx(PhiButtonControl, { label: labels?.clear ?? "Clear", size: "small", disabled: locked || picker.value == null, onClick: () => picker.changeValue(null) }), showPagination ? (_jsx(PhiPaginationControl, { page: page, pageSize: pageSize, total: total, size: "small", disabled: locked, showSizeChanger: true, getPopupContainer: getPopupContainer, popupRootClassName: popupRootClassName, onChange: (next) => onPageChange?.(next.page, next.pageSize) })) : null] })] }));
+    return (_jsx(PhiPopoverControl, { open: picker.open, content: content, placement: placement, disabled: locked, getPopupContainer: getPopupContainer, rootClassName: popupRootClassName, onOpenChange: picker.handleOpenChange, children: trigger ?? (_jsx("span", { children: _jsx(PhiButtonControl, { block: true, icon: _jsx(PictureOutlined, {}), label: labels?.trigger ?? "Select media", disabled: locked, onClick: picker.openPicker }) })) }));
+}

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

@@ -0,0 +1,44 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ItemType } from "antd/es/menu/interface";
+export type PhiMenuControlDivider = {
+    type: "divider";
+    key?: string;
+};
+export type PhiMenuControlEntry = {
+    key: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    className?: string;
+    disabled?: boolean;
+    onClick?: () => void;
+    children?: readonly PhiMenuControlItem[];
+};
+export type PhiMenuControlItem = PhiMenuControlDivider | PhiMenuControlEntry;
+export type PhiMenuControlProps = {
+    /**
+     * Distinguishes the generated theme CSS variable scope between menus rendered on one page
+     * (for example the sidebar and its Builder preview), so their component tokens never collide.
+     */
+    scope: string;
+    items: readonly PhiMenuControlItem[];
+    mode: "inline" | "horizontal";
+    /** Defaults to the active Phi theme mode. */
+    menuTheme?: "light" | "dark";
+    selectedKeys?: readonly string[];
+    collapsed?: boolean;
+    collapsedWidth?: number | string;
+    inlineIndent?: number;
+    /** Resolved presentation values; the owning Widget maps its own config to these. */
+    fontFamily?: string;
+    fontSize?: number;
+    style?: CSSProperties;
+};
+export declare function toPhiAntdMenuItems(items: readonly PhiMenuControlItem[]): ItemType[];
+/**
+ * The canonical navigation menu presentation (SETTINGS.md-independent; see the Control layer
+ * boundary in AGENTS.md): Widgets describe navigation as `PhiMenuControlItem`s and never touch the
+ * Ant Design Menu or its item interface. The theme wiring lives here once — the scoped CSS variable
+ * key, the transparent item backgrounds every Phi menu surface uses, and the collapsed-sider width
+ * — so menu surfaces cannot drift apart in their component tokens.
+ */
+export declare function PhiMenuControl({ scope, items, mode, menuTheme, selectedKeys, collapsed, collapsedWidth, inlineIndent, fontFamily, fontSize, style, }: PhiMenuControlProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,71 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ConfigProvider, Menu } from "antd";
+import { createPhiAntdThemeCssVarKey } from "../../theme/phi-antd-token-resolver";
+import { usePhiConfig } from "../root/phi-config-provider";
+export function toPhiAntdMenuItems(items) {
+    return items.map((item) => {
+        if ("type" in item) {
+            return { type: "divider", ...(item.key ? { key: item.key } : {}) };
+        }
+        const { children, ...entry } = item;
+        return {
+            ...entry,
+            ...(children && children.length > 0 ? { children: toPhiAntdMenuItems(children) } : {}),
+        };
+    });
+}
+/**
+ * The canonical navigation menu presentation (SETTINGS.md-independent; see the Control layer
+ * boundary in AGENTS.md): Widgets describe navigation as `PhiMenuControlItem`s and never touch the
+ * Ant Design Menu or its item interface. The theme wiring lives here once — the scoped CSS variable
+ * key, the transparent item backgrounds every Phi menu surface uses, and the collapsed-sider width
+ * — so menu surfaces cannot drift apart in their component tokens.
+ */
+export function PhiMenuControl({ scope, items, mode, menuTheme, selectedKeys, collapsed = false, collapsedWidth, inlineIndent, fontFamily, fontSize, style, }) {
+    const { mode: themeMode, token } = usePhiConfig();
+    const resolvedMenuTheme = menuTheme ?? themeMode;
+    const localThemeToken = {
+        ...(fontFamily ? { fontFamily } : {}),
+        ...(fontSize ? { fontSize } : {}),
+    };
+    /**
+     * Only the stacked menu overrides item geometry: it fills the width of its Sider, so items carry
+     * no inline margin and paint no background of their own. A horizontal menu keeps the Ant Design
+     * defaults, whose item spacing is what separates the entries in a header bar.
+     */
+    const menuComponentTheme = mode === "inline"
+        ? {
+            ...(collapsedWidth !== undefined ? { collapsedWidth } : {}),
+            itemMarginBlock: token.marginXXS,
+            itemMarginInline: 0,
+            itemBg: "transparent",
+            subMenuItemBg: "transparent",
+            darkItemBg: "transparent",
+            darkSubMenuItemBg: "transparent",
+        }
+        : {};
+    const themeCssVarKey = createPhiAntdThemeCssVarKey(scope, {
+        mode: themeMode,
+        rootToken: token,
+        token: localThemeToken,
+        menu: menuComponentTheme,
+        menuTheme: resolvedMenuTheme,
+    });
+    if (items.length === 0) {
+        return null;
+    }
+    return (_jsx(ConfigProvider, { theme: {
+            cssVar: { prefix: "ant", key: themeCssVarKey },
+            token: localThemeToken,
+            components: { Menu: menuComponentTheme },
+        }, children: _jsx(Menu, { mode: mode, theme: resolvedMenuTheme, selectedKeys: selectedKeys ? [...selectedKeys] : undefined, items: toPhiAntdMenuItems(items), ...(mode === "inline" ? { inlineCollapsed: collapsed, inlineIndent } : {}), style: {
+                background: "transparent",
+                width: "100%",
+                minWidth: 0,
+                ...(mode === "inline"
+                    ? { height: "auto", borderInlineEnd: "none" }
+                    : { borderBottom: "none" }),
+                ...style,
+            } }) }));
+}

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

@@ -0,0 +1,12 @@
+import type { PhiCmsOverlaySize } from "../../types/cms-overlay";
+import type { PhiControlSize } from "../../types/control";
+import type { PhiRenderableBlockSize } from "../../types/renderable-block";
+import { type PhiOverlayControlCommonProps } from "./phi-overlay-control-contract";
+export type PhiModalControlProps = PhiOverlayControlCommonProps & {
+    centered?: boolean;
+    controlSize?: PhiControlSize;
+    size?: PhiRenderableBlockSize | null;
+    width?: PhiCmsOverlaySize | Partial<Record<"xs" | "md" | "lg", PhiCmsOverlaySize>>;
+    rootClassName?: string;
+};
+export declare function PhiModalControl({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, centered, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, }: PhiModalControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,132 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { Modal } from "antd";
+import { PHI_CONTROL, PHI_SPACE } from "../../theme/antd-css-var-contract";
+import { resolvePhiMotionDurationMs } from "../../helpers/motion";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { PHI_OVERLAY_DEFAULT_MASK, resolvePhiOverlayDismissSource, resolvePhiOverlayMaskPresentation, } from "./phi-overlay-control-contract";
+const subscribeHydration = () => () => undefined;
+const PHI_MODAL_WIDTH_BY_CONTROL_SIZE = {
+    small: 520,
+    medium: 720,
+    large: 960,
+};
+const PHI_MODAL_HEADER_MIN_BLOCK_SIZE = `calc(${PHI_CONTROL.md} + ${PHI_SPACE.xs} + ${PHI_SPACE.xs})`;
+export function PhiModalControl({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", centered = false, controlSize, size, width, rootClassName, containerStyle, onDismiss, afterOpenChange, }) {
+    const { token } = usePhiConfig();
+    const hydrated = useSyncExternalStore(subscribeHydration, () => true, () => false);
+    const bodyMeasureRef = useRef(null);
+    const bodyContentRef = useRef(null);
+    const resizeAnimationRef = useRef(null);
+    useEffect(() => {
+        const bodyMeasure = bodyMeasureRef.current;
+        const bodyContent = bodyContentRef.current;
+        if (!open || !bodyMeasure || !bodyContent || size?.height != null || typeof ResizeObserver === "undefined") {
+            return undefined;
+        }
+        let targetBlockSize = bodyContent.getBoundingClientRect().height;
+        const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        const duration = resolvePhiMotionDurationMs(token.motionDurationMid);
+        const animateResize = (from, to) => {
+            if (reducedMotion || duration <= 0 || typeof bodyMeasure.animate !== "function")
+                return;
+            const animation = bodyMeasure.animate([{ height: `${from}px` }, { height: `${to}px` }], { duration, easing: token.motionEaseInOut });
+            resizeAnimationRef.current = animation;
+            animation.addEventListener("finish", () => {
+                if (resizeAnimationRef.current !== animation)
+                    return;
+                resizeAnimationRef.current = null;
+            }, { once: true });
+            animation.addEventListener("cancel", () => {
+                if (resizeAnimationRef.current === animation)
+                    resizeAnimationRef.current = null;
+            }, { once: true });
+        };
+        const observer = new ResizeObserver(() => {
+            const nextBlockSize = bodyContent.getBoundingClientRect().height;
+            if (Math.abs(nextBlockSize - targetBlockSize) < 1)
+                return;
+            const previousBlockSize = resizeAnimationRef.current
+                ? bodyMeasure.getBoundingClientRect().height
+                : targetBlockSize;
+            resizeAnimationRef.current?.cancel();
+            targetBlockSize = nextBlockSize;
+            animateResize(previousBlockSize, nextBlockSize);
+        });
+        observer.observe(bodyContent);
+        return () => {
+            observer.disconnect();
+            resizeAnimationRef.current?.cancel();
+            resizeAnimationRef.current = null;
+        };
+    }, [open, size?.height, token.motionDurationMid, token.motionEaseInOut]);
+    const resolvedMask = resolvePhiOverlayMaskPresentation(mask);
+    const renderedTitle = header == null ? title : (_jsxs("div", { style: {
+            display: "grid",
+            minBlockSize: PHI_MODAL_HEADER_MIN_BLOCK_SIZE,
+            minWidth: 0,
+            position: "relative",
+            width: "100%",
+        }, children: [header, title == null ? null : (_jsx("div", { style: {
+                    insetInlineStart: PHI_SPACE.base,
+                    minWidth: 0,
+                    position: "absolute",
+                    top: "50%",
+                    transform: "translateY(-50%)",
+                    zIndex: 1,
+                }, children: title }))] }));
+    const resolvedWidth = size?.width ?? width ?? (controlSize == null
+        ? undefined
+        : PHI_MODAL_WIDTH_BY_CONTROL_SIZE[controlSize]);
+    return (_jsx(Modal, { open: open, title: renderedTitle, closable: closable, keyboard: keyboard, mask: resolvedMask.adapterMask, destroyOnHidden: mountPolicy === "remount", forceRender: hydrated && mountPolicy === "eager", centered: centered, width: resolvedWidth, style: {
+            maxWidth: `calc(100vw - ${PHI_SPACE.base} - ${PHI_SPACE.base})`,
+            transition: `width ${token.motionDurationMid} ${token.motionEaseInOut}`,
+        }, rootClassName: rootClassName, footer: footer ?? null, focusable: { trap: true, focusTriggerAfterClose: true }, styles: {
+            mask: resolvedMask.maskStyle,
+            container: {
+                display: "flex",
+                flexDirection: "column",
+                gap: 0,
+                ...(size?.height == null ? {} : { blockSize: size.height }),
+                maxBlockSize: `calc(100dvh - ${PHI_SPACE.lg} - ${PHI_SPACE.lg})`,
+                overflow: "hidden",
+                ...containerStyle,
+                padding: 0,
+            },
+            header: {
+                flex: "0 0 auto",
+                display: header == null ? "flex" : undefined,
+                alignItems: header == null ? "center" : undefined,
+                minBlockSize: PHI_MODAL_HEADER_MIN_BLOCK_SIZE,
+                marginBlock: 0,
+                padding: 0,
+                background: "transparent",
+            },
+            title: header == null
+                ? { minWidth: 0, marginInlineStart: PHI_SPACE.base }
+                : { width: "100%", minWidth: 0 },
+            close: {
+                top: PHI_SPACE.xs,
+                insetInlineEnd: PHI_SPACE.xs,
+            },
+            body: {
+                flex: "1 1 auto",
+                minBlockSize: 0,
+                overflowY: "auto",
+                scrollbarGutter: "auto",
+                padding: 0,
+                background: "transparent",
+            },
+            footer: {
+                flex: "0 0 auto",
+                padding: 0,
+                background: "transparent",
+            },
+        }, onCancel: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, modalRender: (node) => (_jsx("div", { onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: _jsx("div", { ref: bodyMeasureRef, "data-phi-modal-body-measure": "true", style: {
+                minWidth: 0,
+                overflow: "hidden",
+                width: "100%",
+                ...(size?.height == null ? {} : { minBlockSize: "100%" }),
+            }, children: _jsx("div", { ref: bodyContentRef, "data-phi-modal-body-content": "true", style: { minWidth: 0, width: "100%" }, children: body }) }) }));
+}

package/components/controls/phi-multi-select-control.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+import type { SelectProps } from "antd";
+import type { PhiControlSize, PhiControlVariant } from "../../types/control";
+import type { PhiControlOption } from "./phi-control-options";
+export type PhiMultiSelectControlProps<TValue extends string | number = string> = {
+    value?: readonly TValue[];
+    label?: string;
+    description?: ReactNode;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    allowCustom?: boolean;
+    allowClear?: boolean;
+    options: readonly PhiControlOption<TValue>[];
+    maxTagCount?: number | "responsive";
+    size?: PhiControlSize;
+    variant?: PhiControlVariant;
+    popupMatchSelectWidth?: boolean | number;
+    style?: SelectProps["style"];
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onChange?: (value: TValue[]) => void;
+};
+export declare function PhiMultiSelectControl<TValue extends string | number = string>({ value, label, description, placeholder, disabled, readOnly, allowCustom, allowClear, options, maxTagCount, size, variant, popupMatchSelectWidth, style, onFocus, onBlur, onChange, }: PhiMultiSelectControlProps<TValue>): import("react").JSX.Element;

package/components/controls/phi-multi-select-control.js

@@ -0,0 +1,26 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Select } from "antd";
+import { PhiControlOptionContent } from "./phi-control-option-content";
+import { PhiLabeledControl } from "./phi-labeled-control";
+export function PhiMultiSelectControl({ value, label, description, placeholder, disabled, readOnly, allowCustom, allowClear, options, maxTagCount, size, variant, popupMatchSelectWidth = false, style, onFocus, onBlur, onChange, }) {
+    const selectOptions = useMemo(() => options.map((option) => ({
+        value: option.value,
+        // Keep labels non-primitive so rc-select cannot add native HTML titles.
+        label: _jsx(_Fragment, { children: option.label }),
+        searchLabel: option.label,
+        option,
+        disabled: option.disabled,
+    })), [options]);
+    const control = (_jsx(Select, { mode: allowCustom ? "tags" : "multiple", allowClear: allowClear, value: [...(value ?? [])], placeholder: placeholder, disabled: disabled || readOnly || !onChange, options: selectOptions, optionFilterProp: ["searchLabel", "value"], optionRender: (option) => {
+            const item = option.data.option;
+            return _jsx(PhiControlOptionContent, { option: item, presentation: "dropdown" });
+        }, labelRender: (selectedOption) => {
+            const selected = options.find((option) => option.value === selectedOption.value);
+            return selected
+                ? _jsx(PhiControlOptionContent, { option: selected, presentation: "selection" })
+                : selectedOption.label;
+        }, maxTagCount: maxTagCount, popupMatchSelectWidth: popupMatchSelectWidth, size: size, variant: variant, onFocus: onFocus, onBlur: onBlur, onChange: onChange, style: style }));
+    return _jsx(PhiLabeledControl, { label: label, description: description, fill: style?.width === "100%", children: control });
+}

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

@@ -0,0 +1,28 @@
+import type { CSSProperties, FocusEventHandler, KeyboardEventHandler, ReactNode } from "react";
+import type { PhiControlSize, PhiControlVariant } from "../../types/control";
+export type PhiNumberControlProps = {
+    value?: number | null;
+    label?: string;
+    /**
+     * What the number is in, shown inside the field.
+     *
+     * A unit belongs to the value, not to the field's name: a label saying "Tracking (em)" leaves the
+     * number looking unitless the moment the label scrolls out of sight, and it is the reading that
+     * invites somebody to type the unit in as well.
+     */
+    prefix?: ReactNode;
+    placeholder?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    disabled?: boolean;
+    readOnly?: boolean;
+    size?: PhiControlSize;
+    variant?: PhiControlVariant;
+    style?: CSSProperties;
+    onChange?: (value: number | null) => void;
+    onBlur?: FocusEventHandler<HTMLInputElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLInputElement>;
+};
+export declare function PhiNumberControl({ value, label, prefix, placeholder, min, max, step, precision, disabled, readOnly, size, variant, style, onChange, onBlur, onKeyDown, }: PhiNumberControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InputNumber } from "antd";
+import { PhiLabeledControl } from "./phi-labeled-control";
+export function PhiNumberControl({ value, label, prefix, placeholder, min, max, step, precision, disabled, readOnly, size, variant, style, onChange, onBlur, onKeyDown, }) {
+    const control = (_jsx(InputNumber, { value: value, prefix: prefix, placeholder: placeholder, min: min, max: max, step: step, precision: precision, disabled: disabled || (!onChange && !readOnly), readOnly: readOnly, size: size, variant: variant, style: style, onChange: onChange, onBlur: onBlur, onKeyDown: onKeyDown }));
+    return _jsx(PhiLabeledControl, { label: label, fill: style?.width === "100%", children: control });
+}