@cueplusplus/ui 0.1.0

package/dist/flow/use-flow-theme.js

@@ -0,0 +1,109 @@
+"use client";
+import { ThemeContext } from "../system/theme-provider.js";
+import { FLOW_NODE_FRAME_PROPERTY, flowFrameColor } from "./_frame.js";
+import { SignalEdge } from "./signal-edge.js";
+import * as React from "react";
+//#region src/flow/use-flow-theme.ts
+/**
+* React Flow paints its own chrome — edges, handles, controls, the minimap, the
+* selection box — from a documented set of `--xy-*` custom properties, each one
+* consulted before the library's built-in default. Mapping that set onto this
+* system's tokens is the whole theme: no wrapper components, no props threaded
+* through a graph, and a theme, mode or density switch that costs nothing
+* because every value is a *reference*, re-resolved by the browser.
+*
+* The map is published two ways, and they are checked against each other
+* (`test/flow/flow-css.test.ts`):
+*
+* - as this object, to spread on the canvas: `<ReactFlow style={theme.style}>`;
+* - as the `.react-flow` block of `flow.css`, for apps that would rather import
+*   a stylesheet than thread a prop.
+*
+* Either is enough. Both is harmless.
+*/
+const FLOW_THEME_VARIABLES = Object.freeze({
+	"--xy-background-color": "var(--cue-bg)",
+	"--xy-background-pattern-color": "var(--cue-surface-2)",
+	"--xy-edge-stroke": "var(--cue-border-strong)",
+	"--xy-edge-stroke-width": "1.5",
+	"--xy-edge-stroke-selected": "var(--cue-fg)",
+	"--xy-connectionline-stroke": "var(--cue-accent)",
+	"--xy-connectionline-stroke-width": "1.5",
+	"--xy-edge-label-background-color": "var(--cue-surface-2)",
+	"--xy-edge-label-color": "var(--cue-fg)",
+	"--xy-handle-background-color": "var(--cue-accent)",
+	"--xy-handle-border-color": "var(--cue-bg)",
+	"--xy-node-background-color": "var(--cue-surface-1)",
+	"--xy-node-border": "1px solid var(--cue-border)",
+	"--xy-node-border-radius": "var(--cue-radius-surface)",
+	"--xy-node-color": "var(--cue-fg)",
+	"--xy-node-group-background-color": "var(--cue-surface-2)",
+	"--xy-node-boxshadow-hover": "0 0 0 1px var(--cue-border-strong)",
+	"--xy-node-boxshadow-selected": "0 0 0 1px var(--cue-fg)",
+	"--xy-controls-button-background-color": "var(--cue-surface-2)",
+	"--xy-controls-button-background-color-hover": "var(--cue-surface-3)",
+	"--xy-controls-button-color": "var(--cue-fg-muted)",
+	"--xy-controls-button-color-hover": "var(--cue-accent)",
+	"--xy-controls-button-border-color": "var(--cue-border)",
+	"--xy-controls-box-shadow": "0 8px 24px rgba(0, 0, 0, 0.4)",
+	"--xy-minimap-background-color": "var(--cue-surface-1)",
+	"--xy-minimap-mask-background-color": "color-mix(in oklch, var(--cue-bg) 70%, transparent)",
+	"--xy-minimap-mask-stroke-color": "var(--cue-border)",
+	"--xy-minimap-node-background-color": "var(--cue-surface-3)",
+	"--xy-minimap-node-stroke-color": "var(--cue-border)",
+	"--xy-selection-background-color": "var(--cue-accent-soft)",
+	"--xy-selection-border": "1px dashed var(--cue-accent)",
+	"--xy-resize-background-color": "var(--cue-accent)",
+	"--xy-attribution-background-color": "color-mix(in oklch, var(--cue-bg) 70%, transparent)"
+});
+/** Frame colour per node kind, ready to put on a React Flow node's `style`. */
+const NODE_STYLES = Object.freeze({
+	input: { [FLOW_NODE_FRAME_PROPERTY]: flowFrameColor("input") },
+	output: { [FLOW_NODE_FRAME_PROPERTY]: flowFrameColor("output") },
+	processing: { [FLOW_NODE_FRAME_PROPERTY]: flowFrameColor("processing") }
+});
+/**
+* `edgeTypes` for `<ReactFlow>`.
+*
+* A module constant, not a fresh object: React Flow re-registers every edge when
+* this changes identity, and warns in the console about exactly this mistake.
+*/
+const EDGE_TYPES = Object.freeze({ signal: SignalEdge });
+/** `defaultEdgeOptions`: every edge is a signal edge unless it says otherwise. */
+const DEFAULT_EDGE_OPTIONS = Object.freeze({
+	type: "signal",
+	interactionWidth: 16
+});
+/**
+* Everything a `<ReactFlow>` needs to look like it belongs to this system.
+*
+* @example
+* const theme = useFlowTheme();
+* <ReactFlow
+*   nodes={nodes}
+*   edges={edges}
+*   nodeTypes={nodeTypes}
+*   edgeTypes={theme.edgeTypes}
+*   defaultEdgeOptions={theme.defaultEdgeOptions}
+*   colorMode={theme.colorMode}
+*   style={theme.style}
+* >
+*   <FlowBackground />
+*   <FlowControls />
+* </ReactFlow>
+* @example
+* // Colour a whole class of nodes at once — the cards inherit the frame.
+* const nodes = inputs.map((input) => ({ ...input, style: theme.nodeStyles.input }));
+*/
+function useFlowTheme() {
+	const colorMode = React.useContext(ThemeContext)?.resolvedMode ?? "dark";
+	return React.useMemo(() => ({
+		colorMode,
+		style: FLOW_THEME_VARIABLES,
+		edgeTypes: EDGE_TYPES,
+		defaultEdgeOptions: DEFAULT_EDGE_OPTIONS,
+		nodeStyles: NODE_STYLES
+	}), [colorMode]);
+}
+//#endregion
+export { FLOW_THEME_VARIABLES, useFlowTheme };

package/dist/forms/_chassis.d.ts

@@ -0,0 +1,64 @@
+import { ClassProp, VariantProps } from "../lib/cva.js";
+//#region src/forms/_chassis.d.ts
+/**
+ * The rung of the density control ladder a form control sits on.
+ *
+ * Named `FormControlSize` rather than `ControlSize` because
+ * `@cueplusplus/ui/system` already exports a `ControlSize` for
+ * `useControlHeight`, and the root barrel re-exports both.
+ */
+type FormControlSize = "sm" | "md" | "lg";
+/**
+ * Everything the recessed control chassis paints except the box itself.
+ *
+ * Split out from the size rung so controls that own their own geometry — a
+ * `<textarea>` that must grow, a `NumberField.Group` that packs two buttons and
+ * an input into one rim — can reuse the surface without fighting a height or a
+ * horizontal padding they do not want.
+ *
+ * Inputs are **recessed**: `bg-sunken` sets them *into* the panel rather than
+ * raising them off it, which is the portfolio-wide convention for anything the
+ * user types into.
+ *
+ * `focus-visible:outline-solid` re-declares the outline style the sibling
+ * `outline-none` switched off — see the note on `buttonChassis`.
+ */
+declare const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger";
+/**
+ * The full recessed-control recipe, one variant per rung of the control ladder.
+ *
+ * Height, horizontal padding and text size move together — a control that is
+ * one rung shorter also needs to be one rung tighter and one rung smaller, or
+ * the glyphs collide with the rim.
+ *
+ * @example
+ * <input className={cn(controlVariants({ size: "sm" }), className)} />
+ */
+declare const controlVariants: (props?: ({
+  size?: "sm" | "md" | "lg" | null | undefined;
+} & ClassProp) | undefined) => string;
+/** `size` prop shape shared by every control that rides the chassis. */
+type ControlVariantProps = VariantProps<typeof controlVariants>;
+/**
+ * The chassis at its default `md` rung — the exact class list the spec pins for
+ * a plain form control. Kept as a derived constant, never a second copy, so the
+ * recipe cannot drift from {@link controlVariants}.
+ */
+declare const controlClasses: string;
+/**
+ * Ink for a control nested inside something that already paints the rim (an
+ * `InputGroup`, a `NumberField.Group`).
+ *
+ * Strips the box entirely — no border, no fill, no padding, no height — and
+ * inherits the font size from the wrapper so the two never disagree about which
+ * density rung they are on.
+ */
+declare const bareControlClasses = "min-w-0 flex-1 border-0 bg-transparent p-0 font-mono text-[length:inherit] text-fg placeholder:text-fg-subtle outline-none disabled:opacity-40";
+/**
+ * Focus feedback for a wrapper that owns the rim on behalf of an inner control.
+ * A `<div>` never matches `:focus-visible`, so the group has to watch its
+ * descendants instead.
+ */
+declare const controlGroupFocusClasses = "focus-within:border-accent focus-within:outline-2 focus-within:outline-solid focus-within:outline-offset-1 focus-within:outline-accent";
+//#endregion
+export { ControlVariantProps, FormControlSize, bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/forms/_chassis.js

@@ -0,0 +1,59 @@
+import { cva } from "../lib/cva.js";
+//#region src/forms/_chassis.ts
+/**
+* Everything the recessed control chassis paints except the box itself.
+*
+* Split out from the size rung so controls that own their own geometry — a
+* `<textarea>` that must grow, a `NumberField.Group` that packs two buttons and
+* an input into one rim — can reuse the surface without fighting a height or a
+* horizontal padding they do not want.
+*
+* Inputs are **recessed**: `bg-sunken` sets them *into* the panel rather than
+* raising them off it, which is the portfolio-wide convention for anything the
+* user types into.
+*
+* `focus-visible:outline-solid` re-declares the outline style the sibling
+* `outline-none` switched off — see the note on `buttonChassis`.
+*/
+const controlSurface = "w-full rounded-(--radius-control) border border-border bg-sunken font-mono text-fg placeholder:text-fg-subtle outline-none focus:border-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:opacity-40 data-[disabled]:opacity-40 data-[invalid]:border-danger";
+/**
+* The full recessed-control recipe, one variant per rung of the control ladder.
+*
+* Height, horizontal padding and text size move together — a control that is
+* one rung shorter also needs to be one rung tighter and one rung smaller, or
+* the glyphs collide with the rim.
+*
+* @example
+* <input className={cn(controlVariants({ size: "sm" }), className)} />
+*/
+const controlVariants = cva(controlSurface, {
+	variants: { size: {
+		sm: "h-control-sm px-(--cue-space-3) text-(length:--cue-text-label)",
+		md: "h-control-md px-(--cue-space-4) text-(length:--cue-text-ui)",
+		lg: "h-control-lg px-(--cue-space-5) text-(length:--cue-text-body)"
+	} },
+	defaultVariants: { size: "md" }
+});
+/**
+* The chassis at its default `md` rung — the exact class list the spec pins for
+* a plain form control. Kept as a derived constant, never a second copy, so the
+* recipe cannot drift from {@link controlVariants}.
+*/
+const controlClasses = controlVariants();
+/**
+* Ink for a control nested inside something that already paints the rim (an
+* `InputGroup`, a `NumberField.Group`).
+*
+* Strips the box entirely — no border, no fill, no padding, no height — and
+* inherits the font size from the wrapper so the two never disagree about which
+* density rung they are on.
+*/
+const bareControlClasses = "min-w-0 flex-1 border-0 bg-transparent p-0 font-mono text-[length:inherit] text-fg placeholder:text-fg-subtle outline-none disabled:opacity-40";
+/**
+* Focus feedback for a wrapper that owns the rim on behalf of an inner control.
+* A `<div>` never matches `:focus-visible`, so the group has to watch its
+* descendants instead.
+*/
+const controlGroupFocusClasses = "focus-within:border-accent focus-within:outline-2 focus-within:outline-solid focus-within:outline-offset-1 focus-within:outline-accent";
+//#endregion
+export { bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants };

package/dist/forms/_glyphs.js

@@ -0,0 +1,143 @@
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/forms/_glyphs.tsx
+/**
+* Shared form glyphs.
+*
+* Drawn inline rather than pulled from `lucide-react`, for the same reason as
+* `chrome/_glyphs.tsx`, `layout/_glyphs.tsx` and `overlays/_glyphs.tsx`: a caret
+* on a combobox and a tick on a chosen row should not put an icon dependency on
+* the render path of every form, and hand-set strokes stay hairline-thin at the
+* 8–12px sizes console density asks for. `currentColor` everywhere — the tone
+* comes from the parent.
+*
+* @internal Not part of the public API.
+*/
+/** A caret pair — one glyph that says "this opens downward and closes upward". */
+function CaretGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "currentColor",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "M11 10H5l3 3.5zm0-4H5l3-3.5z" })
+	});
+}
+/** The tick marking a chosen row. */
+function TickGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m3 8.5 3.5 3.5L13 4.5" })
+	});
+}
+/** A cross, not an "x" glyph, so it stays square at 8px. Clears and removes. */
+function CrossGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.75",
+		strokeLinecap: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m4 4 8 8M12 4l-8 8" })
+	});
+}
+/** A magnifier at hairline weight, sized to the density icon token by the caller. */
+function SearchGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.75",
+		strokeLinecap: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("circle", {
+			cx: "7",
+			cy: "7",
+			r: "4.5"
+		}), /* @__PURE__ */ jsx("path", { d: "m10.5 10.5 3 3" })]
+	});
+}
+/** An open eye: the value is currently legible. */
+function EyeGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("path", { d: "M1.5 8S4 3.5 8 3.5 14.5 8 14.5 8 12 12.5 8 12.5 1.5 8 1.5 8Z" }), /* @__PURE__ */ jsx("circle", {
+			cx: "8",
+			cy: "8",
+			r: "2"
+		})]
+	});
+}
+/** The same eye with a stroke through it: the value is masked. */
+function EyeOffGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("path", { d: "M6.2 4A6.5 6.5 0 0 1 8 3.5C12 3.5 14.5 8 14.5 8a12 12 0 0 1-2.3 2.7M9.8 12a6.5 6.5 0 0 1-1.8.5C4 12.5 1.5 8 1.5 8A12 12 0 0 1 4.4 4.8" }),
+			/* @__PURE__ */ jsx("path", { d: "M6.6 6.6a2 2 0 0 0 2.8 2.8" }),
+			/* @__PURE__ */ jsx("path", { d: "m2.5 2.5 11 11" })
+		]
+	});
+}
+/**
+* A filled five-point star, the rating mark. Solid rather than outlined: at 12px
+* an outlined star is a smudge, and the difference between "on" and "off" has to
+* survive a glance.
+*/
+function StarGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "currentColor",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m8 1.6 1.9 4 4.4.6-3.2 3.1.8 4.3L8 11.6l-3.9 2 .8-4.3L1.7 6.2l4.4-.6z" })
+	});
+}
+/**
+* `{x}` — the mathematician's variable, the mark on an environment-variable
+* reference. Reads as "a name that stands for something else", which is exactly
+* what `env(NAME)` is.
+*/
+function VariableGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("path", { d: "M5.5 2.5A2.5 2.5 0 0 0 4 4.8v1.4L2.5 8 4 9.8v1.4a2.5 2.5 0 0 0 1.5 2.3" }),
+			/* @__PURE__ */ jsx("path", { d: "M10.5 2.5A2.5 2.5 0 0 1 12 4.8v1.4L13.5 8 12 9.8v1.4a2.5 2.5 0 0 1-1.5 2.3" }),
+			/* @__PURE__ */ jsx("path", { d: "m6.8 6.4 2.4 3.2m0-3.2-2.4 3.2" })
+		]
+	});
+}
+//#endregion
+export { CaretGlyph, CrossGlyph, EyeGlyph, EyeOffGlyph, SearchGlyph, StarGlyph, TickGlyph, VariableGlyph };

package/dist/forms/_listbox.js

@@ -0,0 +1,55 @@
+import { overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses } from "../overlays/_surface.js";
+//#region src/forms/_listbox.ts
+/**
+* The shared skin of every filterable list in this group — `Combobox`,
+* `Autocomplete`, `MultiSelect`, `TagsInput`.
+*
+* All four are the same shape: a control-chassis input that opens a portalled
+* listbox. Encoding the surface once is what keeps them from drifting apart, and
+* it borrows the overlay language from `overlays/_surface.ts` rather than
+* restating it, so "what a floating surface looks like" stays a single decision.
+*
+* @internal Not part of the public API.
+*/
+/** The positioner: a layout box owning the stacking context, nothing painted. */
+const listboxPositionerClasses = overlayPositionerClasses;
+/**
+* The popup: overlay surface, anchored to the trigger's width, capped at the
+* space the positioner reports so a long list scrolls instead of overflowing the
+* viewport.
+*/
+const listboxPopupClasses = `${overlaySurfaceClasses} ${overlayPopupTransitionClasses} w-(--anchor-width) max-w-(--available-width) overflow-hidden py-(--cue-space-1) outline-none`;
+/** The scroll container inside the popup. */
+const listboxListClasses = "max-h-[min(var(--available-height),18rem)] overflow-y-auto overscroll-contain outline-none";
+/**
+* One row. `data-highlighted` — not `:hover` — carries the tint, so keyboard
+* navigation and the pointer agree on which row is active, and the tint is
+* `accent-soft` rather than a solid fill (the luma defect ruling).
+*/
+const listboxItemClasses = "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";
+/** The "nothing matched" line: same rhythm as a row, but muted and unreachable. */
+const listboxEmptyClasses = "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg-subtle select-none";
+/** The tick gutter, always reserved so labels never jog sideways. */
+const listboxIndicatorClasses = "flex size-icon-sm shrink-0 items-center justify-center";
+/**
+* A multi-value control grows with its chips, so it takes the chassis' fill,
+* rim and radius but sets its own vertical rhythm — a fixed `h-control-*` would
+* clip the second row of chips.
+*/
+const chipFieldClasses = "flex w-full cursor-text flex-wrap items-center gap-(--cue-space-1) py-(--cue-space-1)";
+/**
+* A value chip inside the field: the `h-chip` token and the tinted-neutral
+* colours of `chipVariants`, but *not* that recipe.
+*
+* `Chip` is uppercase and wide-tracked because it labels a *state* — `ONLINE`,
+* `FAULT`. A chip here holds user data (a truss name, a tag), and uppercasing
+* user data throws away information the user typed on purpose. Same shape, same
+* palette, ordinary casing.
+*/
+const valueChipClasses = "group/chip inline-flex h-chip max-w-full min-w-0 cursor-default items-center gap-(--cue-space-1) rounded-(--radius-control) border border-border bg-surface-2 py-0 pr-(--cue-space-1) pl-(--cue-space-2) font-mono text-(length:--cue-text-label) leading-none text-fg-muted outline-none select-none data-[highlighted]:border-accent/60 data-[highlighted]:text-fg focus-within:border-accent/60 focus-within:text-fg";
+/** The chip's remove affordance. */
+const chipRemoveClasses = "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";
+/** The trailing caret / clear affordance beside a filterable input. */
+const listboxAdornmentClasses = "flex 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";
+//#endregion
+export { chipFieldClasses, chipRemoveClasses, listboxAdornmentClasses, listboxEmptyClasses, listboxIndicatorClasses, listboxItemClasses, listboxListClasses, listboxPopupClasses, listboxPositionerClasses, valueChipClasses };

package/dist/forms/autocomplete.d.ts

@@ -0,0 +1,61 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+//#region src/forms/autocomplete.d.ts
+interface AutocompleteProps {
+  /** The suggestions, filtered against what is typed. */
+  items: readonly string[];
+  /** Current text. Use with `onValueChange` for a controlled field. */
+  value?: string;
+  /** Initial text for an uncontrolled field. */
+  defaultValue?: string;
+  /** Fired on every keystroke and when a suggestion is picked. */
+  onValueChange?: (value: string) => void;
+  /** Shown while the field is empty. */
+  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;
+  /** Highlight the first match automatically so Enter accepts it. */
+  autoHighlight?: boolean;
+  /** Prevent opening and grey the field out. */
+  disabled?: boolean;
+  /** Require text before the owning form submits. */
+  required?: boolean;
+  /** Name for the input, when the field is part of a form. */
+  name?: string;
+  /** Id forwarded to the 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 the clear button. Defaults to `"Clear"`. */
+  clearLabel?: 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;
+}
+/**
+ * A text field that suggests as you type — and accepts what you typed anyway.
+ *
+ * The counterpart to {@link Combobox}: there the list *is* the set of legal
+ * values, here it is only a shortcut. Anything the user types survives blur, so
+ * this is the right control for a name, a search term or a host — anywhere the
+ * suggestions are a convenience rather than a constraint.
+ *
+ * Suggestions are plain strings for the same reason: an autocomplete has no
+ * separate value/label axis, because the label *is* the value.
+ *
+ * The popup is portalled through {@link useCuePortalProps}, so it carries the
+ * caller's `data-theme` / `data-density` / `data-mode`.
+ *
+ * @example
+ * <Autocomplete aria-label="Cue name" items={recentCues} onValueChange={setName} />
+ */
+declare const Autocomplete: React.ForwardRefExoticComponent<AutocompleteProps & React.RefAttributes<HTMLInputElement>>;
+//#endregion
+export { Autocomplete, AutocompleteProps };

package/dist/forms/autocomplete.js

@@ -0,0 +1,88 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlVariants } from "./_chassis.js";
+import { useCuePortalProps } from "../system/portal.js";
+import { CrossGlyph } from "./_glyphs.js";
+import { listboxAdornmentClasses, listboxEmptyClasses, listboxItemClasses, listboxListClasses, listboxPopupClasses, listboxPositionerClasses } from "./_listbox.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Autocomplete } from "@base-ui/react/autocomplete";
+//#region src/forms/autocomplete.tsx
+/**
+* A text field that suggests as you type — and accepts what you typed anyway.
+*
+* The counterpart to {@link Combobox}: there the list *is* the set of legal
+* values, here it is only a shortcut. Anything the user types survives blur, so
+* this is the right control for a name, a search term or a host — anywhere the
+* suggestions are a convenience rather than a constraint.
+*
+* Suggestions are plain strings for the same reason: an autocomplete has no
+* separate value/label axis, because the label *is* the value.
+*
+* The popup is portalled through {@link useCuePortalProps}, so it carries the
+* caller's `data-theme` / `data-density` / `data-mode`.
+*
+* @example
+* <Autocomplete aria-label="Cue name" items={recentCues} onValueChange={setName} />
+*/
+const Autocomplete$1 = React.forwardRef(function Autocomplete$2({ items, value, defaultValue, onValueChange, placeholder, emptyMessage = "No matches", size, autoHighlight = false, disabled, required, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, clearLabel = "Clear", className, popupClassName, sideOffset = 4 }, ref) {
+	const portalProps = useCuePortalProps();
+	const handleValueChange = React.useCallback((next) => {
+		onValueChange?.(next);
+	}, [onValueChange]);
+	return /* @__PURE__ */ jsxs(Autocomplete.Root, {
+		items,
+		value,
+		defaultValue,
+		onValueChange: onValueChange === void 0 ? void 0 : handleValueChange,
+		autoHighlight,
+		disabled,
+		required,
+		name,
+		children: [/* @__PURE__ */ jsxs(Autocomplete.InputGroup, {
+			"data-slot": "autocomplete-group",
+			className: cn(controlVariants({ size }), "flex items-center gap-(--cue-space-2)", controlGroupFocusClasses, className),
+			children: [/* @__PURE__ */ jsx(Autocomplete.Input, {
+				ref,
+				id,
+				"data-slot": "autocomplete-input",
+				placeholder,
+				"aria-label": ariaLabel,
+				"aria-labelledby": ariaLabelledBy,
+				className: cn(bareControlClasses, "truncate")
+			}), /* @__PURE__ */ jsx(Autocomplete.Clear, {
+				"aria-label": clearLabel,
+				"data-slot": "autocomplete-clear",
+				className: listboxAdornmentClasses,
+				children: /* @__PURE__ */ jsx(CrossGlyph, { className: "size-icon-sm" })
+			})]
+		}), /* @__PURE__ */ jsx(Autocomplete.Portal, {
+			...portalProps,
+			children: /* @__PURE__ */ jsx(Autocomplete.Positioner, {
+				className: listboxPositionerClasses,
+				sideOffset,
+				children: /* @__PURE__ */ jsxs(Autocomplete.Popup, {
+					"data-slot": "autocomplete-popup",
+					className: cn(listboxPopupClasses, popupClassName),
+					children: [/* @__PURE__ */ jsx(Autocomplete.Empty, {
+						className: listboxEmptyClasses,
+						children: emptyMessage
+					}), /* @__PURE__ */ jsx(Autocomplete.List, {
+						className: listboxListClasses,
+						children: (item) => /* @__PURE__ */ jsx(Autocomplete.Item, {
+							value: item,
+							"data-slot": "autocomplete-item",
+							className: listboxItemClasses,
+							children: /* @__PURE__ */ jsx("span", {
+								className: "truncate",
+								children: item
+							})
+						}, item)
+					})]
+				})
+			})
+		})]
+	});
+});
+//#endregion
+export { Autocomplete$1 as Autocomplete };

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

@@ -0,0 +1,47 @@
+import * as React from "react";
+//#region src/forms/button-group.d.ts
+/** Which way a {@link ButtonGroup} runs. */
+type ButtonGroupOrientation = "horizontal" | "vertical";
+interface ButtonGroupProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Which way the children run. Defaults to `"horizontal"`. */
+  orientation?: ButtonGroupOrientation;
+  /**
+   * Join the children into one control (shared rims, outer corners only).
+   * Defaults to `true`; pass `false` for a merely-adjacent row of buttons that
+   * should still be announced as one group.
+   */
+  attached?: boolean;
+  /**
+   * Accessible name for the cluster. A group of buttons with no name is a group
+   * of buttons; with one it is "Blend mode".
+   */
+  "aria-label"?: string;
+  /** The buttons — {@link Button}, {@link IconButton} or anything button-shaped. */
+  children: React.ReactNode;
+}
+/**
+ * Several related actions drawn as one control.
+ *
+ * Purely presentational: it owns no state and imposes no roving focus, because
+ * its members are *actions*, each independently reachable by Tab. When the
+ * members represent a **choice** rather than actions, use {@link ToggleGroup}
+ * (several or none) or `SegmentedControl` (exactly one) — those carry the
+ * pressed-state ARIA a group of plain buttons must not fake.
+ *
+ * The children keep their own variants, so a `secondary`/`primary` pair reads as
+ * "and here is the one you probably want" without any extra API.
+ *
+ * @example
+ * <ButtonGroup aria-label="Blend mode">
+ *   <Button>HTP</Button>
+ *   <Button variant="primary">LTP</Button>
+ * </ButtonGroup>
+ * @example
+ * <ButtonGroup aria-label="Zoom" orientation="vertical">
+ *   <IconButton aria-label="Zoom in" icon={Plus} variant="outline" />
+ *   <IconButton aria-label="Zoom out" icon={Minus} variant="outline" />
+ * </ButtonGroup>
+ */
+declare const ButtonGroup: React.ForwardRefExoticComponent<ButtonGroupProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ButtonGroup, ButtonGroupOrientation, ButtonGroupProps };