@primitiv-ui/react 0.1.0

package/src/Tabs/__tests__/Tabs.fixtures.ts

@@ -0,0 +1,171 @@
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+export const arrowKeyCases = [
+  // LTR horizontal
+  {
+    description: 'LTR Horizontal: Right Arrow moves to next tab',
+    dir: 'ltr',
+    orientation: 'horizontal',
+    defaultValue: 'tab1',
+    key: '{ArrowRight}',
+    expectedTab: 'Tab 2',
+    expectedDeselected: ['Tab 1', 'Tab 3'],
+  },
+  {
+    description: 'LTR Horizontal: Left Arrow moves to previous tab',
+    dir: 'ltr',
+    orientation: 'horizontal',
+    defaultValue: 'tab2',
+    key: '{ArrowLeft}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+  {
+    description: 'LTR Horizontal: Left Arrow wraps to last tab from first',
+    dir: 'ltr',
+    orientation: 'horizontal',
+    defaultValue: 'tab1',
+    key: '{ArrowLeft}',
+    expectedTab: 'Tab 3',
+    expectedDeselected: ['Tab 1', 'Tab 2'],
+  },
+  {
+    description: 'LTR Horizontal: Right Arrow wraps to first tab from last',
+    dir: 'ltr',
+    orientation: 'horizontal',
+    defaultValue: 'tab3',
+    key: '{ArrowRight}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+  // RTL horizontal — ArrowLeft is "forward" (next), ArrowRight is "backward" (previous)
+  {
+    description: 'RTL Horizontal: Left Arrow moves to next tab',
+    dir: 'rtl',
+    orientation: 'horizontal',
+    defaultValue: 'tab1',
+    key: '{ArrowLeft}',
+    expectedTab: 'Tab 2',
+    expectedDeselected: ['Tab 1', 'Tab 3'],
+  },
+  {
+    description: 'RTL Horizontal: Right Arrow moves to previous tab',
+    dir: 'rtl',
+    orientation: 'horizontal',
+    defaultValue: 'tab2',
+    key: '{ArrowRight}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+  {
+    description: 'RTL Horizontal: Right Arrow wraps to last tab from first',
+    dir: 'rtl',
+    orientation: 'horizontal',
+    defaultValue: 'tab1',
+    key: '{ArrowRight}',
+    expectedTab: 'Tab 3',
+    expectedDeselected: ['Tab 1', 'Tab 2'],
+  },
+  {
+    description: 'RTL Horizontal: Left Arrow wraps to first tab from last',
+    dir: 'rtl',
+    orientation: 'horizontal',
+    defaultValue: 'tab3',
+    key: '{ArrowLeft}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+  // Vertical — unaffected by reading direction
+  {
+    description: 'Vertical: Down Arrow moves to next tab',
+    dir: 'ltr',
+    orientation: 'vertical',
+    defaultValue: 'tab1',
+    key: '{ArrowDown}',
+    expectedTab: 'Tab 2',
+    expectedDeselected: ['Tab 1', 'Tab 3'],
+  },
+  {
+    description: 'Vertical: Up Arrow moves to previous tab',
+    dir: 'ltr',
+    orientation: 'vertical',
+    defaultValue: 'tab2',
+    key: '{ArrowUp}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+  {
+    description: 'Vertical: Up Arrow wraps to last tab from first',
+    dir: 'ltr',
+    orientation: 'vertical',
+    defaultValue: 'tab1',
+    key: '{ArrowUp}',
+    expectedTab: 'Tab 3',
+    expectedDeselected: ['Tab 1', 'Tab 2'],
+  },
+  {
+    description: 'Vertical: Down Arrow wraps to first tab from last',
+    dir: 'ltr',
+    orientation: 'vertical',
+    defaultValue: 'tab3',
+    key: '{ArrowDown}',
+    expectedTab: 'Tab 1',
+    expectedDeselected: ['Tab 2', 'Tab 3'],
+  },
+] as const;
+
+export const mouseChangeEventCases = [
+  {
+    name: 'mouse click',
+    interact: async (tab: HTMLElement, user: ReturnType<typeof userEvent.setup>) => {
+      await user.click(tab);
+    },
+    getTab: () => screen.getByRole('tab', { name: 'Tab 2' }),
+    expected: { index: 1, name: 'tab2' },
+  },
+];
+
+export const keyboardChangeEventCases = [
+  {
+    name: 'keyboard navigation (ArrowRight)',
+    defaultValue: 'tab1',
+    interact: async (user: ReturnType<typeof userEvent.setup>) => {
+      await user.tab(); // focus first tab
+      await user.keyboard('{ArrowRight}');
+    },
+    getTab: () => screen.getByRole('tab', { name: 'Tab 2' }),
+    expected: { index: 1, name: 'tab2' },
+  },
+  {
+    name: 'keyboard navigation (Home)',
+    defaultValue: 'tab2', // Start on tab2 so Home changes to tab1
+    interact: async (user: ReturnType<typeof userEvent.setup>) => {
+      await user.tab();
+      await user.keyboard('{Home}');
+    },
+    getTab: () => screen.getByRole('tab', { name: 'Tab 1' }),
+    expected: { index: 0, name: 'tab1' },
+  },
+  {
+    name: 'keyboard navigation (End)',
+    defaultValue: 'tab1',
+    interact: async (user: ReturnType<typeof userEvent.setup>) => {
+      await user.tab();
+      await user.keyboard('{End}');
+    },
+    getTab: () => screen.getByRole('tab', { name: 'Tab 3' }),
+    expected: { index: 2, name: 'tab3' },
+  },
+];
+
+export const errorCases = [
+  {
+    name: 'controlled (value)',
+    rootProps: { value: 'nonexistent', onValueChange: vi.fn() },
+  },
+  {
+    name: 'uncontrolled (defaultValue)',
+    rootProps: { defaultValue: 'nonexistent' },
+  },
+];

package/src/Tabs/__tests__/Tabs.imperative-api.test.tsx

@@ -0,0 +1,118 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { createRef } from "react";
+
+import { Tabs, TabsImperativeApi } from "..";
+
+describe("Tabs Imperative API", () => {
+  it("should expose setActiveTab method via ref", () => {
+    // Arrange
+    const ref = createRef<TabsImperativeApi>();
+    render(
+      <Tabs.Root ref={ref} defaultValue="tab1">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        <Tabs.Content value="tab3">Content 3</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    // Assert
+    expect(typeof ref.current?.setActiveTab).toBe("function");
+  });
+
+  it("should update active tab when setActiveTab is called in uncontrolled mode", async () => {
+    // Arrange
+    const ref = createRef<TabsImperativeApi>();
+    render(
+      <Tabs.Root ref={ref} defaultValue="tab1">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        <Tabs.Content value="tab3">Content 3</Tabs.Content>
+      </Tabs.Root>,
+    );
+    const tab3 = screen.getByRole("tab", { name: "Tab 3" });
+
+    // Act
+    ref.current?.setActiveTab("tab3");
+
+    // Assert
+    await waitFor(() => expect(tab3).toHaveAttribute("aria-selected", "true"));
+  });
+
+  it("should call onValueChange when setActiveTab is called in controlled mode", () => {
+    // Arrange
+    const ref = createRef<TabsImperativeApi>();
+    const handleValueChange = vi.fn();
+    render(
+      <Tabs.Root ref={ref} value="tab1" onValueChange={handleValueChange}>
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        <Tabs.Content value="tab3">Content 3</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    // Act
+    ref.current?.setActiveTab("tab2");
+
+    // Assert
+    expect(handleValueChange).toHaveBeenCalledWith("tab2");
+  });
+
+  it("should validate index in setActiveTab in uncontrolled mode", () => {
+    // Arrange
+    const ref = createRef<TabsImperativeApi>();
+    render(
+      <Tabs.Root ref={ref} defaultValue="tab1">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        <Tabs.Content value="tab3">Content 3</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    // Act & Assert
+    expect(() => ref.current?.setActiveTab("tab99")).toThrow(
+      /Invalid tab value/i,
+    );
+  });
+
+  it("should validate index in setActiveTab in controlled mode", () => {
+    // Arrange
+    const ref = createRef<TabsImperativeApi>();
+    render(
+      <Tabs.Root ref={ref} value="tab1" onValueChange={vi.fn()}>
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        <Tabs.Content value="tab3">Content 3</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    // Act & Assert
+    expect(() => ref.current?.setActiveTab("tab99")).toThrow(
+      /Invalid tab value/i,
+    );
+  });
+});

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

@@ -0,0 +1,192 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { Tabs } from '..';
+
+import { arrowKeyCases } from './Tabs.fixtures';
+
+describe('Tabs keyboard navigation', () => {
+  describe('Tab key focus management', () => {
+    it('should focus the active tab when tabbing into the component', async () => {
+      // Arrange
+      const user = userEvent.setup();
+      render(
+        <Tabs.Root defaultValue="tab2">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+            <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+          <Tabs.Content value="tab3">Content 3</Tabs.Content>
+        </Tabs.Root>,
+      );
+
+      // Act
+      await user.tab();
+
+      // Assert
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      expect(tab2).toHaveFocus();
+    });
+
+  });
+
+  describe('Arrow key navigation', () => {
+    it.each(arrowKeyCases)(
+      '$description',
+      async ({ dir, orientation, defaultValue, key, expectedTab, expectedDeselected }) => {
+        // Arrange
+        const user = userEvent.setup();
+        render(
+          <Tabs.Root dir={dir} orientation={orientation} defaultValue={defaultValue}>
+            <Tabs.List label="Test tabs">
+              <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+              <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+              <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+            </Tabs.List>
+            <Tabs.Content value="tab1">Content 1</Tabs.Content>
+            <Tabs.Content value="tab2">Content 2</Tabs.Content>
+            <Tabs.Content value="tab3">Content 3</Tabs.Content>
+          </Tabs.Root>,
+        );
+
+        // Act
+        await user.tab();
+        await user.keyboard(key);
+
+        // Assert
+        const expectedTabEl = screen.getByRole('tab', { name: expectedTab });
+        expect(expectedTabEl).toHaveFocus();
+        expect(expectedTabEl).toHaveAttribute('aria-selected', 'true');
+        for (const deselected of expectedDeselected) {
+          const deselectedTabEl = screen.getByRole('tab', { name: deselected });
+          expect(deselectedTabEl).toHaveAttribute('aria-selected', 'false');
+        }
+      },
+    );
+  });
+
+  describe('Home and End key navigation', () => {
+    it('should move focus to and activate first tab when Home key is pressed', async () => {
+      // Arrange
+      const user = userEvent.setup();
+      render(
+        <Tabs.Root defaultValue="tab2">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+            <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+          <Tabs.Content value="tab3">Content 3</Tabs.Content>
+        </Tabs.Root>,
+      );
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+
+      // Act
+      await user.tab();
+      await user.keyboard('{Home}');
+
+      // Assert
+      expect(tab1).toHaveFocus();
+      expect(tab1).toHaveAttribute('aria-selected', 'true');
+      expect(tab2).toHaveAttribute('aria-selected', 'false');
+    });
+
+    it('should move focus to and activate last tab when End key is pressed', async () => {
+      // Arrange
+      const user = userEvent.setup();
+      render(
+        <Tabs.Root defaultValue="tab2">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+            <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+          <Tabs.Content value="tab3">Content 3</Tabs.Content>
+        </Tabs.Root>,
+      );
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      const tab3 = screen.getByRole('tab', { name: 'Tab 3' });
+
+      // Act
+      await user.tab();
+      await user.keyboard('{End}');
+
+      // Assert
+      expect(tab3).toHaveFocus();
+      expect(tab3).toHaveAttribute('aria-selected', 'true');
+      expect(tab2).toHaveAttribute('aria-selected', 'false');
+    });
+  });
+
+  describe('Disabled keyboard events', () => {
+    it('should ignore Up/Down arrow key events in horizontal mode', async () => {
+      // Arrange
+      const user = userEvent.setup();
+      render(
+        <Tabs.Root dir="ltr" defaultValue="tab2">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+            <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+          <Tabs.Content value="tab3">Content 3</Tabs.Content>
+        </Tabs.Root>,
+      );
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      const tab3 = screen.getByRole('tab', { name: 'Tab 3' });
+
+      // Act
+      await user.tab();
+      await user.keyboard('{ArrowUp}');
+      await user.keyboard('{ArrowDown}');
+
+      // Assert
+      expect(tab2).toHaveFocus();
+      expect(tab2).toHaveAttribute('aria-selected', 'true');
+      expect(tab1).toHaveAttribute('aria-selected', 'false');
+      expect(tab3).toHaveAttribute('aria-selected', 'false');
+    });
+
+    it('should ignore Left/Right arrow key events in vertical mode', async () => {
+      // Arrange
+      const user = userEvent.setup();
+      render(
+        <Tabs.Root dir="ltr" orientation="vertical" defaultValue="tab2">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+            <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+          <Tabs.Content value="tab3">Content 3</Tabs.Content>
+        </Tabs.Root>,
+      );
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      const tab3 = screen.getByRole('tab', { name: 'Tab 3' });
+
+      // Act
+      await user.tab();
+      await user.keyboard('{ArrowLeft}');
+      await user.keyboard('{ArrowRight}');
+
+      // Assert
+      expect(tab2).toHaveFocus();
+      expect(tab2).toHaveAttribute('aria-selected', 'true');
+      expect(tab1).toHaveAttribute('aria-selected', 'false');
+      expect(tab3).toHaveAttribute('aria-selected', 'false');
+    });
+  });
+});

package/src/Tabs/__tests__/Tabs.lazy-mount.test.tsx

@@ -0,0 +1,61 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Tabs } from "..";
+
+function renderTabs(lazyMount: boolean) {
+  return render(
+    <Tabs.Root defaultValue="tab1" lazyMount={lazyMount}>
+      <Tabs.List label="Test tabs">
+        <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+        <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+        <Tabs.Trigger value="tab3">Tab 3</Tabs.Trigger>
+      </Tabs.List>
+      <Tabs.Content value="tab1">Content 1</Tabs.Content>
+      <Tabs.Content value="tab2">Content 2</Tabs.Content>
+      <Tabs.Content value="tab3">Content 3</Tabs.Content>
+    </Tabs.Root>,
+  );
+}
+
+describe("Tabs lazyMount", () => {
+  it("should render inactive panel children on initial mount by default (no lazyMount)", () => {
+    renderTabs(false);
+
+    expect(screen.getByText("Content 2")).toBeInTheDocument();
+    expect(screen.getByText("Content 3")).toBeInTheDocument();
+  });
+
+  it("should not render inactive panel children on initial mount when lazyMount is true", () => {
+    renderTabs(true);
+
+    expect(screen.queryByText("Content 2")).not.toBeInTheDocument();
+    expect(screen.queryByText("Content 3")).not.toBeInTheDocument();
+  });
+
+  it("should render the default active panel children on mount even when lazyMount is true", () => {
+    renderTabs(true);
+
+    expect(screen.getByText("Content 1")).toBeInTheDocument();
+  });
+
+  it("should render a panel's children after its tab is first activated", async () => {
+    const user = userEvent.setup();
+    renderTabs(true);
+
+    await user.click(screen.getByRole("tab", { name: "Tab 2" }));
+
+    expect(screen.getByText("Content 2")).toBeInTheDocument();
+  });
+
+  it("should keep panel children mounted after switching away from a previously activated tab", async () => {
+    const user = userEvent.setup();
+    renderTabs(true);
+
+    await user.click(screen.getByRole("tab", { name: "Tab 2" }));
+    await user.click(screen.getByRole("tab", { name: "Tab 1" }));
+
+    // Tab 2's content stays in the DOM — lazy mount, not unmount-on-hide.
+    expect(screen.getByText("Content 2")).toBeInTheDocument();
+  });
+});