@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,108 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { RadioCard } from "../RadioCard";
+
+describe("RadioCard uncontrolled state", () => {
+  it("selects an item on mount when defaultValue is provided", () => {
+    // Arrange & Act
+    render(
+      <RadioCard.Root aria-label="Plan" defaultValue="pro">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Pro" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(screen.getByRole("radio", { name: "Starter" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("nothing is selected on mount when defaultValue is omitted", () => {
+    // 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(
+      "aria-checked",
+      "false",
+    );
+    expect(screen.getByRole("radio", { name: "Pro" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("selecting an item updates its aria-checked and data-state", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+    const pro = screen.getByRole("radio", { name: "Pro" });
+
+    // Act
+    await user.click(pro);
+
+    // Assert
+    expect(pro).toHaveAttribute("aria-checked", "true");
+    expect(pro).toHaveAttribute("data-state", "checked");
+    expect(screen.getByRole("radio", { name: "Starter" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("fires onValueChange with the selected value when an item is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioCard.Root aria-label="Plan" onValueChange={onValueChange}>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Pro" }));
+
+    // Assert
+    expect(onValueChange).toHaveBeenCalledOnce();
+    expect(onValueChange).toHaveBeenCalledWith("pro");
+  });
+
+  it("clicking the already-selected item does not fire onValueChange again", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioCard.Root
+        aria-label="Plan"
+        defaultValue="pro"
+        onValueChange={onValueChange}
+      >
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("radio", { name: "Pro" }));
+
+    // Assert
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+});

package/src/RadioCard/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useRadioCardContext } from "./useRadioCardContext";
+export { useRadioCardItemContext } from "./useRadioCardItemContext";
+export { useRadioCardRoot } from "./useRadioCardRoot";

package/src/RadioCard/hooks/useRadioCardContext.ts

@@ -0,0 +1 @@
+export { useRadioCardContext } from "../RadioCardContext";

package/src/RadioCard/hooks/useRadioCardItemContext.ts

@@ -0,0 +1 @@
+export { useRadioCardItemContext } from "../RadioCardItemContext";

package/src/RadioCard/hooks/useRadioCardRoot.ts

@@ -0,0 +1,77 @@
+import { useCallback, useMemo } from "react";
+
+import { useCollection, useControllableState } from "../../hooks";
+
+type UseRadioCardRootArgs = {
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+};
+
+type ItemMeta = {
+  element: HTMLButtonElement;
+  disabled: boolean;
+};
+
+export function useRadioCardRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+}: UseRadioCardRootArgs) {
+  const [value, setValue] = useControllableState<string>(
+    controlledValue,
+    defaultValue,
+    onValueChange,
+  );
+
+  const select = useCallback(
+    (next: string) => {
+      if (value === next) return;
+      setValue(next);
+    },
+    [value, setValue],
+  );
+
+  const {
+    register: registerItemBase,
+    itemsRef,
+    keys: itemValues,
+  } = useCollection<string, ItemMeta>();
+
+  const registerItem = useCallback(
+    (
+      itemValue: string,
+      element: HTMLButtonElement | null,
+      disabled = false,
+    ) => {
+      registerItemBase(itemValue, element ? { element, disabled } : null);
+    },
+    [registerItemBase],
+  );
+
+  const disabledValues = useMemo(
+    () =>
+      new Set(
+        Array.from(itemsRef.current.entries())
+          .filter(([, meta]) => meta.disabled)
+          .map(([v]) => v),
+      ),
+    [itemValues, itemsRef],
+  );
+
+  const focusItem = useCallback(
+    (itemValue: string) => {
+      itemsRef.current.get(itemValue)?.element.focus();
+    },
+    [itemsRef],
+  );
+
+  return {
+    value,
+    select,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+  };
+}

package/src/RadioCard/index.ts

@@ -0,0 +1,4 @@
+export * from "./RadioCard";
+export * from "./RadioCardContext";
+export * from "./RadioCardItemContext";
+export * from "./types";

package/src/RadioCard/types.ts

@@ -0,0 +1,51 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+/**
+ * Which arrow keys navigate the group. `"both"` (default) accepts all
+ * four; `"horizontal"` only Arrow Left/Right; `"vertical"` only Arrow
+ * Up/Down.
+ */
+export type RadioCardOrientation = "horizontal" | "vertical" | "both";
+
+/** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
+export type RadioCardReadingDirection = "ltr" | "rtl";
+
+type RadioCardRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+  asChild?: boolean;
+  orientation?: RadioCardOrientation;
+  dir?: RadioCardReadingDirection;
+};
+
+type RadioCardRootUncontrolledProps = RadioCardRootBaseProps & {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: (value: string) => void;
+};
+
+type RadioCardRootControlledProps = RadioCardRootBaseProps & {
+  defaultValue?: never;
+  value: string;
+  onValueChange: (value: string) => void;
+};
+
+export type RadioCardRootProps =
+  | RadioCardRootUncontrolledProps
+  | RadioCardRootControlledProps;
+
+export type RadioCardItemProps = Omit<
+  ComponentProps<"button">,
+  "type" | "role" | "aria-checked" | "value"
+> & {
+  value: string;
+  children?: ReactNode;
+  ref?: Ref<HTMLButtonElement>;
+  asChild?: boolean;
+};
+
+export type RadioCardIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  forceMount?: boolean;
+  asChild?: boolean;
+};

package/src/RadioGroup/README.md

@@ -0,0 +1,185 @@
+# RadioGroup
+
+A headless, accessible compound component implementing the
+[WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
+
+RadioGroup renders native `<button role="radio">` elements wrapped in a
+`<div role="radiogroup">` so it gets keyboard activation (`Space` /
+`Enter`), focus ring, and disabled semantics for free from the browser.
+The React layer adds single-selection state, roving tabindex, arrow-key
+navigation, an Indicator slot driven by the selected value, and the
+`asChild` composition every primitive in this package supports.
+
+```tsx
+import { RadioGroup } from "@primitiv-ui/react";
+
+<RadioGroup.Root defaultValue="comfortable" aria-label="Density">
+  <RadioGroup.Item value="compact">
+    <RadioGroup.Indicator />
+    Compact
+  </RadioGroup.Item>
+  <RadioGroup.Item value="comfortable">
+    <RadioGroup.Indicator />
+    Comfortable
+  </RadioGroup.Item>
+</RadioGroup.Root>;
+```
+
+## Sub-components
+
+| Export                 | Element    | Notes                                                                                         |
+| ---------------------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `RadioGroup.Root`      | `<div>`    | `role="radiogroup"`. State owner, context provider. `asChild`                                 |
+| `RadioGroup.Item`      | `<button>` | `role="radio"`, `aria-checked`, `data-state`, participates in roving tabindex. `asChild`      |
+| `RadioGroup.Indicator` | `<span>`   | `aria-hidden="true"`. Renders only while the parent Item is selected. `asChild`, `forceMount` |
+
+## State modes
+
+- **Uncontrolled** — pass `defaultValue` (or omit for no initial selection).
+- **Controlled** — pass `value` **and** `onValueChange` together.
+
+The two shapes are statically discriminated at the type level;
+TypeScript rejects mixing them.
+
+```tsx
+// Uncontrolled
+<RadioGroup.Root defaultValue="compact" aria-label="Density">
+  …
+</RadioGroup.Root>;
+
+// Controlled
+const [value, setValue] = useState("compact");
+<RadioGroup.Root value={value} onValueChange={setValue} aria-label="Density">
+  …
+</RadioGroup.Root>;
+```
+
+## Keyboard interaction
+
+| Key                        | Behaviour                                                                     |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `Tab`                      | Moves focus to the group's single tab stop (selected item, or first if none). |
+| `Space` / `Enter`          | Selects the focused item (native `<button>` activation).                      |
+| `ArrowDown` / `ArrowRight` | Moves focus **and** selection to the next non-disabled item, wrapping.        |
+| `ArrowUp` / `ArrowLeft`    | Moves focus **and** selection to the previous non-disabled item, wrapping.    |
+
+The group has exactly one tab stop — the selected item, or the first
+non-disabled item if nothing is selected. This is the standard WAI-ARIA
+Radio Group behaviour: `Tab` takes the user into and out of the group
+in one keystroke, and arrow keys navigate inside it.
+
+## 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
+
+Passing `disabled` to a `RadioGroup.Item` forwards the native
+`disabled` attribute (removing it from the focus ring and suppressing
+clicks) **and** excludes the Item from:
+
+- Arrow-key navigation — the group skips over it to the next enabled
+  Item.
+- The roving-tabindex home base — `Tab` never lands on a disabled Item
+  when nothing is selected.
+
+```tsx
+<RadioGroup.Root aria-label="Plan">
+  <RadioGroup.Item value="free">Free</RadioGroup.Item>
+  <RadioGroup.Item value="pro">Pro</RadioGroup.Item>
+  <RadioGroup.Item value="enterprise" disabled>
+    Enterprise (contact sales)
+  </RadioGroup.Item>
+</RadioGroup.Root>
+```
+
+## `asChild` composition
+
+`RadioGroup.Root`, `RadioGroup.Item`, and `RadioGroup.Indicator` each
+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-shaped radio group — same state machinery, different shell.
+<RadioGroup.Root asChild aria-label="Theme">
+  <menu role="menu">
+    <RadioGroup.Item value="light" asChild>
+      <li role="menuitemradio">Light</li>
+    </RadioGroup.Item>
+    <RadioGroup.Item value="dark" asChild>
+      <li role="menuitemradio">Dark</li>
+    </RadioGroup.Item>
+  </menu>
+</RadioGroup.Root>
+
+// Icon-only indicator — the svg itself becomes the dot.
+<RadioGroup.Indicator asChild>
+  <svg viewBox="0 0 10 10">
+    <circle cx="5" cy="5" r="3" />
+  </svg>
+</RadioGroup.Indicator>
+```
+
+`Root`'s and `Item`'s `asChild` are what let `Dropdown.RadioGroup` /
+`Dropdown.RadioItem` (in a later phase) wrap `<menu role="menu">` and
+`<li role="menuitemradio">` elements around the RadioGroup state
+machinery without re-implementing any of it.
+
+## Animation hooks
+
+`RadioGroup.Indicator` accepts a `forceMount` boolean. When set, the
+indicator stays in the DOM regardless of selection state so a CSS
+animation can play against `data-state="unchecked"`:
+
+```tsx
+<RadioGroup.Item value="blue">
+  <RadioGroup.Indicator forceMount />
+  Blue
+</RadioGroup.Item>
+```
+
+```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 `RadioGroup.Item`
+and `RadioGroup.Indicator`, letting any CSS system target the two
+phases from one rule:
+
+```css
+button[role="radio"][data-state="checked"] {
+  border-color: oklch(65% 0.18 250);
+}
+button[role="radio"]:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```