@cueplusplus/ui 0.13.0

package/dist/forms/file-upload.js

@@ -0,0 +1,232 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { CrossGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/forms/file-upload.tsx
+/** Does `file` satisfy one clause of an `accept` string? */
+function matchesAcceptClause(file, clause) {
+	const rule = clause.trim().toLowerCase();
+	if (rule === "") return true;
+	if (rule.startsWith(".")) return file.name.toLowerCase().endsWith(rule);
+	if (rule.endsWith("/*")) return file.type.toLowerCase().startsWith(rule.slice(0, -1));
+	return file.type.toLowerCase() === rule;
+}
+/**
+* Split a drop into the files that pass the rules and the ones that do not,
+* each with the reason it was turned away.
+*
+* Exported and pure because "why was my file rejected?" is the question a drop
+* zone most often has to answer, and a caller filtering by hand would answer it
+* differently from the component. Order is preserved, and the count ceiling
+* keeps the *first* files rather than an arbitrary subset.
+*
+* @param files - Everything the drop or the file dialog produced.
+* @param options - The rules to apply.
+* @returns The accepted files and the reasoned rejections.
+* @example
+* partitionFiles(files, { accept: "image/*", maxSize: 2_000_000 })
+*/
+function partitionFiles(files, { accept, maxSize, maxFiles }) {
+	const clauses = accept === void 0 ? [] : accept.split(",").filter((part) => part.trim() !== "");
+	const accepted = [];
+	const rejected = [];
+	for (const file of files) if (clauses.length > 0 && !clauses.some((clause) => matchesAcceptClause(file, clause))) rejected.push({
+		file,
+		reason: "type"
+	});
+	else if (maxSize !== void 0 && file.size > maxSize) rejected.push({
+		file,
+		reason: "size"
+	});
+	else if (maxFiles !== void 0 && accepted.length >= maxFiles) rejected.push({
+		file,
+		reason: "count"
+	});
+	else accepted.push(file);
+	return {
+		accepted,
+		rejected
+	};
+}
+/** SI units, one decimal — `1536` reads as `1.5 kB`, not `1.5 KiB`. */
+function formatBytes(bytes) {
+	if (bytes < 1e3) return `${bytes} B`;
+	const units = [
+		"kB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let value = bytes / 1e3;
+	let unit = 0;
+	while (value >= 1e3 && unit < units.length - 1) {
+		value /= 1e3;
+		unit += 1;
+	}
+	return `${value.toFixed(1)} ${units[unit]}`;
+}
+/**
+* A drop zone with a file list under it.
+*
+* The zone is a real `<button>`, not a div with a drop handler: dropping is the
+* mouse affordance, and pressing Enter on a focused button to open the file
+* dialog is the keyboard one. A zone that only accepts drops is unusable
+* without a pointer (WCAG 2.1.1), and it is the single most common defect in
+* hand-rolled uploaders.
+*
+* State is the caller's. This component turns drops into `File[]` (plus
+* reasoned rejections, via {@link partitionFiles}) and renders whatever rows it
+* is handed — it never holds an upload queue, because the transport, the
+* retries and the progress belong to the app.
+*
+* @example
+* <FileUpload
+*   label="Drop show files"
+*   hint="CSV or QLab bundle, up to 20 MB"
+*   accept=".csv,.qlab"
+*   maxSize={20_000_000}
+*   files={rows}
+*   onFilesAccepted={enqueue}
+*   onFilesRejected={explain}
+*   onRemove={cancel}
+* />
+*/
+const FileUpload = React.forwardRef(function FileUpload({ className, zoneClassName, label = "Drop files", hint, accept, multiple = false, maxSize, maxFiles, disabled = false, files, onFilesAccepted, onFilesRejected, onRemove, removeLabel = (file) => `Remove ${file.name}`, ...elementProps }, ref) {
+	const inputRef = React.useRef(null);
+	const [dragging, setDragging] = React.useState(false);
+	const depth = React.useRef(0);
+	const intake = (incoming) => {
+		if (disabled || incoming === null || incoming.length === 0) return;
+		const { accepted, rejected } = partitionFiles(Array.from(incoming), {
+			accept,
+			maxSize,
+			maxFiles: maxFiles ?? (multiple ? void 0 : 1)
+		});
+		if (accepted.length > 0) onFilesAccepted?.(accepted);
+		if (rejected.length > 0) onFilesRejected?.(rejected);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "file-upload",
+		className: cn("flex w-full flex-col gap-(--cue-space-2)", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsxs("button", {
+				type: "button",
+				"data-slot": "file-upload-zone",
+				"data-dragging": dragging ? "true" : void 0,
+				disabled,
+				onClick: () => inputRef.current?.click(),
+				onDragEnter: (event) => {
+					if (disabled) return;
+					event.preventDefault();
+					depth.current += 1;
+					setDragging(true);
+				},
+				onDragOver: (event) => {
+					if (disabled) return;
+					event.preventDefault();
+				},
+				onDragLeave: (event) => {
+					if (disabled) return;
+					event.preventDefault();
+					depth.current -= 1;
+					if (depth.current <= 0) {
+						depth.current = 0;
+						setDragging(false);
+					}
+				},
+				onDrop: (event) => {
+					event.preventDefault();
+					depth.current = 0;
+					setDragging(false);
+					intake(event.dataTransfer?.files ?? null);
+				},
+				className: cn("flex w-full cursor-pointer flex-col items-center justify-center gap-(--cue-space-1) rounded-(--radius-control) border border-dashed border-border bg-sunken px-(--cue-space-4) py-(--cue-space-5) font-mono text-(length:--cue-text-ui) text-fg-muted outline-none transition-colors duration-150 hover:border-border-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-40 data-[dragging=true]:border-accent data-[dragging=true]:bg-accent-soft data-[dragging=true]:text-fg motion-reduce:transition-none", zoneClassName),
+				children: [/* @__PURE__ */ jsx("span", { children: label }), hint === void 0 ? null : /* @__PURE__ */ jsx("span", {
+					className: "text-(length:--cue-text-label) text-fg-subtle",
+					children: hint
+				})]
+			}),
+			/* @__PURE__ */ jsx("input", {
+				ref: inputRef,
+				type: "file",
+				hidden: true,
+				tabIndex: -1,
+				accept,
+				multiple,
+				disabled,
+				"data-slot": "file-upload-input",
+				onChange: (event) => {
+					intake(event.target.files);
+					event.target.value = "";
+				}
+			}),
+			files === void 0 || files.length === 0 ? null : /* @__PURE__ */ jsx("ul", {
+				"data-slot": "file-upload-list",
+				className: "flex flex-col gap-px",
+				children: files.map((file) => /* @__PURE__ */ jsx(FileUploadRow, {
+					file,
+					onRemove,
+					removeLabel
+				}, file.id))
+			})
+		]
+	});
+});
+/** One file: name, size, progress or reason, and a way out. */
+function FileUploadRow({ file, onRemove, removeLabel }) {
+	const status = file.status ?? "pending";
+	const showProgress = status === "uploading" && file.progress !== void 0;
+	return /* @__PURE__ */ jsxs("li", {
+		"data-slot": "file-upload-row",
+		"data-status": status,
+		className: "flex min-h-control-sm items-center gap-(--cue-space-3) bg-surface-2 px-(--cue-space-3) py-(--cue-space-1) font-mono text-(length:--cue-text-label)",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex min-w-0 flex-1 flex-col gap-px",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "truncate text-fg",
+					children: file.name
+				}), file.error === void 0 ? null : /* @__PURE__ */ jsx("span", {
+					"data-slot": "file-upload-error",
+					className: "truncate text-danger",
+					children: file.error
+				})]
+			}),
+			file.size === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "shrink-0 tabular-nums text-fg-subtle",
+				children: formatBytes(file.size)
+			}),
+			showProgress ? /* @__PURE__ */ jsx("div", {
+				role: "progressbar",
+				"aria-label": `Uploading ${file.name}`,
+				"aria-valuenow": file.progress,
+				"aria-valuemin": 0,
+				"aria-valuemax": 100,
+				"data-slot": "file-upload-progress",
+				className: "h-px w-[4rem] shrink-0 overflow-hidden bg-surface-3",
+				children: /* @__PURE__ */ jsx("div", {
+					className: "h-full bg-accent transition-[width] duration-[120ms] ease-linear motion-reduce:transition-none",
+					style: { width: `${file.progress}%` }
+				})
+			}) : null,
+			status === "done" ? /* @__PURE__ */ jsx("span", {
+				className: "shrink-0 text-ok",
+				"aria-hidden": "true",
+				children: "✓"
+			}) : null,
+			onRemove === void 0 ? null : /* @__PURE__ */ jsx("button", {
+				type: "button",
+				"aria-label": removeLabel(file),
+				"data-slot": "file-upload-remove",
+				onClick: () => onRemove(file.id),
+				className: "flex size-icon-sm shrink-0 cursor-pointer items-center justify-center rounded-(--radius-control) border-0 bg-transparent p-0 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 motion-reduce:transition-none",
+				children: /* @__PURE__ */ jsx(CrossGlyph, { className: "size-full" })
+			})
+		]
+	});
+}
+//#endregion
+export { FileUpload, partitionFiles };

package/dist/forms/index.d.ts

@@ -0,0 +1,26 @@
+import { ControlVariantProps, FormControlSize, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants } from "./_chassis.js";
+import { Autocomplete, AutocompleteProps } from "./autocomplete.js";
+import { ButtonGroup, ButtonGroupOrientation, ButtonGroupProps } from "./button-group.js";
+import { Checkbox, CheckboxGroup, CheckboxGroupProps, CheckboxProps } from "./checkbox.js";
+import { Combobox, ComboboxOption, ComboboxProps } from "./combobox.js";
+import { EnvVarInput, EnvVarInputProps, envReference, parseEnvReference } from "./env-var-input.js";
+import { Field, FieldDescription, FieldDescriptionProps, FieldError, FieldErrorProps, FieldIssue, FieldLabel, FieldLabelProps, FieldProps } from "./field.js";
+import { FilePartition, FilePartitionOptions, FileRejectReason, FileRejection, FileUpload, FileUploadProps, UploadFile, UploadStatus, partitionFiles } from "./file-upload.js";
+import { Input, InputProps } from "./input.js";
+import { InputGroup, InputGroupProps } from "./input-group.js";
+import { MultiSelect, MultiSelectProps } from "./multi-select.js";
+import { NumberField, NumberFieldProps } from "./number-field.js";
+import { OTPField, OTPFieldProps } from "./otp-field.js";
+import { PasswordInput, PasswordInputProps } from "./password-input.js";
+import { Radio, RadioGroup, RadioGroupProps, RadioProps } from "./radio-group.js";
+import { Rating, RatingProps, RatingSize } from "./rating.js";
+import { ScrubInput, ScrubInputProps } from "./scrub-input.js";
+import { SearchInput, SearchInputProps } from "./search-input.js";
+import { Select, SelectOption, SelectProps } from "./select.js";
+import { Slider, SliderProps } from "./slider.js";
+import { Switch, SwitchProps } from "./switch.js";
+import { TagsInput, TagsInputProps } from "./tags-input.js";
+import { Textarea, TextareaProps } from "./textarea.js";
+import { Toggle, ToggleProps } from "./toggle.js";
+import { ToggleGroup, ToggleGroupProps } from "./toggle-group.js";
+export { Autocomplete, type AutocompleteProps, ButtonGroup, type ButtonGroupOrientation, type ButtonGroupProps, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, type ControlVariantProps, EnvVarInput, type EnvVarInputProps, Field, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, type FieldIssue, FieldLabel, type FieldLabelProps, type FieldProps, type FilePartition, type FilePartitionOptions, type FileRejectReason, type FileRejection, FileUpload, type FileUploadProps, type FormControlSize, Input, InputGroup, type InputGroupProps, type InputProps, MultiSelect, type MultiSelectProps, NumberField, type NumberFieldProps, OTPField, type OTPFieldProps, PasswordInput, type PasswordInputProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type RatingSize, ScrubInput, type ScrubInputProps, SearchInput, type SearchInputProps, Select, type SelectOption, type SelectProps, Slider, type SliderProps, Switch, type SwitchProps, TagsInput, type TagsInputProps, Textarea, type TextareaProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, type UploadFile, type UploadStatus, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, envReference, parseEnvReference, partitionFiles };

package/dist/forms/index.js

@@ -0,0 +1,26 @@
+import { Checkbox, CheckboxGroup } from "./checkbox.js";
+import { bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants } from "./_chassis.js";
+import { InputGroup } from "./input-group.js";
+import { Input } from "./input.js";
+import { NumberField } from "./number-field.js";
+import { Radio, RadioGroup } from "./radio-group.js";
+import { Autocomplete } from "./autocomplete.js";
+import { ButtonGroup } from "./button-group.js";
+import { Combobox } from "./combobox.js";
+import { PasswordInput } from "./password-input.js";
+import { EnvVarInput, envReference, parseEnvReference } from "./env-var-input.js";
+import { Field, FieldDescription, FieldError, FieldLabel } from "./field.js";
+import { FileUpload, partitionFiles } from "./file-upload.js";
+import { MultiSelect } from "./multi-select.js";
+import { OTPField } from "./otp-field.js";
+import { Rating } from "./rating.js";
+import { ScrubInput } from "./scrub-input.js";
+import { SearchInput } from "./search-input.js";
+import { Select } from "./select.js";
+import { Slider } from "./slider.js";
+import { Switch } from "./switch.js";
+import { TagsInput } from "./tags-input.js";
+import { Textarea } from "./textarea.js";
+import { ToggleGroup } from "./toggle-group.js";
+import { Toggle } from "./toggle.js";
+export { Autocomplete, ButtonGroup, Checkbox, CheckboxGroup, Combobox, EnvVarInput, Field, FieldDescription, FieldError, FieldLabel, FileUpload, Input, InputGroup, MultiSelect, NumberField, OTPField, PasswordInput, Radio, RadioGroup, Rating, ScrubInput, SearchInput, Select, Slider, Switch, TagsInput, Textarea, Toggle, ToggleGroup, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, envReference, parseEnvReference, partitionFiles };

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

@@ -0,0 +1,36 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+//#region src/forms/input-group.d.ts
+interface InputGroupProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Content pinned to the left gutter — a glyph, a unit prefix, a protocol. */
+  leading?: React.ReactNode;
+  /** Content pinned to the right gutter — a unit suffix, a `Kbd`, a clear button. */
+  trailing?: React.ReactNode;
+  /** Rung of the control ladder for the whole cluster. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** The control. An {@link Input} here renders bare and fills the middle. */
+  children: React.ReactNode;
+}
+/**
+ * A control and its adornments, drawn as a single field.
+ *
+ * The group — not the input — owns the chassis, so there is exactly one rim and
+ * one fill however many affordances are bolted on. It publishes that fact
+ * through context: an {@link Input} rendered inside strips its own border,
+ * background, height and padding and inherits the group's font size.
+ *
+ * Focus feedback splits in two, because a `<div>` matches neither `:focus` nor
+ * `:focus-visible` itself. The rim strengthens on `:focus-within` — anything
+ * focused inside, however it got there — while the ring waits for
+ * `:has(:focus-visible)`, so a mouse click into the field does not light the
+ * whole cluster up. Both halves live on the wrapper; the inner control paints
+ * no ring of its own.
+ *
+ * @example
+ * <InputGroup leading={<Search />} trailing={<Kbd>⌘K</Kbd>}>
+ *   <Input aria-label="Search cues" />
+ * </InputGroup>
+ */
+declare const InputGroup: React.ForwardRefExoticComponent<InputGroupProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { InputGroup, InputGroupProps };

package/dist/forms/input-group.js

@@ -0,0 +1,59 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { controlGroupFocusClasses, controlVariants } from "./_chassis.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/forms/input-group.tsx
+/**
+* `true` inside an {@link InputGroup}: tells a nested control to render bare
+* because the group already paints the rim, the fill and the height.
+*
+* @internal Not part of the public API; read by `input.tsx`.
+*/
+const InputGroupContext = React.createContext(false);
+/**
+* A control and its adornments, drawn as a single field.
+*
+* The group — not the input — owns the chassis, so there is exactly one rim and
+* one fill however many affordances are bolted on. It publishes that fact
+* through context: an {@link Input} rendered inside strips its own border,
+* background, height and padding and inherits the group's font size.
+*
+* Focus feedback splits in two, because a `<div>` matches neither `:focus` nor
+* `:focus-visible` itself. The rim strengthens on `:focus-within` — anything
+* focused inside, however it got there — while the ring waits for
+* `:has(:focus-visible)`, so a mouse click into the field does not light the
+* whole cluster up. Both halves live on the wrapper; the inner control paints
+* no ring of its own.
+*
+* @example
+* <InputGroup leading={<Search />} trailing={<Kbd>⌘K</Kbd>}>
+*   <Input aria-label="Search cues" />
+* </InputGroup>
+*/
+const InputGroup = React.forwardRef(function InputGroup({ className, leading, trailing, size, children, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "input-group",
+		className: cn(controlVariants({ size }), "flex items-center gap-(--cue-space-2)", controlGroupFocusClasses, className),
+		...elementProps,
+		children: [
+			leading === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "input-group-leading",
+				className: "flex shrink-0 items-center text-fg-subtle",
+				children: leading
+			}),
+			/* @__PURE__ */ jsx(InputGroupContext.Provider, {
+				value: true,
+				children
+			}),
+			trailing === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "input-group-trailing",
+				className: "flex shrink-0 items-center text-fg-subtle",
+				children: trailing
+			})
+		]
+	});
+});
+//#endregion
+export { InputGroup, InputGroupContext };

package/dist/forms/input.d.ts

@@ -0,0 +1,45 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+import { Input } from "@base-ui/react/input";
+//#region src/forms/input.d.ts
+interface InputProps extends Omit<Input.Props, "className" | "size"> {
+  /** Extra classes, merged over the chassis. */
+  className?: string;
+  /**
+   * Rung of the control ladder. Defaults to `"md"`. Shadows the native `size`
+   * attribute (a character count), which nothing in a token-driven layout wants.
+   */
+  size?: FormControlSize;
+  /**
+   * Accessible name for the input, when no `FieldLabel` names it. Declared here
+   * rather than left to the inherited attribute so the props table carries the
+   * row: a bare input outside a `Field` has no other way to be named.
+   */
+  "aria-label"?: string;
+  /**
+   * An example of what goes in the field, shown while it is empty. Not a name:
+   * it disappears on the first keystroke, so pair it with `aria-label` or a
+   * `FieldLabel`. Declared for the props-table row, as `aria-label` is above.
+   */
+  placeholder?: string;
+}
+/**
+ * The single-line text control.
+ *
+ * Wraps Base UI's `Input`, so dropping one inside a {@link Field} wires up the
+ * label, the description and the validity state with no `id` plumbing. Rides
+ * the recessed chassis: `bg-sunken` sets it into the panel rather than raising
+ * it off, which is how this system distinguishes "you type here" from "you
+ * press here".
+ *
+ * Inside an {@link InputGroup} it renders bare — the group owns the rim — so the
+ * two compose without a doubled border.
+ *
+ * @example
+ * <Input placeholder="e.g. Blackout" />
+ * @example
+ * <Input type="number" size="sm" defaultValue={512} />
+ */
+declare const Input$1: React.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+//#endregion
+export { Input$1 as Input, InputProps };

package/dist/forms/input.js

@@ -0,0 +1,36 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlVariants } from "./_chassis.js";
+import { InputGroupContext } from "./input-group.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+import { Input } from "@base-ui/react/input";
+//#region src/forms/input.tsx
+/**
+* The single-line text control.
+*
+* Wraps Base UI's `Input`, so dropping one inside a {@link Field} wires up the
+* label, the description and the validity state with no `id` plumbing. Rides
+* the recessed chassis: `bg-sunken` sets it into the panel rather than raising
+* it off, which is how this system distinguishes "you type here" from "you
+* press here".
+*
+* Inside an {@link InputGroup} it renders bare — the group owns the rim — so the
+* two compose without a doubled border.
+*
+* @example
+* <Input placeholder="e.g. Blackout" />
+* @example
+* <Input type="number" size="sm" defaultValue={512} />
+*/
+const Input$1 = React.forwardRef(function Input$2({ className, size, ...elementProps }, ref) {
+	const inGroup = React.useContext(InputGroupContext);
+	return /* @__PURE__ */ jsx(Input, {
+		ref,
+		"data-slot": "input",
+		className: cn(inGroup ? bareControlClasses : controlVariants({ size }), className),
+		...elementProps
+	});
+});
+//#endregion
+export { Input$1 as Input };

package/dist/forms/multi-select.d.ts

@@ -0,0 +1,62 @@
+import { FormControlSize } from "./_chassis.js";
+import { ComboboxOption } from "./combobox.js";
+import * as React from "react";
+//#region src/forms/multi-select.d.ts
+interface MultiSelectProps {
+  /** The rows, in display order. Base UI filters them against what is typed. */
+  items: readonly ComboboxOption[];
+  /** Selected values. Use with `onValueChange` for a controlled field. */
+  value?: readonly string[];
+  /** Initially selected values for an uncontrolled field. */
+  defaultValue?: readonly string[];
+  /** Called with the full selection after every add or remove. */
+  onValueChange?: (value: string[]) => void;
+  /** Shown while nothing is selected — suppressed once chips fill the field. */
+  placeholder?: string;
+  /** Shown in place of the list when the query matches nothing. */
+  emptyMessage?: React.ReactNode;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Prevent opening and grey the field out. */
+  disabled?: boolean;
+  /** Require at least one value before the owning form submits. */
+  required?: boolean;
+  /** Name for the hidden input, when the field is part of a form. */
+  name?: string;
+  /** Id forwarded to the text input. */
+  id?: string;
+  /** Accessible name for the input, when no {@link FieldLabel} names it. */
+  "aria-label"?: string;
+  /** Id of the element naming the input. */
+  "aria-labelledby"?: string;
+  /**
+   * Accessible name for a chip's remove button, given the row's label. Defaults
+   * to ``(label) => `Remove ${label}` ``.
+   */
+  removeLabel?: (label: string) => string;
+  /** Extra classes for the field. */
+  className?: string;
+  /** Extra classes for the popup surface. */
+  popupClassName?: string;
+  /** Distance in px between the field and the popup. Defaults to `4`. */
+  sideOffset?: number;
+}
+/**
+ * Several values out of a known set, each shown as a removable chip.
+ *
+ * The chips live *inside* the field rather than under it, which is what makes
+ * the control honest about its own size: a selection of nine trusses is visibly
+ * nine trusses tall, and nothing is hidden behind a "+6 more" the user has to
+ * open something to read. That is also why the field takes `min-h-control-*`
+ * instead of a fixed height.
+ *
+ * Backspace in an empty input removes the last chip and the chips themselves are
+ * arrow-key navigable — both come from Base UI's `Combobox.Chips`, and both are
+ * the parts hand-rolled multi-selects forget.
+ *
+ * @example
+ * <MultiSelect aria-label="Trusses" items={trusses} value={picked} onValueChange={setPicked} />
+ */
+declare const MultiSelect: React.ForwardRefExoticComponent<MultiSelectProps & React.RefAttributes<HTMLInputElement>>;
+//#endregion
+export { MultiSelect, MultiSelectProps };

package/dist/forms/multi-select.js

@@ -0,0 +1,107 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlSurface } from "./_chassis.js";
+import { useCuePortalProps } from "../system/portal.js";
+import { CrossGlyph, TickGlyph } from "./_glyphs.js";
+import { chipFieldClasses, chipRemoveClasses, listboxEmptyClasses, listboxIndicatorClasses, listboxItemClasses, listboxListClasses, listboxPopupClasses, listboxPositionerClasses, valueChipClasses } from "./_listbox.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Combobox } from "@base-ui/react/combobox";
+//#region src/forms/multi-select.tsx
+/** Horizontal padding and type size per rung; the height comes from the chips. */
+const FIELD_SIZES = {
+	sm: "min-h-control-sm px-(--cue-space-2) text-(length:--cue-text-label)",
+	md: "min-h-control-md px-(--cue-space-3) text-(length:--cue-text-ui)",
+	lg: "min-h-control-lg px-(--cue-space-4) text-(length:--cue-text-body)"
+};
+/**
+* Several values out of a known set, each shown as a removable chip.
+*
+* The chips live *inside* the field rather than under it, which is what makes
+* the control honest about its own size: a selection of nine trusses is visibly
+* nine trusses tall, and nothing is hidden behind a "+6 more" the user has to
+* open something to read. That is also why the field takes `min-h-control-*`
+* instead of a fixed height.
+*
+* Backspace in an empty input removes the last chip and the chips themselves are
+* arrow-key navigable — both come from Base UI's `Combobox.Chips`, and both are
+* the parts hand-rolled multi-selects forget.
+*
+* @example
+* <MultiSelect aria-label="Trusses" items={trusses} value={picked} onValueChange={setPicked} />
+*/
+const MultiSelect = React.forwardRef(function MultiSelect({ items, value, defaultValue, onValueChange, placeholder, emptyMessage = "No matches", size = "md", disabled, required, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, removeLabel = (label) => `Remove ${label}`, className, popupClassName, sideOffset = 4 }, ref) {
+	const portalProps = useCuePortalProps();
+	const resolve = React.useCallback((keys) => keys === void 0 ? void 0 : keys.map((key) => items.find((item) => item.value === key)).filter((item) => item !== void 0), [items]);
+	const handleValueChange = React.useCallback((next) => {
+		onValueChange?.(next.map((item) => item.value));
+	}, [onValueChange]);
+	return /* @__PURE__ */ jsxs(Combobox.Root, {
+		multiple: true,
+		items,
+		value: resolve(value),
+		defaultValue: resolve(defaultValue),
+		onValueChange: onValueChange === void 0 ? void 0 : handleValueChange,
+		disabled,
+		required,
+		name,
+		children: [/* @__PURE__ */ jsx(Combobox.InputGroup, {
+			"data-slot": "multi-select-group",
+			className: cn(controlSurface, FIELD_SIZES[size], controlGroupFocusClasses, className),
+			children: /* @__PURE__ */ jsx(Combobox.Chips, {
+				className: chipFieldClasses,
+				children: /* @__PURE__ */ jsx(Combobox.Value, { children: (selected) => /* @__PURE__ */ jsxs(React.Fragment, { children: [selected.map((item) => /* @__PURE__ */ jsxs(Combobox.Chip, {
+					"data-slot": "multi-select-chip",
+					className: valueChipClasses,
+					children: [/* @__PURE__ */ jsx("span", {
+						className: "truncate",
+						children: item.label
+					}), /* @__PURE__ */ jsx(Combobox.ChipRemove, {
+						"aria-label": removeLabel(item.label),
+						className: chipRemoveClasses,
+						children: /* @__PURE__ */ jsx(CrossGlyph, { className: "size-icon-sm" })
+					})]
+				}, item.value)), /* @__PURE__ */ jsx(Combobox.Input, {
+					ref,
+					id,
+					"data-slot": "multi-select-input",
+					placeholder: selected.length > 0 ? "" : placeholder,
+					"aria-label": ariaLabel,
+					"aria-labelledby": ariaLabelledBy,
+					className: cn(bareControlClasses, "h-control-sm w-auto min-w-[6ch]")
+				})] }) })
+			})
+		}), /* @__PURE__ */ jsx(Combobox.Portal, {
+			...portalProps,
+			children: /* @__PURE__ */ jsx(Combobox.Positioner, {
+				className: listboxPositionerClasses,
+				sideOffset,
+				children: /* @__PURE__ */ jsxs(Combobox.Popup, {
+					"data-slot": "multi-select-popup",
+					className: cn(listboxPopupClasses, popupClassName),
+					children: [/* @__PURE__ */ jsx(Combobox.Empty, {
+						className: listboxEmptyClasses,
+						children: emptyMessage
+					}), /* @__PURE__ */ jsx(Combobox.List, {
+						className: listboxListClasses,
+						children: (item) => /* @__PURE__ */ jsxs(Combobox.Item, {
+							value: item,
+							disabled: item.disabled,
+							"data-slot": "multi-select-item",
+							className: listboxItemClasses,
+							children: [/* @__PURE__ */ jsx("span", {
+								className: listboxIndicatorClasses,
+								children: /* @__PURE__ */ jsx(Combobox.ItemIndicator, { children: /* @__PURE__ */ jsx(TickGlyph, { className: "size-icon-sm" }) })
+							}), /* @__PURE__ */ jsx("span", {
+								className: "truncate",
+								children: item.label
+							})]
+						}, item.value)
+					})]
+				})
+			})
+		})]
+	});
+});
+//#endregion
+export { MultiSelect };