gsap-react-marquee 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -87,8 +87,9 @@ type GSAPReactMarqueeProps = {
      */
     followScrollDir?: boolean;
     /**
-     * @description Speed factor when syncing with page scroll
+     * @description Speed factor when syncing with page scroll, max value is 4
      * @type {number}
+     * @default 2.5
      */
     scrollSpeed?: number;
 };
@@ -97,22 +98,91 @@ declare const GSAPReactMarquee: react.ForwardRefExoticComponent<GSAPReactMarquee
 
 /**
  * Utility function to merge Tailwind classes with clsx
+ *
+ * Combines clsx for conditional classes with tailwind-merge to handle
+ * conflicting Tailwind classes by keeping the last occurrence.
+ * This prevents issues like "p-4 p-2" where both would be applied.
+ *
+ * @param inputs - Array of class values (strings, conditionals, objects)
+ * @returns Merged and deduplicated class string
  */
 declare const cn: (...inputs: ClassValue[]) => string;
 /**
- * Sets up container styles and rotation handling
+ * Sets up container styles and rotation handling for the marquee
+ *
+ * This function handles the complex styling requirements for different marquee orientations:
+ *
+ * 1. **Basic Setup**: Applies gap spacing and rotation for vertical marquees
+ * 2. **Vertical Mode**: Rotates container 90° and adjusts width to parent height
+ * 3. **Rotation Alignment**: Special mode for vertical text that remains readable
+ *
+ * @param containerMarquee - The main container element that holds all marquee instances
+ * @param marquees - Array of individual marquee wrapper elements
+ * @param marqueesChildren - Array of content container elements within each marquee
+ * @param isVertical - Boolean indicating if marquee moves up/down instead of left/right
+ * @param props - Configuration object containing spacing and alignment options
  */
 declare const setupContainerStyles: (containerMarquee: HTMLElement, marquees: HTMLElement[], marqueesChildren: HTMLElement[], isVertical: boolean, props: GSAPReactMarqueeProps) => void;
 /**
- * Calculates the number of duplicates needed to fill the container
+ * Calculates the number of content duplicates needed for seamless looping
+ *
+ * For smooth infinite scrolling, we need enough content copies to fill the visible area
+ * plus buffer space. This prevents gaps when content loops back to the beginning.
+ *
+ * Algorithm:
+ * 1. If not in fill mode, only one copy is needed (content already spans container)
+ * 2. Determine target width (viewport height for vertical, container width for horizontal)
+ * 3. Calculate how many copies fit in the target space, rounding up for complete coverage
+ *
+ * @param marqueeChildrenWidth - Width of a single content instance
+ * @param containerMarqueeWidth - Width of the marquee container
+ * @param isVertical - Whether the marquee scrolls vertically
+ * @param props - Configuration object containing fill mode setting
+ * @returns Number of content duplicates needed (minimum 1)
  */
 declare const calculateDuplicates: (marqueeChildrenWidth: number, containerMarqueeWidth: number, isVertical: boolean, props: GSAPReactMarqueeProps) => number;
 /**
- * Determines the minimum width for marquee elements
+ * Determines the minimum width for marquee elements based on content and container
+ *
+ * This function ensures marquee elements have appropriate dimensions for their content
+ * and container context, handling different modes and orientations.
+ *
+ * Width determination logic:
+ * 1. **Fill mode**: Auto width lets content size naturally
+ * 2. **Rotation alignment**: Use content height as width (rotated dimensions)
+ * 3. **Undersized content**: Stretch to 100% to fill container
+ * 4. **Oversized content**: Use actual content width for overflow scrolling
+ *
+ * @param marqueesChildren - Array of content elements for dimension measurement
+ * @param totalWidth - Combined width of all content elements
+ * @param containerMarqueeWidth - Available container width
+ * @param props - Configuration object containing fill and alignment settings
+ * @returns CSS width value (string with units or number for pixels)
  */
 declare const getMinWidth: (marqueesChildren: HTMLElement[], totalWidth: number, containerMarqueeWidth: number, props: GSAPReactMarqueeProps) => string | number;
 /**
  * Creates a complex fill-based marquee animation with seamless looping
+ *
+ * This is the core animation engine that creates smooth, continuous scrolling.
+ * It handles the complex math required for seamless looping by calculating
+ * precise positions and durations for each content element.
+ *
+ * Animation Strategy:
+ * 1. **Position Calculation**: Convert pixel positions to percentages for responsive scaling
+ * 2. **Seamless Looping**: Calculate track length and loop points to prevent gaps
+ * 3. **Staggered Animation**: Each element starts at different times for smooth flow
+ * 4. **Direction Handling**: Support forward and reverse directions with proper timing
+ *
+ * Technical Details:
+ * - Uses xPercent for percentage-based positioning (responsive to element width changes)
+ * - Creates two-part animation: main movement + seamless loop reset
+ * - Calculates precise durations based on distance and speed for consistent motion
+ *
+ * @param elementsToAnimate - Array of DOM elements to animate (content or containers)
+ * @param startX - Starting X position reference point
+ * @param tl - GSAP timeline to add animations to
+ * @param isReverse - Whether animation should play in reverse direction
+ * @param props - Configuration object with spacing, speed, delay, and other settings
  */
 declare const coreAnimation: (elementsToAnimate: HTMLElement[], startX: number, tl: gsap.core.Timeline, isReverse: boolean, props: GSAPReactMarqueeProps) => void;