@phis/ui 0.1.0

package/components/controls/phi-builder-insert-picker-control.js

@@ -0,0 +1,190 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { Flex, Input, Segmented, Select, Space, Tag, Tooltip, Typography, theme as antdTheme } from "antd";
+import { PhiIcon } from "../shell/phi-icon";
+import { PhiPopoverControl } from "./phi-popover-control";
+import { usePhiImmediatePicker } from "./use-phi-immediate-picker";
+import { PHI_BUILDER_INSERT_PICKER_CONTROL_DEFAULT_LABELS, } from "./phi-builder-insert-picker-control-labels";
+function normalizeSearchText(value) {
+    return value.trim().toLowerCase();
+}
+function resolveItemPackageName(item) {
+    const raw = item.packageName ?? item.origin ?? "";
+    if (!raw)
+        return null;
+    const parts = raw.split("/");
+    if (raw.startsWith("@") && parts.length >= 2) {
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return parts[0] ?? raw;
+}
+function buildItemSearchText(item) {
+    return [
+        item.title,
+        item.description ?? "",
+        item.category ?? "",
+        resolveItemPackageName(item) ?? "",
+        ...(item.tags ?? []),
+    ].join(" ").toLowerCase();
+}
+function resolveItemCategoryTagColor(category) {
+    switch (category) {
+        case "navigation": return "green";
+        case "form": return "gold";
+        case "content": return "purple";
+        case "commerce": return "volcano";
+        case "account": return "geekblue";
+        case "data":
+        case "media": return "cyan";
+        case "configuration": return "orange";
+        case "workspace": return "red";
+        case "developer": return "magenta";
+        case "structure":
+        default: return "blue";
+    }
+}
+const WIDGET_CATEGORY_ORDER = [
+    "content",
+    "navigation",
+    "form",
+    "data",
+    "media",
+    "commerce",
+    "account",
+    "configuration",
+    "structure",
+    "workspace",
+    "developer",
+    "other",
+];
+function resolveWidgetCategorySortValue(category) {
+    const order = WIDGET_CATEGORY_ORDER.indexOf(category);
+    return order >= 0 ? order : WIDGET_CATEGORY_ORDER.length;
+}
+function resolveItemIcon(item) {
+    if (item.icon)
+        return item.icon;
+    return item.kind === "layout"
+        ? "@phis/ui/layouts:flex"
+        : "@phis/ui/widgets:internal";
+}
+export function PhiBuilderInsertPickerControl({ open, trigger, items, section, packageFilters, widgetCategoryFilters, allowLayoutSection, allowWidgetSection, placement = "top", labels = PHI_BUILDER_INSERT_PICKER_CONTROL_DEFAULT_LABELS, onOpenChange, onSectionChange, onPackageFiltersChange, onWidgetCategoryFiltersChange, onChange, }) {
+    const { token } = antdTheme.useToken();
+    const picker = usePhiImmediatePicker({
+        value: null,
+        open,
+        onOpenChange,
+        onChange: (item) => {
+            if (item)
+                onChange(item);
+        },
+    });
+    const [search, setSearch] = useState("");
+    const popoverWidth = Math.min(token.controlHeight * 26, 420);
+    const popoverMaxWidth = `calc(100vw - ${token.paddingLG * 2}px)`;
+    const popoverHeight = `min(${token.controlHeight * 18}px, calc(100vh - ${token.paddingLG * 2}px))`;
+    const listMaxHeight = token.controlHeight * 12;
+    const itemIconFrameSize = token.controlHeight;
+    const itemIconSize = token.fontSizeHeading3;
+    const normalizedSearch = normalizeSearchText(search);
+    const packageFilterSet = useMemo(() => new Set(packageFilters), [packageFilters]);
+    const categoryFilterSet = useMemo(() => new Set(widgetCategoryFilters), [widgetCategoryFilters]);
+    const sectionItems = useMemo(() => items.filter((item) => item.kind === section), [items, section]);
+    const packageOptions = useMemo(() => [...new Set(sectionItems
+            .map(resolveItemPackageName)
+            .filter((packageName) => Boolean(packageName)))].sort((left, right) => left.localeCompare(right)), [sectionItems]);
+    const categoryOptions = useMemo(() => [...new Set(items
+            .filter((item) => item.kind === "widget" && item.category != null)
+            .map((item) => item.category))].sort((left, right) => {
+        const orderDelta = resolveWidgetCategorySortValue(left) - resolveWidgetCategorySortValue(right);
+        return orderDelta !== 0 ? orderDelta : left.localeCompare(right);
+    }), [items]);
+    const visibleItems = sectionItems.filter((item) => {
+        const packageName = resolveItemPackageName(item) ?? "";
+        if (packageFilters.length > 0 && !packageFilterSet.has(packageName))
+            return false;
+        if (item.kind === "widget" && widgetCategoryFilters.length > 0 && !categoryFilterSet.has(item.category ?? "other"))
+            return false;
+        return !normalizedSearch || buildItemSearchText(item).includes(normalizedSearch);
+    });
+    const title = section === "widget" ? labels.pickWidget : labels.pickLayout;
+    const placeholder = section === "widget" ? labels.searchWidgets : labels.searchLayouts;
+    const selectItem = (item) => {
+        picker.changeValue(item);
+        picker.closePicker("commit");
+    };
+    const content = (_jsx("div", { style: {
+            width: popoverWidth,
+            maxWidth: popoverMaxWidth,
+            maxHeight: popoverHeight,
+            display: "flex",
+            flexDirection: "column",
+            overflow: "hidden",
+        }, onClick: (event) => event.stopPropagation(), onMouseDown: (event) => event.stopPropagation(), onPointerDown: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsxs(Flex, { vertical: true, gap: token.paddingSM, style: { width: "100%", minHeight: 0, overflow: "hidden" }, children: [_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: true, children: [_jsx(Typography.Text, { strong: true, style: { fontSize: token.fontSize }, children: title }), _jsx(Segmented, { value: section, onChange: (nextSection) => {
+                                if (nextSection === "layout" && !allowLayoutSection) {
+                                    onSectionChange("widget");
+                                    return;
+                                }
+                                onSectionChange(nextSection);
+                            }, size: "small", options: [
+                                { label: labels.layouts, value: "layout", disabled: !allowLayoutSection },
+                                { label: labels.widgets, value: "widget", disabled: !allowWidgetSection },
+                            ] })] }), _jsx(Input, { autoFocus: true, allowClear: true, value: search, onChange: (event) => setSearch(event.target.value), placeholder: placeholder, variant: "borderless", style: {
+                        borderBottom: `1px solid ${token.colorBorderSecondary}`,
+                        borderRadius: 0,
+                        paddingInline: 0,
+                        boxShadow: "none",
+                    } }), _jsx(Select, { mode: "multiple", allowClear: true, showSearch: false, value: [...packageFilters], onChange: onPackageFiltersChange, options: packageOptions.map((packageName) => ({ value: packageName, label: packageName })), placeholder: labels.filterPackages, maxTagCount: "responsive", style: { width: "100%" } }), section === "widget" ? (_jsx(Select, { mode: "multiple", allowClear: true, showSearch: false, value: [...widgetCategoryFilters], onChange: onWidgetCategoryFiltersChange, options: categoryOptions.map((category) => ({ value: category, label: category })), placeholder: labels.filterCategories, maxTagCount: "responsive", style: { width: "100%" } })) : null, _jsx("div", { style: {
+                        border: `1px solid ${token.colorBorderSecondary}`,
+                        borderRadius: 0,
+                        background: token.colorBgElevated,
+                        padding: token.paddingSM,
+                        flex: "1 1 auto",
+                        minHeight: 0,
+                        maxHeight: listMaxHeight,
+                        overflowY: "auto",
+                        overflowX: "hidden",
+                    }, children: visibleItems.length > 0 ? (_jsx("div", { style: {
+                            display: "grid",
+                            gridTemplateColumns: section === "widget" ? "minmax(0, 1fr)" : "repeat(2, minmax(0, 1fr))",
+                            gap: token.paddingMD,
+                            width: "100%",
+                        }, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingXS, width: "100%" }, children: [_jsx(Typography.Text, { type: "secondary", children: section === "widget" ? labels.widgets : labels.layouts }), _jsx(Space, { orientation: "vertical", size: 0, style: { width: "100%" }, children: visibleItems.map((item, index) => {
+                                        const isLast = index === visibleItems.length - 1;
+                                        const isActive = picker.value?.key === item.key;
+                                        return (_jsx("div", { role: "button", tabIndex: 0, style: {
+                                                cursor: "pointer",
+                                                paddingInline: 0,
+                                                paddingBlock: token.paddingSM,
+                                                borderBottom: isLast ? "none" : `1px solid ${token.colorBorderSecondary}`,
+                                                borderRadius: 0,
+                                                background: isActive ? token.colorFillQuaternary : "transparent",
+                                                outline: isActive ? `1px solid ${token.colorPrimary}` : "none",
+                                                outlineOffset: -1,
+                                            }, onClick: () => selectItem(item), onKeyDown: (event) => {
+                                                if (event.key !== "Enter" && event.key !== " ")
+                                                    return;
+                                                event.preventDefault();
+                                                selectItem(item);
+                                            }, children: _jsxs("div", { style: {
+                                                    display: "grid",
+                                                    gridTemplateColumns: `${itemIconFrameSize}px minmax(0, 1fr) auto`,
+                                                    alignItems: "center",
+                                                    gap: token.paddingSM,
+                                                    width: "100%",
+                                                }, children: [_jsx("span", { style: {
+                                                            width: itemIconFrameSize,
+                                                            height: itemIconFrameSize,
+                                                            lineHeight: 1,
+                                                            display: "inline-flex",
+                                                            alignItems: "center",
+                                                            justifyContent: "center",
+                                                        }, children: _jsx(Tooltip, { title: item.description ?? undefined, placement: "top", children: _jsx(PhiIcon, { name: resolveItemIcon(item), size: itemIconSize }) }) }), _jsxs(Space, { orientation: "vertical", size: 0, style: { minWidth: 0 }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, children: item.title }), resolveItemPackageName(item) ? (_jsx(Typography.Text, { type: "secondary", children: resolveItemPackageName(item) })) : null] }), _jsxs(Space, { orientation: "vertical", size: 2, style: { alignItems: "flex-end" }, children: [item.kind === "widget" && item.category ? (_jsx(Tag, { color: resolveItemCategoryTagColor(item.category), style: { marginInlineEnd: 0 }, children: item.category })) : null, (item.tags ?? []).length > 0 ? (_jsx(Space, { size: 4, wrap: true, style: { justifyContent: "flex-end" }, children: (item.tags ?? []).map((tag) => _jsx(Tag, { color: "blue", children: tag }, tag)) })) : null] })] }) }, item.key));
+                                    }) })] }) })) : (_jsx(Typography.Text, { type: "secondary", children: labels.noCompatibleItems })) })] }) }));
+    return (_jsx(PhiPopoverControl, { open: picker.open, trigger: "click", placement: placement, arrow: "point-at-center", destroyOnHidden: true, content: content, popupContentStyle: { overflow: "hidden" }, onOpenChange: (nextOpen) => {
+            if (!nextOpen)
+                setSearch("");
+            picker.handleOpenChange(nextOpen);
+        }, children: trigger }));
+}

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

@@ -0,0 +1,59 @@
+import type { ReactNode, Ref } from "react";
+import type { ButtonProps } from "antd";
+import type { PhiControlSize } from "../../types/control";
+import type { PhiButtonType } from "./phi-button-types";
+export type PhiControlBadgePresentation = {
+    enabled?: boolean;
+    value?: string | number | null;
+    color?: string;
+    overflowCount?: number;
+    showZero?: boolean;
+};
+export type PhiButtonControlProps = {
+    label?: ReactNode;
+    ariaLabel?: string;
+    /**
+     * Renders the button as a link rather than a command.
+     *
+     * A Button without `onClick` is disabled on purpose -- a control that emits nothing is not a control
+     * -- but a link emits nothing and still does something, so `href` lifts that rule for itself. The
+     * anchor is a real one: it works before hydration and survives a page that mounts no Controller,
+     * which is exactly the case a refusal page is.
+     */
+    href?: string;
+    /**
+     * Opens `href` in a new tab, and only ever together with `rel="noreferrer"`.
+     *
+     * A flag rather than `target` and `rel` of its own: the two are one decision, and a new tab without
+     * `noreferrer` hands the opened page a handle back to this one. Making them separate props would make
+     * that mistake the easy one.
+     */
+    newTab?: boolean;
+    tooltip?: ReactNode;
+    icon?: ReactNode;
+    type?: PhiButtonType;
+    /** A round button is what an icon on its own wants, over a picture or in a toolbar. */
+    shape?: ButtonProps["shape"];
+    danger?: boolean;
+    disabled?: boolean;
+    loading?: boolean;
+    htmlType?: ButtonProps["htmlType"];
+    block?: boolean;
+    size?: PhiControlSize;
+    style?: ButtonProps["style"];
+    badge?: PhiControlBadgePresentation;
+    /**
+     * A styling hook, for a surface that places the button with its own stylesheet.
+     *
+     * Authoring chrome is the case: its affordances are sized and positioned by the scaffold stylesheets,
+     * which find them by class. A class carries no behaviour, so it stays inside what a Control may accept.
+     */
+    className?: string;
+    /**
+     * The button element itself, for something that has to measure or register it -- a drop target, the
+     * scaffold a preview is taken from. Never a way to reach the element's own handlers.
+     */
+    ref?: Ref<HTMLButtonElement | HTMLAnchorElement>;
+    onClick?: () => void;
+};
+export declare function PhiButtonControl({ label, ariaLabel, href, newTab, tooltip, icon, type, shape, danger, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }: PhiButtonControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Link from "next/link";
+import { Badge, Button, Tooltip } from "antd";
+export function PhiButtonControl({ label, ariaLabel, href, newTab, tooltip, icon, type = "default", shape, danger, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }) {
+    const visibleTooltip = typeof label === "string" && typeof tooltip === "string" && label === tooltip
+        ? null
+        : tooltip;
+    const button = (_jsx(Button, { ref: ref, className: className, "aria-label": ariaLabel, type: type, shape: shape, danger: danger, disabled: disabled || (!onClick && !href && htmlType !== "submit"), loading: loading, htmlType: htmlType, block: block, size: size, style: style, icon: icon, onClick: onClick, children: label }));
+    /*
+     * Never prefetched. A button-shaped link is a deliberate action rather than somewhere the visitor is
+     * already heading, so speculating on it buys nothing -- and on a refusal page, where this is what the
+     * home link is made of, it buys a request for the Area root that the visitor never asked for. An Area
+     * root that forwards turns that into two.
+     */
+    const linked = href && !disabled ? (_jsx(Link, { href: href, prefetch: false, target: newTab ? "_blank" : undefined, rel: newTab ? "noreferrer" : undefined, children: button })) : button;
+    const badged = badge?.enabled ? (_jsx(Badge, { color: badge.color, count: badge.value ?? 0, overflowCount: badge.overflowCount, showZero: badge.showZero, size: "small", children: linked })) : linked;
+    return visibleTooltip ? _jsx(Tooltip, { title: visibleTooltip, children: badged }) : badged;
+}

package/components/controls/phi-button-types.d.ts

@@ -0,0 +1,2 @@
+export type PhiButtonType = "default" | "primary" | "dashed" | "text" | "link";
+export declare function readPhiButtonType(value: unknown): PhiButtonType;

package/components/controls/phi-button-types.js

@@ -0,0 +1,9 @@
+export function readPhiButtonType(value) {
+    const buttonType = typeof value === "string" ? value.trim() : undefined;
+    return buttonType === "primary" ||
+        buttonType === "dashed" ||
+        buttonType === "text" ||
+        buttonType === "link"
+        ? buttonType
+        : "default";
+}

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

@@ -0,0 +1,5 @@
+import type { PhiCalendarAdapterCalendarProps, PhiCalendarAdapterKey } from "../../types/calendar";
+export type PhiCalendarControlProps = PhiCalendarAdapterCalendarProps & {
+    adapterKey: PhiCalendarAdapterKey;
+};
+export declare function PhiCalendarControl({ adapterKey, ...props }: PhiCalendarControlProps): import("react").ReactNode;

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

@@ -0,0 +1,6 @@
+"use client";
+import { usePhiCalendarAdapterClient } from "../runtime/runtime-module-calendar-adapter-client-manifest";
+export function PhiCalendarControl({ adapterKey, ...props }) {
+    const adapter = usePhiCalendarAdapterClient(adapterKey);
+    return adapter.renderCalendar(props);
+}

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

@@ -0,0 +1,32 @@
+import { type CSSProperties } from "react";
+import type { CascaderProps } from "antd/es/cascader";
+import type { PhiControlSize } from "../../types/control";
+import type { PhiControlOption } from "./phi-control-options";
+export type PhiCascaderNormalizeMode = "raw" | "path";
+export type PhiCascaderOption = PhiControlOption;
+export declare function normalizePhiCascaderValue(value: string | null | undefined, options?: {
+    separator?: string | null;
+    rootValue?: string | null;
+    normalize?: PhiCascaderNormalizeMode | null;
+}): string;
+export declare function PhiCascaderControl({ value, options, allowRoot, allowClear, expandTrigger, separator, rootValue, normalize, disabled, readOnly, label, placeholder, size, onChange, onFocus, onBlur, classNames, getPopupContainer, style, }: {
+    value?: string | null;
+    options?: readonly PhiCascaderOption[];
+    allowRoot?: boolean;
+    allowClear?: boolean;
+    expandTrigger?: CascaderProps["expandTrigger"];
+    separator?: string;
+    rootValue?: string;
+    normalize?: PhiCascaderNormalizeMode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    label?: string;
+    placeholder?: string;
+    size?: PhiControlSize;
+    onChange?: (nextValue: string) => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    classNames?: CascaderProps["classNames"];
+    getPopupContainer?: CascaderProps["getPopupContainer"];
+    style?: CSSProperties;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,174 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { Cascader } from "antd";
+import { PhiLabeledControl } from "./phi-labeled-control";
+export function normalizePhiCascaderValue(value, options) {
+    const separator = options?.separator?.trim() || "/";
+    const rootValue = options?.rootValue?.trim() || "/";
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed || trimmed === rootValue) {
+        return rootValue;
+    }
+    const normalizedInput = trimmed
+        .replace(new RegExp(`^${escapeRegExp(separator)}+`), "")
+        .replace(new RegExp(`${escapeRegExp(separator)}+$`), "");
+    const segments = normalizedInput
+        .split(separator)
+        .map((segment) => {
+        const rawSegment = segment.trim();
+        if (options?.normalize !== "path") {
+            return rawSegment;
+        }
+        return rawSegment
+            .toLowerCase()
+            .replace(/['"]/g, "")
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "");
+    })
+        .filter(Boolean);
+    return segments.length > 0 ? `${rootValue === separator ? separator : ""}${segments.join(separator)}` : rootValue;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function titleizeSegment(value, rootValue) {
+    if (value === rootValue) {
+        return rootValue;
+    }
+    return (value
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join(" ") || rootValue);
+}
+function splitCascaderSegments(value, separator, rootValue) {
+    const normalized = normalizePhiCascaderValue(value, { separator, rootValue, normalize: "raw" });
+    return normalized === rootValue
+        ? [rootValue]
+        : normalized.replace(new RegExp(`^${escapeRegExp(separator)}+`), "").split(separator).filter(Boolean);
+}
+function joinCascaderSegments(segments, separator, rootValue) {
+    if (segments.length === 0 || segments[0] === rootValue) {
+        return rootValue;
+    }
+    return `${rootValue === separator ? separator : ""}${segments.join(separator)}`;
+}
+function findOptionPath(options, normalizedValue, separator, rootValue) {
+    const targetSegments = splitCascaderSegments(normalizedValue, separator, rootValue);
+    const visit = (nodes, segmentIndex, prefix) => {
+        const targetValue = targetSegments[segmentIndex] === rootValue
+            ? rootValue
+            : joinCascaderSegments(targetSegments.slice(0, segmentIndex + 1), separator, rootValue);
+        for (const node of nodes) {
+            if (node.value !== targetValue) {
+                continue;
+            }
+            const currentPath = [...prefix, String(node.value)];
+            if (segmentIndex === targetSegments.length - 1) {
+                return currentPath;
+            }
+            const childPath = node.children ? visit(node.children, segmentIndex + 1, currentPath) : null;
+            if (childPath) {
+                return childPath;
+            }
+        }
+        return null;
+    };
+    return visit(options, 0, []);
+}
+function insertCascaderOption(options, option, allowRoot, separator, rootValue, normalize) {
+    const value = normalizePhiCascaderValue(option.value, { separator, rootValue, normalize });
+    if (value === rootValue) {
+        if (allowRoot && !options.some((entry) => entry.value === rootValue)) {
+            options.unshift({
+                value: rootValue,
+                label: option.label?.trim() || rootValue,
+                title: "",
+            });
+        }
+        return;
+    }
+    const segments = splitCascaderSegments(value, separator, rootValue);
+    let currentOptions = options;
+    segments.forEach((segment, index) => {
+        const cumulativeValue = joinCascaderSegments(segments.slice(0, index + 1), separator, rootValue);
+        let current = currentOptions.find((entry) => entry.value === cumulativeValue);
+        if (!current) {
+            current = {
+                value: cumulativeValue,
+                label: index === segments.length - 1 ? option.label?.trim() || titleizeSegment(segment, rootValue) : titleizeSegment(segment, rootValue),
+                title: "",
+            };
+            currentOptions.push(current);
+            currentOptions.sort((left, right) => String(left.label ?? "").localeCompare(String(right.label ?? "")));
+        }
+        if (index < segments.length - 1) {
+            current.children = current.children ?? [];
+            currentOptions = current.children;
+        }
+    });
+}
+function buildCascaderOptions(configuredOptions, currentValue, allowRoot, separator, rootValue, normalize) {
+    const options = [];
+    if (allowRoot) {
+        const configuredRoot = configuredOptions.find((option) => normalizePhiCascaderValue(option.value, { separator, rootValue, normalize }) === rootValue);
+        insertCascaderOption(options, { value: rootValue, label: configuredRoot?.label ?? rootValue }, allowRoot, separator, rootValue, normalize);
+    }
+    for (const option of configuredOptions) {
+        insertCascaderOption(options, option, allowRoot, separator, rootValue, normalize);
+    }
+    insertCascaderOption(options, { value: currentValue, label: titleizeSegment(currentValue, rootValue) }, allowRoot, separator, rootValue, normalize);
+    return options;
+}
+export function PhiCascaderControl({ value, options, allowRoot = true, allowClear = false, expandTrigger = "click", separator = "/", rootValue = "/", normalize = "raw", disabled = false, readOnly = false, label, placeholder, size, onChange, onFocus, onBlur, classNames, getPopupContainer, style, }) {
+    const resolvedSeparator = separator.trim() || "/";
+    const resolvedRootValue = rootValue.trim() || "/";
+    const normalizedValue = normalizePhiCascaderValue(value, {
+        separator: resolvedSeparator,
+        rootValue: resolvedRootValue,
+        normalize,
+    });
+    const [searchValue, setSearchValue] = useState("");
+    const cascaderOptions = useMemo(() => buildCascaderOptions(options ?? [], normalizedValue, allowRoot, resolvedSeparator, resolvedRootValue, normalize), [allowRoot, normalize, normalizedValue, options, resolvedRootValue, resolvedSeparator]);
+    const cascaderValue = findOptionPath(cascaderOptions, normalizedValue, resolvedSeparator, resolvedRootValue) ?? [];
+    function commit(nextValue) {
+        const normalizedNextValue = normalizePhiCascaderValue(nextValue, {
+            separator: resolvedSeparator,
+            rootValue: resolvedRootValue,
+            normalize,
+        });
+        if (!allowRoot && normalizedNextValue === resolvedRootValue) {
+            return;
+        }
+        setSearchValue("");
+        onChange?.(normalizedNextValue);
+    }
+    const control = (_jsx(Cascader, { allowClear: allowClear, changeOnSelect: true, expandTrigger: expandTrigger, rootClassName: "phi-cascader-control", disabled: disabled || readOnly || !onChange, displayRender: (_, selectedOptions) => {
+            const selectedLabels = (selectedOptions ?? [])
+                .map((option) => option.label)
+                .filter((label) => label != null);
+            // Keep the selected label non-primitive so rc-select cannot synthesize
+            // a native HTML title from the visible Cascader text.
+            return _jsx(_Fragment, { children: selectedLabels.length > 0 ? selectedLabels.join(" / ") : resolvedRootValue });
+        }, options: cascaderOptions, placeholder: placeholder, size: size, searchValue: searchValue, showSearch: true, value: cascaderValue, classNames: classNames, getPopupContainer: getPopupContainer, onFocus: onFocus, onBlur: () => {
+            if (searchValue.trim()) {
+                commit(searchValue);
+            }
+            onBlur?.();
+        }, onChange: (nextValue) => {
+            const selectedValue = Array.isArray(nextValue) ? nextValue.at(-1) : null;
+            if (typeof selectedValue === "string") {
+                commit(selectedValue);
+            }
+            else if (allowClear) {
+                setSearchValue("");
+                onChange?.(resolvedRootValue);
+            }
+        }, onKeyDown: (event) => {
+            if (event.key === "Enter" && searchValue.trim()) {
+                commit(searchValue);
+            }
+        }, onSearch: setSearchValue, style: { width: "100%", ...style } }));
+    return (_jsx(PhiLabeledControl, { label: label, fill: style?.width === undefined || style.width === "100%", children: control }));
+}

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

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+export type PhiCheckboxControlProps = {
+    checked?: boolean;
+    label?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    indeterminate?: boolean;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    onChange?: (checked: boolean) => void;
+};
+export declare function PhiCheckboxControl({ checked, label, disabled, readOnly, indeterminate, onFocus, onBlur, onChange, }: PhiCheckboxControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Checkbox } from "antd";
+export function PhiCheckboxControl({ checked, label, disabled, readOnly, indeterminate, onFocus, onBlur, onChange, }) {
+    return (_jsx(Checkbox, { checked: checked, disabled: disabled || readOnly || !onChange, indeterminate: indeterminate, onFocus: onFocus, onBlur: onBlur, onChange: (event) => onChange?.(event.target.checked), children: label }));
+}

package/components/controls/phi-checkbox-group-control.d.ts

@@ -0,0 +1,10 @@
+import type { PhiControlOption } from "./phi-control-options";
+export type PhiCheckboxGroupControlProps<TValue extends string | number = string> = {
+    value?: readonly TValue[];
+    options: readonly PhiControlOption<TValue>[];
+    disabled?: boolean;
+    readOnly?: boolean;
+    vertical?: boolean;
+    onChange?: (value: TValue[]) => void;
+};
+export declare function PhiCheckboxGroupControl<TValue extends string | number = string>({ value, options, disabled, readOnly, vertical, onChange, }: PhiCheckboxGroupControlProps<TValue>): import("react").JSX.Element;

package/components/controls/phi-checkbox-group-control.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Checkbox, Flex, Tooltip } from "antd";
+import { PhiIcon } from "../shell/phi-icon";
+export function PhiCheckboxGroupControl({ value, options, disabled, readOnly, vertical, onChange, }) {
+    return (_jsx(Checkbox.Group, { value: [...(value ?? [])], disabled: disabled || readOnly || !onChange, onChange: (nextValue) => onChange?.(nextValue), style: { width: "100%" }, children: _jsx(Flex, { vertical: vertical, gap: "small", wrap: vertical ? false : "wrap", children: options.map((option) => {
+                const content = (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: "var(--ant-padding-xxs)" }, children: [option.icon ? _jsx(PhiIcon, { name: option.icon, size: 14 }) : null, option.label] }));
+                return (_jsx(Checkbox, { value: option.value, disabled: option.disabled, children: option.description ? _jsx(Tooltip, { title: option.description, children: content }) : content }, option.value));
+            }) }) }));
+}

package/components/controls/phi-collection-header-control.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export type PhiCollectionHeaderControlProps = {
+    title?: ReactNode;
+    description?: ReactNode;
+    filters?: ReactNode;
+    toolbar?: ReactNode;
+};
+export declare function PhiCollectionHeaderControl({ title, description, filters, toolbar, }: PhiCollectionHeaderControlProps): import("react").JSX.Element | null;

package/components/controls/phi-collection-header-control.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Tooltip, Typography } from "antd";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { PHI_DESCRIPTION_TOOLTIP_ICON } from "./phi-description-tooltip-icon";
+export function PhiCollectionHeaderControl({ title, description, filters, toolbar, }) {
+    const { token } = usePhiConfig();
+    const hasTitle = title !== undefined && title !== null && title !== "";
+    const hasFilters = filters !== undefined && filters !== null;
+    const hasToolbar = toolbar !== undefined && toolbar !== null;
+    if (!hasTitle && !hasFilters && !hasToolbar)
+        return null;
+    return (_jsxs("div", { style: {
+            display: "flex",
+            alignItems: "flex-end",
+            flexWrap: "wrap",
+            gap: token.paddingSM,
+            width: "100%",
+            minWidth: 0,
+        }, children: [hasTitle ? (_jsxs("div", { style: {
+                    display: "inline-flex",
+                    alignItems: "center",
+                    gap: token.paddingXXS,
+                    flex: "0 1 auto",
+                    minWidth: 0,
+                }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: title }), description ? (_jsx(Tooltip, { title: description, children: _jsx("span", { role: "img", "aria-label": "Information", tabIndex: 0, style: {
+                                display: "inline-flex",
+                                alignItems: "center",
+                                color: token.colorTextSecondary,
+                                cursor: "help",
+                                flex: "none",
+                            }, children: PHI_DESCRIPTION_TOOLTIP_ICON }) })) : null] })) : null, hasFilters ? (_jsx("div", { style: {
+                    display: "flex",
+                    alignItems: "flex-end",
+                    flex: "1 1 280px",
+                    flexWrap: "wrap",
+                    gap: token.paddingSM,
+                    minWidth: 0,
+                }, children: filters })) : hasTitle && hasToolbar ? _jsx("span", { "aria-hidden": true, style: { flex: "1 1 auto" } }) : null, hasToolbar ? (_jsx("div", { style: {
+                    display: "flex",
+                    alignItems: "flex-end",
+                    justifyContent: "flex-end",
+                    marginInlineStart: "auto",
+                    flex: "0 0 auto",
+                }, children: toolbar })) : null] }));
+}

package/components/controls/phi-collection-layout-control.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export type PhiCollectionLayoutControlProps = {
+    mode: "grid" | "masonry" | "stack";
+    gap: string | number;
+    minColumnWidth: string | number;
+    items: ReactNode[];
+};
+export declare function PhiCollectionLayoutControl({ mode, gap, minColumnWidth, items, }: PhiCollectionLayoutControlProps): import("react").JSX.Element;