@cueplusplus/ui 0.13.0

package/dist/forms/scrub-input.d.ts

@@ -0,0 +1,81 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+//#region src/forms/scrub-input.d.ts
+interface ScrubInputProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue" | "onDragStart" | "onDragEnd"> {
+  /** The value. Always controlled — a scrub is a stream of edits, not a state to lose. */
+  value: number;
+  /**
+   * Called with every new value: each drag frame, each arrow-key step, and the
+   * committed result of a typed edit. Not a DOM change event.
+   */
+  onChange: (value: number) => void;
+  /** Called only for values produced by a drag, for hosts that throttle live writes. */
+  onLiveDrag?: (value: number) => void;
+  /** Called once when a drag actually begins — after the click threshold, not on press. */
+  onDragStart?: () => void;
+  /** Called once when a drag ends. */
+  onDragEnd?: () => void;
+  /**
+   * Called once per finished gesture: pointer-up after a drag, each key step, a
+   * committed typed value. Hang undo entries, network writes and persistence
+   * here — `onChange` fires dozens of times per drag.
+   */
+  onCommit?: (value: number) => void;
+  /** Lower bound. Defaults to `-Infinity`. */
+  min?: number;
+  /** Upper bound. Defaults to `Infinity`. */
+  max?: number;
+  /** Grid the value snaps to. Defaults to `1`. */
+  step?: number;
+  /** Decimal places shown. Defaults to whatever `step` implies. */
+  precision?: number;
+  /** Suffix drawn after the number — `%`, `s`, `dB`. */
+  unit?: string;
+  /**
+   * The units this value can be expressed in. With more than one the suffix
+   * becomes a button that cycles through them and reports via `onUnitChange`.
+   */
+  units?: readonly string[];
+  /** Called with the next unit when the suffix is clicked. */
+  onUnitChange?: (unit: string) => void;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Refuse dragging, typing and keyboard steps. */
+  disabled?: boolean;
+  /** Accessible name for the control. */
+  "aria-label"?: string;
+  /** Id of the element naming the control. */
+  "aria-labelledby"?: string;
+  /** Extra classes for the control. */
+  className?: string;
+}
+/**
+ * A number you scrub: drag up to raise it, down to lower it, click to type it.
+ *
+ * The console's answer to `<input type="number">`. Native spinners are two 4px
+ * arrows that only appear on hover — unusable at this density and invisible on
+ * touch — while a slider costs 200px of width to say one number. Dragging on the
+ * number itself costs nothing and is the interaction every audio and lighting
+ * tool has converged on: pointer capture so the cursor may leave the box, Shift
+ * for fine adjustment, `cursor-ns-resize` to advertise the axis.
+ *
+ * Click-to-type is not a fallback, it is the other half of the control: a
+ * gesture is for *approximately*, typing is for *exactly*, and a value you can
+ * only reach by dragging is a value you cannot enter from a cue sheet.
+ *
+ * `role="spinbutton"` is what makes any of this reachable without a pointer —
+ * arrow keys step, Page keys jump ten, Home/End go to the bounds — and it is why
+ * the resting element is not an `<input>`: a spinbutton announces its value,
+ * where a text box would announce its editable string on every drag frame.
+ *
+ * The `onChange`/`onCommit` split is the same undo-coalescing contract as
+ * {@link Slider}: one drag is one undo entry, not two hundred.
+ *
+ * @example
+ * <ScrubInput aria-label="Intensity" value={level} onChange={setLevel} onCommit={pushUndo} />
+ * @example
+ * <ScrubInput aria-label="Fade" value={fade} onChange={setFade} step={0.1} unit="s" min={0} />
+ */
+declare const ScrubInput: React.ForwardRefExoticComponent<ScrubInputProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ScrubInput, ScrubInputProps };

package/dist/forms/scrub-input.js

@@ -0,0 +1,249 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlVariants } from "./_chassis.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/forms/scrub-input.tsx
+/**
+* Pixels of vertical travel per step. Two pixels per step is the Ableton/Live
+* feel the audit called out: fast enough to cross a 0–100 range in a flick,
+* slow enough that a single value is reachable without the fine modifier.
+*/
+const PIXELS_PER_STEP = 2;
+/**
+* How much Shift slows a drag. Quarter speed — same value grid, four times the
+* travel per step, which is precision of *control* rather than sub-step values
+* the caller never asked for.
+*/
+const FINE_FACTOR = .25;
+/** Travel, in px, before a press counts as a drag rather than a click. */
+const DRAG_THRESHOLD_PX = 3;
+/** Arrow keys move one step; Page keys move ten. */
+const PAGE_FACTOR = 10;
+/** Snap to the step grid, clamp to the bounds, and drop float noise. */
+function quantise(raw, { min, max, step, precision }) {
+	const snapped = Math.round(raw / step) * step;
+	const clamped = Math.min(max, Math.max(min, snapped));
+	const factor = 10 ** precision;
+	return Math.round(clamped * factor) / factor;
+}
+/** Decimal places implied by a step, when the caller did not say. */
+function precisionOf(step) {
+	const text = String(step);
+	const dot = text.indexOf(".");
+	return dot === -1 ? 0 : Math.min(6, text.length - dot - 1);
+}
+/**
+* A number you scrub: drag up to raise it, down to lower it, click to type it.
+*
+* The console's answer to `<input type="number">`. Native spinners are two 4px
+* arrows that only appear on hover — unusable at this density and invisible on
+* touch — while a slider costs 200px of width to say one number. Dragging on the
+* number itself costs nothing and is the interaction every audio and lighting
+* tool has converged on: pointer capture so the cursor may leave the box, Shift
+* for fine adjustment, `cursor-ns-resize` to advertise the axis.
+*
+* Click-to-type is not a fallback, it is the other half of the control: a
+* gesture is for *approximately*, typing is for *exactly*, and a value you can
+* only reach by dragging is a value you cannot enter from a cue sheet.
+*
+* `role="spinbutton"` is what makes any of this reachable without a pointer —
+* arrow keys step, Page keys jump ten, Home/End go to the bounds — and it is why
+* the resting element is not an `<input>`: a spinbutton announces its value,
+* where a text box would announce its editable string on every drag frame.
+*
+* The `onChange`/`onCommit` split is the same undo-coalescing contract as
+* {@link Slider}: one drag is one undo entry, not two hundred.
+*
+* @example
+* <ScrubInput aria-label="Intensity" value={level} onChange={setLevel} onCommit={pushUndo} />
+* @example
+* <ScrubInput aria-label="Fade" value={fade} onChange={setFade} step={0.1} unit="s" min={0} />
+*/
+const ScrubInput = React.forwardRef(function ScrubInput({ className, value, onChange, onLiveDrag, onDragStart, onDragEnd, onCommit, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, step = 1, precision, unit, units, onUnitChange, size = "md", disabled = false, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...elementProps }, ref) {
+	const decimals = precision ?? precisionOf(step);
+	const bounds = React.useMemo(() => ({
+		min,
+		max,
+		step,
+		precision: decimals
+	}), [
+		decimals,
+		max,
+		min,
+		step
+	]);
+	const [editing, setEditing] = React.useState(false);
+	const [draft, setDraft] = React.useState("");
+	const editorRef = React.useRef(null);
+	/** Escape has already discarded this edit; a trailing blur must not undo that. */
+	const abandoned = React.useRef(false);
+	/** Live gesture state. A ref, not state: a drag must not re-render to track itself. */
+	const gesture = React.useRef(null);
+	const display = value.toFixed(decimals);
+	const valueText = unit === void 0 ? display : `${display} ${unit}`;
+	const emit = React.useCallback((next, fromDrag) => {
+		if (next === value) return false;
+		onChange(next);
+		if (fromDrag) onLiveDrag?.(next);
+		return true;
+	}, [
+		onChange,
+		onLiveDrag,
+		value
+	]);
+	const beginEditing = React.useCallback(() => {
+		abandoned.current = false;
+		setDraft(value.toFixed(decimals));
+		setEditing(true);
+	}, [decimals, value]);
+	const handlePointerDown = (event) => {
+		if (disabled || editing || event.button !== 0) return;
+		gesture.current = {
+			pointerId: event.pointerId,
+			startY: event.clientY,
+			startValue: value,
+			dragging: false,
+			last: value
+		};
+		event.currentTarget.setPointerCapture?.(event.pointerId);
+	};
+	const handlePointerMove = (event) => {
+		const active = gesture.current;
+		if (active === null || active.pointerId !== event.pointerId) return;
+		const travel = active.startY - event.clientY;
+		if (!active.dragging) {
+			if (Math.abs(travel) < DRAG_THRESHOLD_PX) return;
+			active.dragging = true;
+			onDragStart?.();
+		}
+		const scale = event.shiftKey ? FINE_FACTOR : 1;
+		const next = quantise(active.startValue + travel / PIXELS_PER_STEP * step * scale, bounds);
+		if (next === active.last) return;
+		active.last = next;
+		emit(next, true);
+	};
+	const endGesture = (event) => {
+		const active = gesture.current;
+		if (active === null || active.pointerId !== event.pointerId) return;
+		gesture.current = null;
+		event.currentTarget.releasePointerCapture?.(event.pointerId);
+		if (!active.dragging) {
+			if (!disabled) beginEditing();
+			return;
+		}
+		onDragEnd?.();
+		onCommit?.(active.last);
+	};
+	React.useEffect(() => {
+		if (editing) editorRef.current?.select();
+	}, [editing]);
+	const commitDraft = React.useCallback(() => {
+		setEditing(false);
+		if (abandoned.current) return;
+		const parsed = Number.parseFloat(draft);
+		if (Number.isNaN(parsed)) return;
+		const next = quantise(parsed, bounds);
+		if (emit(next, false)) onCommit?.(next);
+	}, [
+		bounds,
+		draft,
+		emit,
+		onCommit
+	]);
+	const handleKeyDown = (event) => {
+		if (disabled) return;
+		let next = null;
+		if (event.key === "ArrowUp") next = value + step;
+		else if (event.key === "ArrowDown") next = value - step;
+		else if (event.key === "PageUp") next = value + step * PAGE_FACTOR;
+		else if (event.key === "PageDown") next = value - step * PAGE_FACTOR;
+		else if (event.key === "Home" && Number.isFinite(min)) next = min;
+		else if (event.key === "End" && Number.isFinite(max)) next = max;
+		else if (event.key === "Enter") {
+			event.preventDefault();
+			beginEditing();
+			return;
+		}
+		if (next === null) return;
+		event.preventDefault();
+		const quantised = quantise(next, bounds);
+		if (emit(quantised, false)) onCommit?.(quantised);
+	};
+	const cycleUnit = () => {
+		if (units === void 0 || units.length === 0) return;
+		const index = unit === void 0 ? -1 : units.indexOf(unit);
+		onUnitChange?.(units[(index + 1) % units.length]);
+	};
+	if (editing) return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		"data-slot": "scrub-input-editor",
+		className: cn(controlVariants({ size }), "flex items-center gap-(--cue-space-2)", controlGroupFocusClasses, className),
+		children: [/* @__PURE__ */ jsx("input", {
+			ref: editorRef,
+			type: "text",
+			inputMode: "decimal",
+			"aria-label": ariaLabel,
+			"aria-labelledby": ariaLabelledBy,
+			value: draft,
+			autoFocus: true,
+			onChange: (event) => setDraft(event.currentTarget.value),
+			onBlur: commitDraft,
+			onKeyDown: (event) => {
+				if (event.key === "Enter") {
+					event.preventDefault();
+					commitDraft();
+				} else if (event.key === "Escape") {
+					event.preventDefault();
+					abandoned.current = true;
+					setEditing(false);
+				}
+			},
+			className: cn(bareControlClasses, "text-right tabular-nums", "[appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none")
+		}), unit === void 0 ? null : /* @__PURE__ */ jsx("span", {
+			className: "shrink-0 text-fg-subtle select-none",
+			children: unit
+		})]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "spinbutton",
+		"data-slot": "scrub-input",
+		tabIndex: disabled ? -1 : 0,
+		"aria-label": ariaLabel,
+		"aria-labelledby": ariaLabelledBy,
+		"aria-valuenow": value,
+		"aria-valuemin": Number.isFinite(min) ? min : void 0,
+		"aria-valuemax": Number.isFinite(max) ? max : void 0,
+		"aria-valuetext": valueText,
+		"aria-disabled": disabled ? true : void 0,
+		onPointerDown: handlePointerDown,
+		onPointerMove: handlePointerMove,
+		onPointerUp: endGesture,
+		onPointerCancel: endGesture,
+		onKeyDown: handleKeyDown,
+		className: cn(controlVariants({ size }), "flex touch-none items-center justify-between gap-(--cue-space-2) select-none", disabled ? "cursor-default opacity-40" : "cursor-ns-resize", className),
+		children: [/* @__PURE__ */ jsx("span", {
+			"data-slot": "scrub-input-value",
+			className: "truncate tabular-nums",
+			children: display
+		}), unit === void 0 ? null : units === void 0 || units.length < 2 ? /* @__PURE__ */ jsx("span", {
+			"data-slot": "scrub-input-unit",
+			className: "shrink-0 text-fg-subtle",
+			children: unit
+		}) : /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"data-slot": "scrub-input-unit",
+			"aria-label": `Unit: ${unit}`,
+			disabled,
+			onPointerDown: (event) => event.stopPropagation(),
+			onClick: cycleUnit,
+			className: "shrink-0 cursor-pointer rounded-(--radius-control) border-0 bg-transparent p-0 font-mono text-[length:inherit] text-fg-subtle outline-none transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none",
+			children: unit
+		})]
+	});
+});
+//#endregion
+export { ScrubInput };

package/dist/forms/search-input.d.ts

@@ -0,0 +1,54 @@
+import { FormControlSize } from "./_chassis.js";
+import { InputProps } from "./input.js";
+import * as React from "react";
+//#region src/forms/search-input.d.ts
+interface SearchInputProps extends Omit<InputProps, "type" | "size" | "value" | "defaultValue" | "onValueChange" | "children"> {
+  /** Current query. Supply it with `onValueChange` for a controlled input. */
+  value?: string;
+  /** Initial query for an uncontrolled input. */
+  defaultValue?: string;
+  /** Fired on every keystroke, and with `""` when the query is cleared. */
+  onValueChange?: (value: string) => void;
+  /**
+   * Quiet period in ms before {@link SearchInputProps.onDebouncedChange} fires.
+   * Defaults to `250`. `0` fires it synchronously with every keystroke.
+   */
+  debounce?: number;
+  /**
+   * Fired once the user stops typing for `debounce` ms — the callback to hang a
+   * query or a filter recomputation on. Clearing flushes it immediately, because
+   * "show me everything again" should never wait.
+   */
+  onDebouncedChange?: (value: string) => void;
+  /** Fired when the query is cleared, by Escape or by the clear button. */
+  onClear?: () => void;
+  /** Leading glyph component. Defaults to a magnifier. */
+  icon?: React.ElementType;
+  /** Accessible name for the clear button. Defaults to `"Clear search"`. */
+  clearLabel?: string;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Extra classes for the group that wraps the icon, the input and the clear button. */
+  className?: string;
+}
+/**
+ * A filter box: leading magnifier, Escape to clear, and a debounced change
+ * callback for whatever the query drives.
+ *
+ * Escape-to-clear is the reason this is a component and not a recipe. It is the
+ * behaviour every console filter needs and the one every hand-rolled search box
+ * forgets, and getting it right means also stopping the key from bubbling into a
+ * dialog that would otherwise close underneath the user.
+ *
+ * Debouncing is deliberately separate from `onValueChange`: the input stays
+ * responsive on every keystroke while the expensive work waits for the typing to
+ * stop. Clearing flushes the debounce rather than scheduling it.
+ *
+ * @example
+ * <SearchInput aria-label="Filter cues" onDebouncedChange={setQuery} />
+ * @example
+ * <SearchInput value={q} onValueChange={setQ} debounce={0} size="sm" />
+ */
+declare const SearchInput: React.ForwardRefExoticComponent<Omit<SearchInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+//#endregion
+export { SearchInput, SearchInputProps };

package/dist/forms/search-input.js

@@ -0,0 +1,112 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { InputGroup } from "./input-group.js";
+import { Input } from "./input.js";
+import { CrossGlyph, SearchGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/forms/search-input.tsx
+const DEFAULT_DEBOUNCE_MS = 250;
+/**
+* A filter box: leading magnifier, Escape to clear, and a debounced change
+* callback for whatever the query drives.
+*
+* Escape-to-clear is the reason this is a component and not a recipe. It is the
+* behaviour every console filter needs and the one every hand-rolled search box
+* forgets, and getting it right means also stopping the key from bubbling into a
+* dialog that would otherwise close underneath the user.
+*
+* Debouncing is deliberately separate from `onValueChange`: the input stays
+* responsive on every keystroke while the expensive work waits for the typing to
+* stop. Clearing flushes the debounce rather than scheduling it.
+*
+* @example
+* <SearchInput aria-label="Filter cues" onDebouncedChange={setQuery} />
+* @example
+* <SearchInput value={q} onValueChange={setQ} debounce={0} size="sm" />
+*/
+const SearchInput = React.forwardRef(function SearchInput({ className, value, defaultValue, onValueChange, onChange, onKeyDown, debounce = DEFAULT_DEBOUNCE_MS, onDebouncedChange, onClear, icon: Icon = SearchGlyph, clearLabel = "Clear search", size, ...elementProps }, ref) {
+	const isControlled = value !== void 0;
+	const [internal, setInternal] = React.useState(defaultValue ?? "");
+	const current = isControlled ? value : internal;
+	const innerRef = React.useRef(null);
+	const setRefs = React.useCallback((node) => {
+		innerRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref !== null) ref.current = node;
+	}, [ref]);
+	const debouncedRef = React.useRef(onDebouncedChange);
+	React.useEffect(() => {
+		debouncedRef.current = onDebouncedChange;
+	}, [onDebouncedChange]);
+	const lastNotified = React.useRef(current);
+	React.useEffect(() => {
+		const notify = debouncedRef.current;
+		if (notify === void 0 || current === lastNotified.current) return;
+		if (debounce <= 0) {
+			lastNotified.current = current;
+			notify(current);
+			return;
+		}
+		const timer = setTimeout(() => {
+			lastNotified.current = current;
+			notify(current);
+		}, debounce);
+		return () => clearTimeout(timer);
+	}, [current, debounce]);
+	const commit = React.useCallback((next) => {
+		if (!isControlled) setInternal(next);
+		onValueChange?.(next);
+	}, [isControlled, onValueChange]);
+	const clear = React.useCallback(() => {
+		commit("");
+		lastNotified.current = "";
+		debouncedRef.current?.("");
+		onClear?.();
+		innerRef.current?.focus();
+	}, [commit, onClear]);
+	const handleChange = React.useCallback((event) => {
+		onChange?.(event);
+		commit(event.currentTarget.value);
+	}, [commit, onChange]);
+	const handleKeyDown = React.useCallback((event) => {
+		onKeyDown?.(event);
+		if (event.defaultPrevented || event.key !== "Escape") return;
+		if (current === "") return;
+		event.preventDefault();
+		event.stopPropagation();
+		clear();
+	}, [
+		clear,
+		current,
+		onKeyDown
+	]);
+	return /* @__PURE__ */ jsx(InputGroup, {
+		size,
+		className,
+		leading: /* @__PURE__ */ jsx(Icon, {
+			"data-slot": "search-icon",
+			"aria-hidden": "true",
+			className: "size-icon-md"
+		}),
+		trailing: current === "" ? void 0 : /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-label": clearLabel,
+			onClick: clear,
+			className: "flex shrink-0 cursor-pointer items-center justify-center rounded-(--radius-control) text-fg-subtle outline-none transition-colors hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+			children: /* @__PURE__ */ jsx(CrossGlyph, { className: "size-icon-sm" })
+		}),
+		children: /* @__PURE__ */ jsx(Input, {
+			ref: setRefs,
+			type: "search",
+			"data-slot": "search-input",
+			value: current,
+			onChange: handleChange,
+			onKeyDown: handleKeyDown,
+			className: cn("[&::-webkit-search-cancel-button]:appearance-none"),
+			...elementProps
+		})
+	});
+});
+//#endregion
+export { SearchInput };

package/dist/forms/select.d.ts

@@ -0,0 +1,75 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+//#region src/forms/select.d.ts
+/** One row in a {@link Select}. */
+interface SelectOption {
+  /** Submitted value and identity of the row. */
+  value: string;
+  /** What the user reads, in the trigger as well as the list. */
+  label: React.ReactNode;
+  /** Grey the row out and skip it during keyboard navigation. */
+  disabled?: boolean;
+}
+interface SelectProps {
+  /** The rows, in display order. */
+  items: readonly SelectOption[];
+  /** Selected value. Use with `onValueChange` for a controlled select. */
+  value?: string | null;
+  /** Initially selected value for an uncontrolled select. */
+  defaultValue?: string | null;
+  /** Called with the newly selected value (`null` when cleared). */
+  onValueChange?: (value: string | null) => void;
+  /** Shown in the trigger while nothing is selected. */
+  placeholder?: React.ReactNode;
+  /** Rung of the control ladder for the trigger. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Prevent opening and grey the trigger out. */
+  disabled?: boolean;
+  /** Require a value before the owning form submits. */
+  required?: boolean;
+  /** Name for the hidden input, when the select is part of a form. */
+  name?: string;
+  /** Id forwarded to the select's hidden input. */
+  id?: string;
+  /** Accessible name for the trigger, when no {@link FieldLabel} names it. */
+  "aria-label"?: string;
+  /** Id of the element naming the trigger. */
+  "aria-labelledby"?: string;
+  /**
+   * Lock interaction to the popup while it is open. Defaults to `true`, matching
+   * Base UI; set `false` inside a canvas or a drag surface that must keep
+   * receiving pointer events.
+   */
+  modal?: boolean;
+  /** Extra classes for the trigger. */
+  className?: string;
+  /** Extra classes for the popup surface. */
+  popupClassName?: string;
+  /** Distance in px between the trigger and the popup. Defaults to `4`. */
+  sideOffset?: number;
+}
+/**
+ * A dropdown for choosing one of a known set of values.
+ *
+ * The trigger rides the recessed control chassis so a select lines up with the
+ * {@link Input}s beside it; the popup wears the overlay surface
+ * (`surface-2` + `border-overlay` + the overlay radius) that every floating
+ * element in this system shares. Rows are one `control-sm` tall — the list is
+ * meant to show a dozen options without scrolling.
+ *
+ * The popup is portalled through {@link useCuePortalProps}, so it carries the
+ * caller's `data-theme` / `data-density` / `data-mode` even though it mounts at
+ * the end of `<body>`. Without that a select opened inside an ultra-compact
+ * island would render at the page's density.
+ *
+ * @example
+ * <Select
+ *   aria-label="Blend mode"
+ *   items={[{ value: "htp", label: "HTP" }, { value: "ltp", label: "LTP" }]}
+ *   value={mode}
+ *   onValueChange={setMode}
+ * />
+ */
+declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLButtonElement>>;
+//#endregion
+export { Select, SelectOption, SelectProps };

package/dist/forms/select.js

@@ -0,0 +1,91 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { controlVariants } from "./_chassis.js";
+import { useCuePortalProps } from "../system/portal.js";
+import { CaretGlyph, TickGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Select } from "@base-ui/react/select";
+//#region src/forms/select.tsx
+/**
+* A dropdown for choosing one of a known set of values.
+*
+* The trigger rides the recessed control chassis so a select lines up with the
+* {@link Input}s beside it; the popup wears the overlay surface
+* (`surface-2` + `border-overlay` + the overlay radius) that every floating
+* element in this system shares. Rows are one `control-sm` tall — the list is
+* meant to show a dozen options without scrolling.
+*
+* The popup is portalled through {@link useCuePortalProps}, so it carries the
+* caller's `data-theme` / `data-density` / `data-mode` even though it mounts at
+* the end of `<body>`. Without that a select opened inside an ultra-compact
+* island would render at the page's density.
+*
+* @example
+* <Select
+*   aria-label="Blend mode"
+*   items={[{ value: "htp", label: "HTP" }, { value: "ltp", label: "LTP" }]}
+*   value={mode}
+*   onValueChange={setMode}
+* />
+*/
+const Select$1 = React.forwardRef(function Select$2({ items, value, defaultValue, onValueChange, placeholder, size, disabled, required, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, modal, className, popupClassName, sideOffset = 4 }, ref) {
+	const portalProps = useCuePortalProps();
+	const handleValueChange = React.useCallback((next) => {
+		onValueChange?.(next ?? null);
+	}, [onValueChange]);
+	return /* @__PURE__ */ jsxs(Select.Root, {
+		items,
+		value,
+		defaultValue,
+		onValueChange: onValueChange === void 0 ? void 0 : handleValueChange,
+		disabled,
+		required,
+		name,
+		id,
+		modal,
+		children: [/* @__PURE__ */ jsxs(Select.Trigger, {
+			ref,
+			"data-slot": "select-trigger",
+			"aria-label": ariaLabel,
+			"aria-labelledby": ariaLabelledBy,
+			className: cn(controlVariants({ size }), "flex cursor-default items-center justify-between gap-(--cue-space-3) text-left", "hover:not-data-disabled:border-border-strong", className),
+			children: [/* @__PURE__ */ jsx(Select.Value, {
+				className: "truncate data-[placeholder]:text-fg-subtle",
+				placeholder
+			}), /* @__PURE__ */ jsx(Select.Icon, {
+				className: "flex shrink-0 items-center text-fg-subtle",
+				children: /* @__PURE__ */ jsx(CaretGlyph, { className: "size-icon-md" })
+			})]
+		}), /* @__PURE__ */ jsx(Select.Portal, {
+			...portalProps,
+			children: /* @__PURE__ */ jsx(Select.Positioner, {
+				className: "z-50 outline-none",
+				sideOffset,
+				alignItemWithTrigger: false,
+				children: /* @__PURE__ */ jsx(Select.Popup, {
+					"data-slot": "select-popup",
+					className: cn("min-w-(--anchor-width) origin-(--transform-origin) overflow-hidden rounded-(--radius-overlay) border border-border-overlay bg-surface-2 py-(--cue-space-1) shadow-[0_8px_24px_rgba(0,0,0,0.4)] outline-none", "transition-[opacity,scale] duration-100 ease-out motion-reduce:transition-none", "data-[starting-style]:scale-[0.98] data-[starting-style]:opacity-0", "data-[ending-style]:scale-[0.98] data-[ending-style]:opacity-0", popupClassName),
+					children: /* @__PURE__ */ jsx(Select.List, {
+						className: "max-h-(--available-height) overflow-y-auto",
+						children: items.map((item) => /* @__PURE__ */ jsxs(Select.Item, {
+							value: item.value,
+							disabled: item.disabled,
+							"data-slot": "select-item",
+							className: "flex h-control-sm cursor-default items-center gap-(--cue-space-2) px-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg-muted outline-none select-none data-[highlighted]:bg-accent-soft data-[highlighted]:text-fg data-[selected]:text-accent data-[disabled]:pointer-events-none data-[disabled]:opacity-40",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "flex size-icon-sm shrink-0 items-center justify-center",
+								children: /* @__PURE__ */ jsx(Select.ItemIndicator, { children: /* @__PURE__ */ jsx(TickGlyph, { className: "size-icon-sm" }) })
+							}), /* @__PURE__ */ jsx(Select.ItemText, {
+								className: "truncate",
+								children: item.label
+							})]
+						}, item.value))
+					})
+				})
+			})
+		})]
+	});
+});
+//#endregion
+export { Select$1 as Select };