@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/lightbox/behaviour.d.ts

@@ -0,0 +1,82 @@
+import { type Motion1DType } from "../motion/index.js";
+import { parseLength, type LightboxState } from "./state.js";
+interface PointerSample {
+    id: number;
+    x: number;
+    y: number;
+    target: EventTarget | null;
+}
+interface Controller {
+    container: HTMLElement;
+    /** Track offset (px, physical x). */
+    x: Motion1DType;
+    /** Pull offset (px). */
+    y: Motion1DType;
+    pointers: PointerSample[];
+    active: number | undefined;
+    gesture: "swipe" | "pull" | undefined;
+    start: number;
+    offset: number;
+    base: number;
+    /** Wheel swipe (YARL useWheelSwipe refs). */
+    wheel: {
+        offset: number;
+        intent: number;
+        inertia: number;
+        start: number;
+        swiping: boolean;
+        timers: Record<string, ReturnType<typeof setTimeout> | undefined>;
+    };
+    lastKey: number;
+    installed: boolean;
+}
+/** Events a plugin handled (Zoom pans / zooms): the core swipe, wheel and arrow navigation skip them (YARL stopPropagation). */
+export declare const lightboxHandled: WeakSet<Event>;
+/** The lightbox container element (`<id>-container`). */
+export declare const lightboxContainer: (state: LightboxState) => HTMLElement | null;
+/** The carousel track element (`<id>-carousel`). */
+export declare const lightboxCarousel: (state: LightboxState) => HTMLElement | null;
+/** Whether animations jump (`prefers-reduced-motion: reduce`). */
+export declare function lightboxReducesMotion(): boolean;
+/** The runtime controller of a lightbox (created on first use; `undefined` before the container exists). */
+export declare function lightboxController(state: LightboxState): Controller | undefined;
+/** Closes the lightbox (no-op inline). */
+export declare function closeLightbox(state: LightboxState): void;
+/** Distance between two neighbouring slides in px (width + spacing). */
+export declare function lightboxStep(state: LightboxState): number;
+/**
+ * Pauses media of slides that are no longer current and autoplays the current slide's `video[data-autoplay]` (YARL Video
+ * plugin: pause on leave, autoplay when viewed). DOM-driven (no effect), so resumed / inline pages run nothing at load.
+ */
+export declare function syncLightboxMedia(state: LightboxState): void;
+/**
+ * Navigates by `increment` slides (YARL `swipe` action): the current index changes at once; the track jumps by the
+ * distance the slides moved and settles to its rest position (`ms` = animation duration).
+ */
+export declare function lightboxNavigate(state: LightboxState, increment: number, ms?: number): void;
+/** Previous slide (YARL `prev`, `count` slides). */
+export declare const lightboxPrev: (state: LightboxState, count?: number) => void;
+/** Next slide (YARL `next`). */
+export declare const lightboxNext: (state: LightboxState, count?: number) => void;
+/** Jumps to slide `index` (shortest way round when not finite), animated. */
+export declare function lightboxGoTo(state: LightboxState, index: number): void;
+/** Syncs the rendered slide with the controlled `index` (external change: jump, no animation). */
+export declare function syncLightboxIndex(state: LightboxState): void;
+/** Focuses the container (YARL `focus`). */
+export declare function focusLightbox(state: LightboxState): void;
+/** `pointerdown` on the container. */
+export declare function lightboxPointerDown(state: LightboxState, event: PointerEvent): void;
+/** `pointermove` on the container. */
+export declare function lightboxPointerMove(state: LightboxState, event: PointerEvent): void;
+/** `pointerup` / `pointercancel` / `pointerleave` on the container. */
+export declare function lightboxPointerUp(state: LightboxState, event: PointerEvent): void;
+/** `keydown` on the container: ArrowLeft / ArrowRight (mirrored in RTL), throttled. Escape is the overlay's. */
+export declare function lightboxKeyDown(state: LightboxState, event: KeyboardEvent): void;
+/**
+ * Installs the browser-only listeners (non-passive `wheel`) once per container: called when the lightbox opens and from
+ * the first pointer / focus interaction of an inline lightbox (nothing runs on a resumed page before that).
+ */
+export declare function ensureLightbox(state: LightboxState): void;
+/** `padding` / `spacing` of the carousel as CSS (`calc` of px + % of the carousel width). */
+export declare function lightboxLengthCss(value: Parameters<typeof parseLength>[0]): string;
+export {};

package/lightbox/behaviour.js

@@ -0,0 +1,490 @@
+// Ported from yet-another-react-lightbox (src/modules/Controller/{Controller.tsx,usePointerSwipe.ts,useWheelSwipe.ts,
+// usePreventWheelDefaults.ts}, src/modules/Navigation/{useKeyboardNavigation.ts,useNavigationState.ts}, v3.32.2), MIT,
+// © Igor Danchenko.
+// Rivet:
+// - Motion = the house motion (`../motion`, embla-carousel 8.6.0 physics, MIT, © David Jerleke): the carousel track and the
+//   pull offset are `Motion1D` values (YARL: FLIP keyframe animations with CSS easings). Navigation keeps the visual
+//   position (the track jumps by the slide step the re-keyed slides moved) and settles to 0; swipe release / cancel and
+//   pull cancel settle the same way. Reduced motion (`prefers-reduced-motion: reduce`) jumps.
+// - Gesture rules are YARL's: 30 px threshold, swipe finishes past 30 % of the width or a short (< `animation.swipe`)
+//   flick over 5 px, pull closes past 60 px, wheel swipe intent 30 px / 20 % finish / inertia filter, keyboard throttle
+//   (navigation or swipe duration) / 2, `isSwipeValid` for finite carousels, RTL mirrored.
+// - DOM-agnostic state, handlers bound by the parts (resumable inline arrows call these functions); the per-container
+//   runtime (motions, pointers, timers) lives in a WeakMap keyed by the container element — never serialized.
+// - Escape and focus containment / restoration belong to the cdk overlay (`ModalOverlay`); `closeLightbox` closes the
+//   overlay state the root keeps in `state.overlay`.
+// - Media controls: a pointer down within 40 px of the bottom of a `<video controls>` never starts a swipe (YARL: WebKit
+//   only), so the scrubber works in every browser.
+import { untrack } from "@rivetjs/reactivity";
+import { Motion1D } from "../motion/index.js";
+import { closeOverlay } from "../state/overlays.js";
+import { getSlideIndex, lengthPx, lightboxNavigation, lightboxSlides, msToMotion, parseLength, round, setLightboxGlobalIndex, } from "./state.js";
+const SWIPE_THRESHOLD = 30;
+const PULL_MIN_OPACITY = 0.5;
+const PULL_OPACITY_THRESHOLD = 60;
+const controllers = new WeakMap();
+/** Events a plugin handled (Zoom pans / zooms): the core swipe, wheel and arrow navigation skip them (YARL stopPropagation). */
+export const lightboxHandled = new WeakSet();
+const doc = () => globalThis.document;
+/** The lightbox container element (`<id>-container`). */
+export const lightboxContainer = (state) => doc()?.getElementById(`${state.id}-container`) ?? null;
+/** The carousel track element (`<id>-carousel`). */
+export const lightboxCarousel = (state) => doc()?.getElementById(`${state.id}-carousel`) ?? null;
+/** Whether animations jump (`prefers-reduced-motion: reduce`). */
+export function lightboxReducesMotion() {
+    return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+const isRTL = (el) => typeof getComputedStyle === "function" && getComputedStyle(el).direction === "rtl";
+function render(c, state) {
+    const track = lightboxCarousel(state);
+    // A settled motion renders its target (the last interpolated frame can stop short of it).
+    const x = c.x.settled() ? c.x.target.get() : c.x.get(), y = c.y.settled() ? c.y.target.get() : c.y.get();
+    if (track) {
+        if (Math.abs(x) < 0.5 && Math.abs(y) < 0.5 && c.x.settled() && c.y.settled())
+            track.style.removeProperty("transform");
+        else
+            track.style.transform = `translate3d(${round(x, 2)}px, ${round(y, 2)}px, 0)`;
+    }
+    const ctl = state.controller;
+    const pull = (ctl.closeOnPullDown && y > 0) || (ctl.closeOnPullUp && y < 0) ? Math.abs(y) : 0;
+    const opacity = Math.min(Math.max(round(1 - (pull / PULL_OPACITY_THRESHOLD) * (1 - PULL_MIN_OPACITY), 2), PULL_MIN_OPACITY), 1);
+    if (opacity < 1)
+        c.container.style.setProperty("--rv-lightbox-pull-opacity", String(opacity));
+    else
+        c.container.style.removeProperty("--rv-lightbox-pull-opacity");
+}
+/** The runtime controller of a lightbox (created on first use; `undefined` before the container exists). */
+export function lightboxController(state) {
+    const container = lightboxContainer(state);
+    if (!container)
+        return undefined;
+    let c = controllers.get(container);
+    if (c)
+        return c;
+    const settle = () => {
+        if (c && c.x.settled() && c.y.settled() && !c.gesture)
+            untrack(() => state.gesture.set(undefined));
+    };
+    c = {
+        container,
+        x: Motion1D({ value: 0, duration: msToMotion(state.animation.swipe), render: () => render(c, state), onSettle: settle }),
+        y: Motion1D({ value: 0, duration: msToMotion(state.animation.fade), render: () => render(c, state), onSettle: settle }),
+        pointers: [],
+        active: undefined,
+        gesture: undefined,
+        start: 0,
+        offset: 0,
+        base: 0,
+        wheel: { offset: 0, intent: 0, inertia: 0, start: 0, swiping: false, timers: {} },
+        lastKey: 0,
+        installed: false,
+    };
+    controllers.set(container, c);
+    return c;
+}
+/** Closes the lightbox (no-op inline). */
+export function closeLightbox(state) {
+    if (state.overlay)
+        closeOverlay(state.overlay);
+}
+/** Width of the carousel track (0 before layout). */
+function trackWidth(state) {
+    return lightboxCarousel(state)?.clientWidth ?? lightboxContainer(state)?.clientWidth ?? 0;
+}
+/** Distance between two neighbouring slides in px (width + spacing). */
+export function lightboxStep(state) {
+    const width = trackWidth(state);
+    return width + lengthPx(state.carousel.spacing, width);
+}
+/** YARL `isSwipeValid`: a finite carousel cannot swipe past its ends (`offset` in physical px). */
+function isSwipeValid(state, offset, rtl) {
+    if (!state.carousel.finite)
+        return true;
+    const count = lightboxSlides(state).length;
+    const current = getSlideIndex(untrack(state.globalIndex), count);
+    const value = (rtl ? -1 : 1) * offset;
+    return !((value > 0 && current === 0) || (value < 0 && current === count - 1));
+}
+function animate(m, value, ms) {
+    const units = lightboxReducesMotion() ? 0 : msToMotion(ms);
+    if (!units) {
+        m.to(value, true);
+        return;
+    }
+    m.to(value);
+    m.scrollBody.useDuration(units);
+}
+/**
+ * Pauses media of slides that are no longer current and autoplays the current slide's `video[data-autoplay]` (YARL Video
+ * plugin: pause on leave, autoplay when viewed). DOM-driven (no effect), so resumed / inline pages run nothing at load.
+ */
+export function syncLightboxMedia(state) {
+    const container = lightboxContainer(state);
+    if (!container)
+        return;
+    for (const video of container.querySelectorAll("[data-lightbox-slide]:not([data-current]) video"))
+        if (!video.paused)
+            video.pause();
+    const current = container.querySelector("[data-lightbox-slide][data-current] video[data-autoplay]");
+    if (current && current.paused)
+        current.play()?.catch(() => { });
+}
+/** After a slide change (bindings flushed): refocus the container when focus sits in a slide that moved off screen or on
+ * a button that became disabled (YARL CarouselSlide `focus()` effect + `useLoseFocus`), sync media. */
+function afterNavigate(state) {
+    queueMicrotask(() => {
+        syncLightboxMedia(state);
+        const container = lightboxContainer(state);
+        if (container) {
+            // Thumbnails: keep the current one in view (YARL ThumbnailsTrack offset animation).
+            container
+                .querySelector("[data-lightbox-thumbnail][data-current]")
+                ?.scrollIntoView({ block: "nearest", inline: "nearest", behavior: lightboxReducesMotion() ? "auto" : "smooth" });
+            // Plugins that run while active (Slideshow) listen for this.
+            container.dispatchEvent(new (container.ownerDocument.defaultView ?? globalThis).CustomEvent("rv-lightbox-view"));
+        }
+        const active = doc()?.activeElement;
+        if (!container || !active || !container.contains(active) || active === container)
+            return;
+        const slide = active.closest("[data-lightbox-slide]");
+        if ((slide && !slide.hasAttribute("data-current")) || active.matches(":disabled"))
+            container.focus({ preventScroll: true });
+    });
+}
+/**
+ * Navigates by `increment` slides (YARL `swipe` action): the current index changes at once; the track jumps by the
+ * distance the slides moved and settles to its rest position (`ms` = animation duration).
+ */
+export function lightboxNavigate(state, increment, ms) {
+    if (!increment)
+        return;
+    const count = untrack(() => lightboxSlides(state)).length;
+    if (!count)
+        return;
+    const nav = untrack(() => lightboxNavigation(state));
+    if ((increment < 0 && nav.prevDisabled) || (increment > 0 && nav.nextDisabled))
+        return;
+    let target = untrack(state.globalIndex) + increment;
+    if (state.carousel.finite) {
+        const current = getSlideIndex(untrack(state.globalIndex), count);
+        target = untrack(state.globalIndex) + Math.max(-current, Math.min(count - 1 - current, increment));
+    }
+    const moved = target - untrack(state.globalIndex);
+    const c = lightboxController(state);
+    setLightboxGlobalIndex(state, target);
+    untrack(() => state.on.onView?.({ index: getSlideIndex(target, count) }));
+    if (c) {
+        const sign = isRTL(c.container) ? -1 : 1;
+        c.x.to(c.x.get() + sign * moved * lightboxStep(state), true);
+        state.gesture.set("animation");
+        animate(c.x, 0, ms ?? state.animation.navigation ?? state.animation.swipe);
+    }
+    afterNavigate(state);
+}
+/** Previous slide (YARL `prev`, `count` slides). */
+export const lightboxPrev = (state, count = 1) => lightboxNavigate(state, -count);
+/** Next slide (YARL `next`). */
+export const lightboxNext = (state, count = 1) => lightboxNavigate(state, count);
+/** Jumps to slide `index` (shortest way round when not finite), animated. */
+export function lightboxGoTo(state, index) {
+    const count = untrack(() => lightboxSlides(state)).length;
+    if (!count)
+        return;
+    const current = getSlideIndex(untrack(state.globalIndex), count);
+    let delta = getSlideIndex(index, count) - current;
+    if (!state.carousel.finite && Math.abs(delta) > count / 2)
+        delta -= Math.sign(delta) * count;
+    lightboxNavigate(state, delta);
+}
+/** Syncs the rendered slide with the controlled `index` (external change: jump, no animation). */
+export function syncLightboxIndex(state) {
+    const count = lightboxSlides(state).length;
+    const index = state.index.value();
+    untrack(() => {
+        const g = state.globalIndex();
+        if (count && getSlideIndex(g, count) !== getSlideIndex(index, count)) {
+            state.globalIndex.set(g - getSlideIndex(g, count) + getSlideIndex(index, count));
+            if (doc())
+                afterNavigate(state);
+        }
+    });
+}
+/** Focuses the container (YARL `focus`). */
+export function focusLightbox(state) {
+    lightboxContainer(state)?.focus({ preventScroll: true });
+}
+/* ------------------------------------------------------------------------------------------------
+ * Pointer swipe / pull (YARL usePointerSwipe)
+ * ----------------------------------------------------------------------------------------------*/
+function clearPointer(c, id) {
+    if (c.active === id) {
+        c.active = undefined;
+        c.gesture = undefined;
+    }
+    c.pointers = c.pointers.filter((p) => p.id !== id);
+}
+function isMediaControls(event) {
+    const target = event.target;
+    if (!(target instanceof HTMLMediaElement) || !target.controls)
+        return false;
+    return target.getBoundingClientRect().bottom - event.clientY < 40;
+}
+/** `pointerdown` on the container. */
+export function lightboxPointerDown(state, event) {
+    const c = lightboxController(state);
+    if (!c)
+        return;
+    ensureLightbox(state);
+    if (event.pointerType === "mouse" && event.button !== 0)
+        return;
+    if (isMediaControls(event))
+        return;
+    clearPointer(c, event.pointerId);
+    c.pointers.push({ id: event.pointerId, x: event.clientX, y: event.clientY, target: event.target });
+    // A second pointer (pinch) cancels a running swipe / pull.
+    if (c.pointers.length > 1 && c.active !== undefined)
+        cancelGesture(state, c);
+}
+function cancelGesture(state, c) {
+    const gesture = c.gesture;
+    c.active = undefined;
+    c.gesture = undefined;
+    c.offset = 0;
+    if (gesture === "swipe")
+        animate(c.x, 0, state.animation.swipe / 2);
+    if (gesture === "pull")
+        animate(c.y, 0, state.animation.fade * 2);
+}
+const exceedsPull = (state, value, threshold) => (state.controller.closeOnPullDown && value > threshold) || (state.controller.closeOnPullUp && value < -threshold);
+/** `pointermove` on the container. */
+export function lightboxPointerMove(state, event) {
+    const c = lightboxController(state);
+    if (!c)
+        return;
+    const pointer = c.pointers.find((p) => p.id === event.pointerId);
+    if (!pointer)
+        return;
+    const isCurrent = c.active === event.pointerId;
+    if (event.buttons === 0) {
+        // Released over an opaque element / out-of-order events (YARL #48, #59).
+        if (isCurrent && c.offset !== 0)
+            lightboxPointerUp(state, event);
+        else
+            clearPointer(c, event.pointerId);
+        return;
+    }
+    // Zoomed in or pinching: the Zoom plugin pans / zooms.
+    if (untrack(state.zoom) > 1 || c.pointers.length > 1)
+        return;
+    const dx = event.clientX - pointer.x;
+    const dy = event.clientY - pointer.y;
+    if (c.active === undefined) {
+        const rtl = isRTL(c.container);
+        const startGesture = (gesture) => {
+            c.active = event.pointerId;
+            c.start = Date.now();
+            c.gesture = gesture;
+            c.offset = 0;
+            state.gesture.set(gesture);
+            try {
+                c.container.setPointerCapture(event.pointerId);
+            }
+            catch {
+                // pointer already released
+            }
+        };
+        if (Math.abs(dx) > Math.abs(dy) && Math.abs(dx) > SWIPE_THRESHOLD && isSwipeValid(state, dx, rtl)) {
+            if (!state.controller.disableSwipeNavigation) {
+                startGesture("swipe");
+                c.base = c.x.get();
+                c.x.stop();
+            }
+        }
+        else if (Math.abs(dy) > Math.abs(dx) && exceedsPull(state, dy, SWIPE_THRESHOLD)) {
+            startGesture("pull");
+        }
+    }
+    if (c.active === event.pointerId) {
+        if (c.gesture === "swipe") {
+            c.offset = dx;
+            c.x.to(c.base + dx, true);
+        }
+        else if (c.gesture === "pull") {
+            c.offset = dy;
+            c.y.to(dy, true);
+        }
+    }
+}
+/** `pointerup` / `pointercancel` / `pointerleave` on the container. */
+export function lightboxPointerUp(state, event) {
+    const c = lightboxController(state);
+    if (!c)
+        return;
+    const pointer = c.pointers.find((p) => p.id === event.pointerId);
+    if (pointer) {
+        if (c.active === event.pointerId) {
+            const duration = Date.now() - c.start;
+            const offset = c.offset;
+            const gesture = c.gesture;
+            c.active = undefined;
+            c.gesture = undefined;
+            c.offset = 0;
+            if (gesture === "swipe") {
+                const width = trackWidth(state);
+                if (event.type !== "pointercancel" && (Math.abs(offset) > 0.3 * width || (Math.abs(offset) > 5 && duration < state.animation.swipe))) {
+                    const rtl = isRTL(c.container);
+                    lightboxNavigate(state, (rtl ? -1 : 1) * offset > 0 ? -1 : 1, state.animation.swipe);
+                }
+                else
+                    animate(c.x, 0, state.animation.swipe / 2);
+            }
+            else if (gesture === "pull") {
+                if (event.type !== "pointercancel" && exceedsPull(state, offset, 2 * SWIPE_THRESHOLD)) {
+                    closeLightbox(state);
+                    animate(c.y, 0, state.animation.fade);
+                }
+                else
+                    animate(c.y, 0, state.animation.fade * 2);
+            }
+        }
+        else if (event.type === "pointerup") {
+            // A click: close on the backdrop (the slide box or a media wrapper, not the media).
+            const target = event.target;
+            if (state.controller.closeOnBackdropClick &&
+                target instanceof Element &&
+                target === pointer.target &&
+                (target.hasAttribute("data-lightbox-slide") || target.hasAttribute("data-lightbox-backdrop")))
+                closeLightbox(state);
+        }
+    }
+    clearPointer(c, event.pointerId);
+}
+/* ------------------------------------------------------------------------------------------------
+ * Keyboard (YARL useKeyboardNavigation)
+ * ----------------------------------------------------------------------------------------------*/
+/** `keydown` on the container: ArrowLeft / ArrowRight (mirrored in RTL), throttled. Escape is the overlay's. */
+export function lightboxKeyDown(state, event) {
+    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight")
+        return;
+    // The Zoom plugin pans with the arrows while zoomed in (it marks the event handled).
+    if (lightboxHandled.has(event) || untrack(state.zoom) > 1)
+        return;
+    const c = lightboxController(state);
+    event.stopPropagation();
+    const throttle = (state.animation.navigation ?? state.animation.swipe) / 2;
+    const now = Date.now();
+    if (c) {
+        if (now - c.lastKey < throttle)
+            return;
+        c.lastKey = now;
+    }
+    const rtl = c ? isRTL(c.container) : false;
+    const prev = event.key === "ArrowLeft" ? !rtl : rtl;
+    if (prev)
+        lightboxPrev(state);
+    else
+        lightboxNext(state);
+}
+/* ------------------------------------------------------------------------------------------------
+ * Wheel (YARL useWheelSwipe + usePreventWheelDefaults)
+ * ----------------------------------------------------------------------------------------------*/
+function wheelSwipe(state, c, event) {
+    if (event.ctrlKey)
+        return; // zoom
+    if (Math.abs(event.deltaY) > Math.abs(event.deltaX))
+        return; // pan-y
+    if (untrack(state.zoom) > 1)
+        return;
+    const w = c.wheel;
+    const width = trackWidth(state);
+    const swipeMs = state.animation.swipe;
+    const setInertia = (inertia) => {
+        w.inertia = inertia;
+        clearTimeout(w.timers.inertia);
+        w.timers.inertia =
+            inertia > 0
+                ? setTimeout(() => {
+                    w.inertia = 0;
+                    w.timers.inertia = undefined;
+                }, 300)
+                : undefined;
+    };
+    if (!w.swiping) {
+        if (c.gesture || untrack(state.gesture) === "animation") {
+            setInertia(event.deltaX);
+            return;
+        }
+        if (Math.abs(event.deltaX) <= 1.2 * Math.abs(w.inertia)) {
+            setInertia(event.deltaX);
+            return;
+        }
+        if (!isSwipeValid(state, -event.deltaX, isRTL(c.container)))
+            return;
+        w.intent += event.deltaX;
+        clearTimeout(w.timers.intent);
+        if (Math.abs(w.intent) > 30) {
+            w.intent = 0;
+            setInertia(0);
+            w.start = Date.now();
+            w.swiping = true;
+            w.offset = 0;
+            c.base = c.x.get();
+            c.x.stop();
+            state.gesture.set("swipe");
+        }
+        else {
+            const intent = w.intent;
+            w.timers.intent = setTimeout(() => {
+                w.timers.intent = undefined;
+                if (intent === w.intent)
+                    w.intent = 0;
+            }, swipeMs);
+        }
+        return;
+    }
+    let offset = w.offset - event.deltaX;
+    offset = Math.min(Math.abs(offset), width) * Math.sign(offset);
+    w.offset = offset;
+    c.x.to(c.base + offset, true);
+    clearTimeout(w.timers.reset);
+    if (Math.abs(offset) > 0.2 * width) {
+        setInertia(event.deltaX);
+        w.swiping = false;
+        w.offset = 0;
+        const rtl = isRTL(c.container);
+        lightboxNavigate(state, (rtl ? -1 : 1) * offset > 0 ? -1 : 1, swipeMs);
+        return;
+    }
+    w.timers.reset = setTimeout(() => {
+        w.timers.reset = undefined;
+        if (w.swiping && w.offset === offset) {
+            w.swiping = false;
+            w.offset = 0;
+            animate(c.x, 0, swipeMs / 2);
+        }
+    }, 2 * swipeMs);
+}
+/**
+ * Installs the browser-only listeners (non-passive `wheel`) once per container: called when the lightbox opens and from
+ * the first pointer / focus interaction of an inline lightbox (nothing runs on a resumed page before that).
+ */
+export function ensureLightbox(state) {
+    const c = lightboxController(state);
+    if (!c || c.installed)
+        return;
+    c.installed = true;
+    c.container.addEventListener("wheel", (event) => {
+        const { preventDefaultWheelX, preventDefaultWheelY } = state.controller;
+        const horizontal = Math.abs(event.deltaX) > Math.abs(event.deltaY);
+        if ((horizontal && preventDefaultWheelX) || (!horizontal && preventDefaultWheelY) || event.ctrlKey)
+            event.preventDefault();
+        if (lightboxHandled.has(event))
+            return;
+        wheelSwipe(state, c, event);
+    }, { passive: false });
+}
+/** `padding` / `spacing` of the carousel as CSS (`calc` of px + % of the carousel width). */
+export function lightboxLengthCss(value) {
+    const v = parseLength(value);
+    return `calc(${v.pixel ?? 0}px + ${v.percent ?? 0}%)`;
+}

package/lightbox/captions/index.d.ts

@@ -0,0 +1,39 @@
+import type { StyleObject } from "@rivetjs/runtime/style";
+import { type LightboxToggleChildren } from "../index.jsx";
+import { type LightboxState } from "../state.js";
+/** Captions plugin options (YARL `CaptionsProps`). */
+export interface LightboxCaptionsOptions {
+    /** Initially hidden. @default false */
+    hidden?: boolean;
+    /** Description text alignment. @default "start" */
+    descriptionTextAlign?: "start" | "end" | "center";
+    /** Description lines shown (0 = all). @default 3 */
+    descriptionMaxLines?: number;
+}
+/** Whether captions are visible (tracked). */
+export declare const lightboxCaptionsVisible: (state: LightboxState, hidden?: boolean) => boolean;
+/** Shows / hides the captions (YARL `captions.ref` `show` / `hide`). */
+export declare function setLightboxCaptions(state: LightboxState, visible: boolean): void;
+export interface LightboxCaptionsProps extends LightboxCaptionsOptions {
+    /** @default "rv-LightboxCaptions" */
+    class?: string;
+    style?: StyleObject;
+    /** @default "rv-LightboxCaptionsTitle" */
+    titleClass?: string;
+    /** @default "rv-LightboxCaptionsDescription" */
+    descriptionClass?: string;
+}
+/** The current slide's title and description (YARL Captions `Title` + `Description`). */
+export declare function LightboxCaptions(props: LightboxCaptionsProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface LightboxCaptionsToggleProps {
+    class?: string;
+    style?: StyleObject;
+    /** Initially hidden (same value as the `LightboxCaptions` part). @default false */
+    hidden?: boolean;
+    /** Label override (default "Show captions" / "Hide captions"). */
+    label?: string;
+    /** Icon: content, or a function of the visible state. */
+    children?: LightboxToggleChildren;
+}
+/** Show / hide captions button (YARL `CaptionsButton`, `aria-pressed` = visible). */
+export declare function LightboxCaptionsToggle(props: LightboxCaptionsToggleProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/lightbox/captions/index.jsx

@@ -0,0 +1,44 @@
+// Ported from yet-another-react-lightbox (src/plugins/captions/{Captions.tsx,Title.tsx,Description.tsx,CaptionsButton.tsx,
+// CaptionsContext.tsx,props.ts}, v3.32.2), MIT, © Igor Danchenko.
+// Rivet:
+// - `<LightboxCaptions>` renders the current slide's `title` / `description` once (over the carousel, absolutely
+//   positioned by CSS) instead of once per slide (YARL renders them inside every slide's `render.slideFooter`); the text
+//   swaps with the slide.
+// - Visibility lives in the lightbox state (`state.captions`, resumable; YARL CaptionsContext `visible`), toggled by
+//   `<LightboxCaptionsToggle>` (YARL `showToggle` button); both parts take `hidden` (initial: hidden).
+// - `descriptionMaxLines` = `-webkit-line-clamp` inline; `descriptionTextAlign` = `text-align`.
+import { Show } from "@rivetjs/runtime/dom";
+import { LightboxButton, lightboxToggleContent, useLightbox } from "../index.jsx";
+import { lightboxSlide, translateLabel } from "../state.js";
+/** Whether captions are visible (tracked). */
+export const lightboxCaptionsVisible = (state, hidden = false) => state.captions() ?? !hidden;
+/** Shows / hides the captions (YARL `captions.ref` `show` / `hide`). */
+export function setLightboxCaptions(state, visible) {
+    state.captions.set(visible);
+}
+/** The current slide's title and description (YARL Captions `Title` + `Description`). */
+export function LightboxCaptions(props) {
+    const state = useLightbox();
+    const hidden = props.hidden ?? false, align = props.descriptionTextAlign ?? "start", lines = props.descriptionMaxLines ?? 3;
+    const cls = props.class ?? "rv-LightboxCaptions", style = props.style, titleCls = props.titleClass ?? "rv-LightboxCaptionsTitle", descriptionCls = props.descriptionClass ?? "rv-LightboxCaptionsDescription";
+    const clamp = lines > 0 ? { display: "-webkit-box", WebkitBoxOrient: "vertical", WebkitLineClamp: String(lines), overflow: "hidden" } : {};
+    return (<Show when={() => lightboxCaptionsVisible(state, hidden) && !!(lightboxSlide(state)?.title || lightboxSlide(state)?.description)}>
+      {() => (<div class={cls} style={style} data-lightbox-captions="">
+          <Show when={() => !!lightboxSlide(state)?.title}>{() => <div class={titleCls}>{lightboxSlide(state)?.title}</div>}</Show>
+          <Show when={() => !!lightboxSlide(state)?.description}>
+            {() => (<div class={descriptionCls} style={{ textAlign: align, whiteSpace: "pre-line", ...clamp }}>
+                {lightboxSlide(state)?.description}
+              </div>)}
+          </Show>
+        </div>)}
+    </Show>);
+}
+/** Show / hide captions button (YARL `CaptionsButton`, `aria-pressed` = visible). */
+export function LightboxCaptionsToggle(props) {
+    const state = useLightbox();
+    const hidden = props.hidden ?? false, label = props.label, children = props.children;
+    const visible = () => lightboxCaptionsVisible(state, hidden);
+    return (<LightboxButton class={props.class} style={props.style} action="captions" pressed={visible} label={() => label ?? translateLabel(state.labels, visible() ? "Hide captions" : "Show captions")} onPress={() => setLightboxCaptions(state, !lightboxCaptionsVisible(state, hidden))}>
+      {lightboxToggleContent(children, visible)}
+    </LightboxButton>);
+}

package/lightbox/counter/index.d.ts

@@ -0,0 +1,10 @@
+import type { StyleObject } from "@rivetjs/runtime/style";
+export interface LightboxCounterProps {
+    /** @default "rv-LightboxCounter" */
+    class?: string;
+    style?: StyleObject;
+    /** Text between the index and the total. @default "/" */
+    separator?: string;
+}
+/** Slide counter `index / total` (YARL Counter). Renders nothing for an empty lightbox. */
+export declare function LightboxCounter(props: LightboxCounterProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;