@primitiv-ui/react 0.1.33 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/react",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "Headless, accessible React components built on the WAI-ARIA authoring patterns. Zero styles ship with this package — bring your own (CSS, Tailwind, CSS-in-JS, design tokens).",
   "type": "module",
   "main": "./src/index.ts",

package/src/Carousel/README.md

@@ -1445,81 +1445,3 @@ So `scroll-snap-align: center`/`"end"` end up centering/ending the whole
 page, matching what the programmatic `scrollTo` already does. This is
 automatic and needs no consumer CSS; it's a no-op when `slidesPerPage` is
 1 (the leading slide already *is* the whole page).
-
-### Cover Flow (scroll-driven 3D)
-
-A "cover flow" — narrow snap units with cards that tilt away in 3D
-and stack with depth — can be built entirely in CSS, with no extra JS,
-using scroll-driven animations (`view-timeline` + `animation-timeline`).
-The full working source is the workbench example at
-`apps/workbench/src/pages/CarouselExample/examples/_coverFlow.scss`;
-this section documents the design so it can be reused or ported.
-
-**Structure.** Each slide is a narrow snap unit that owns the named
-timelines. Inside it, a card-sized `visual` box is centred over the
-snap unit (and overflows it so neighbours interleave) and handles the
-`translateX`; inside that, a `card` element handles the `rotateY`.
-Keep `perspective()` *inside* the keyframe transform — a `overflow-x`
-scroll container flattens a `perspective` CSS property, but the
-function form is immune.
-
-**Two timelines, one slide.** The rotate/translate run on a tight
-centred band (`view-timeline-inset` shrinks the scrollport) over
-`animation-range: contain`. The depth order runs on a *second*,
-full-scrollport timeline (`inset: 0`) over `animation-range: cover`.
-The wide range matters: `z-index` is an animatable integer, so a
-`1 → peak → 1` keyframe driven by each slide's own timeline makes the
-most-centred card win the stack generically — no per-slide numbers.
-A narrow range would clamp every off-centre slide to the boundary
-`z-index`, leaving DOM order to (incorrectly) break the ties on one
-side.
-
-**Customising.** Drive every dimension from a small set of custom
-properties on the root, and derive the rest with `calc()`:
-
-```css
-.cover-flow {
-  /* Geometry knobs */
-  --cf-viewport-w: 38rem;   /* visible carousel width                  */
-  --cf-card-w: 180px;       /* rendered card width                     */
-  --cf-aspect: 1.168;       /* width ÷ height — 1 = square, >1 = wide   */
-  --cf-snap: 90px;          /* centre-to-centre spacing (< card-w → overlap) */
-  --cf-track-pad: 0px;      /* grey track shown above/below the cards   */
-  --cf-radius: 10px;
-  /* Motion knobs */
-  --cf-spread: 1.4;         /* tilt band width, in multiples of --cf-snap */
-  --cf-tilt: 55deg;         /* max rotateY of the side cards            */
-  --cf-perspective: 500px;
-  --cf-shift: 30%;          /* translateX of the card toward centre     */
-  --cf-lift: 10;            /* peak z-index of the centred card         */
-
-  /* Derived — leave alone */
-  --cf-card-h: calc(var(--cf-card-w) / var(--cf-aspect));
-  --cf-viewport-h: calc(var(--cf-card-h) + var(--cf-track-pad) * 2);
-  --cf-center-pad: calc(50% - var(--cf-snap) / 2); /* centres first/last card */
-  --cf-band: calc(var(--cf-snap) * var(--cf-spread));
-}
-```
-
-With that in place the three common tweaks are one line each:
-
-- **Viewport size** — set `--cf-viewport-w`. The height follows the
-  cards automatically (`card-h + 2·track-pad`), so you rarely set it.
-- **Padding / spacing** — `--cf-track-pad` adds grey track above and
-  below the cards; `--cf-snap` is the centre-to-centre spacing — the
-  smaller it is relative to `--cf-card-w`, the more the cards overlap
-  (it also sets the centring gutter).
-- **Slide shape** — `--cf-aspect` is width ÷ height (`1` = exact
-  square, `>1` = landscape, `<1` = portrait); `--cf-card-w` is the
-  rendered size. A 240px square is `--cf-card-w: 240px; --cf-aspect: 1`.
-
-Two gotchas:
-
-- `--cf-aspect` must resolve to a *number*, not a fraction token.
-  `--cf-aspect: 16 / 9` lands inside `card-w / aspect` and divides
-  twice; use `--cf-aspect: calc(16 / 9)` (or a literal like `1.778`).
-- The whole recipe relies on `animation-timeline` and `calc()` length
-  division. Wrap it in `@supports (animation-timeline: --x)` and keep
-  a static `[data-state="active"] { z-index: var(--cf-lift) }` fallback
-  plus `@media (prefers-reduced-motion: reduce) { animation: none }` so
-  the carousel degrades to a plain scroll-snap row.

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

@@ -0,0 +1,28 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { Carousel } from "../Carousel.tsx";
+
+/**
+ * The Viewport chose its scroll behaviour by reading
+ * `window.matchMedia` in a `useMemo` — during render, so a server render
+ * (no `window`) threw `ReferenceError: window is not defined`. Guarded with a
+ * `typeof window` check, the primitive renders a static snapshot on the server.
+ */
+describe("Carousel SSR", () => {
+  it("should render to static markup when there is no window", () => {
+    expect(typeof window).toBe("undefined");
+
+    const markup = renderToStaticMarkup(
+      <Carousel.Root ariaLabel="Featured">
+        <Carousel.Viewport>
+          <Carousel.Slide>First</Carousel.Slide>
+          <Carousel.Slide>Second</Carousel.Slide>
+        </Carousel.Viewport>
+      </Carousel.Root>,
+    );
+
+    expect(markup).toContain("First");
+    expect(markup).toContain("Second");
+  });
+});

package/src/Carousel/hooks/useCarouselViewport.ts

@@ -319,8 +319,13 @@ export function useCarouselViewport() {
 
   // Read prefers-reduced-motion once on mount; choose scrollTo
   // behavior accordingly so we don't fight the OS-level setting.
+  // `useMemo` runs during render, so this must be SSR-safe: on the server
+  // there is no `window`, and reading it unguarded threw. Default to "smooth"
+  // there — the first client scroll re-reads it anyway (nothing scrolls on the
+  // server), so the resolved behaviour is never actually server-rendered.
   const scrollBehavior = useMemo<ScrollBehavior>(
     () =>
+      typeof window !== "undefined" &&
       window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
         ? "instant"
         : "smooth",

package/src/Carousel/types.ts

@@ -150,8 +150,8 @@ export type CarouselLoopMode = "none" | "wrap" | "infinite";
  * - `"center"` — scrolls so the first slide of the target page is
  *   **centred** in the Viewport. The target is offset inward by
  *   `(viewportWidth − slideWidth) / 2`. Use this with
- *   `scroll-snap-align: center` in consumer CSS (e.g. Cover Flow
- *   layouts where slides are narrower than the Viewport).
+ *   `scroll-snap-align: center` in consumer CSS (e.g. a peek
+ *   layout where slides are narrower than the Viewport).
  * - `"end"` — scrolls so the first slide of the target page's
  *   **trailing** edge aligns with the Viewport's trailing edge. The
  *   target is offset inward by the full `viewportWidth − slideWidth`.
@@ -373,7 +373,7 @@ export type CarouselRootProps = Omit<
     /** Scroll-snap alignment the Viewport targets when programmatically
      * scrolling to a page — see {@link CarouselSnapAlign}.
      * Defaults to `"start"`. Set to `"center"` when consumer CSS uses
-     * `scroll-snap-align: center` on slides (e.g. Cover Flow layouts
+     * `scroll-snap-align: center` on slides (e.g. a peek layout
      * where slides are narrower than the Viewport). */
     snapAlign?: CarouselSnapAlign;
     /** Axis the carousel scrolls and paginates along — see