@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Carousel/hooks/useCarouselRoot.ts

@@ -12,10 +12,16 @@ import {
 
 import type {
   CarouselAutoplay,
+  CarouselAutoplayStatus,
   CarouselContextValue,
+  CarouselDragStatus,
   CarouselIds,
   CarouselImperativeApi,
+  CarouselLoopMode,
+  CarouselOrientation,
+  CarouselOverscrollStatus,
   CarouselSnapAlign,
+  CarouselSnapType,
   CarouselTransition,
   CarouselTranslations,
 } from "../types";
@@ -29,8 +35,20 @@ const DEFAULT_TRANSLATIONS: Required<CarouselTranslations> = {
   indicatorLabel: ({ index }) => `Slide ${index}`,
   startSlideshow: "Start automatic slide show",
   stopSlideshow: "Stop automatic slide show",
+  progressText: ({ page, totalPages }) => `${page + 1} of ${totalPages}`,
 };
 
+/**
+ * Coerce a consumer-supplied layout count to a safe integer ≥ `min`. The
+ * slide count and `slidesPerPage` / `slidesPerMove` come from the consumer,
+ * so 0, negative, fractional, or non-finite values must degrade to a sane
+ * integer — otherwise the page maths divides by zero (Infinity pages → a
+ * thrown RangeError from the indicator map) or the carousel goes inert.
+ */
+function clampCount(n: number, min: number): number {
+  return Number.isFinite(n) ? Math.max(min, Math.floor(n)) : min;
+}
+
 function resolveAutoplay(autoplay: CarouselAutoplay | undefined): {
   enabled: boolean;
   delay: number;
@@ -61,6 +79,9 @@ type UseCarouselRootProps = {
   onPlayingChange?: (playing: boolean) => void;
   /** Autoplay configuration — see {@link CarouselAutoplay}. */
   autoplay?: CarouselAutoplay;
+  /** Fires on every autoplay status transition — see
+   * {@link CarouselAutoplayStatus}. */
+  onAutoplayStatusChange?: (status: CarouselAutoplayStatus) => void;
   /** Number of slides visible per page. Defaults to `1`. */
   slidesPerPage?: number;
   /** Slides advanced per Prev/Next click — `"auto"` (default) is
@@ -76,6 +97,26 @@ type UseCarouselRootProps = {
   transition?: CarouselTransition;
   /** Scroll-snap alignment — see {@link CarouselSnapAlign}. */
   snapAlign?: CarouselSnapAlign;
+  /** Scroll/pagination axis — see {@link CarouselOrientation}. */
+  orientation?: CarouselOrientation;
+  /** Wrap navigation around the ends instead of clamping — `boolean` for
+   * ergonomics (`true` = `"wrap"`) or a named mode. Defaults to `false`. */
+  loop?: boolean | "wrap" | "infinite";
+  /** Opt-in mouse click-and-drag scrolling. */
+  allowMouseDrag?: boolean;
+  /** Fires on every mouse-drag status transition — see
+   * {@link CarouselDragStatus}. */
+  onDragStatusChange?: (status: CarouselDragStatus) => void;
+  /** Fires whenever the keyboard, wheel, or a mouse drag pushes against a
+   * boundary with nowhere further to go — see
+   * {@link CarouselOverscrollStatus}. */
+  onOverscrollStatusChange?: (status: CarouselOverscrollStatus) => void;
+  /** IntersectionObserver visibility threshold(s) for the `isInView`
+   * fallback. Defaults to `0.6`. */
+  inViewThreshold?: number | number[];
+  /** `scroll-snap-type` strictness — see {@link CarouselSnapType}.
+   * Defaults to `"mandatory"`. */
+  snapType?: CarouselSnapType;
 };
 
 /**
@@ -111,12 +152,20 @@ export function useCarouselRoot(
     playing,
     onPlayingChange,
     autoplay,
+    onAutoplayStatusChange,
     slidesPerPage = 1,
     slidesPerMove = "auto",
     translations,
     ids = EMPTY_IDS,
     transition = "slide",
-    snapAlign = "start",
+    snapAlign = "center",
+    orientation = "horizontal",
+    loop = false,
+    allowMouseDrag = false,
+    onDragStatusChange,
+    onOverscrollStatusChange,
+    inViewThreshold = 0.6,
+    snapType = "mandatory",
   }: UseCarouselRootProps = {},
   imperativeRef?: Ref<CarouselImperativeApi>,
 ) {
@@ -128,21 +177,41 @@ export function useCarouselRoot(
   const isControlled = page !== undefined;
   const rawPage = isControlled ? (page as number) : internalPage;
   const total = slideKeys.length;
+  // Resolve the ergonomic boolean/named `loop` prop to a single mode.
+  // `true` is sugar for `"wrap"`; `false`/omitted is `"none"`. `"wrap"` and
+  // `"infinite"` share the page model below (`looping`), differing only in
+  // the scroll/clone layer the styled surface keys off `data-loop`.
+  const loopMode: CarouselLoopMode =
+    loop === true ? "wrap" : loop === false ? "none" : loop;
+  const looping = loopMode !== "none";
+  // Guard the layout counts (see clampCount). perPage is an integer ≥ 1; a
+  // numeric slidesPerMove is additionally clamped to ≤ perPage so a move can
+  // never skip past a page and orphan the slides in the gap. "auto" moves a
+  // full page.
+  const perPage = clampCount(slidesPerPage, 1);
+  // Slides advanced per page step: a full page in "auto" mode, else the numeric
+  // move clamped to ≤ perPage so a move can never skip past a page and orphan
+  // the slides in the gap.
   const effectiveSlidesPerMove =
-    slidesPerMove === "auto" ? slidesPerPage : slidesPerMove;
-  // "auto" mode keeps the existing ceil(total / slidesPerPage) formula
-  // and accepts a partial last page; numeric mode uses
-  // floor((total - slidesPerPage) / slidesPerMove) + 1 so the active
-  // window is always full. Math.ceil(0 / N) === 0 so the empty-slide
-  // case still gives totalPages === 0.
+    slidesPerMove === "auto"
+      ? perPage
+      : Math.min(perPage, clampCount(slidesPerMove, 1));
+  // Pages step by `effectiveSlidesPerMove` from 0, and the **last page always
+  // end-aligns** to `maxOffset` (the track end minus a full page). This is the
+  // single offset model for both modes: it guarantees every page is a full
+  // window that can start-snap cleanly, so a total that isn't a whole number of
+  // pages can't leave a partial last page whose leading slide can't reach the
+  // viewport start (which desyncs the active page against the scroll). The
+  // formula is identical to `ceil(total / perPage)` when the step is a full
+  // page, so the page *count* is unchanged — only the last page's offset shifts
+  // back to keep its window full.
+  const maxOffset = Math.max(0, total - perPage);
   const totalPages =
     total === 0
       ? 0
-      : total <= slidesPerPage
+      : total <= perPage
         ? 1
-        : slidesPerMove === "auto"
-          ? Math.ceil(total / slidesPerPage)
-          : Math.floor((total - slidesPerPage) / effectiveSlidesPerMove) + 1;
+        : Math.ceil(maxOffset / effectiveSlidesPerMove) + 1;
 
   // In controlled mode an out-of-range page prop is a consumer error —
   // throw loudly so it surfaces during development rather than shipping
@@ -161,6 +230,36 @@ export function useCarouselRoot(
       ? Math.max(0, Math.min(rawPage, totalPages - 1))
       : rawPage;
 
+  // Start slide index of the active window: step by move, but the last page
+  // end-aligns (clamped to maxOffset) so its window is always full.
+  const currentPageOffset = Math.min(
+    currentPage * effectiveSlidesPerMove,
+    maxOffset,
+  );
+
+  // Inverse of the offset model: which page does a leading slide index belong
+  // to? Because the last page end-aligns, the offsets aren't a clean multiple
+  // series (the final step is short), so round/floor can't invert them — pick
+  // the page whose start offset is nearest the slide. Ties favour the earlier
+  // page (`<`). Returns 0 for the empty carousel (the loop runs zero times) —
+  // pageForSlideIndex is only called once slides exist anyway.
+  const pageForSlideIndex = useCallback(
+    (slideIndex: number) => {
+      let best = 0;
+      let bestDistance = Infinity;
+      for (let page = 0; page < totalPages; page++) {
+        const offset = Math.min(page * effectiveSlidesPerMove, maxOffset);
+        const distance = Math.abs(offset - slideIndex);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          best = page;
+        }
+      }
+      return best;
+    },
+    [effectiveSlidesPerMove, maxOffset, totalPages],
+  );
+
   const [internalPlaying, setInternalPlaying] = useState(defaultPlaying);
   const isPlayingControlled = playing !== undefined;
   const currentPlaying = isPlayingControlled ? playing : internalPlaying;
@@ -189,11 +288,17 @@ export function useCarouselRoot(
   const suspended =
     (hovered || focused || touchActive) && !userInitiatedPlayRef.current;
 
-  // Boundary derivation: navigation requires at least one page. The
-  // ends clamp at the last page (which, with slidesPerPage > 1, is
-  // generally before the last slide).
-  const canGoPrevious = totalPages > 0 && currentPage > 0;
-  const canGoNext = totalPages > 0 && currentPage < totalPages - 1;
+  // Boundary derivation: navigation requires at least one page. Without
+  // loop the ends clamp at the last page (which, with slidesPerPage > 1,
+  // is generally before the last slide). With loop, navigation wraps, so
+  // both directions stay available as long as there's more than one page
+  // to wrap between — a single page has no wrap target.
+  const canGoPrevious = looping
+    ? totalPages > 1
+    : totalPages > 0 && currentPage > 0;
+  const canGoNext = looping
+    ? totalPages > 1
+    : totalPages > 0 && currentPage < totalPages - 1;
 
   const registerSlide = useCallback(
     (key: string, element: HTMLDivElement | null) => {
@@ -214,30 +319,69 @@ export function useCarouselRoot(
   // once the imperative API or autoplay land; they're added then.
   const isProgrammaticScrollRef = useRef(false);
 
-  const next = useCallback(() => {
-    if (currentPage >= totalPages - 1) return;
-    isProgrammaticScrollRef.current = true;
-    const target = currentPage + 1;
-    if (isControlled) {
-      onPageChange?.(target);
-    } else {
-      setInternalPage(target);
-    }
-  }, [currentPage, totalPages, isControlled, onPageChange]);
-
-  const previous = useCallback(() => {
-    if (currentPage <= 0) return;
-    isProgrammaticScrollRef.current = true;
-    const target = currentPage - 1;
-    if (isControlled) {
-      onPageChange?.(target);
-    } else {
-      setInternalPage(target);
-    }
-  }, [currentPage, isControlled, onPageChange]);
+  // One-shot override for the resolved smooth/reduced-motion scrollBehavior,
+  // consumed by the Viewport hook's scroll effect on the very next run and
+  // reset immediately after (see useCarouselViewport.ts) — so it never
+  // outlives the single call that requested it.
+  const instantScrollRef = useRef(false);
+
+  // One-shot hint for the infinite-loop engine (useCarouselLoop), consumed and
+  // reset the same way as instantScrollRef above. `next()`/`previous()` are a
+  // relative step, so under looping they should always take the wrap
+  // shortcut — continuing forward off the last slide onto the clone, not
+  // rewinding across the whole strip. `goTo()` (and `scrollToIndex`, which
+  // calls it) is an absolute jump to a *specific* page, most visibly from an
+  // indicator/thumbnail click — there, the wrap shortcut reads wrong: picking
+  // the last thumbnail from the first should visibly travel forward through
+  // every slide in between, matching the indicators' own left-to-right
+  // reading order, not silently take the one-step-back route around the ring
+  // just because it happens to be shorter. See RFC 0018 (loop navigation).
+  const directJumpRef = useRef(false);
+
+  const next = useCallback(
+    (instant?: boolean) => {
+      // At the last page: clamp (no-op) normally, or wrap to the first when
+      // looping (provided there's more than one page to wrap between).
+      if (currentPage >= totalPages - 1 && !(looping && totalPages > 1)) return;
+      isProgrammaticScrollRef.current = true;
+      instantScrollRef.current = !!instant;
+      directJumpRef.current = false;
+      const target = looping
+        ? (currentPage + 1) % totalPages
+        : currentPage + 1;
+      if (isControlled) {
+        onPageChange?.(target);
+      } else {
+        setInternalPage(target);
+      }
+    },
+    [currentPage, totalPages, looping, isControlled, onPageChange],
+  );
+
+  const previous = useCallback(
+    (instant?: boolean) => {
+      // At the first page: clamp (no-op) normally, or wrap to the last when
+      // looping (provided there's more than one page to wrap between).
+      if (currentPage <= 0 && !(looping && totalPages > 1)) return;
+      isProgrammaticScrollRef.current = true;
+      instantScrollRef.current = !!instant;
+      directJumpRef.current = false;
+      const target = looping
+        ? (currentPage - 1 + totalPages) % totalPages
+        : currentPage - 1;
+      if (isControlled) {
+        onPageChange?.(target);
+      } else {
+        setInternalPage(target);
+      }
+    },
+    [currentPage, totalPages, looping, isControlled, onPageChange],
+  );
 
   const goTo = useCallback(
-    (target: number) => {
+    (target: number, instant?: boolean) => {
+      instantScrollRef.current = !!instant;
+      directJumpRef.current = true;
       if (isControlled) {
         onPageChange?.(target);
       } else {
@@ -247,17 +391,59 @@ export function useCarouselRoot(
     [isControlled, onPageChange],
   );
 
+  // Slide-granularity counterpart to page-granularity goTo — maps the
+  // target slide index to its containing page via pageForSlideIndex (a
+  // multi-slide page's interior slides aren't independently reachable,
+  // so this always lands on the page start closest to slideIndex) and
+  // defers to the same goTo the trigger components use. Matches Ark UI's
+  // scrollToIndex(index, instant?).
+  const scrollToIndex = useCallback(
+    (slideIndex: number, instant?: boolean) => {
+      goTo(pageForSlideIndex(slideIndex), instant);
+    },
+    [goTo, pageForSlideIndex],
+  );
+
   // Autoplay timer. Schedules a single setTimeout per active page; when
   // next() runs it bumps currentPage, which retriggers the effect with
   // a fresh timer. canGoNext gates the schedule so autoplay stops at
   // the last page.
   // The suspended flag pauses the timer while the user is hovering or
   // has focus inside the Root, per WCAG 2.2.2.
+  // isAutoplayRunningRef edge-triggers onAutoplayStatusChange's
+  // "autoplay.start"/"autoplay.stop" pair around a running session — the
+  // effect reruns on every page change (autoplayRunning stays true, so no
+  // duplicate "start"), and "autoplay" fires once per tick from inside the
+  // scheduled callback, right before next() advances the page.
+  const isAutoplayRunningRef = useRef(false);
   useEffect(() => {
-    if (!autoplayEnabled || !currentPlaying || !canGoNext || suspended) {
+    const eligible =
+      autoplayEnabled && currentPlaying && canGoNext && !suspended;
+    if (!eligible) {
+      if (isAutoplayRunningRef.current) {
+        isAutoplayRunningRef.current = false;
+        onAutoplayStatusChange?.({
+          type: "autoplay.stop",
+          page: currentPage,
+          isPlaying: false,
+        });
+      }
       return;
     }
+    if (!isAutoplayRunningRef.current) {
+      isAutoplayRunningRef.current = true;
+      onAutoplayStatusChange?.({
+        type: "autoplay.start",
+        page: currentPage,
+        isPlaying: true,
+      });
+    }
     const id = setTimeout(() => {
+      onAutoplayStatusChange?.({
+        type: "autoplay",
+        page: currentPage,
+        isPlaying: true,
+      });
       next();
     }, autoplayDelay);
     return () => clearTimeout(id);
@@ -268,6 +454,8 @@ export function useCarouselRoot(
     suspended,
     autoplayDelay,
     next,
+    currentPage,
+    onAutoplayStatusChange,
   ]);
 
   // Handlers spread onto the Root <section>. mouseEnter / mouseLeave
@@ -348,6 +536,18 @@ export function useCarouselRoot(
     [currentPage, totalPages],
   );
 
+  // The same offset formula `currentPageOffset` uses for the active page,
+  // computed for every page — the leading slide index each page snaps to.
+  // Exposed so a consumer can build a custom progress bar / indicator from
+  // the raw offsets instead of re-deriving the end-align math themselves.
+  const getPageSnapPoints = useCallback(
+    () =>
+      Array.from({ length: totalPages }, (_, page) =>
+        Math.min(page * effectiveSlidesPerMove, maxOffset),
+      ),
+    [totalPages, effectiveSlidesPerMove, maxOffset],
+  );
+
   // Visibility tracking is a ref (not state) because callers read on
   // demand via isInView() and the IO callback in useCarouselViewport
   // mutates many entries per tick — re-rendering on each addition
@@ -362,19 +562,83 @@ export function useCarouselRoot(
     [],
   );
 
+  // Same ref-not-state reasoning as visibility tracking above: isDragging()
+  // is read on demand, and the Viewport hook's pointermove handler would
+  // otherwise re-render on every tick of a drag for no benefit (the DOM
+  // data-dragging hook already handles the visual).
+  const isDraggingRef = useRef(false);
+  const setDragging = useCallback((value: boolean) => {
+    isDraggingRef.current = value;
+  }, []);
+  const isDragging = useCallback(() => isDraggingRef.current, []);
+
+  // Same ref-not-state reasoning again: isOverscrolling() is read on
+  // demand, and set/cleared from inside the Viewport hook's pointermove
+  // handler on every tick of a drag-overscroll (the data-overscroll DOM
+  // hook already handles the visual).
+  const isOverscrollingRef = useRef(false);
+  const setOverscrolling = useCallback((value: boolean) => {
+    isOverscrollingRef.current = value;
+  }, []);
+  const isOverscrolling = useCallback(() => isOverscrollingRef.current, []);
+
+  // Same ref-not-state reasoning again: getScrollProgress()/
+  // getSlideProgress() are read on demand, and the Viewport hook's
+  // scroll/resize recompute would otherwise re-render on every tick for
+  // no benefit (the --carousel-progress/--slide-progress CSS custom
+  // properties already handle the visual).
+  const scrollProgressRef = useRef(0);
+  const setScrollProgress = useCallback((value: number) => {
+    scrollProgressRef.current = value;
+  }, []);
+  const getScrollProgress = useCallback(() => scrollProgressRef.current, []);
+
+  const slideProgressRef = useRef<Map<number, number>>(new Map());
+  const setSlideProgress = useCallback(
+    (slideIndex: number, value: number) => {
+      slideProgressRef.current.set(slideIndex, value);
+    },
+    [],
+  );
+  const getSlideProgress = useCallback(
+    (slideIndex: number) => slideProgressRef.current.get(slideIndex) ?? 0,
+    [],
+  );
+
   useImperativeHandle(
     imperativeRef,
     () => ({
       next,
       previous,
       goTo,
+      scrollToIndex,
       play,
       pause,
       refresh,
       getProgress,
       isInView,
+      getPageSnapPoints,
+      isDragging,
+      isOverscrolling,
+      getScrollProgress,
+      getSlideProgress,
     }),
-    [next, previous, goTo, play, pause, refresh, getProgress, isInView],
+    [
+      next,
+      previous,
+      goTo,
+      scrollToIndex,
+      play,
+      pause,
+      refresh,
+      getProgress,
+      isInView,
+      getPageSnapPoints,
+      isDragging,
+      isOverscrolling,
+      getScrollProgress,
+      getSlideProgress,
+    ],
   );
 
   // Reset the user-initiated flag when the playing session ends, so a
@@ -398,8 +662,11 @@ export function useCarouselRoot(
       registerSlide,
       slidesRef,
       slideKeys,
-      slidesPerPage,
+      slidesPerPage: perPage,
       effectiveSlidesPerMove,
+      maxOffset,
+      currentPageOffset,
+      pageForSlideIndex,
       totalPages,
       currentPage,
       canGoNext,
@@ -415,17 +682,35 @@ export function useCarouselRoot(
       ids,
       transition,
       snapAlign,
+      orientation,
+      loop: loopMode,
+      allowMouseDrag,
+      onDragStatusChange,
+      onOverscrollStatusChange,
+      inViewThreshold,
+      snapType,
       refreshTick,
       visibleSlideIndicesRef,
       setSlideInView,
       isProgrammaticScrollRef,
+      instantScrollRef,
+      directJumpRef,
+      isDraggingRef,
+      setDragging,
+      isOverscrollingRef,
+      setOverscrolling,
+      setScrollProgress,
+      setSlideProgress,
     }),
     [
       registerSlide,
       slidesRef,
       slideKeys,
-      slidesPerPage,
+      perPage,
       effectiveSlidesPerMove,
+      maxOffset,
+      currentPageOffset,
+      pageForSlideIndex,
       totalPages,
       currentPage,
       canGoNext,
@@ -441,8 +726,19 @@ export function useCarouselRoot(
       ids,
       transition,
       snapAlign,
+      orientation,
+      loopMode,
+      allowMouseDrag,
+      onDragStatusChange,
+      onOverscrollStatusChange,
+      inViewThreshold,
+      snapType,
       refreshTick,
       setSlideInView,
+      setDragging,
+      setOverscrolling,
+      setScrollProgress,
+      setSlideProgress,
     ],
   );
 

package/src/Carousel/hooks/useCarouselSlide.ts

@@ -1,5 +1,6 @@
 import { useCallback, useId } from "react";
 
+import type { CarouselSnapAlign } from "../types";
 import { useCarouselContext } from "./useCarouselContext";
 
 /**
@@ -12,14 +13,20 @@ import { useCarouselContext } from "./useCarouselContext";
  * a callback ref (rather than `useEffect`) keeps DOM-attachment and
  * registration in lockstep, which matters when slides mount or unmount
  * during a render pass driven by an external state change.
+ *
+ * `snapAlignOverride` is the slide's own `Carousel.Slide.snapAlign` prop
+ * (if set) — it wins over the root's resolved `snapAlign` for this one
+ * slide, but only when the slide is actually a valid snap-start position;
+ * see the `snapAlign` field below.
  */
-export function useCarouselSlide() {
+export function useCarouselSlide(snapAlignOverride?: CarouselSnapAlign) {
   const {
     registerSlide,
     slideKeys,
     slidesPerPage,
+    currentPageOffset,
     effectiveSlidesPerMove,
-    currentPage,
+    snapAlign: rootSnapAlign,
   } = useCarouselContext();
   const slideKey = useId();
 
@@ -32,14 +39,42 @@ export function useCarouselSlide() {
 
   const index = slideKeys.indexOf(slideKey);
   const total = slideKeys.length;
-  // The active "page" covers a window of slidesPerPage slides starting
-  // at pageOffset = currentPage * effectiveSlidesPerMove. With
-  // slidesPerMove="auto" this collapses to non-overlapping page-sized
-  // groups; with a numeric slidesPerMove the windows overlap.
-  const pageOffset = currentPage * effectiveSlidesPerMove;
+  // The active page covers a window of slidesPerPage slides starting at
+  // currentPageOffset (computed by the Root — non-overlapping page groups
+  // in "auto" mode, overlapping/end-aligned windows with a numeric
+  // slidesPerMove).
   const isActive =
-    index >= 0 && index >= pageOffset && index < pageOffset + slidesPerPage;
+    index >= 0 &&
+    index >= currentPageOffset &&
+    index < currentPageOffset + slidesPerPage;
   const state: "active" | "inactive" = isActive ? "active" : "inactive";
 
-  return { slideRef, index, total, state };
+  // Only a page's *leading* slide is a valid scroll-snap resting position.
+  // The Root's page offsets are `min(page * effectiveSlidesPerMove,
+  // maxOffset)` for each page — the same set an interior slide (any other
+  // index) is never a member of. Letting every slide snap (the old,
+  // unconditional CSS default) lets the browser rest scroll on an interior
+  // slide when slidesPerPage > 1, which has no valid page mapping: the
+  // viewport shows a straddled mix of two pages while currentPage/the
+  // indicators still claim one clean page is active. Mirrors the identical
+  // offset formula pageForSlideIndex inverts, so the two always agree.
+  const maxOffset = Math.max(0, total - slidesPerPage);
+  const isSnapStart =
+    index >= 0 &&
+    (index === maxOffset ||
+      (index <= maxOffset && index % effectiveSlidesPerMove === 0));
+  // The *value* mirrors the resolved root snapAlign (or this slide's own
+  // override, if set), not just a fixed "start" — so the native scroll-snap
+  // resting position agrees with where the programmatic scroll (Viewport's
+  // centerOffset maths, which reads this same value off the DOM) actually
+  // targets. Previously this was hardcoded to "start" regardless of
+  // snapAlign, so a user's own swipe/wheel/drag would snap back to the
+  // slide's leading edge even under snapAlign="center". Gated on
+  // isSnapStart either way — an interior slide of a multi-slide page must
+  // never snap, even if it carries its own snapAlign override.
+  const snapAlign = isSnapStart
+    ? (snapAlignOverride ?? rootSnapAlign)
+    : undefined;
+
+  return { slideRef, index, total, state, snapAlign };
 }