@primitiv-ui/react 0.1.0

package/src/RadioCard/README.md

@@ -0,0 +1,133 @@
+# RadioCard
+
+Headless, accessible **RadioCard** — a card/tile-shaped radio group variant
+implementing the
+[WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+The entire card surface is the interactive element. Zero styles ship.
+
+```tsx
+import { RadioCard } from "@primitiv-ui/react";
+
+<RadioCard.Root defaultValue="pro" aria-label="Plan">
+  <RadioCard.Item value="starter">
+    <RadioCard.Indicator />
+    <h3>Starter</h3>
+    <p>Free forever</p>
+  </RadioCard.Item>
+  <RadioCard.Item value="pro">
+    <RadioCard.Indicator />
+    <h3>Pro</h3>
+    <p>$9/month</p>
+  </RadioCard.Item>
+</RadioCard.Root>
+```
+
+## Sub-components
+
+| Export | Element | ARIA / data hooks | `asChild` |
+|--------|---------|------------------|-----------|
+| `RadioCard.Root` | `<div>` | `role="radiogroup"` | yes |
+| `RadioCard.Item` | `<button>` | `role="radio"`, `aria-checked`, `data-state`, `tabIndex` | yes |
+| `RadioCard.Indicator` | `<span>` | `aria-hidden="true"`, `data-state` | yes |
+
+## State modes
+
+### Uncontrolled
+
+Pass `defaultValue` (or omit for nothing selected on mount). The component owns
+the value internally.
+
+```tsx
+<RadioCard.Root defaultValue="pro" aria-label="Plan">
+  <RadioCard.Item value="starter">Starter</RadioCard.Item>
+  <RadioCard.Item value="pro">Pro</RadioCard.Item>
+</RadioCard.Root>
+```
+
+### Controlled
+
+Pass `value` and `onValueChange` together. The parent owns the value.
+
+```tsx
+const [plan, setPlan] = useState("pro");
+
+<RadioCard.Root value={plan} onValueChange={setPlan} aria-label="Plan">
+  <RadioCard.Item value="starter">Starter</RadioCard.Item>
+  <RadioCard.Item value="pro">Pro</RadioCard.Item>
+</RadioCard.Root>
+```
+
+## Keyboard interaction
+
+| Key | Behaviour |
+|-----|-----------|
+| `ArrowDown` / `ArrowRight` | Select and focus the next enabled Item, wrapping at the end |
+| `ArrowUp` / `ArrowLeft` | Select and focus the previous enabled Item, wrapping at the start |
+| `Space` / `Enter` | Select the focused Item (native `<button>` behaviour) |
+| `Tab` | Move focus out of the group (only one Item is in the tab sequence at a time) |
+
+## Orientation
+
+By default (`orientation="both"`) all four arrow keys navigate the group.
+Pass `orientation` to restrict navigation to a single axis:
+
+- `orientation="horizontal"` — only `ArrowLeft` / `ArrowRight` navigate.
+- `orientation="vertical"` — only `ArrowUp` / `ArrowDown` navigate.
+
+A `horizontal` or `vertical` group also reflects the axis to assistive
+technology via `aria-orientation` on the `radiogroup` element.
+
+## Reading direction
+
+Pass `dir` (`"ltr"` / `"rtl"`) to swap the horizontal arrow pair, so
+`ArrowLeft` moves forward and `ArrowRight` moves backward in RTL. The
+vertical pair is never swapped. When `dir` is omitted, it is inherited
+from the nearest [`DirectionProvider`](../DirectionProvider/README.md),
+falling back to `"ltr"` when there is no provider. An explicit `dir` prop
+always wins over the inherited value.
+
+## Disabled items
+
+Pass `disabled` on any `RadioCard.Item`. The native attribute suppresses clicks,
+removes the item from the focus ring, and excludes it from arrow-key navigation
+and the roving-tabindex home base.
+
+```tsx
+<RadioCard.Root aria-label="Plan">
+  <RadioCard.Item value="starter" disabled>Starter</RadioCard.Item>
+  <RadioCard.Item value="pro">Pro</RadioCard.Item>
+</RadioCard.Root>
+```
+
+## `asChild` composition
+
+All three sub-components accept `asChild`. The library's ARIA attributes,
+`data-state`, event handlers, and ref are merged onto the consumer's element;
+the default element is dropped.
+
+```tsx
+<RadioCard.Root asChild aria-label="Plan">
+  <ul>
+    <RadioCard.Item value="pro" asChild>
+      <li>Pro</li>
+    </RadioCard.Item>
+  </ul>
+</RadioCard.Root>
+```
+
+## Indicator animation hooks
+
+`RadioCard.Indicator` mounts only while its Item is selected. Pass `forceMount`
+to keep it in the DOM — `data-state="unchecked"` lets a CSS exit animation play.
+
+```tsx
+<RadioCard.Indicator forceMount>
+  <svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="3" /></svg>
+</RadioCard.Indicator>
+```
+
+## Styling hooks
+
+| Attribute | Values | Set on |
+|-----------|--------|--------|
+| `data-state` | `"checked"` \| `"unchecked"` | `RadioCard.Item`, `RadioCard.Indicator` |

package/src/RadioCard/RadioCard.tsx

@@ -0,0 +1,334 @@
+import { useEffect, useMemo, useRef } from "react";
+
+import { useDirection } from "../DirectionProvider";
+import { useRovingTabindex } from "../hooks";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot";
+
+import { RadioCardContext } from "./RadioCardContext";
+import { RadioCardItemContext } from "./RadioCardItemContext";
+import {
+  useRadioCardContext,
+  useRadioCardItemContext,
+  useRadioCardRoot,
+} from "./hooks";
+import {
+  RadioCardIndicatorProps,
+  RadioCardItemProps,
+  RadioCardRootProps,
+} from "./types";
+
+/**
+ * The root of a RadioCard group — a `<div role="radiogroup">` that owns the
+ * selected value and provides {@link RadioCardContext} to descendant
+ * {@link RadioCardItem | `RadioCard.Item`}s.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link RadioCardRootProps.defaultValue | `defaultValue`} (or omit
+ *   for nothing selected on mount). The component owns the value.
+ * - **Controlled** — pass
+ *   {@link RadioCardRootProps.value | `value`} *and*
+ *   {@link RadioCardRootProps.onValueChange | `onValueChange`}
+ *   together. The parent owns the value; the component defers every
+ *   change back through the callback.
+ *
+ * **ARIA.** `role="radiogroup"` is set automatically. Provide an
+ * accessible name via `aria-label` or `aria-labelledby`.
+ *
+ * **Orientation.** By default (`orientation="both"`) all four arrow keys
+ * navigate. Pass `orientation="horizontal"` or `"vertical"` to restrict
+ * navigation to a single axis.
+ *
+ * **Reading direction.** `dir` (`"ltr"` / `"rtl"`) swaps the horizontal
+ * arrow pair so Arrow Left moves forward in RTL. When omitted, it is
+ * inherited from the nearest {@link DirectionProvider}, falling back to
+ * `"ltr"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element with the RadioCard's props merged in. The native `<div>` is dropped.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <RadioCard.Root defaultValue="pro" aria-label="Plan">
+ *   <RadioCard.Item value="starter">
+ *     <h3>Starter</h3>
+ *     <RadioCard.Indicator />
+ *   </RadioCard.Item>
+ *   <RadioCard.Item value="pro">
+ *     <h3>Pro</h3>
+ *     <RadioCard.Indicator />
+ *   </RadioCard.Item>
+ * </RadioCard.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [plan, setPlan] = useState("pro");
+ *
+ * <RadioCard.Root value={plan} onValueChange={setPlan} aria-label="Plan">
+ *   <RadioCard.Item value="starter">Starter</RadioCard.Item>
+ *   <RadioCard.Item value="pro">Pro</RadioCard.Item>
+ * </RadioCard.Root>
+ * ```
+ */
+function RadioCardRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  orientation = "both",
+  dir,
+  asChild = false,
+  children,
+  ...rest
+}: RadioCardRootProps) {
+  const resolvedDir = dir ?? useDirection();
+  const { value, select, registerItem, itemValues, disabledValues, focusItem } =
+    useRadioCardRoot({
+      defaultValue,
+      value: controlledValue,
+      onValueChange,
+    });
+  const contextValue = useMemo(
+    () => ({
+      value,
+      select,
+      registerItem,
+      itemValues,
+      disabledValues,
+      focusItem,
+      orientation,
+      dir: resolvedDir,
+    }),
+    [
+      value,
+      select,
+      registerItem,
+      itemValues,
+      disabledValues,
+      focusItem,
+      orientation,
+      resolvedDir,
+    ],
+  );
+  const rootProps = {
+    role: "radiogroup" as const,
+    "aria-orientation": orientation === "both" ? undefined : orientation,
+    dir: resolvedDir,
+    ...rest,
+  };
+  return (
+    <RadioCardContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </RadioCardContext.Provider>
+  );
+}
+
+RadioCardRoot.displayName = "RadioCardRoot";
+
+/**
+ * An individual card option inside a RadioCard group — a native
+ * `<button role="radio">` whose entire surface is the interactive area.
+ * Participates in the roving tabindex and handles arrow-key navigation.
+ *
+ * **Selection.** Clicking an Item (or pressing Space / Enter via native
+ * `<button>` behaviour) selects it. The arrow keys enabled by the group's
+ * `orientation` move focus and selection to the next or previous
+ * non-disabled Item, wrapping at the ends.
+ *
+ * **Roving tabindex.** Only one Item per group is in the document tab
+ * sequence at a time: the selected one if any, otherwise the first
+ * non-disabled Item.
+ *
+ * **Disabled.** Passing `disabled` forwards the native attribute and
+ * excludes the Item from arrow-key navigation and the roving-tabindex
+ * home base.
+ *
+ * **Styling hook.** `data-state="checked" | "unchecked"` mirrors the
+ * selection state for CSS targeting.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer element with
+ * the Item's ARIA, data-state, tabIndex, onClick, onKeyDown, disabled, and
+ * ref merged onto it.
+ *
+ * @throws if rendered outside a `RadioCard.Root`.
+ */
+function RadioCardItem({
+  value,
+  children,
+  onClick,
+  onKeyDown,
+  disabled,
+  asChild = false,
+  ref,
+  ...rest
+}: RadioCardItemProps) {
+  const {
+    value: selectedValue,
+    select,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+    orientation,
+    dir,
+  } = useRadioCardContext();
+  const isChecked = selectedValue === value;
+  const enabledValues = useMemo(
+    () => itemValues.filter((v) => !disabledValues.has(v)),
+    [itemValues, disabledValues],
+  );
+  const isTabStop =
+    selectedValue !== undefined ? isChecked : enabledValues[0] === value;
+
+  const localRef = useRef<HTMLButtonElement | null>(null);
+  const setRef = useMemo(() => composeRefs(localRef, ref), [ref]);
+
+  useEffect(() => {
+    registerItem(value, localRef.current, disabled);
+    return () => registerItem(value, null);
+  }, [value, disabled, registerItem]);
+
+  const { handleKeyDown } = useRovingTabindex<string>({
+    orientation,
+    dir,
+    navigable: enabledValues,
+    currentKey: value,
+    onNavigate: (target) => {
+      select(target);
+      focusItem(target);
+    },
+  });
+
+  const itemContextValue = useMemo(() => ({ checked: isChecked }), [isChecked]);
+
+  const itemProps = {
+    ...rest,
+    ref: setRef,
+    role: "radio" as const,
+    "aria-checked": isChecked,
+    "data-state": isChecked ? ("checked" as const) : ("unchecked" as const),
+    tabIndex: isTabStop ? 0 : -1,
+    disabled,
+    onClick: composeEventHandlers(onClick, () => select(value)),
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+  };
+
+  return (
+    <RadioCardItemContext.Provider value={itemContextValue}>
+      {asChild ? (
+        <Slot {...itemProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...itemProps}>
+          {children}
+        </button>
+      )}
+    </RadioCardItemContext.Provider>
+  );
+}
+
+RadioCardItem.displayName = "RadioCardItem";
+
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children
+ * only while the enclosing {@link RadioCardItem | `RadioCard.Item`}
+ * is the selected one. Purely visual — accessible state is conveyed by
+ * `aria-checked` on the Item.
+ *
+ * **Styling hook.** Mirrors the parent Item's
+ * `data-state="checked" | "unchecked"` so the same CSS rule can target both.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * as the indicator itself, with `aria-hidden` and `data-state` merged in.
+ *
+ * **`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
+ * <RadioCard.Item value="pro">
+ *   <RadioCard.Indicator />
+ *   Pro
+ * </RadioCard.Item>
+ * ```
+ *
+ * @throws if rendered outside a `RadioCard.Item`.
+ */
+function RadioCardIndicator({
+  children,
+  forceMount,
+  asChild = false,
+  ...rest
+}: RadioCardIndicatorProps) {
+  const { checked } = useRadioCardItemContext();
+  if (!checked && !forceMount) return null;
+  const indicatorProps = {
+    ...rest,
+    "aria-hidden": "true" as const,
+    "data-state": checked ? ("checked" as const) : ("unchecked" as const),
+  };
+  if (asChild) {
+    return <Slot {...indicatorProps}>{children}</Slot>;
+  }
+  return <span {...indicatorProps}>{children}</span>;
+}
+
+RadioCardIndicator.displayName = "RadioCardIndicator";
+
+type TRadioCardCompound = typeof RadioCardRoot & {
+  Root: typeof RadioCardRoot;
+  Item: typeof RadioCardItem;
+  Indicator: typeof RadioCardIndicator;
+};
+
+/**
+ * Headless, accessible **RadioCard** — a card/tile-shaped radio group
+ * variant implementing the
+ * [WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+ * The entire card surface is the interactive element. Zero styles ship.
+ *
+ * `RadioCard` is both callable (an alias of
+ * {@link RadioCardRoot | `RadioCard.Root`}) and carries its sub-components
+ * as static properties.
+ *
+ * - {@link RadioCardRoot | `RadioCard.Root`} — state owner, context provider,
+ *   `<div role="radiogroup">` wrapper.
+ * - {@link RadioCardItem | `RadioCard.Item`} — a selectable card participating
+ *   in the roving tabindex.
+ * - {@link RadioCardIndicator | `RadioCard.Indicator`} — decorative indicator,
+ *   mounted only while the parent Item is selected.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { RadioCard } from "@primitiv-ui/react";
+ *
+ * <RadioCard.Root defaultValue="pro" aria-label="Plan">
+ *   <RadioCard.Item value="starter">
+ *     <RadioCard.Indicator />
+ *     Starter
+ *   </RadioCard.Item>
+ *   <RadioCard.Item value="pro">
+ *     <RadioCard.Indicator />
+ *     Pro
+ *   </RadioCard.Item>
+ * </RadioCard.Root>
+ * ```
+ *
+ * @see {@link RadioCardRoot} for state modes.
+ * @see {@link RadioCardItem} for selection, roving tabindex, and keyboard navigation.
+ * @see {@link RadioCardIndicator} for the mount gate and animation hooks.
+ */
+const RadioCardCompound: TRadioCardCompound = Object.assign(RadioCardRoot, {
+  Root: RadioCardRoot,
+  Item: RadioCardItem,
+  Indicator: RadioCardIndicator,
+});
+
+RadioCardCompound.displayName = "RadioCard";
+
+export { RadioCardCompound as RadioCard };

package/src/RadioCard/RadioCardContext.ts

@@ -0,0 +1,23 @@
+import { createStrictContext } from "../utils";
+
+import { RadioCardOrientation, RadioCardReadingDirection } from "./types";
+
+export type RadioCardContextValue = {
+  value: string | undefined;
+  select: (value: string) => void;
+  registerItem: (
+    value: string,
+    element: HTMLButtonElement | null,
+    disabled?: boolean,
+  ) => void;
+  itemValues: string[];
+  disabledValues: Set<string>;
+  focusItem: (value: string) => void;
+  orientation: RadioCardOrientation;
+  dir: RadioCardReadingDirection;
+};
+
+export const [RadioCardContext, useRadioCardContext] =
+  createStrictContext<RadioCardContextValue>(
+    "RadioCard sub-components must be rendered inside a <RadioCard.Root>.",
+  );

package/src/RadioCard/RadioCardItemContext.ts

@@ -0,0 +1,10 @@
+import { createStrictContext } from "../utils";
+
+export type RadioCardItemContextValue = {
+  checked: boolean;
+};
+
+export const [RadioCardItemContext, useRadioCardItemContext] =
+  createStrictContext<RadioCardItemContextValue>(
+    "RadioCard.Indicator must be rendered inside a <RadioCard.Item>.",
+  );

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

@@ -0,0 +1,76 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { RadioCard } from "../RadioCard";
+
+describe("RadioCard asChild", () => {
+  it("renders the Root as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root asChild aria-label="Plan">
+        <section>
+          <RadioCard.Item value="pro">Pro</RadioCard.Item>
+        </section>
+      </RadioCard.Root>,
+    );
+
+    // Assert — section rendered, not div; role still present via merged prop
+    const group = screen.getByRole("radiogroup", { name: "Plan" });
+    expect(group.tagName).toBe("SECTION");
+  });
+
+  it("renders the Item as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro" asChild>
+          <div>Pro card</div>
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert — div rendered, not button; role and aria-checked merged
+    const item = screen.getByRole("radio", { name: "Pro card" });
+    expect(item.tagName).toBe("DIV");
+    expect(item).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("merges onClick onto the asChild Item element", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro" asChild onClick={onClick}>
+          <div>Pro</div>
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Pro" }));
+
+    // Assert
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it("renders the Indicator as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan" defaultValue="pro">
+        <RadioCard.Item value="pro">
+          <RadioCard.Indicator asChild>
+            <svg data-testid="icon" viewBox="0 0 10 10" />
+          </RadioCard.Indicator>
+          Pro
+        </RadioCard.Item>
+      </RadioCard.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");
+  });
+});

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

@@ -0,0 +1,87 @@
+import { render, screen } from "@testing-library/react";
+
+import { RadioCard } from "../RadioCard";
+
+describe("RadioCard basic rendering", () => {
+  it('renders a container with role="radiogroup"', () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("radiogroup", { name: "Plan" }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders each item as a <button role="radio"> with aria-checked="false" by default', () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+    const starter = screen.getByRole("radio", { name: "Starter" });
+    const pro = screen.getByRole("radio", { name: "Pro" });
+
+    // Assert
+    expect(starter.tagName).toBe("BUTTON");
+    expect(starter).toHaveAttribute("aria-checked", "false");
+    expect(pro.tagName).toBe("BUTTON");
+    expect(pro).toHaveAttribute("aria-checked", "false");
+  });
+
+  it('defaults type="button" on items so they never submit an enclosing form', () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Starter" })).toHaveAttribute(
+      "type",
+      "button",
+    );
+  });
+
+  it('sets data-state="unchecked" on each item when nothing is selected', () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Starter" })).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+    expect(screen.getByRole("radio", { name: "Pro" })).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+  });
+
+  it("renders children inside the card item", () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro">
+          <span data-testid="icon">icon</span>
+          Pro plan
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+});