@phis/ui 0.2.0 → 0.3.0

package/components/controls/phi-bullet-list-control.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import { type PhiBulletListNode, type PhiResolvedBulletListStyle } from "../widgets/shared/bullet-list-vocabulary";
+export type PhiBulletListControlProps = {
+    items: readonly PhiBulletListNode<ReactNode>[];
+    /** How the list is set (`bullet-list-vocabulary.ts`); left out, the defaults. */
+    listStyle?: PhiResolvedBulletListStyle;
+    /** How deep this list stands, 1 for the outermost; the level picks the marker. */
+    depth?: number;
+    /** A list that counts whatever its level's marker says -- a Markdown `1.` list. */
+    ordered?: boolean;
+    /** The first number of a counting list. */
+    start?: number;
+    /**
+     * The height of an entry's first line, which the marker is centred on. The text's own line by default;
+     * an entry that is a text field has the field's height instead.
+     */
+    markerLineHeight?: string;
+};
+/**
+ * A list, as the house draws one: a marker per level, entries with a box of their own or none, lines
+ * between them if asked, and lists inside entries one level down.
+ *
+ * Drawn the same on the server, in a Widget's preview and in its editor -- no hooks, no Ant Design -- so
+ * the Description's aside, a Markdown text's lists and whatever comes next are one list, set with one
+ * vocabulary (`bullet-list-vocabulary.ts`), rather than three copies that drift apart. It is a real
+ * `ul` or `ol` with `li`s: a reader that announces lists finds one.
+ *
+ * What an entry shows is the caller's: text on a page, a text field in an editor, a Markdown entry's
+ * blocks. An entry's children are the list one level below it, drawn inside the entry under its content,
+ * so they are indented by the marker and keep to the entry's box.
+ */
+export declare function PhiBulletListControl({ items, listStyle, depth, ordered, start, markerLineHeight, }: PhiBulletListControlProps): import("react").JSX.Element;

package/components/controls/phi-bullet-list-control.js

@@ -0,0 +1,73 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { PhiIcon } from "../shell/phi-icon";
+import { phiSurfaceDrawsChrome, resolvePhiSurfaceStyle } from "../../helpers/surface-style";
+import { PHI_COLOR, PHI_RADIUS, PHI_SPACE } from "../../theme/antd-css-var-contract";
+import { resolvePhiSpacingScaleValue } from "../widgets/config/spacing-options";
+import { PhiBulletListFlag, resolvePhiBulletListLevel, resolvePhiBulletListStyle, } from "../widgets/shared/bullet-list-vocabulary";
+import { hasPhiFlag } from "../../helpers/flags";
+const PHI_BULLET_LIST_MARKER_SIZE = PHI_SPACE.xs;
+const PHI_BULLET_LIST_ICON_SIZE = 14;
+function renderMarker(marker, icon, number) {
+    switch (marker) {
+        case "none":
+            return null;
+        case "number":
+            return (_jsxs("span", { style: { color: PHI_COLOR.textSecondary, fontVariantNumeric: "tabular-nums", minWidth: "1.5em", textAlign: "end" }, children: [number, "."] }));
+        case "icon":
+            // An icon marker with no icon chosen yet draws the dot, so the entries do not stand bare meanwhile.
+            if (icon) {
+                return _jsx(PhiIcon, { name: icon, size: PHI_BULLET_LIST_ICON_SIZE, style: { color: PHI_COLOR.primary } });
+            }
+            return renderMarker("dot", null, number);
+        case "dash":
+            return _jsx("span", { style: { width: PHI_SPACE.sm, height: 2, borderRadius: 1, background: PHI_COLOR.primary } });
+        case "circle":
+            return (_jsx("span", { style: {
+                    width: PHI_BULLET_LIST_MARKER_SIZE,
+                    height: PHI_BULLET_LIST_MARKER_SIZE,
+                    boxSizing: "border-box",
+                    borderRadius: "50%",
+                    border: `1.5px solid ${PHI_COLOR.primary}`,
+                } }));
+        case "dot":
+            return (_jsx("span", { style: {
+                    width: PHI_BULLET_LIST_MARKER_SIZE,
+                    height: PHI_BULLET_LIST_MARKER_SIZE,
+                    borderRadius: "50%",
+                    background: PHI_COLOR.primary,
+                } }));
+    }
+}
+/**
+ * A list, as the house draws one: a marker per level, entries with a box of their own or none, lines
+ * between them if asked, and lists inside entries one level down.
+ *
+ * Drawn the same on the server, in a Widget's preview and in its editor -- no hooks, no Ant Design -- so
+ * the Description's aside, a Markdown text's lists and whatever comes next are one list, set with one
+ * vocabulary (`bullet-list-vocabulary.ts`), rather than three copies that drift apart. It is a real
+ * `ul` or `ol` with `li`s: a reader that announces lists finds one.
+ *
+ * What an entry shows is the caller's: text on a page, a text field in an editor, a Markdown entry's
+ * blocks. An entry's children are the list one level below it, drawn inside the entry under its content,
+ * so they are indented by the marker and keep to the entry's box.
+ */
+export function PhiBulletListControl({ items, listStyle = resolvePhiBulletListStyle(null), depth = 1, ordered = false, start = 1, markerLineHeight = "1lh", }) {
+    const level = resolvePhiBulletListLevel(depth);
+    const marker = ordered ? "number" : listStyle.markers[level];
+    const gap = resolvePhiSpacingScaleValue(listStyle.gap);
+    const boxed = phiSurfaceDrawsChrome(listStyle.itemSurface);
+    const surface = resolvePhiSurfaceStyle(listStyle.itemSurface, { cornerFallback: PHI_RADIUS.base, groundLayer: false });
+    // A line between entries that have edges of their own would only double them.
+    const divided = !boxed && hasPhiFlag(listStyle.flags, PhiBulletListFlag.Dividers);
+    const ListTag = marker === "number" ? "ol" : "ul";
+    const listCss = { display: "grid", gap, margin: 0, padding: 0, listStyle: "none", width: "100%", minWidth: 0 };
+    return (_jsx(ListTag, { style: listCss, ...(ListTag === "ol" && start !== 1 ? { start } : {}), children: items.map((item, index) => (_jsxs("li", { className: surface.className, style: {
+                display: "flex",
+                alignItems: "flex-start",
+                gap: PHI_SPACE.sm,
+                minWidth: 0,
+                ...surface.style,
+                ...(boxed ? { padding: `${PHI_SPACE.sm} ${PHI_SPACE.md}` } : {}),
+                ...(divided && index > 0 ? { borderTop: `1px solid ${PHI_COLOR.borderSecondary}`, paddingTop: gap } : {}),
+            }, children: [marker === "none" ? null : (_jsx("span", { "aria-hidden": "true", style: { display: "inline-flex", alignItems: "center", justifyContent: "center", flexShrink: 0, height: markerLineHeight }, children: renderMarker(marker, listStyle.icon, start + index) })), _jsxs("div", { style: { display: "grid", gap, flex: 1, minWidth: 0 }, children: [item.content, item.children?.length ? (_jsx(PhiBulletListControl, { items: item.children, listStyle: listStyle, depth: depth + 1, markerLineHeight: markerLineHeight })) : null] })] }, index))) }));
+}

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

@@ -12,6 +12,8 @@ export type PhiControlBadgePresentation = {
 export type PhiButtonControlProps = {
     label?: ReactNode;
     ariaLabel?: string;
+    /** For a button that is a toggle -- pause and play -- whether it is on. */
+    ariaPressed?: boolean;
     /**
      * Renders the button as a link rather than a command.
      *
@@ -53,6 +55,11 @@ export type PhiButtonControlProps = {
      */
     ghost?: boolean;
     disabled?: boolean;
+    /**
+     * Shown as it is and answering nothing: no hover, no press, no click -- where `disabled` greys it out.
+     * A read-only toolbar button states something without being one to use. Its tooltip still opens.
+     */
+    readOnly?: boolean;
     loading?: boolean;
     htmlType?: ButtonProps["htmlType"];
     block?: boolean;
@@ -73,4 +80,4 @@ export type PhiButtonControlProps = {
     ref?: Ref<HTMLButtonElement | HTMLAnchorElement>;
     onClick?: () => void;
 };
-export declare function PhiButtonControl({ label, ariaLabel, href, newTab, external, tooltip, icon, type, shape, danger, ghost, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }: PhiButtonControlProps): import("react").JSX.Element;
+export declare function PhiButtonControl({ label, ariaLabel, ariaPressed, href, newTab, external, tooltip, icon, type, shape, danger, ghost, disabled, readOnly, loading, htmlType, block, size, style, badge, className, ref, onClick, }: PhiButtonControlProps): import("react").JSX.Element;

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

@@ -10,12 +10,14 @@ import { PhiHoverText } from "./phi-hover-text";
  * that draws a Button.
  */
 const PhiLazyBadge = lazy(() => import("antd/es/badge"));
-export function PhiButtonControl({ label, ariaLabel, href, newTab, external, tooltip, icon, type = "default", shape, danger, ghost, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }) {
+export function PhiButtonControl({ label, ariaLabel, ariaPressed, href, newTab, external, tooltip, icon, type = "default", shape, danger, ghost, disabled, readOnly, loading, htmlType, block, size, style, badge, className, ref, onClick, }) {
     const visibleTooltip = typeof label === "string" && typeof tooltip === "string" && label === tooltip
         ? null
         : tooltip;
-    const inert = disabled || (!onClick && !href && htmlType !== "submit");
-    const button = (_jsx(Button, { ref: ref, className: className, "aria-label": ariaLabel, type: type, shape: shape, danger: danger, ghost: ghost, disabled: inert, loading: loading, htmlType: htmlType, block: block, size: size, style: style, icon: icon, onClick: onClick, children: label }));
+    const inert = disabled || (!readOnly && !onClick && !href && htmlType !== "submit");
+    const button = (_jsx(Button, { ref: ref, className: className, "aria-label": ariaLabel, "aria-pressed": ariaPressed, type: type, shape: shape, danger: danger, ghost: ghost, disabled: inert, loading: loading, htmlType: htmlType, block: block, size: size, 
+        /* Not a pointer target at all, so the Button's own hover and press states never start. */
+        style: readOnly ? { ...style, pointerEvents: "none" } : style, "aria-disabled": readOnly || undefined, icon: icon, onClick: readOnly ? undefined : onClick, children: label }));
     /*
      * Through `PhiLink`, which is where this house decides between a client navigation and a plain
      * anchor -- and where `target="_blank"` and `rel` are one decision rather than two props that can
@@ -29,7 +31,7 @@ export function PhiButtonControl({ label, ariaLabel, href, newTab, external, too
      *
      * The colour is the Button's. A link states one, and here the Button beneath it already has.
      */
-    const linked = href && !disabled ? (_jsx(PhiLink, { href: href, ...(external === undefined ? {} : { external }), newTab: newTab, prefetch: false, style: { display: "inline-flex", color: "inherit" }, children: button })) : button;
+    const linked = href && !disabled && !readOnly ? (_jsx(PhiLink, { href: href, ...(external === undefined ? {} : { external }), newTab: newTab, prefetch: false, style: { display: "inline-flex", color: "inherit" }, children: button })) : button;
     /*
      * Rendered on the Server it is complete, and hydration waits for the chunk. Mounted in the browser before
      * the chunk is there, the Button stands without its count until it arrives.
@@ -45,6 +47,8 @@ export function PhiButtonControl({ label, ariaLabel, href, newTab, external, too
      */
     const target = inert
         ? _jsx("span", { style: { display: "inline-flex", cursor: "not-allowed" }, children: badged })
-        : badged;
+        : readOnly
+            ? _jsx("span", { style: { display: "inline-flex" }, children: badged })
+            : badged;
     return _jsx(PhiHoverText, { title: visibleTooltip, children: target });
 }

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

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

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

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

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

@@ -2,6 +2,7 @@ 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";
+import type { PhiTreeOption } from "../../types/tree";
 export type PhiCascaderNormalizeMode = "raw" | "path";
 export type PhiCascaderOption = PhiControlOption;
 export declare function normalizePhiCascaderValue(value: string | null | undefined, options?: {
@@ -30,3 +31,24 @@ export declare function PhiCascaderControl({ value, options, allowRoot, allowCle
     getPopupContainer?: CascaderProps["getPopupContainer"];
     style?: CSSProperties;
 }): import("react").JSX.Element;
+/**
+ * A Cascader over a tree that already is one, choosing several nodes at once.
+ *
+ * The Cascader above builds its tree from the paths in its values, so a value has to be a path. This one
+ * is handed the tree, and a value is whatever a node stands for -- a Page reference, which carries no
+ * path at all. Checking every child of a node stores the node instead (`SHOW_PARENT`): a parent stands
+ * for everything below it, including what is added there later, which is what checking it means.
+ *
+ * `disabled` on an option greys its own box only, so a node that cannot be chosen still opens onto the
+ * children that can.
+ */
+export declare function PhiTreeCascaderControl({ value, options, disabled, placeholder, size, onChange, getPopupContainer, style, }: {
+    value?: readonly string[];
+    options: readonly PhiTreeOption[];
+    disabled?: boolean;
+    placeholder?: string;
+    size?: PhiControlSize;
+    onChange?: (nextValue: string[]) => void;
+    getPopupContainer?: CascaderProps["getPopupContainer"];
+    style?: CSSProperties;
+}): import("react").JSX.Element;

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

@@ -1,8 +1,10 @@
 "use client";
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { Cascader } from "antd";
-import { PhiLabeledControl } from "./phi-labeled-control";
+import { PhiLabeledControl, usePhiControlLabel } from "./phi-labeled-control";
+import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
+import { usePhiConfig } from "../root/phi-config-provider";
 export function normalizePhiCascaderValue(value, options) {
     const separator = options?.separator?.trim() || "/";
     const rootValue = options?.rootValue?.trim() || "/";
@@ -103,6 +105,13 @@ function insertCascaderOption(options, option, allowRoot, separator, rootValue,
             currentOptions.push(current);
             currentOptions.sort((left, right) => String(left.label ?? "").localeCompare(String(right.label ?? "")));
         }
+        /*
+         * The option's own description lands on its own entry, also where that entry was made earlier as
+         * the parent of a deeper one -- `/shop` stands in the tree before `/shop` itself is inserted.
+         */
+        if (index === segments.length - 1 && option.description && current.description == null) {
+            current.description = option.description;
+        }
         if (index < segments.length - 1) {
             current.children = current.children ?? [];
             currentOptions = current.children;
@@ -122,6 +131,8 @@ function buildCascaderOptions(configuredOptions, currentValue, allowRoot, separa
     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 { labelId, labelledBy } = usePhiControlLabel(label);
+    const { token } = usePhiConfig();
     const resolvedSeparator = separator.trim() || "/";
     const resolvedRootValue = rootValue.trim() || "/";
     const normalizedValue = normalizePhiCascaderValue(value, {
@@ -144,14 +155,20 @@ export function PhiCascaderControl({ value, options, allowRoot = true, allowClea
         setSearchValue("");
         onChange?.(normalizedNextValue);
     }
-    const control = (_jsx(Cascader, { allowClear: allowClear, changeOnSelect: true, expandTrigger: expandTrigger, rootClassName: "phi-cascader-control", disabled: disabled || readOnly || !onChange, displayRender: (_, selectedOptions) => {
+    const control = (_jsx(Cascader, { "aria-labelledby": labelledBy, 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: () => {
+        }, options: cascaderOptions, 
+        /*
+         * A row carries its description as the hint every option list draws (`PhiControlOptionContent`):
+         * its own target before the label, so passing over the rows does not fire it. The label stays a
+         * string on the option, because the search matches and highlights it.
+         */
+        optionRender: (option) => option.description ? (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: token.paddingXS, minWidth: 0 }, children: [_jsx(PhiDescriptionHint, { description: option.description }), option.label] })) : option.label, placeholder: placeholder, size: size, searchValue: searchValue, showSearch: true, value: cascaderValue, classNames: classNames, getPopupContainer: getPopupContainer, onFocus: onFocus, onBlur: () => {
             if (searchValue.trim()) {
                 commit(searchValue);
             }
@@ -170,5 +187,45 @@ export function PhiCascaderControl({ value, options, allowRoot = true, allowClea
                 commit(searchValue);
             }
         }, onSearch: setSearchValue, style: { width: "100%", ...style } }));
-    return (_jsx(PhiLabeledControl, { label: label, fill: style?.width === undefined || style.width === "100%", children: control }));
+    return (_jsx(PhiLabeledControl, { label: label, labelId: labelId, fill: style?.width === undefined || style.width === "100%", children: control }));
+}
+/**
+ * A Cascader over a tree that already is one, choosing several nodes at once.
+ *
+ * The Cascader above builds its tree from the paths in its values, so a value has to be a path. This one
+ * is handed the tree, and a value is whatever a node stands for -- a Page reference, which carries no
+ * path at all. Checking every child of a node stores the node instead (`SHOW_PARENT`): a parent stands
+ * for everything below it, including what is added there later, which is what checking it means.
+ *
+ * `disabled` on an option greys its own box only, so a node that cannot be chosen still opens onto the
+ * children that can.
+ */
+export function PhiTreeCascaderControl({ value, options, disabled = false, placeholder, size, onChange, getPopupContainer, style, }) {
+    const { token } = usePhiConfig();
+    const { cascaderOptions, pathByValue } = useMemo(() => {
+        const paths = new Map();
+        const toCascader = (nodes, prefix) => nodes.map((node) => {
+            const path = [...prefix, node.value];
+            paths.set(node.value, path);
+            return {
+                value: node.value,
+                label: node.label,
+                description: node.description,
+                disableCheckbox: node.disabled,
+                ...(node.children?.length ? { children: toCascader(node.children, path) } : {}),
+            };
+        });
+        return { cascaderOptions: toCascader(options, []), pathByValue: paths };
+    }, [options]);
+    const cascaderValue = (value ?? []).flatMap((entry) => {
+        const path = pathByValue.get(entry);
+        return path ? [path] : [];
+    });
+    return (_jsx(Cascader, { multiple: true, showCheckedStrategy: Cascader.SHOW_PARENT, rootClassName: "phi-cascader-control", disabled: disabled || !onChange, options: cascaderOptions, optionRender: (option) => option.description ? (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: token.paddingXS, minWidth: 0 }, children: [_jsx(PhiDescriptionHint, { description: option.description }), option.label] })) : option.label, placeholder: placeholder, size: size, showSearch: true, maxTagCount: "responsive", value: cascaderValue, getPopupContainer: getPopupContainer, onChange: (next) => {
+            const values = (next ?? []).flatMap((path) => {
+                const last = Array.isArray(path) ? path.at(-1) : null;
+                return last == null ? [] : [String(last)];
+            });
+            onChange?.(values);
+        }, style: { width: "100%", ...style } }));
 }

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

@@ -0,0 +1,43 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { PhiControlSize } from "../../types/control";
+/**
+ * Sections that fold, each on its own or one at a time -- the whole surface the CollapsibleLayout needs.
+ *
+ * PhiAccordionControl is the narrow case (one open, nothing to decide); this is the wide one, and it is
+ * a Control so that the Layout describes sections and the primitive stays in this folder.
+ *
+ * It is controlled: the Layout keeps the open keys where they survive a reload and travel as a signal,
+ * and a Control keeping its own would be a second answer to the same question.
+ */
+export type PhiCollapseControlSection = {
+    key: string;
+    label: ReactNode;
+    children: ReactNode;
+    /** Render the body while folded, so what is inside keeps running. */
+    forceRender?: boolean;
+    /** Kept mounted and off the screen, rather than dropped. */
+    hidden?: boolean;
+};
+export type PhiCollapseControlProps = {
+    sections: readonly PhiCollapseControlSection[];
+    /** The open sections. With `accordion` only the first counts. */
+    openKeys: readonly string[];
+    onOpenKeysChange?: (keys: string[]) => void;
+    accordion?: boolean;
+    /** What folds a section: its whole header, only the icon, or nothing. */
+    collapsible?: "header" | "icon" | "disabled";
+    /** No ground of its own for headers and bodies. */
+    ghost?: boolean;
+    expandIconPlacement?: "start" | "end";
+    size?: PhiControlSize;
+    /**
+     * A class for every header element, owned by the caller. Code that has to tell a header click from
+     * another click tests this name rather than one the primitive happens to use.
+     */
+    headerClassName?: string;
+    headerPadding?: CSSProperties["padding"];
+    bodyPadding?: CSSProperties["padding"];
+    titleStrong?: boolean;
+    style?: CSSProperties;
+};
+export declare function PhiCollapseControl({ sections, openKeys, onOpenKeysChange, accordion, collapsible, ghost, expandIconPlacement, size, headerClassName, headerPadding, bodyPadding, titleStrong, style, }: PhiCollapseControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapse } from "antd";
+/*
+ * The grounds are square, because they are not an edge.
+ *
+ * A header and a body are the filling of whatever box the caller stands them in, and that box has
+ * already decided its corner. Rounding them a second time means the same number in two places, which
+ * drifts apart the moment one of the two gains a source the other does not have. Square, the caller's
+ * clip is the only corner there is.
+ */
+function resolveSectionStyles(titleStrong, headerPadding, bodyPadding) {
+    return {
+        header: { ...(headerPadding == null ? {} : { padding: headerPadding }), borderRadius: 0 },
+        title: titleStrong ? { fontWeight: 600 } : undefined,
+        /*
+         * No inset on top: header and body stand on one ground with no rule between them (`bordered` is
+         * always off), so the header's own bottom padding is already the space under the title. A body inset
+         * on top of it put the first line further from the title than from the panel's sides.
+         */
+        body: { ...(bodyPadding == null ? {} : { padding: bodyPadding }), paddingTop: 0, borderRadius: 0 },
+    };
+}
+export function PhiCollapseControl({ sections, openKeys, onOpenKeysChange, accordion = false, collapsible = "header", ghost = false, expandIconPlacement = "start", size, headerClassName, headerPadding, bodyPadding, titleStrong = false, style, }) {
+    return (_jsx(Collapse, { accordion: accordion, activeKey: accordion ? openKeys[0] ?? undefined : [...openKeys], 
+        // The caller's box draws the outline; what stays here is `ghost`, which decides the inside.
+        bordered: false, ghost: ghost, collapsible: collapsible, destroyOnHidden: false, expandIconPlacement: expandIconPlacement, size: size, classNames: headerClassName ? { header: headerClassName } : undefined, items: sections.map((section) => ({
+            key: section.key,
+            label: section.label,
+            collapsible,
+            forceRender: section.forceRender,
+            ...(section.hidden ? { style: { display: "none" } } : {}),
+            children: section.children,
+        })), onChange: (next) => onOpenKeysChange?.(Array.isArray(next) ? next : next ? [next] : []), styles: resolveSectionStyles(titleStrong, headerPadding, bodyPadding), style: style }));
+}

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

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Typography } from "antd";
 import { usePhiConfig } from "../root/phi-config-provider";
+import { PHI_VISUAL_ANCHOR_PART_ATTRIBUTE } from "../../types/tours";
 import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
 export function PhiCollectionHeaderControl({ title, description, filters, toolbar, }) {
     const { token } = usePhiConfig();
@@ -23,14 +24,14 @@ export function PhiCollectionHeaderControl({ title, description, filters, toolba
                     gap: token.paddingXXS,
                     flex: "0 1 auto",
                     minWidth: 0,
-                }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: title }), description ? _jsx(PhiDescriptionHint, { description: description }) : null] })) : null, hasFilters ? (_jsx("div", { style: {
+                }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: title }), description ? _jsx(PhiDescriptionHint, { description: description }) : null] })) : null, hasFilters ? (_jsx("div", { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "filters", 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: {
+                }, children: filters })) : hasTitle && hasToolbar ? _jsx("span", { "aria-hidden": true, style: { flex: "1 1 auto" } }) : null, hasToolbar ? (_jsx("div", { [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "toolbar", style: {
                     display: "flex",
                     alignItems: "flex-end",
                     justifyContent: "flex-end",

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

@@ -5,75 +5,17 @@ import { ColorPicker, Flex, theme } from "antd";
 import { PhiLabeledControl } from "./phi-labeled-control";
 import { PhiSelectControl } from "./phi-select-control";
 import { usePhiImmediatePicker } from "./use-phi-immediate-picker";
+import { readPhiCssLinearGradient } from "../../helpers/css-linear-gradient";
 const PHI_COLOR_PICKER_CONTENT_WIDTH = 234;
-function splitLinearGradientStops(input) {
-    const stops = [];
-    let current = "";
-    let depth = 0;
-    for (const char of input) {
-        if (char === "(")
-            depth += 1;
-        if (char === ")")
-            depth = Math.max(0, depth - 1);
-        if (char === "," && depth === 0) {
-            const next = current.trim();
-            if (next)
-                stops.push(next);
-            current = "";
-            continue;
-        }
-        current += char;
-    }
-    const trailing = current.trim();
-    if (trailing)
-        stops.push(trailing);
-    return stops;
-}
+/*
+ * A gradient the picker may edit is one a Background can hold: read by the Background's own reader, so
+ * the picker no longer offers corners or two-position stops that the save then refuses.
+ */
 function parseLinearGradientValue(value) {
-    const trimmed = value.trim();
-    if (!trimmed.startsWith("linear-gradient(") || !trimmed.endsWith(")")) {
-        return null;
-    }
-    const parts = splitLinearGradientStops(trimmed.slice("linear-gradient(".length, -1));
-    const hasDirection = /^(?:to\s+(?:left|right|top|bottom)(?:\s+(?:left|right|top|bottom))?|[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:deg|grad|rad|turn))$/i.test(parts[0] ?? "");
-    const stopParts = hasDirection ? parts.slice(1) : parts;
-    if (stopParts.length < 2)
-        return null;
-    const parsedStops = stopParts.map((part) => {
-        const match = part.match(/^(.+?)(?:\s+(-?(?:\d+(?:\.\d+)?|\.\d+))%)?$/);
-        if (!match)
-            return null;
-        const color = match[1]?.trim();
-        const percent = match[2] == null ? null : Number.parseFloat(match[2]);
-        if (!color || (percent != null && !Number.isFinite(percent)))
-            return null;
-        return { color, percent };
-    });
-    if (parsedStops.some((entry) => entry == null))
-        return null;
-    const colorStops = parsedStops;
-    if (colorStops[0]?.percent == null)
-        colorStops[0].percent = 0;
-    if (colorStops[colorStops.length - 1]?.percent == null) {
-        colorStops[colorStops.length - 1].percent = 100;
-    }
-    let previousPosition = 0;
-    while (previousPosition < colorStops.length - 1) {
-        let nextPosition = previousPosition + 1;
-        while (nextPosition < colorStops.length && colorStops[nextPosition]?.percent == null) {
-            nextPosition += 1;
-        }
-        const startPercent = colorStops[previousPosition]?.percent;
-        const endPercent = colorStops[nextPosition]?.percent;
-        if (startPercent == null || endPercent == null)
-            return null;
-        const intervalCount = nextPosition - previousPosition;
-        for (let index = previousPosition + 1; index < nextPosition; index += 1) {
-            colorStops[index].percent = startPercent + ((endPercent - startPercent) * (index - previousPosition)) / intervalCount;
-        }
-        previousPosition = nextPosition;
-    }
-    return colorStops;
+    const reading = readPhiCssLinearGradient(value);
+    return reading?.gradient
+        ? reading.gradient.stops.map((stop) => ({ color: stop.color, percent: stop.percent }))
+        : null;
 }
 function resolveAntdColorValue(value, fallback) {
     const resolved = value?.trim() || fallback;

package/components/controls/phi-color-field-control.d.ts

@@ -3,15 +3,20 @@ import { createPhiColorPickerPresets } from "../widgets/config/color-picker-pres
 import { type PhiColorPickerLabels } from "../widgets/label-types/color-picker";
 import { type PhiColorPickerMode } from "./phi-color-control";
 import type { PhiPickerPlacement } from "./phi-picker-control-contract";
+import type { PhiThemeTokenKey } from "../../theme/phi-theme-tokens";
 import { type PhiColorControlCustomColor } from "./use-phi-color-control-presets";
 export type PhiColorFieldControlProps = {
     label?: string;
     value?: string | null;
     defaultValue?: string;
+    /** A Theme token to fall back to instead of `defaultValue`, read live so it follows the Theme. */
+    defaultToken?: PhiThemeTokenKey;
     /** Handed back with every change, so one handler can serve several fields. */
     tokenKey?: string;
     disabled?: boolean;
     mode?: PhiColorPickerMode;
+    /** Whether the trigger writes the value out beside the swatch; left out, a single colour does. */
+    showText?: boolean;
     placement?: PhiPickerPlacement;
     allowClear?: boolean;
     children?: ReactNode;
@@ -35,4 +40,4 @@ export type PhiColorFieldControlProps = {
  * authoring tool buttons. The Color Widget is the Core Module's placement of it, which adds its config
  * and its signals.
  */
-export declare function PhiColorFieldControl({ label, value, defaultValue, tokenKey, disabled, mode, placement, allowClear, children, presets, getPopupContainer, popupClassName, renderPanel, onOpenChange, onCommit, onDiscard, onClear, customColors, labels, onChange, onValueChange, }: PhiColorFieldControlProps): import("react").JSX.Element;
+export declare function PhiColorFieldControl({ label, value, defaultValue: fixedDefaultValue, defaultToken, tokenKey, disabled, mode, showText, placement, allowClear, children, presets, getPopupContainer, popupClassName, renderPanel, onOpenChange, onCommit, onDiscard, onClear, customColors, labels, onChange, onValueChange, }: PhiColorFieldControlProps): import("react").JSX.Element;

package/components/controls/phi-color-field-control.js

@@ -15,8 +15,10 @@ import { PhiTypographyControl } from "./phi-typography-control";
  * authoring tool buttons. The Color Widget is the Core Module's placement of it, which adds its config
  * and its signals.
  */
-export function PhiColorFieldControl({ label, value, defaultValue = "#1677ff", tokenKey, disabled = false, mode = "single", placement, allowClear, children, presets, getPopupContainer, popupClassName, renderPanel, onOpenChange, onCommit, onDiscard, onClear, customColors, labels = PHI_COLOR_PICKER_DEFAULT_LABELS, onChange, onValueChange, }) {
+export function PhiColorFieldControl({ label, value, defaultValue: fixedDefaultValue = "#1677ff", defaultToken, tokenKey, disabled = false, mode = "single", showText, placement, allowClear, children, presets, getPopupContainer, popupClassName, renderPanel, onOpenChange, onCommit, onDiscard, onClear, customColors, labels = PHI_COLOR_PICKER_DEFAULT_LABELS, onChange, onValueChange, }) {
     const { token } = usePhiConfig();
+    const tokenValue = defaultToken ? token[defaultToken] : undefined;
+    const defaultValue = typeof tokenValue === "string" ? tokenValue : fixedDefaultValue;
     const resolvedValue = value?.trim() || defaultValue;
     const pickerPresets = usePhiColorControlPresets({ labels, customColors, presets });
     function publish(nextValue) {
@@ -28,5 +30,5 @@ export function PhiColorFieldControl({ label, value, defaultValue = "#1677ff", t
         onChange?.(nextValue, tokenKey);
         onValueChange?.(nextValue, tokenKey);
     }
-    return (_jsxs(PhiFlexControl, { vertical: true, gap: token.paddingXXS, align: "flex-start", style: { width: children ? "auto" : "100%", minWidth: 0, maxWidth: "100%" }, children: [label ? (_jsx(PhiTypographyControl, { type: "secondary", style: { fontSize: token.fontSizeSM }, children: label })) : null, _jsx(PhiColorControl, { mode: mode, placement: placement, disabled: disabled, allowClear: allowClear, value: resolvedValue, defaultValue: defaultValue, getPopupContainer: getPopupContainer, popupClassName: popupClassName, renderPanel: renderPanel, onOpenChange: onOpenChange, onCommit: onCommit, onDiscard: onDiscard, presets: pickerPresets, onChange: publish, children: children })] }));
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: token.paddingXXS, align: "flex-start", style: { width: children ? "auto" : "100%", minWidth: 0, maxWidth: "100%" }, children: [label ? (_jsx(PhiTypographyControl, { type: "secondary", style: { fontSize: token.fontSizeSM }, children: label })) : null, _jsx(PhiColorControl, { mode: mode, showText: showText, placement: placement, disabled: disabled, allowClear: allowClear, value: resolvedValue, defaultValue: defaultValue, getPopupContainer: getPopupContainer, popupClassName: popupClassName, renderPanel: renderPanel, onOpenChange: onOpenChange, onCommit: onCommit, onDiscard: onDiscard, presets: pickerPresets, onChange: publish, children: children })] }));
 }

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

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-export type PhiConfirmDialogRequest = {
+type PhiConfirmDialogRequest = {
     title: ReactNode;
     content?: ReactNode;
     confirmLabel?: string;
@@ -30,3 +30,4 @@ export declare function usePhiConfirmDialog(): {
     confirm: (next: PhiConfirmDialogRequest) => void;
     confirmDialog: import("react").JSX.Element;
 };
+export {};

package/components/controls/phi-control-option-content.d.ts

@@ -3,8 +3,12 @@ import type { PhiControlOption } from "./phi-control-options";
  * 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
@@ -16,5 +20,5 @@ import type { PhiControlOption } from "./phi-control-options";
  */
 export declare function PhiControlOptionContent<TValue extends string | number>({ option, presentation, }: {
     option: PhiControlOption<TValue>;
-    presentation: "dropdown" | "selection" | "option";
+    presentation: "dropdown" | "tree" | "selection" | "option";
 }): import("react").JSX.Element;