react-scroll-media 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Public type definitions for react-scroll-media
+ */
+type SequenceSource = {
+    type: 'manual';
+    frames: string[];
+} | {
+    type: 'pattern';
+    url: string;
+    start?: number;
+    end: number;
+    pad?: number;
+} | {
+    type: 'manifest';
+    url: string;
+};
+interface ScrollSequenceProps {
+    /**
+     * Source configuration for the image sequence.
+     * Can be 'manual', 'pattern', or 'manifest'.
+     */
+    source: SequenceSource;
+    /** If true, shows a debug overlay with progress and frame info. */
+    debug?: boolean;
+    /**
+     * Memory management strategy.
+     * 'eager' (default): Preloads all images on mount. Smooth playback, higher memory.
+     * 'lazy': Loads images only when needed (curren frame ±3). Saves memory, may stutter on slow networks.
+     */
+    memoryStrategy?: 'eager' | 'lazy';
+    /**
+     * Buffer size for lazy loading (default 10).
+     * Number of frames to keep loaded around the current frame.
+     */
+    lazyBuffer?: number;
+    /** CSS height for the scroll container. Defines the total scroll distance. */
+    scrollLength?: string;
+    /** CSS class name for the container div. */
+    className?: string;
+    /** Optional children to render inside the sticky container (e.g. ScrollText). */
+    children?: React.ReactNode;
+    /** Component to render while the sequence is loading. */
+    fallback?: React.ReactNode;
+    /** Accessibility label for the canvas (role="img"). Defaults to "Scroll sequence". */
+    accessibilityLabel?: string;
+    /** Callback fired when an error occurs (e.g. image load failure). */
+    onError?: (error: Error) => void;
+}
+interface ResolvedSequence {
+    /** Sorted array of frame URLs (sorted numerically by filename). */
+    frames: string[];
+    /** Total number of frames. */
+    frameCount: number;
+}
+interface ScrollProgress {
+    /** Progress value between 0 and 1. */
+    progress: number;
+    /** Current scroll position in pixels. */
+    scrollTop: number;
+    /** Total scrollable height in pixels. */
+    scrollHeight: number;
+    /** Viewport height in pixels. */
+    viewportHeight: number;
+}
+
+declare const ScrollSequence: React__default.ForwardRefExoticComponent<ScrollSequenceProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface UseScrollSequenceParams {
+    source: ScrollSequenceProps['source'];
+    debugRef?: React.MutableRefObject<HTMLDivElement | null>;
+    memoryStrategy?: 'eager' | 'lazy';
+    lazyBuffer?: number;
+    onError?: (error: Error) => void;
+}
+/**
+ * Hook to manage image sequence in a timeline context.
+ * MUST be used inside ScrollTimelineProvider.
+ */
+declare function useScrollSequence({ source, debugRef, memoryStrategy, lazyBuffer, onError, }: UseScrollSequenceParams): {
+    canvasRef: React$1.RefObject<HTMLCanvasElement>;
+    isLoaded: boolean;
+    error: Error | null;
+};
+
+interface ScrollTimelineProviderProps {
+    children: React__default.ReactNode;
+    /** CSS height for the scroll container (e.g., "300vh"). */
+    scrollLength?: string;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function ScrollTimelineProvider({ children, scrollLength, className, style, }: ScrollTimelineProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ScrollTextProps {
+    children: React__default.ReactNode;
+    /** Progress start (0-1) where ENTRANCE animation begins */
+    start?: number;
+    /** Progress end (0-1) where ENTRANCE animation ends */
+    end?: number;
+    /** Progress start (0-1) where EXIT animation begins. If omitted, element stays visible. */
+    exitStart?: number;
+    /** Progress end (0-1) where EXIT animation ends */
+    exitEnd?: number;
+    /** Initial opacity */
+    initialOpacity?: number;
+    /** Target opacity (when entered) */
+    targetOpacity?: number;
+    /** Final opacity (after exit) */
+    finalOpacity?: number;
+    /** Y-axis translation range in pixels (e.g., 50 means move down 50px) */
+    translateY?: number;
+    style?: React__default.CSSProperties;
+    className?: string;
+}
+declare function ScrollText({ children, start, end, exitStart, exitEnd, initialOpacity, targetOpacity, finalOpacity, translateY, style, className, }: ScrollTextProps): react_jsx_runtime.JSX.Element;
+
+interface ScrollWordRevealProps {
+    text: string;
+    /** Progress start (0-1) */
+    start?: number;
+    /** Progress end (0-1) */
+    end?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function ScrollWordReveal({ text, start, end, className, style }: ScrollWordRevealProps): react_jsx_runtime.JSX.Element;
+
+type TimelineCallback = (progress: number) => void;
+declare class ScrollTimeline {
+    private container;
+    private subscribers;
+    private currentProgress;
+    private cachedRect;
+    private cachedScrollParent;
+    private cachedScrollParentRect;
+    private cachedViewportHeight;
+    private cachedOffsetTop;
+    private isLayoutDirty;
+    private resizeObserver;
+    readonly id: string;
+    constructor(container: Element);
+    private onWindowResize;
+    /**
+     * Subscribe to progress updates.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: TimelineCallback): () => void;
+    unsubscribe(callback: TimelineCallback): void;
+    /**
+     * Start is now handled by LoopManager via subscriptions
+     * Deprecated but kept for API stability if needed.
+     */
+    start(): void;
+    stop(): void;
+    private tick;
+    private notify;
+    private updateCache;
+    private calculateProgress;
+    private getScrollParent;
+    destroy(): void;
+}
+
+interface UseScrollTimelineResult {
+    /**
+     * Manual subscription to the timeline.
+     * Useful for low-level DOM updates (refs) without re-rendering.
+     */
+    subscribe: (callback: TimelineCallback) => () => void;
+    /** The raw timeline instance (for advanced usage) */
+    timeline: ScrollTimeline | null;
+}
+declare function useScrollTimeline(): UseScrollTimelineResult;
+
+/**
+ * Clamps a value between a minimum and maximum.
+ * Default range is [0, 1], suitable for progress values.
+ *
+ * @param value - The value to clamp
+ * @param min - Minimum value (default: 0)
+ * @param max - Maximum value (default: 1)
+ * @returns The clamped value
+ */
+declare function clamp(value: number, min?: number, max?: number): number;
+
+/**
+ * SequenceResolver
+ * Handles intelligent frame resolution from multiple input sources:
+ * - Manual frame list (frames[])
+ * - Pattern generation (pattern, start, end, pad)
+ * - Remote manifest (manifest URL)
+ */
+
+/**
+ * Resolves frame sequence from props.
+ * Prioritizes: frames > pattern > manifest
+ */
+/**
+ * Resolves frame sequence from props.
+ * Handles 'manual', 'pattern', and 'manifest' sources.
+ */
+declare function resolveSequence(source: ScrollSequenceProps['source']): Promise<ResolvedSequence>;
+
+/**
+ * ImageController
+ * Manages canvas rendering, image loading, and frame-by-frame drawing.
+ * Handles preloading and caching to minimize redraws.
+ */
+interface ImageControllerConfig {
+    /** HTMLCanvasElement to draw on */
+    canvas: HTMLCanvasElement;
+    /** Array of sorted frame URLs */
+    frames: string[];
+    /** Memory management strategy */
+    strategy?: 'eager' | 'lazy';
+    /** Lazy load buffer size (default 10) */
+    bufferSize?: number;
+}
+declare class ImageController {
+    private canvas;
+    private ctx;
+    private frames;
+    private imageCache;
+    private loadingPromises;
+    private currentFrameIndex;
+    private strategy;
+    private bufferSize;
+    /**
+     * Create a new ImageController instance.
+     *
+     * @param config - Configuration object
+     * @throws If canvas doesn't support 2D context
+     */
+    private isDestroyed;
+    constructor(config: ImageControllerConfig);
+    private preloadAll;
+    private ensureFrameWindow;
+    preloadFrame(index: number): Promise<void>;
+    private loadImage;
+    update(progress: number): void;
+    private drawFrame;
+    setCanvasSize(width: number, height: number): void;
+    destroy(): void;
+}
+
+export { ImageController, type ImageControllerConfig, type ResolvedSequence, type ScrollProgress, ScrollSequence, type ScrollSequenceProps, ScrollText, ScrollTimeline, ScrollTimelineProvider, ScrollWordReveal, clamp, resolveSequence, useScrollSequence, useScrollTimeline };