@primitiv-ui/react 0.1.27 → 0.1.29

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

@@ -14,4 +14,9 @@ describe("Portal basic rendering", () => {
     // Assert
     expect(screen.getByText("Portal content")).toBeInTheDocument();
   });
+
+  it('sets displayName to "Portal" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Portal.displayName).toBe("Portal");
+  });
 });

package/src/Portal/types.ts

@@ -5,6 +5,11 @@ import { ReactNode } from "react";
  * `container` to render into (defaults to `document.body`).
  */
 export type PortalProps = {
+  /** Content to render inside the portal. Appears directly inside `container`
+   * with no wrapping host element added by `Portal` itself. */
   children?: ReactNode;
+  /** DOM node to mount the portal children into. When omitted, children are
+   * mounted into `document.body`.
+   * @default document.body */
   container?: HTMLElement;
 };

package/src/Progress/Progress.tsx

@@ -33,6 +33,16 @@ function defaultGetValueLabel(value: number, max: number): string {
  * **Styling hooks.** `data-state="indeterminate" | "loading" | "complete"`,
  * plus `data-value` (determinate only) and `data-max` on the root.
  *
+ * **Validation.** `max` must be a positive, finite number and `value` (when
+ * not `null`) must be finite and within `0..max`; either violation throws a
+ * descriptive error during render so bad inputs surface early in development.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * element as the root instead of the native `<div>`, merging the ARIA and
+ * `data-*` hooks onto it via the {@link Slot} pattern.
+ *
+ * @extends HTMLDivElement
+ *
  * @example Determinate
  * ```tsx
  * <Progress.Root value={60} aria-label="Upload progress">
@@ -46,6 +56,18 @@ function defaultGetValueLabel(value: number, max: number): string {
  *   <Progress.Indicator />
  * </Progress.Root>
  * ```
+ *
+ * @example Custom value label
+ * ```tsx
+ * <Progress.Root
+ *   value={3}
+ *   max={5}
+ *   getValueLabel={(v, m) => `Step ${v} of ${m}`}
+ *   aria-label="Setup progress"
+ * >
+ *   <Progress.Indicator />
+ * </Progress.Root>
+ * ```
  */
 export function ProgressRoot({
   value,
@@ -93,7 +115,11 @@ export function ProgressRoot({
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Progress" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof ProgressRoot`,
+// which TProgressCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 ProgressRoot.displayName = "ProgressRoot";
 
 /**
@@ -109,6 +135,8 @@ ProgressRoot.displayName = "ProgressRoot";
  * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
  * the indicator, with the `data-*` hooks merged in.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Progress.Root value={75} aria-label="Upload progress">
@@ -127,6 +155,10 @@ export function ProgressIndicator({
   const indicatorProps = {
     ...rest,
     "data-state": state,
+    // Stryker disable next-line ConditionalExpression: `value` is null only
+    // while indeterminate, and React renders null and undefined attributes
+    // identically (both omitted), so the guarded (`undefined`) and unguarded
+    // (`null`) forms produce the same DOM — a provably-equivalent mutant.
     "data-value": value === null ? undefined : value,
     "data-max": max,
   };

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

@@ -1,6 +1,7 @@
 import { render, screen } from "@testing-library/react";
 
 import { Progress } from "../Progress";
+import { ProgressContext } from "../ProgressContext";
 
 describe("Progress basic rendering", () => {
   it('renders a <div role="progressbar">', () => {
@@ -30,6 +31,7 @@ describe("Progress basic rendering", () => {
     // Assert
     expect(bar).toHaveAttribute("data-state", "indeterminate");
     expect(bar).not.toHaveAttribute("aria-valuenow");
+    expect(bar).not.toHaveAttribute("aria-valuetext");
     expect(bar).not.toHaveAttribute("data-value");
   });
 
@@ -62,4 +64,12 @@ describe("Progress basic rendering", () => {
     );
     expect(screen.getByTestId("indicator")).toHaveAttribute("data-max", "100");
   });
+
+  it("sets a displayName on the compound, indicator, and context", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Progress".
+    expect(Progress.displayName).toBe("Progress");
+    expect(Progress.Indicator.displayName).toBe("ProgressIndicator");
+    expect(ProgressContext.displayName).toBe("ProgressContext");
+  });
 });

package/src/Progress/__tests__/Progress.value.test.tsx

@@ -66,6 +66,27 @@ describe("Progress value", () => {
     expect(screen.getByTestId("indicator")).toHaveAttribute("data-value", "70");
   });
 
+  it("propagates a changed value to the Indicator through context", () => {
+    // Arrange
+    const { rerender } = render(
+      <Progress.Root value={40} aria-label="Upload">
+        <Progress.Indicator data-testid="indicator" />
+      </Progress.Root>,
+    );
+    expect(screen.getByTestId("indicator")).toHaveAttribute("data-value", "40");
+
+    // Act — a new value must recompute the memoised context value, not a stale
+    // one frozen by empty dependencies.
+    rerender(
+      <Progress.Root value={70} aria-label="Upload">
+        <Progress.Indicator data-testid="indicator" />
+      </Progress.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute("data-value", "70");
+  });
+
   describe.each(determinateStateCases)(
     "value $value of $max",
     ({ value, max, expectedState }) => {

package/src/Progress/types.ts

@@ -21,23 +21,39 @@ export type ProgressRootProps = Omit<
 > & {
   /**
    * Current progress, between `0` and `max`. Pass `null` (or omit) for an
-   * indeterminate progress bar whose completion ratio is unknown.
+   * indeterminate progress bar whose completion ratio is unknown. Drives the
+   * resolved {@link ProgressState} and the `aria-valuenow` / `data-value`
+   * hooks. A non-`null` value outside `0..max` throws.
+   * @default null
    */
   value?: number | null;
-  /** Upper bound of `value`. Must be a positive finite number. Defaults to `100`. */
+  /**
+   * Upper bound of `value`. Must be a positive, finite number, or Root throws
+   * during render.
+   * @default 100
+   */
   max?: number;
   /**
    * Produces the human-readable `aria-valuetext`. Receives the resolved
    * `value` and `max`. Defaults to a rounded percentage (e.g. `"42%"`).
    * Not called while indeterminate.
+   * @default (value, max) => `${Math.round((value / max) * 100)}%`
    */
   getValueLabel?: (value: number, max: number) => string;
-  /** Render the consumer's own element instead of the native `<div>`. */
+  /**
+   * Render the consumer's own element instead of the native `<div>`, merging
+   * the ARIA and `data-*` hooks onto it via {@link Slot}.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /** Props for {@link Progress.Indicator} — all `<div>` attributes plus `asChild`. */
 export type ProgressIndicatorProps = ComponentProps<"div"> & {
-  /** Render the consumer's own element instead of the native `<div>`. */
+  /**
+   * Render the consumer's own element instead of the native `<div>`, merging
+   * the `data-*` hooks onto it via {@link Slot}.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/Radio/Radio.tsx

@@ -46,6 +46,8 @@ function dataStateOf(checked: boolean) {
  * visibility off the input's native `:checked` / `:has()` selectors;
  * `data-state` is a convenience mirror.
  *
+ * @extends HTMLInputElement
+ *
  * @example Native group (the browser owns selection)
  * ```tsx
  * <Radio.Root name="density" value="compact" defaultChecked aria-label="Compact">
@@ -112,7 +114,11 @@ export function RadioRoot(props: RadioRootProps): ReactElement {
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Radio" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof RadioRoot`,
+// which TRadioCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 RadioRoot.displayName = "RadioRoot";
 
 /**
@@ -129,6 +135,8 @@ RadioRoot.displayName = "RadioRoot";
  * (typically an `<svg>` dot) as the indicator itself, with `data-state` merged
  * onto that element rather than a wrapper.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Dot as the indicator via `asChild`
  * ```tsx
  * <Radio.Indicator asChild>

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

@@ -63,4 +63,18 @@ describe("Radio basic rendering", () => {
       "unchecked",
     );
   });
+
+  it("sets a displayName on the compound and the Indicator", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Radio".
+    expect(Radio.displayName).toBe("Radio");
+    expect(Radio.Indicator.displayName).toBe("RadioIndicator");
+  });
+
+  it("throws a helpful error when a sub-component renders outside Radio.Root", () => {
+    // Assert — the strict-context guard names the required parent.
+    expect(() => render(<Radio.Indicator />)).toThrow(
+      "Radio sub-components must be rendered inside a <Radio.Root>.",
+    );
+  });
 });

package/src/Radio/hooks/useRadioRoot.ts

@@ -36,6 +36,9 @@ export function useRadioRoot({
     onChange?.(event);
     if (event.defaultPrevented) return;
     const next = event.target.checked;
+    // Stryker disable next-line ConditionalExpression: in controlled mode the
+    // input reads the controlled value, never `mirror`, so setting mirror here
+    // (the mutant's always-run form) has no observable effect — equivalent.
     if (!isControlled) setMirror(next);
     onCheckedChange?.(next);
   };

package/src/Radio/types.ts

@@ -8,7 +8,16 @@ import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
  * grouped sibling (which fires no React event).
  */
 export type RadioIndicatorProps = ComponentProps<"span"> & {
+  /** Custom dot content. Omit to let the shipped CSS draw the dot off the
+   * input's native `:checked` state; provide your own (an icon, glyph, or
+   * nested element) to override it. */
   children?: ReactNode;
+  /**
+   * When `true`, render `children` as the indicator element itself (via the
+   * {@link Slot} pattern) instead of wrapping them in a `<span>`. `data-state`
+   * and `aria-hidden` are merged onto that element.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -42,7 +51,11 @@ export type RadioRootBaseProps = Omit<
  * forbidden.
  */
 export type RadioRootUncontrolledProps = RadioRootBaseProps & {
+  /** Whether this radio is selected on first render; the **browser** owns it
+   * thereafter, so native `name`-grouping (including silent deselection of
+   * siblings) works for free. Omit for an initially unselected radio. */
   defaultChecked?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
   checked?: never;
 };
 
@@ -52,8 +65,15 @@ export type RadioRootUncontrolledProps = RadioRootBaseProps & {
  * forbidden. The consumer owns grouping in this mode.
  */
 export type RadioRootControlledProps = RadioRootBaseProps & {
+  /** Forbidden in controlled mode — use `checked` instead. */
   defaultChecked?: never;
+  /** Whether this radio is currently selected, owned by the parent. The
+   * consumer owns grouping in this mode (typically deriving each radio's
+   * `checked` from a single shared value). Keep it in sync via
+   * `onCheckedChange`. */
   checked: boolean;
+  /** Called (always with `true`) whenever this radio becomes selected —
+   * required in controlled mode so the parent can update its shared value. */
   onCheckedChange: (checked: boolean) => void;
 };
 

package/src/RadioCard/RadioCard.tsx

@@ -49,6 +49,8 @@ import {
  * **`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">
@@ -130,6 +132,11 @@ export function RadioCardRoot({
 }
 
 /** @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";
 
 /**
@@ -157,6 +164,8 @@ RadioCardRoot.displayName = "RadioCardRoot";
  * 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({
@@ -252,6 +261,8 @@ RadioCardItem.displayName = "RadioCardItem";
  * while unchecked so a CSS exit animation can play against
  * `data-state="unchecked"`.
  *
+ * @extends HTMLSpanElement
+ *
  * @example
  * ```tsx
  * <RadioCard.Item value="pro">

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

@@ -84,4 +84,12 @@ describe("RadioCard basic rendering", () => {
     // Assert
     expect(screen.getByTestId("icon")).toBeInTheDocument();
   });
+
+  it("sets a displayName on the compound, Item, and Indicator", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "RadioCard".
+    expect(RadioCard.displayName).toBe("RadioCard");
+    expect(RadioCard.Item.displayName).toBe("RadioCardItem");
+    expect(RadioCard.Indicator.displayName).toBe("RadioCardIndicator");
+  });
 });

package/src/RadioCard/__tests__/RadioCard.disabled-items.test.tsx

@@ -37,6 +37,33 @@ describe("RadioCard disabled items", () => {
     expect(onValueChange).not.toHaveBeenCalled();
   });
 
+  it("re-registers an item's disabled flag when it changes after mount", async () => {
+    // Arrange — all enabled at mount; Pro becomes disabled afterwards.
+    const user = userEvent.setup();
+    function Fixture({ proDisabled }: { proDisabled: boolean }) {
+      return (
+        <RadioCard.Root aria-label="Plan" defaultValue="starter">
+          <RadioCard.Item value="starter">Starter</RadioCard.Item>
+          <RadioCard.Item value="pro" disabled={proDisabled}>
+            Pro
+          </RadioCard.Item>
+          <RadioCard.Item value="enterprise">Enterprise</RadioCard.Item>
+        </RadioCard.Root>
+      );
+    }
+    const { rerender } = render(<Fixture proDisabled={false} />);
+
+    // Act — disable Pro after mount, then arrow forwards from Starter.
+    rerender(<Fixture proDisabled />);
+    screen.getByRole("radio", { name: "Starter" }).focus();
+    await user.keyboard("{ArrowDown}");
+
+    // Assert — the registrar effect re-ran, so Pro is skipped and focus lands
+    // on Enterprise. A stale registration would keep Pro navigable and strand
+    // focus (a disabled button cannot receive it).
+    expect(screen.getByRole("radio", { name: "Enterprise" })).toHaveFocus();
+  });
+
   it("excludes disabled items from the roving-tabindex home base", () => {
     // Arrange & Act — no default value, first NON-disabled item is the tab stop
     render(

package/src/RadioCard/__tests__/RadioCard.keyboard-interaction.test.tsx

@@ -3,6 +3,59 @@ import userEvent from "@testing-library/user-event";
 
 import { RadioCard } from "../RadioCard";
 
+describe("RadioCard roving tab stop", () => {
+  it("makes the selected item the tab stop even when it is not first", () => {
+    // Arrange & Act — Pro is selected but not the first item.
+    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 — selection drives the tab stop; falling back to the first item
+    // would strand it on Starter.
+    expect(screen.getByRole("radio", { name: "Pro" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("radio", { name: "Starter" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
+
+  it("unregisters an unmounted item so the home-base tab stop moves", () => {
+    // Arrange — nothing selected, so the first item is the home base.
+    function Fixture({ items }: { items: string[] }) {
+      return (
+        <RadioCard.Root aria-label="Plan">
+          {items.map((v) => (
+            <RadioCard.Item key={v} value={v}>
+              {v}
+            </RadioCard.Item>
+          ))}
+        </RadioCard.Root>
+      );
+    }
+    const { rerender } = render(<Fixture items={["starter", "pro"]} />);
+    expect(screen.getByRole("radio", { name: "starter" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — remove "starter"; its effect cleanup must unregister it.
+    rerender(<Fixture items={["pro"]} />);
+
+    // Assert — "pro" becomes the home base. A no-op cleanup would leave
+    // "starter" registered ahead of it, leaving "pro" at tabindex -1.
+    expect(screen.getByRole("radio", { name: "pro" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+  });
+});
+
 describe("RadioCard keyboard interaction", () => {
   it("selects and focuses the next item on ArrowDown", async () => {
     // Arrange

package/src/RadioCard/__tests__/RadioCard.ref-forwarding.test.tsx

@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+
+import { RadioCard } from "../RadioCard";
+
+describe("RadioCard.Item ref forwarding", () => {
+  it("forwards the underlying button element to a consumer function ref", () => {
+    // Arrange
+    const received: (HTMLButtonElement | null)[] = [];
+    const functionRef = (node: HTMLButtonElement | null) => {
+      received.push(node);
+    };
+
+    // Act
+    render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro" ref={functionRef}>
+          Pro
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert
+    expect(received).toContain(screen.getByRole("radio", { name: "Pro" }));
+  });
+
+  it("re-attaches to a replacement ref when the ref prop changes", () => {
+    // Arrange — the item's ref memo must depend on `ref`, or a changed ref
+    // callback is never invoked with the element.
+    const secondReceived: (HTMLButtonElement | null)[] = [];
+    const firstRef = () => {};
+    const secondRef = (node: HTMLButtonElement | null) => {
+      secondReceived.push(node);
+    };
+
+    // Act — mount with the first ref, then re-render with a different one.
+    const { rerender } = render(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro" ref={firstRef}>
+          Pro
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+    rerender(
+      <RadioCard.Root aria-label="Plan">
+        <RadioCard.Item value="pro" ref={secondRef}>
+          Pro
+        </RadioCard.Item>
+      </RadioCard.Root>,
+    );
+
+    // Assert — the replacement ref received the button.
+    expect(secondReceived).toContain(screen.getByRole("radio", { name: "Pro" }));
+  });
+});

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

@@ -105,4 +105,25 @@ describe("RadioCard uncontrolled state", () => {
     // Assert
     expect(onValueChange).not.toHaveBeenCalled();
   });
+
+  it("does not re-fire onValueChange when a freshly selected item is re-clicked", async () => {
+    // Arrange — no defaultValue, so the guard reads a value that changes after
+    // the first click; a stale select closure would re-fire on the second.
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioCard.Root aria-label="Plan" onValueChange={onValueChange}>
+        <RadioCard.Item value="pro">Pro</RadioCard.Item>
+        <RadioCard.Item value="starter">Starter</RadioCard.Item>
+      </RadioCard.Root>,
+    );
+    const pro = screen.getByRole("radio", { name: "Pro" });
+
+    // Act — select Pro, then click it again while it is already selected.
+    await user.click(pro);
+    await user.click(pro);
+
+    // Assert — exactly one change: the redundant second click is a no-op.
+    expect(onValueChange).toHaveBeenCalledOnce();
+  });
 });

package/src/RadioCard/hooks/useRadioCardRoot.ts

@@ -46,6 +46,9 @@ export function useRadioCardRoot({
     ) => {
       registerItemBase(itemValue, element ? { element, disabled } : null);
     },
+    // `registerItemBase` is a stable useCollection callback (its own deps never
+    // change), so emptying this array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [registerItemBase],
   );
 
@@ -61,8 +64,16 @@ export function useRadioCardRoot({
 
   const focusItem = useCallback(
     (itemValue: string) => {
+      // `itemValue` is always sourced from `navigable` (the enabled subset of
+      // `itemValues`), and `useCollection`'s register() writes `itemsRef` and
+      // the `itemValues` state together in the same call — so a value that
+      // appears here is guaranteed to already have a live entry in the map.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
       itemsRef.current.get(itemValue)?.element.focus();
     },
+    // `itemsRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [itemsRef],
   );