@primitiv-ui/react 0.1.14 → 0.1.16

package/src/Radio/Radio.tsx

@@ -1,7 +1,7 @@
 import { useMemo } from "react";
 import type { ReactElement } from "react";
 
-import { Slot, composeEventHandlers } from "../Slot/index.ts";
+import { Slot } from "../Slot/index.ts";
 
 import { RadioContext } from "./RadioContext";
 import { useRadioContext, useRadioRoot } from "./hooks/index.ts";
@@ -12,52 +12,54 @@ function dataStateOf(checked: boolean) {
 }
 
 /**
- * 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).
+ * The root of a Radio — a `<label>` that is itself the **visible, styled box**
+ * and wraps a **real, visually-hidden `<input type="radio">`** (the focusable,
+ * form-participating control) plus the decorative
+ * {@link RadioIndicator | `Radio.Indicator`} dot. It provides
+ * {@link RadioContext | `RadioContext`} to the indicator.
+ *
+ * Because the underlying element is a genuine native radio, it behaves like
+ * one: siblings sharing a `name` form a **native radio group** (the browser
+ * deselects the others when one is chosen — no JS required), it submits with
+ * an enclosing form, resets with it, and gets keyboard activation and focus
+ * for free. This is the standalone primitive for "I own the grouping via
+ * `name`, or I'm a single opt-in". For a managed set with roving-tabindex
+ * arrow-key navigation, reach for `RadioGroup` instead.
+ *
+ * Props routing: `className` / `style` style the **box** (the `<label>` you
+ * see — the input is hidden); every other prop (`name`, `value`, `id`,
+ * `aria-*`, `required`, `disabled`, `ref`, …) spreads onto the input, because
+ * semantically the Root *is* the radio.
  *
  * 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.
+ *   {@link RadioRootProps.defaultChecked | `defaultChecked`} (or omit). The
+ *   **browser** owns the value, so native `name`-grouping just works.
  * - **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.
+ *   {@link RadioRootProps.onCheckedChange | `onCheckedChange`} together. The
+ *   parent owns the value and the grouping.
  *
- * **ARIA.** `role="radio"` and `aria-checked` are set automatically.
+ * **Styling hooks.** `data-state="checked" | "unchecked"` and
+ * `data-disabled=""` on the box (and `data-state` on the indicator). These
+ * mirror the input but can lag a silent native deselect, so shipped CSS keys
+ * visibility off the input's native `:checked` / `:has()` selectors;
+ * `data-state` is a convenience mirror.
  *
- * **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
+ * @example Native group (the browser owns selection)
  * ```tsx
- * <Radio.Root defaultChecked aria-label="Compact">
+ * <Radio.Root name="density" value="compact" defaultChecked aria-label="Compact">
  *   <Radio.Indicator />
  * </Radio.Root>
  * ```
  *
- * @example Controlled (consumer owns the group)
+ * @example Controlled
  * ```tsx
  * const [value, setValue] = useState("comfortable");
  *
  * <Radio.Root
+ *   name="density"
+ *   value="compact"
  *   checked={value === "compact"}
  *   onCheckedChange={() => setValue("compact")}
  *   aria-label="Compact"
@@ -68,39 +70,44 @@ function dataStateOf(checked: boolean) {
  */
 export function RadioRoot(props: RadioRootProps): ReactElement {
   const {
-    defaultChecked,
-    checked,
-    onCheckedChange,
-    onClick,
-    disabled,
-    asChild = false,
+    className,
+    style,
     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,
+    onChange,
     disabled,
-    onClick: composeEventHandlers(onClick, select),
-  };
+    ref,
+    ...inputRest
+  } = props;
+  const {
+    checked: isChecked,
+    handleChange,
+    inputStateProps,
+  } = useRadioRoot({ defaultChecked, checked, onCheckedChange, onChange });
+  const contextValue = useMemo(
+    () => ({ checked: isChecked, disabled: Boolean(disabled) }),
+    [isChecked, disabled],
+  );
   return (
     <RadioContext.Provider value={contextValue}>
-      {asChild ? (
-        <Slot {...rootProps}>{children}</Slot>
-      ) : (
-        <button type="button" {...rootProps}>
-          {children}
-        </button>
-      )}
+      <label
+        className={className}
+        style={style}
+        data-state={dataStateOf(isChecked)}
+        data-disabled={disabled ? "" : undefined}
+      >
+        <input
+          type="radio"
+          ref={ref}
+          disabled={disabled}
+          {...inputRest}
+          {...inputStateProps}
+          onChange={handleChange}
+        />
+        {children}
+      </label>
     </RadioContext.Provider>
   );
 }
@@ -109,32 +116,18 @@ export function RadioRoot(props: RadioRootProps): ReactElement {
 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.
+ * The decorative dot — a `<span>` that is **always mounted**, sitting inside
+ * the {@link RadioRoot | `Radio.Root`} box. Its visibility is a pure CSS
+ * concern, driven off the input's native `:checked` state, so it stays correct
+ * even when the browser silently deselects a grouped sibling (an event React
+ * never sees). The radio's accessible state is conveyed by the native input,
+ * so the dot is purely visual.
  *
- * **Styling hook.** Mirrors the root's
- * `data-state="checked" | "unchecked"` so the same CSS rule can target
- * both.
+ * **Styling hook.** Mirrors the root's `data-state="checked" | "unchecked"`.
  *
  * **`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>
- * ```
+ * (typically an `<svg>` dot) as the indicator itself, with `data-state` merged
+ * onto that element rather than a wrapper.
  *
  * @example Dot as the indicator via `asChild`
  * ```tsx
@@ -147,12 +140,10 @@ RadioRoot.displayName = "RadioRoot";
  */
 export function RadioIndicator({
   children,
-  forceMount,
   asChild = false,
   ...rest
-}: RadioIndicatorProps): ReactElement | null {
+}: RadioIndicatorProps): ReactElement {
   const { checked } = useRadioContext();
-  if (!checked && !forceMount) return null;
   const indicatorProps = {
     ...rest,
     "aria-hidden": "true" as const,
@@ -174,33 +165,31 @@ export type TRadioCompound = typeof RadioRoot & {
 };
 
 /**
- * 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.
+ * Headless, accessible **Radio** — a standalone compound component built on a
+ * **real, visually-hidden native `<input type="radio">`**. Unlike a button
+ * dressed up with `role="radio"`, it participates in native forms and groups
+ * by `name` the way the platform intends. 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 the lone control for when you own the grouping (via a native
+ * `name`, or a single opt-in); 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.
+ * `Radio` is both callable (an alias of {@link RadioRoot | `Radio.Root`}) and
+ * carries its sub-components as static properties.
  *
- * - {@link RadioRoot | `Radio.Root`} — state owner, context provider, select button.
- * - {@link RadioIndicator | `Radio.Indicator`} — decorative dot, conditional on selected state.
+ * - {@link RadioRoot | `Radio.Root`} — the styled box: label + hidden input, state owner, context provider.
+ * - {@link RadioIndicator | `Radio.Indicator`} — the decorative dot.
  *
  * @example Minimal usage
  * ```tsx
  * import { Radio } from "@primitiv-ui/react";
  *
- * <Radio.Root aria-label="Compact">
+ * <Radio.Root name="plan" value="free" aria-label="Free">
  *   <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.
+ * @see {@link RadioRoot} for state modes and native-grouping semantics.
  */
 const RadioCompound: TRadioCompound = Object.assign(RadioRoot, {
   Root: RadioRoot,

package/src/Radio/RadioContext.ts

@@ -1,7 +1,16 @@
 import { createStrictContext } from "../utils/index.ts";
 
 export type RadioContextValue = {
+  /**
+   * Best-effort mirror of the input's checked state, for the `data-state`
+   * hook on the visual parts. Accurate in controlled mode and for self-clicks;
+   * may go stale when the browser silently deselects a grouped sibling, which
+   * is why the shipped CSS keys visibility off the input's native `:checked`,
+   * not off `data-state`.
+   */
   checked: boolean;
+  /** Whether the radio is disabled, for the `data-disabled` hook. */
+  disabled: boolean;
 };
 
 export const [RadioContext, useRadioContext] =

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

@@ -3,39 +3,64 @@ import { render, screen } from "@testing-library/react";
 import { Radio } from "../Radio";
 
 describe("Radio basic rendering", () => {
-  it('renders a <button> with role="radio"', () => {
+  it("renders a real native <input type=radio> as the control", () => {
     // Arrange & Act
     render(<Radio.Root aria-label="Compact" />);
     const radio = screen.getByRole("radio", { name: "Compact" });
 
     // Assert
-    expect(radio.tagName).toBe("BUTTON");
+    expect(radio.tagName).toBe("INPUT");
+    expect(radio).toHaveAttribute("type", "radio");
   });
 
-  it('defaults aria-checked to "false"', () => {
+  it("wraps the input in a <label> so the visible control is clickable", () => {
     // Arrange & Act
     render(<Radio.Root aria-label="Compact" />);
     const radio = screen.getByRole("radio", { name: "Compact" });
 
     // Assert
-    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio.closest("label")).not.toBeNull();
   });
 
-  it('defaults type="button" so the radio never submits an enclosing form', () => {
+  it("is unchecked by default", () => {
     // Arrange & Act
     render(<Radio.Root aria-label="Compact" />);
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Compact" })).not.toBeChecked();
+  });
+
+  it("forwards native input attributes (name, value, id) to the input", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root id="r1" name="density" value="compact" aria-label="Compact" />,
+    );
     const radio = screen.getByRole("radio", { name: "Compact" });
 
     // Assert
-    expect(radio).toHaveAttribute("type", "button");
+    expect(radio).toHaveAttribute("id", "r1");
+    expect(radio).toHaveAttribute("name", "density");
+    expect(radio).toHaveAttribute("value", "compact");
   });
 
-  it('sets data-state="unchecked" on the root when unchecked', () => {
+  it("applies className to the wrapper, not the hidden input", () => {
     // Arrange & Act
-    render(<Radio.Root aria-label="Compact" />);
+    render(<Radio.Root className="box" aria-label="Compact" />);
     const radio = screen.getByRole("radio", { name: "Compact" });
 
     // Assert
-    expect(radio).toHaveAttribute("data-state", "unchecked");
+    expect(radio).not.toHaveClass("box");
+    expect(radio.closest("label")).toHaveClass("box");
+  });
+
+  it('sets data-state="unchecked" on the wrapper when unchecked', () => {
+    // Arrange & Act
+    const { container } = render(<Radio.Root aria-label="Compact" />);
+
+    // Assert
+    expect(container.querySelector("label")).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
   });
 });

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

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 
-import { render, screen } from "@testing-library/react";
+import { render } from "@testing-library/react";
 
 import { Radio } from "../Radio";
 
@@ -10,11 +10,11 @@ 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.
+ * from what the component actually emits. The radio's `data-*` surface lives
+ * on the **wrapper** (the styled root) — `data-state="checked" | "unchecked"`
+ * (always present) plus `data-disabled=""` when disabled. The authored half
+ * (classes, 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)),
@@ -23,6 +23,13 @@ const contractPath = resolve(
 
 const contract = JSON.parse(readFileSync(contractPath, "utf8"));
 
+/** The wrapper element is the contracted styling root. */
+function rootOf(container: HTMLElement): HTMLElement {
+  const root = container.querySelector("label");
+  if (!root) throw new Error("expected a Radio wrapper element");
+  return root;
+}
+
 /** Every `data-*` attribute name present on an element. */
 function dataAttributeNames(element: Element): string[] {
   return [...element.attributes]
@@ -37,25 +44,23 @@ describe("Radio styling contract", () => {
   );
 
   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>,
+      <Radio.Root key="checked" checked onCheckedChange={() => {}} aria-label="x" />,
+      <Radio.Root
+        key="unchecked"
+        checked={false}
+        onCheckedChange={() => {}}
+        aria-label="x"
+      />,
+      <Radio.Root key="disabled" disabled aria-label="x" />,
     ]) {
-      const { unmount } = render(ui);
-      for (const name of dataAttributeNames(screen.getByRole("radio"))) {
+      const { container, unmount } = render(ui);
+      for (const name of dataAttributeNames(rootOf(container))) {
         emitted.add(name);
       }
       unmount();
@@ -73,16 +78,14 @@ describe("Radio styling contract", () => {
     );
 
     for (const entry of stateEntries) {
-      const { unmount } = render(
+      const { container, 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);
+      expect(rootOf(container)).toHaveAttribute("data-state", entry.value);
       unmount();
     }
   });
@@ -92,21 +95,12 @@ describe("Radio styling contract", () => {
       (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);
+    const { container } = render(<Radio.Root disabled aria-label="x" />);
+    expect(rootOf(container)).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");
+    const { container } = render(<Radio.Root aria-label="x" />);
+    expect(rootOf(container)).not.toHaveAttribute("data-disabled");
   });
 });

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

@@ -11,18 +11,30 @@ describe("Radio controlled state", () => {
       <Radio.Root checked={false} onCheckedChange={() => {}} aria-label="Compact" />,
     );
     const radio = screen.getByRole("radio", { name: "Compact" });
-    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).not.toBeChecked();
 
     rerender(
       <Radio.Root checked onCheckedChange={() => {}} aria-label="Compact" />,
     );
 
     // Assert
-    expect(radio).toHaveAttribute("aria-checked", "true");
-    expect(radio).toHaveAttribute("data-state", "checked");
+    expect(radio).toBeChecked();
   });
 
-  it("does not update its rendered state when the parent refuses to update `checked`", async () => {
+  it("mirrors the controlled value into the wrapper's data-state", () => {
+    // Arrange & Act
+    const { container } = render(
+      <Radio.Root checked onCheckedChange={() => {}} aria-label="Compact" />,
+    );
+
+    // Assert
+    expect(container.querySelector("label")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
+  });
+
+  it("does not change its rendered state when the parent refuses to update `checked`", async () => {
     // Arrange
     const user = userEvent.setup();
     const onCheckedChange = vi.fn();
@@ -38,11 +50,9 @@ describe("Radio controlled state", () => {
     // Act
     await user.click(radio);
 
-    // Assert: callback fired but the rendered state stays false because the
-    // parent did not flip the controlled prop.
+    // Assert: callback fired but the rendered state stays unchecked.
     expect(onCheckedChange).toHaveBeenCalledWith(true);
-    expect(radio).toHaveAttribute("aria-checked", "false");
-    expect(radio).toHaveAttribute("data-state", "unchecked");
+    expect(radio).not.toBeChecked();
   });
 
   it("lets a parent drive the value end to end", async () => {
@@ -60,10 +70,10 @@ describe("Radio controlled state", () => {
     }
     render(<Harness />);
     const radio = screen.getByRole("radio", { name: "Compact" });
-    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).not.toBeChecked();
 
-    // Act & Assert: the click is deferred to the parent, which selects it.
+    // Act & Assert
     await user.click(radio);
-    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toBeChecked();
   });
 });

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

@@ -1,23 +1,48 @@
 import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 
 import { Radio } from "../Radio";
 
 describe("Radio disabled state", () => {
-  it('sets data-disabled="" on the root so CSS can target the disabled state', () => {
+  it("disables the underlying native input", () => {
     // Arrange & Act
     render(<Radio.Root disabled aria-label="Compact" />);
-    const radio = screen.getByRole("radio", { name: "Compact" });
 
     // Assert
-    expect(radio).toHaveAttribute("data-disabled", "");
+    expect(screen.getByRole("radio", { name: "Compact" })).toBeDisabled();
+  });
+
+  it('sets data-disabled="" on the wrapper so CSS can target the disabled state', () => {
+    // Arrange & Act
+    const { container } = render(<Radio.Root disabled aria-label="Compact" />);
+
+    // Assert
+    expect(container.querySelector("label")).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" });
+    const { container } = render(<Radio.Root aria-label="Compact" />);
+
+    // Assert
+    expect(container.querySelector("label")).not.toHaveAttribute("data-disabled");
+  });
+
+  it("does not fire onCheckedChange when a disabled radio is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root disabled onCheckedChange={onCheckedChange} aria-label="Compact" />,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
 
     // Assert
-    expect(radio).not.toHaveAttribute("data-disabled");
+    expect(onCheckedChange).not.toHaveBeenCalled();
   });
 });