@primitiv-ui/react 0.1.14 → 0.1.16

package/src/Radio/__tests__/Radio.native-grouping.test.tsx

@@ -0,0 +1,77 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+/**
+ * The behaviour this whole redesign exists to fix: three standalone radios
+ * sharing a `name` must form a *native* radio group, where the browser — not
+ * React — enforces single-selection and silently deselects the others. The
+ * old `<button role="radio">` could never do this; a real `<input
+ * type="radio">` does it for free.
+ */
+describe("Radio native grouping", () => {
+  function DensityGroup() {
+    return (
+      <fieldset>
+        {["compact", "comfortable", "spacious"].map((value) => (
+          <Radio.Root key={value} name="density" value={value} aria-label={value} />
+        ))}
+      </fieldset>
+    );
+  }
+
+  it("enforces single-selection across siblings sharing a name", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(<DensityGroup />);
+    const compact = screen.getByRole("radio", { name: "compact" });
+    const comfortable = screen.getByRole("radio", { name: "comfortable" });
+    const spacious = screen.getByRole("radio", { name: "spacious" });
+
+    // Act: select the first
+    await user.click(compact);
+
+    // Assert: only it is checked
+    expect(compact).toBeChecked();
+    expect(comfortable).not.toBeChecked();
+    expect(spacious).not.toBeChecked();
+
+    // Act: select a sibling — the browser deselects the first
+    await user.click(comfortable);
+
+    // Assert: selection moved; no two radios are checked at once
+    expect(compact).not.toBeChecked();
+    expect(comfortable).toBeChecked();
+    expect(spacious).not.toBeChecked();
+  });
+
+  it("submits the selected radio's value with an enclosing form", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const submitted: string[] = [];
+    function Form() {
+      return (
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            const data = new FormData(event.currentTarget);
+            submitted.push(String(data.get("density")));
+          }}
+        >
+          <Radio.Root name="density" value="compact" aria-label="compact" />
+          <Radio.Root name="density" value="spacious" aria-label="spacious" />
+          <button type="submit">Save</button>
+        </form>
+      );
+    }
+    render(<Form />);
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "spacious" }));
+    await user.click(screen.getByRole("button", { name: "Save" }));
+
+    // Assert
+    expect(submitted).toEqual(["spacious"]);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio.Indicator", () => {
+  it("is always mounted, regardless of checked state", () => {
+    // Arrange & Act — unchecked, yet the dot is in the DOM (CSS hides it).
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator data-testid="dot" />
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("dot")).toBeInTheDocument();
+  });
+
+  it("is decorative, carrying aria-hidden", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator data-testid="dot" />
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("dot")).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("mirrors the radio's data-state for CSS to key off", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator data-testid="dot" />
+      </Radio.Root>,
+    );
+    const dot = screen.getByTestId("dot");
+    expect(dot).toHaveAttribute("data-state", "unchecked");
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+
+    // Assert
+    expect(dot).toHaveAttribute("data-state", "checked");
+  });
+
+  it("delegates to the consumer's element (e.g. an svg dot) via asChild", () => {
+    // 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>,
+    );
+    const dot = screen.getByTestId("dot");
+
+    // Assert
+    expect(dot.tagName.toLowerCase()).toBe("svg");
+    expect(dot).toHaveAttribute("data-state", "checked");
+  });
+
+  it("throws when rendered outside Radio.Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() => render(<Radio.Indicator />)).toThrow();
+
+    error.mockRestore();
+  });
+});

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

@@ -7,14 +7,12 @@ 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");
+    expect(screen.getByRole("radio", { name: "Compact" })).toBeChecked();
   });
 
-  it("selects on click from unchecked to checked", async () => {
+  it("checks on click", async () => {
     // Arrange
     const user = userEvent.setup();
     render(<Radio.Root aria-label="Compact" />);
@@ -24,57 +22,47 @@ describe("Radio uncontrolled state", () => {
     await user.click(radio);
 
     // Assert
-    expect(radio).toHaveAttribute("aria-checked", "true");
-    expect(radio).toHaveAttribute("data-state", "checked");
+    expect(radio).toBeChecked();
   });
 
-  it("is a no-op when an already-selected radio is clicked (no toggle-off)", async () => {
+  it("calls onCheckedChange with true when it becomes selected", 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" });
+    render(<Radio.Root onCheckedChange={onCheckedChange} aria-label="Compact" />);
 
     // Act
-    await user.click(radio);
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
 
-    // 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();
+    // Assert
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
   });
 
-  it("calls onCheckedChange with true the first time it is selected", async () => {
+  it("updates the data-state mirror on the wrapper when 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" });
+    const { container } = render(<Radio.Root aria-label="Compact" />);
 
     // Act
-    await user.click(radio);
-    await user.click(radio);
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
 
-    // Assert: selection is one-way, so the second click is swallowed.
-    expect(onCheckedChange).toHaveBeenCalledTimes(1);
-    expect(onCheckedChange).toHaveBeenCalledWith(true);
+    // Assert
+    expect(container.querySelector("label")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
   });
 
-  it("composes the consumer's onClick with the internal select (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(
       <Radio.Root
-        onClick={onClick}
+        onChange={onChange}
         onCheckedChange={onCheckedChange}
         aria-label="Compact"
       />,
@@ -86,4 +74,23 @@ describe("Radio uncontrolled state", () => {
     // Assert
     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(
+      <Radio.Root
+        onChange={(event) => event.preventDefault()}
+        onCheckedChange={onCheckedChange}
+        aria-label="Compact"
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+
+    // Assert
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
 });

package/src/Radio/hooks/useRadioRoot.ts

@@ -1,32 +1,48 @@
-import { useCallback } from "react";
+import { useState } from "react";
+import type { ChangeEvent } from "react";
 
-import { useControllableState } from "../../hooks/index.ts";
+import type { RadioChangeHandler } from "../types";
 
 type UseRadioRootArgs = {
   defaultChecked?: boolean;
   checked?: boolean;
   onCheckedChange?: (checked: boolean) => void;
+  onChange?: RadioChangeHandler;
 };
 
+/**
+ * Resolves the controlled / uncontrolled state for a {@link Radio.Root} and
+ * produces the props to spread onto its native `<input type="radio">`.
+ *
+ * The key correctness move: in **uncontrolled** mode the input is rendered
+ * with `defaultChecked` and *no* `checked` prop, so the browser owns the
+ * value and native `name`-grouping (including the silent deselection of
+ * siblings) works. The returned `checked` is only a best-effort mirror used
+ * for the `data-state` styling hook — it is updated from the input's own
+ * `change` events, and may lag behind a sibling-driven deselect, which the
+ * CSS `:checked` selector handles instead.
+ */
 export function useRadioRoot({
   defaultChecked,
   checked: controlledChecked,
   onCheckedChange,
+  onChange,
 }: UseRadioRootArgs) {
-  const [checked, setChecked] = useControllableState<boolean>(
-    controlledChecked,
-    defaultChecked ?? false,
-  );
+  const isControlled = controlledChecked !== undefined;
+  const [mirror, setMirror] = useState(defaultChecked ?? false);
+  const checked = isControlled ? controlledChecked : mirror;
 
-  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]);
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(event);
+    if (event.defaultPrevented) return;
+    const next = event.target.checked;
+    if (!isControlled) setMirror(next);
+    onCheckedChange?.(next);
+  };
 
-  return { checked, select };
+  const inputStateProps = isControlled
+    ? { checked: controlledChecked }
+    : { defaultChecked: defaultChecked ?? false };
+
+  return { checked, handleChange, inputStateProps };
 }

package/src/Radio/types.ts

@@ -1,44 +1,55 @@
-import { ComponentProps, ReactNode, Ref } from "react";
+import { ChangeEventHandler, 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.
+ * Props for {@link Radio.Indicator} — the decorative dot. All `<span>`
+ * attributes plus the `asChild` escape hatch. The indicator is always mounted;
+ * its visibility is a CSS concern, driven off the input's native `:checked`
+ * state, so it stays correct even when the browser silently deselects a
+ * grouped sibling (which fires no React event).
  */
 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`.
+ * `<input type="radio">` attributes (minus the ones the component owns) plus
+ * the `onCheckedChange` convenience callback. `className` / `style` here style
+ * the **wrapper** (the visible control), not the hidden input; everything
+ * else spreads onto the input, because semantically the Root *is* the radio.
  */
 export type RadioRootBaseProps = Omit<
-  ComponentProps<"button">,
-  "type" | "role" | "aria-checked" | "defaultChecked"
+  ComponentProps<"input">,
+  "type" | "checked" | "defaultChecked"
 > & {
-  asChild?: boolean;
-  ref?: Ref<HTMLButtonElement>;
+  /**
+   * Fired with the new checked value whenever this radio becomes selected.
+   * A native radio only ever fires `change` when it moves *into* the checked
+   * state, so this is always called with `true`.
+   */
+  onCheckedChange?: (checked: boolean) => void;
+  children?: ReactNode;
+  /** Forwarded to the underlying native `<input type="radio">`. */
+  ref?: Ref<HTMLInputElement>;
 };
 
 /**
- * Uncontrolled variant of {@link RadioRootProps}: the component owns the
- * checked value. Pass `defaultChecked` (or omit it); `onCheckedChange` is
- * optional and `checked` is forbidden.
+ * Uncontrolled variant of {@link RadioRootProps}: the **browser** owns the
+ * checked value (the input is rendered with `defaultChecked` and no `checked`
+ * prop), so native `name`-grouping — including the silent deselection of
+ * siblings — works for free. Pass `defaultChecked` (or omit it); `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.
+ * forbidden. The consumer owns grouping in this mode.
  */
 export type RadioRootControlledProps = RadioRootBaseProps & {
   defaultChecked?: never;
@@ -54,3 +65,6 @@ export type RadioRootControlledProps = RadioRootBaseProps & {
 export type RadioRootProps =
   | RadioRootUncontrolledProps
   | RadioRootControlledProps;
+
+/** Internal: the native `onChange` shape the Root composes with its own. */
+export type RadioChangeHandler = ChangeEventHandler<HTMLInputElement>;

package/src/Switch/README.md

@@ -1,14 +1,14 @@
 # Switch
 
-Headless, accessible **Switch** — a compound component implementing the
-[WAI-ARIA Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
-on a native `<button role="switch">`. Semantically represents an immediate
-on/off action (as opposed to a selection choice). Zero styles ship.
+Headless, accessible **Switch** — a compound component built on a **real,
+visually-hidden native `<input type="checkbox" role="switch">`**. Semantically
+represents an immediate on/off action (as opposed to a selection choice), and —
+being a genuine native input — participates in forms. Zero styles ship.
 
 ```tsx
 import { Switch } from "@primitiv-ui/react";
 
-<Switch.Root defaultChecked aria-label="Enable notifications">
+<Switch.Root name="notify" value="on" defaultChecked aria-label="Enable notifications">
   <Switch.Thumb />
 </Switch.Root>
 ```
@@ -17,18 +17,23 @@ import { Switch } from "@primitiv-ui/react";
 
 | Export | Element | ARIA / data hooks | `asChild` |
 |--------|---------|------------------|-----------|
-| `Switch.Root` | `<button>` | `role="switch"`, `aria-checked`, `data-state`, `data-disabled` | yes |
+| `Switch.Root` | `<label>` + hidden `<input>` | input is `role="switch"`; `data-state`, `data-disabled` on the label | — |
 | `Switch.Thumb` | `<span>` | `aria-hidden="true"`, `data-state` | yes |
 
+`Switch.Root`'s `className` / `style` style the **track** (the `<label>` you
+see). Every other prop spreads onto the hidden `<input>`, because semantically
+the Root *is* the switch: pass `name`, `value`, `id`, `required`, `aria-*`,
+`ref`, etc. straight to `Switch.Root`.
+
 ## State modes
 
 ### Uncontrolled
 
-Pass `defaultChecked` (or omit for unchecked on mount). The component owns
-the value internally.
+Pass `defaultChecked` (or omit for off on mount). The **browser** owns the
+value, so the switch participates in forms and resets.
 
 ```tsx
-<Switch.Root defaultChecked aria-label="Enable dark mode">
+<Switch.Root name="dark" value="on" defaultChecked aria-label="Enable dark mode">
   <Switch.Thumb />
 </Switch.Root>
 ```
@@ -45,18 +50,24 @@ const [enabled, setEnabled] = useState(false);
 </Switch.Root>
 ```
 
+> **`data-state` is a best-effort mirror.** Drive the *visual* on/off look off
+> the input's native `:checked` (and `:has(> input:checked)` on the track), as
+> the shipped registry stylesheet does — it stays correct through a form reset,
+> which fires no React event.
+
 ## Keyboard interaction
 
 | Key | Behaviour |
 |-----|-----------|
-| `Space` | Toggle the switch (native `<button>` behaviour) |
-| `Enter` | Toggle the switch (native `<button>` behaviour) |
+| `Space` | Toggle the switch (native checkbox behaviour) |
 | `Tab` | Move focus to or from the switch |
 
+`Enter` does **not** toggle — a checkbox-based control responds to `Space` only.
+
 ## Disabled
 
 Pass `disabled` on the Root. The native attribute suppresses clicks and removes
-the switch from the focus ring. `data-disabled=""` is set for CSS targeting.
+the switch from the focus ring. `data-disabled=""` is set on the track for CSS.
 
 ```tsx
 <Switch.Root aria-label="Enable feature" disabled>
@@ -67,15 +78,7 @@ the switch from the focus ring. `data-disabled=""` is set for CSS targeting.
 ## Size
 
 The styled surface installed by `primitiv add switch` exposes a `size` prop.
-The default is `md`.
-
-| Value | Description |
-|-------|-------------|
-| `xs` | Extra small |
-| `sm` | Small |
-| `md` | Medium (default) |
-| `lg` | Large |
-| `xl` | Extra large |
+The default is `md` (`xs` · `sm` · `md` · `lg` · `xl`).
 
 ```tsx
 <Switch size="sm" aria-label="Enable notifications" />
@@ -83,56 +86,41 @@ The default is `md`.
 
 ## The Thumb
 
-`Switch.Thumb` is **always mounted** — unlike `Checkbox.Indicator`, it never
-conditionally unmounts. Its visual position (left for off, right for on) is
-driven entirely by CSS targeting `data-state`. This gives consumers a real DOM
-node to animate with `transition` or Web Animations, rather than being
-constrained to pseudo-elements.
+`Switch.Thumb` is **always mounted**. Its visual position (off → on) should be
+driven by CSS keyed off the input's native `:checked` (a sibling selector), so
+it stays correct through a form reset. It gives consumers a real DOM node to
+animate with `transition` or Web Animations.
 
-```scss
-.switch-root {
+```css
+.switch {
   position: relative;
-  width: 2.75rem;
-  height: 1.5rem;
-  border-radius: 9999px;
-  background: #d1d5db;
-  transition: background 120ms ease;
-
-  &[data-state="checked"] {
-    background: #6366f1;
-  }
 }
-
-.switch-thumb {
-  position: absolute;
-  top: 0.125rem;
-  left: 0.125rem;
-  width: 1.25rem;
-  height: 1.25rem;
-  border-radius: 50%;
-  background: white;
+.switch:has(> input:checked) {
+  background: #6366f1;
+}
+.switch__thumb {
   transition: translate 120ms ease;
-
-  &[data-state="checked"] {
-    translate: 1.25rem 0;
-  }
+}
+.switch > input:checked ~ .switch__thumb {
+  translate: 1.25rem 0;
 }
 ```
 
 ## `asChild` composition
 
-Both sub-components accept `asChild`. The library's ARIA attributes,
-`data-state`, event handlers, and ref are merged onto the consumer's element.
+`Switch.Thumb` accepts `asChild`: the library's `aria-hidden`, `data-state`, and
+ref are merged onto the consumer's element.
 
 ```tsx
-<Switch.Root asChild aria-label="Enable notifications">
-  <div role="switch">…</div>
-</Switch.Root>
+<Switch.Thumb asChild>
+  <span className="my-thumb" />
+</Switch.Thumb>
 ```
 
 ## Styling hooks
 
 | Attribute | Values | Set on |
 |-----------|--------|--------|
-| `data-state` | `"checked"` \| `"unchecked"` | `Switch.Root`, `Switch.Thumb` |
-| `data-disabled` | `""` (present when disabled) | `Switch.Root` |
+| `data-state` | `"checked"` \| `"unchecked"` | `Switch.Root` (track), `Switch.Thumb` |
+| `data-disabled` | `""` (present when disabled) | `Switch.Root` (track) |
+| `:checked` / `:focus-visible` / `:disabled` | native | the hidden `<input>` |