gsap-react-marquee 0.1.3 → 0.1.5

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,24 +98,119 @@ 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
+ * Traverses the DOM tree upward to find the first non-transparent background color
+ *
+ * This function walks up the element hierarchy starting from the given element,
+ * checking each parent's computed backgroundColor style until it finds a visible
+ * (non-transparent) background color. This is useful for automatically detecting
+ * the effective background behind an element for gradient overlays.
+ *
+ * The traversal stops at the first element with a visible background color,
+ * which could be the element itself or any of its ancestors up to the document root.
+ *
+ * @param el - The HTMLElement to start the background color search from
+ * @returns The first non-transparent background color found in the hierarchy,
+ *          or "transparent" if no visible background is found
+ *
+ * @example
+ * // Element with white parent background
+ * const color = getEffectiveBackgroundColor(marqueeElement);
+ * // Returns: "rgb(255, 255, 255)" or "#ffffff"
+ *
+ * @example
+ * // Element with no background set anywhere in hierarchy
+ * const color = getEffectiveBackgroundColor(marqueeElement);
+ * // Returns: "transparent"
+ */
+declare const getEffectiveBackgroundColor: (el: HTMLElement) => string;
+/**
+ * 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;
 
-export { calculateDuplicates, cn, coreAnimation, GSAPReactMarquee as default, getMinWidth, setupContainerStyles };
+export { calculateDuplicates, cn, coreAnimation, GSAPReactMarquee as default, getEffectiveBackgroundColor, getMinWidth, setupContainerStyles };
 export type { GSAPReactMarqueeProps };

package/dist/index.esm.css

@@ -1 +1 @@
-.gsap-react-marquee{flex:1;height:max-content;width:auto}.gsap-react-marquee,.gsap-react-marquee-content{display:flex;line-height:100%;white-space:preserve nowrap}.gsap-react-marquee-content{overflow:hidden;width:max-content}
+.gsap-react-marquee-container:after{background:linear-gradient(270deg,hsla(0,0%,100%,0) 0,var(--gradient-color) 75%);content:"";height:100%;left:0;position:absolute;top:0;width:15%;z-index:10}.gsap-react-marquee-container:before{background:linear-gradient(90deg,hsla(0,0%,100%,0) 0,var(--gradient-color) 75%);content:"";height:100%;position:absolute;right:0;top:0;width:15%;z-index:10}.gsap-react-marquee{flex:1;height:max-content;width:auto}.gsap-react-marquee,.gsap-react-marquee-content{display:flex;line-height:100%;white-space:preserve nowrap}.gsap-react-marquee-content{overflow:hidden;width:max-content}