@primitiv-ui/react 0.1.38 → 0.1.40

package/src/RadioCard/README.md

@@ -1,134 +0,0 @@
-# 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`, `data-disabled`, `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` |
-| `data-disabled` | `""` (present only while disabled) | `RadioCard.Item` |

package/src/RadioCard/RadioCard.tsx

@@ -1,354 +0,0 @@
-import { useEffect, useMemo, useRef } from "react";
-import type { ReactElement } from "react";
-
-import { useDirection } from "../DirectionProvider/index.ts";
-import { useRovingTabindex } from "../hooks/index.ts";
-import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.ts";
-
-import { RadioCardContext } from "./RadioCardContext";
-import { RadioCardItemContext } from "./RadioCardItemContext";
-import {
-  useRadioCardContext,
-  useRadioCardItemContext,
-  useRadioCardRoot,
-} from "./hooks/index.ts";
-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.
- *
- * @extends HTMLDivElement
- *
- * @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>
- * ```
- */
-export function RadioCardRoot({
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  orientation = "both",
-  dir,
-  asChild = false,
-  children,
-  ...rest
-}: RadioCardRootProps): ReactElement {
-  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>
-  );
-}
-
-/** @internal */
-// Runtime-dead: the compound alias below (same object via Object.assign)
-// overwrites this to "RadioCard" at load, so the value is never observable.
-// The assignment stays because it declares `displayName` on
-// `typeof RadioCardRoot`, which TRadioCardCompound extends.
-// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
-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 hooks.** `data-state="checked" | "unchecked"` mirrors the
- * selection state, and `data-disabled=""` is present while disabled — the
- * same pair `CheckboxCard.Root` publishes, so one stylesheet can dress
- * both.
- *
- * **`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.
- *
- * @extends HTMLButtonElement
- *
- * @throws if rendered outside a `RadioCard.Root`.
- */
-export function RadioCardItem({
-  value,
-  children,
-  onClick,
-  onKeyDown,
-  disabled,
-  asChild = false,
-  ref,
-  ...rest
-}: RadioCardItemProps): ReactElement {
-  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),
-    "data-disabled": disabled ? "" : undefined,
-    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>
-  );
-}
-
-/** @internal */
-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"`.
- *
- * @extends HTMLSpanElement
- *
- * @example
- * ```tsx
- * <RadioCard.Item value="pro">
- *   <RadioCard.Indicator />
- *   Pro
- * </RadioCard.Item>
- * ```
- *
- * @throws if rendered outside a `RadioCard.Item`.
- */
-export function RadioCardIndicator({
-  children,
-  forceMount,
-  asChild = false,
-  ...rest
-}: RadioCardIndicatorProps): ReactElement | null {
-  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>;
-}
-
-/** @internal */
-RadioCardIndicator.displayName = "RadioCardIndicator";
-
-/** Type of the {@link RadioCard} compound: the callable `RadioCard.Root`
- * component augmented with its sub-components as static properties. */
-export 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

@@ -1,35 +0,0 @@
-import type { Context } from "react";
-import { createStrictContext } from "../utils/index.ts";
-
-import { RadioCardOrientation, RadioCardReadingDirection } from "./types";
-
-/** The value shared by `RadioCard.Root` with its items through context: the
- * current selection and setter, the item registry used for roving focus and
- * keyboard navigation, and the resolved orientation/direction. */
-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;
-};
-
-const radioCardContextPair = createStrictContext<RadioCardContextValue>(
-  "RadioCard sub-components must be rendered inside a <RadioCard.Root>.",
-);
-
-/** Strict React context carrying the {@link RadioCardContextValue} from
- * `RadioCard.Root` to its items. `null` when read outside a `RadioCard.Root`. */
-export const RadioCardContext: Context<RadioCardContextValue | null> =
-  radioCardContextPair[0];
-/** Reads the {@link RadioCardContextValue}; throws when used outside a
- * `RadioCard.Root`. */
-export const useRadioCardContext: () => RadioCardContextValue =
-  radioCardContextPair[1];

package/src/RadioCard/RadioCardItemContext.ts

@@ -1,23 +0,0 @@
-import type { Context } from "react";
-import { createStrictContext } from "../utils/index.ts";
-
-/** The value shared by `RadioCard.Item` with its `RadioCard.Indicator`,
- * exposing whether the item is currently selected. */
-export type RadioCardItemContextValue = {
-  /** Whether the enclosing item is the selected card. */
-  checked: boolean;
-};
-
-const radioCardItemContextPair = createStrictContext<RadioCardItemContextValue>(
-  "RadioCard.Indicator must be rendered inside a <RadioCard.Item>.",
-);
-
-/** Strict React context carrying the {@link RadioCardItemContextValue} from
- * `RadioCard.Item` to its indicator. `null` when read outside a
- * `RadioCard.Item`. */
-export const RadioCardItemContext: Context<RadioCardItemContextValue | null> =
-  radioCardItemContextPair[0];
-/** Reads the {@link RadioCardItemContextValue}; throws when used outside a
- * `RadioCard.Item`. */
-export const useRadioCardItemContext: () => RadioCardItemContextValue =
-  radioCardItemContextPair[1];

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

@@ -1,76 +0,0 @@
-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");
-  });
-});