@primitiv-ui/react 0.1.0

package/src/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,353 @@
+import { useEffect, useMemo, useRef } from "react";
+
+import { useDirection } from "../DirectionProvider";
+import { useRovingTabindex } from "../hooks";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot";
+
+import { RadioGroupContext } from "./RadioGroupContext";
+import { RadioGroupItemContext } from "./RadioGroupItemContext";
+import {
+  useRadioGroupContext,
+  useRadioGroupItemContext,
+  useRadioGroupRoot,
+} from "./hooks";
+import {
+  RadioGroupIndicatorProps,
+  RadioGroupItemProps,
+  RadioGroupRootProps,
+} from "./types";
+
+/**
+ * The root of a RadioGroup — a `<div role="radiogroup">` that owns the
+ * selected value and provides {@link RadioGroupContext} to descendant
+ * {@link RadioGroupItem | `RadioGroup.Item`}s.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link RadioGroupRootProps.defaultValue | `defaultValue`} (or omit
+ *   for nothing selected on mount). The component owns the value.
+ * - **Controlled** — pass
+ *   {@link RadioGroupRootProps.value | `value`} *and*
+ *   {@link RadioGroupRootProps.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 (e.g. `<menu role="menu">` for dropdown composition) with
+ * the RadioGroup's props merged in. The native `<div>` is dropped.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <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>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [value, setValue] = useState("comfortable");
+ *
+ * <RadioGroup.Root value={value} onValueChange={setValue} aria-label="…">
+ *   <RadioGroup.Item value="compact">Compact</RadioGroup.Item>
+ *   <RadioGroup.Item value="comfortable">Comfortable</RadioGroup.Item>
+ * </RadioGroup.Root>
+ * ```
+ */
+function RadioGroupRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  orientation = "both",
+  dir,
+  asChild = false,
+  children,
+  ...rest
+}: RadioGroupRootProps) {
+  const resolvedDir = dir ?? useDirection();
+  const { value, select, registerItem, itemValues, disabledValues, focusItem } =
+    useRadioGroupRoot({
+      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 (
+    <RadioGroupContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </RadioGroupContext.Provider>
+  );
+}
+
+RadioGroupRoot.displayName = "RadioGroupRoot";
+
+/**
+ * An individual radio option inside a RadioGroup — a native
+ * `<button role="radio">` that reports its state, participates in the
+ * roving tabindex, and handles arrow-key navigation within the group.
+ *
+ * **Selection.** Clicking an Item (or pressing Space / Enter on the
+ * focused Item 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. All others have `tabIndex=-1` so `Tab` escapes
+ * the group in a single keystroke.
+ *
+ * **Disabled.** Passing `disabled` forwards the native attribute (the
+ * browser suppresses clicks and removes it from the focus ring) and
+ * excludes the Item from arrow-key navigation and the roving-tabindex
+ * home base. Styling via `:disabled` works natively.
+ *
+ * **Styling hook.** `data-state="checked" | "unchecked"` mirrors the
+ * selection state for CSS targeting.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer element
+ * (e.g. `<li role="menuitemradio">` for dropdown menu composition)
+ * with the Item's ARIA, data-state, tabIndex, onClick, onKeyDown,
+ * disabled, and ref merged onto it. The native `<button>` is dropped;
+ * consumers who render a non-focusable element are responsible for
+ * making it focusable.
+ *
+ * @throws if rendered outside a `RadioGroup.Root`.
+ */
+function RadioGroupItem({
+  value,
+  children,
+  onClick,
+  onKeyDown,
+  disabled,
+  asChild = false,
+  ref,
+  ...rest
+}: RadioGroupItemProps) {
+  const {
+    value: selectedValue,
+    select,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+    orientation,
+    dir,
+  } = useRadioGroupContext();
+  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 (
+    <RadioGroupItemContext.Provider value={itemContextValue}>
+      {asChild ? (
+        <Slot {...itemProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...itemProps}>
+          {children}
+        </button>
+      )}
+    </RadioGroupItemContext.Provider>
+  );
+}
+
+RadioGroupItem.displayName = "RadioGroupItem";
+
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children
+ * only while the enclosing {@link RadioGroupItem | `RadioGroup.Item`}
+ * is the selected one — typically the filled dot inside a radio
+ * control. The radio's accessible state is already conveyed by
+ * `aria-checked` on the Item, so the indicator is purely visual.
+ *
+ * **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 (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
+ * <RadioGroup.Item value="red">
+ *   <RadioGroup.Indicator />
+ *   Red
+ * </RadioGroup.Item>
+ * ```
+ *
+ * @example Icon as the indicator via `asChild`
+ * ```tsx
+ * <RadioGroup.Indicator asChild>
+ *   <svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="3" /></svg>
+ * </RadioGroup.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `RadioGroup.Item`.
+ */
+function RadioGroupIndicator({
+  children,
+  forceMount,
+  asChild = false,
+  ...rest
+}: RadioGroupIndicatorProps) {
+  const { checked } = useRadioGroupItemContext();
+  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>;
+}
+
+RadioGroupIndicator.displayName = "RadioGroupIndicator";
+
+type TRadioGroupCompound = typeof RadioGroupRoot & {
+  Root: typeof RadioGroupRoot;
+  Item: typeof RadioGroupItem;
+  Indicator: typeof RadioGroupIndicator;
+};
+
+/**
+ * Headless, accessible **RadioGroup** — a compound component
+ * implementing the
+ * [WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+ * built on native `<button role="radio">` elements. Zero styles ship.
+ *
+ * `RadioGroup` is both callable (an alias of
+ * {@link RadioGroupRoot | `RadioGroup.Root`}) and carries its
+ * sub-components as static properties. Prefer the namespaced form in
+ * application code for readability and grep-ability.
+ *
+ * - {@link RadioGroupRoot | `RadioGroup.Root`} — state owner, context
+ *   provider, `<div role="radiogroup">` wrapper.
+ * - {@link RadioGroupItem | `RadioGroup.Item`} — a selectable radio
+ *   button participating in the roving tabindex.
+ * - {@link RadioGroupIndicator | `RadioGroup.Indicator`} — decorative
+ *   dot, mounted only while the parent Item is selected.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { RadioGroup } from "@primitiv-ui/react";
+ *
+ * <RadioGroup.Root defaultValue="compact" aria-label="Density">
+ *   <RadioGroup.Item value="compact">
+ *     <RadioGroup.Indicator />
+ *     Compact
+ *   </RadioGroup.Item>
+ *   <RadioGroup.Item value="comfortable">
+ *     <RadioGroup.Indicator />
+ *     Comfortable
+ *   </RadioGroup.Item>
+ * </RadioGroup.Root>;
+ * ```
+ *
+ * @see {@link RadioGroupRoot} for state modes.
+ * @see {@link RadioGroupItem} for selection, roving tabindex, and keyboard navigation.
+ * @see {@link RadioGroupIndicator} for the mount gate and animation hooks.
+ */
+const RadioGroupCompound: TRadioGroupCompound = Object.assign(RadioGroupRoot, {
+  Root: RadioGroupRoot,
+  Item: RadioGroupItem,
+  Indicator: RadioGroupIndicator,
+});
+
+RadioGroupCompound.displayName = "RadioGroup";
+
+export { RadioGroupCompound as RadioGroup };

package/src/RadioGroup/RadioGroupContext.ts

@@ -0,0 +1,23 @@
+import { createStrictContext } from "../utils";
+
+import { RadioGroupOrientation, RadioGroupReadingDirection } from "./types";
+
+export type RadioGroupContextValue = {
+  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: RadioGroupOrientation;
+  dir: RadioGroupReadingDirection;
+};
+
+export const [RadioGroupContext, useRadioGroupContext] =
+  createStrictContext<RadioGroupContextValue>(
+    "RadioGroup sub-components must be rendered inside a <RadioGroup.Root>.",
+  );

package/src/RadioGroup/RadioGroupItemContext.ts

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

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

@@ -0,0 +1,105 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { RadioGroup } from "../RadioGroup";
+
+describe("RadioGroup asChild composition", () => {
+  it("Root asChild renders the consumer element with radiogroup role preserved", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root asChild aria-label="Colour">
+        <menu data-testid="menu">
+          <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        </menu>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    const root = screen.getByTestId("menu");
+    expect(root.tagName).toBe("MENU");
+    expect(root).toHaveAttribute("role", "radiogroup");
+    expect(root).toHaveAttribute("aria-label", "Colour");
+  });
+
+  it("Root asChild allows the consumer to override the role for menu contexts", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root asChild aria-label="Colour">
+        <menu role="menu" data-testid="menu">
+          <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        </menu>
+      </RadioGroup.Root>,
+    );
+
+    // Assert: the consumer's <menu> is the rendered root. Its own role
+    // wins (Slot's "child overrides" rule), and Slot must have merged
+    // the Root's aria-label onto it — without asChild the aria-label
+    // would sit on a wrapping <div> and not on the <menu>.
+    const menuEl = screen.getByTestId("menu");
+    expect(menuEl).toHaveAttribute("role", "menu");
+    expect(menuEl).toHaveAttribute("aria-label", "Colour");
+  });
+
+  it("Item asChild delegates to the child element while keeping ARIA + selection wiring", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup.Root aria-label="Colour" onValueChange={onValueChange}>
+        <RadioGroup.Item value="red" asChild>
+          <li>Red</li>
+        </RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    const item = screen.getByRole("radio", { name: "Red" });
+
+    // Assert element is the consumer's <li>
+    expect(item.tagName).toBe("LI");
+    expect(item).toHaveAttribute("aria-checked", "false");
+    expect(item).toHaveAttribute("data-state", "unchecked");
+
+    // Act
+    await user.click(item);
+
+    // Assert selection wiring still fires via composed onClick
+    expect(onValueChange).toHaveBeenCalledWith("red");
+    expect(item).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("Item asChild lets the consumer override the role for menu-item contexts", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red" asChild>
+          <li role="menuitemradio">Red</li>
+        </RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    const item = screen.getByRole("menuitemradio", { name: "Red" });
+    expect(item).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("Indicator asChild delegates rendering to the consumer's element", () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour" defaultValue="red">
+        <RadioGroup.Item value="red">
+          Red
+          <RadioGroup.Indicator asChild>
+            <svg data-testid="dot" viewBox="0 0 10 10">
+              <circle cx="5" cy="5" r="3" />
+            </svg>
+          </RadioGroup.Indicator>
+        </RadioGroup.Item>
+      </RadioGroup.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/RadioGroup/__tests__/RadioGroup.basic-rendering.test.tsx

@@ -0,0 +1,72 @@
+import { render, screen } from "@testing-library/react";
+
+import { RadioGroup } from "../RadioGroup";
+
+describe("RadioGroup basic rendering", () => {
+  it('renders a container with role="radiogroup"', () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("radiogroup", { name: "Colour" }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders each item as a <button role="radio"> with aria-checked="false" by default', () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    const red = screen.getByRole("radio", { name: "Red" });
+    const blue = screen.getByRole("radio", { name: "Blue" });
+
+    // Assert
+    expect(red.tagName).toBe("BUTTON");
+    expect(red).toHaveAttribute("aria-checked", "false");
+    expect(blue.tagName).toBe("BUTTON");
+    expect(blue).toHaveAttribute("aria-checked", "false");
+  });
+
+  it('defaults type="button" on items so they never submit an enclosing form', () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "type",
+      "button",
+    );
+  });
+
+  it('sets data-state="unchecked" on each item when nothing is selected', () => {
+    // Arrange & Act
+    render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+  });
+});

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

@@ -0,0 +1,109 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { RadioGroup } from "../RadioGroup";
+
+describe("RadioGroup controlled state", () => {
+  it("reflects the controlled `value` prop", () => {
+    // Arrange & Act
+    const { rerender } = render(
+      <RadioGroup.Root
+        aria-label="Colour"
+        value="red"
+        onValueChange={() => {}}
+      >
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+
+    rerender(
+      <RadioGroup.Root
+        aria-label="Colour"
+        value="blue"
+        onValueChange={() => {}}
+      >
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+
+  it("does not update rendered state when the parent refuses to update `value`", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup.Root
+        aria-label="Colour"
+        value="red"
+        onValueChange={onValueChange}
+      >
+        <RadioGroup.Item value="red">Red</RadioGroup.Item>
+        <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    const blue = screen.getByRole("radio", { name: "Blue" });
+
+    // Act
+    await user.click(blue);
+
+    // Assert: callback fires but the pinned `value` prop keeps the
+    // rendered state on "red".
+    expect(onValueChange).toHaveBeenCalledWith("blue");
+    expect(screen.getByRole("radio", { name: "Red" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(blue).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("lets a parent drive the value end to end", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    function Harness() {
+      // Start on "blue" so the pre-click state can only be correct if
+      // the controlled prop is honoured — a broken impl would fall back
+      // to defaultValue and render nothing selected.
+      const [value, setValue] = useState("blue");
+      return (
+        <RadioGroup.Root
+          aria-label="Colour"
+          value={value}
+          onValueChange={setValue}
+        >
+          <RadioGroup.Item value="red">Red</RadioGroup.Item>
+          <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+        </RadioGroup.Root>
+      );
+    }
+    render(<Harness />);
+    const red = screen.getByRole("radio", { name: "Red" });
+    const blue = screen.getByRole("radio", { name: "Blue" });
+    expect(blue).toHaveAttribute("aria-checked", "true");
+
+    // Act & Assert
+    await user.click(red);
+    expect(red).toHaveAttribute("aria-checked", "true");
+    expect(blue).toHaveAttribute("aria-checked", "false");
+
+    await user.click(blue);
+    expect(blue).toHaveAttribute("aria-checked", "true");
+    expect(red).toHaveAttribute("aria-checked", "false");
+  });
+});