@primitiv-ui/react 0.1.0

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

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

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

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Checkbox } from "../Checkbox";
+
+describe("Checkbox uncontrolled state", () => {
+  it("starts checked when defaultChecked is true", () => {
+    // Arrange & Act
+    render(<Checkbox.Root defaultChecked aria-label="Accept terms" />);
+    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+
+    // Assert
+    expect(checkbox).toHaveAttribute("aria-checked", "true");
+    expect(checkbox).toHaveAttribute("data-state", "checked");
+  });
+
+  it("toggles on click from unchecked to checked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(<Checkbox.Root aria-label="Accept terms" />);
+    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+
+    // Act
+    await user.click(checkbox);
+
+    // Assert
+    expect(checkbox).toHaveAttribute("aria-checked", "true");
+    expect(checkbox).toHaveAttribute("data-state", "checked");
+  });
+
+  it("toggles on click from checked to unchecked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(<Checkbox.Root defaultChecked aria-label="Accept terms" />);
+    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+    // Precondition: defaultChecked really did initialise as checked.
+    expect(checkbox).toHaveAttribute("aria-checked", "true");
+
+    // Act
+    await user.click(checkbox);
+
+    // Assert
+    expect(checkbox).toHaveAttribute("aria-checked", "false");
+    expect(checkbox).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("calls onCheckedChange with the new boolean value", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(
+      <Checkbox.Root
+        onCheckedChange={onCheckedChange}
+        aria-label="Accept terms"
+      />,
+    );
+    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+
+    // Act
+    await user.click(checkbox);
+    await user.click(checkbox);
+
+    // Assert
+    expect(onCheckedChange).toHaveBeenNthCalledWith(1, true);
+    expect(onCheckedChange).toHaveBeenNthCalledWith(2, false);
+  });
+
+  it("composes the consumer's onClick with the internal toggle (consumer runs first)", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const order: string[] = [];
+    const onClick = vi.fn(() => order.push("consumer"));
+    const onCheckedChange = vi.fn(() => order.push("internal"));
+    render(
+      <Checkbox.Root
+        onClick={onClick}
+        onCheckedChange={onCheckedChange}
+        aria-label="Accept terms"
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByRole("checkbox", { name: "Accept terms" }));
+
+    // Assert
+    expect(order).toEqual(["consumer", "internal"]);
+  });
+
+});

package/src/Checkbox/hooks/index.ts

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

package/src/Checkbox/hooks/useCheckboxContext.ts

@@ -0,0 +1 @@
+export { useCheckboxContext } from "../CheckboxContext";

package/src/Checkbox/hooks/useCheckboxRoot.ts

@@ -0,0 +1,32 @@
+import { useCallback } from "react";
+
+import { useControllableState } from "../../hooks";
+
+import { CheckedState } from "../types";
+
+type UseCheckboxRootArgs = {
+  defaultChecked?: CheckedState;
+  checked?: CheckedState;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+export function useCheckboxRoot({
+  defaultChecked,
+  checked: controlledChecked,
+  onCheckedChange,
+}: UseCheckboxRootArgs) {
+  const [checked, setChecked] = useControllableState<CheckedState>(
+    controlledChecked,
+    defaultChecked ?? false,
+  );
+
+  const toggle = useCallback(() => {
+    // Indeterminate resolves to checked per the WAI-ARIA tri-state
+    // convention; boolean flips.
+    const next = checked === "indeterminate" ? true : !checked;
+    setChecked(next);
+    onCheckedChange?.(next);
+  }, [checked, setChecked, onCheckedChange]);
+
+  return { checked, toggle };
+}

package/src/Checkbox/index.ts

@@ -0,0 +1 @@
+export * from "./Checkbox";

package/src/Checkbox/types.ts

@@ -0,0 +1,33 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+export type CheckedState = boolean | "indeterminate";
+
+export type CheckboxIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  forceMount?: boolean;
+  asChild?: boolean;
+};
+
+type CheckboxRootBaseProps = Omit<
+  ComponentProps<"button">,
+  "type" | "role" | "aria-checked" | "defaultChecked"
+> & {
+  asChild?: boolean;
+  ref?: Ref<HTMLButtonElement>;
+};
+
+type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
+  defaultChecked?: CheckedState;
+  checked?: never;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+type CheckboxRootControlledProps = CheckboxRootBaseProps & {
+  defaultChecked?: never;
+  checked: CheckedState;
+  onCheckedChange: (checked: boolean) => void;
+};
+
+export type CheckboxRootProps =
+  | CheckboxRootUncontrolledProps
+  | CheckboxRootControlledProps;

package/src/CheckboxCard/CheckboxCard.tsx

@@ -0,0 +1,208 @@
+import { useMemo } from "react";
+
+import { Slot, composeEventHandlers } from "../Slot";
+
+import { CheckboxCardContext } from "./CheckboxCardContext";
+import { useCheckboxCardContext, useCheckboxCardRoot } from "./hooks";
+import {
+  CheckboxCardIndicatorProps,
+  CheckboxCardRootProps,
+  CheckedState,
+} from "./types";
+
+function dataStateOf(checked: CheckedState) {
+  if (checked === "indeterminate") return "indeterminate" as const;
+  return checked ? ("checked" as const) : ("unchecked" as const);
+}
+
+/**
+ * The root of a CheckboxCard — a native `<button role="checkbox">` whose
+ * entire card surface is the interactive area. Owns the tri-state checked
+ * value and provides {@link CheckboxCardContext | `CheckboxCardContext`} to
+ * descendant {@link CheckboxCardIndicator | `CheckboxCard.Indicator`}s.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link CheckboxCardRootProps.defaultChecked | `defaultChecked`} (or omit
+ *   for unchecked-on-mount). The component owns the value internally.
+ * - **Controlled** — pass
+ *   {@link CheckboxCardRootProps.checked | `checked`} *and*
+ *   {@link CheckboxCardRootProps.onCheckedChange | `onCheckedChange`}
+ *   together. The parent owns the value.
+ *
+ * Both `checked` and `defaultChecked` accept `boolean | "indeterminate"`.
+ * Clicking an indeterminate card 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.
+ *
+ * **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
+ * with the checkbox's ARIA attributes, data-state, composed onClick, and ref
+ * merged in.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <CheckboxCard.Root defaultChecked aria-label="Enable feature">
+ *   <CheckboxCard.Indicator>
+ *     <CheckIcon />
+ *   </CheckboxCard.Indicator>
+ *   <h3>Feature name</h3>
+ *   <p>Feature description</p>
+ * </CheckboxCard.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [enabled, setEnabled] = useState<CheckedState>(false);
+ *
+ * <CheckboxCard.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+ *   <CheckboxCard.Indicator />
+ *   Feature name
+ * </CheckboxCard.Root>
+ * ```
+ */
+function CheckboxCardRoot(props: CheckboxCardRootProps) {
+  const {
+    defaultChecked,
+    checked,
+    onCheckedChange,
+    onClick,
+    disabled,
+    asChild = false,
+    children,
+    ...rest
+  } = props;
+  const { checked: isChecked, toggle } = useCheckboxCardRoot({
+    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,
+    disabled,
+    onClick: composeEventHandlers(onClick, toggle),
+  };
+  return (
+    <CheckboxCardContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...rootProps}>
+          {children}
+        </button>
+      )}
+    </CheckboxCardContext.Provider>
+  );
+}
+
+CheckboxCardRoot.displayName = "CheckboxCardRoot";
+
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children only
+ * while the parent {@link CheckboxCardRoot | `CheckboxCard.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.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked" | "indeterminate"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` tick icon) as the indicator itself.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the indicator in the DOM
+ * while unchecked so a CSS exit animation can play against
+ * `data-state="unchecked"`.
+ *
+ * @example
+ * ```tsx
+ * <CheckboxCard.Indicator>
+ *   <CheckIcon />
+ * </CheckboxCard.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `CheckboxCard.Root`.
+ */
+function CheckboxCardIndicator({
+  children,
+  forceMount,
+  asChild = false,
+  ...rest
+}: CheckboxCardIndicatorProps) {
+  const { checked } = useCheckboxCardContext();
+  const isVisible = checked !== false;
+  if (!isVisible && !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>;
+}
+
+CheckboxCardIndicator.displayName = "CheckboxCardIndicator";
+
+type TCheckboxCardCompound = typeof CheckboxCardRoot & {
+  Root: typeof CheckboxCardRoot;
+  Indicator: typeof CheckboxCardIndicator;
+};
+
+/**
+ * Headless, accessible **CheckboxCard** — a card/tile-shaped checkbox
+ * implementing the
+ * [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+ * including the tri-state ("mixed") variant. The entire card surface is the
+ * interactive element. Zero styles ship.
+ *
+ * `CheckboxCard` is both callable (an alias of
+ * {@link CheckboxCardRoot | `CheckboxCard.Root`}) and carries its
+ * sub-components as static properties.
+ *
+ * - {@link CheckboxCardRoot | `CheckboxCard.Root`} — state owner, context
+ *   provider, toggle button.
+ * - {@link CheckboxCardIndicator | `CheckboxCard.Indicator`} — decorative
+ *   tick, conditional on checked state.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { CheckboxCard } from "@primitiv-ui/react";
+ *
+ * <CheckboxCard.Root aria-label="Enable feature">
+ *   <CheckboxCard.Indicator>
+ *     <CheckIcon />
+ *   </CheckboxCard.Indicator>
+ *   <h3>Feature name</h3>
+ *   <p>Enable this to unlock advanced capabilities.</p>
+ * </CheckboxCard.Root>
+ * ```
+ *
+ * @see {@link CheckboxCardRoot} for state modes and tri-state semantics.
+ * @see {@link CheckboxCardIndicator} for the mount gate and animation hooks.
+ */
+const CheckboxCardCompound: TCheckboxCardCompound = Object.assign(
+  CheckboxCardRoot,
+  {
+    Root: CheckboxCardRoot,
+    Indicator: CheckboxCardIndicator,
+  },
+);
+
+CheckboxCardCompound.displayName = "CheckboxCard";
+
+export { CheckboxCardCompound as CheckboxCard };

package/src/CheckboxCard/CheckboxCardContext.ts

@@ -0,0 +1,12 @@
+import { createStrictContext } from "../utils";
+
+import { CheckedState } from "./types";
+
+export type CheckboxCardContextValue = {
+  checked: CheckedState;
+};
+
+export const [CheckboxCardContext, useCheckboxCardContext] =
+  createStrictContext<CheckboxCardContextValue>(
+    "CheckboxCard sub-components must be rendered inside a <CheckboxCard.Root>.",
+  );

package/src/CheckboxCard/README.md

@@ -0,0 +1,114 @@
+# CheckboxCard
+
+Headless, accessible **CheckboxCard** — a card/tile-shaped checkbox implementing
+the
+[WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+including the tri-state ("mixed") variant. The entire card surface is the
+interactive element. Zero styles ship.
+
+```tsx
+import { CheckboxCard } from "@primitiv-ui/react";
+
+<CheckboxCard.Root aria-label="Enable dark mode">
+  <CheckboxCard.Indicator>
+    <CheckIcon />
+  </CheckboxCard.Indicator>
+  <h3>Dark mode</h3>
+  <p>Switch the interface to a dark colour scheme.</p>
+</CheckboxCard.Root>
+```
+
+## Sub-components
+
+| Export | Element | ARIA / data hooks | `asChild` |
+|--------|---------|------------------|-----------|
+| `CheckboxCard.Root` | `<button>` | `role="checkbox"`, `aria-checked`, `data-state`, `data-disabled` | yes |
+| `CheckboxCard.Indicator` | `<span>` | `aria-hidden="true"`, `data-state` | yes |
+
+## State modes
+
+### Uncontrolled
+
+Pass `defaultChecked` (or omit for unchecked on mount). The component owns
+the value internally.
+
+```tsx
+<CheckboxCard.Root defaultChecked aria-label="Enable dark mode">
+  <CheckboxCard.Indicator />
+  Dark mode
+</CheckboxCard.Root>
+```
+
+### Controlled
+
+Pass `checked` and `onCheckedChange` together. The parent owns the value.
+
+```tsx
+const [enabled, setEnabled] = useState<CheckedState>(false);
+
+<CheckboxCard.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+  <CheckboxCard.Indicator />
+  Dark mode
+</CheckboxCard.Root>
+```
+
+## Tri-state (indeterminate)
+
+Both `checked` and `defaultChecked` accept `boolean | "indeterminate"`.
+`aria-checked="mixed"` and `data-state="indeterminate"` are set automatically.
+Clicking an indeterminate card resolves it to `true` per the WAI-ARIA tri-state
+convention, then flips boolean on subsequent clicks.
+
+```tsx
+<CheckboxCard.Root defaultChecked="indeterminate" aria-label="Select all">
+  <CheckboxCard.Indicator />
+  Select all items
+</CheckboxCard.Root>
+```
+
+## Keyboard interaction
+
+Clicking or pressing `Space` / `Enter` on the focused card toggles its state
+(native `<button>` behaviour).
+
+## Disabled
+
+Pass `disabled` on the Root. The native attribute suppresses clicks, removes
+the card from the focus ring, and `data-disabled=""` is set for CSS targeting.
+
+```tsx
+<CheckboxCard.Root aria-label="Premium feature" disabled>
+  <CheckboxCard.Indicator />
+  Premium feature
+</CheckboxCard.Root>
+```
+
+## `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.
+
+```tsx
+<CheckboxCard.Root asChild aria-label="Enable feature">
+  <li>Feature name</li>
+</CheckboxCard.Root>
+```
+
+## Indicator animation hooks
+
+`CheckboxCard.Indicator` mounts only while the card is checked or indeterminate.
+Pass `forceMount` to keep it in the DOM — `data-state="unchecked"` lets a CSS
+exit animation play.
+
+```tsx
+<CheckboxCard.Indicator forceMount>
+  <CheckIcon />
+</CheckboxCard.Indicator>
+```
+
+## Styling hooks
+
+| Attribute | Values | Set on |
+|-----------|--------|--------|
+| `data-state` | `"checked"` \| `"unchecked"` \| `"indeterminate"` | `CheckboxCard.Root`, `CheckboxCard.Indicator` |
+| `data-disabled` | `""` (present when disabled) | `CheckboxCard.Root` |

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

@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { CheckboxCard } from "../CheckboxCard";
+
+describe("CheckboxCard asChild", () => {
+  it("renders the Root as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <CheckboxCard.Root asChild aria-label="Enable feature">
+        <div>Feature card</div>
+      </CheckboxCard.Root>,
+    );
+
+    // Assert — div rendered, not button; role and aria-checked merged
+    const card = screen.getByRole("checkbox", { name: "Enable feature" });
+    expect(card.tagName).toBe("DIV");
+    expect(card).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("merges onClick onto the asChild Root element", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <CheckboxCard.Root asChild aria-label="Enable feature" onClick={onClick}>
+        <div>Feature card</div>
+      </CheckboxCard.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("checkbox", { name: "Enable feature" }));
+
+    // Assert
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it("renders the Indicator as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <CheckboxCard.Root aria-label="Enable feature" defaultChecked>
+        <CheckboxCard.Indicator asChild>
+          <svg data-testid="icon" viewBox="0 0 10 10" />
+        </CheckboxCard.Indicator>
+      </CheckboxCard.Root>,
+    );
+
+    // Assert — svg rendered, not span; aria-hidden and data-state merged
+    const icon = screen.getByTestId("icon");
+    expect(icon.tagName).toBe("svg");
+    expect(icon).toHaveAttribute("aria-hidden", "true");
+    expect(icon).toHaveAttribute("data-state", "checked");
+  });
+});