@primitiv-ui/react 0.1.15 → 0.1.16

package/README.md

@@ -25,7 +25,7 @@ import { Tabs } from "@primitiv-ui/react";
 | [Breadcrumb](src/Breadcrumb/README.md)   | WAI-ARIA Breadcrumb pattern — stateless compound component: a `<nav>` landmark wrapping an ordered list of ancestor-page links, decorative separators with a configurable glyph, an `aria-current` current page, and `asChild` composition on the link                                  |
 | [Button](src/Button/README.md)           | Headless semantic `<button>` with `type="button"` default, ref forwarding, `disabled` with `data-disabled` styling hook, and `asChild` composition                                                                                                                                     |
 | [Carousel](src/Carousel/README.md)       | WAI-ARIA Carousel pattern — compound component built on native CSS scroll-snap with swipe support, keyboard navigation, slide indicators, optional auto-rotation with WCAG 2.2.2 pause behaviour, and `asChild` composition                                                             |
-| [Checkbox](src/Checkbox/README.md)       | WAI-ARIA Checkbox pattern — native `<button role="checkbox">` with tri-state (`"indeterminate"` / `aria-checked="mixed"`), controlled/uncontrolled state, `Indicator` slot, and `asChild` composition                                                                                   |
+| [Checkbox](src/Checkbox/README.md)       | A real, visually-hidden native `<input type="checkbox">` in a `<label>` box, so it participates in forms; the platform tri-state (`indeterminate` → `aria-checked="mixed"`, `:indeterminate`), controlled/uncontrolled state, `Indicator` mark, and `asChild` on the indicator                                                                                   |
 | [CheckboxCard](src/CheckboxCard/README.md) | WAI-ARIA Checkbox pattern in a card/tile layout — the entire card surface is the interactive element, with tri-state support, controlled/uncontrolled state, `Indicator` slot, `disabled` with `data-disabled` styling hook, and `asChild` composition                                |
 | [Collapsible](src/Collapsible/README.md) | Single-panel show/hide — boolean controlled/uncontrolled state, `disabled`, `asChild` composition with explicit Enter/Space handling, `forceMount` for CSS-Grid-driven animation, and `TriggerIcon` slot                                                                                |
 | [ContextMenu](src/ContextMenu/README.md) | WAI-ARIA Menu pattern for right-click / long-press / context-key menus — native HTML `popover` compound component positioned at the cursor, with nested submenus, checkbox and radio items, `ItemIndicator` icon slot, groups and labels, keyboard navigation, typeahead, disabled-item skipping, `onSelect` escape hatch, and `asChild` composition |
@@ -41,14 +41,14 @@ 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)                                                |
+| [Radio](src/Radio/README.md)             | Standalone — a real, visually-hidden native `<input type="radio">` in a `<label>` box, so siblings sharing a `name` form a native radio group (the browser enforces single-selection) and it participates in forms; controlled/uncontrolled state, `Indicator` dot, `disabled` with `data-disabled` styling hook, and `asChild` on the indicator (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`) |
 | [SkipNav](src/SkipNav/README.md)         | WCAG 2.4.1 Bypass Blocks technique — a stateless "skip to main content" link and its `tabIndex=-1` focus target, connected by a shared content id, working with no JavaScript at runtime |
 | [Slider](src/Slider/README.md)           | WAI-ARIA Slider & Multi-Thumb Slider pattern — an array-valued range input with any number of independently focusable thumbs, keyboard and pointer dragging, `min`/`max`/`step`, `minStepsBetweenThumbs`, horizontal/vertical orientation, RTL and `inverted` direction, `onValueCommit`, hidden inputs for form submission, `disabled` with `data-disabled` styling hook, and `asChild` composition                                              |
 | [Status](src/Status/README.md)           | WAI-ARIA `status` role — a polite live region for low-priority, non-urgent status messages, announced once the user is idle, with `asChild` composition |
-| [Switch](src/Switch/README.md)           | WAI-ARIA Switch pattern — `<button role="switch">` with binary on/off state, always-mounted `Thumb` sub-component for CSS-driven sliding animation, controlled/uncontrolled state, `data-disabled` styling hook, and `asChild` composition                                              |
+| [Switch](src/Switch/README.md)           | A real, visually-hidden native `<input type="checkbox" role="switch">` in a `<label>` track, so it participates in forms; binary on/off state, always-mounted `Thumb` for CSS-driven sliding (off the input's native `:checked`), controlled/uncontrolled state, `data-disabled` styling hook, and `asChild` on the thumb                                              |
 | [Table](src/Table/README.md)             | WAI-ARIA Table pattern — compound component wrapping standard HTML table elements with accessible headers, captions, and a responsive scroll wrapper                                                                                                                                    |
 | [Tabs](src/Tabs/README.md)               | WAI-ARIA Tabs pattern — compound component with keyboard navigation, controlled/uncontrolled state, and `asChild` composition                                                                                                                                                           |
 | [Textarea](src/Textarea/README.md)       | Headless multi-line text input — native `<textarea>` with full attribute pass-through, ref forwarding, `disabled` with `data-disabled` styling hook, `asChild` composition for wrapping autosizing implementations, 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.15",
+  "version": "0.1.16",
   "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/Checkbox.tsx

@@ -1,10 +1,10 @@
-import { useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import type { ReactElement } from "react";
 
-import { Slot, composeEventHandlers } from "../Slot/index.ts";
+import { Slot, composeRefs } from "../Slot/index.ts";
 
 import { CheckboxContext } from "./CheckboxContext";
-import { useCheckboxContext, useCheckboxRoot } from "./hooks/index.ts";
+import { useCheckboxContext, useCheckboxInput } from "./hooks/index.ts";
 import {
   CheckboxIndicatorProps,
   CheckboxRootProps,
@@ -17,104 +17,105 @@ function dataStateOf(checked: CheckedState) {
 }
 
 /**
- * The root of a Checkbox — a native `<button role="checkbox">` that
- * owns the tri-state checked value and provides
- * {@link CheckboxContext | `CheckboxContext`} to descendant
- * {@link CheckboxIndicator | `Checkbox.Indicator`}s.
+ * The root of a Checkbox — a `<label>` that is itself the **visible, styled
+ * box** and wraps a **real, visually-hidden `<input type="checkbox">`** (the
+ * focusable, form-participating control) plus the decorative
+ * {@link CheckboxIndicator | `Checkbox.Indicator`} mark. It provides
+ * {@link CheckboxContext | `CheckboxContext`} to the indicator.
+ *
+ * Because the underlying element is a genuine native checkbox, it behaves like
+ * one: it submits its `value` under `name` with an enclosing form, resets with
+ * the form, and gets keyboard activation and focus for free. The tri-state
+ * `"indeterminate"` is the platform's own: it is applied via the input's
+ * `.indeterminate` DOM property, so the browser exposes `aria-checked="mixed"`
+ * and the `:indeterminate` pseudo-class for styling.
+ *
+ * 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 checkbox.
  *
  * Supports two state modes, statically discriminated at the type level:
  *
  * - **Uncontrolled** — pass
- *   {@link CheckboxRootProps.defaultChecked | `defaultChecked`} (or omit
- *   for unchecked-on-mount). The component owns the value internally.
+ *   {@link CheckboxRootProps.defaultChecked | `defaultChecked`} (or omit). It
+ *   may be `"indeterminate"` for a mixed-on-mount checkbox.
  * - **Controlled** — pass
  *   {@link CheckboxRootProps.checked | `checked`} *and*
- *   {@link CheckboxRootProps.onCheckedChange | `onCheckedChange`}
- *   together. The parent owns the value; the component defers every
- *   change back through the callback.
- *
- * Both `checked` and `defaultChecked` accept `boolean | "indeterminate"`.
- * Clicking an indeterminate checkbox resolves it to `true` per the
- * WAI-ARIA tri-state convention, then flips boolean on subsequent clicks.
- *
- * **ARIA.** `role="checkbox"` and `aria-checked` are set automatically;
- * `aria-checked="mixed"` represents the indeterminate state.
+ *   {@link CheckboxRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   Clicking a mixed checkbox resolves it to `true`.
  *
  * **Styling hooks.** `data-state="checked" | "unchecked" | "indeterminate"`
- * on the root, plus `data-disabled=""` when disabled.
- *
- * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
- * element (e.g. `<li role="menuitemcheckbox">` for menu composition)
- * with the checkbox'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.
+ * and `data-disabled=""` on the box (and `data-state` on the indicator). These
+ * mirror the input, but shipped CSS keys the mark off the input's native
+ * `:checked` / `:indeterminate` instead; `data-state` is a convenience mirror.
  *
  * @example Uncontrolled
  * ```tsx
- * <Checkbox.Root defaultChecked aria-label="Accept terms">
- *   <Checkbox.Indicator>
- *     <CheckIcon />
- *   </Checkbox.Indicator>
+ * <Checkbox.Root name="terms" value="accepted" defaultChecked aria-label="Accept terms">
+ *   <Checkbox.Indicator />
  * </Checkbox.Root>
  * ```
  *
- * @example Controlled
+ * @example Controlled tri-state
  * ```tsx
- * const [checked, setChecked] = useState<CheckedState>(false);
+ * const [checked, setChecked] = useState<CheckedState>("indeterminate");
  *
  * <Checkbox.Root checked={checked} onCheckedChange={setChecked} aria-label="…">
- *   <Checkbox.Indicator>
- *     <CheckIcon />
- *   </Checkbox.Indicator>
- * </Checkbox.Root>
- * ```
- *
- * @example Composed into a menu item via `asChild`
- * ```tsx
- * <Checkbox.Root asChild aria-label="Show hidden files">
- *   <li role="menuitemcheckbox">Show hidden files</li>
+ *   <Checkbox.Indicator />
  * </Checkbox.Root>
  * ```
  */
 export function CheckboxRoot(props: CheckboxRootProps): ReactElement {
   const {
-    defaultChecked,
-    checked,
-    onCheckedChange,
-    onClick,
-    disabled,
-    asChild = false,
+    className,
+    style,
     children,
-    ...rest
-  } = props;
-  const { checked: isChecked, toggle } = useCheckboxRoot({
     defaultChecked,
     checked,
     onCheckedChange,
-  });
-  const contextValue = useMemo(() => ({ checked: isChecked }), [isChecked]);
-  const rootProps = {
-    ...rest,
-    role: "checkbox" as const,
-    "aria-checked":
-      isChecked === "indeterminate"
-        ? ("mixed" as const)
-        : (isChecked as boolean),
-    "data-state": dataStateOf(isChecked),
-    "data-disabled": disabled ? "" : undefined,
+    onChange,
     disabled,
-    onClick: composeEventHandlers(onClick, toggle),
-  };
+    ref,
+    ...inputRest
+  } = props;
+  const {
+    checked: value,
+    handleChange,
+    inputStateProps,
+  } = useCheckboxInput({ defaultChecked, checked, onCheckedChange, onChange });
+
+  // `indeterminate` is a DOM property with no JSX attribute, so it is applied
+  // imperatively whenever the resolved tri-state value changes. The input is
+  // rendered unconditionally, so the ref is always set here.
+  const inputRef = useRef<HTMLInputElement>(null);
+  useEffect(() => {
+    inputRef.current!.indeterminate = value === "indeterminate";
+  }, [value]);
+  const composedRef = ref ? composeRefs(inputRef, ref) : inputRef;
+
+  const contextValue = useMemo(
+    () => ({ checked: value, disabled: Boolean(disabled) }),
+    [value, disabled],
+  );
   return (
     <CheckboxContext.Provider value={contextValue}>
-      {asChild ? (
-        <Slot {...rootProps}>{children}</Slot>
-      ) : (
-        <button type="button" {...rootProps}>
-          {children}
-        </button>
-      )}
+      <label
+        className={className}
+        style={style}
+        data-state={dataStateOf(value)}
+        data-disabled={disabled ? "" : undefined}
+      >
+        <input
+          type="checkbox"
+          ref={composedRef}
+          disabled={disabled}
+          {...inputRest}
+          {...inputStateProps}
+          onChange={handleChange}
+        />
+        {children}
+      </label>
     </CheckboxContext.Provider>
   );
 }
@@ -123,32 +124,19 @@ export function CheckboxRoot(props: CheckboxRootProps): ReactElement {
 CheckboxRoot.displayName = "CheckboxRoot";
 
 /**
- * A decorative `<span aria-hidden="true">` that renders its children
- * only while the parent {@link CheckboxRoot | `Checkbox.Root`} is
- * **checked** or **indeterminate** — never when unchecked. The
- * checkbox's accessible state is already conveyed by `aria-checked`
- * on the root, so the indicator is purely visual.
+ * The decorative mark — a `<span>` that is **always mounted**, sitting inside
+ * the {@link CheckboxRoot | `Checkbox.Root`} box. Its visibility and shape (a
+ * tick when checked, a bar when indeterminate) are a pure CSS concern, revealed
+ * off the input's native `:checked` / `:indeterminate` state. The checkbox's
+ * accessible state is conveyed by the native input, so the mark is purely
+ * visual.
  *
  * **Styling hook.** Mirrors the root's
- * `data-state="checked" | "unchecked" | "indeterminate"` so the same
- * CSS rules can target both.
- *
- * **`asChild` prop.** Pass `asChild` to render the consumer's own
- * element (typically an `<svg>` tick icon) 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.
+ * `data-state="checked" | "unchecked" | "indeterminate"`.
  *
- * @example Default span wrapper
- * ```tsx
- * <Checkbox.Indicator>
- *   <CheckIcon />
- * </Checkbox.Indicator>
- * ```
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` tick) as the indicator itself, with `data-state`
+ * merged onto that element rather than a wrapper.
  *
  * @example Icon as the indicator via `asChild`
  * ```tsx
@@ -157,24 +145,14 @@ CheckboxRoot.displayName = "CheckboxRoot";
  * </Checkbox.Indicator>
  * ```
  *
- * @example Force-mounted for exit animation
- * ```tsx
- * <Checkbox.Indicator forceMount>
- *   <CheckIcon />
- * </Checkbox.Indicator>
- * ```
- *
  * @throws if rendered outside a `Checkbox.Root`.
  */
 export function CheckboxIndicator({
   children,
-  forceMount,
   asChild = false,
   ...rest
-}: CheckboxIndicatorProps): ReactElement | null {
+}: CheckboxIndicatorProps): ReactElement {
   const { checked } = useCheckboxContext();
-  const isVisible = checked !== false;
-  if (!isVisible && !forceMount) return null;
   const indicatorProps = {
     ...rest,
     "aria-hidden": "true" as const,
@@ -196,31 +174,29 @@ export type TCheckboxCompound = typeof CheckboxRoot & {
 };
 
 /**
- * Headless, accessible **Checkbox** — a compound component built on a
- * native `<button role="checkbox">` that implements the
- * [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
- * including the tri-state ("mixed") variant. Zero styles ship.
+ * Headless, accessible **Checkbox** — a compound component built on a **real,
+ * visually-hidden native `<input type="checkbox">`**, including the platform's
+ * own tri-state (`indeterminate` → `aria-checked="mixed"`). Unlike a button
+ * dressed up with `role="checkbox"`, it participates in native forms. Zero
+ * styles ship.
  *
- * `Checkbox` is both callable (an alias of {@link CheckboxRoot | `Checkbox.Root`})
- * and carries its sub-components as static properties. Prefer the
- * namespaced form in application code for readability and grep-ability.
+ * `Checkbox` is both callable (an alias of
+ * {@link CheckboxRoot | `Checkbox.Root`}) and carries its sub-components as
+ * static properties.
  *
- * - {@link CheckboxRoot | `Checkbox.Root`} — state owner, context provider, toggle button.
- * - {@link CheckboxIndicator | `Checkbox.Indicator`} — decorative tick, conditional on checked state.
+ * - {@link CheckboxRoot | `Checkbox.Root`} — the styled box: label + hidden input, state owner, context provider.
+ * - {@link CheckboxIndicator | `Checkbox.Indicator`} — the decorative mark.
  *
  * @example Minimal usage
  * ```tsx
  * import { Checkbox } from "@primitiv-ui/react";
  *
- * <Checkbox.Root aria-label="Accept terms">
- *   <Checkbox.Indicator>
- *     <CheckIcon />
- *   </Checkbox.Indicator>
+ * <Checkbox.Root name="terms" value="accepted" aria-label="Accept terms">
+ *   <Checkbox.Indicator />
  * </Checkbox.Root>;
  * ```
  *
  * @see {@link CheckboxRoot} for state modes and tri-state semantics.
- * @see {@link CheckboxIndicator} for the mount gate and animation hooks.
  */
 const CheckboxCompound: TCheckboxCompound = Object.assign(CheckboxRoot, {
   Root: CheckboxRoot,

package/src/Checkbox/CheckboxContext.ts

@@ -3,7 +3,15 @@ import { createStrictContext } from "../utils/index.ts";
 import { CheckedState } from "./types";
 
 export type CheckboxContextValue = {
+  /**
+   * Best-effort mirror of the input's tri-state value, for the `data-state`
+   * hook on the indicator. The shipped CSS reveals the mark off the input's
+   * native `:checked` / `:indeterminate` instead, so it stays correct through
+   * a form reset; `data-state` is a convenience mirror.
+   */
   checked: CheckedState;
+  /** Whether the checkbox is disabled, for the `data-disabled` hook. */
+  disabled: boolean;
 };
 
 export const [CheckboxContext, useCheckboxContext] =

package/src/Checkbox/README.md

@@ -1,107 +1,111 @@
 # Checkbox
 
-A headless, accessible compound component implementing the
-[WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/),
-including the tri-state ("mixed") variant.
-
-Checkbox renders a native `<button role="checkbox">` so it gets
-keyboard activation (`Space` / `Enter`), focus ring, and disabled
-semantics for free from the browser. The React layer adds three-state
-support, `Indicator` mounting driven by the checked state, and the
-`asChild` composition every primitive in this package supports.
+A headless, accessible Checkbox built on a **real native
+`<input type="checkbox">`**, including the platform's own tri-state
+("mixed") variant.
+
+Checkbox renders a `<label>` that is the visible box, wrapping a
+visually-hidden native `<input type="checkbox">` (the focusable,
+form-participating control) and a decorative `Indicator` mark. Because the
+underlying element is a genuine native checkbox, it submits its `value`
+under `name` with an enclosing form, resets with the form, and gets keyboard
+activation and focus for free. The `"indeterminate"` state is the
+platform's: it is applied via the input's `.indeterminate` DOM property, so
+the browser exposes `aria-checked="mixed"` and the `:indeterminate`
+pseudo-class for styling.
 
 ```tsx
 import { Checkbox } from "@primitiv-ui/react";
 
-<Checkbox.Root defaultChecked aria-label="Accept terms">
-  <Checkbox.Indicator>
-    <CheckIcon />
-  </Checkbox.Indicator>
+<Checkbox.Root name="terms" value="accepted" defaultChecked aria-label="Accept terms">
+  <Checkbox.Indicator />
 </Checkbox.Root>;
 ```
 
 ## Sub-components
 
-| Export               | Element    | Notes                                                                                      |
-| -------------------- | ---------- | ------------------------------------------------------------------------------------------ |
-| `Checkbox.Root`      | `<button>` | `role="checkbox"`, `aria-checked`, `data-state`, `data-disabled`. `asChild`                |
-| `Checkbox.Indicator` | `<span>`   | `aria-hidden="true"`. Renders only while checked or indeterminate. `asChild`, `forceMount` |
+| Export               | Element                          | Notes                                                                                       |
+| -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `Checkbox.Root`      | `<label>` + hidden `<input>`     | The styled box. `data-state`, `data-disabled` on the label; `name`/`value`/`aria-*`/`ref` go to the input. |
+| `Checkbox.Indicator` | `<span>`                         | `aria-hidden="true"`. Always mounted; CSS reveals it. `asChild`                             |
+
+`Checkbox.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 checkbox: pass `name`, `value`, `id`, `required`, `aria-*`,
+`ref`, etc. straight to `Checkbox.Root`.
 
 ## Checked state
 
 Checkbox is tri-state. The `checked` / `defaultChecked` value is
 `boolean | "indeterminate"`:
 
-| Value             | `aria-checked` | `data-state`      | Indicator renders?       |
-| ----------------- | -------------- | ----------------- | ------------------------ |
-| `true`            | `"true"`       | `"checked"`       | Yes                      |
-| `false`           | `"false"`      | `"unchecked"`     | No (unless `forceMount`) |
-| `"indeterminate"` | `"mixed"`      | `"indeterminate"` | Yes                      |
+| Value             | Native           | `data-state`      | Mark visible? |
+| ----------------- | ---------------- | ----------------- | ------------- |
+| `true`            | `:checked`       | `"checked"`       | Yes (tick)    |
+| `false`           | —                | `"unchecked"`     | No            |
+| `"indeterminate"` | `:indeterminate` | `"indeterminate"` | Yes (bar)     |
 
-Clicking an indeterminate checkbox resolves it to `true` per the
-WAI-ARIA tri-state convention; subsequent clicks flip between `true`
-and `false`.
+Clicking an indeterminate checkbox resolves it to `true` per the WAI-ARIA
+tri-state convention (the native default); subsequent clicks flip between
+`true` and `false`.
 
 ## State modes
 
 - **Uncontrolled** — pass `defaultChecked` (or omit for unchecked on mount).
+  It may be `"indeterminate"`.
 - **Controlled** — pass `checked` **and** `onCheckedChange` together.
 
-The two shapes are statically discriminated at the type level;
-TypeScript rejects mixing them.
+The two shapes are statically discriminated at the type level; TypeScript
+rejects mixing them.
 
 ```tsx
 // Uncontrolled
-<Checkbox.Root defaultChecked>…</Checkbox.Root>;
+<Checkbox.Root name="terms" value="accepted" defaultChecked>
+  <Checkbox.Indicator />
+</Checkbox.Root>;
 
 // Controlled
 const [checked, setChecked] = useState<CheckedState>(false);
 <Checkbox.Root checked={checked} onCheckedChange={setChecked}>
-  …
+  <Checkbox.Indicator />
 </Checkbox.Root>;
 ```
 
+> **`data-state` is a best-effort mirror.** Drive the *visual* checked look off
+> the input's native `:checked` / `:indeterminate` (and `:has(> input:checked)`
+> on the box), as the shipped registry stylesheet does — it stays correct
+> through a form reset, which fires no React event.
+
 ## Keyboard interaction
 
-| Key     | Behaviour                                |
-| ------- | ---------------------------------------- |
-| `Space` | Toggles the checkbox (native `<button>`) |
-| `Enter` | Toggles the checkbox (native `<button>`) |
+| Key     | Behaviour                                    |
+| ------- | -------------------------------------------- |
+| `Space` | Toggles the focused checkbox (native input)  |
+| `Tab`   | Moves to / from the checkbox (native)        |
 
-Keyboard handling comes from the underlying `<button>` element — no
-custom `keydown` listeners are needed.
+Keyboard handling comes from the underlying native input — no custom `keydown`
+listeners are needed.
 
 ## 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`.
+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 box so CSS can target `[data-disabled]` without
+reaching for `:disabled`.
 
 ```tsx
 <Checkbox.Root disabled aria-label="Locked setting">
-  <Checkbox.Indicator>
-    <CheckIcon />
-  </Checkbox.Indicator>
+  <Checkbox.Indicator />
 </Checkbox.Root>
 ```
 
 ## `asChild` composition
 
-Both `Checkbox.Root` and `Checkbox.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`).
+`Checkbox.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 an `<svg>` tick:
 
 ```tsx
-// Menu-item checkbox — the same state machinery, different element + role.
-<Checkbox.Root asChild aria-label="Show hidden files">
-  <li role="menuitemcheckbox">Show hidden files</li>
-</Checkbox.Root>
-
-// Icon-only indicator — the svg itself becomes the indicator.
 <Checkbox.Indicator asChild>
   <svg viewBox="0 0 10 10">
     <path d="M1 5l3 3 5-7" />
@@ -109,47 +113,24 @@ calls `preventDefault`).
 </Checkbox.Indicator>
 ```
 
-`Root`'s `asChild` is what lets `Dropdown.CheckboxItem` (in a later
-phase) wrap an `<li role="menuitemcheckbox">` around the Checkbox
-state / toggle behaviour without re-implementing any of it.
-
-## Animation hooks
-
-`Checkbox.Indicator` accepts a `forceMount` boolean. When set, the
-indicator stays in the DOM regardless of checked state so a CSS
-animation can play against `data-state="unchecked"`:
-
-```tsx
-<Checkbox.Indicator forceMount>
-  <CheckIcon />
-</Checkbox.Indicator>
-```
-
-```css
-[data-state="checked"] {
-  animation: tick-in 120ms ease-out;
-}
-[data-state="unchecked"] {
-  animation: tick-out 100ms ease-in forwards;
-}
-```
-
-Consumers using `forceMount` own the exit timing themselves.
-
 ## Styling hooks
 
-`data-state="checked" | "unchecked" | "indeterminate"` is set on both
-`Checkbox.Root` and `Checkbox.Indicator`, letting any CSS system target
-the three phases.
+- The box (`Checkbox.Root`) carries
+  `data-state="checked" | "unchecked" | "indeterminate"` and `data-disabled=""`.
+- The hidden input exposes the always-correct native states: `:checked`,
+  `:indeterminate`, `:focus-visible`, `:disabled`. Prefer these for the *marked*
+  look.
 
 ```css
-button[data-state="checked"] {
+.checkbox:has(> input:checked),
+.checkbox:has(> input:indeterminate) {
   background: oklch(65% 0.18 145);
 }
-button[data-state="indeterminate"] {
-  background: oklch(70% 0.1 250);
+.checkbox > input:checked ~ .checkbox__indicator,
+.checkbox > input:indeterminate ~ .checkbox__indicator {
+  scale: 1;
 }
-button[data-disabled] {
+.checkbox[data-disabled] {
   opacity: 0.5;
   cursor: not-allowed;
 }