@primitiv-ui/react 0.1.14 → 0.1.16

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

@@ -6,12 +6,16 @@ import { Checkbox } from "../Checkbox";
 describe("Checkbox uncontrolled state", () => {
   it("starts checked when defaultChecked is true", () => {
     // Arrange & Act
-    render(<Checkbox.Root defaultChecked aria-label="Accept terms" />);
-    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+    const { container } = render(
+      <Checkbox.Root defaultChecked aria-label="Accept terms" />,
+    );
 
     // Assert
-    expect(checkbox).toHaveAttribute("aria-checked", "true");
-    expect(checkbox).toHaveAttribute("data-state", "checked");
+    expect(screen.getByRole("checkbox", { name: "Accept terms" })).toBeChecked();
+    expect(container.querySelector("label")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
   });
 
   it("toggles on click from unchecked to checked", async () => {
@@ -24,8 +28,7 @@ describe("Checkbox uncontrolled state", () => {
     await user.click(checkbox);
 
     // Assert
-    expect(checkbox).toHaveAttribute("aria-checked", "true");
-    expect(checkbox).toHaveAttribute("data-state", "checked");
+    expect(checkbox).toBeChecked();
   });
 
   it("toggles on click from checked to unchecked", async () => {
@@ -33,15 +36,13 @@ describe("Checkbox uncontrolled state", () => {
     const user = userEvent.setup();
     render(<Checkbox.Root defaultChecked aria-label="Accept terms" />);
     const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
-    // Precondition: defaultChecked really did initialise as checked.
-    expect(checkbox).toHaveAttribute("aria-checked", "true");
+    expect(checkbox).toBeChecked();
 
     // Act
     await user.click(checkbox);
 
     // Assert
-    expect(checkbox).toHaveAttribute("aria-checked", "false");
-    expect(checkbox).toHaveAttribute("data-state", "unchecked");
+    expect(checkbox).not.toBeChecked();
   });
 
   it("calls onCheckedChange with the new boolean value", async () => {
@@ -49,10 +50,7 @@ describe("Checkbox uncontrolled state", () => {
     const user = userEvent.setup();
     const onCheckedChange = vi.fn();
     render(
-      <Checkbox.Root
-        onCheckedChange={onCheckedChange}
-        aria-label="Accept terms"
-      />,
+      <Checkbox.Root onCheckedChange={onCheckedChange} aria-label="Accept terms" />,
     );
     const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
 
@@ -65,15 +63,15 @@ describe("Checkbox uncontrolled state", () => {
     expect(onCheckedChange).toHaveBeenNthCalledWith(2, false);
   });
 
-  it("composes the consumer's onClick with the internal toggle (consumer runs first)", async () => {
+  it("composes a consumer onChange, running it before the internal handler", async () => {
     // Arrange
     const user = userEvent.setup();
     const order: string[] = [];
-    const onClick = vi.fn(() => order.push("consumer"));
+    const onChange = vi.fn(() => order.push("consumer"));
     const onCheckedChange = vi.fn(() => order.push("internal"));
     render(
       <Checkbox.Root
-        onClick={onClick}
+        onChange={onChange}
         onCheckedChange={onCheckedChange}
         aria-label="Accept terms"
       />,
@@ -86,4 +84,22 @@ describe("Checkbox uncontrolled state", () => {
     expect(order).toEqual(["consumer", "internal"]);
   });
 
+  it("lets a consumer onChange veto the internal handler via preventDefault", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Checkbox.Root
+        onChange={(event) => event.preventDefault()}
+        onCheckedChange={onCheckedChange}
+        aria-label="Accept terms"
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByRole("checkbox", { name: "Accept terms" }));
+
+    // Assert
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
 });

package/src/Checkbox/hooks/index.ts

@@ -1,2 +1,3 @@
 export { useCheckboxRoot } from "./useCheckboxRoot";
+export { useCheckboxInput } from "./useCheckboxInput";
 export { useCheckboxContext } from "./useCheckboxContext";

package/src/Checkbox/hooks/useCheckboxInput.ts

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import type { ChangeEvent } from "react";
+
+import { CheckboxChangeHandler, CheckedState } from "../types";
+
+type UseCheckboxInputArgs = {
+  defaultChecked?: CheckedState;
+  checked?: CheckedState;
+  onCheckedChange?: (checked: boolean) => void;
+  onChange?: CheckboxChangeHandler;
+};
+
+/**
+ * Resolves the controlled / uncontrolled tri-state for a {@link Checkbox.Root}
+ * and produces the props to spread onto its native `<input type="checkbox">`.
+ *
+ * Distinct from {@link useCheckboxRoot}, which drives the *button*-based
+ * `menuitemcheckbox` items in Dropdown / ContextMenu via a `toggle()` callback.
+ * This hook instead lets the native input own the toggling: the boolean half of
+ * the state maps to the input's `checked` / `defaultChecked`, and the
+ * `"indeterminate"` value is applied by the component via the input's
+ * `.indeterminate` DOM property. A native checkbox only toggles between booleans
+ * by user action — clicking a mixed checkbox resolves it to `true` — so
+ * `onCheckedChange` is always called with a boolean.
+ */
+export function useCheckboxInput({
+  defaultChecked,
+  checked: controlledChecked,
+  onCheckedChange,
+  onChange,
+}: UseCheckboxInputArgs) {
+  const isControlled = controlledChecked !== undefined;
+  const [mirror, setMirror] = useState<CheckedState>(defaultChecked ?? false);
+  const checked = isControlled ? controlledChecked : mirror;
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(event);
+    if (event.defaultPrevented) return;
+    const next = event.target.checked;
+    if (!isControlled) setMirror(next);
+    onCheckedChange?.(next);
+  };
+
+  const inputStateProps = isControlled
+    ? { checked: controlledChecked === true }
+    : { defaultChecked: defaultChecked === true };
+
+  return { checked, handleChange, inputStateProps };
+}

package/src/Checkbox/types.ts

@@ -1,47 +1,51 @@
-import { ComponentProps, ReactNode, Ref } from "react";
+import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
 
 /** The checked value of a checkbox — `true`, `false`, or `"indeterminate"` (the tri-state). */
 export type CheckedState = boolean | "indeterminate";
 
 /**
- * Props for {@link Checkbox.Indicator} — all `<span>` attributes plus
- * `forceMount` (keep mounted while unchecked for exit animations) and the
- * `asChild` escape hatch.
+ * Props for {@link Checkbox.Indicator} — the decorative mark. All `<span>`
+ * attributes plus the `asChild` escape hatch. The indicator is always mounted;
+ * its visibility is a CSS concern, revealed off the input's native `:checked` /
+ * `:indeterminate` state.
  */
 export type CheckboxIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
-  forceMount?: boolean;
   asChild?: boolean;
 };
 
 /**
  * Shared base for both {@link CheckboxRootProps} variants — the native
- * `<button>` attributes (minus the ones the component owns) plus the
- * `asChild` escape hatch and a typed `ref`.
+ * `<input type="checkbox">` attributes (minus the ones the component owns) plus
+ * the `onCheckedChange` convenience callback. `className` / `style` here style
+ * the **box** (the visible control), not the hidden input; everything else
+ * spreads onto the input, because semantically the Root *is* the checkbox.
  */
 export type CheckboxRootBaseProps = Omit<
-  ComponentProps<"button">,
-  "type" | "role" | "aria-checked" | "defaultChecked"
+  ComponentProps<"input">,
+  "type" | "checked" | "defaultChecked"
 > & {
-  asChild?: boolean;
-  ref?: Ref<HTMLButtonElement>;
+  /** Fired with the new boolean checked value on every user toggle. */
+  onCheckedChange?: (checked: boolean) => void;
+  children?: ReactNode;
+  /** Forwarded to the underlying native `<input type="checkbox">`. */
+  ref?: Ref<HTMLInputElement>;
 };
 
 /**
  * Uncontrolled variant of {@link CheckboxRootProps}: the component owns the
- * checked value. Pass `defaultChecked` (or omit it); `onCheckedChange` is
- * optional and `checked` is forbidden.
+ * checked value. Pass `defaultChecked` (or omit it); `checked` is forbidden.
+ * `defaultChecked` may be `"indeterminate"` for a mixed-on-mount checkbox.
  */
 export type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
   defaultChecked?: CheckedState;
   checked?: never;
-  onCheckedChange?: (checked: boolean) => void;
 };
 
 /**
- * Controlled variant of {@link CheckboxRootProps}: the parent owns the
- * checked value. Pass `checked` and `onCheckedChange` together;
- * `defaultChecked` is forbidden.
+ * Controlled variant of {@link CheckboxRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
  */
 export type CheckboxRootControlledProps = CheckboxRootBaseProps & {
   defaultChecked?: never;
@@ -58,3 +62,6 @@ export type CheckboxRootControlledProps = CheckboxRootBaseProps & {
 export type CheckboxRootProps =
   | CheckboxRootUncontrolledProps
   | CheckboxRootControlledProps;
+
+/** Internal: the native `onChange` shape the Root composes with its own. */
+export type CheckboxChangeHandler = ChangeEventHandler<HTMLInputElement>;

package/src/Radio/README.md

@@ -1,116 +1,135 @@
 # 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.
+A headless, accessible, **standalone** radio control built on a **real native
+`<input type="radio">`**.
+
+Radio renders a `<label>` that is the visible box, wrapping a visually-hidden
+native `<input type="radio">` (the focusable, form-participating control) and a
+decorative `Indicator` dot. Because the underlying element is a genuine native
+radio, siblings sharing a `name` form a **native radio group** — the browser,
+not JavaScript, enforces single-selection and silently deselects the others.
+It also submits with an enclosing form, resets with it, and gets keyboard
+activation and focus for free.
+
+> **Radio vs. RadioGroup.** `Radio` is the lone native control for when you own
+> the grouping (a shared `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) — it
+> composes `role="radio"` items and owns the shared selected value itself.
 
 ```tsx
 import { Radio } from "@primitiv-ui/react";
 
-<Radio.Root defaultChecked aria-label="Compact">
-  <Radio.Indicator>
-    <DotIcon />
-  </Radio.Indicator>
+<Radio.Root name="density" value="comfortable" defaultChecked aria-label="Comfortable">
+  <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`  |
+| Export            | Element                          | Notes                                                                              |
+| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------- |
+| `Radio.Root`      | `<label>` + hidden `<input>`     | The styled box. `data-state`, `data-disabled` on the label; `name`/`value`/`aria-*`/`ref` go to the input. |
+| `Radio.Indicator` | `<span>`                         | `aria-hidden="true"`. Always mounted; CSS reveals it. `asChild`                    |
+
+`Radio.Root`'s `className` / `style` style the **box** (the `<label>` you see).
+Every other prop spreads onto the hidden `<input>`, because semantically the
+Root *is* the radio: pass `name`, `value`, `id`, `required`, `aria-*`, `ref`,
+etc. straight to `Radio.Root`.
+
+## Native grouping (the headline)
+
+Give sibling radios the same `name` and the browser groups them. No shared
+state, no `RadioGroup`, no controlled wiring required:
+
+```tsx
+{plans.map((plan) => (
+  <Radio.Root key={plan.id} name="plan" value={plan.id} aria-label={plan.label}>
+    <Radio.Indicator />
+  </Radio.Root>
+))}
+```
+
+Selecting one deselects the rest, and the chosen `value` submits under `plan`
+with an enclosing `<form>`.
 
 ## 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`) |
+| Value   | Native    | `data-state`  | Dot visible? |
+| ------- | --------- | ------------- | ------------ |
+| `true`  | `:checked`| `"checked"`   | Yes          |
+| `false` | —         | `"unchecked"` | No           |
 
-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.
+A native radio only ever moves *into* the checked state by user action —
+clicking the already-selected radio is a no-op, and selection moves off it only
+when a sibling is chosen. You get that for free.
 
 ## State modes
 
 - **Uncontrolled** — pass `defaultChecked` (or omit for unselected on mount).
-- **Controlled** — pass `checked` **and** `onCheckedChange` together.
+  The **browser** owns the value, so native `name`-grouping works.
+- **Controlled** — pass `checked` **and** `onCheckedChange` together. The parent
+  owns the value (and the grouping).
 
 The two shapes are statically discriminated at the type level; TypeScript
 rejects mixing them.
 
 ```tsx
-// Uncontrolled
-<Radio.Root defaultChecked>…</Radio.Root>;
+// Uncontrolled native group
+<Radio.Root name="density" value="compact" defaultChecked>
+  <Radio.Indicator />
+</Radio.Root>;
 
 // Controlled — the consumer owns the group's selected value.
 const [value, setValue] = useState("comfortable");
 <Radio.Root
+  name="density"
+  value="compact"
   checked={value === "compact"}
   onCheckedChange={() => setValue("compact")}
 >
-  …
+  <Radio.Indicator />
 </Radio.Root>;
 ```
 
+> **`data-state` is a best-effort mirror.** It is accurate in controlled mode and
+> for self-clicks, but a sibling the browser silently deselects fires no React
+> event, so its `data-state` can lag. Drive the *visual* checked look off the
+> input's native `:checked` (and `:has(> input:checked)` on the box), as the
+> shipped registry stylesheet does — not off `data-state`.
+
 ## Keyboard interaction
 
-| Key     | Behaviour                              |
-| ------- | -------------------------------------- |
-| `Space` | Selects the radio (native `<button>`)  |
-| `Enter` | Selects the radio (native `<button>`)  |
+| Key            | Behaviour                                  |
+| -------------- | ------------------------------------------ |
+| `Space`        | Selects the focused radio (native `<input>`) |
+| `Tab`          | Moves to / from the radio (native)         |
 
-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.)
+Keyboard handling comes from the underlying native input — no custom `keydown`
+listeners. (Arrow-key navigation *within* a group is a `RadioGroup` concern.)
 
 ## Disabled
 
-Passing `disabled` forwards the native `disabled` attribute to the button
+Passing `disabled` forwards the native `disabled` attribute to the input
 (removing it from the tab order and suppressing clicks) **and** sets
-`data-disabled=""` on the root so CSS can target `[data-disabled]` without
+`data-disabled=""` on the box so CSS can target `[data-disabled]` without
 reaching for `:disabled`.
 
 ```tsx
 <Radio.Root disabled aria-label="Unavailable plan">
-  <Radio.Indicator>
-    <DotIcon />
-  </Radio.Indicator>
+  <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`).
+`Radio.Indicator` accepts an `asChild` boolean. When set, the component
+delegates rendering to its single child element and merges its `aria-hidden`,
+`data-state`, and ref onto the child — typically to use an `<svg>` as the dot:
 
 ```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" />
@@ -118,39 +137,23 @@ library's runs second unless the child calls `preventDefault`).
 </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.
+- The box (`Radio.Root`) carries `data-state="checked" | "unchecked"` and
+  `data-disabled=""`.
+- The hidden input exposes the always-correct native states: `:checked`,
+  `:focus-visible`, `:disabled`. Prefer these for the *checked* look.
 
 ```css
-button[data-state="checked"] {
+/* Reveal the dot from the native checked state — correct even on a silent
+   sibling deselect. */
+.radio > input:checked ~ .radio__indicator {
+  scale: 1;
+}
+.radio:has(> input:checked) {
   border-color: oklch(55% 0.2 265);
 }
-button[data-disabled] {
+.radio[data-disabled] {
   opacity: 0.5;
   cursor: not-allowed;
 }