@primitiv-ui/react 0.1.13 → 0.1.15

package/README.md

@@ -41,6 +41,7 @@ import { Tabs } from "@primitiv-ui/react";
 | [Modal](src/Modal/README.md)             | WAI-ARIA Modal Dialog pattern — native `<dialog>`-based compound component with Portal, bounding-rect click-outside, controlled/uncontrolled state, escape hatches, imperative API, `asChild`, and `forceMount` animation hooks                                                         |
 | [Portal](src/Portal/README.md)           | DOM-escape utility — renders children into `document.body` (or a consumer-supplied container) via `createPortal`; compose with any component that needs to break out of the current stacking context                                                                                    |
 | [Progress](src/Progress/README.md)       | WAI-ARIA progressbar pattern — display-only compound component reflecting a consumer-supplied `value`, with determinate/indeterminate states, configurable `max`, `getValueLabel` for `aria-valuetext`, `data-*` styling hooks on the fill `Indicator`, and `asChild` composition          |
+| [Radio](src/Radio/README.md)             | WAI-ARIA Radio pattern, standalone — native `<button role="radio">` with one-way single-selection state (no toggle-off), controlled/uncontrolled state, `Indicator` slot, `disabled` with `data-disabled` styling hook, and `asChild` composition; pair with your own grouping (use `RadioGroup` for managed roving-tabindex sets)                                                |
 | [RadioCard](src/RadioCard/README.md)     | WAI-ARIA Radio Group pattern in a card/tile layout — the entire card surface is the interactive element, with single-selection state, roving tabindex, arrow-key navigation, disabled-item skipping, `Indicator` slot, and `asChild` composition                                        |
 | [RadioGroup](src/RadioGroup/README.md)   | WAI-ARIA Radio Group pattern — native `<button role="radio">` items with single-selection state, roving tabindex, arrow-key navigation, disabled-item skipping, `Indicator` slot, and `asChild` composition                                                                             |
 | [Select](src/Select/README.md)           | Headless wrapper over native `<select>` / `<option>` / `<optgroup>` — controlled/uncontrolled state via `onValueChange`, `Select.Placeholder` with auto-`defaultValue` inference, `Select.Group` for optgroup labelling, `data-disabled` styling hook, `asChild` composition, and Field-aware (opts into `FieldContext` for auto-wired `id` / `aria-describedby` / `aria-invalid` / `disabled` / `required`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/react",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Headless, accessible React components built on the WAI-ARIA authoring patterns. Zero styles ship with this package — bring your own (CSS, Tailwind, CSS-in-JS, design tokens).",
   "type": "module",
   "main": "./src/index.ts",

package/src/Checkbox/__tests__/Checkbox.contract.test.tsx

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+
+import { Checkbox } from "../Checkbox";
+
+/**
+ * Auto-verification of the Checkbox styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/checkbox/contract.json` is *derived from
+ * and asserted against the rendered headless component* so it can never drift
+ * from what the component actually emits. Checkbox is tri-state: its surface is
+ * `data-state="checked" | "unchecked" | "indeterminate"` (always present) plus
+ * `data-disabled=""` when disabled. The authored half (root class, parts, custom
+ * properties) is a styling convention the headless layer does not emit and is
+ * checked by the generator drift-guards instead.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/checkbox/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+describe("Checkbox styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The Checkbox has no authored data-* surface; the whole contract is derived.
+    expect(autoAttributes).toHaveLength(contract.dataAttributes.length);
+  });
+
+  it("emits exactly the contracted data-* attribute names across its states", () => {
+    const emitted = new Set<string>();
+    for (const ui of [
+      <Checkbox.Root key="checked" checked onCheckedChange={() => {}} aria-label="x">
+        <Checkbox.Indicator />
+      </Checkbox.Root>,
+      <Checkbox.Root
+        key="indeterminate"
+        checked="indeterminate"
+        onCheckedChange={() => {}}
+        aria-label="x"
+      >
+        <Checkbox.Indicator />
+      </Checkbox.Root>,
+      <Checkbox.Root key="disabled" disabled aria-label="x">
+        <Checkbox.Indicator />
+      </Checkbox.Root>,
+    ]) {
+      const { unmount } = render(ui);
+      for (const name of dataAttributeNames(screen.getByRole("checkbox"))) {
+        emitted.add(name);
+      }
+      unmount();
+    }
+
+    const contracted = new Set(
+      autoAttributes.map((attribute: { name: string }) => attribute.name),
+    );
+    expect([...emitted].sort()).toEqual([...contracted].sort());
+  });
+
+  it("emits data-state with the documented value for each state", () => {
+    const stateEntries = autoAttributes.filter(
+      (attribute: { name: string }) => attribute.name === "data-state",
+    );
+
+    for (const entry of stateEntries) {
+      const checked =
+        entry.value === "indeterminate"
+          ? ("indeterminate" as const)
+          : entry.value === "checked";
+      const { unmount } = render(
+        <Checkbox.Root checked={checked} onCheckedChange={() => {}} aria-label="x">
+          <Checkbox.Indicator />
+        </Checkbox.Root>,
+      );
+      expect(screen.getByRole("checkbox")).toHaveAttribute("data-state", entry.value);
+      unmount();
+    }
+  });
+
+  it("emits data-disabled exactly as the contract documents it", () => {
+    const entry = autoAttributes.find(
+      (attribute: { name: string }) => attribute.name === "data-disabled",
+    );
+
+    render(
+      <Checkbox.Root disabled aria-label="x">
+        <Checkbox.Indicator />
+      </Checkbox.Root>,
+    );
+    expect(screen.getByRole("checkbox")).toHaveAttribute(entry.name, entry.value);
+  });
+
+  it("omits data-disabled when the documented condition does not hold", () => {
+    render(
+      <Checkbox.Root aria-label="x">
+        <Checkbox.Indicator />
+      </Checkbox.Root>,
+    );
+
+    expect(screen.getByRole("checkbox")).not.toHaveAttribute("data-disabled");
+  });
+});

package/src/Radio/README.md

@@ -0,0 +1,157 @@
+# Radio
+
+A headless, accessible, **standalone** compound component implementing the
+single-selection half of the
+[WAI-ARIA Radio pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+
+Radio renders a native `<button role="radio">` so it gets keyboard
+activation (`Space` / `Enter`), focus ring, and disabled semantics for free
+from the browser. The React layer adds one-way selection, `Indicator`
+mounting driven by the selected state, and the `asChild` composition every
+primitive in this package supports.
+
+> **Radio vs. RadioGroup.** `Radio` is the lone control for when you own the
+> grouping (a native form `name`, a bespoke layout, a single opt-in). For a
+> managed set with roving-tabindex keyboard navigation, arrow-key selection,
+> and disabled-item skipping, reach for
+> [`RadioGroup`](../RadioGroup/README.md) instead — it composes `role="radio"`
+> items the same way but owns the shared selected value.
+
+```tsx
+import { Radio } from "@primitiv-ui/react";
+
+<Radio.Root defaultChecked aria-label="Compact">
+  <Radio.Indicator>
+    <DotIcon />
+  </Radio.Indicator>
+</Radio.Root>;
+```
+
+## Sub-components
+
+| Export            | Element    | Notes                                                                       |
+| ----------------- | ---------- | --------------------------------------------------------------------------- |
+| `Radio.Root`      | `<button>` | `role="radio"`, `aria-checked`, `data-state`, `data-disabled`. `asChild`    |
+| `Radio.Indicator` | `<span>`   | `aria-hidden="true"`. Renders only while selected. `asChild`, `forceMount`  |
+
+## Selected state
+
+Radio is binary. The `checked` / `defaultChecked` value is a `boolean`:
+
+| Value   | `aria-checked` | `data-state`  | Indicator renders?       |
+| ------- | -------------- | ------------- | ------------------------ |
+| `true`  | `"true"`       | `"checked"`   | Yes                      |
+| `false` | `"false"`      | `"unchecked"` | No (unless `forceMount`) |
+
+Selection is **one-way**: clicking an unselected radio selects it, but
+clicking the already-selected radio is a no-op — a lone radio never toggles
+itself off, and `onCheckedChange` does not fire for a re-select. De-selection
+happens when a sibling is chosen, which is the grouping consumer's concern.
+
+## State modes
+
+- **Uncontrolled** — pass `defaultChecked` (or omit for unselected on mount).
+- **Controlled** — pass `checked` **and** `onCheckedChange` together.
+
+The two shapes are statically discriminated at the type level; TypeScript
+rejects mixing them.
+
+```tsx
+// Uncontrolled
+<Radio.Root defaultChecked>…</Radio.Root>;
+
+// Controlled — the consumer owns the group's selected value.
+const [value, setValue] = useState("comfortable");
+<Radio.Root
+  checked={value === "compact"}
+  onCheckedChange={() => setValue("compact")}
+>
+  …
+</Radio.Root>;
+```
+
+## Keyboard interaction
+
+| Key     | Behaviour                              |
+| ------- | -------------------------------------- |
+| `Space` | Selects the radio (native `<button>`)  |
+| `Enter` | Selects the radio (native `<button>`)  |
+
+Keyboard handling comes from the underlying `<button>` element — no custom
+`keydown` listeners are needed. (Arrow-key navigation across a set is a
+`RadioGroup` concern, not a standalone `Radio` one.)
+
+## Disabled
+
+Passing `disabled` forwards the native `disabled` attribute to the button
+(removing it from the tab order and suppressing clicks) **and** sets
+`data-disabled=""` on the root so CSS can target `[data-disabled]` without
+reaching for `:disabled`.
+
+```tsx
+<Radio.Root disabled aria-label="Unavailable plan">
+  <Radio.Indicator>
+    <DotIcon />
+  </Radio.Indicator>
+</Radio.Root>
+```
+
+## `asChild` composition
+
+Both `Radio.Root` and `Radio.Indicator` accept an `asChild` boolean. When
+set, the component delegates rendering to its single child element and merges
+its own ARIA attributes, data-state, composed event handlers, and ref onto
+the child (the asChild contract: the child's handler runs first, the
+library's runs second unless the child calls `preventDefault`).
+
+```tsx
+// Menu-item radio — the same state machinery, different element + role.
+<Radio.Root asChild aria-label="Sort by name">
+  <li role="menuitemradio">Sort by name</li>
+</Radio.Root>
+
+// Icon-only indicator — the svg itself becomes the indicator.
+<Radio.Indicator asChild>
+  <svg viewBox="0 0 10 10">
+    <circle cx="5" cy="5" r="3" />
+  </svg>
+</Radio.Indicator>
+```
+
+## Animation hooks
+
+`Radio.Indicator` accepts a `forceMount` boolean. When set, the indicator
+stays in the DOM regardless of selected state so a CSS animation can play
+against `data-state="unchecked"`:
+
+```tsx
+<Radio.Indicator forceMount>
+  <DotIcon />
+</Radio.Indicator>
+```
+
+```css
+[data-state="checked"] {
+  animation: dot-in 120ms ease-out;
+}
+[data-state="unchecked"] {
+  animation: dot-out 100ms ease-in forwards;
+}
+```
+
+Consumers using `forceMount` own the exit timing themselves.
+
+## Styling hooks
+
+`data-state="checked" | "unchecked"` is set on both `Radio.Root` and
+`Radio.Indicator`, letting any CSS system target both phases.
+
+```css
+button[data-state="checked"] {
+  border-color: oklch(55% 0.2 265);
+}
+button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```

package/src/Radio/Radio.tsx

@@ -0,0 +1,213 @@
+import { useMemo } from "react";
+import type { ReactElement } from "react";
+
+import { Slot, composeEventHandlers } from "../Slot/index.ts";
+
+import { RadioContext } from "./RadioContext";
+import { useRadioContext, useRadioRoot } from "./hooks/index.ts";
+import { RadioIndicatorProps, RadioRootProps } from "./types";
+
+function dataStateOf(checked: boolean) {
+  return checked ? ("checked" as const) : ("unchecked" as const);
+}
+
+/**
+ * The root of a Radio — a native `<button role="radio">` that owns a
+ * single boolean selected value and provides
+ * {@link RadioContext | `RadioContext`} to descendant
+ * {@link RadioIndicator | `Radio.Indicator`}s.
+ *
+ * Unlike a checkbox, selection is **one-way**: clicking an unselected
+ * radio selects it, but clicking the already-selected radio is a no-op —
+ * a lone radio never toggles itself off. De-selection happens when a
+ * sibling is chosen, which is the grouping consumer's concern. For a
+ * managed set with roving-tabindex keyboard navigation, reach for
+ * `RadioGroup` instead; `Radio` is the standalone control for when you
+ * own the grouping (e.g. a native form `name`, or a bespoke layout).
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link RadioRootProps.defaultChecked | `defaultChecked`} (or omit for
+ *   unselected-on-mount). The component owns the value internally.
+ * - **Controlled** — pass {@link RadioRootProps.checked | `checked`} *and*
+ *   {@link RadioRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   The parent owns the value; the component defers selection back through
+ *   the callback.
+ *
+ * **ARIA.** `role="radio"` and `aria-checked` are set automatically.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked"` on the root,
+ * plus `data-disabled=""` when disabled.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element (e.g. `<li role="menuitemradio">` for menu composition) with
+ * the radio's ARIA attributes, data-state, composed onClick, and ref
+ * merged in. The native `<button>` is dropped; consumers who want keyboard
+ * activation on a non-button element are responsible for providing it.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Radio.Root defaultChecked aria-label="Compact">
+ *   <Radio.Indicator />
+ * </Radio.Root>
+ * ```
+ *
+ * @example Controlled (consumer owns the group)
+ * ```tsx
+ * const [value, setValue] = useState("comfortable");
+ *
+ * <Radio.Root
+ *   checked={value === "compact"}
+ *   onCheckedChange={() => setValue("compact")}
+ *   aria-label="Compact"
+ * >
+ *   <Radio.Indicator />
+ * </Radio.Root>
+ * ```
+ */
+export function RadioRoot(props: RadioRootProps): ReactElement {
+  const {
+    defaultChecked,
+    checked,
+    onCheckedChange,
+    onClick,
+    disabled,
+    asChild = false,
+    children,
+    ...rest
+  } = props;
+  const { checked: isChecked, select } = useRadioRoot({
+    defaultChecked,
+    checked,
+    onCheckedChange,
+  });
+  const contextValue = useMemo(() => ({ checked: isChecked }), [isChecked]);
+  const rootProps = {
+    ...rest,
+    role: "radio" as const,
+    "aria-checked": isChecked,
+    "data-state": dataStateOf(isChecked),
+    "data-disabled": disabled ? "" : undefined,
+    disabled,
+    onClick: composeEventHandlers(onClick, select),
+  };
+  return (
+    <RadioContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...rootProps}>
+          {children}
+        </button>
+      )}
+    </RadioContext.Provider>
+  );
+}
+
+/** @internal */
+RadioRoot.displayName = "RadioRoot";
+
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children only
+ * while the parent {@link RadioRoot | `Radio.Root`} is **selected** —
+ * typically the filled dot inside a radio control. The radio's accessible
+ * state is already conveyed by `aria-checked` on the root, so the indicator
+ * is purely visual.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked"` so the same CSS rule can target
+ * both.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` dot) as the indicator itself, with `aria-hidden`
+ * and `data-state` merged onto that element rather than a wrapper.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the indicator in the
+ * DOM while unchecked so a CSS exit animation can play against
+ * `data-state="unchecked"`. Consumers who use `forceMount` own the exit
+ * lifecycle themselves.
+ *
+ * @example Default span wrapper
+ * ```tsx
+ * <Radio.Root aria-label="Compact">
+ *   <Radio.Indicator />
+ *   Compact
+ * </Radio.Root>
+ * ```
+ *
+ * @example Dot as the indicator via `asChild`
+ * ```tsx
+ * <Radio.Indicator asChild>
+ *   <svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="3" /></svg>
+ * </Radio.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `Radio.Root`.
+ */
+export function RadioIndicator({
+  children,
+  forceMount,
+  asChild = false,
+  ...rest
+}: RadioIndicatorProps): ReactElement | null {
+  const { checked } = useRadioContext();
+  if (!checked && !forceMount) return null;
+  const indicatorProps = {
+    ...rest,
+    "aria-hidden": "true" as const,
+    "data-state": dataStateOf(checked),
+  };
+  if (asChild) {
+    return <Slot {...indicatorProps}>{children}</Slot>;
+  }
+  return <span {...indicatorProps}>{children}</span>;
+}
+
+/** @internal */
+RadioIndicator.displayName = "RadioIndicator";
+
+/** Type of the {@link Radio} compound: the root callable plus its attached sub-components. */
+export type TRadioCompound = typeof RadioRoot & {
+  Root: typeof RadioRoot;
+  Indicator: typeof RadioIndicator;
+};
+
+/**
+ * Headless, accessible **Radio** — a standalone compound component built
+ * on a native `<button role="radio">` that implements the single-selection
+ * half of the
+ * [WAI-ARIA Radio pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+ * Zero styles ship.
+ *
+ * `Radio` is the lone control for when you own the grouping; for a managed
+ * set with roving-tabindex keyboard navigation use `RadioGroup`.
+ *
+ * `Radio` is both callable (an alias of {@link RadioRoot | `Radio.Root`})
+ * and carries its sub-components as static properties. Prefer the
+ * namespaced form in application code for readability and grep-ability.
+ *
+ * - {@link RadioRoot | `Radio.Root`} — state owner, context provider, select button.
+ * - {@link RadioIndicator | `Radio.Indicator`} — decorative dot, conditional on selected state.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Radio } from "@primitiv-ui/react";
+ *
+ * <Radio.Root aria-label="Compact">
+ *   <Radio.Indicator />
+ * </Radio.Root>;
+ * ```
+ *
+ * @see {@link RadioRoot} for state modes and one-way selection semantics.
+ * @see {@link RadioIndicator} for the mount gate and animation hooks.
+ */
+const RadioCompound: TRadioCompound = Object.assign(RadioRoot, {
+  Root: RadioRoot,
+  Indicator: RadioIndicator,
+});
+
+/** @internal */
+RadioCompound.displayName = "Radio";
+
+export { RadioCompound as Radio };

package/src/Radio/RadioContext.ts

@@ -0,0 +1,10 @@
+import { createStrictContext } from "../utils/index.ts";
+
+export type RadioContextValue = {
+  checked: boolean;
+};
+
+export const [RadioContext, useRadioContext] =
+  createStrictContext<RadioContextValue>(
+    "Radio sub-components must be rendered inside a <Radio.Root>.",
+  );

package/src/Radio/__tests__/Radio.asChild.test.tsx

@@ -0,0 +1,63 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio asChild composition", () => {
+  it("Root asChild delegates to the child element while keeping ARIA and select wiring", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root asChild onCheckedChange={onCheckedChange} aria-label="Compact">
+        <li>Compact</li>
+      </Radio.Root>,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert element is the consumer's <li>
+    expect(radio.tagName).toBe("LI");
+    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+
+    // Act
+    await user.click(radio);
+
+    // Assert select still fires through composed onClick
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+    expect(radio).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("Root asChild lets the consumer override the role for menu-item contexts", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root asChild aria-label="Compact">
+        <li role="menuitemradio">Compact</li>
+      </Radio.Root>,
+    );
+
+    // Assert
+    const item = screen.getByRole("menuitemradio", { name: "Compact" });
+    expect(item).toHaveAttribute("aria-checked", "false");
+    expect(item).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("Indicator asChild delegates rendering to the consumer's element", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator asChild>
+          <svg data-testid="dot" viewBox="0 0 10 10">
+            <circle cx="5" cy="5" r="3" />
+          </svg>
+        </Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    const dot = screen.getByTestId("dot");
+    expect(dot.tagName.toLowerCase()).toBe("svg");
+    expect(dot).toHaveAttribute("aria-hidden", "true");
+    expect(dot).toHaveAttribute("data-state", "checked");
+  });
+});

package/src/Radio/__tests__/Radio.basic-rendering.test.tsx

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+describe("Radio basic rendering", () => {
+  it('renders a <button> with role="radio"', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio.tagName).toBe("BUTTON");
+  });
+
+  it('defaults aria-checked to "false"', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "false");
+  });
+
+  it('defaults type="button" so the radio never submits an enclosing form', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("type", "button");
+  });
+
+  it('sets data-state="unchecked" on the root when unchecked', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+  });
+});

package/src/Radio/__tests__/Radio.contract.test.tsx

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+/**
+ * Auto-verification of the Radio styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/radio/contract.json` is *derived from
+ * and asserted against the rendered headless component* so it can never drift
+ * from what the component actually emits. Radio is binary: its surface is
+ * `data-state="checked" | "unchecked"` (always present) plus `data-disabled=""`
+ * when disabled. The authored half (root class, parts, custom properties) is a
+ * styling convention the headless layer does not emit and is checked by the
+ * generator drift-guards instead.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/radio/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+describe("Radio styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The Radio has no authored data-* surface; the whole contract is derived.
+    expect(autoAttributes).toHaveLength(contract.dataAttributes.length);
+  });
+
+  it("emits exactly the contracted data-* attribute names across its states", () => {
+    const emitted = new Set<string>();
+    for (const ui of [
+      <Radio.Root key="checked" checked onCheckedChange={() => {}} aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+      <Radio.Root key="unchecked" checked={false} onCheckedChange={() => {}} aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+      <Radio.Root key="disabled" disabled aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    ]) {
+      const { unmount } = render(ui);
+      for (const name of dataAttributeNames(screen.getByRole("radio"))) {
+        emitted.add(name);
+      }
+      unmount();
+    }
+
+    const contracted = new Set(
+      autoAttributes.map((attribute: { name: string }) => attribute.name),
+    );
+    expect([...emitted].sort()).toEqual([...contracted].sort());
+  });
+
+  it("emits data-state with the documented value for each state", () => {
+    const stateEntries = autoAttributes.filter(
+      (attribute: { name: string }) => attribute.name === "data-state",
+    );
+
+    for (const entry of stateEntries) {
+      const { unmount } = render(
+        <Radio.Root
+          checked={entry.value === "checked"}
+          onCheckedChange={() => {}}
+          aria-label="x"
+        >
+          <Radio.Indicator />
+        </Radio.Root>,
+      );
+      expect(screen.getByRole("radio")).toHaveAttribute("data-state", entry.value);
+      unmount();
+    }
+  });
+
+  it("emits data-disabled exactly as the contract documents it", () => {
+    const entry = autoAttributes.find(
+      (attribute: { name: string }) => attribute.name === "data-disabled",
+    );
+
+    render(
+      <Radio.Root disabled aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute(entry.name, entry.value);
+  });
+
+  it("omits data-disabled when the documented condition does not hold", () => {
+    render(
+      <Radio.Root aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    );
+
+    expect(screen.getByRole("radio")).not.toHaveAttribute("data-disabled");
+  });
+});

package/src/Radio/__tests__/Radio.controlled-state.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { Radio } from "../Radio";
+
+describe("Radio controlled state", () => {
+  it("reflects the controlled `checked` prop", () => {
+    // Arrange & Act
+    const { rerender } = render(
+      <Radio.Root checked={false} onCheckedChange={() => {}} aria-label="Compact" />,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+    expect(radio).toHaveAttribute("aria-checked", "false");
+
+    rerender(
+      <Radio.Root checked onCheckedChange={() => {}} aria-label="Compact" />,
+    );
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toHaveAttribute("data-state", "checked");
+  });
+
+  it("does not update its rendered state when the parent refuses to update `checked`", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root
+        checked={false}
+        onCheckedChange={onCheckedChange}
+        aria-label="Compact"
+      />,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Act
+    await user.click(radio);
+
+    // Assert: callback fired but the rendered state stays false because the
+    // parent did not flip the controlled prop.
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("lets a parent drive the value end to end", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    function Harness() {
+      const [checked, setChecked] = useState(false);
+      return (
+        <Radio.Root
+          checked={checked}
+          onCheckedChange={setChecked}
+          aria-label="Compact"
+        />
+      );
+    }
+    render(<Harness />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+    expect(radio).toHaveAttribute("aria-checked", "false");
+
+    // Act & Assert: the click is deferred to the parent, which selects it.
+    await user.click(radio);
+    expect(radio).toHaveAttribute("aria-checked", "true");
+  });
+});

package/src/Radio/__tests__/Radio.disabled.test.tsx

@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+describe("Radio disabled state", () => {
+  it('sets data-disabled="" on the root so CSS can target the disabled state', () => {
+    // Arrange & Act
+    render(<Radio.Root disabled aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("data-disabled", "");
+  });
+
+  it("omits data-disabled when not disabled", () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).not.toHaveAttribute("data-disabled");
+  });
+});

package/src/Radio/__tests__/Radio.indicator.test.tsx

@@ -0,0 +1,103 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio.Indicator", () => {
+  it("does not render its children when the radio is unchecked", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.queryByText("dot")).not.toBeInTheDocument();
+  });
+
+  it("renders its children when the radio is checked", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("dot")).toBeInTheDocument();
+  });
+
+  it("mounts in response to selecting", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+    expect(screen.queryByText("dot")).not.toBeInTheDocument();
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+
+    // Assert
+    expect(screen.getByText("dot")).toBeInTheDocument();
+  });
+
+  it('carries aria-hidden="true" since it is decorative', () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator data-testid="indicator">dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it("mirrors the radio's data-state on the indicator", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator data-testid="indicator">dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
+  });
+
+  it("stays in the DOM while unchecked when forceMount is set", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator forceMount data-testid="indicator">
+          dot
+        </Radio.Indicator>
+      </Radio.Root>,
+    );
+    const indicator = screen.getByTestId("indicator");
+
+    // Assert
+    expect(indicator).toBeInTheDocument();
+    expect(indicator).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("throws when rendered outside Radio.Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() => render(<Radio.Indicator>dot</Radio.Indicator>)).toThrow();
+
+    error.mockRestore();
+  });
+});

package/src/Radio/__tests__/Radio.uncontrolled-state.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio uncontrolled state", () => {
+  it("starts checked when defaultChecked is true", () => {
+    // Arrange & Act
+    render(<Radio.Root defaultChecked aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toHaveAttribute("data-state", "checked");
+  });
+
+  it("selects on click from unchecked to checked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Act
+    await user.click(radio);
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toHaveAttribute("data-state", "checked");
+  });
+
+  it("is a no-op when an already-selected radio is clicked (no toggle-off)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root
+        defaultChecked
+        onCheckedChange={onCheckedChange}
+        aria-label="Compact"
+      />,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Act
+    await user.click(radio);
+
+    // Assert: stays checked and the callback never fires for a re-select.
+    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toHaveAttribute("data-state", "checked");
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
+
+  it("calls onCheckedChange with true the first time it is selected", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(<Radio.Root onCheckedChange={onCheckedChange} aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Act
+    await user.click(radio);
+    await user.click(radio);
+
+    // Assert: selection is one-way, so the second click is swallowed.
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("composes the consumer's onClick with the internal select (consumer runs first)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const order: string[] = [];
+    const onClick = vi.fn(() => order.push("consumer"));
+    const onCheckedChange = vi.fn(() => order.push("internal"));
+    render(
+      <Radio.Root
+        onClick={onClick}
+        onCheckedChange={onCheckedChange}
+        aria-label="Compact"
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+
+    // Assert
+    expect(order).toEqual(["consumer", "internal"]);
+  });
+});

package/src/Radio/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useRadioRoot } from "./useRadioRoot";
+export { useRadioContext } from "./useRadioContext";

package/src/Radio/hooks/useRadioContext.ts

@@ -0,0 +1 @@
+export { useRadioContext } from "../RadioContext";

package/src/Radio/hooks/useRadioRoot.ts

@@ -0,0 +1,32 @@
+import { useCallback } from "react";
+
+import { useControllableState } from "../../hooks/index.ts";
+
+type UseRadioRootArgs = {
+  defaultChecked?: boolean;
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+export function useRadioRoot({
+  defaultChecked,
+  checked: controlledChecked,
+  onCheckedChange,
+}: UseRadioRootArgs) {
+  const [checked, setChecked] = useControllableState<boolean>(
+    controlledChecked,
+    defaultChecked ?? false,
+  );
+
+  const select = useCallback(() => {
+    // A radio only ever moves *into* the selected state — re-clicking the
+    // already-selected radio is a no-op (no toggle-off), per the WAI-ARIA
+    // radio convention. De-selection happens when a sibling is chosen, which
+    // is the grouping consumer's concern, not this lone control's.
+    if (checked) return;
+    setChecked(true);
+    onCheckedChange?.(true);
+  }, [checked, setChecked, onCheckedChange]);
+
+  return { checked, select };
+}

package/src/Radio/index.ts

@@ -0,0 +1,2 @@
+export * from "./Radio";
+export * from "./types";

package/src/Radio/types.ts

@@ -0,0 +1,56 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+/**
+ * Props for {@link Radio.Indicator} — all `<span>` attributes plus
+ * `forceMount` (keep mounted while unchecked for exit animations) and the
+ * `asChild` escape hatch.
+ */
+export type RadioIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  forceMount?: boolean;
+  asChild?: boolean;
+};
+
+/**
+ * Shared base for both {@link RadioRootProps} variants — the native
+ * `<button>` attributes (minus the ones the component owns) plus the
+ * `asChild` escape hatch and a typed `ref`.
+ */
+export type RadioRootBaseProps = Omit<
+  ComponentProps<"button">,
+  "type" | "role" | "aria-checked" | "defaultChecked"
+> & {
+  asChild?: boolean;
+  ref?: Ref<HTMLButtonElement>;
+};
+
+/**
+ * Uncontrolled variant of {@link RadioRootProps}: the component owns the
+ * checked value. Pass `defaultChecked` (or omit it); `onCheckedChange` is
+ * optional and `checked` is forbidden.
+ */
+export type RadioRootUncontrolledProps = RadioRootBaseProps & {
+  defaultChecked?: boolean;
+  checked?: never;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+/**
+ * Controlled variant of {@link RadioRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
+ */
+export type RadioRootControlledProps = RadioRootBaseProps & {
+  defaultChecked?: never;
+  checked: boolean;
+  onCheckedChange: (checked: boolean) => void;
+};
+
+/**
+ * Props for {@link Radio.Root}. A discriminated union of
+ * {@link RadioRootUncontrolledProps} and {@link RadioRootControlledProps},
+ * so TypeScript accepts exactly one state mode.
+ */
+export type RadioRootProps =
+  | RadioRootUncontrolledProps
+  | RadioRootControlledProps;

package/src/index.ts

@@ -21,6 +21,7 @@ export * from "./MillerColumns/index.ts";
 export * from "./Modal/index.ts";
 export * from "./Portal/index.ts";
 export * from "./Progress/index.ts";
+export * from "./Radio/index.ts";
 export * from "./RadioCard/index.ts";
 export * from "./RadioGroup/index.ts";
 export * from "./Select/index.ts";