@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Carousel/hooks/useCarouselViewport.js

@@ -0,0 +1,786 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, } from "react";
+import { useCarouselContext } from "./useCarouselContext.js";
+// A pointer movement below this many pixels (along the scroll axis) is
+// still a click, not a drag — so a link/button inside a slide keeps
+// working under the pointer that just tapped it.
+const DRAG_THRESHOLD_PX = 3;
+// Amplifies the pointer delta applied to scrollLeft/scrollTop during a
+// drag. A slide can be many hundreds of pixels wide, and a literal 1:1
+// ratio means dragging the slide's full width to move through it once —
+// far more physical movement than the gesture should cost. 2x means a
+// drag needs to cover only half the on-screen distance to produce the
+// same scroll, without introducing momentum (the multiplier only scales
+// the *tracked* delta; there's still no motion after release).
+const DRAG_SENSITIVITY = 2;
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Owns the Viewport-side scroll-state sync — bidirectional.
+ *
+ * **State → scroll.** When `currentPage` flips for any reason
+ * (NextTrigger, Indicator click, autoplay tick, imperative goTo), the
+ * effect locates the first slide of the target page via the published
+ * `slidesRef`, reads its `getBoundingClientRect` relative to the
+ * viewport, and calls `scrollTo` so the visual surface tracks React
+ * state. The current `scrollLeft` is included in the target so the
+ * calculation is correct mid-scroll. The run also asserts
+ * `isProgrammaticScrollRef` so the IntersectionObserver fallback
+ * doesn't treat the in-flight animation as a user scroll and undo the
+ * page change; the flag clears on `scrollend` (with a timeout
+ * fallback for environments that don't fire it).
+ *
+ * **Scroll → state.** When the user swipes the viewport, the browser
+ * fires `scrollsnapchange` with the new snap target. The handler
+ * looks up which slide that target is, computes
+ * `floor(slideIndex / slidesPerPage)`, and calls `goTo` on the new
+ * page (skipping when the page is unchanged so consumers don't see
+ * spurious onPageChange callbacks, and bailing when the snap target
+ * isn't one of our registered slides). An `IntersectionObserver`
+ * provides the same page-drive for browsers without `scrollsnapchange`,
+ * but stands down when the event is supported (it is authoritative);
+ * the observer still always feeds `isInView`.
+ *
+ * **Keyboard → state.** Returns an `onKeyDown` handler that wires the
+ * WAI-ARIA Carousel pattern arrow keys (`ArrowRight` / `ArrowLeft` for
+ * next / previous) plus `Home` / `End` (first / last) onto the same
+ * imperative API the trigger buttons call, so smooth scroll matches
+ * the click path. The handler only fires when the Viewport itself is
+ * the focus target — focus inside a slide keeps its native arrow-key
+ * semantics — and respects `canGoNext` / `canGoPrevious` so it clamps
+ * at the ends.
+ */
+export function useCarouselViewport() {
+    const { slidesRef, slideKeys, slidesPerPage, effectiveSlidesPerMove, maxOffset, currentPageOffset, pageForSlideIndex, totalPages, currentPage, goTo, next, previous, canGoNext, canGoPrevious, transition, snapAlign, orientation, loop, allowMouseDrag, onDragStatusChange, onOverscrollStatusChange, inViewThreshold, refreshTick, visibleSlideIndicesRef, setSlideInView, isProgrammaticScrollRef, instantScrollRef, setDragging, setOverscrolling, setScrollProgress, setSlideProgress, } = useCarouselContext();
+    // The observer's own `threshold` option accepts a number or number[]
+    // as-is; for the "in view" cutoff a single number is used directly, and
+    // an array uses its highest value (the strictest crossing) — matching
+    // the single-boolean semantics `isInView`/the IO page-drive fallback need.
+    const inViewCutoff = Array.isArray(inViewThreshold)
+        ? Math.max(...inViewThreshold)
+        : inViewThreshold;
+    const internalRef = useRef(null);
+    // Set to true by the scrollsnapchange handler and the IntersectionObserver
+    // callback before they call goTo(), so the scroll effect knows the page
+    // change originated from a user scroll (CSS snap already positioned the
+    // viewport) and must not call scrollTo() again.
+    const isUserScrollRef = useRef(false);
+    // Callback ref so the consumer can compose their own ref with ours
+    // via `composeRefs` later (cycle 22 introduces asChild). For now,
+    // it just stashes the node.
+    const viewportRef = useCallback((node) => {
+        internalRef.current = node;
+    }, []);
+    // Mouse click-and-drag scrolling. Opt-in via `allowMouseDrag` (default
+    // false) — an unconditionally-on drag could conflict with a consumer's own
+    // drag-sensitive slide content (a nested carousel, a draggable card, a
+    // canvas). When enabled, tracks the pointer at DRAG_SENSITIVITY× (no
+    // momentum — the multiplier only scales the tracked delta, motion still
+    // stops dead on release) by writing scrollLeft/scrollTop directly during
+    // the drag; release lets the
+    // existing scroll-snap-type settle to the nearest slide, which the
+    // scrollsnapchange sync above already picks up for free — no extra "scroll
+    // → state" wiring needed here. `dragStateRef.current.dragging` only flips
+    // true once the pointer clears DRAG_THRESHOLD_PX, so a plain click (no
+    // capture, no preventDefault) still reaches a link/button under the
+    // pointer untouched. The delta is always computed against the *start*
+    // scroll position (not incrementally from the last move), and
+    // scrollLeft/scrollTop is direction-mode-agnostic — dragging right always
+    // reveals content that was to the left, in both LTR and the
+    // now-standardized negative-scrollLeft RTL convention — so no RTL
+    // special-casing is needed.
+    const dragStateRef = useRef(null);
+    // Browsers still synthesize a click at the release point after a drag
+    // unless it's suppressed — set once a drag crosses the threshold, consumed
+    // (and cleared) by the next click, so a link/button under the release
+    // point doesn't fire.
+    const suppressNextClickRef = useRef(false);
+    const onPointerDown = useCallback((event) => {
+        if (!allowMouseDrag ||
+            event.pointerType !== "mouse" ||
+            transition !== "slide") {
+            return;
+        }
+        // Guaranteed populated — this handler only ever fires as a React
+        // event on the very element viewportRef attached to.
+        const viewport = internalRef.current;
+        const vertical = orientation === "vertical";
+        dragStateRef.current = {
+            pointerId: event.pointerId,
+            startClient: vertical ? event.clientY : event.clientX,
+            startScroll: vertical ? viewport.scrollTop : viewport.scrollLeft,
+            dragging: false,
+            overscrollEdge: null,
+        };
+    }, [allowMouseDrag, orientation, transition]);
+    // A real <img>/<a> inside a slide is natively draggable, and starting a
+    // drag over one fires the browser's own HTML5 drag-and-drop (the
+    // semi-transparent ghost that follows the cursor) — which visually
+    // competes with the custom pointer-based drag-to-scroll below. Only
+    // suppressed when allowMouseDrag is opted into; a consumer who hasn't
+    // enabled our drag-to-scroll keeps native image/link dragging untouched.
+    const onDragStart = useCallback((event) => {
+        if (!allowMouseDrag)
+            return;
+        event.preventDefault();
+    }, [allowMouseDrag]);
+    const onPointerMove = useCallback((event) => {
+        const drag = dragStateRef.current;
+        if (!drag || event.pointerId !== drag.pointerId)
+            return;
+        // Guaranteed populated (see onPointerDown).
+        const viewport = internalRef.current;
+        const vertical = orientation === "vertical";
+        const clientPos = vertical ? event.clientY : event.clientX;
+        const delta = clientPos - drag.startClient;
+        if (!drag.dragging) {
+            if (Math.abs(delta) < DRAG_THRESHOLD_PX)
+                return;
+            drag.dragging = true;
+            suppressNextClickRef.current = true;
+            viewport.setPointerCapture?.(drag.pointerId);
+            viewport.setAttribute("data-dragging", "");
+            setDragging(true);
+            onDragStatusChange?.({
+                type: "dragging.start",
+                page: currentPage,
+                isDragging: true,
+            });
+        }
+        else {
+            onDragStatusChange?.({
+                type: "dragging",
+                page: currentPage,
+                isDragging: true,
+            });
+        }
+        // Overscroll: dragging further past a boundary the carousel has
+        // already reached. Positive delta drags toward the start edge,
+        // negative delta toward the end edge — see the scrollLeft/scrollTop
+        // assignment below (the same convention the regular drag scroll
+        // uses). Only meaningful once the drag threshold is crossed
+        // (drag.dragging, asserted above).
+        const overscrollEdge = delta > 0 && !canGoPrevious
+            ? "start"
+            : delta < 0 && !canGoNext
+                ? "end"
+                : null;
+        if (overscrollEdge) {
+            const amount = Math.abs(delta) * DRAG_SENSITIVITY;
+            const type = drag.overscrollEdge ? "overscroll" : "overscroll.start";
+            drag.overscrollEdge = overscrollEdge;
+            setOverscrolling(true);
+            viewport.setAttribute("data-overscroll", overscrollEdge);
+            onOverscrollStatusChange?.({
+                type,
+                edge: overscrollEdge,
+                source: "drag",
+                amount,
+                page: currentPage,
+            });
+        }
+        else if (drag.overscrollEdge) {
+            const endedEdge = drag.overscrollEdge;
+            drag.overscrollEdge = null;
+            setOverscrolling(false);
+            viewport.removeAttribute("data-overscroll");
+            onOverscrollStatusChange?.({
+                type: "overscroll.end",
+                edge: endedEdge,
+                source: "drag",
+                amount: 0,
+                page: currentPage,
+            });
+        }
+        event.preventDefault();
+        const nextScroll = drag.startScroll - delta * DRAG_SENSITIVITY;
+        if (vertical)
+            viewport.scrollTop = nextScroll;
+        else
+            viewport.scrollLeft = nextScroll;
+    }, [
+        orientation,
+        currentPage,
+        onDragStatusChange,
+        setDragging,
+        canGoNext,
+        canGoPrevious,
+        onOverscrollStatusChange,
+        setOverscrolling,
+    ]);
+    const endDrag = useCallback(() => {
+        const drag = dragStateRef.current;
+        if (!drag)
+            return;
+        if (drag.dragging) {
+            internalRef.current?.releasePointerCapture?.(drag.pointerId);
+            internalRef.current?.removeAttribute("data-dragging");
+            setDragging(false);
+            onDragStatusChange?.({
+                type: "dragging.end",
+                page: currentPage,
+                isDragging: false,
+            });
+            if (drag.overscrollEdge) {
+                internalRef.current?.removeAttribute("data-overscroll");
+                setOverscrolling(false);
+                onOverscrollStatusChange?.({
+                    type: "overscroll.end",
+                    edge: drag.overscrollEdge,
+                    source: "drag",
+                    amount: 0,
+                    page: currentPage,
+                });
+            }
+        }
+        dragStateRef.current = null;
+    }, [
+        currentPage,
+        onDragStatusChange,
+        setDragging,
+        onOverscrollStatusChange,
+        setOverscrolling,
+    ]);
+    const onClickCapture = useCallback((event) => {
+        if (suppressNextClickRef.current) {
+            suppressNextClickRef.current = false;
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }, []);
+    // 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(() => typeof window !== "undefined" &&
+        window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+        ? "instant"
+        : "smooth", []);
+    useEffect(() => {
+        // transition="none" hands the visual to consumer CSS; we don't
+        // touch viewport.scrollTo at all in that mode. loop="infinite" is driven by
+        // the transform engine (useCarouselLoop), not native scroll — this effect
+        // stands down for it.
+        if (transition !== "slide" || loop === "infinite")
+            return;
+        const firstSlideKey = slideKeys[currentPageOffset];
+        // No slides registered yet, or page out of range: nothing to scroll to.
+        if (!firstSlideKey)
+            return;
+        // Both viewport ref and the slide element are guaranteed populated
+        // here — the effect runs post-commit (after callback refs fire) and
+        // any key in slideKeys was just registered into slidesRef in
+        // lockstep by useCarouselRoot.registerSlide.
+        // A user swipe via CSS scroll-snap has already positioned the viewport;
+        // calling scrollTo on top would start a second animation and cause jank.
+        if (isUserScrollRef.current) {
+            isUserScrollRef.current = false;
+            return;
+        }
+        const viewport = internalRef.current;
+        // Mark the scroll as programmatic so the IntersectionObserver
+        // doesn't treat the in-flight animation as a user scroll and undo
+        // the page change. next() / previous() also set this — re-asserting
+        // here covers indicator-driven goTo and the initial scroll on
+        // mount, neither of which goes through next() / previous().
+        isProgrammaticScrollRef.current = true;
+        // Scroll the *viewport itself* — never `targetEl.scrollIntoView()`, which
+        // walks every scrollable ancestor (including the page/window) and so scrolls
+        // the whole document when the carousel is off-screen. We read the target
+        // slide's `getBoundingClientRect` relative to the viewport and add the delta
+        // to the current scroll offset (so the maths is correct mid-scroll), then let
+        // the consumer's `scroll-snap-align` make the final correction — we never
+        // fight the snap engine. The scroll axis follows `orientation`; the cross axis
+        // is untouched, so the viewport never drifts on the other axis. `start` aligns
+        // the slide's leading edge to the viewport's; `center` centres it; `end`
+        // aligns its trailing edge.
+        const targetEl = slidesRef.current.get(firstSlideKey);
+        // A loop-mode switch reparents the slides into / out of the transform track,
+        // so a slide can unmount + re-register in the same commit that re-runs this
+        // effect: the key is still in slideKeys but its element isn't back in slidesRef
+        // yet. Bail; the re-register bumps slideKeys and re-runs this against the
+        // settled set. (Same race the --slide-progress effect below already guards.)
+        if (!targetEl)
+            return;
+        const vertical = orientation === "vertical";
+        const viewportRect = viewport.getBoundingClientRect();
+        const targetRect = targetEl.getBoundingClientRect();
+        const currentScroll = vertical ? viewport.scrollTop : viewport.scrollLeft;
+        const delta = vertical
+            ? targetRect.top - viewportRect.top
+            : targetRect.left - viewportRect.left;
+        // The target slide's own snapAlign (Carousel.Slide's `snapAlign` prop,
+        // already merged with the root default) is read off the DOM rather than
+        // context, since only the slide component knows whether it set a
+        // per-slide override. `Carousel.Slide` always publishes data-snap-align
+        // on a valid snap-start slide — the only kind `firstSlideKey` ever is
+        // (see useCarouselSlide's isSnapStart gate) — so this is never
+        // undefined in practice; no fallback needed. `snapAlign` (the root
+        // value) stays a dependency below purely so this effect re-runs and
+        // re-reads the DOM when it changes without an accompanying page change.
+        const effectiveSnapAlign = targetEl.dataset.snapAlign;
+        // For center/end, the leftover space must be measured against the whole
+        // *page* (every slide sharing this page, edge to edge) rather than just
+        // the leading slide's own box — a multi-slide page's other members would
+        // otherwise be excluded from the alignment math entirely, undershooting
+        // the scroll and leaving the page's trailing slide(s) clipped off-screen.
+        // `start` doesn't depend on this (its alignOffset is always 0), but
+        // computing it unconditionally costs nothing and keeps the code path
+        // uniform. The last member's index is clamped to the actual slide count
+        // (slidesPerPage can exceed how many slides really exist).
+        const lastMemberIndex = Math.min(currentPageOffset + slidesPerPage - 1, slideKeys.length - 1);
+        // Present whenever targetEl is (a loop-mode reparent unmounts every slide
+        // together, so the guard above already caught a mid-reparent run).
+        const lastMemberEl = slidesRef.current.get(slideKeys[lastMemberIndex]);
+        const lastMemberRect = lastMemberEl.getBoundingClientRect();
+        // Computed as left/top + width/height, not the rect's own .right/.bottom
+        // — real DOMRects derive those the same way, but keeping the maths
+        // explicit here matches the plain-object rect fixtures used in tests.
+        const pageSpan = vertical
+            ? lastMemberRect.top + lastMemberRect.height - targetRect.top
+            : lastMemberRect.left + lastMemberRect.width - targetRect.left;
+        const leftoverSpace = vertical
+            ? viewport.clientHeight - pageSpan
+            : viewport.clientWidth - pageSpan;
+        const alignOffset = effectiveSnapAlign === "center"
+            ? leftoverSpace / 2
+            : effectiveSnapAlign === "end"
+                ? leftoverSpace
+                : 0;
+        const position = currentScroll + delta - alignOffset;
+        // instantScrollRef is a one-shot override set by this specific next() /
+        // previous() / goTo() call — consumed (and cleared) immediately so it
+        // never leaks into a later page change that didn't request it (e.g. a
+        // user swipe or a subsequent plain next()).
+        const behavior = instantScrollRef.current ? "instant" : scrollBehavior;
+        instantScrollRef.current = false;
+        viewport.scrollTo(vertical ? { top: position, behavior } : { left: position, behavior });
+        // Clear the programmatic-scroll guard once the animation settles.
+        // `scrollend` is the reliable signal in real browsers; the setTimeout
+        // is a fallback for environments (jsdom, older Safari) that don't fire
+        // it. The timeout is longer than any typical smooth-scroll duration so
+        // real-browser IO entries that fire mid-animation are still suppressed.
+        // Re-clearing the flag is harmless, so no idempotency guard is needed.
+        const clearFlag = () => {
+            isProgrammaticScrollRef.current = false;
+        };
+        viewport.addEventListener("scrollend", clearFlag, { once: true });
+        const timeoutId = setTimeout(() => {
+            viewport.removeEventListener("scrollend", clearFlag);
+            clearFlag();
+        }, 600);
+        return () => {
+            clearTimeout(timeoutId);
+            viewport.removeEventListener("scrollend", clearFlag);
+        };
+    }, [
+        transition,
+        snapAlign,
+        orientation,
+        loop,
+        currentPageOffset,
+        slidesPerPage,
+        slideKeys,
+        slidesRef,
+        refreshTick,
+        scrollBehavior,
+    ]);
+    // Keeps every page's leading slide `scroll-margin` extended out to its
+    // page's actual last member, so a user's own swipe/wheel/touch — settled
+    // entirely by the browser's native scroll-snap, never by the scrollTo
+    // effect above — also spans the whole page for center/end alignment
+    // instead of just the leading slide's own box (the same fix applied to
+    // the programmatic scroll, just expressed as a native snap-area
+    // extension rather than a scrollTo offset). A single slide-per-page
+    // carousel needs no extension at all, so this is a no-op there. Runs for
+    // every page up front (not just the current one), since a fast native
+    // fling under `mandatory` snapping can settle on a page the effect above
+    // never programmatically targeted.
+    useEffect(() => {
+        if (transition !== "slide" || slidesPerPage <= 1)
+            return;
+        // Guaranteed populated — this effect only runs post-commit, and
+        // slidesRef.current is a plain useRef(new Map()) in useCarouselRoot,
+        // never null.
+        const viewport = internalRef.current;
+        const vertical = orientation === "vertical";
+        const recomputeScrollMargins = () => {
+            const slides = slidesRef.current;
+            for (let page = 0; page < totalPages; page++) {
+                const offset = Math.min(page * effectiveSlidesPerMove, maxOffset);
+                const lastIndex = Math.min(offset + slidesPerPage - 1, slideKeys.length - 1);
+                // Guaranteed populated — any key in slideKeys was just registered
+                // into slidesRef in lockstep by useCarouselRoot.registerSlide (see
+                // the scroll-position effect above).
+                const leadingEl = slides.get(slideKeys[offset]);
+                const lastEl = slides.get(slideKeys[lastIndex]);
+                const leadingRect = leadingEl.getBoundingClientRect();
+                const lastRect = lastEl.getBoundingClientRect();
+                // Computed as left/top + width/height (not .right/.bottom) to match
+                // the plain-object rect fixtures used in tests — real DOMRects
+                // derive those the same way.
+                const extra = vertical
+                    ? lastRect.top + lastRect.height - (leadingRect.top + leadingRect.height)
+                    : lastRect.left + lastRect.width - (leadingRect.left + leadingRect.width);
+                leadingEl.style.scrollMarginInlineEnd = vertical ? "" : `${extra}px`;
+                leadingEl.style.scrollMarginBlockEnd = vertical ? `${extra}px` : "";
+            }
+        };
+        recomputeScrollMargins();
+        // Equal-share slide sizes derive from the viewport's own width/height, so
+        // the px extension above must stay current across resizes, not just
+        // page/slide-count changes (which the effect already re-runs for).
+        const resizeObserver = new ResizeObserver(recomputeScrollMargins);
+        resizeObserver.observe(viewport);
+        return () => resizeObserver.disconnect();
+    }, [
+        transition,
+        orientation,
+        slidesPerPage,
+        effectiveSlidesPerMove,
+        maxOffset,
+        totalPages,
+        slideKeys,
+        slidesRef,
+    ]);
+    // Continuous scroll-progress signal — a live 0..1 global value plus a
+    // per-slide -1..1 center-distance, both mirrored onto CSS custom
+    // properties for real-time visual consumption without a React
+    // re-render. Unconditional (unlike the scroll-margin effect above,
+    // which is meaningless outside `transition: "slide"`) — progress
+    // should degrade gracefully to near-zero in `fade` mode rather than
+    // not exist at all.
+    useEffect(() => {
+        const viewport = internalRef.current;
+        const vertical = orientation === "vertical";
+        // Coalesces any number of scroll/resize signals within one animation
+        // frame into a single recompute — a native `scroll` event can fire many
+        // times per frame during momentum scrolling, and each recompute reads
+        // getBoundingClientRect() per slide (a forced-layout read), so batching
+        // avoids a textbook scroll-jank anti-pattern. `pendingFrame` is a plain
+        // closure variable, not a ref — it never needs to outlive this specific
+        // effect instance.
+        let pendingFrame = null;
+        const recomputeProgress = () => {
+            const maxScroll = vertical
+                ? viewport.scrollHeight - viewport.clientHeight
+                : viewport.scrollWidth - viewport.clientWidth;
+            const scrollPos = vertical ? viewport.scrollTop : viewport.scrollLeft;
+            // Math.abs, not the raw signed value — modern browsers standardize
+            // RTL scrollLeft on the "negative" convention (0 at the start, down
+            // to -maxScroll at the end), so this makes "distance travelled from
+            // the start" monotonic in both directions with no dir/
+            // getComputedStyle read, mirroring why the drag handler above needs
+            // no RTL special-casing either.
+            const scrollProgress = maxScroll > 0 ? clamp(Math.abs(scrollPos) / maxScroll, 0, 1) : 0;
+            setScrollProgress(scrollProgress);
+            viewport.style.setProperty("--carousel-progress", String(scrollProgress));
+            const viewportRect = viewport.getBoundingClientRect();
+            const viewportHalfSize = vertical
+                ? viewportRect.height / 2
+                : viewportRect.width / 2;
+            const viewportCenter = vertical
+                ? viewportRect.top + viewportHalfSize
+                : viewportRect.left + viewportHalfSize;
+            const slides = slidesRef.current;
+            slideKeys.forEach((key, index) => {
+                const slideEl = slides.get(key);
+                // A slide can unmount in the same commit that re-runs this effect
+                // (orientation is one of its other dependencies) — the removed
+                // slide's ref callback deletes it from slidesRef synchronously
+                // during the mutation phase, while this effect's own closure still
+                // has the pre-drop slideKeys (its slideKeys update hasn't flushed
+                // a render yet). Skip the orphaned key; the next slideKeys change
+                // re-runs this effect against the settled set. Same race as the
+                // IntersectionObserver effect above.
+                if (!slideEl)
+                    return;
+                const slideRect = slideEl.getBoundingClientRect();
+                const slideCenter = vertical
+                    ? slideRect.top + slideRect.height / 2
+                    : slideRect.left + slideRect.width / 2;
+                const slideProgress = viewportHalfSize > 0
+                    ? clamp((slideCenter - viewportCenter) / viewportHalfSize, -1, 1)
+                    : 0;
+                setSlideProgress(index, slideProgress);
+                slideEl.style.setProperty("--slide-progress", String(slideProgress));
+            });
+        };
+        const scheduleRecompute = () => {
+            if (pendingFrame !== null)
+                return;
+            pendingFrame = requestAnimationFrame(() => {
+                pendingFrame = null;
+                recomputeProgress();
+            });
+        };
+        recomputeProgress();
+        viewport.addEventListener("scroll", scheduleRecompute, { passive: true });
+        const resizeObserver = new ResizeObserver(scheduleRecompute);
+        resizeObserver.observe(viewport);
+        return () => {
+            viewport.removeEventListener("scroll", scheduleRecompute);
+            resizeObserver.disconnect();
+            if (pendingFrame !== null)
+                cancelAnimationFrame(pendingFrame);
+        };
+    }, [orientation, slideKeys, slidesRef, setScrollProgress, setSlideProgress]);
+    // Horizontal mouse-wheel translation. A physical scroll wheel (vertical
+    // notches, deltaY only) already natively scrolls a vertically-scrollable
+    // container, so orientation="vertical" needs nothing here. But browsers
+    // only auto-translate a plain vertical wheel to horizontal scroll when
+    // Shift is held, so a horizontal (the default) carousel gets no scroll at
+    // all from a physical wheel without this. Registered via addEventListener
+    // (not the React onWheel prop) with { passive: false } — React attaches
+    // wheel listeners as passive by default, which would silently no-op
+    // preventDefault() and let the page scroll vertically at the same time.
+    // Deliberately stands down whenever deltaX is non-negligible: a trackpad
+    // or Magic Mouse horizontal swipe already produces real deltaX and already
+    // scrolls a horizontal viewport natively via the same mechanism as touch —
+    // this must never fight that, only fill the gap a plain vertical wheel
+    // leaves. deltaY is normalized from line/page units to pixels so a
+    // physical wheel's larger, fewer DOM_DELTA_LINE ticks feel proportional to
+    // a trackpad's many small DOM_DELTA_PIXEL ones.
+    useEffect(() => {
+        // Infinite is transform-driven, not a scroll container — no wheel-to-scroll.
+        if (transition !== "slide" ||
+            orientation === "vertical" ||
+            loop === "infinite")
+            return;
+        const viewport = internalRef.current;
+        const handler = (event) => {
+            if (Math.abs(event.deltaX) > 0.5)
+                return;
+            let deltaY = event.deltaY;
+            if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) {
+                deltaY *= 16;
+            }
+            else if (event.deltaMode === WheelEvent.DOM_DELTA_PAGE) {
+                deltaY *= viewport.clientWidth;
+            }
+            // Overscroll: a wheel notch pushing forward/backward while already
+            // at that boundary. A single discrete tick — no meaningful distance
+            // to report, unlike the continuous drag case.
+            if (deltaY > 0 && !canGoNext) {
+                onOverscrollStatusChange?.({
+                    type: "overscroll",
+                    edge: "end",
+                    source: "wheel",
+                    amount: 0,
+                    page: currentPage,
+                });
+            }
+            else if (deltaY < 0 && !canGoPrevious) {
+                onOverscrollStatusChange?.({
+                    type: "overscroll",
+                    edge: "start",
+                    source: "wheel",
+                    amount: 0,
+                    page: currentPage,
+                });
+            }
+            event.preventDefault();
+            viewport.scrollLeft += deltaY;
+        };
+        viewport.addEventListener("wheel", handler, { passive: false });
+        return () => viewport.removeEventListener("wheel", handler);
+    }, [
+        transition,
+        orientation,
+        loop,
+        canGoNext,
+        canGoPrevious,
+        currentPage,
+        onOverscrollStatusChange,
+    ]);
+    // User-driven scroll → state. Listen for scrollsnapchange and update
+    // currentPage from the snapped slide's index. The viewport ref is
+    // guaranteed populated post-commit (callback ref runs first).
+    useEffect(() => {
+        // Infinite is transform-driven (useCarouselLoop) with no native scroll, so
+        // it emits no scrollsnapchange — this sync is for the scroll-snap modes.
+        if (transition !== "slide" || loop === "infinite")
+            return;
+        const viewport = internalRef.current;
+        const handler = (event) => {
+            // The snapped slide is reported on the axis the viewport scrolls:
+            // snapTargetBlock for a vertical carousel, snapTargetInline otherwise.
+            const snapEvent = event;
+            const target = orientation === "vertical"
+                ? snapEvent.snapTargetBlock
+                : snapEvent.snapTargetInline;
+            // findIndex returns -1 when the snap target isn't one of our
+            // registered slides — e.g. a consumer-wrapped element inside the
+            // viewport. Ignore those; only registered slides drive the page.
+            const slideIndex = slideKeys.findIndex((key) => slidesRef.current.get(key) === target);
+            if (slideIndex < 0)
+                return;
+            const targetPage = pageForSlideIndex(slideIndex);
+            if (targetPage !== currentPage) {
+                isUserScrollRef.current = true;
+                goTo(targetPage);
+            }
+        };
+        viewport.addEventListener("scrollsnapchange", handler);
+        return () => viewport.removeEventListener("scrollsnapchange", handler);
+    }, [
+        transition,
+        loop,
+        orientation,
+        slideKeys,
+        slidesRef,
+        pageForSlideIndex,
+        currentPage,
+        goTo,
+    ]);
+    // IntersectionObserver fallback for browsers without scrollsnapchange,
+    // and the source of truth for isInView() on the imperative API. The
+    // observer fires whenever a slide crosses the inViewThreshold visibility
+    // threshold (0.6 by default); the lowest-index visible slide derives the
+    // active page.
+    useEffect(() => {
+        if (transition !== "slide")
+            return;
+        // When the browser fires scrollsnapchange (Chrome 129+), that event is
+        // the authoritative source of the active page — snapTargetInline is the
+        // precisely-snapped slide. The observer below then only feeds isInView.
+        // Its lowest-index-visible heuristic is a coarse page fallback for
+        // browsers without the event, and would mis-track a centre-aligned
+        // carousel that shows several slides at once (it follows the leftmost
+        // visible slide, not the centred one), so it must not drive the page
+        // when the event is available.
+        const supportsSnapEvents = "onscrollsnapchange" in window;
+        const observer = new IntersectionObserver((entries) => {
+            // The live observer only observes elements still present in
+            // slidesRef (the setup loop skips orphaned keys), and a stale
+            // observer is disconnected on cleanup when the effect re-runs, so
+            // by the time a callback fires both lookups (slideKeys.findIndex →
+            // registered key, and the slidesRef get → element) resolve.
+            for (const entry of entries) {
+                const idx = slideKeys.findIndex((key) => slidesRef.current.get(key) === entry.target);
+                setSlideInView(idx, entry.isIntersecting && entry.intersectionRatio >= inViewCutoff);
+            }
+            // isInView is updated above regardless; only the page-drive below
+            // is the fallback that scrollsnapchange supersedes. Infinite is
+            // transform-driven — its page never comes from viewport visibility — so
+            // the page-drive stands down there too (the isInView feed above stays).
+            if (supportsSnapEvents || loop === "infinite")
+                return;
+            const visible = visibleSlideIndicesRef.current;
+            if (visible.size === 0)
+                return;
+            const firstVisible = Math.min(...visible);
+            const targetPage = pageForSlideIndex(firstVisible);
+            // Guard: if a programmatic scroll is in flight (e.g. user clicked
+            // NextTrigger and the smooth-scroll animation hasn't settled), the
+            // IO may still see the old slide as ≥ the cutoff visible. Calling
+            // goTo here would undo the navigation, so skip until the flag clears.
+            if (targetPage !== currentPage && !isProgrammaticScrollRef.current) {
+                isUserScrollRef.current = true;
+                goTo(targetPage);
+            }
+        }, { threshold: inViewThreshold });
+        for (const key of slideKeys) {
+            // A slide can unmount in the same commit that re-runs this effect — a
+            // dynamic slide-count drop removes its element from slidesRef during the
+            // mutation phase while this effect still closes over the pre-drop
+            // slideKeys. Skip the orphaned key; the registerSlide that unmounted it
+            // schedules a fresh slideKeys, re-running this effect to observe the
+            // settled set.
+            const element = slidesRef.current.get(key);
+            if (element)
+                observer.observe(element);
+        }
+        return () => observer.disconnect();
+    }, [
+        transition,
+        loop,
+        slideKeys,
+        slidesRef,
+        pageForSlideIndex,
+        currentPage,
+        goTo,
+        setSlideInView,
+        visibleSlideIndicesRef,
+        inViewThreshold,
+        inViewCutoff,
+    ]);
+    // Keyboard navigation per the WAI-ARIA Carousel pattern: arrow keys
+    // route through the same imperative API as the trigger buttons so the
+    // smooth scroll and loop-wrap animation match the click path. The
+    // event.target === currentTarget guard restricts handling to the
+    // Viewport itself — focus inside a slide (e.g. on a link or form
+    // control) keeps its native arrow-key semantics.
+    const onKeyDown = useCallback((event) => {
+        // Restrict to keypresses originating on the Viewport itself —
+        // focus inside a slide (e.g. on a link or form control) keeps
+        // its native arrow-key semantics.
+        if (event.target !== event.currentTarget)
+            return;
+        // The paging arrows follow the scroll axis: Down/Up for a vertical
+        // carousel, Right/Left otherwise. Home/End are axis-agnostic.
+        const forwardKey = orientation === "vertical" ? "ArrowDown" : "ArrowRight";
+        const backwardKey = orientation === "vertical" ? "ArrowUp" : "ArrowLeft";
+        if (event.key === forwardKey) {
+            event.preventDefault();
+            if (canGoNext) {
+                next();
+            }
+            else {
+                onOverscrollStatusChange?.({
+                    type: "overscroll",
+                    edge: "end",
+                    source: "keyboard",
+                    amount: 0,
+                    page: currentPage,
+                });
+            }
+        }
+        else if (event.key === backwardKey) {
+            event.preventDefault();
+            if (canGoPrevious) {
+                previous();
+            }
+            else {
+                onOverscrollStatusChange?.({
+                    type: "overscroll",
+                    edge: "start",
+                    source: "keyboard",
+                    amount: 0,
+                    page: currentPage,
+                });
+            }
+        }
+        else if (event.key === "Home") {
+            event.preventDefault();
+            goTo(0);
+        }
+        else if (event.key === "End") {
+            event.preventDefault();
+            goTo(totalPages - 1);
+        }
+    }, [
+        orientation,
+        canGoNext,
+        canGoPrevious,
+        next,
+        previous,
+        goTo,
+        totalPages,
+        currentPage,
+        onOverscrollStatusChange,
+    ]);
+    return {
+        viewportRef,
+        onKeyDown,
+        onDragStart,
+        onPointerDown,
+        onPointerMove,
+        onPointerUp: endDrag,
+        onPointerCancel: endDrag,
+        onClickCapture,
+    };
+}