@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Carousel/__tests__/Carousel.instant-scroll.test.tsx

@@ -0,0 +1,124 @@
+import { createRef } from "react";
+import { act, render, screen } from "@testing-library/react";
+
+import { Carousel } from "../index.ts";
+import type { CarouselImperativeApi } from "../index.ts";
+
+describe("Carousel imperative API — per-call instant scroll override", () => {
+  it("should scroll with behavior='instant' when next(true) is called, even without prefers-reduced-motion", () => {
+    const ref = createRef<CarouselImperativeApi>();
+    render(
+      <Carousel.Root ref={ref} ariaLabel="Featured products">
+        <Carousel.Viewport data-testid="viewport">
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const scrollToSpy = vi.spyOn(screen.getByTestId("viewport"), "scrollTo");
+
+    act(() => {
+      ref.current!.next(true);
+    });
+
+    expect(scrollToSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ behavior: "instant" }),
+    );
+  });
+
+  it("should scroll with behavior='instant' when previous(true) is called", () => {
+    const ref = createRef<CarouselImperativeApi>();
+    render(
+      <Carousel.Root ref={ref} ariaLabel="Featured products" defaultPage={1}>
+        <Carousel.Viewport data-testid="viewport">
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const scrollToSpy = vi.spyOn(screen.getByTestId("viewport"), "scrollTo");
+
+    act(() => {
+      ref.current!.previous(true);
+    });
+
+    expect(scrollToSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ behavior: "instant" }),
+    );
+  });
+
+  it("should scroll with behavior='instant' when goTo(page, true) is called", () => {
+    const ref = createRef<CarouselImperativeApi>();
+    render(
+      <Carousel.Root ref={ref} ariaLabel="Featured products">
+        <Carousel.Viewport data-testid="viewport">
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const scrollToSpy = vi.spyOn(screen.getByTestId("viewport"), "scrollTo");
+
+    act(() => {
+      ref.current!.goTo(1, true);
+    });
+
+    expect(scrollToSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ behavior: "instant" }),
+    );
+  });
+
+  it("should only skip the animation for that one call, reverting to smooth for the next navigation", () => {
+    const ref = createRef<CarouselImperativeApi>();
+    render(
+      <Carousel.Root ref={ref} ariaLabel="Featured products">
+        <Carousel.Viewport data-testid="viewport">
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+          <Carousel.Slide data-testid="slide-2" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const scrollToSpy = vi.spyOn(screen.getByTestId("viewport"), "scrollTo");
+
+    act(() => {
+      ref.current!.next(true);
+    });
+    expect(scrollToSpy).toHaveBeenLastCalledWith(
+      expect.objectContaining({ behavior: "instant" }),
+    );
+
+    act(() => {
+      ref.current!.next();
+    });
+    expect(scrollToSpy).toHaveBeenLastCalledWith(
+      expect.objectContaining({ behavior: "smooth" }),
+    );
+  });
+
+  it("should default to the resolved smooth/reduced-motion behavior when no instant argument is passed", () => {
+    const ref = createRef<CarouselImperativeApi>();
+    render(
+      <Carousel.Root ref={ref} ariaLabel="Featured products">
+        <Carousel.Viewport data-testid="viewport">
+          <Carousel.Slide data-testid="slide-0" />
+          <Carousel.Slide data-testid="slide-1" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const scrollToSpy = vi.spyOn(screen.getByTestId("viewport"), "scrollTo");
+
+    act(() => {
+      ref.current!.next();
+    });
+
+    expect(scrollToSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ behavior: "smooth" }),
+    );
+  });
+});

package/src/Carousel/__tests__/Carousel.intersection-observer.test.tsx

@@ -209,7 +209,7 @@ describe("Carousel IntersectionObserver fallback + isInView", () => {
         ]);
       });
 
-      // The page stays put — scrollsnapchange owns it…
+      // The page stays put — scrollsnapchange owns it...
       expect(screen.getByTestId("slide-0")).toHaveAttribute(
         "data-state",
         "active",
@@ -218,7 +218,7 @@ describe("Carousel IntersectionObserver fallback + isInView", () => {
         "data-state",
         "inactive",
       );
-      // …but isInView still reflects what the observer reported.
+      // ...but isInView still reflects what the observer reported.
       expect(ref.current!.isInView(2)).toBe(true);
     } finally {
       delete (window as unknown as { onscrollsnapchange?: unknown })
@@ -273,4 +273,92 @@ describe("Carousel IntersectionObserver fallback + isInView", () => {
       "inactive",
     );
   });
+
+  it("should pass 0.6 as the default threshold to the IntersectionObserver", () => {
+    render(
+      <Carousel.Root ariaLabel="Featured products">
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    expect(MockIntersectionObserver.latest!.options?.threshold).toBe(0.6);
+  });
+
+  it("should use a custom inViewThreshold as the observer's threshold option and isInView cutoff", () => {
+    const ref = {
+      current: null,
+    } as unknown as RefObject<CarouselImperativeApi>;
+    render(
+      <Carousel.Root
+        ref={ref}
+        ariaLabel="Featured products"
+        inViewThreshold={0.3}
+      >
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const io = MockIntersectionObserver.latest!;
+    expect(io.options?.threshold).toBe(0.3);
+
+    // Below the default 0.6 but above the custom 0.3 — only in view under
+    // the custom threshold.
+    act(() => {
+      io.fire([
+        {
+          target: screen.getByTestId("slide-0"),
+          isIntersecting: true,
+          intersectionRatio: 0.4,
+        },
+      ]);
+    });
+
+    expect(ref.current!.isInView(0)).toBe(true);
+  });
+
+  it("should accept an array of thresholds, using the highest value as the isInView cutoff", () => {
+    const ref = {
+      current: null,
+    } as unknown as RefObject<CarouselImperativeApi>;
+    render(
+      <Carousel.Root
+        ref={ref}
+        ariaLabel="Featured products"
+        inViewThreshold={[0.2, 0.5, 0.8]}
+      >
+        <Carousel.Viewport>
+          <Carousel.Slide data-testid="slide-0" />
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    const io = MockIntersectionObserver.latest!;
+    expect(io.options?.threshold).toEqual([0.2, 0.5, 0.8]);
+
+    act(() => {
+      io.fire([
+        {
+          target: screen.getByTestId("slide-0"),
+          isIntersecting: true,
+          intersectionRatio: 0.6,
+        },
+      ]);
+    });
+    expect(ref.current!.isInView(0)).toBe(false);
+
+    act(() => {
+      io.fire([
+        {
+          target: screen.getByTestId("slide-0"),
+          isIntersecting: true,
+          intersectionRatio: 0.9,
+        },
+      ]);
+    });
+    expect(ref.current!.isInView(0)).toBe(true);
+  });
 });

package/src/Carousel/__tests__/Carousel.loop.test.tsx

@@ -0,0 +1,163 @@
+import { act, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Carousel } from "../index.ts";
+
+function renderWithSlides(
+  rootProps: {
+    loop?: boolean | "wrap" | "infinite";
+    defaultPage?: number;
+  } = {},
+  count = 3,
+) {
+  return render(
+    <Carousel.Root ariaLabel="Featured products" {...rootProps}>
+      <Carousel.Viewport>
+        {Array.from({ length: count }).map((_, i) => (
+          <Carousel.Slide key={i} data-testid={`slide-${i}`} />
+        ))}
+      </Carousel.Viewport>
+      <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
+      <Carousel.NextTrigger>Next</Carousel.NextTrigger>
+    </Carousel.Root>,
+  );
+}
+
+describe("Carousel loop (semantic wrap)", () => {
+  it('should resolve the bare loop flag to data-loop="wrap" on the Root', () => {
+    renderWithSlides({ loop: true });
+
+    expect(
+      screen.getByRole("region", { name: "Featured products" }),
+    ).toHaveAttribute("data-loop", "wrap");
+  });
+
+  it('should publish data-loop="none" on the Root when loop is left off', () => {
+    renderWithSlides();
+
+    expect(
+      screen.getByRole("region", { name: "Featured products" }),
+    ).toHaveAttribute("data-loop", "none");
+  });
+
+  it('should resolve loop="wrap" to data-loop="wrap"', () => {
+    renderWithSlides({ loop: "wrap" });
+
+    expect(
+      screen.getByRole("region", { name: "Featured products" }),
+    ).toHaveAttribute("data-loop", "wrap");
+  });
+
+  it('should resolve loop="infinite" to data-loop="infinite"', () => {
+    renderWithSlides({ loop: "infinite" });
+
+    expect(
+      screen.getByRole("region", { name: "Featured products" }),
+    ).toHaveAttribute("data-loop", "infinite");
+  });
+
+  it("should share the wrap page model with infinite — Next stays enabled and wraps on the last page", async () => {
+    const user = userEvent.setup();
+    const { container } = renderWithSlides({
+      loop: "infinite",
+      defaultPage: 2,
+    });
+
+    const next = screen.getByRole("button", { name: "Next" });
+    expect(next).not.toBeDisabled();
+
+    await user.click(next);
+
+    // Wrap and infinite share the same page model — Next on the last page sets
+    // the active page back to the first (the transform engine only changes how
+    // that page is presented, not the page state). Scope to the REAL slide (the
+    // clone strip copies data-testid but strips data-index).
+    const slide0 = container.querySelector('[data-testid="slide-0"][data-index]');
+    expect(slide0).toHaveAttribute("data-state", "active");
+  });
+
+  it("should keep Carousel.NextTrigger enabled on the last page when looping", () => {
+    renderWithSlides({ loop: true, defaultPage: 2 });
+
+    expect(screen.getByRole("button", { name: "Next" })).not.toBeDisabled();
+  });
+
+  it("should keep Carousel.PreviousTrigger enabled on the first page when looping", () => {
+    renderWithSlides({ loop: true });
+
+    expect(
+      screen.getByRole("button", { name: "Previous" }),
+    ).not.toBeDisabled();
+  });
+
+  it("should wrap Next from the last page back to the first when looping", async () => {
+    const user = userEvent.setup();
+    renderWithSlides({ loop: true, defaultPage: 2 });
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+
+    expect(screen.getByTestId("slide-0")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+    expect(screen.getByTestId("slide-2")).toHaveAttribute(
+      "data-state",
+      "inactive",
+    );
+  });
+
+  it("should wrap Previous from the first page back to the last when looping", async () => {
+    const user = userEvent.setup();
+    renderWithSlides({ loop: true });
+
+    await user.click(screen.getByRole("button", { name: "Previous" }));
+
+    expect(screen.getByTestId("slide-2")).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+    expect(screen.getByTestId("slide-0")).toHaveAttribute(
+      "data-state",
+      "inactive",
+    );
+  });
+
+  it("should still disable both triggers when only one page exists, even with loop", () => {
+    renderWithSlides({ loop: true }, 1);
+
+    expect(screen.getByRole("button", { name: "Previous" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Next" })).toBeDisabled();
+  });
+
+  it("should let autoplay wrap past the last page back to the first when looping", () => {
+    vi.useFakeTimers();
+    try {
+      render(
+        <Carousel.Root
+          ariaLabel="Featured products"
+          loop
+          autoplay
+          defaultPlaying
+          defaultPage={1}
+        >
+          <Carousel.Viewport>
+            <Carousel.Slide data-testid="slide-0" />
+            <Carousel.Slide data-testid="slide-1" />
+          </Carousel.Viewport>
+        </Carousel.Root>,
+      );
+
+      // Start on the last page; without loop autoplay would stop here.
+      act(() => {
+        vi.advanceTimersByTime(4000);
+      });
+
+      expect(screen.getByTestId("slide-0")).toHaveAttribute(
+        "data-state",
+        "active",
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/Carousel/__tests__/Carousel.loopEngine.test.ts

@@ -0,0 +1,77 @@
+import {
+  shortestStep,
+  snapTarget,
+  flingTarget,
+  normalizeOffset,
+} from "../loopEngine.ts";
+
+// Pure positioning math for the infinite transform loop (RFC 0018). No DOM —
+// these are the deterministic heart the interaction layer composes: which way to
+// wrap, where a drag settles, where a fling lands, and how to keep the track
+// offset bounded for seamless repositioning.
+
+describe("loopEngine.shortestStep", () => {
+  it("steps forward by one when the target is the next slide", () => {
+    expect(shortestStep(0, 1, 4)).toBe(1);
+  });
+
+  it("wraps forward the short way from the last slide to the first", () => {
+    // 3 → 0 around a ring of 4 is +1 forward, not −3 back (the rewind).
+    expect(shortestStep(3, 0, 4)).toBe(1);
+  });
+
+  it("wraps backward the short way from the first slide to the last", () => {
+    expect(shortestStep(0, 3, 4)).toBe(-1);
+  });
+
+  it("resolves an exact half-way tie forward", () => {
+    // 0 → 2 of 4 is equidistant either way; ties go forward (positive).
+    expect(shortestStep(0, 2, 4)).toBe(2);
+  });
+
+  it("takes the backward route when it is strictly shorter", () => {
+    // 0 → 3 of 5: forward 3 vs backward 2 → backward.
+    expect(shortestStep(0, 3, 5)).toBe(-2);
+  });
+
+  it("is a no-op for a non-positive count", () => {
+    expect(shortestStep(0, 1, 0)).toBe(0);
+  });
+});
+
+describe("loopEngine.snapTarget", () => {
+  it("rounds a continuous offset to the nearest slide boundary", () => {
+    expect(snapTarget(230, 100)).toBe(200);
+    expect(snapTarget(260, 100)).toBe(300);
+  });
+
+  it("returns 0 for a non-positive stride", () => {
+    expect(snapTarget(260, 0)).toBe(0);
+  });
+});
+
+describe("loopEngine.flingTarget", () => {
+  it("carries the offset by velocity × deceleration, then snaps to a boundary", () => {
+    // offset 100 + (2 px/ms × 60 ms) = 220 → nearest 100-boundary = 200.
+    expect(flingTarget(100, 2, 60, 100)).toBe(200);
+  });
+
+  it("projects backward for a negative velocity", () => {
+    // 300 + (−2 × 60) = 180 → nearest boundary 200.
+    expect(flingTarget(300, -2, 60, 100)).toBe(200);
+  });
+});
+
+describe("loopEngine.normalizeOffset", () => {
+  it("wraps an over-long offset back into [0, trackLength)", () => {
+    expect(normalizeOffset(450, 400)).toBe(50);
+  });
+
+  it("wraps a negative offset up into range", () => {
+    expect(normalizeOffset(-50, 400)).toBe(350);
+  });
+
+  it("returns 0 for a non-positive track length", () => {
+    expect(normalizeOffset(450, 0)).toBe(0);
+  });
+});