@jorgemadrid/open-carousel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,618 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, PointerEvent, MouseEvent } from 'react';
+
+declare const VISUAL_CONFIG: {
+    readonly MAX_DIST_MOBILE: 320;
+    readonly MAX_DIST_TABLET: 400;
+    readonly MAX_DIST_DESKTOP: 500;
+    readonly BASE_SCALE_MOBILE: 0.8;
+    readonly BASE_SCALE_TABLET: 0.82;
+    readonly BASE_SCALE_DESKTOP: 0.85;
+    readonly VIEW_BUFFER: 200;
+    readonly CENTER_THRESHOLD: 10;
+    readonly DISABLE_DYNAMIC_SHADOW: true;
+};
+declare const TIMING_CONFIG: {
+    readonly BOUNCE_DISTANCE_PX: 30;
+    readonly BOUNCE_PHASE1_MS: 150;
+    readonly BOUNCE_PHASE2_MS: 450;
+    readonly PRE_TELEPORT_CLEAR_DELAY_MS: 100;
+    readonly SCROLL_IDLE_FALLBACK_MS: 300;
+    readonly SCROLL_DEBOUNCE_FALLBACK_MS: 50;
+    readonly SNAP_RESTORE_DELAY_MS: 100;
+    readonly RESIZE_DEBOUNCE_MS: 100;
+    readonly SCROLL_PERSIST_DEBOUNCE_MS: 150;
+    readonly SCROLL_COMPLETION_DEBOUNCE_MS: 150;
+    readonly SCROLL_TARGET_TOLERANCE_RATIO: 0.5;
+};
+declare const LAYOUT_CONFIG: {
+    readonly GAP_MOBILE: 12;
+    readonly GAP_DESKTOP: 16;
+    readonly GAP_BREAKPOINT: 768;
+    readonly MIN_BUFFER_COUNT: 50;
+    readonly EDGE_TOLERANCE_START: 20;
+    readonly EDGE_TOLERANCE_END: 5;
+    readonly INITIAL_CARD_WIDTH: 180;
+    readonly INITIAL_GAP: 16;
+};
+declare const DEBUG_CONFIG: {
+    ENABLED: boolean;
+    HISTORY_SIZE: number;
+    CHANNELS: {
+        ALL: boolean;
+        TELEPORT: boolean;
+        VISUALS: boolean;
+        LAYOUT: boolean;
+        INIT: boolean;
+        CACHE: boolean;
+        COORDINATOR: boolean;
+        NAV: boolean;
+        INTERACT: boolean;
+        PERF: boolean;
+    };
+};
+declare const FEATURE_FLAGS: {
+    readonly USE_RAF_FRAME_SEPARATION: true;
+};
+
+type DebugChannel = keyof typeof DEBUG_CONFIG.CHANNELS;
+type ChannelConfig = Partial<Record<DebugChannel, boolean>> | 'ALL';
+interface LoggerConfig {
+    /** Override channel activation for this instance (or 'ALL' for everything) */
+    channels?: ChannelConfig;
+    /** Max entries in local buffer (default: 100) */
+    bufferSize?: number;
+}
+declare class CarouselLoggerInstance {
+    readonly id: string;
+    private localHistory;
+    private maxLocalHistory;
+    private channelOverrides;
+    private registry;
+    constructor(id: string, config?: LoggerConfig);
+    /**
+     * Check if a channel should log to console.
+     * Resolution order: instance override → global config
+     */
+    private shouldLog;
+    /**
+     * Log a message to history buffers and optionally to console.
+     */
+    log(channel: DebugChannel, message: string, data?: unknown): void;
+    /**
+     * Dump this instance's local history to console.
+     */
+    dump(): string;
+    /** Clear local history */
+    clear(): void;
+    /**
+     * Create a performance timer for tracking elapsed time.
+     * Usage:
+     *   const timer = logger.createTimer()
+     *   // ... do work ...
+     *   logger.log('INIT', 'Completed', { elapsedMs: timer.elapsed() })
+     */
+    createTimer(): {
+        elapsed: () => number;
+        reset: () => void;
+    };
+}
+/**
+ * Create a new logger instance for a carousel.
+ *
+ * @param id - Unique identifier for this carousel (e.g., 'hero', 'related-products')
+ * @param config - Optional configuration for channel overrides and buffer size
+ *
+ * @example
+ * ```tsx
+ * // In BaseCarousel
+ * const logger = createLogger(debugId, { channels: { NAV: true } })
+ *
+ * // Pass to hooks
+ * const navigation = useCarouselNavigation({ ..., logger })
+ * ```
+ */
+declare function createLogger(id: string, config?: LoggerConfig): CarouselLoggerInstance;
+declare const carouselLogger: CarouselLoggerInstance;
+
+/**
+/** Available CSS variable names for carousel item widths */
+type CarouselWidthVar = 'default' | 'review' | 'compact' | 'collection' | 'wide';
+interface BaseCarouselProps<T> {
+    items: T[];
+    getItemKey: (item: T, index: number) => string;
+    renderItem: (item: T, index: number, helpers: {
+        scrollToItem: () => void;
+    }) => ReactNode;
+    infinite?: boolean;
+    onEndReached?: () => void;
+    hasNextPage?: boolean;
+    /**
+     * CSS variable name for item width. Uses native CSS media queries for responsive widths.
+     * Options: 'default' | 'review' | 'compact' | 'collection' | 'wide'
+     * @deprecated Use itemWidthCssVar for full flexibility
+     */
+    itemWidthVar?: CarouselWidthVar;
+    /**
+     * Custom CSS variable name for item width (e.g., '--my-carousel-item-width').
+     * Use this for full flexibility - define your own CSS variable with responsive breakpoints.
+     * Takes precedence over itemWidthVar when provided.
+     */
+    itemWidthCssVar?: string;
+    /**
+     * Fallback width in pixels when using itemWidthCssVar and the CSS variable is undefined.
+     * Required when using itemWidthCssVar. Defaults to 200 if not provided.
+     */
+    fallbackWidth?: number;
+    itemClassName?: string;
+    snapType?: 'mandatory' | 'proximity';
+    disableOpacityEffect?: boolean;
+    disableScaleEffect?: boolean;
+    /** Custom vertical padding for the carousel container. Defaults to '20px'. */
+    verticalPadding?: string;
+    snap?: boolean;
+    /** Optional custom skeleton renderer. Receives index. */
+    renderSkeleton?: (index: number) => ReactNode;
+    /**
+     * Optional key for persisting scroll position in sessionStorage.
+     * When provided, the carousel will restore its scroll position after navigation.
+     * Use a unique key per carousel instance, e.g., 'homepage-recommended'.
+     */
+    persistKey?: string;
+    onActiveItemChange?: (item: T) => void;
+    /** Optional explicit gap value in pixels. If not provided, uses LAYOUT_CONFIG based on viewport. */
+    gap?: number;
+    /** Optional id for debug logging - helps identify which carousel in console */
+    debugId?: string;
+    /**
+     * Optional per-instance debug config.
+     * Set `channels` to override global config for this carousel only.
+     * Use 'ALL' to enable all channels.
+     */
+    debug?: {
+        channels?: ChannelConfig;
+        bufferSize?: number;
+    };
+    /**
+     * Optional initial index to scroll to on mount.
+     * Takes precedence over buffer positioning but yields to persisted position if available.
+     */
+    initialIndex?: number;
+    /**
+     * If true, changes the selection threshold on mobile (viewport < 640px) from 0.5 (50%) to 0.3 (30%)
+     * This makes the carousel select the next/prev item with less swipe distance.
+     */
+    eagerSelectionOnMobile?: boolean;
+}
+declare function BaseCarouselInner<T>({ items, getItemKey, renderItem, infinite, onEndReached, hasNextPage, itemWidthVar, itemWidthCssVar, fallbackWidth, itemClassName, snapType, disableOpacityEffect, disableScaleEffect, verticalPadding, snap, renderSkeleton, persistKey, onActiveItemChange, gap: gapProp, debugId, debug, eagerSelectionOnMobile, initialIndex, }: BaseCarouselProps<T>): react_jsx_runtime.JSX.Element;
+declare const Carousel: typeof BaseCarouselInner;
+
+type Direction = 'left' | 'right';
+interface CarouselArrowProps {
+    direction: Direction;
+    onClick: () => void;
+    disabled?: boolean;
+    className?: string;
+}
+declare function CarouselArrow({ direction, onClick, disabled, className, }: CarouselArrowProps): react_jsx_runtime.JSX.Element;
+
+type CarouselPhase = 'UNINITIALIZED' | 'IDLE' | 'SCROLLING' | 'BOUNCING' | 'PRE_TELEPORTING' | 'TELEPORTING' | 'DRAGGING';
+interface CarouselContext {
+    phase: CarouselPhase;
+    pendingTarget: number | null;
+    scrollDirection: -1 | 1 | null;
+    teleportOffset: number | null;
+    isTeleporting: boolean;
+    isPreTeleporting: boolean;
+    lastActiveItemKey: string | null;
+    snapTimeoutId: ReturnType<typeof setTimeout> | null;
+    scrollIdleTimeoutId: ReturnType<typeof setTimeout> | null;
+    bounceTimeoutId: ReturnType<typeof setTimeout> | null;
+    hasScrollEndListener: boolean;
+}
+type CarouselAction = {
+    type: 'INITIALIZE';
+} | {
+    type: 'ARROW_CLICK';
+    direction: -1 | 1;
+    targetScroll: number;
+} | {
+    type: 'ITEM_CLICK';
+    targetScroll: number;
+} | {
+    type: 'SCROLL_COMPLETE';
+} | {
+    type: 'USER_INTERRUPT';
+} | {
+    type: 'START_BOUNCE';
+    timeoutId: ReturnType<typeof setTimeout>;
+} | {
+    type: 'END_BOUNCE';
+} | {
+    type: 'START_PRE_TELEPORT';
+} | {
+    type: 'EXECUTE_TELEPORT';
+    offset: number;
+} | {
+    type: 'END_TELEPORT';
+} | {
+    type: 'START_DRAG';
+} | {
+    type: 'END_DRAG';
+} | {
+    type: 'SET_SNAP_TIMEOUT';
+    timeoutId: ReturnType<typeof setTimeout>;
+} | {
+    type: 'CLEAR_SNAP_TIMEOUT';
+} | {
+    type: 'SET_SCROLL_IDLE_TIMEOUT';
+    timeoutId: ReturnType<typeof setTimeout>;
+} | {
+    type: 'CLEAR_SCROLL_IDLE_TIMEOUT';
+} | {
+    type: 'SET_SCROLL_END_LISTENER';
+    hasListener: boolean;
+} | {
+    type: 'SET_ACTIVE_ITEM_KEY';
+    key: string | null;
+} | {
+    type: 'SET_TELEPORTING';
+    value: boolean;
+} | {
+    type: 'SET_PRE_TELEPORTING';
+    value: boolean;
+} | {
+    type: 'SET_PENDING_TARGET';
+    target: number;
+};
+declare function reduce(context: CarouselContext, action: CarouselAction): CarouselContext;
+interface UseCarouselCoordinatorOptions {
+    /** Optional logger for debugging */
+    logger?: CarouselLoggerInstance;
+}
+interface UseCarouselCoordinatorReturn {
+    /** Dispatch an action to transition state */
+    transition: (action: CarouselAction) => CarouselContext;
+    /** Get current phase */
+    getPhase: () => CarouselPhase;
+    /** Get full context (read-only snapshot) */
+    getContext: () => Readonly<CarouselContext>;
+    /** Direct ref access (for passing to child hooks) */
+    contextRef: React.MutableRefObject<CarouselContext>;
+    /** Check if currently in a "busy" phase (not idle) */
+    isBusy: () => boolean;
+    /** Check if user interaction should be blocked */
+    isBlocking: () => boolean;
+}
+/**
+ * Carousel Coordinator Hook
+ *
+ * Consolidates all carousel state into a single ref-based state machine.
+ * No re-renders triggered - all state is in refs.
+ *
+ * @example
+ * ```tsx
+ * const { transition, getPhase, getContext } = useCarouselCoordinator({ logger })
+ *
+ * // Check state
+ * if (getPhase() === 'IDLE') {
+ *   transition({ type: 'ARROW_CLICK', direction: 1, targetScroll: 500 })
+ * }
+ *
+ * // Later, on scroll complete
+ * transition({ type: 'SCROLL_COMPLETE' })
+ * ```
+ */
+declare function useCarouselCoordinator(options?: UseCarouselCoordinatorOptions): UseCarouselCoordinatorReturn;
+
+interface UseCarouselLayoutOptions {
+    /** Ref to the scrollable carousel container */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Callback when layout is measured (for updating visual caches) */
+    onLayoutChange?: (layout: {
+        cardWidth: number;
+        gap: number;
+    }) => void;
+    /** Debounce delay for resize handling in ms. Default: 100 */
+    resizeDebounceMs?: number;
+    /** Optional logger for debugging */
+    logger?: CarouselLoggerInstance;
+}
+interface UseCarouselLayoutReturn {
+    /** Current layout measurements */
+    layout: {
+        cardWidth: number;
+        gap: number;
+        domStride: number;
+    };
+    /** Computed stride (cardWidth + gap) - fallback if domStride unavailable */
+    stride: number;
+    /** Whether viewport is mobile (< 640px) */
+    isMobile: boolean;
+    /** Whether viewport is tablet (< 1024px but >= 640px) */
+    isTablet: boolean;
+    /** Manually trigger a layout measurement */
+    measureLayout: () => {
+        cardWidth: number;
+        gap: number;
+    };
+    /** Mark layout as dirty (triggers remeasure on next access) */
+    invalidateLayout: () => void;
+    /**
+     * Counter that increments each time ResizeObserver fires.
+     * Used to trigger re-checks even when layout values are unchanged.
+     */
+    resizeCount: number;
+}
+/**
+ * Calculate layout measurements from a carousel container element.
+ * Reads the first child's width and determines gap based on breakpoint.
+ *
+ * @param container - The scrollable carousel container element
+ * @returns The measured cardWidth and gap values, or null if children aren't rendered yet
+ */
+declare function measureLayoutFromElement(container: HTMLElement): {
+    cardWidth: number;
+    gap: number;
+    domStride: number;
+} | null;
+/**
+ * Hook that manages carousel layout measurements.
+ * Handles:
+ * - Initial layout measurement from first card element
+ * - Viewport detection (mobile, tablet, desktop)
+ * - Resize handling with debouncing
+ * - Stride calculation
+ */
+declare function useCarouselLayout({ containerRef, onLayoutChange, resizeDebounceMs, logger, }: UseCarouselLayoutOptions): UseCarouselLayoutReturn;
+
+interface UseCarouselNavigationOptions {
+    /** Ref to the scrollable carousel container */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Whether this is an infinite carousel */
+    infinite: boolean;
+    /** Layout measurements */
+    layout: {
+        cardWidth: number;
+        gap: number;
+    };
+    /** Function to cancel momentum scroll (from useDraggableScroll) */
+    cancelMomentum: () => void;
+    /** Pre-teleport function for infinite carousels (from useCarouselTeleport) */
+    preTeleport?: (targetScroll: number) => number;
+    /** Callback when navigating to a new item */
+    onNavigate?: (targetScroll: number) => void;
+    /** Coordinator for state management (REQUIRED in Phase 2+) */
+    coordinator: UseCarouselCoordinatorReturn;
+    /** Optional logger for debugging */
+    logger?: CarouselLoggerInstance;
+}
+interface UseCarouselNavigationReturn {
+    /** Navigate left (previous item) */
+    scrollLeft: () => void;
+    /** Navigate right (next item) */
+    scrollRight: () => void;
+    /** Direct access to navigation handler */
+    handleScrollNav: (direction: -1 | 1) => void;
+}
+/**
+ * Hook that handles arrow navigation for carousels.
+ *
+ * Phase 2: Uses coordinator as single source of truth for state.
+ * No more external ref passing - all state is managed via coordinator.
+ *
+ * Features:
+ * - Rapid-click "Catch-Up & Advance" strategy for smooth multi-click navigation
+ * - Bounce animation at edges for finite carousels
+ * - Pre-teleport integration for infinite carousels
+ * - Scroll completion detection (scrollend or debounce fallback)
+ */
+declare function useCarouselNavigation({ containerRef, infinite, layout, cancelMomentum, preTeleport, onNavigate, coordinator, logger, }: UseCarouselNavigationOptions): UseCarouselNavigationReturn;
+
+interface UseCarouselPersistenceOptions {
+    /** Unique key for this carousel's scroll position in sessionStorage */
+    persistKey?: string;
+    /** Debounce delay in ms for saving scroll position. Default: 150 */
+    debounceMs?: number;
+}
+interface UseCarouselPersistenceReturn {
+    /** Get saved scroll position from sessionStorage (null if not found) */
+    getSavedPosition: () => number | null;
+    /** Save current scroll position to sessionStorage (debounced) */
+    savePosition: (scrollLeft: number) => void;
+    /** Immediately save position (no debounce, for unmount) */
+    savePositionImmediate: (scrollLeft: number) => void;
+    /** Clear saved position from sessionStorage */
+    clearPosition: () => void;
+}
+/**
+ * Hook for persisting carousel scroll position across navigation.
+ *
+ * Uses sessionStorage so position survives:
+ * - Browser back/forward navigation
+ * - Same-tab navigation
+ *
+ * But resets on:
+ * - New tab/window
+ * - Browser close
+ *
+ * @example
+ * ```tsx
+ * const { getSavedPosition, savePosition } = useCarouselPersistence({
+ *   persistKey: 'homepage-featured'
+ * })
+ *
+ * // On mount
+ * useEffect(() => {
+ *   const saved = getSavedPosition()
+ *   if (saved !== null) containerRef.current.scrollLeft = saved
+ * }, [])
+ *
+ * // On scroll
+ * const handleScroll = () => savePosition(containerRef.current.scrollLeft)
+ * ```
+ */
+declare function useCarouselPersistence({ persistKey, debounceMs, }?: UseCarouselPersistenceOptions): UseCarouselPersistenceReturn;
+
+interface UseCarouselTeleportOptions {
+    /** Ref to the scrollable carousel container */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Whether this is an infinite carousel */
+    infinite: boolean;
+    /** Number of items in the original set */
+    itemsCount: number;
+    /** Width of each card in pixels */
+    cardWidth: number;
+    /** Gap between cards in pixels */
+    gap: number;
+    /** Number of buffer items before the original set */
+    bufferBeforeCount: number;
+    /** Function to apply visual effects after teleport */
+    applyVisuals: (el: HTMLElement, scrollLeft?: number) => void;
+    /** Function to adjust scroll tracking in useDraggableScroll */
+    adjustScroll: (delta: number) => void;
+    /** Delay in ms before clearing pre-teleport flag */
+    preTeleportClearDelayMs: number;
+    /** Coordinator for state management (required - Phase 3) */
+    coordinator: UseCarouselCoordinatorReturn;
+    /** Optional logger for debugging */
+    logger?: CarouselLoggerInstance;
+}
+/**
+ * Hook that handles the teleport logic for infinite carousels.
+ *
+ * THE TELEPORT LOOP - HYBRID STRATEGY
+ * Desktop (mouse): Teleport during scroll - works perfectly, no compositor conflict
+ * Mobile (touch):
+ *   - Teleport on 'scrollend' - natural stop after momentum
+ *   - Teleport on 'pointerdown' - "catch & reset" when user touches during momentum
+ */
+declare function useCarouselTeleport({ containerRef, infinite, itemsCount, cardWidth, gap, bufferBeforeCount, applyVisuals, adjustScroll, preTeleportClearDelayMs, coordinator, logger, }: UseCarouselTeleportOptions): {
+    /** Ref to track if current interaction is touch-based */
+    isTouchInteraction: react.MutableRefObject<boolean>;
+    /** Proactive pre-teleport for arrow navigation */
+    preTeleport: (targetScroll: number) => number;
+};
+
+interface UseCarouselVisualsOptions {
+    /** Layout measurements */
+    layout: {
+        cardWidth: number;
+        gap: number;
+    };
+    /** Number of items (used to detect cache invalidation) */
+    itemsCount: number;
+    /** Buffer items before original set */
+    bufferBeforeCount: number;
+    /** Disable opacity effect */
+    disableOpacityEffect: boolean;
+    /** Disable scale effect */
+    disableScaleEffect: boolean;
+    /** Optional logger for debugging */
+    logger?: CarouselLoggerInstance;
+}
+interface ChildPosition {
+    left: number;
+    width: number;
+}
+/**
+ * Hook that manages visual effects for carousel items.
+ * Handles:
+ * - Position cache for children (offsetLeft, offsetWidth)
+ * - Container width cache (to avoid layout thrashing)
+ * - Apply visual effects (scale, opacity, shadow, z-index)
+ * - Viewport culling (skip items outside visible area)
+ */
+declare function useCarouselVisuals({ layout, itemsCount, bufferBeforeCount, disableOpacityEffect, disableScaleEffect, logger, }: UseCarouselVisualsOptions): {
+    /** Position cache for all children */
+    childrenPositions: react.MutableRefObject<ChildPosition[]>;
+    /** Whether the cache needs to be rebuilt */
+    isCacheDirty: react.MutableRefObject<boolean>;
+    /** Container width cache ref */
+    containerWidthRef: react.MutableRefObject<number>;
+    /** Whether container width needs to be remeasured */
+    isContainerWidthDirty: react.MutableRefObject<boolean>;
+    /** Update the position cache */
+    updateCache: (el: HTMLElement) => void;
+    /** Apply visual effects to visible items */
+    applyVisuals: (el: HTMLElement, overrideScrollLeft?: number) => void;
+};
+
+interface UseDraggableScrollOptions {
+    infinite?: boolean;
+    hasNextPage?: boolean;
+    onEndReached?: () => void;
+    cardWidth?: number;
+    gap?: number;
+    cloneCount?: number;
+    friction?: number;
+    maxVelocity?: number;
+}
+declare function useDraggableScroll({ infinite, hasNextPage, onEndReached, cardWidth, gap, cloneCount, friction, maxVelocity, }?: UseDraggableScrollOptions): {
+    ref: react.RefObject<HTMLDivElement>;
+    isDragging: boolean;
+    cancelMomentum: () => void;
+    adjustScroll: (delta: number) => void;
+    events: {
+        onPointerDown: (e: PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (e: PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (e: PointerEvent<HTMLDivElement>) => void;
+        onLostPointerCapture: (e: PointerEvent<HTMLDivElement>) => void;
+        onClickCapture: (e: MouseEvent) => void;
+        onDragStart: (e: MouseEvent) => void;
+    };
+};
+
+interface UseLoadingStateOptions {
+    /** Unique key for session cache. If provided, enables caching behavior. */
+    cacheKey?: string;
+    /** Delay in ms before showing skeleton. Default: 500 */
+    skeletonDelay?: number;
+    /** Hard fallback timeout in ms. Guarantees isReady after this. Default: 3000 */
+    fallbackTimeout?: number;
+    /**
+     * If true, start in ready state immediately (e.g., for already-mounted carousels).
+     * Useful when the component should skip the loading phase entirely.
+     */
+    startReady?: boolean;
+}
+interface UseLoadingStateReturn {
+    /** True when resource is loaded OR fallback has fired */
+    isReady: boolean;
+    /** True if loading takes longer than skeletonDelay AND resource is not cached */
+    showSkeleton: boolean;
+    /** True if resource was cached (instant load, no fade needed) */
+    isInstant: boolean;
+    /** Call this when your resource finishes loading (e.g., image onLoad) */
+    markReady: () => void;
+}
+/**
+ * Unified hook for managing loading states with:
+ * - First load: fade in, optional skeleton after delay
+ * - Cached load: instant (no fade, no skeleton)
+ * - Strict fallback: guaranteed ready after timeout
+ */
+declare function useLoadingState({ cacheKey, skeletonDelay, fallbackTimeout, startReady, }?: UseLoadingStateOptions): UseLoadingStateReturn;
+/**
+ * Utility to clear the session cache (for testing)
+ */
+declare function clearLoadingStateCache(): void;
+
+interface UseScrollCompletionOptions {
+    ref: React.RefObject<HTMLElement | null>;
+    onComplete: (source: string) => void;
+    /** Optional shared ref to track the listener for cleanup */
+    listenerRef?: React.MutableRefObject<(() => void) | null>;
+    /** Optional shared ref for the safety timeout */
+    timeoutRef?: React.MutableRefObject<NodeJS.Timeout | null>;
+}
+/**
+ * Hook to handle scroll completion detection across browsers.
+ * Uses native `scrollend` event where available, falls back to debounce pattern.
+ */
+declare function useScrollCompletion({ ref, onComplete, listenerRef, timeoutRef }: UseScrollCompletionOptions): {
+    waitForScrollCompletion: (timeoutDuration?: 300) => void;
+};
+
+export { Carousel, type CarouselAction, CarouselArrow, type CarouselContext, CarouselLoggerInstance, type CarouselPhase, type ChannelConfig, type ChildPosition, DEBUG_CONFIG, type DebugChannel, FEATURE_FLAGS, LAYOUT_CONFIG, type LoggerConfig, TIMING_CONFIG, type UseCarouselCoordinatorOptions, type UseCarouselCoordinatorReturn, type UseCarouselLayoutOptions, type UseCarouselLayoutReturn, type UseCarouselNavigationOptions, type UseCarouselNavigationReturn, type UseCarouselPersistenceOptions, type UseCarouselPersistenceReturn, type UseCarouselTeleportOptions, type UseCarouselVisualsOptions, type UseLoadingStateOptions, type UseLoadingStateReturn, type UseScrollCompletionOptions, VISUAL_CONFIG, carouselLogger, clearLoadingStateCache, createLogger, measureLayoutFromElement, reduce, useCarouselCoordinator, useCarouselLayout, useCarouselNavigation, useCarouselPersistence, useCarouselTeleport, useCarouselVisuals, useDraggableScroll, useLoadingState, useScrollCompletion };