@primitiv-ui/react 0.1.12 → 0.1.14

package/src/Radio/Radio.tsx

@@ -0,0 +1,213 @@
+import { useMemo } from "react";
+import type { ReactElement } from "react";
+
+import { Slot, composeEventHandlers } from "../Slot/index.ts";
+
+import { RadioContext } from "./RadioContext";
+import { useRadioContext, useRadioRoot } from "./hooks/index.ts";
+import { RadioIndicatorProps, RadioRootProps } from "./types";
+
+function dataStateOf(checked: boolean) {
+  return checked ? ("checked" as const) : ("unchecked" as const);
+}
+
+/**
+ * The root of a Radio — a native `<button role="radio">` that owns a
+ * single boolean selected value and provides
+ * {@link RadioContext | `RadioContext`} to descendant
+ * {@link RadioIndicator | `Radio.Indicator`}s.
+ *
+ * Unlike a checkbox, selection is **one-way**: clicking an unselected
+ * radio selects it, but clicking the already-selected radio is a no-op —
+ * a lone radio never toggles itself off. De-selection happens when a
+ * sibling is chosen, which is the grouping consumer's concern. For a
+ * managed set with roving-tabindex keyboard navigation, reach for
+ * `RadioGroup` instead; `Radio` is the standalone control for when you
+ * own the grouping (e.g. a native form `name`, or a bespoke layout).
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link RadioRootProps.defaultChecked | `defaultChecked`} (or omit for
+ *   unselected-on-mount). The component owns the value internally.
+ * - **Controlled** — pass {@link RadioRootProps.checked | `checked`} *and*
+ *   {@link RadioRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   The parent owns the value; the component defers selection back through
+ *   the callback.
+ *
+ * **ARIA.** `role="radio"` and `aria-checked` are set automatically.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked"` on the root,
+ * plus `data-disabled=""` when disabled.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element (e.g. `<li role="menuitemradio">` for menu composition) with
+ * the radio's ARIA attributes, data-state, composed onClick, and ref
+ * merged in. The native `<button>` is dropped; consumers who want keyboard
+ * activation on a non-button element are responsible for providing it.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Radio.Root defaultChecked aria-label="Compact">
+ *   <Radio.Indicator />
+ * </Radio.Root>
+ * ```
+ *
+ * @example Controlled (consumer owns the group)
+ * ```tsx
+ * const [value, setValue] = useState("comfortable");
+ *
+ * <Radio.Root
+ *   checked={value === "compact"}
+ *   onCheckedChange={() => setValue("compact")}
+ *   aria-label="Compact"
+ * >
+ *   <Radio.Indicator />
+ * </Radio.Root>
+ * ```
+ */
+export function RadioRoot(props: RadioRootProps): ReactElement {
+  const {
+    defaultChecked,
+    checked,
+    onCheckedChange,
+    onClick,
+    disabled,
+    asChild = false,
+    children,
+    ...rest
+  } = props;
+  const { checked: isChecked, select } = useRadioRoot({
+    defaultChecked,
+    checked,
+    onCheckedChange,
+  });
+  const contextValue = useMemo(() => ({ checked: isChecked }), [isChecked]);
+  const rootProps = {
+    ...rest,
+    role: "radio" as const,
+    "aria-checked": isChecked,
+    "data-state": dataStateOf(isChecked),
+    "data-disabled": disabled ? "" : undefined,
+    disabled,
+    onClick: composeEventHandlers(onClick, select),
+  };
+  return (
+    <RadioContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...rootProps}>
+          {children}
+        </button>
+      )}
+    </RadioContext.Provider>
+  );
+}
+
+/** @internal */
+RadioRoot.displayName = "RadioRoot";
+
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children only
+ * while the parent {@link RadioRoot | `Radio.Root`} is **selected** —
+ * typically the filled dot inside a radio control. The radio's accessible
+ * state is already conveyed by `aria-checked` on the root, so the indicator
+ * is purely visual.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked"` so the same CSS rule can target
+ * both.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` dot) as the indicator itself, with `aria-hidden`
+ * and `data-state` merged onto that element rather than a wrapper.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the indicator in the
+ * DOM while unchecked so a CSS exit animation can play against
+ * `data-state="unchecked"`. Consumers who use `forceMount` own the exit
+ * lifecycle themselves.
+ *
+ * @example Default span wrapper
+ * ```tsx
+ * <Radio.Root aria-label="Compact">
+ *   <Radio.Indicator />
+ *   Compact
+ * </Radio.Root>
+ * ```
+ *
+ * @example Dot as the indicator via `asChild`
+ * ```tsx
+ * <Radio.Indicator asChild>
+ *   <svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="3" /></svg>
+ * </Radio.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `Radio.Root`.
+ */
+export function RadioIndicator({
+  children,
+  forceMount,
+  asChild = false,
+  ...rest
+}: RadioIndicatorProps): ReactElement | null {
+  const { checked } = useRadioContext();
+  if (!checked && !forceMount) return null;
+  const indicatorProps = {
+    ...rest,
+    "aria-hidden": "true" as const,
+    "data-state": dataStateOf(checked),
+  };
+  if (asChild) {
+    return <Slot {...indicatorProps}>{children}</Slot>;
+  }
+  return <span {...indicatorProps}>{children}</span>;
+}
+
+/** @internal */
+RadioIndicator.displayName = "RadioIndicator";
+
+/** Type of the {@link Radio} compound: the root callable plus its attached sub-components. */
+export type TRadioCompound = typeof RadioRoot & {
+  Root: typeof RadioRoot;
+  Indicator: typeof RadioIndicator;
+};
+
+/**
+ * Headless, accessible **Radio** — a standalone compound component built
+ * on a native `<button role="radio">` that implements the single-selection
+ * half of the
+ * [WAI-ARIA Radio pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+ * Zero styles ship.
+ *
+ * `Radio` is the lone control for when you own the grouping; for a managed
+ * set with roving-tabindex keyboard navigation use `RadioGroup`.
+ *
+ * `Radio` is both callable (an alias of {@link RadioRoot | `Radio.Root`})
+ * and carries its sub-components as static properties. Prefer the
+ * namespaced form in application code for readability and grep-ability.
+ *
+ * - {@link RadioRoot | `Radio.Root`} — state owner, context provider, select button.
+ * - {@link RadioIndicator | `Radio.Indicator`} — decorative dot, conditional on selected state.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Radio } from "@primitiv-ui/react";
+ *
+ * <Radio.Root aria-label="Compact">
+ *   <Radio.Indicator />
+ * </Radio.Root>;
+ * ```
+ *
+ * @see {@link RadioRoot} for state modes and one-way selection semantics.
+ * @see {@link RadioIndicator} for the mount gate and animation hooks.
+ */
+const RadioCompound: TRadioCompound = Object.assign(RadioRoot, {
+  Root: RadioRoot,
+  Indicator: RadioIndicator,
+});
+
+/** @internal */
+RadioCompound.displayName = "Radio";
+
+export { RadioCompound as Radio };

package/src/Radio/RadioContext.ts

@@ -0,0 +1,10 @@
+import { createStrictContext } from "../utils/index.ts";
+
+export type RadioContextValue = {
+  checked: boolean;
+};
+
+export const [RadioContext, useRadioContext] =
+  createStrictContext<RadioContextValue>(
+    "Radio sub-components must be rendered inside a <Radio.Root>.",
+  );

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

@@ -0,0 +1,63 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio asChild composition", () => {
+  it("Root asChild delegates to the child element while keeping ARIA and select wiring", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root asChild onCheckedChange={onCheckedChange} aria-label="Compact">
+        <li>Compact</li>
+      </Radio.Root>,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert element is the consumer's <li>
+    expect(radio.tagName).toBe("LI");
+    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+
+    // Act
+    await user.click(radio);
+
+    // Assert select still fires through composed onClick
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+    expect(radio).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("Root asChild lets the consumer override the role for menu-item contexts", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root asChild aria-label="Compact">
+        <li role="menuitemradio">Compact</li>
+      </Radio.Root>,
+    );
+
+    // Assert
+    const item = screen.getByRole("menuitemradio", { name: "Compact" });
+    expect(item).toHaveAttribute("aria-checked", "false");
+    expect(item).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("Indicator asChild delegates rendering to the consumer's element", () => {
+    // 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>,
+    );
+
+    // Assert
+    const dot = screen.getByTestId("dot");
+    expect(dot.tagName.toLowerCase()).toBe("svg");
+    expect(dot).toHaveAttribute("aria-hidden", "true");
+    expect(dot).toHaveAttribute("data-state", "checked");
+  });
+});

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

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+describe("Radio basic rendering", () => {
+  it('renders a <button> with role="radio"', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio.tagName).toBe("BUTTON");
+  });
+
+  it('defaults aria-checked to "false"', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "false");
+  });
+
+  it('defaults type="button" so the radio never submits an enclosing form', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("type", "button");
+  });
+
+  it('sets data-state="unchecked" on the root when unchecked', () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+  });
+});

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

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+/**
+ * Auto-verification of the Radio styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/radio/contract.json` is *derived from
+ * and asserted against the rendered headless component* so it can never drift
+ * from what the component actually emits. Radio is binary: its surface is
+ * `data-state="checked" | "unchecked"` (always present) plus `data-disabled=""`
+ * when disabled. The authored half (root class, parts, custom properties) is a
+ * styling convention the headless layer does not emit and is checked by the
+ * generator drift-guards instead.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/radio/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("Radio 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 Radio has no authored data-* surface; the whole contract is derived.
+    expect(autoAttributes).toHaveLength(contract.dataAttributes.length);
+  });
+
+  it("emits exactly the contracted data-* attribute names across its states", () => {
+    const emitted = new Set<string>();
+    for (const ui of [
+      <Radio.Root key="checked" checked onCheckedChange={() => {}} aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+      <Radio.Root key="unchecked" checked={false} onCheckedChange={() => {}} aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+      <Radio.Root key="disabled" disabled aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    ]) {
+      const { unmount } = render(ui);
+      for (const name of dataAttributeNames(screen.getByRole("radio"))) {
+        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 { unmount } = render(
+        <Radio.Root
+          checked={entry.value === "checked"}
+          onCheckedChange={() => {}}
+          aria-label="x"
+        >
+          <Radio.Indicator />
+        </Radio.Root>,
+      );
+      expect(screen.getByRole("radio")).toHaveAttribute("data-state", entry.value);
+      unmount();
+    }
+  });
+
+  it("emits data-disabled exactly as the contract documents it", () => {
+    const entry = autoAttributes.find(
+      (attribute: { name: string }) => attribute.name === "data-disabled",
+    );
+
+    render(
+      <Radio.Root disabled aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    );
+    expect(screen.getByRole("radio")).toHaveAttribute(entry.name, entry.value);
+  });
+
+  it("omits data-disabled when the documented condition does not hold", () => {
+    render(
+      <Radio.Root aria-label="x">
+        <Radio.Indicator />
+      </Radio.Root>,
+    );
+
+    expect(screen.getByRole("radio")).not.toHaveAttribute("data-disabled");
+  });
+});

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

@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { Radio } from "../Radio";
+
+describe("Radio controlled state", () => {
+  it("reflects the controlled `checked` prop", () => {
+    // Arrange & Act
+    const { rerender } = render(
+      <Radio.Root checked={false} onCheckedChange={() => {}} aria-label="Compact" />,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+    expect(radio).toHaveAttribute("aria-checked", "false");
+
+    rerender(
+      <Radio.Root checked onCheckedChange={() => {}} aria-label="Compact" />,
+    );
+
+    // Assert
+    expect(radio).toHaveAttribute("aria-checked", "true");
+    expect(radio).toHaveAttribute("data-state", "checked");
+  });
+
+  it("does not update its rendered state when the parent refuses to update `checked`", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Radio.Root
+        checked={false}
+        onCheckedChange={onCheckedChange}
+        aria-label="Compact"
+      />,
+    );
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Act
+    await user.click(radio);
+
+    // Assert: callback fired but the rendered state stays false because the
+    // parent did not flip the controlled prop.
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+    expect(radio).toHaveAttribute("aria-checked", "false");
+    expect(radio).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("lets a parent drive the value end to end", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    function Harness() {
+      const [checked, setChecked] = useState(false);
+      return (
+        <Radio.Root
+          checked={checked}
+          onCheckedChange={setChecked}
+          aria-label="Compact"
+        />
+      );
+    }
+    render(<Harness />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+    expect(radio).toHaveAttribute("aria-checked", "false");
+
+    // Act & Assert: the click is deferred to the parent, which selects it.
+    await user.click(radio);
+    expect(radio).toHaveAttribute("aria-checked", "true");
+  });
+});

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

@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+
+import { Radio } from "../Radio";
+
+describe("Radio disabled state", () => {
+  it('sets data-disabled="" on the root so CSS can target the disabled state', () => {
+    // Arrange & Act
+    render(<Radio.Root disabled aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).toHaveAttribute("data-disabled", "");
+  });
+
+  it("omits data-disabled when not disabled", () => {
+    // Arrange & Act
+    render(<Radio.Root aria-label="Compact" />);
+    const radio = screen.getByRole("radio", { name: "Compact" });
+
+    // Assert
+    expect(radio).not.toHaveAttribute("data-disabled");
+  });
+});

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

@@ -0,0 +1,103 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Radio } from "../Radio";
+
+describe("Radio.Indicator", () => {
+  it("does not render its children when the radio is unchecked", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.queryByText("dot")).not.toBeInTheDocument();
+  });
+
+  it("renders its children when the radio is checked", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("dot")).toBeInTheDocument();
+  });
+
+  it("mounts in response to selecting", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator>dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+    expect(screen.queryByText("dot")).not.toBeInTheDocument();
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+
+    // Assert
+    expect(screen.getByText("dot")).toBeInTheDocument();
+  });
+
+  it('carries aria-hidden="true" since it is decorative', () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator data-testid="indicator">dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it("mirrors the radio's data-state on the indicator", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root defaultChecked aria-label="Compact">
+        <Radio.Indicator data-testid="indicator">dot</Radio.Indicator>
+      </Radio.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
+  });
+
+  it("stays in the DOM while unchecked when forceMount is set", () => {
+    // Arrange & Act
+    render(
+      <Radio.Root aria-label="Compact">
+        <Radio.Indicator forceMount data-testid="indicator">
+          dot
+        </Radio.Indicator>
+      </Radio.Root>,
+    );
+    const indicator = screen.getByTestId("indicator");
+
+    // Assert
+    expect(indicator).toBeInTheDocument();
+    expect(indicator).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("throws when rendered outside Radio.Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() => render(<Radio.Indicator>dot</Radio.Indicator>)).toThrow();
+
+    error.mockRestore();
+  });
+});