@primitiv-ui/react 0.1.12 → 0.1.14

package/README.md

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

package/package.json

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

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

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

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

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render } from "@testing-library/react";
+
+import { Field } from "../Field";
+
+/**
+ * Auto-verification of the Field styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/field/contract.json` is *derived from and
+ * asserted against the rendered headless `Field.Root`* so it can never drift from
+ * what the component emits. The root always carries `data-field`, plus
+ * `data-field-invalid` / `data-field-disabled` / `data-field-required` when the
+ * matching flag is set. The authored half (part classes, custom properties) is a
+ * styling convention the headless layer does not emit and is checked by the
+ * generator drift-guards instead.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/field/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+/** Render a `Field.Root` with the given flags and return its `[data-field]` element. */
+function renderRoot(props: Record<string, boolean>): Element {
+  const { container } = render(<Field.Root {...props} />);
+  return container.querySelector("[data-field]")!;
+}
+
+describe("Field styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The Field 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 props of [{}, { invalid: true, disabled: true, required: true }]) {
+      for (const name of dataAttributeNames(renderRoot(props))) {
+        emitted.add(name);
+      }
+    }
+
+    const contracted = new Set(
+      autoAttributes.map((attribute: { name: string }) => attribute.name),
+    );
+    expect([...emitted].sort()).toEqual([...contracted].sort());
+  });
+
+  it("always emits data-field regardless of state", () => {
+    expect(renderRoot({})).toHaveAttribute("data-field", "");
+  });
+
+  it("emits each conditional attribute exactly as the contract documents it", () => {
+    const conditional = autoAttributes.filter(
+      (attribute: { when: string }) => attribute.when !== "always",
+    );
+
+    for (const entry of conditional) {
+      const root = renderRoot({ [entry.when]: true });
+      expect(root).toHaveAttribute(entry.name, entry.value);
+    }
+  });
+
+  it("omits each conditional attribute when its flag is not set", () => {
+    const root = renderRoot({});
+    for (const entry of autoAttributes.filter(
+      (attribute: { when: string }) => attribute.when !== "always",
+    )) {
+      expect(root).not.toHaveAttribute(entry.name);
+    }
+  });
+});

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

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+
+import { Input } from "../Input";
+
+/**
+ * Auto-verification of the Input styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/input/contract.json` is *derived from and
+ * asserted against the rendered headless component* so it can never drift from
+ * what the component actually emits. Input's only data-* surface is
+ * `data-disabled=""` when disabled — `invalid` is an `aria-invalid` concern, not
+ * a data attribute. The authored half (root class, custom properties) is a
+ * styling convention the headless layer does not emit and is checked by the
+ * generator drift-guards instead.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/input/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+describe("Input styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The Input 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 [
+      <Input key="default" aria-label="x" />,
+      <Input key="disabled" aria-label="x" disabled />,
+    ]) {
+      const { unmount } = render(ui);
+      for (const name of dataAttributeNames(screen.getByRole("textbox"))) {
+        emitted.add(name);
+      }
+      unmount();
+    }
+
+    const contracted = new Set(
+      autoAttributes.map((attribute: { name: string }) => attribute.name),
+    );
+    expect([...emitted].sort()).toEqual([...contracted].sort());
+  });
+
+  it("emits data-disabled exactly as the contract documents it", () => {
+    const entry = autoAttributes.find(
+      (attribute: { name: string }) => attribute.name === "data-disabled",
+    );
+
+    render(<Input aria-label="x" disabled />);
+    expect(screen.getByRole("textbox")).toHaveAttribute(entry.name, entry.value);
+  });
+
+  it("omits data-disabled when the documented condition does not hold", () => {
+    render(<Input aria-label="x" />);
+
+    expect(screen.getByRole("textbox")).not.toHaveAttribute("data-disabled");
+  });
+});

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

@@ -0,0 +1,60 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render } from "@testing-library/react";
+
+import { InputGroup } from "../InputGroup";
+
+/**
+ * Auto-verification of the InputGroup styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/input-group/contract.json` is *derived
+ * from and asserted against the rendered headless `InputGroup.Root`* so it can
+ * never drift. The root always carries `data-input-group`; the adornment slots
+ * are styled through their part classes, not a contracted data attribute. The
+ * authored half (part classes, custom properties) is a styling convention the
+ * headless layer does not emit and is checked by the generator drift-guards.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/input-group/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+describe("InputGroup styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The InputGroup root has no authored data-* surface; the contract is derived.
+    expect(autoAttributes).toHaveLength(contract.dataAttributes.length);
+  });
+
+  it("emits exactly the contracted data-* attribute names on the root", () => {
+    const { container } = render(<InputGroup.Root />);
+    const root = container.querySelector("[data-input-group]")!;
+
+    const contracted = autoAttributes
+      .map((attribute: { name: string }) => attribute.name)
+      .sort();
+    expect(dataAttributeNames(root)).toEqual(contracted);
+  });
+
+  it("always emits data-input-group", () => {
+    const { container } = render(<InputGroup.Root />);
+    expect(container.querySelector("[data-input-group]")).toHaveAttribute(
+      "data-input-group",
+      "",
+    );
+  });
+});

package/src/Radio/README.md

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