@primitiv-ui/react 0.1.28 → 0.1.30

package/src/SplitButton/__tests__/SplitButton.disabled.test.tsx

@@ -0,0 +1,79 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { SplitButton } from "../SplitButton";
+
+describe("SplitButton — disabled", () => {
+  it("disables both halves when the group is disabled", () => {
+    render(
+      <SplitButton disabled>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu />
+      </SplitButton>,
+    );
+
+    expect(screen.getByRole("group")).toHaveAttribute("data-disabled", "");
+    expect(
+      screen.getByRole("button", { name: "Squash and merge" }),
+    ).toBeDisabled();
+    expect(
+      screen.getByRole("button", { name: "More merge options" }),
+    ).toBeDisabled();
+  });
+
+  it("disables one half independently, leaving the other interactive", () => {
+    render(
+      <SplitButton>
+        <SplitButton.Action disabled>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu />
+      </SplitButton>,
+    );
+
+    expect(screen.getByRole("group")).not.toHaveAttribute("data-disabled");
+    expect(
+      screen.getByRole("button", { name: "Squash and merge" }),
+    ).toHaveAttribute("data-disabled", "");
+    expect(
+      screen.getByRole("button", { name: "More merge options" }),
+    ).toBeEnabled();
+  });
+
+  it("disables only the menu half when the trigger is disabled", () => {
+    render(
+      <SplitButton>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger disabled aria-label="More merge options" />
+        <SplitButton.Menu />
+      </SplitButton>,
+    );
+
+    expect(
+      screen.getByRole("button", { name: "Squash and merge" }),
+    ).toBeEnabled();
+    expect(
+      screen.getByRole("button", { name: "More merge options" }),
+    ).toHaveAttribute("data-disabled", "");
+  });
+
+  it("re-propagates when the group's disabled flips after mount", () => {
+    const markup = (disabled: boolean) => (
+      <SplitButton disabled={disabled}>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu />
+      </SplitButton>
+    );
+    const { rerender } = render(markup(false));
+
+    rerender(markup(true));
+
+    expect(
+      screen.getByRole("button", { name: "Squash and merge" }),
+    ).toBeDisabled();
+    expect(
+      screen.getByRole("button", { name: "More merge options" }),
+    ).toBeDisabled();
+  });
+});

package/src/SplitButton/__tests__/SplitButton.error-handling.test.tsx

@@ -0,0 +1,29 @@
+import { render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { SplitButton } from "../SplitButton";
+
+const outsideRoot =
+  "SplitButton sub-components must be rendered inside a <SplitButton.Root>.";
+
+describe("SplitButton — error handling", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("throws when SplitButton.Action is used outside SplitButton.Root", () => {
+    expect(() =>
+      render(<SplitButton.Action>Orphan</SplitButton.Action>),
+    ).toThrowError(outsideRoot);
+  });
+
+  it("throws when SplitButton.Trigger is used outside SplitButton.Root", () => {
+    expect(() => render(<SplitButton.Trigger aria-label="Orphan" />)).toThrowError(
+      outsideRoot,
+    );
+  });
+});

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

@@ -0,0 +1,56 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { SplitButton } from "../SplitButton";
+
+describe("SplitButton — keyboard interaction", () => {
+  it("opens the menu from the action with ArrowDown and focuses the first item", async () => {
+    const user = userEvent.setup();
+    render(
+      <SplitButton>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu>
+          <SplitButton.Item>Create a merge commit</SplitButton.Item>
+          <SplitButton.Item>Rebase and merge</SplitButton.Item>
+        </SplitButton.Menu>
+      </SplitButton>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}");
+
+    expect(
+      screen.getByRole("button", { name: "More merge options" }),
+    ).toHaveAttribute("aria-expanded", "true");
+    expect(
+      screen.getByRole("menuitem", {
+        name: "Create a merge commit",
+        hidden: true,
+      }),
+    ).toHaveFocus();
+  });
+
+  it("leaves the menu closed for other keys, and still runs the action's own handler", async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+    render(
+      <SplitButton>
+        <SplitButton.Action onKeyDown={onKeyDown}>
+          Squash and merge
+        </SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu>
+          <SplitButton.Item>Create a merge commit</SplitButton.Item>
+        </SplitButton.Menu>
+      </SplitButton>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowUp}");
+
+    expect(onKeyDown).toHaveBeenCalledOnce();
+    expect(screen.getByRole("group")).toHaveAttribute("data-state", "closed");
+  });
+});

package/src/SplitButton/__tests__/SplitButton.state-modes.test.tsx

@@ -0,0 +1,68 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Dropdown } from "../../Dropdown/index.ts";
+import { SplitButton } from "../SplitButton";
+
+describe("SplitButton — state modes", () => {
+  it("starts open in uncontrolled mode when defaultOpen is set", () => {
+    render(
+      <SplitButton defaultOpen>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu>
+          <SplitButton.Item>Rebase and merge</SplitButton.Item>
+        </SplitButton.Menu>
+      </SplitButton>,
+    );
+
+    expect(screen.getByRole("group")).toHaveAttribute("data-state", "open");
+  });
+
+  it("defers to the parent in controlled mode", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <SplitButton open={false} onOpenChange={onOpenChange}>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu>
+          <SplitButton.Item>Rebase and merge</SplitButton.Item>
+        </SplitButton.Menu>
+      </SplitButton>,
+    );
+
+    await user.click(screen.getByRole("button", { name: "More merge options" }));
+
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(screen.getByRole("group")).toHaveAttribute("data-state", "closed");
+  });
+
+  it("passes the reading direction down to menus composed from Dropdown", async () => {
+    const user = userEvent.setup();
+    render(
+      <SplitButton dir="rtl" defaultOpen>
+        <SplitButton.Action>Squash and merge</SplitButton.Action>
+        <SplitButton.Trigger aria-label="More merge options" />
+        <SplitButton.Menu>
+          <Dropdown.Sub>
+            <Dropdown.SubTrigger>Merge strategies</Dropdown.SubTrigger>
+            <Dropdown.SubContent>
+              <SplitButton.Item>Rebase and merge</SplitButton.Item>
+            </Dropdown.SubContent>
+          </Dropdown.Sub>
+        </SplitButton.Menu>
+      </SplitButton>,
+    );
+
+    await user.keyboard("{ArrowLeft}");
+
+    expect(
+      screen.getByRole("menuitem", {
+        name: "Merge strategies",
+        hidden: true,
+      }),
+    ).toHaveAttribute("aria-expanded", "true");
+  });
+});

package/src/SplitButton/index.ts

@@ -0,0 +1,2 @@
+export { SplitButton } from "./SplitButton";
+export type * from "./types";

package/src/SplitButton/types.ts

@@ -0,0 +1,186 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+import type { Direction } from "../DirectionProvider/index.ts";
+import type {
+  DropdownContentProps,
+  DropdownItemProps,
+  DropdownSeparatorProps,
+  DropdownTriggerProps,
+} from "../Dropdown/types";
+
+/**
+ * Shared base for both {@link SplitButtonRootProps} variants — the native
+ * `<div>` attributes (minus the component-owned `role` and the narrowed
+ * `dir`) plus the `asChild` escape hatch, reading direction, and the
+ * group-level `disabled`.
+ */
+export type SplitButtonRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "role" | "dir"
+> & {
+  /**
+   * The widget's parts — typically one
+   * {@link SplitButtonActionProps | `SplitButton.Action`}, one
+   * {@link SplitButtonTriggerProps | `SplitButton.Trigger`}, and one
+   * {@link SplitButtonMenuProps | `SplitButton.Menu`}.
+   */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement` (or to the `asChild`
+   * element). */
+  ref?: Ref<HTMLDivElement>;
+  /**
+   * When `true`, Root delegates rendering to a single consumer-supplied
+   * element via the {@link Slot} pattern instead of the default `<div>`;
+   * `role="group"`, `data-state`, `data-disabled` and the remaining props are
+   * merged onto it.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Reading direction for the menu. Only affects which arrow key opens or
+   * closes a submenu composed from `Dropdown.Sub` — `ArrowRight` opens in
+   * `"ltr"`, `ArrowLeft` in `"rtl"`. When omitted it is inherited from the
+   * nearest {@link DirectionProvider}, falling back to `"ltr"`.
+   */
+  dir?: Direction;
+  /**
+   * Disables the whole widget — both the primary action and the menu trigger
+   * become non-interactive, and `data-disabled=""` is set on the group. OR-ed
+   * with each half's own `disabled`, so a disabled group can never be
+   * overridden back to enabled by a part.
+   * @default false
+   */
+  disabled?: boolean;
+};
+
+/**
+ * Uncontrolled variant of {@link SplitButtonRootProps}: the component owns the
+ * menu's open state. Pass `defaultOpen` (or omit it); `onOpenChange` is
+ * optional and `open` is forbidden.
+ */
+export type SplitButtonRootUncontrolledProps = SplitButtonRootBaseProps & {
+  /**
+   * Whether the menu is open on first render. Omit to start closed. The
+   * component owns the state thereafter.
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
+  open?: never;
+  /**
+   * Called whenever a user-driven transition opens or closes the menu
+   * (trigger click, `ArrowDown` on the action, Escape, outside click,
+   * selection). Optional in uncontrolled mode.
+   */
+  onOpenChange?: (open: boolean) => void;
+};
+
+/**
+ * Controlled variant of {@link SplitButtonRootProps}: the parent owns the
+ * menu's open state. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
+ */
+export type SplitButtonRootControlledProps = SplitButtonRootBaseProps & {
+  /** Forbidden in controlled mode — use `open` instead. */
+  defaultOpen?: never;
+  /**
+   * Whether the menu is currently open. Must be kept in sync by the parent via
+   * `onOpenChange`; the component never mutates it internally.
+   */
+  open: boolean;
+  /**
+   * Called whenever a user-driven transition would open or close the menu. The
+   * parent is responsible for reflecting the new value back into `open`.
+   * Required in controlled mode.
+   */
+  onOpenChange: (open: boolean) => void;
+};
+
+/**
+ * Props for {@link SplitButtonRoot | `SplitButton.Root`} — the
+ * controlled/uncontrolled discriminated union pairing
+ * {@link SplitButtonRootUncontrolledProps} with
+ * {@link SplitButtonRootControlledProps}, plus the shared group props.
+ */
+export type SplitButtonRootProps =
+  | SplitButtonRootUncontrolledProps
+  | SplitButtonRootControlledProps;
+
+/**
+ * Props for the internal frame component that renders the group element. Root
+ * splits it out so the frame sits *inside* the `Dropdown.Root` it renders and
+ * can therefore read the menu's open state.
+ *
+ * @internal
+ */
+export type SplitButtonFrameProps = Omit<
+  SplitButtonRootBaseProps,
+  "dir" | "disabled"
+> & {
+  /** Already defaulted by Root, so the frame receives a definite boolean. */
+  disabled: boolean;
+};
+
+/**
+ * Value published by `SplitButtonContext` — the derived ids that wire the
+ * trigger's accessible name to the action, plus the group's disabled flag.
+ *
+ * @internal
+ */
+export type SplitButtonContextValue = {
+  /** DOM id applied to {@link SplitButtonActionProps | `SplitButton.Action`};
+   * referenced by the trigger's derived `aria-labelledby`. */
+  actionId: string;
+  /** DOM id applied to {@link SplitButtonTriggerProps | `SplitButton.Trigger`};
+   * the self-reference half of its derived `aria-labelledby`. */
+  triggerId: string;
+  /** Whether the whole widget is disabled (Root's `disabled` prop). */
+  disabled: boolean;
+};
+
+/**
+ * Props for {@link SplitButtonAction | `SplitButton.Action`} — the native
+ * `<button>` attributes minus `id`, which the component owns because the menu
+ * trigger's accessible name references it.
+ */
+export type SplitButtonActionProps = Omit<ComponentProps<"button">, "id"> & {
+  /** The action's visible label. Keep it real text — the menu trigger borrows
+   * it for its own accessible name. */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLButtonElement` (or to the `asChild`
+   * element). */
+  ref?: Ref<HTMLButtonElement>;
+  /**
+   * When `true`, renders the consumer's element instead of `<button>` via the
+   * {@link Slot} pattern. `type="button"` is **not** forwarded in this mode —
+   * the child owns its own type semantics.
+   * @default false
+   */
+  asChild?: boolean;
+};
+
+/**
+ * Props for {@link SplitButtonTrigger | `SplitButton.Trigger`} —
+ * {@link DropdownTriggerProps} minus `id`, which the component owns because
+ * its derived `aria-labelledby` self-references it. Supply `aria-label` or
+ * `aria-labelledby` to opt out of the derived name.
+ */
+export type SplitButtonTriggerProps = Omit<DropdownTriggerProps, "id">;
+
+/**
+ * Props for {@link SplitButtonMenu | `SplitButton.Menu`} — identical to
+ * {@link DropdownContentProps}; the menu *is* a `Dropdown.Content`.
+ */
+export type SplitButtonMenuProps = DropdownContentProps;
+
+/**
+ * Props for {@link SplitButtonItem | `SplitButton.Item`} — identical to
+ * {@link DropdownItemProps}.
+ */
+export type SplitButtonItemProps = DropdownItemProps;
+
+/**
+ * Props for {@link SplitButtonSeparator | `SplitButton.Separator`} — identical
+ * to {@link DropdownSeparatorProps}.
+ */
+export type SplitButtonSeparatorProps = DropdownSeparatorProps;

package/src/Status/Status.tsx

@@ -4,29 +4,50 @@ import { Slot } from "../Slot/index.ts";
 import { StatusProps } from "./types";
 
 /**
- * A polite live region for low-priority, non-urgent status messages.
+ * A polite live region for low-priority, non-urgent status messages,
+ * implementing the WAI-ARIA `status` role.
  *
- * Renders a `<div role="status">`. The `status` role carries an
- * implicit `aria-live="polite"` and `aria-atomic="true"`, so assistive
- * technology announces the message once the user is idle, without
- * interrupting them — use it for confirmations, counts, and background
- * progress. For errors the user must see immediately, reach for
- * `Alert` instead.
+ * Renders a `<div role="status">`. The `status` role carries an implicit
+ * `aria-live="polite"` and `aria-atomic="true"`, so assistive technology
+ * announces the message once the user is idle, without interrupting
+ * them — use it for confirmations, counts, and background progress. For
+ * errors the user must see immediately, reach for `Alert` instead.
  *
- * Render the `Status` conditionally, or update its text content while
- * it stays mounted: the live region announces content that changes
- * *after* it is already in the DOM.
+ * **Live region timing.** A live region only announces content that
+ * changes *after* the region is already in the DOM. Either render
+ * `Status` conditionally (mount when a message is ready), or keep it
+ * mounted and update its text:
  *
- * **`asChild` composition.** Renders the consumer's element instead of
- * a `<div>`, merging `role="status"` and all other props in via the
- * {@link Slot} utility.
+ * ```tsx
+ * // Conditional mount — announces on first appearance
+ * {saved && <Status>All changes saved.</Status>}
+ *
+ * // Persistent — announces on every content change
+ * <Status>{count} items in your cart</Status>
+ * ```
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * element instead of a `<div>`, merging `role="status"` and all other
+ * props onto it via the {@link Slot} utility. Event handlers compose with
+ * the child's own handlers (child runs first).
+ *
+ * @extends HTMLDivElement
  *
  * @example Confirmation message
  * ```tsx
- * {saved && <Status>All changes saved.</Status>}
+ * import { Status } from "@primitiv-ui/react";
+ *
+ * function SaveIndicator({ saved }: { saved: boolean }) {
+ *   return saved ? <Status>All changes saved.</Status> : null;
+ * }
+ * ```
+ *
+ * @example Cart count — persistent live region
+ * ```tsx
+ * <Status>{count} items in your cart</Status>
  * ```
  *
- * @example asChild — keep semantic markup
+ * @example asChild — apply the status role to a semantic element
  * ```tsx
  * <Status asChild>
  *   <output>{count} items in your cart</output>

package/src/Status/__tests__/Status.test.tsx

@@ -25,4 +25,9 @@ describe("Status component", () => {
     expect(status.tagName).toBe("SECTION");
     expect(status).toHaveTextContent("Saved");
   });
+
+  it('sets displayName to "Status" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Status.displayName).toBe("Status");
+  });
 });

package/src/Status/types.ts

@@ -1,9 +1,20 @@
-import { ComponentProps } from "react";
+import { ComponentProps, ReactNode } from "react";
 
 /**
  * Props for {@link Status} — all native `<div>` attributes plus the
  * `asChild` escape hatch.
  */
 export type StatusProps = ComponentProps<"div"> & {
+  /**
+   * Renders the child element instead of a native `<div>`, merging
+   * `role="status"` and all other props onto it via {@link Slot}.
+   * Event handlers compose with the child's own handlers (child runs
+   * first). Use this to apply the live-region role to a semantically
+   * appropriate element (e.g. `<output>`).
+   * @default false
+   */
   asChild?: boolean;
+  /** Content to announce. A live region announces changes that occur
+   * after the region is already present in the DOM. */
+  children?: ReactNode;
 };

package/src/Switch/README.md

@@ -45,7 +45,7 @@ Pass `checked` and `onCheckedChange` together. The parent owns the value.
 ```tsx
 const [enabled, setEnabled] = useState(false);
 
-<Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+<Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="...">
   <Switch.Thumb />
 </Switch.Root>
 ```

package/src/Switch/Switch.tsx

@@ -25,7 +25,7 @@ function dataStateOf(checked: boolean) {
  *
  * Props routing: `className` / `style` style the **track** (the `<label>` you
  * see — the input is hidden); every other prop (`name`, `value`, `id`,
- * `aria-*`, `required`, `disabled`, `ref`, …) spreads onto the input, because
+ * `aria-*`, `required`, `disabled`, `ref`, ...) spreads onto the input, because
  * semantically the Root *is* the switch.
  *
  * Supports two state modes, statically discriminated at the type level:
@@ -42,6 +42,12 @@ function dataStateOf(checked: boolean) {
  * **Keyboard.** Toggles on `Space` (the native checkbox behaviour); `Enter`
  * does not toggle a checkbox-based control.
  *
+ * **`onChange` composition.** The consumer's raw `onChange` fires first; if it
+ * calls `event.preventDefault()`, the internal mirror update and
+ * `onCheckedChange` are skipped for that event. See {@link SwitchRootBaseProps}.
+ *
+ * @extends HTMLInputElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <Switch.Root name="notify" value="on" defaultChecked aria-label="Enable notifications">
@@ -53,7 +59,7 @@ function dataStateOf(checked: boolean) {
  * ```tsx
  * const [enabled, setEnabled] = useState(false);
  *
- * <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+ * <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="...">
  *   <Switch.Thumb />
  * </Switch.Root>
  * ```
@@ -102,7 +108,11 @@ export function SwitchRoot({
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Switch" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof SwitchRoot`,
+// which TSwitchCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 SwitchRoot.displayName = "SwitchRoot";
 
 /**
@@ -114,7 +124,10 @@ SwitchRoot.displayName = "SwitchRoot";
  * **Styling hook.** Mirrors the root's `data-state="checked" | "unchecked"`.
  *
  * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
- * the thumb, with `aria-hidden` and `data-state` merged in.
+ * the thumb, with `aria-hidden` and `data-state` merged in via the
+ * {@link Slot} pattern. See {@link SwitchThumbProps}.
+ *
+ * @extends HTMLSpanElement
  *
  * @example
  * ```tsx

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

@@ -92,4 +92,11 @@ describe("Switch basic rendering", () => {
     expect(thumb).toHaveAttribute("aria-hidden", "true");
     expect(thumb).toHaveAttribute("data-state", "unchecked");
   });
+
+  it("sets a displayName on the compound and the Thumb", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Switch".
+    expect(Switch.displayName).toBe("Switch");
+    expect(Switch.Thumb.displayName).toBe("SwitchThumb");
+  });
 });

package/src/Switch/hooks/useSwitchRoot.ts

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