@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,151 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function SingleFixture({ defaultValue }: { defaultValue?: string }) {
+  return (
+    <ToggleGroup.Root type="single" defaultValue={defaultValue} aria-label="Alignment">
+      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+function MultipleFixture() {
+  return (
+    <ToggleGroup.Root type="multiple" aria-label="Formatting">
+      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
+      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup keyboard — roving tabindex", () => {
+  it("only one item has tabIndex=0 on mount (first item when nothing selected)", async () => {
+    render(<SingleFixture />);
+    // Wait for item registration effect
+    await Promise.resolve();
+    const buttons = screen.getAllByRole("button");
+    const tabstops = buttons.filter((b) => b.getAttribute("tabindex") === "0");
+    expect(tabstops).toHaveLength(1);
+  });
+
+  it("the selected item is the tabstop when defaultValue is set", async () => {
+    render(<SingleFixture defaultValue="center" />);
+    await Promise.resolve();
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
+});
+
+describe("ToggleGroup keyboard — arrow key navigation (no auto-select)", () => {
+  it("ArrowRight moves focus to the next item without toggling", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("button", { name: "Center" })).toHaveFocus();
+    // Focus moved but nothing is pressed
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("ArrowLeft moves focus to the previous item", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Center" }).focus();
+    await user.keyboard("{ArrowLeft}");
+    expect(screen.getByRole("button", { name: "Left" })).toHaveFocus();
+  });
+
+  it("ArrowRight wraps from last to first", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Right" }).focus();
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("button", { name: "Left" })).toHaveFocus();
+  });
+
+  it("Home moves focus to the first item", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Right" }).focus();
+    await user.keyboard("{Home}");
+    expect(screen.getByRole("button", { name: "Left" })).toHaveFocus();
+  });
+
+  it("End moves focus to the last item", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{End}");
+    expect(screen.getByRole("button", { name: "Right" })).toHaveFocus();
+  });
+});
+
+describe("ToggleGroup keyboard — Space/Enter activate focused item", () => {
+  it("Space toggles the focused item on", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Center" }).focus();
+    await user.keyboard(" ");
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("Space toggles the focused active item off (single mode deselect)", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture defaultValue="center" />);
+    screen.getByRole("button", { name: "Center" }).focus();
+    await user.keyboard(" ");
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("Enter toggles the focused item on (multiple mode)", async () => {
+    const user = userEvent.setup();
+    render(<MultipleFixture />);
+    screen.getByRole("button", { name: "Bold" }).focus();
+    await user.keyboard("{Enter}");
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    // Others unaffected
+    expect(screen.getByRole("button", { name: "Italic" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("navigating then activating toggles the destination item", async () => {
+    const user = userEvent.setup();
+    render(<SingleFixture />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{ArrowRight}");
+    await user.keyboard(" ");
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.multiple-mode.test.tsx

@@ -0,0 +1,144 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function Fixture({
+  defaultValue,
+  value,
+  onValueChange,
+}: {
+  defaultValue?: string[];
+  value?: string[];
+  onValueChange?: (v: string[]) => void;
+}) {
+  if (value !== undefined || onValueChange) {
+    return (
+      <ToggleGroup.Root
+        type="multiple"
+        value={value!}
+        onValueChange={onValueChange!}
+        aria-label="Formatting"
+      >
+        <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+        <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
+        <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
+      </ToggleGroup.Root>
+    );
+  }
+  return (
+    <ToggleGroup.Root
+      type="multiple"
+      defaultValue={defaultValue}
+      aria-label="Formatting"
+    >
+      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
+      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup multiple mode — uncontrolled", () => {
+  it("starts with no items pressed when defaultValue is omitted", () => {
+    render(<Fixture />);
+    for (const name of ["Bold", "Italic", "Underline"]) {
+      expect(screen.getByRole("button", { name })).toHaveAttribute(
+        "aria-pressed",
+        "false",
+      );
+    }
+  });
+
+  it("starts with defaultValue items pressed", () => {
+    render(<Fixture defaultValue={["bold", "italic"]} />);
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Italic" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Underline" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("clicking an item adds it to the pressed set without affecting others", async () => {
+    const user = userEvent.setup();
+    render(<Fixture defaultValue={["bold"]} />);
+    await user.click(screen.getByRole("button", { name: "Italic" }));
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Italic" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("clicking an active item removes it from the pressed set", async () => {
+    const user = userEvent.setup();
+    render(<Fixture defaultValue={["bold", "italic"]} />);
+    await user.click(screen.getByRole("button", { name: "Bold" }));
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+    expect(screen.getByRole("button", { name: "Italic" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("all items can be pressed simultaneously", async () => {
+    const user = userEvent.setup();
+    render(<Fixture />);
+    for (const name of ["Bold", "Italic", "Underline"]) {
+      await user.click(screen.getByRole("button", { name }));
+    }
+    for (const name of ["Bold", "Italic", "Underline"]) {
+      expect(screen.getByRole("button", { name })).toHaveAttribute(
+        "aria-pressed",
+        "true",
+      );
+    }
+  });
+});
+
+describe("ToggleGroup multiple mode — controlled", () => {
+  it("reflects the controlled value array", () => {
+    render(<Fixture value={["bold", "underline"]} onValueChange={vi.fn()} />);
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Italic" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+    expect(screen.getByRole("button", { name: "Underline" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("calls onValueChange with the updated array when adding an item", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<Fixture value={["bold"]} onValueChange={onValueChange} />);
+    await user.click(screen.getByRole("button", { name: "Italic" }));
+    expect(onValueChange).toHaveBeenCalledWith(["bold", "italic"]);
+  });
+
+  it("calls onValueChange with the updated array when removing an item", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<Fixture value={["bold", "italic"]} onValueChange={onValueChange} />);
+    await user.click(screen.getByRole("button", { name: "Bold" }));
+    expect(onValueChange).toHaveBeenCalledWith(["italic"]);
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.reading-direction.test.tsx

@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { DirectionProvider } from "../../DirectionProvider";
+import { ToggleGroup } from "../ToggleGroup";
+
+describe("ToggleGroup reading direction", () => {
+  it("should inherit reading direction from a DirectionProvider", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <DirectionProvider dir="rtl">
+        <ToggleGroup.Root type="single" aria-label="Alignment">
+          <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+          <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+          <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+        </ToggleGroup.Root>
+      </DirectionProvider>,
+    );
+    screen.getByRole("button", { name: "Left" }).focus();
+
+    // Act — in RTL, Arrow Left moves forward
+    await user.keyboard("{ArrowLeft}");
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Center" })).toHaveFocus();
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.single-mode.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function Fixture({
+  defaultValue,
+  value,
+  onValueChange,
+}: {
+  defaultValue?: string;
+  value?: string | undefined;
+  onValueChange?: (v: string | undefined) => void;
+}) {
+  if (value !== undefined || onValueChange) {
+    return (
+      <ToggleGroup.Root
+        type="single"
+        value={value}
+        onValueChange={onValueChange!}
+        aria-label="Alignment"
+      >
+        <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+        <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+        <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+      </ToggleGroup.Root>
+    );
+  }
+  return (
+    <ToggleGroup.Root
+      type="single"
+      defaultValue={defaultValue}
+      aria-label="Alignment"
+    >
+      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup single mode — uncontrolled", () => {
+  it("starts with no item pressed when defaultValue is omitted", () => {
+    render(<Fixture />);
+    for (const name of ["Left", "Center", "Right"]) {
+      expect(screen.getByRole("button", { name })).toHaveAttribute(
+        "aria-pressed",
+        "false",
+      );
+    }
+  });
+
+  it("starts with the defaultValue item pressed", () => {
+    render(<Fixture defaultValue="center" />);
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("pressing an unpressed item presses it and unpresses the previously pressed item", async () => {
+    const user = userEvent.setup();
+    render(<Fixture defaultValue="left" />);
+    await user.click(screen.getByRole("button", { name: "Center" }));
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("pressing the active item deselects it (toggle-off)", async () => {
+    const user = userEvent.setup();
+    render(<Fixture defaultValue="left" />);
+    await user.click(screen.getByRole("button", { name: "Left" }));
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it('sets data-state="on" on the pressed item and "off" on others', async () => {
+    const user = userEvent.setup();
+    render(<Fixture />);
+    await user.click(screen.getByRole("button", { name: "Right" }));
+    expect(screen.getByRole("button", { name: "Right" })).toHaveAttribute(
+      "data-state",
+      "on",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "data-state",
+      "off",
+    );
+  });
+});
+
+describe("ToggleGroup single mode — controlled", () => {
+  it("reflects the controlled value", () => {
+    render(<Fixture value="center" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+
+  it("calls onValueChange with the new value when a different item is clicked", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<Fixture value="left" onValueChange={onValueChange} />);
+    await user.click(screen.getByRole("button", { name: "Center" }));
+    expect(onValueChange).toHaveBeenCalledWith("center");
+  });
+
+  it("calls onValueChange with undefined when the active item is clicked", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<Fixture value="left" onValueChange={onValueChange} />);
+    await user.click(screen.getByRole("button", { name: "Left" }));
+    expect(onValueChange).toHaveBeenCalledWith(undefined);
+  });
+
+  it("does not flip the UI without a re-render (controlled contract)", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<Fixture value="left" onValueChange={onValueChange} />);
+    await user.click(screen.getByRole("button", { name: "Center" }));
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  });
+});

package/src/ToggleGroup/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useToggleGroupRoot } from "./useToggleGroupRoot";
+export { useToggleGroupContext } from "./useToggleGroupContext";

package/src/ToggleGroup/hooks/useToggleGroupContext.ts

@@ -0,0 +1 @@
+export { useToggleGroupContext } from "../ToggleGroupContext";

package/src/ToggleGroup/hooks/useToggleGroupRoot.ts

@@ -0,0 +1,110 @@
+import { useCallback, useMemo, useState } from "react";
+
+import { useCollection, useControllableState } from "../../hooks";
+
+type ItemMeta = { element: HTMLButtonElement; disabled: boolean };
+
+type UseToggleGroupRootArgs = {
+  type: "single" | "multiple";
+  defaultValue?: string | string[];
+  value?: string | string[] | undefined;
+  onValueChange?:
+    | ((v: string | undefined) => void)
+    | ((v: string[]) => void);
+  orientation: "horizontal" | "vertical";
+  dir: "ltr" | "rtl";
+};
+
+function toArray(v: string | string[] | undefined): string[] {
+  if (v === undefined) return [];
+  if (typeof v === "string") return [v];
+  return v;
+}
+
+export function useToggleGroupRoot({
+  type,
+  defaultValue,
+  value: rawControlled,
+  onValueChange,
+  orientation,
+  dir,
+}: UseToggleGroupRootArgs) {
+  const isControlled = onValueChange !== undefined;
+  const normalizedControlled = isControlled ? toArray(rawControlled) : undefined;
+  const normalizedDefault = toArray(defaultValue);
+
+  const [value, setValue] = useControllableState<string[]>(
+    normalizedControlled,
+    normalizedDefault,
+  );
+
+  const toggle = useCallback(
+    (itemValue: string) => {
+      const isSelected = value.includes(itemValue);
+      if (type === "single") {
+        const next = isSelected ? [] : [itemValue];
+        setValue(next);
+        (onValueChange as ((v: string | undefined) => void) | undefined)?.(
+          isSelected ? undefined : itemValue,
+        );
+      } else {
+        const next = isSelected
+          ? value.filter((v) => v !== itemValue)
+          : [...value, itemValue];
+        setValue(next);
+        (onValueChange as ((v: string[]) => void) | undefined)?.(next);
+      }
+    },
+    [type, value, setValue, onValueChange],
+  );
+
+  const {
+    register: registerBase,
+    itemsRef,
+    keys: itemValues,
+  } = useCollection<string, ItemMeta>();
+
+  const registerItem = useCallback(
+    (itemValue: string, element: HTMLButtonElement | null, disabled = false) => {
+      registerBase(itemValue, element ? { element, disabled } : null);
+    },
+    [registerBase],
+  );
+
+  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],
+  );
+
+  // Tracks which item holds the tabstop. Initialises to the first pressed
+  // value so the selected item is immediately tabbable. Updated via the
+  // onFocus handler in each Item so the tabstop follows actual focus.
+  const [focusedValue, setFocusedValue] = useState<string | undefined>(
+    () => value[0],
+  );
+
+  return {
+    value,
+    toggle,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+    focusedValue,
+    setFocusedValue,
+    orientation,
+    dir,
+  };
+}

package/src/ToggleGroup/index.ts

@@ -0,0 +1,2 @@
+export * from "./ToggleGroup";
+export * from "./types";

package/src/ToggleGroup/types.ts

@@ -0,0 +1,72 @@
+import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
+
+type ToggleGroupRootBaseProps = Omit<HTMLAttributes<HTMLDivElement>, "dir"> & {
+  orientation?: "horizontal" | "vertical";
+  dir?: "ltr" | "rtl";
+  asChild?: boolean;
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+};
+
+type SingleUncontrolledProps = {
+  type: "single";
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: never;
+};
+
+type SingleControlledProps = {
+  type: "single";
+  value: string | undefined;
+  onValueChange: (value: string | undefined) => void;
+  defaultValue?: never;
+};
+
+type MultipleUncontrolledProps = {
+  type: "multiple";
+  defaultValue?: string[];
+  value?: never;
+  onValueChange?: never;
+};
+
+type MultipleControlledProps = {
+  type: "multiple";
+  value: string[];
+  onValueChange: (value: string[]) => void;
+  defaultValue?: never;
+};
+
+export type ToggleGroupRootProps = ToggleGroupRootBaseProps &
+  (
+    | SingleUncontrolledProps
+    | SingleControlledProps
+    | MultipleUncontrolledProps
+    | MultipleControlledProps
+  );
+
+export type ToggleGroupItemProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type"
+> & {
+  value: string;
+  disabled?: boolean;
+  asChild?: boolean;
+  ref?: Ref<HTMLButtonElement>;
+};
+
+export type ToggleGroupContextValue = {
+  value: string[];
+  toggle: (itemValue: string) => void;
+  registerItem: (
+    itemValue: string,
+    element: HTMLButtonElement | null,
+    disabled?: boolean,
+  ) => void;
+  itemValues: string[];
+  disabledValues: Set<string>;
+  focusItem: (itemValue: string) => void;
+  focusedValue: string | undefined;
+  setFocusedValue: (itemValue: string) => void;
+  orientation: "horizontal" | "vertical";
+  dir: "ltr" | "rtl";
+};