nudge-ui 0.2.0

package/dist/inspector/tokens/tokenEdits.d.ts

@@ -0,0 +1,3 @@
+import type { TokenChangeRecord } from "../changes/changesLog.js";
+import type { TokenCatalogRow } from "./catalog.js";
+export declare function setGlobalTokenValue(row: TokenCatalogRow, value: string): TokenChangeRecord | null;

package/dist/inspector/tokens/tokenEdits.js

@@ -0,0 +1,22 @@
+import { appendChange } from "../changes/changesLog.js";
+export function setGlobalTokenValue(row, value) {
+    const nextValue = value.trim();
+    if (!row.activeDeclaration || !nextValue)
+        return null;
+    const record = {
+        kind: "token",
+        tokenName: row.definition.cssName,
+        file: row.file,
+        line: row.line,
+        selector: row.selector,
+        property: row.definition.cssName,
+        rawValue: nextValue,
+        oldRawValue: row.authoredValue,
+        important: row.activeDeclaration.important,
+        context: row.styleContext,
+        contextLabel: row.contextLabel,
+        source: { file: row.file, line: row.line, component: "Global token" },
+    };
+    appendChange(record);
+    return record;
+}

package/dist/inspector/tokens/valueSemanticsAdapter.d.ts

@@ -0,0 +1,6 @@
+import type { TokenEntry } from "../../css/model/index.js";
+import type { TokenOrigin, TokenTable } from "../../css/model/index.js";
+import type { Directionality, ValueSemanticsContext } from "../../css/value-semantics/index.js";
+export declare function inspectorTokenOrigin(entry: TokenEntry | undefined): TokenOrigin;
+/** Inspector Adapter for framework-specific token attribution facts. */
+export declare function createInspectorValueContext(tokenTable: TokenTable, localAliases?: ReadonlyMap<string, string>, directionality?: Directionality): ValueSemanticsContext;

package/dist/inspector/tokens/valueSemanticsAdapter.js

@@ -0,0 +1,68 @@
+const EMPTY_LOCAL_ALIASES = new Map();
+export function inspectorTokenOrigin(entry) {
+    if (!entry)
+        return "runtime";
+    if (entry.origin)
+        return entry.origin;
+    if (entry.adapter === "tailwind-v3" || entry.adapter === "tailwind-v4")
+        return "framework";
+    return "project";
+}
+function colorTuple(value) {
+    const trimmed = value.trim().toLowerCase().replace(/\s*\/\s*var\([^)]*\)/, "");
+    const hex = /^#([\da-f]{3}|[\da-f]{6})$/.exec(trimmed);
+    if (hex) {
+        const raw = hex[1];
+        const expanded = raw.length === 3 ? raw.split("").map((part) => part + part).join("") : raw;
+        return [expanded.slice(0, 2), expanded.slice(2, 4), expanded.slice(4, 6)]
+            .map((part) => Number.parseInt(part, 16))
+            .join(",");
+    }
+    const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(trimmed);
+    return rgb ? [rgb[1], rgb[2], rgb[3]].map((part) => String(Math.round(Number(part)))).join(",") : null;
+}
+function directFrameworkColor(value, tokenTable) {
+    const tuple = colorTuple(value);
+    if (!tuple)
+        return undefined;
+    return Object.values(tokenTable).find((entry) => entry.adapter === "tailwind-v3" && colorTuple(entry.value) === tuple);
+}
+function twLocalAliasPolicy(ref, inner) {
+    if (!ref.startsWith("--tw-")) {
+        return {
+            known: true,
+            tokenName: ref,
+            resolvedValue: inner.resolvedValue,
+            leafTokenName: inner.leafTokenName ?? ref,
+            cycle: inner.cycle,
+        };
+    }
+    return inner.tokenName
+        ? {
+            known: true,
+            tokenName: inner.tokenName,
+            resolvedValue: inner.resolvedValue,
+            leafTokenName: inner.leafTokenName ?? null,
+            cycle: inner.cycle,
+        }
+        : {
+            known: false,
+            tokenName: null,
+            resolvedValue: `var(${ref})`,
+            leafTokenName: null,
+            cycle: inner.cycle,
+        };
+}
+/** Inspector Adapter for framework-specific token attribution facts. */
+export function createInspectorValueContext(tokenTable, localAliases = EMPTY_LOCAL_ALIASES, directionality) {
+    return {
+        tokenContext: {
+            table: tokenTable,
+            localAliases,
+            resolveDirectToken: (value) => directFrameworkColor(value, tokenTable),
+            resolveOrigin: inspectorTokenOrigin,
+            resolveAlias: twLocalAliasPolicy,
+        },
+        ...(directionality ? { directionality } : {}),
+    };
+}

package/dist/inspector/ui/AtRuleContext.d.ts

@@ -0,0 +1,18 @@
+import type { ReactElement, ReactNode } from "react";
+import type { AtRuleCandidate, AtRuleContext, ResolvedProperty } from "../../css/model/index.js";
+export interface AtRuleContextProviderProps {
+    rows: readonly ResolvedProperty[];
+    children?: ReactNode;
+}
+/**
+ * Makes the active conditional source context available to fields that only
+ * receive a property name (not their resolved property row) as props.
+ */
+export declare function AtRuleContextProvider({ rows, children }: AtRuleContextProviderProps): ReactElement;
+export declare function useFieldAtRules(property: string): readonly AtRuleCandidate[];
+export interface AtRuleIndicatorProps {
+    atRules?: readonly (AtRuleContext | AtRuleCandidate)[];
+    className?: string;
+}
+/** Compact, field-level attribution for the conditional rule that currently wins. */
+export declare function AtRuleIndicator({ atRules, className }: AtRuleIndicatorProps): ReactElement | null;

package/dist/inspector/ui/AtRuleContext.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { Tooltip } from "@base-ui/react/tooltip";
+const EMPTY_AT_RULES = [];
+const FieldAtRuleContext = createContext(new Map());
+/**
+ * Makes the active conditional source context available to fields that only
+ * receive a property name (not their resolved property row) as props.
+ */
+export function AtRuleContextProvider({ rows, children }) {
+    const atRulesByProperty = useMemo(() => {
+        const next = new Map();
+        for (const row of rows) {
+            if (row.atRuleCandidates?.length) {
+                next.set(row.property, row.atRuleCandidates);
+            }
+            else if (row.atRules?.length) {
+                next.set(row.property, row.atRules.map((atRule) => ({ ...atRule, active: true })));
+            }
+        }
+        return next;
+    }, [rows]);
+    return (_jsx(FieldAtRuleContext.Provider, { value: atRulesByProperty, children: children }));
+}
+export function useFieldAtRules(property) {
+    return useContext(FieldAtRuleContext).get(property) ?? EMPTY_AT_RULES;
+}
+function labelFor(atRules) {
+    const kinds = Array.from(new Set(atRules.map((atRule) => atRule.kind)));
+    if (kinds.length === 1) {
+        if (kinds[0] === "media")
+            return "Media query";
+        if (kinds[0] === "container")
+            return "Container query";
+        return "Feature query";
+    }
+    return "Conditional query";
+}
+function countLabel(label, count) {
+    const noun = label.toLowerCase().replace(/query$/, count === 1 ? "query" : "queries");
+    return `${count} ${noun}`;
+}
+function portalContainer() {
+    return document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body;
+}
+/** Compact, field-level attribution for the conditional rule that currently wins. */
+export function AtRuleIndicator({ atRules = EMPTY_AT_RULES, className }) {
+    if (atRules.length === 0)
+        return null;
+    const label = labelFor(atRules);
+    const activeCount = atRules.filter((atRule) => !("active" in atRule) || atRule.active).length;
+    const count = countLabel(label, atRules.length);
+    return (_jsx(Tooltip.Provider, { children: _jsxs(Tooltip.Root, { disableHoverablePopup: true, children: [_jsx(Tooltip.Trigger, { type: "button", delay: 0, className: `at-rule-indicator${className ? ` ${className}` : ""}`, "data-test": "at-rule-indicator", "aria-label": activeCount > 0 ? `Active ${count}` : count, children: _jsx("span", { className: "at-rule-indicator__symbol", "aria-hidden": "true", children: atRules.length }) }), _jsx(Tooltip.Portal, { container: portalContainer(), children: _jsx(Tooltip.Positioner, { className: "at-rule-tooltip-positioner", side: "top", align: "end", sideOffset: 7, children: _jsx(Tooltip.Popup, { className: "at-rule-tooltip", "data-test": "at-rule-tooltip", children: _jsx("div", { className: "at-rule-tooltip__rules", children: atRules.map((atRule, index) => (_jsx("div", { className: `at-rule-tooltip__rule${!("active" in atRule) || atRule.active ? " at-rule-tooltip__rule--active" : ""}`, "data-active": !("active" in atRule) || atRule.active ? "true" : "false", children: _jsx("code", { children: atRule.params }) }, `${atRule.kind}-${atRule.params}-${index}`))) }) }) }) })] }) }));
+}

package/dist/inspector/ui/Button.d.ts

@@ -0,0 +1,9 @@
+import type { ButtonHTMLAttributes, ReactElement } from "react";
+export type ButtonVariant = "primary" | "secondary" | "quiet" | "danger" | "disabled";
+export type ButtonSize = "default" | "compact";
+export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    "data-test"?: string;
+};
+export declare function Button({ variant, size, className, ...props }: ButtonProps): ReactElement;

package/dist/inspector/ui/Button.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Button({ variant = "secondary", size = "default", className, ...props }) {
+    return (_jsx("button", { ...props, className: `button button--${variant} button--${size}${className ? ` ${className}` : ""}` }));
+}

package/dist/inspector/ui/ColorSwatch.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+export interface ColorSwatchProps {
+    color: string;
+    className?: string;
+    "data-test"?: string;
+}
+export declare function ColorSwatch({ color, className, "data-test": dataTest }: ColorSwatchProps): ReactElement;

package/dist/inspector/ui/ColorSwatch.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ColorSwatch({ color, className, "data-test": dataTest }) {
+    return (_jsx("span", { className: `color-swatch${className ? ` ${className}` : ""}`, "data-test": dataTest, 
+        // SAFETY: React CSSProperties permits custom properties through index signatures; only --swatch-color is set.
+        style: { "--swatch-color": color || "transparent" }, "aria-hidden": "true" }));
+}

package/dist/inspector/ui/ControlSurface.d.ts

@@ -0,0 +1,14 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from "react";
+/**
+ * Visual boundary for an inspector control. It owns the shared control chrome
+ * while the child owns its particular input or selection behaviour.
+ */
+export type ControlAppearance = "default" | "embedded";
+export type ControlDensity = "default" | "compact";
+export interface ControlSurfaceProps extends HTMLAttributes<HTMLSpanElement> {
+    appearance?: ControlAppearance;
+    density?: ControlDensity;
+    "data-test"?: string;
+    children?: ReactNode;
+}
+export declare function ControlSurface({ appearance, density, className, children, ...props }: ControlSurfaceProps): ReactElement;

package/dist/inspector/ui/ControlSurface.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ControlSurface({ appearance = "default", density = "default", className, children, ...props }) {
+    const classes = [
+        "control-surface",
+        appearance === "embedded" ? "control-surface--embedded" : "",
+        density === "compact" ? "control-surface--compact" : "",
+        className ?? "",
+    ].filter(Boolean).join(" ");
+    return _jsx("span", { ...props, className: classes, children: children });
+}

package/dist/inspector/ui/FieldRow.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode, ReactElement } from "react";
+import type { AtRuleContext } from "../../css/model/index.js";
+export interface FieldRowProps {
+    label: ReactNode;
+    children: ReactNode;
+    action?: ReactNode;
+    hint?: ReactNode;
+    hideLabel?: boolean;
+    property?: string;
+    atRules?: readonly AtRuleContext[];
+    className?: string;
+    "data-test"?: string;
+}
+export declare function FieldRow({ label, children, action, hint, hideLabel, property, atRules, className, "data-test": dataTest }: FieldRowProps): ReactElement;

package/dist/inspector/ui/FieldRow.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatInspectorLabel } from "./labels.js";
+import { AtRuleIndicator, useFieldAtRules } from "./AtRuleContext.js";
+export function FieldRow({ label, children, action, hint, hideLabel = false, property, atRules, className, "data-test": dataTest }) {
+    const displayLabel = typeof label === "string" ? formatInspectorLabel(label) : label;
+    const inheritedAtRules = useFieldAtRules(property ?? "");
+    const fieldAtRules = atRules ?? inheritedAtRules;
+    const hasAtRules = fieldAtRules.length > 0;
+    const rowClassName = [
+        "field-row",
+        action ? "field-row--has-action" : "",
+        className ?? "",
+    ].filter(Boolean).join(" ");
+    return (_jsxs("label", { className: rowClassName, "data-test": dataTest, children: [_jsx("span", { className: `field-row__label${hideLabel ? " field-row__label--hidden" : ""}`, children: displayLabel }), _jsxs("span", { className: "field-row__control", "data-has-at-rule": hasAtRules ? "true" : undefined, children: [children, _jsx(AtRuleIndicator, { atRules: fieldAtRules }), hint ? _jsx("span", { className: "field-row__hint", children: hint }) : null] }), action ? _jsx("span", { className: "field-row__action", children: action }) : null] }));
+}

package/dist/inspector/ui/IconButton.d.ts

@@ -0,0 +1,14 @@
+import type { ButtonHTMLAttributes } from "react";
+import type { ButtonSize, ButtonVariant } from "./Button.js";
+export type IconButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    label: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    "data-test"?: string;
+};
+export declare const IconButton: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
+    label: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    "data-test"?: string;
+} & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/inspector/ui/IconButton.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+export const IconButton = forwardRef(function IconButton({ label, variant = "secondary", size = "default", className, ...props }, ref) {
+    return (_jsx("button", { ref: ref, ...props, type: props.type ?? "button", "aria-label": label, className: `icon-button icon-button--${variant} icon-button--${size}${className ? ` ${className}` : ""}` }));
+});

package/dist/inspector/ui/InspectorPopover.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement, ReactNode } from "react";
+export interface InspectorPopoverProps {
+    triggerElement: ReactElement;
+    children: ReactNode;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    sideOffset?: number;
+    "data-test"?: string;
+}
+/**
+ * Base UI popover anchored inside the inspector shadow root. Unlike the
+ * listbox popover, this leaves the popup content to the caller for compound
+ * settings panels and field controls.
+ */
+export declare function InspectorPopover({ triggerElement, children, open, onOpenChange, side, align, sideOffset, "data-test": dataTest, }: InspectorPopoverProps): ReactElement;

package/dist/inspector/ui/InspectorPopover.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Popover as BasePopover } from "@base-ui/react/popover";
+/**
+ * Base UI popover anchored inside the inspector shadow root. Unlike the
+ * listbox popover, this leaves the popup content to the caller for compound
+ * settings panels and field controls.
+ */
+export function InspectorPopover({ triggerElement, children, open, onOpenChange, side = "bottom", align = "center", sideOffset = 6, "data-test": dataTest, }) {
+    const portalContainer = typeof document !== "undefined"
+        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
+        : null;
+    return (_jsxs(BasePopover.Root, { open: open, onOpenChange: onOpenChange, children: [_jsx(BasePopover.Trigger, { render: triggerElement, "data-test": dataTest }), _jsx(BasePopover.Portal, { container: portalContainer, children: _jsx(BasePopover.Positioner, { className: "inspector-popover__positioner", side: side, align: align, sideOffset: sideOffset, children: _jsx(BasePopover.Popup, { className: "inspector-popover__popup", "data-test": dataTest ? `${dataTest}-popover` : undefined, children: children }) }) })] }));
+}

package/dist/inspector/ui/PopoverListbox.d.ts

@@ -0,0 +1,37 @@
+import type { FocusEventHandler, KeyboardEventHandler, ReactElement, ReactNode, Ref } from "react";
+import type { ControlAppearance } from "./ControlSurface.js";
+export interface PopoverListboxItem {
+    value: string;
+    label: string;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    "data-test"?: string;
+}
+export interface PopoverListboxProps {
+    value?: string | null;
+    query: string;
+    items: PopoverListboxItem[];
+    open: boolean;
+    trigger?: ReactNode;
+    triggerElement?: ReactElement;
+    triggerClassName?: string;
+    triggerDataTest?: string;
+    triggerAriaLabel?: string;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    searchAriaLabel?: string;
+    placeholder?: string;
+    inputRef?: Ref<HTMLInputElement>;
+    inputClassName?: string;
+    inputAppearance?: ControlAppearance;
+    inputDataTest?: string;
+    inputOnFocus?: FocusEventHandler<HTMLInputElement>;
+    inputOnBlur?: FocusEventHandler<HTMLInputElement>;
+    inputOnKeyDown?: KeyboardEventHandler<HTMLInputElement>;
+    disabled?: boolean;
+    className?: string;
+    onQueryChange: (query: string) => void;
+    onOpenChange: (open: boolean) => void;
+    onSelect: (value: string) => void;
+}
+export declare function PopoverListbox({ value, query, items, open, trigger, triggerElement, triggerClassName, triggerDataTest, triggerAriaLabel, searchable, searchPlaceholder, searchAriaLabel, placeholder, inputRef, inputClassName, inputAppearance, inputDataTest, inputOnFocus, inputOnBlur, inputOnKeyDown, disabled, className, onQueryChange, onOpenChange, onSelect, }: PopoverListboxProps): ReactElement;

package/dist/inspector/ui/PopoverListbox.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Combobox } from "@base-ui/react/combobox";
+import { Autocomplete } from "@base-ui/react/autocomplete";
+export function PopoverListbox({ value = null, query, items, open, trigger, triggerElement, triggerClassName, triggerDataTest, triggerAriaLabel, searchable = false, searchPlaceholder = "Search…", searchAriaLabel = "Search options", placeholder, inputRef, inputClassName, inputAppearance = "default", inputDataTest, inputOnFocus, inputOnBlur, inputOnKeyDown, disabled = false, className, onQueryChange, onOpenChange, onSelect, }) {
+    const portalContainer = typeof document !== "undefined"
+        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
+        : null;
+    const itemByValue = new Map(items.map((item) => [item.value, item]));
+    function renderComboboxItem(item) {
+        return (_jsxs(Combobox.Item, { value: item.value, className: "popover-listbox__item", "data-test": item["data-test"], children: [item.leading ? _jsx("span", { className: "popover-listbox__leading", children: item.leading }) : null, _jsx("span", { className: "popover-listbox__label", children: item.label }), item.trailing ? _jsx("span", { className: "popover-listbox__trailing", children: item.trailing }) : null] }, item.value));
+    }
+    return (_jsx("div", { className: `popover-listbox${className ? ` ${className}` : ""}`, children: trigger || triggerElement ? (_jsxs(Combobox.Root, { value: value, inputValue: searchable ? undefined : query, open: open, items: items.map((item) => item.value), filteredItems: searchable ? undefined : items.map((item) => item.value), autoHighlight: true, itemToStringLabel: (item) => itemByValue.get(item)?.label ?? item, onInputValueChange: (next) => onQueryChange(next), onOpenChange: (next) => onOpenChange(next), onValueChange: (next) => {
+                if (typeof next === "string")
+                    onSelect(next);
+            }, children: [triggerElement ? (_jsx(Combobox.Trigger, { render: triggerElement, className: `popover-listbox__trigger${triggerClassName ? ` ${triggerClassName}` : ""}`, "data-test": triggerDataTest, "aria-label": triggerAriaLabel, disabled: disabled })) : (_jsx(Combobox.Trigger, { className: `popover-listbox__trigger${triggerClassName ? ` ${triggerClassName}` : ""}`, "data-test": triggerDataTest, "aria-label": triggerAriaLabel, disabled: disabled, children: trigger })), _jsx(Combobox.Portal, { container: portalContainer, children: _jsx(Combobox.Positioner, { className: "popover-listbox__positioner", children: _jsxs(Combobox.Popup, { className: `popover-listbox__popup${searchable ? " popover-listbox__popup--searchable" : ""}`, children: [searchable ? (_jsxs(_Fragment, { children: [_jsx(Combobox.Input, { className: "popover-listbox__search-input", placeholder: searchPlaceholder, "aria-label": searchAriaLabel, "data-test": triggerDataTest ? `${triggerDataTest}-search` : "popover-listbox-search" }), _jsx(Combobox.Empty, { className: "popover-listbox__empty", children: "No matching options." })] })) : null, _jsx(Combobox.List, { className: `popover-listbox__list${searchable ? " popover-listbox__list--searchable" : ""}`, children: searchable
+                                        ? ((itemValue) => {
+                                            const item = itemByValue.get(itemValue);
+                                            return item ? renderComboboxItem(item) : null;
+                                        })
+                                        : items.map((item) => renderComboboxItem(item)) })] }) }) })] })) : (_jsxs(Autocomplete.Root, { value: query, open: open, items: items.map((item) => item.value), filteredItems: items.map((item) => item.value), autoHighlight: true, mode: "none", openOnInputClick: true, onValueChange: onQueryChange, onOpenChange: (next) => onOpenChange(next), children: [_jsx(Autocomplete.Input, { ref: inputRef, className: `text-input${inputAppearance === "embedded" ? " text-input--embedded" : ""}${inputClassName ? ` ${inputClassName}` : ""}`, placeholder: placeholder, "data-test": inputDataTest, onFocus: inputOnFocus, onBlur: inputOnBlur, onKeyDownCapture: inputOnKeyDown, disabled: disabled }), _jsx(Autocomplete.Portal, { container: portalContainer, children: _jsx(Autocomplete.Positioner, { className: "popover-listbox__positioner", children: _jsx(Autocomplete.Popup, { className: "popover-listbox__popup", children: _jsx(Autocomplete.List, { className: "popover-listbox__list", children: items.map((item) => (_jsxs(Autocomplete.Item, { value: item.value, className: "popover-listbox__item", "data-test": item["data-test"], onClick: () => onSelect(item.value), children: [item.leading ? _jsx("span", { className: "popover-listbox__leading", children: item.leading }) : null, _jsx("span", { className: "popover-listbox__label", children: item.label }), item.trailing ? _jsx("span", { className: "popover-listbox__trailing", children: item.trailing }) : null] }, item.value))) }) }) }) })] })) }));
+}

package/dist/inspector/ui/SegmentedControl.d.ts

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from "react";
+export interface SegmentedControlOption<T extends string> {
+    value: T;
+    /** Accessible name; also the visible label when `icon` is omitted. */
+    label: string;
+    icon?: ReactNode;
+    testId?: string;
+}
+interface SegmentedControlProps<T extends string> {
+    value: T | null;
+    options: readonly SegmentedControlOption<T>[];
+    onChange: (value: T) => void;
+    "aria-label": string;
+    "data-test"?: string;
+    "data-property"?: string;
+    className?: string;
+    /** Allows the active option to be cleared by clicking it again. */
+    allowDeselect?: boolean;
+    /** Restores the value represented by an unselected control. */
+    onDeselect?: () => void;
+}
+/** A compact single-choice control for adjacent, peer actions. */
+export declare function SegmentedControl<T extends string>({ value, options, onChange, "aria-label": ariaLabel, "data-test": dataTest, "data-property": dataProperty, className, allowDeselect, onDeselect, }: SegmentedControlProps<T>): ReactElement;
+export {};

package/dist/inspector/ui/SegmentedControl.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Toggle } from "@base-ui/react/toggle";
+/** A compact single-choice control for adjacent, peer actions. */
+export function SegmentedControl({ value, options, onChange, "aria-label": ariaLabel, "data-test": dataTest, "data-property": dataProperty, className, allowDeselect = false, onDeselect, }) {
+    return (_jsx("div", { className: `segmented-control${className ? ` ${className}` : ""}`, role: "group", "aria-label": ariaLabel, "data-test": dataTest, "data-property": dataProperty, children: options.map((option) => {
+            const selected = option.value === value;
+            return (_jsx(Toggle, { type: "button", className: `button segmented-control__button${selected ? " segmented-control__button--selected" : ""}`, pressed: selected, "aria-label": option.label, title: option.label, "data-test": option.testId, "data-active": selected ? "true" : "false", onPressedChange: (pressed) => {
+                    if (pressed) {
+                        onChange(option.value);
+                    }
+                    else if (allowDeselect) {
+                        onDeselect?.();
+                    }
+                }, children: option.icon ?? _jsx("span", { className: "segmented-control__label", children: option.label }) }, option.value));
+        }) }));
+}

package/dist/inspector/ui/Select.d.ts

@@ -0,0 +1,25 @@
+import type { ButtonHTMLAttributes, ReactElement } from "react";
+import type { ControlAppearance } from "./ControlSurface.js";
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface SelectGroup {
+    label: string;
+    options: SelectOption[];
+}
+export type SelectProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> & {
+    value?: string;
+    options?: SelectOption[];
+    groups?: SelectGroup[];
+    placeholder?: string;
+    compact?: boolean;
+    appearance?: ControlAppearance;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    searchAriaLabel?: string;
+    onValueChange?: (value: string) => void;
+    "data-test"?: string;
+};
+export declare function Select(props: SelectProps): ReactElement;

package/dist/inspector/ui/Select.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Select as BaseSelect } from "@base-ui/react/select";
+import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
+import { IconCheck, IconChevronDown } from "@tabler/icons-react";
+export function Select(props) {
+    if (props.searchable)
+        return _jsx(SearchableSelect, { ...props });
+    return _jsx(NativeSelect, { ...props });
+}
+function NativeSelect({ value, options = [], groups = [], placeholder, compact, appearance = "default", searchable: _searchable, searchPlaceholder: _searchPlaceholder, searchAriaLabel: _searchAriaLabel, className, disabled, children, ...props }) {
+    const allOptions = [...options, ...groups.flatMap((group) => group.options)];
+    const selectedOption = allOptions.find((option) => option.value === value);
+    const portalContainer = typeof document !== "undefined"
+        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
+        : null;
+    function handleValueChange(next) {
+        if (typeof next === "string")
+            props.onValueChange?.(next);
+    }
+    const { onValueChange: _onValueChange, ...triggerProps } = props;
+    return (_jsxs(BaseSelect.Root, { value: value || null, disabled: disabled, items: allOptions.map((option) => ({ value: option.value, label: option.label })), onValueChange: handleValueChange, children: [_jsxs(BaseSelect.Trigger, { ...triggerProps, disabled: disabled, className: `select${compact ? " select--compact" : ""}${appearance === "embedded" ? " select--embedded" : ""}${className ? ` ${className}` : ""}`, children: [_jsx(BaseSelect.Value, { className: "select__value", placeholder: placeholder, children: selectedOption?.label ?? (value || undefined) }), _jsx(BaseSelect.Icon, { className: "select__icon", children: _jsx(IconChevronDown, { size: 15, stroke: 1.8, "aria-hidden": "true" }) }), children] }), _jsx(BaseSelect.Portal, { container: portalContainer, children: _jsx(BaseSelect.Positioner, { className: "select__positioner", sideOffset: 4, children: _jsx(BaseSelect.Popup, { className: "select__popup", children: _jsxs(BaseSelect.List, { className: "select__list", children: [options.map((option) => _jsx(SelectItem, { option: option }, option.value)), groups.map((group) => (_jsxs(BaseSelect.Group, { className: "select__group", children: [_jsx(BaseSelect.GroupLabel, { className: "select__group-label", children: group.label }), group.options.map((option) => _jsx(SelectItem, { option: option }, `${group.label}-${option.value}`))] }, group.label)))] }) }) }) })] }));
+}
+function SearchableSelect({ value, options = [], groups = [], placeholder, compact, appearance = "default", searchable: _searchable, searchPlaceholder = "Search…", searchAriaLabel = "Search options", className, disabled, children, "data-test": dataTest, ...props }) {
+    const allOptions = [...options, ...groups.flatMap((group) => group.options)];
+    const selectedOption = allOptions.find((option) => option.value === value);
+    const optionByValue = new Map(allOptions.map((option) => [option.value, option]));
+    const searchableGroups = [
+        ...(options.length > 0
+            ? [{ value: "__ungrouped__", items: options.map((option) => option.value) }]
+            : []),
+        ...groups.map((group, index) => ({
+            value: `group-${index}-${group.label}`,
+            label: group.label,
+            items: group.options.map((option) => option.value),
+        })),
+    ];
+    const portalContainer = typeof document !== "undefined"
+        ? document.getElementById("nudge-ui-root")?.shadowRoot ?? document.body
+        : null;
+    function handleValueChange(next) {
+        if (typeof next === "string")
+            props.onValueChange?.(next);
+    }
+    const { onValueChange: _onValueChange, ...triggerProps } = props;
+    const triggerClassName = `select${compact ? " select--compact" : ""}${appearance === "embedded" ? " select--embedded" : ""}${className ? ` ${className}` : ""}`;
+    return (_jsxs(BaseCombobox.Root, { value: value || null, disabled: disabled, items: searchableGroups, itemToStringLabel: (item) => optionByValue.get(item)?.label ?? item, autoHighlight: true, onValueChange: handleValueChange, children: [_jsxs(BaseCombobox.Trigger, { ...triggerProps, "data-test": dataTest, disabled: disabled, className: triggerClassName, children: [_jsx("span", { className: "select__value", children: _jsx(BaseCombobox.Value, { placeholder: placeholder, children: selectedOption?.label ?? (value || undefined) }) }), _jsx(BaseCombobox.Icon, { className: "select__icon", children: _jsx(IconChevronDown, { size: 15, stroke: 1.8, "aria-hidden": "true" }) }), children] }), _jsx(BaseCombobox.Portal, { container: portalContainer, children: _jsx(BaseCombobox.Positioner, { className: "select__positioner", sideOffset: 4, children: _jsxs(BaseCombobox.Popup, { className: "select__popup select__popup--searchable", children: [_jsx(BaseCombobox.Input, { className: "select__search-input", placeholder: searchPlaceholder, "aria-label": searchAriaLabel, "data-test": dataTest ? `${dataTest}-search` : "select-search" }), _jsx(BaseCombobox.Empty, { className: "select__empty", children: "No matching options." }), _jsx(BaseCombobox.List, { className: "select__list select__list--searchable", children: (group) => (_jsxs(BaseCombobox.Group, { className: "select__group", items: group.items, children: [group.label ? (_jsx(BaseCombobox.GroupLabel, { className: "select__group-label", children: group.label })) : null, _jsx(BaseCombobox.Collection, { children: (item) => {
+                                                const option = optionByValue.get(item);
+                                                return option ? _jsx(SearchableSelectItem, { option: option }, item) : null;
+                                            } })] }, group.value)) })] }) }) })] }));
+}
+function SelectItem({ option }) {
+    return (_jsxs(BaseSelect.Item, { className: "select__item", value: option.value, label: option.label, disabled: option.disabled, "data-value": option.value, children: [_jsx(BaseSelect.ItemText, { className: "select__item-text", children: option.label }), _jsx(BaseSelect.ItemIndicator, { className: "select__item-indicator", children: _jsx(IconCheck, { size: 15, stroke: 2.4, "aria-hidden": "true" }) })] }));
+}
+function SearchableSelectItem({ option }) {
+    return (_jsxs(BaseCombobox.Item, { className: "select__item", value: option.value, disabled: option.disabled, "data-value": option.value, children: [_jsx("span", { className: "select__item-text", children: option.label }), _jsx(BaseCombobox.ItemIndicator, { className: "select__item-indicator", children: _jsx(IconCheck, { size: 15, stroke: 2.4, "aria-hidden": "true" }) })] }));
+}

package/dist/inspector/ui/SideValuesField.d.ts

@@ -0,0 +1,44 @@
+import type { ReactElement, ReactNode } from "react";
+export declare const SIDE_NAMES: readonly ["top", "right", "bottom", "left"];
+export type SideName = (typeof SIDE_NAMES)[number];
+export type SideValueAxis = "horizontal" | "vertical";
+export type SideControlsLayout = "sides" | "corners";
+export interface SideValueSlot {
+    side: SideName;
+    control: ReactNode;
+    icon?: ReactNode;
+    sideLabel?: string;
+}
+export interface SideValuePairSlot {
+    axis: SideValueAxis;
+    control: ReactNode;
+    icon?: ReactNode;
+}
+export interface SideValuesFieldProps {
+    label: ReactNode;
+    sides: readonly SideValueSlot[];
+    pairedControls?: readonly SideValuePairSlot[];
+    defaultExpanded?: boolean;
+    showLabel?: boolean;
+    empty?: boolean;
+    onAdd?: () => void;
+    emptyAction?: ReactNode;
+    resetKey?: unknown;
+    "data-test"?: string;
+    "data-property"?: string;
+}
+/**
+ * A compact side editor. Callers provide grouped horizontal/vertical controls
+ * that expand into the four physical sides (or omit `pairedControls` to show
+ * the four sides directly). The field owns presentation and expand state
+ * while callers own the actual CSS/token controls rendered in each slot.
+ */
+export declare function SideValuesField({ label, sides, pairedControls, defaultExpanded, showLabel, empty, onAdd, emptyAction, resetKey, "data-test": dataTest, "data-property": dataProperty, }: SideValuesFieldProps): ReactElement;
+export declare function SideControls({ label, sides, layout, }: {
+    label: ReactNode;
+    sides: readonly SideValueSlot[];
+    layout?: SideControlsLayout;
+}): ReactElement;
+export declare function MarginSideIndicator({ side }: {
+    side: SideName;
+}): ReactElement;