@cueplusplus/ui 0.13.0

package/dist/forms/number-field.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+import { NumberField } from "@base-ui/react/number-field";
+//#region src/forms/number-field.d.ts
+interface NumberFieldProps extends Omit<NumberField.Root.Props, "className"> {
+  /** Extra classes, merged over the group chassis. */
+  className?: string;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: "sm" | "md";
+  /** Accessible name for the decrement button. Defaults to `"Decrease"`. */
+  decrementLabel?: string;
+  /** Accessible name for the increment button. Defaults to `"Increase"`. */
+  incrementLabel?: string;
+  /** Placeholder shown while the field is empty. */
+  placeholder?: string;
+  /** Accessible name for the text control, when no {@link FieldLabel} names it. */
+  "aria-label"?: string;
+}
+/**
+ * A numeric control with explicit − / + affordances and no native spinners.
+ *
+ * Native `<input type="number">` spinners are unusable at console density — a
+ * pair of 4px arrows that only appear on hover — so this is a text input with
+ * `inputMode="numeric"` flanked by real buttons, which is also what makes it
+ * touch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,
+ * and values typed out of range are clamped to `min`/`max` on blur.
+ *
+ * The group owns the rim; the input and both buttons render bare inside it, so
+ * the whole cluster reads as one field. Focus feedback follows the group's
+ * split: the rim strengthens on `:focus-within`, and the ring waits for
+ * `:has(:focus-visible)` so a click on a stepper does not paint one.
+ *
+ * @example
+ * <NumberField aria-label="Fade time" defaultValue={3} min={0} max={600} step={0.5} />
+ * @example
+ * <Field><FieldLabel>Universe</FieldLabel><NumberField min={1} max={512} /></Field>
+ */
+declare const NumberField$1: React.ForwardRefExoticComponent<Omit<NumberFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { NumberField$1 as NumberField, NumberFieldProps };

package/dist/forms/number-field.js

@@ -0,0 +1,65 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlSurface } from "./_chassis.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { NumberField } from "@base-ui/react/number-field";
+//#region src/forms/number-field.tsx
+/** The − and + affordances: square, borderless, and quiet until hovered. */
+const stepperClasses = "flex shrink-0 items-center justify-center border-0 bg-transparent p-0 font-mono text-fg-muted leading-none select-none outline-none transition-colors hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent data-[disabled]:pointer-events-none data-[disabled]:opacity-40";
+/**
+* A numeric control with explicit − / + affordances and no native spinners.
+*
+* Native `<input type="number">` spinners are unusable at console density — a
+* pair of 4px arrows that only appear on hover — so this is a text input with
+* `inputMode="numeric"` flanked by real buttons, which is also what makes it
+* touch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,
+* and values typed out of range are clamped to `min`/`max` on blur.
+*
+* The group owns the rim; the input and both buttons render bare inside it, so
+* the whole cluster reads as one field. Focus feedback follows the group's
+* split: the rim strengthens on `:focus-within`, and the ring waits for
+* `:has(:focus-visible)` so a click on a stepper does not paint one.
+*
+* @example
+* <NumberField aria-label="Fade time" defaultValue={3} min={0} max={600} step={0.5} />
+* @example
+* <Field><FieldLabel>Universe</FieldLabel><NumberField min={1} max={512} /></Field>
+*/
+const NumberField$1 = React.forwardRef(function NumberField$2({ className, size = "md", decrementLabel = "Decrease", incrementLabel = "Increase", placeholder, "aria-label": ariaLabel, ...elementProps }, ref) {
+	const rung = size === "sm" ? "sm" : "md";
+	return /* @__PURE__ */ jsx(NumberField.Root, {
+		ref,
+		"data-slot": "number-field",
+		...elementProps,
+		children: /* @__PURE__ */ jsxs(NumberField.Group, {
+			"data-slot": "number-field-group",
+			className: cn(controlSurface, "flex items-stretch overflow-hidden", rung === "sm" ? "h-control-sm text-(length:--cue-text-label)" : "h-control-md text-(length:--cue-text-ui)", controlGroupFocusClasses, className),
+			children: [
+				/* @__PURE__ */ jsx(NumberField.Decrement, {
+					"aria-label": decrementLabel,
+					className: cn(stepperClasses, rung === "sm" ? "w-control-sm" : "w-control-md"),
+					children: /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						children: "−"
+					})
+				}),
+				/* @__PURE__ */ jsx(NumberField.Input, {
+					"aria-label": ariaLabel,
+					placeholder,
+					className: cn(bareControlClasses, "w-full px-(--cue-space-2) text-center tabular-nums", "[appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none")
+				}),
+				/* @__PURE__ */ jsx(NumberField.Increment, {
+					"aria-label": incrementLabel,
+					className: cn(stepperClasses, rung === "sm" ? "w-control-sm" : "w-control-md"),
+					children: /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						children: "+"
+					})
+				})
+			]
+		})
+	});
+});
+//#endregion
+export { NumberField$1 as NumberField };

package/dist/forms/otp-field.d.ts

@@ -0,0 +1,54 @@
+import { FormControlSize } from "./_chassis.js";
+import * as React from "react";
+import { OTPField } from "@base-ui/react/otp-field";
+//#region src/forms/otp-field.d.ts
+interface OTPFieldProps extends Omit<OTPField.Root.Props, "className" | "children" | "length"> {
+  /** How many characters the code has. Defaults to `6`. */
+  length?: number;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /**
+   * Insert a separator after every `groupSize` slots — `groupSize={3}` renders a
+   * six-character code as `123 456`, which is how people read one off a screen.
+   */
+  groupSize?: number;
+  /** What sits between groups. Defaults to `"–"`. Always `aria-hidden`. */
+  separator?: React.ReactNode;
+  /**
+   * Accessible name for the field. Names the group *and*, through a visually
+   * hidden `<label>`, the first slot — the ARIA pattern for a code field. Leave
+   * it off inside a {@link Field}, which supplies a real label.
+   */
+  "aria-label"?: string;
+  /** Id of the first slot. Generated when omitted, so the hidden label can target it. */
+  id?: string;
+  /**
+   * Accessible name for slot `index` (1-based here, since slot 0 is named by the
+   * field label) of `length`. Defaults to
+   * ``(index, length) => `Character ${index + 1} of ${length}` ``.
+   */
+  slotLabel?: (index: number, length: number) => string;
+  /** Extra classes for the row. */
+  className?: string;
+  /** Extra classes for every slot. */
+  slotClassName?: string;
+}
+/**
+ * A one-time code, one character per box.
+ *
+ * The boxes are not decoration: they tell the user how long the code is before
+ * they start typing, which is the whole reason this pattern beats a plain text
+ * input. Paste, arrow keys, Backspace across slot boundaries and the
+ * `one-time-code` autofill hint all come from Base UI.
+ *
+ * Slots ride the recessed chassis — sunken fill, hairline rim — so a code field
+ * reads as "type here" like every other input in the system, just squared off.
+ *
+ * @example
+ * <OTPField aria-label="Verification code" onValueComplete={submit} />
+ * @example
+ * <OTPField aria-label="Recovery code" length={8} groupSize={4} validationType="alphanumeric" />
+ */
+declare const OTPField$1: React.ForwardRefExoticComponent<Omit<OTPFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { OTPField$1 as OTPField, OTPFieldProps };

package/dist/forms/otp-field.js

@@ -0,0 +1,59 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { controlSurface } from "./_chassis.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { OTPField } from "@base-ui/react/otp-field";
+//#region src/forms/otp-field.tsx
+/** One square slot per rung of the control ladder. */
+const SLOT_SIZES = {
+	sm: "size-control-sm text-(length:--cue-text-ui)",
+	md: "size-control-md text-(length:--cue-text-body)",
+	lg: "size-control-lg text-(length:--cue-text-emphasis)"
+};
+/**
+* A one-time code, one character per box.
+*
+* The boxes are not decoration: they tell the user how long the code is before
+* they start typing, which is the whole reason this pattern beats a plain text
+* input. Paste, arrow keys, Backspace across slot boundaries and the
+* `one-time-code` autofill hint all come from Base UI.
+*
+* Slots ride the recessed chassis — sunken fill, hairline rim — so a code field
+* reads as "type here" like every other input in the system, just squared off.
+*
+* @example
+* <OTPField aria-label="Verification code" onValueComplete={submit} />
+* @example
+* <OTPField aria-label="Recovery code" length={8} groupSize={4} validationType="alphanumeric" />
+*/
+const OTPField$1 = React.forwardRef(function OTPField$2({ length = 6, size = "md", groupSize, separator = "–", "aria-label": ariaLabel, id, slotLabel = (index, total) => `Character ${index + 1} of ${total}`, className, slotClassName, ...elementProps }, ref) {
+	const generatedId = React.useId();
+	const fieldId = id ?? generatedId;
+	const slotClasses = cn(controlSurface, "w-auto p-0 text-center tabular-nums", SLOT_SIZES[size], slotClassName);
+	return /* @__PURE__ */ jsxs(OTPField.Root, {
+		ref,
+		id: fieldId,
+		length,
+		"aria-label": ariaLabel,
+		"data-slot": "otp-field",
+		className: cn("relative flex items-center gap-(--cue-space-2)", className),
+		...elementProps,
+		children: [ariaLabel === void 0 ? null : /* @__PURE__ */ jsx("label", {
+			htmlFor: fieldId,
+			className: "sr-only",
+			children: ariaLabel
+		}), Array.from({ length }, (_, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [groupSize !== void 0 && index > 0 && index % groupSize === 0 ? /* @__PURE__ */ jsx("span", {
+			"data-slot": "otp-field-separator",
+			"aria-hidden": "true",
+			className: "px-(--cue-space-1) font-mono text-fg-subtle select-none",
+			children: separator
+		}) : null, /* @__PURE__ */ jsx(OTPField.Input, {
+			"data-slot": "otp-field-slot",
+			"aria-label": index === 0 ? void 0 : slotLabel(index, length),
+			className: slotClasses
+		})] }, index))]
+	});
+});
+//#endregion
+export { OTPField$1 as OTPField };

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

@@ -0,0 +1,46 @@
+import { FormControlSize } from "./_chassis.js";
+import { InputProps } from "./input.js";
+import * as React from "react";
+//#region src/forms/password-input.d.ts
+interface PasswordInputProps extends Omit<InputProps, "type" | "size"> {
+  /** Reveal the value. Use with `onRevealedChange` for a controlled toggle. */
+  revealed?: boolean;
+  /** Initially revealed, for an uncontrolled toggle. Defaults to `false`. */
+  defaultRevealed?: boolean;
+  /** Called with the new reveal state. */
+  onRevealedChange?: (revealed: boolean) => void;
+  /**
+   * Offer the reveal affordance at all. Defaults to `true`. Switch it off for a
+   * value the product must never re-display — a stored secret the user is
+   * replacing rather than reading.
+   */
+  showReveal?: boolean;
+  /** Accessible name while masked. Defaults to `"Show password"`. */
+  revealLabel?: string;
+  /** Accessible name while revealed. Defaults to `"Hide password"`. */
+  hideLabel?: string;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Extra classes for the group that wraps the input and the reveal button. */
+  className?: string;
+}
+/**
+ * A masked text field with a reveal control.
+ *
+ * The reveal is a **toggle button carrying `aria-pressed`**, not a checkbox and
+ * not a bare icon: a screen-reader user needs to know both what it does and
+ * which way it currently is, and `aria-pressed` is the one attribute that says
+ * both. The label swaps with the state for the same reason.
+ *
+ * Revealing switches `type` between `password` and `text` rather than painting
+ * over the characters, so the browser's own autofill and password managers keep
+ * working.
+ *
+ * @example
+ * <PasswordInput aria-label="Service key" value={key} onValueChange={setKey} />
+ * @example
+ * <Field><FieldLabel>Token</FieldLabel><PasswordInput showReveal={false} /></Field>
+ */
+declare const PasswordInput: React.ForwardRefExoticComponent<Omit<PasswordInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+//#endregion
+export { PasswordInput, PasswordInputProps };

package/dist/forms/password-input.js

@@ -0,0 +1,62 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { InputGroup } from "./input-group.js";
+import { Input } from "./input.js";
+import { EyeGlyph, EyeOffGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/forms/password-input.tsx
+/**
+* A masked text field with a reveal control.
+*
+* The reveal is a **toggle button carrying `aria-pressed`**, not a checkbox and
+* not a bare icon: a screen-reader user needs to know both what it does and
+* which way it currently is, and `aria-pressed` is the one attribute that says
+* both. The label swaps with the state for the same reason.
+*
+* Revealing switches `type` between `password` and `text` rather than painting
+* over the characters, so the browser's own autofill and password managers keep
+* working.
+*
+* @example
+* <PasswordInput aria-label="Service key" value={key} onValueChange={setKey} />
+* @example
+* <Field><FieldLabel>Token</FieldLabel><PasswordInput showReveal={false} /></Field>
+*/
+const PasswordInput = React.forwardRef(function PasswordInput({ className, revealed: revealedProp, defaultRevealed = false, onRevealedChange, showReveal = true, revealLabel = "Show password", hideLabel = "Hide password", size, disabled, ...elementProps }, ref) {
+	const [uncontrolled, setUncontrolled] = React.useState(defaultRevealed);
+	const revealed = revealedProp ?? uncontrolled;
+	const toggle = React.useCallback(() => {
+		const next = !revealed;
+		if (revealedProp === void 0) setUncontrolled(next);
+		onRevealedChange?.(next);
+	}, [
+		onRevealedChange,
+		revealed,
+		revealedProp
+	]);
+	return /* @__PURE__ */ jsx(InputGroup, {
+		size,
+		className,
+		trailing: showReveal ? /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-pressed": revealed,
+			"aria-label": revealed ? hideLabel : revealLabel,
+			disabled,
+			onClick: toggle,
+			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 disabled:pointer-events-none disabled:opacity-40 aria-pressed:text-fg",
+			children: /* @__PURE__ */ jsx(revealed ? EyeOffGlyph : EyeGlyph, { className: "size-icon-md" })
+		}) : void 0,
+		children: /* @__PURE__ */ jsx(Input, {
+			ref,
+			type: revealed ? "text" : "password",
+			"data-slot": "password-input",
+			spellCheck: false,
+			disabled,
+			className: cn("[&::-ms-reveal]:hidden"),
+			...elementProps
+		})
+	});
+});
+//#endregion
+export { PasswordInput };

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

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { Radio } from "@base-ui/react/radio";
+import { RadioGroup } from "@base-ui/react/radio-group";
+//#region src/forms/radio-group.d.ts
+interface RadioGroupProps extends Omit<RadioGroup.Props, "className"> {
+  /** Extra classes, merged over the stack defaults. */
+  className?: string;
+  /** Lay the options out in a column (default) or a row. */
+  orientation?: "vertical" | "horizontal";
+}
+/**
+ * One-of-many selection: a roving-tabindex group of {@link Radio}s sharing a
+ * single value.
+ *
+ * Arrow keys move *and* select, per the WAI-ARIA radio group pattern that Base
+ * UI implements — so the whole group is one tab stop, which is what keeps a
+ * dense settings panel navigable.
+ *
+ * @example
+ * <RadioGroup aria-label="Blend mode" value={mode} onValueChange={setMode}>
+ *   <Radio value="htp" label="HTP" />
+ *   <Radio value="ltp" label="LTP" />
+ * </RadioGroup>
+ */
+declare const RadioGroup$1: React.ForwardRefExoticComponent<Omit<RadioGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface RadioProps extends Omit<Radio.Root.Props, "className"> {
+  /** Extra classes, merged over the dot defaults. */
+  className?: string;
+  /**
+   * Inline label rendered beside the dot and wrapped with it in a `<label>`, so
+   * the text is both the accessible name and part of the hit target.
+   */
+  label?: React.ReactNode;
+  /** Rung of the density icon ladder for the dot. Defaults to `"md"`. */
+  size?: "sm" | "md";
+}
+/**
+ * One option inside a {@link RadioGroup}.
+ *
+ * Round, to say "exactly one" the way a square {@link Checkbox} says "any
+ * number". Checked draws an accent rim with an accent core rather than a solid
+ * fill, so the selected option stays legible against the sunken field colour on
+ * every theme.
+ *
+ * @example
+ * <Radio value="htp" label="Highest takes precedence" />
+ */
+declare const Radio$1: React.ForwardRefExoticComponent<Omit<RadioProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+//#endregion
+export { Radio$1 as Radio, RadioGroup$1 as RadioGroup, RadioGroupProps, RadioProps };

package/dist/forms/radio-group.js

@@ -0,0 +1,64 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Radio } from "@base-ui/react/radio";
+import { RadioGroup } from "@base-ui/react/radio-group";
+//#region src/forms/radio-group.tsx
+/**
+* One-of-many selection: a roving-tabindex group of {@link Radio}s sharing a
+* single value.
+*
+* Arrow keys move *and* select, per the WAI-ARIA radio group pattern that Base
+* UI implements — so the whole group is one tab stop, which is what keeps a
+* dense settings panel navigable.
+*
+* @example
+* <RadioGroup aria-label="Blend mode" value={mode} onValueChange={setMode}>
+*   <Radio value="htp" label="HTP" />
+*   <Radio value="ltp" label="LTP" />
+* </RadioGroup>
+*/
+const RadioGroup$1 = React.forwardRef(function RadioGroup$2({ className, orientation = "vertical", ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx(RadioGroup, {
+		ref,
+		"data-slot": "radio-group",
+		"data-orientation": orientation,
+		className: cn("flex", orientation === "horizontal" ? "flex-row flex-wrap items-center gap-(--cue-space-5)" : "flex-col gap-(--cue-space-2)", className),
+		...elementProps
+	});
+});
+/**
+* One option inside a {@link RadioGroup}.
+*
+* Round, to say "exactly one" the way a square {@link Checkbox} says "any
+* number". Checked draws an accent rim with an accent core rather than a solid
+* fill, so the selected option stays legible against the sunken field colour on
+* every theme.
+*
+* @example
+* <Radio value="htp" label="Highest takes precedence" />
+*/
+const Radio$1 = React.forwardRef(function Radio$2({ className, label, size = "md", ...elementProps }, ref) {
+	const labelId = React.useId();
+	const hasLabel = label !== void 0;
+	const dot = /* @__PURE__ */ jsx(Radio.Root, {
+		ref,
+		"data-slot": "radio",
+		"aria-labelledby": hasLabel ? labelId : void 0,
+		className: cn("flex shrink-0 items-center justify-center rounded-full border border-border bg-sunken text-accent outline-none transition-colors", size === "sm" ? "size-icon-sm" : "size-icon-md", "hover:border-border-strong", "data-[checked]:border-accent", "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", "data-[disabled]:pointer-events-none data-[disabled]:opacity-40", "data-[invalid]:border-danger", className),
+		...elementProps,
+		children: /* @__PURE__ */ jsx(Radio.Indicator, { className: "block size-1/2 rounded-full bg-accent data-[unchecked]:hidden" })
+	});
+	if (!hasLabel) return dot;
+	return /* @__PURE__ */ jsxs("label", {
+		"data-slot": "radio-label",
+		className: "inline-flex cursor-pointer items-center gap-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg-muted select-none has-[[data-disabled]]:cursor-default has-[[data-disabled]]:opacity-40",
+		children: [dot, /* @__PURE__ */ jsx("span", {
+			id: labelId,
+			children: label
+		})]
+	});
+});
+//#endregion
+export { Radio$1 as Radio, RadioGroup$1 as RadioGroup };

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