@cueplusplus/ui 0.1.0

package/dist/forms/rating.d.ts

@@ -0,0 +1,69 @@
+import * as React from "react";
+//#region src/forms/rating.d.ts
+/** Mark size per rung — a rating is read at a glance, so it tracks the icon ladder. */
+declare const MARK_SIZES: {
+  readonly sm: "size-icon-sm";
+  readonly md: "size-icon-md";
+  readonly lg: "size-[calc(var(--cue-icon-md)*1.35)]";
+};
+/** Rung of the icon ladder a {@link Rating}'s marks sit on. */
+type RatingSize = keyof typeof MARK_SIZES;
+interface RatingProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue"> {
+  /** The rating, `0`–`count`. Use with `onValueChange` for a controlled widget. */
+  value?: number;
+  /** Initial rating for an uncontrolled widget. Defaults to `0`. */
+  defaultValue?: number;
+  /** Called with the new rating; `0` means "cleared". */
+  onValueChange?: (value: number) => void;
+  /** How many marks. Defaults to `5`. */
+  count?: number;
+  /** Rung of the icon ladder. Defaults to `"md"`. */
+  size?: RatingSize;
+  /**
+   * Picking the current value clears it back to `0`. Defaults to `true` — a
+   * rating you cannot take back is a trap, and there is no other affordance for
+   * "actually, no opinion".
+   */
+  allowClear?: boolean;
+  /** Render a static readout with no controls. */
+  readOnly?: boolean;
+  /** Grey the marks out and refuse interaction. */
+  disabled?: boolean;
+  /**
+   * Accessible name for the group. Also the prefix of the read-only readout —
+   * `"Signal quality: 4 of 5"`. Synonym of `aria-label`, which wins if both are
+   * given.
+   */
+  label?: string;
+  /** Accessible name for the group, for callers who prefer the ARIA spelling. */
+  "aria-label"?: string;
+  /** The mark component. Defaults to a filled star. */
+  icon?: React.ElementType;
+  /**
+   * Accessible name for mark `index` (1-based) of `count`. Defaults to
+   * ``(index, count) => `${index} of ${count}` ``.
+   */
+  markLabel?: (index: number, count: number) => string;
+  /** Extra classes for the group. */
+  className?: string;
+}
+/**
+ * A 0–N rating, drawn as marks.
+ *
+ * Built as a **radio group**, not a row of buttons: exactly one value is in
+ * effect, arrow keys move between the options, and one Tab stop covers the whole
+ * widget. A row of toggle buttons would put five stops in the tab order and
+ * announce five unrelated controls.
+ *
+ * Read-only renders as a single `img` with the value in its name — an
+ * un-interactive control that still takes focus is a trap, and five disabled
+ * radios announce five things where one sentence will do.
+ *
+ * @example
+ * <Rating label="Signal quality" value={score} onValueChange={setScore} />
+ * @example
+ * <Rating aria-label="Signal quality" value={4} readOnly size="sm" />
+ */
+declare const Rating: React.ForwardRefExoticComponent<RatingProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Rating, RatingProps, RatingSize };

package/dist/forms/rating.js

@@ -0,0 +1,103 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { StarGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/forms/rating.tsx
+/** Mark size per rung — a rating is read at a glance, so it tracks the icon ladder. */
+const MARK_SIZES = {
+	sm: "size-icon-sm",
+	md: "size-icon-md",
+	lg: "size-[calc(var(--cue-icon-md)*1.35)]"
+};
+const MARK_CLASSES = "flex cursor-pointer items-center justify-center border-0 bg-transparent p-0 text-fg-subtle transition-colors duration-150 outline-none hover:text-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-40 aria-checked:text-accent";
+/**
+* A 0–N rating, drawn as marks.
+*
+* Built as a **radio group**, not a row of buttons: exactly one value is in
+* effect, arrow keys move between the options, and one Tab stop covers the whole
+* widget. A row of toggle buttons would put five stops in the tab order and
+* announce five unrelated controls.
+*
+* Read-only renders as a single `img` with the value in its name — an
+* un-interactive control that still takes focus is a trap, and five disabled
+* radios announce five things where one sentence will do.
+*
+* @example
+* <Rating label="Signal quality" value={score} onValueChange={setScore} />
+* @example
+* <Rating aria-label="Signal quality" value={4} readOnly size="sm" />
+*/
+const Rating = React.forwardRef(function Rating({ className, value: valueProp, defaultValue = 0, onValueChange, count = 5, size = "md", allowClear = true, readOnly = false, disabled = false, label, "aria-label": ariaLabel, icon: Icon = StarGlyph, markLabel = (index, total) => `${index} of ${total}`, ...elementProps }, ref) {
+	const isControlled = valueProp !== void 0;
+	const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
+	const value = isControlled ? valueProp : uncontrolled;
+	const name = ariaLabel ?? label;
+	const commit = React.useCallback((next) => {
+		const clamped = Math.min(count, Math.max(0, next));
+		if (clamped === value) return;
+		if (!isControlled) setUncontrolled(clamped);
+		onValueChange?.(clamped);
+	}, [
+		count,
+		isControlled,
+		onValueChange,
+		value
+	]);
+	const marks = Array.from({ length: count }, (_, index) => index + 1);
+	if (readOnly) return /* @__PURE__ */ jsx("div", {
+		ref,
+		role: "img",
+		"data-slot": "rating",
+		"aria-label": name === void 0 ? `${value} of ${count}` : `${name}: ${value} of ${count}`,
+		className: cn("inline-flex items-center gap-(--cue-space-1)", className),
+		...elementProps,
+		children: marks.map((mark) => /* @__PURE__ */ jsx(Icon, {
+			"aria-hidden": "true",
+			"data-slot": "rating-mark",
+			"data-filled": mark <= value ? "" : void 0,
+			className: cn(MARK_SIZES[size], mark <= value ? "text-accent" : "text-fg-subtle")
+		}, mark))
+	});
+	const handleKeyDown = (event) => {
+		if (disabled) return;
+		const step = event.key === "ArrowRight" || event.key === "ArrowUp" ? 1 : event.key === "ArrowLeft" || event.key === "ArrowDown" ? -1 : 0;
+		let next = null;
+		if (step !== 0) next = Math.min(count, Math.max(1, value + step));
+		else if (event.key === "Home") next = 1;
+		else if (event.key === "End") next = count;
+		if (next === null) return;
+		event.preventDefault();
+		commit(next);
+		event.currentTarget.querySelector(`[data-slot="rating-mark"][data-index="${next}"]`)?.focus();
+	};
+	const focusable = value === 0 ? 1 : value;
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		role: "radiogroup",
+		"data-slot": "rating",
+		"aria-label": name,
+		"aria-disabled": disabled ? true : void 0,
+		onKeyDown: handleKeyDown,
+		className: cn("inline-flex items-center gap-(--cue-space-1)", className),
+		...elementProps,
+		children: marks.map((mark) => /* @__PURE__ */ jsx("button", {
+			type: "button",
+			role: "radio",
+			"data-slot": "rating-mark",
+			"data-index": mark,
+			"aria-checked": mark === value,
+			"aria-label": markLabel(mark, count),
+			tabIndex: mark === focusable ? 0 : -1,
+			disabled,
+			onClick: () => commit(mark === value && allowClear ? 0 : mark),
+			className: MARK_CLASSES,
+			children: /* @__PURE__ */ jsx(Icon, {
+				"aria-hidden": "true",
+				className: cn(MARK_SIZES[size], mark <= value ? "text-accent" : void 0)
+			})
+		}, mark))
+	});
+});
+//#endregion
+export { Rating };

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 };