@phis/ui 0.1.0 → 0.2.1

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

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
-import { ColorPicker, Flex, Tooltip, theme } from "antd";
+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";
 const PHI_COLOR_PICKER_CONTENT_WIDTH = 234;
@@ -91,7 +92,7 @@ function resolveCssValue(nextValue, fallbackCss) {
 function resolveAntdMode(mode) {
     return mode === "both" ? ["single", "gradient"] : mode;
 }
-export function PhiColorControl({ value = null, defaultValue = "#f0f0f0", disabled, allowClear, mode = "single", open, showText = false, trigger, placement = "auto", size, children, presets = [], getPopupContainer, popupClassName, renderPanel, onChange, onCommit, onDiscard, onOpenChange, onClear, }) {
+export function PhiColorControl({ value = null, defaultValue = "#f0f0f0", disabled, allowClear, mode = "single", open, showText, trigger, placement = "auto", size, children, presets = [], getPopupContainer, popupClassName, renderPanel, onChange, onCommit, onDiscard, onOpenChange, onClear, }) {
     const { token } = theme.useToken();
     const picker = usePhiImmediatePicker({
         value,
@@ -111,18 +112,33 @@ export function PhiColorControl({ value = null, defaultValue = "#f0f0f0", disabl
     const selectedPaletteKey = selectedPalette?.key;
     const selectedPaletteLabel = selectedPalette?.label ?? selectedPaletteKey;
     const selectedCssValue = picker.value ?? defaultValue;
+    /*
+     * A single colour names itself, a gradient cannot.
+     *
+     * antd spells a gradient out stop by stop -- "rgb(22, 119, 255) 0%, rgb(255, 255, 255) 100%" -- which
+     * says less than the swatch already shows and takes a whole Inspector row to say it. So the value is
+     * written out only where it is one colour, and a caller that passes its own trigger keeps it bare.
+     */
+    const showsGradient = parseLinearGradientValue(selectedCssValue) != null;
+    const resolvedShowText = showText ?? (children == null && !showsGradient);
     const antdPresets = presets.map((preset) => ({
         key: preset.key,
         label: preset.label,
         colors: [...preset.colors],
         defaultOpen: preset.defaultOpen,
     }));
-    return (_jsx(ColorPicker, { mode: resolveAntdMode(mode), value: resolveAntdColorValue(picker.value, defaultValue), open: picker.open, disabled: disabled, allowClear: allowClear, trigger: trigger, placement: placement === "auto" ? undefined : placement, size: size, showText: showText, presets: antdPresets, getPopupContainer: getPopupContainer, classNames: { popup: { root: ["phi-color-widget-popup", popupClassName].filter(Boolean).join(" ") } }, styles: {
+    return (_jsx(ColorPicker, { mode: resolveAntdMode(mode), value: resolveAntdColorValue(picker.value, defaultValue), open: picker.open, disabled: disabled, allowClear: allowClear, trigger: trigger, placement: placement === "auto" ? undefined : placement, size: size, showText: resolvedShowText, presets: antdPresets, getPopupContainer: getPopupContainer, classNames: { popup: { root: ["phi-color-widget-popup", popupClassName].filter(Boolean).join(" ") } }, styles: {
             root: {
                 display: "inline-flex",
                 alignItems: "center",
                 lineHeight: 1,
                 maxWidth: "100%",
+                /*
+                 * A grid or flex cell stretches an item whose width is `auto`, and the swatch was taking the
+                 * whole Inspector column for it. It is a button, not a field: it is as wide as what it shows.
+                 * A caller that brings its own trigger keeps the sizing that trigger was written for.
+                 */
+                ...(children == null ? { width: "fit-content" } : {}),
             },
             popupOverlayInner: {
                 padding: 12,
@@ -138,16 +154,16 @@ export function PhiColorControl({ value = null, defaultValue = "#f0f0f0", disabl
                                     const selected = presetColor === selectedCssValue;
                                     const swatchLabel = selectedPalette.colorLabels?.[index]
                                         ?? `${selectedPaletteLabel} ${index + 1}`;
-                                    return (_jsx(Tooltip, { title: swatchLabel, children: _jsx("span", { style: { display: "inline-flex" }, children: _jsx("button", { type: "button", "aria-label": `${swatchLabel}: ${presetColor}`, "aria-pressed": selected, title: `${swatchLabel}: ${presetColor}`, disabled: disabled, onClick: () => picker.changeValue(presetColor), style: {
-                                                    width: 22,
-                                                    height: 22,
-                                                    padding: 0,
-                                                    border: `1px solid ${selected ? token.colorPrimary : token.colorBorder}`,
-                                                    borderRadius: token.borderRadiusSM,
-                                                    background: presetColor,
-                                                    boxShadow: selected ? `0 0 0 2px ${token.colorPrimaryBorder}` : undefined,
-                                                    cursor: disabled ? "not-allowed" : "pointer",
-                                                } }) }) }, `${index}-${presetColor}`));
+                                    return (_jsx(PhiLabeledControl, { description: `${swatchLabel}: ${presetColor}`, children: _jsx("button", { type: "button", "aria-label": `${swatchLabel}: ${presetColor}`, "aria-pressed": selected, disabled: disabled, onClick: () => picker.changeValue(presetColor), style: {
+                                                width: 22,
+                                                height: 22,
+                                                padding: 0,
+                                                border: `1px solid ${selected ? token.colorPrimary : token.colorBorder}`,
+                                                borderRadius: token.borderRadiusSM,
+                                                background: presetColor,
+                                                boxShadow: selected ? `0 0 0 2px ${token.colorPrimaryBorder}` : undefined,
+                                                cursor: disabled ? "not-allowed" : "pointer",
+                                            } }) }, `${index}-${presetColor}`));
                                 }) })] })) : null] }));
             return renderPanel?.(content) ?? content;
         }, onChange: (nextValue, css) => {

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

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { createPhiColorPickerPresets } from "../widgets/config/color-picker-presets";
+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 PhiColorControlCustomColor } from "./use-phi-color-control-presets";
+export type PhiColorFieldControlProps = {
+    label?: string;
+    value?: string | null;
+    defaultValue?: string;
+    /** Handed back with every change, so one handler can serve several fields. */
+    tokenKey?: string;
+    disabled?: boolean;
+    mode?: PhiColorPickerMode;
+    placement?: PhiPickerPlacement;
+    allowClear?: boolean;
+    children?: ReactNode;
+    presets?: ReturnType<typeof createPhiColorPickerPresets>;
+    getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;
+    popupClassName?: string;
+    renderPanel?: (panel: ReactNode) => ReactNode;
+    onOpenChange?: (open: boolean) => void;
+    onCommit?: (value: string | null, originalValue: string | null) => void;
+    onDiscard?: (originalValue: string | null) => void;
+    onClear?: () => void;
+    customColors?: ReadonlyArray<PhiColorControlCustomColor>;
+    labels?: PhiColorPickerLabels;
+    onChange?: (value: string, tokenKey?: string) => void;
+    onValueChange?: (value: string | null, tokenKey?: string) => void;
+};
+/**
+ * A labelled colour field: the colour primitive with the Site's presets and custom colours.
+ *
+ * A Control, so every Module may use it -- the Theme's brand controls, the Builder's Inspector, the
+ * 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;

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

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { createPhiColorPickerPresets } from "../widgets/config/color-picker-presets";
+import { PHI_COLOR_PICKER_DEFAULT_LABELS, } from "../widgets/label-types/color-picker";
+import { PhiColorControl } from "./phi-color-control";
+import { usePhiColorControlPresets, } from "./use-phi-color-control-presets";
+import { PhiFlexControl } from "./phi-flex-control";
+import { PhiTypographyControl } from "./phi-typography-control";
+/**
+ * A labelled colour field: the colour primitive with the Site's presets and custom colours.
+ *
+ * A Control, so every Module may use it -- the Theme's brand controls, the Builder's Inspector, the
+ * 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, }) {
+    const { token } = usePhiConfig();
+    const resolvedValue = value?.trim() || defaultValue;
+    const pickerPresets = usePhiColorControlPresets({ labels, customColors, presets });
+    function publish(nextValue) {
+        if (nextValue == null) {
+            onValueChange?.(null, tokenKey);
+            onClear?.();
+            return;
+        }
+        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 })] }));
+}

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

@@ -0,0 +1,38 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { PhiControlSize } from "../../types/control";
+/**
+ * Controls joined into one shape: the seam between two of them drawn once instead of twice, and only
+ * the outer corners rounded.
+ *
+ * **It has to be a wrapper around the primitive, and cannot be written here.** Ant Design does this
+ * through a React context rather than through CSS: `Space.Compact` puts `isFirstItem`, `isLastItem`,
+ * the size and the direction around each child, and ten of its components read that context and emit
+ * their own border-collapsing class names -- Button, Input, InputNumber, Select, Cascader, DatePicker,
+ * ColorPicker, Dropdown, TreeSelect. A wrapper of our own with negative margins would reach eighty per
+ * cent and then break on everything that changes a border: the focus ring, an error state, a disabled
+ * edge, an open Select. And it would break per Control, separately.
+ *
+ * **Two things look like this, and only one of them is a field.**
+ *
+ * A *compound field* is several Controls holding **one** value, joined so they read as one input: a
+ * number and its unit, a width and its style, a range with a start and an end. The seam says the parts
+ * belong to each other.
+ *
+ * A *button group* is several **separate** commands drawn as one bar -- a toolbar, a row of actions.
+ * The seam says they are peers, not that they are one thing.
+ *
+ * **It is not a layout.** Two Controls side by side with air between them is `PhiFlexControl`, and
+ * arranging Widgets is the Layout contract. Joining is for things that belong together closely enough
+ * that a gap would be a lie.
+ */
+export type PhiCompactGroupControlProps = {
+    children: ReactNode;
+    /** Fills the width it is given, for a field that is as wide as its row. */
+    block?: boolean;
+    /** Sizes every part at once, so a group cannot be assembled from mismatched heights. */
+    size?: PhiControlSize;
+    /** Stacked rather than side by side, where the seam runs horizontally. */
+    vertical?: boolean;
+    style?: CSSProperties;
+};
+export declare function PhiCompactGroupControl({ children, block, size, vertical, style, }: PhiCompactGroupControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Space } from "antd";
+export function PhiCompactGroupControl({ children, block, size, vertical, style, }) {
+    return (_jsx(Space.Compact, { block: block, size: size, vertical: vertical, style: style, children: children }));
+}

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

@@ -2,20 +2,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Popconfirm } from "antd";
 import { PhiButtonControl } from "./phi-button-control";
-export const PHI_CONFIRM_PLACEMENTS = [
-    "top",
-    "topLeft",
-    "topRight",
-    "bottom",
-    "bottomLeft",
-    "bottomRight",
-    "left",
-    "leftTop",
-    "leftBottom",
-    "right",
-    "rightTop",
-    "rightBottom",
-];
+import { PHI_POPUP_PLACEMENTS } from "./phi-picker-control-contract";
+export const PHI_CONFIRM_PLACEMENTS = PHI_POPUP_PLACEMENTS;
 export function PhiConfirmControl({ title, description, confirmLabel, cancelLabel, danger, disabled, placement, onConfirm, onCancel, trigger, children, }) {
     return (_jsx(Popconfirm, { title: title, description: description, okText: confirmLabel, cancelText: cancelLabel, okButtonProps: danger ? { danger: true } : undefined, disabled: disabled, placement: placement, onConfirm: onConfirm, onCancel: onCancel, children: trigger ? (_jsx(PhiButtonControl, { label: trigger.label, ariaLabel: trigger.ariaLabel, icon: trigger.icon, type: trigger.type, danger: trigger.danger, size: trigger.size, disabled: disabled, 
             // The confirmation reacts to the press; this only keeps the button a live one.

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

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+export type PhiConfirmDialogRequest = {
+    title: ReactNode;
+    content?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** A confirmation whose answer cannot be walked back, drawn as the danger it is. */
+    danger?: boolean;
+    onConfirm: () => void | Promise<void>;
+    onCancel?: () => void;
+};
+/**
+ * A confirmation that has nothing to hang on.
+ *
+ * `PhiConfirmControl` is the one to reach for wherever a button asks the question: a Popconfirm points
+ * at what it is about. This is for the other case -- a Widget told by a signal to run an action that
+ * needs an answer first, where there is no trigger on screen to point at, and for a command that is
+ * issued from somewhere else entirely.
+ *
+ * It exists so that case does not mean `App.useApp().modal`. Ant Design's imperative `modal` needs the
+ * `App` provider above it, and that provider carries the message, notification and modal runtimes into
+ * every first load of every page, whether or not anything ever asks one of them a question. A Control
+ * rendering a Dialog costs what it draws, and only where it is drawn.
+ *
+ * The caller renders `confirmDialog` somewhere in its own tree and calls `confirm(...)`; the Dialog
+ * closes once the answer has been carried out. A `onConfirm` that throws leaves it open, because the
+ * question was not answered -- what to say about the failure is the caller's, as it was before.
+ */
+export declare function usePhiConfirmDialog(): {
+    confirm: (next: PhiConfirmDialogRequest) => void;
+    confirmDialog: import("react").JSX.Element;
+};

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

@@ -0,0 +1,79 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useRef, useState } from "react";
+import { PhiDialogControl } from "./phi-dialog-control";
+/**
+ * A confirmation that has nothing to hang on.
+ *
+ * `PhiConfirmControl` is the one to reach for wherever a button asks the question: a Popconfirm points
+ * at what it is about. This is for the other case -- a Widget told by a signal to run an action that
+ * needs an answer first, where there is no trigger on screen to point at, and for a command that is
+ * issued from somewhere else entirely.
+ *
+ * It exists so that case does not mean `App.useApp().modal`. Ant Design's imperative `modal` needs the
+ * `App` provider above it, and that provider carries the message, notification and modal runtimes into
+ * every first load of every page, whether or not anything ever asks one of them a question. A Control
+ * rendering a Dialog costs what it draws, and only where it is drawn.
+ *
+ * The caller renders `confirmDialog` somewhere in its own tree and calls `confirm(...)`; the Dialog
+ * closes once the answer has been carried out. A `onConfirm` that throws leaves it open, because the
+ * question was not answered -- what to say about the failure is the caller's, as it was before.
+ */
+export function usePhiConfirmDialog() {
+    const [request, setRequest] = useState(null);
+    const [confirming, setConfirming] = useState(false);
+    // The question on screen right now, read by an answer that finishes after another was asked.
+    const currentRequestRef = useRef(null);
+    const close = useCallback(() => {
+        currentRequestRef.current = null;
+        setRequest(null);
+        setConfirming(false);
+    }, []);
+    const confirm = useCallback((next) => {
+        currentRequestRef.current = next;
+        setConfirming(false);
+        setRequest(next);
+    }, []);
+    const cancel = useCallback(() => {
+        request?.onCancel?.();
+        close();
+    }, [close, request]);
+    const accept = useCallback(() => {
+        if (!request || confirming)
+            return;
+        setConfirming(true);
+        void (async () => {
+            /*
+             * The answer may take a while, and a new question can be asked in the meantime. Settling then
+             * belongs to the question that was answered: closing or re-enabling would dismiss or unlock the
+             * one that replaced it.
+             */
+            try {
+                await request.onConfirm();
+                if (currentRequestRef.current === request)
+                    close();
+            }
+            catch {
+                if (currentRequestRef.current === request)
+                    setConfirming(false);
+            }
+        })();
+    }, [close, confirming, request]);
+    const confirmDialog = (_jsx(PhiDialogControl, { open: request != null, title: request?.title, centered: true, actions: request == null ? [] : [
+            {
+                key: "cancel",
+                label: request.cancelLabel ?? "Cancel",
+                disabled: confirming,
+                onClick: cancel,
+            },
+            {
+                key: "confirm",
+                label: request.confirmLabel ?? "OK",
+                type: "primary",
+                danger: request.danger,
+                loading: confirming,
+                onClick: accept,
+            },
+        ], onDismiss: cancel, children: request?.content ?? null }));
+    return { confirm, confirmDialog };
+}

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

@@ -1,5 +1,20 @@
 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.
+ *
+ * **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
+ * the description gets a deliberate target of its own. A standing option is pointed at on purpose, so the
+ * option itself carries it: the larger target, and the one a finger can hit. The chosen option carries
+ * nothing, because the hover target there belongs to the Control, not to the option. Two of these were
+ * written out a second time in the checkbox and radio groups, close enough to look identical and far
+ * enough apart to drift -- an option's icon rendered there, its preview swatch did not.
+ */
 export declare function PhiControlOptionContent<TValue extends string | number>({ option, presentation, }: {
     option: PhiControlOption<TValue>;
-    presentation: "dropdown" | "selection";
+    presentation: "dropdown" | "selection" | "option";
 }): import("react").JSX.Element;

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

@@ -3,19 +3,34 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Tooltip } from "antd";
 import { PhiIcon } from "../shell/phi-icon";
 import { usePhiConfig } from "../root/phi-config-provider";
-import { PHI_DESCRIPTION_TOOLTIP_ICON } from "./phi-description-tooltip-icon";
+import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
+/**
+ * One option, drawn the same way wherever options are drawn.
+ *
+ * `presentation` says where the option sits, not how it should look: `dropdown` is a row in an open list,
+ * `option` is an option standing on its own next to its siblings -- a checkbox, a radio -- and `selection`
+ * is the chosen one shown inside a closed Control.
+ *
+ * **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
+ * the description gets a deliberate target of its own. A standing option is pointed at on purpose, so the
+ * option itself carries it: the larger target, and the one a finger can hit. The chosen option carries
+ * nothing, because the hover target there belongs to the Control, not to the option. Two of these were
+ * written out a second time in the checkbox and radio groups, close enough to look identical and far
+ * enough apart to drift -- an option's icon rendered there, its preview swatch did not.
+ */
 export function PhiControlOptionContent({ option, presentation, }) {
     const { token } = usePhiConfig();
-    return (_jsxs("span", { style: {
-            display: "flex",
+    const standing = presentation === "option";
+    const content = (_jsxs("span", { style: {
+            display: standing ? "inline-flex" : "flex",
             alignItems: "center",
-            gap: token.paddingXS,
+            gap: standing ? token.paddingXXS : token.paddingXS,
             ...(presentation === "dropdown" ? { height: "100%", lineHeight: 1 } : {}),
             minWidth: 0,
             maxWidth: "100%",
-            overflow: "hidden",
-            whiteSpace: "nowrap",
-        }, children: [presentation === "dropdown" && option.description ? (_jsx(Tooltip, { title: option.description, children: _jsx("span", { role: "img", "aria-label": "Option description", style: { display: "inline-flex", alignItems: "center", flex: "none", color: token.colorTextTertiary }, children: PHI_DESCRIPTION_TOOLTIP_ICON }) })) : null, option.preview?.kind === "background" ? (_jsx("span", { "aria-hidden": "true", style: {
+            ...(standing ? {} : { overflow: "hidden", whiteSpace: "nowrap" }),
+        }, children: [presentation === "dropdown" && option.description ? (_jsx(PhiDescriptionHint, { description: option.description })) : null, option.preview?.kind === "background" ? (_jsx("span", { "aria-hidden": "true", style: {
                     width: 24,
                     height: 20,
                     flex: "0 0 24px",
@@ -29,9 +44,10 @@ export function PhiControlOptionContent({ option, presentation, }) {
                     backgroundRepeat: option.preview.backgroundRepeat,
                 } })) : option.icon ? (_jsx(PhiIcon, { name: option.icon, size: 14 })) : null, _jsx("span", { style: {
                     minWidth: 0,
-                    overflow: "hidden",
-                    textOverflow: "ellipsis",
-                    whiteSpace: "nowrap",
+                    ...(standing ? {} : { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }),
                     ...(option.preview?.kind === "font" ? { fontFamily: option.preview.fontFamily } : {}),
                 }, children: option.label })] }));
+    return standing && option.description
+        ? _jsx(Tooltip, { title: option.description, children: content })
+        : content;
 }

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

@@ -1,69 +1 @@
-import { type PhiRuntimeDataProviderKey } from "../../types/runtime-data-provider";
-export type PhiControlOption<TValue extends string | number = string> = {
-    value: TValue;
-    label: string;
-    disabled?: boolean;
-    description?: string;
-    icon?: string;
-    preview?: PhiControlOptionPreview;
-    /**
-     * The heading this option is listed under, where the Control can group -- a Select shows consecutive
-     * options with the same group under one heading. A Control that cannot group lists the options as they
-     * come, so the order has to make sense without the headings.
-     */
-    group?: string;
-};
-export type PhiControlOptionPreview = PhiControlOptionBackgroundPreview | PhiControlOptionFontPreview;
-/**
- * The option's label set in the typeface it names, so a list of fonts shows the fonts.
- *
- * `fontFamily` is a complete `font-family` value -- a family, its fallback, a generic -- because the
- * option is drawn in a popup outside the page's root, where a variable that names a font is not in
- * scope. Whoever builds the option resolves the variable first.
- */
-export type PhiControlOptionFontPreview = {
-    kind: "font";
-    fontFamily: string;
-};
-export type PhiControlOptionBackgroundPreview = {
-    kind: "background";
-    backgroundColor?: string;
-    backgroundImage?: string;
-    backgroundSize?: string;
-    backgroundPosition?: string;
-    backgroundRepeat?: string;
-};
-export type PhiControlOptionsProviderLoadMode = "client" | "server" | "hybrid";
-export type PhiControlOptionsProviderSearchConfig = {
-    enabled?: boolean;
-    minChars?: number;
-};
-/**
- * A value this provider needs that another field holds.
- *
- * `source` and `valuePath` are the vocabulary conditions already use, so "the value of a sibling field"
- * is said the same way everywhere. `form` reads the live form values; `config` reads the field or Widget
- * configuration the control was built from, which is what an Inspector has instead of a form.
- *
- * `required` is the difference between narrowing a list and having no list: a provider whose answer is
- * meaningless without the parent value is not asked at all until it has one, rather than answering with
- * everything and looking as if the dependency were ignored.
- */
-export type PhiControlOptionsProviderDependency = {
-    /** The name the provider reads this value under. */
-    param: string;
-    source: "form" | "config";
-    valuePath: string;
-    required?: boolean;
-};
-export type PhiControlOptionsProviderConfig = {
-    providerKey: PhiRuntimeDataProviderKey;
-    scopeKey?: string;
-    area?: string;
-    params?: Record<string, unknown>;
-    loadMode?: PhiControlOptionsProviderLoadMode;
-    search?: PhiControlOptionsProviderSearchConfig;
-    dependencies?: readonly PhiControlOptionsProviderDependency[];
-};
-export declare function parsePhiControlOptionsProviderConfig(value: unknown): PhiControlOptionsProviderConfig | null;
-export declare function readPhiControlOptions(value: unknown): PhiControlOption[];
+export { parsePhiControlOptionsProviderConfig, readPhiControlOptions, type PhiControlOption, type PhiControlOptionBackgroundPreview, type PhiControlOptionFontPreview, type PhiControlOptionPreview, type PhiControlOptionsProviderConfig, type PhiControlOptionsProviderDependency, type PhiControlOptionsProviderLoadMode, type PhiControlOptionsProviderSearchConfig, } from "@phis/contracts/controls";

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

@@ -1,112 +1,6 @@
-import { isPhiRuntimeDataProviderKey, } from "../../types/runtime-data-provider";
-function readString(value) {
-    return typeof value === "string" && value.trim().length > 0
-        ? value.trim()
-        : undefined;
-}
-function readRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
-}
-function readLoadMode(value) {
-    return value === "client" || value === "server" || value === "hybrid" ? value : undefined;
-}
-function readSearchConfig(value) {
-    const record = readRecord(value);
-    if (!record) {
-        return undefined;
-    }
-    const enabled = typeof record.enabled === "boolean" ? record.enabled : undefined;
-    const minChars = typeof record.minChars === "number" && Number.isFinite(record.minChars)
-        ? Math.max(0, Math.trunc(record.minChars))
-        : undefined;
-    if (enabled === undefined && minChars === undefined) {
-        return undefined;
-    }
-    return {
-        enabled,
-        minChars,
-    };
-}
-function readDependencies(value) {
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
-    const dependencies = value.flatMap((entry) => {
-        const record = readRecord(entry);
-        const param = readString(record?.param);
-        const valuePath = readString(record?.valuePath);
-        const source = record?.source === "form" || record?.source === "config" ? record.source : undefined;
-        if (!param || !valuePath || !source) {
-            return [];
-        }
-        return [{
-                param,
-                source,
-                valuePath,
-                required: record?.required === true ? true : undefined,
-            }];
-    });
-    return dependencies.length > 0 ? dependencies : undefined;
-}
-function readOptionPreview(value) {
-    const record = readRecord(value);
-    if (record?.kind === "font") {
-        const fontFamily = readString(record.fontFamily);
-        return fontFamily ? { kind: "font", fontFamily } : undefined;
-    }
-    if (record?.kind !== "background")
-        return undefined;
-    return {
-        kind: "background",
-        backgroundColor: readString(record.backgroundColor),
-        backgroundImage: readString(record.backgroundImage),
-        backgroundSize: readString(record.backgroundSize),
-        backgroundPosition: readString(record.backgroundPosition),
-        backgroundRepeat: readString(record.backgroundRepeat),
-    };
-}
-export function parsePhiControlOptionsProviderConfig(value) {
-    const record = readRecord(value);
-    if (!record) {
-        return null;
-    }
-    const providerKey = readString(record.providerKey);
-    if (!isPhiRuntimeDataProviderKey(providerKey)) {
-        return null;
-    }
-    return {
-        providerKey,
-        scopeKey: readString(record.scopeKey),
-        area: readString(record.area),
-        params: readRecord(record.params),
-        loadMode: readLoadMode(record.loadMode),
-        search: readSearchConfig(record.search),
-        dependencies: readDependencies(record.dependencies),
-    };
-}
-export function readPhiControlOptions(value) {
-    if (Array.isArray(value)) {
-        return value
-            .map((item) => {
-            if (!item || typeof item !== "object" || Array.isArray(item)) {
-                return null;
-            }
-            const record = item;
-            const optionValue = readString(record.value);
-            if (!optionValue) {
-                return null;
-            }
-            return {
-                value: optionValue,
-                label: readString(record.label) ?? optionValue,
-                disabled: typeof record.disabled === "boolean" ? record.disabled : undefined,
-                description: readString(record.description),
-                icon: readString(record.icon),
-                preview: readOptionPreview(record.preview),
-                group: readString(record.group),
-            };
-        })
-            .filter((item) => item != null);
-    }
-    return [];
-}
+/*
+ * What a choice control offers is stored as much as drawn: a Form field lists its options or names the
+ * provider that answers for them, and phis-server reads the field as it is stored. The shapes and their
+ * parsers are therefore `@phis/contracts/controls`.
+ */
+export { parsePhiControlOptionsProviderConfig, readPhiControlOptions, } from "@phis/contracts/controls";