@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,569 @@
+import { render, screen } from "@testing-library/react";
+
+import { Carousel } from "..";
+
+describe("Carousel basic rendering tests", () => {
+  describe("Carousel.Root", () => {
+    it("should render the Carousel.Root component", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products" data-testid="carousel-root" />,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toBeVisible();
+    });
+
+    it('should apply aria-roledescription="carousel" so assistive tech announces the widget as a carousel', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products" data-testid="carousel-root" />,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toHaveAttribute("aria-roledescription", "carousel");
+    });
+
+    it("should expose the required ariaLabel prop as aria-label on the rendered element", () => {
+      const label = "Featured products";
+      render(<Carousel.Root ariaLabel={label} data-testid="carousel-root" />);
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toHaveAttribute("aria-label", label);
+    });
+
+    it("should accept ariaLabelledBy as an alternative to ariaLabel", () => {
+      const labelId = "carousel-heading";
+      render(
+        <>
+          <h2 id={labelId}>Featured products</h2>
+          <Carousel.Root ariaLabelledBy={labelId} data-testid="carousel-root" />
+        </>,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toHaveAttribute("aria-labelledby", labelId);
+    });
+
+    it("should render as a <section> element by default to match the WAI-ARIA carousel pattern", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products" data-testid="carousel-root" />,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot.tagName).toBe("SECTION");
+    });
+
+    it("should accept a className prop", () => {
+      const testClass = "custom-carousel-root";
+      render(
+        <Carousel.Root
+          ariaLabel="Featured products"
+          className={testClass}
+          data-testid="carousel-root"
+        />,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toHaveAttribute("class", testClass);
+    });
+
+    it("should apply a className of empty string by default when not specified", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products" data-testid="carousel-root" />,
+      );
+      const carouselRoot = screen.getByTestId("carousel-root");
+
+      expect(carouselRoot).toHaveAttribute("class", "");
+    });
+
+    it("should render children inside Carousel.Root", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <p>Carousel body</p>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByText("Carousel body")).toBeVisible();
+    });
+  });
+
+  describe("Carousel.Viewport", () => {
+    it("should render the Carousel.Viewport component inside Carousel.Root", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport data-testid="carousel-viewport" />
+        </Carousel.Root>,
+      );
+      const viewport = screen.getByTestId("carousel-viewport");
+
+      expect(viewport).toBeVisible();
+    });
+
+    it("should render children inside the viewport", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <p>Slide body</p>
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByText("Slide body")).toBeVisible();
+    });
+
+    it("should set a data-carousel-viewport attribute as a CSS-targeting hook for the recommended scroll-snap rules", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport data-testid="carousel-viewport" />
+        </Carousel.Root>,
+      );
+      const viewport = screen.getByTestId("carousel-viewport");
+
+      expect(viewport).toHaveAttribute("data-carousel-viewport", "");
+    });
+
+    it("should accept a className prop", () => {
+      const testClass = "custom-viewport";
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport
+            className={testClass}
+            data-testid="carousel-viewport"
+          />
+        </Carousel.Root>,
+      );
+      const viewport = screen.getByTestId("carousel-viewport");
+
+      expect(viewport).toHaveAttribute("class", testClass);
+    });
+
+    it("should apply a className of empty string by default when not specified", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport data-testid="carousel-viewport" />
+        </Carousel.Root>,
+      );
+      const viewport = screen.getByTestId("carousel-viewport");
+
+      expect(viewport).toHaveAttribute("class", "");
+    });
+
+    it("should render slides in source order without injecting extra DOM nodes", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport data-testid="carousel-viewport">
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+      const viewport = screen.getByTestId("carousel-viewport");
+
+      expect(viewport.querySelectorAll("[data-carousel-slide]")).toHaveLength(3);
+      expect(
+        viewport.querySelectorAll("[data-carousel-slide-clone]"),
+      ).toHaveLength(0);
+    });
+  });
+
+  describe("Carousel.Slide", () => {
+    it("should render the Carousel.Slide component inside the viewport", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toBeVisible();
+    });
+
+    it('should render with role="group" so assistive tech treats each slide as a discrete group', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute("role", "group");
+    });
+
+    it('should render with aria-roledescription="slide" per the WAI-ARIA Carousel pattern', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute(
+        "aria-roledescription",
+        "slide",
+      );
+    });
+
+    it("should set a data-carousel-slide attribute as a CSS-targeting hook", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute(
+        "data-carousel-slide",
+        "",
+      );
+    });
+
+    it("should render children inside the slide", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide>
+              <p>Slide content</p>
+            </Carousel.Slide>
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByText("Slide content")).toBeVisible();
+    });
+
+    it("should accept a className prop", () => {
+      const testClass = "custom-slide";
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide className={testClass} data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute("class", testClass);
+    });
+
+    it("should apply a className of empty string by default when not specified", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute("class", "");
+    });
+
+    it("should expose its zero-based registration position as data-index", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute("data-index", "0");
+      expect(screen.getByTestId("slide-1")).toHaveAttribute("data-index", "1");
+      expect(screen.getByTestId("slide-2")).toHaveAttribute("data-index", "2");
+    });
+
+    it("should expose the total registered slide count as data-total on every slide", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      ["slide-0", "slide-1", "slide-2"].forEach((id) => {
+        expect(screen.getByTestId(id)).toHaveAttribute("data-total", "3");
+      });
+    });
+
+    it("should update data-index and data-total when slides are unmounted", () => {
+      const { rerender } = render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      rerender(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute("data-index", "0");
+      expect(screen.getByTestId("slide-2")).toHaveAttribute("data-index", "1");
+      expect(screen.getByTestId("slide-0")).toHaveAttribute("data-total", "2");
+      expect(screen.getByTestId("slide-2")).toHaveAttribute("data-total", "2");
+    });
+  });
+
+  describe("Carousel.Slide data-state", () => {
+    it('should mark the slide at the active page with data-state="active" and the rest as "inactive"', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute(
+        "data-state",
+        "active",
+      );
+      expect(screen.getByTestId("slide-1")).toHaveAttribute(
+        "data-state",
+        "inactive",
+      );
+      expect(screen.getByTestId("slide-2")).toHaveAttribute(
+        "data-state",
+        "inactive",
+      );
+    });
+  });
+
+  describe("Carousel.NextTrigger", () => {
+    it("should render the Carousel.NextTrigger component inside Carousel.Root", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toBeVisible();
+    });
+
+    it('should render with type="button"', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toHaveAttribute(
+        "type",
+        "button",
+      );
+    });
+
+    it("should accept a className prop", () => {
+      const testClass = "custom-next";
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.NextTrigger className={testClass}>Next</Carousel.NextTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toHaveAttribute(
+        "class",
+        testClass,
+      );
+    });
+
+    it("should apply a className of empty string by default when not specified", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toHaveAttribute(
+        "class",
+        "",
+      );
+    });
+  });
+
+  describe("Carousel.PreviousTrigger", () => {
+    it("should render the Carousel.PreviousTrigger component inside Carousel.Root", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Previous" })).toBeVisible();
+    });
+
+    it('should render with type="button"', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Previous" })).toHaveAttribute(
+        "type",
+        "button",
+      );
+    });
+
+    it("should accept a className prop", () => {
+      const testClass = "custom-prev";
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.PreviousTrigger className={testClass}>
+            Previous
+          </Carousel.PreviousTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Previous" })).toHaveAttribute(
+        "class",
+        testClass,
+      );
+    });
+
+    it("should apply a className of empty string by default when not specified", () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByRole("button", { name: "Previous" })).toHaveAttribute(
+        "class",
+        "",
+      );
+    });
+  });
+
+  describe("Carousel.Slide aria-label", () => {
+    it('should auto-generate an aria-label of "N of M" using the slide\'s index and the live total', () => {
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute(
+        "aria-label",
+        "1 of 3",
+      );
+      expect(screen.getByTestId("slide-1")).toHaveAttribute(
+        "aria-label",
+        "2 of 3",
+      );
+      expect(screen.getByTestId("slide-2")).toHaveAttribute(
+        "aria-label",
+        "3 of 3",
+      );
+    });
+
+    it("should update the auto-generated aria-label when slides are added or removed at runtime", () => {
+      const { rerender } = render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      rerender(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute(
+        "aria-label",
+        "1 of 2",
+      );
+      expect(screen.getByTestId("slide-2")).toHaveAttribute(
+        "aria-label",
+        "2 of 2",
+      );
+    });
+
+    it("should let the consumer override the auto-generated aria-label via the ariaLabel prop", () => {
+      const customLabel = "Hand-picked for you";
+      render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide ariaLabel={customLabel} data-testid="slide" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide")).toHaveAttribute(
+        "aria-label",
+        customLabel,
+      );
+    });
+
+    it("should keep ariaLabel stable as siblings mount and unmount around it", () => {
+      const customLabel = "Hand-picked for you";
+      const { rerender } = render(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide ariaLabel={customLabel} data-testid="slide-1" />
+            <Carousel.Slide data-testid="slide-2" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      rerender(
+        <Carousel.Root ariaLabel="Featured products">
+          <Carousel.Viewport>
+            <Carousel.Slide ariaLabel={customLabel} data-testid="slide-1" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      expect(screen.getByTestId("slide-1")).toHaveAttribute(
+        "aria-label",
+        customLabel,
+      );
+    });
+  });
+
+  describe("context errors", () => {
+    it.each([
+      ["Carousel.Viewport", () => <Carousel.Viewport />],
+      ["Carousel.Slide", () => <Carousel.Slide />],
+      ["Carousel.NextTrigger", () => <Carousel.NextTrigger />],
+      ["Carousel.PreviousTrigger", () => <Carousel.PreviousTrigger />],
+    ] as const)(
+      "should throw an error when %s is used outside Carousel.Root",
+      (_, ComponentRenderer) => {
+        expect(() => {
+          render(ComponentRenderer());
+        }).toThrow("Component must be rendered as a child of Carousel.Root");
+      },
+    );
+  });
+});

package/src/Carousel/__tests__/Carousel.controlled-state.test.tsx

@@ -0,0 +1,137 @@
+import { useState } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Carousel } from "..";
+
+describe("Carousel controlled page state", () => {
+  it("should derive the active slide from the controlled page prop", () => {
+    render(
+      <Carousel.Root
+        ariaLabel="Featured products"
+        page={1}
+        onPageChange={() => {}}
+      >
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+          <Carousel.Slide data-testid="slide-2" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    expect(screen.getByTestId("slide-0")).toHaveAttribute(
+      "data-state",
+      "inactive",
+    );
+    expect(screen.getByTestId("slide-1")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+    expect(screen.getByTestId("slide-2")).toHaveAttribute(
+      "data-state",
+      "inactive",
+    );
+  });
+
+  it("should call onPageChange with page+1 when NextTrigger is clicked, without updating any internal state", async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    render(
+      <Carousel.Root
+        ariaLabel="Featured products"
+        page={0}
+        onPageChange={onPageChange}
+      >
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+        </Carousel.Viewport>
+        <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+      </Carousel.Root>,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+
+    expect(onPageChange).toHaveBeenCalledTimes(1);
+    expect(onPageChange).toHaveBeenCalledWith(1);
+    // Parent has not re-rendered with a new page prop, so the active
+    // slide must remain at the controlled value.
+    expect(screen.getByTestId("slide-0")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+    expect(screen.getByTestId("slide-1")).toHaveAttribute(
+      "data-state",
+      "inactive",
+    );
+  });
+
+  it("should call onPageChange with page-1 when PreviousTrigger is clicked", async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    render(
+      <Carousel.Root
+        ariaLabel="Featured products"
+        page={2}
+        onPageChange={onPageChange}
+      >
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+          <Carousel.Slide data-testid="slide-2" />
+        </Carousel.Viewport>
+        <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
+      </Carousel.Root>,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Previous" }));
+
+    expect(onPageChange).toHaveBeenCalledTimes(1);
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
+  it("should reflect the parent's controlled page across both trigger clicks and external state changes", async () => {
+    const user = userEvent.setup();
+    function Parent() {
+      const [page, setPage] = useState(0);
+      return (
+        <>
+          <button type="button" onClick={() => setPage(0)}>
+            Reset
+          </button>
+          <Carousel.Root
+            ariaLabel="Featured products"
+            page={page}
+            onPageChange={setPage}
+          >
+            <Carousel.Viewport>
+              <Carousel.Slide data-testid="slide-0" />
+              <Carousel.Slide data-testid="slide-1" />
+              <Carousel.Slide data-testid="slide-2" />
+            </Carousel.Viewport>
+            <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+          </Carousel.Root>
+        </>
+      );
+    }
+
+    render(<Parent />);
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(screen.getByTestId("slide-2")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+
+    // External (non-trigger) state change must be reflected too — proves the
+    // visual is driven by the controlled prop, not by an internal counter
+    // that advances independently of the parent.
+    await user.click(screen.getByRole("button", { name: "Reset" }));
+    expect(screen.getByTestId("slide-0")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+  });
+});