react-native-puff-pop 1.0.4 → 1.0.5

package/README.md

@@ -102,6 +102,35 @@ By default, `skeleton={true}` reserves space for the component before animation:
 
 ### Staggered Animations
 
+Use `PuffPopGroup` for easy staggered animations:
+
+```tsx
+import { PuffPopGroup } from 'react-native-puff-pop';
+
+// Simple stagger
+<PuffPopGroup staggerDelay={100} effect="scale">
+  <Card title="First" />
+  <Card title="Second" />
+  <Card title="Third" />
+</PuffPopGroup>
+
+// With different directions
+<PuffPopGroup staggerDelay={80} staggerDirection="reverse">
+  <Item />
+  <Item />
+  <Item />
+</PuffPopGroup>
+
+// Horizontal layout with gap
+<PuffPopGroup horizontal gap={12} effect="slideUp">
+  <Avatar />
+  <Avatar />
+  <Avatar />
+</PuffPopGroup>
+```
+
+Or use manual delays with `PuffPop`:
+
 ```tsx
 <View>
   <PuffPop delay={0}>
@@ -172,6 +201,28 @@ function App() {
 | `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
 | `testID` | `string` | - | Test ID for testing purposes |
 
+### PuffPopGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Children to animate with stagger effect |
+| `effect` | `PuffPopEffect` | `'scale'` | Animation effect for all children |
+| `duration` | `number` | `400` | Animation duration for each child in ms |
+| `staggerDelay` | `number` | `100` | Delay between each child's animation in ms |
+| `initialDelay` | `number` | `0` | Delay before the first child animates in ms |
+| `easing` | `PuffPopEasing` | `'easeOut'` | Easing function for all children |
+| `skeleton` | `boolean` | `true` | Reserve space before animation |
+| `visible` | `boolean` | `true` | Control visibility of all children |
+| `animateOnMount` | `boolean` | `true` | Animate when component mounts |
+| `onAnimationStart` | `() => void` | - | Callback when first child starts animating |
+| `onAnimationComplete` | `() => void` | - | Callback when all children complete |
+| `style` | `ViewStyle` | - | Custom container style |
+| `staggerDirection` | `'forward' \| 'reverse' \| 'center' \| 'edges'` | `'forward'` | Direction of stagger animation |
+| `horizontal` | `boolean` | `false` | Render children in horizontal layout |
+| `gap` | `number` | - | Gap between children |
+| `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
+| `testID` | `string` | - | Test ID for testing purposes |
+
 ### Animation Effects (`PuffPopEffect`)
 
 | Effect | Description |

package/lib/module/index.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useCallback, useMemo, } from 'react';
+import { useEffect, useRef, useState, useCallback, useMemo, Children, } from 'react';
 import { View, Animated, StyleSheet, Easing, AccessibilityInfo, } from 'react-native';
 /**
  * Get easing function based on type
@@ -173,11 +173,19 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
             // Stop any existing loop animation
             if (loopAnimationRef.current) {
                 loopAnimationRef.current.stop();
+                loopAnimationRef.current = null;
+            }
+            // Clear any existing timeout
+            if (loopTimeoutRef.current) {
+                clearTimeout(loopTimeoutRef.current);
+                loopTimeoutRef.current = null;
             }
             const loopCount = typeof loop === 'number' ? loop : -1;
             let currentIteration = 0;
             const runLoop = () => {
                 resetValues();
+                // Store the current animation reference so it can be stopped
+                loopAnimationRef.current = animation;
                 animation.start(({ finished }) => {
                     if (finished) {
                         currentIteration++;
@@ -194,13 +202,17 @@ export function PuffPop({ children, effect = 'scale', duration = 400, delay = 0,
                                 runLoop();
                             }
                         }
-                        else if (onAnimationComplete) {
-                            onAnimationComplete();
+                        else {
+                            // Loop finished, clear reference
+                            loopAnimationRef.current = null;
+                            if (onAnimationComplete) {
+                                onAnimationComplete();
+                            }
                         }
                     }
                 });
             };
-            // Store reference and start
+            // Start the loop
             runLoop();
         }
         else {
@@ -372,5 +384,79 @@ const styles = StyleSheet.create({
     hidden: {
         opacity: 0,
     },
+    groupContainer: {},
 });
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ *
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export function PuffPopGroup({ children, effect = 'scale', duration = 400, staggerDelay = 100, initialDelay = 0, easing = 'easeOut', skeleton = true, visible = true, animateOnMount = true, onAnimationComplete, onAnimationStart, style, respectReduceMotion = true, testID, staggerDirection = 'forward', horizontal = false, gap, }) {
+    const childArray = Children.toArray(children);
+    const childCount = childArray.length;
+    const completedCount = useRef(0);
+    const hasCalledStart = useRef(false);
+    // Calculate delay for each child based on stagger direction
+    const getChildDelay = useCallback((index) => {
+        let delayIndex;
+        switch (staggerDirection) {
+            case 'reverse':
+                delayIndex = childCount - 1 - index;
+                break;
+            case 'center': {
+                const center = (childCount - 1) / 2;
+                delayIndex = Math.abs(index - center);
+                break;
+            }
+            case 'edges': {
+                const center = (childCount - 1) / 2;
+                delayIndex = center - Math.abs(index - center);
+                break;
+            }
+            case 'forward':
+            default:
+                delayIndex = index;
+                break;
+        }
+        return initialDelay + delayIndex * staggerDelay;
+    }, [childCount, initialDelay, staggerDelay, staggerDirection]);
+    // Handle individual child animation complete
+    const handleChildComplete = useCallback(() => {
+        completedCount.current += 1;
+        if (completedCount.current >= childCount && onAnimationComplete) {
+            onAnimationComplete();
+        }
+    }, [childCount, onAnimationComplete]);
+    // Handle first child animation start
+    const handleChildStart = useCallback(() => {
+        if (!hasCalledStart.current && onAnimationStart) {
+            hasCalledStart.current = true;
+            onAnimationStart();
+        }
+    }, [onAnimationStart]);
+    // Reset counters when visibility changes
+    useEffect(() => {
+        if (visible) {
+            completedCount.current = 0;
+            hasCalledStart.current = false;
+        }
+    }, [visible]);
+    const containerStyle = useMemo(() => {
+        const baseStyle = {
+            flexDirection: horizontal ? 'row' : 'column',
+        };
+        if (gap !== undefined) {
+            baseStyle.gap = gap;
+        }
+        return baseStyle;
+    }, [horizontal, gap]);
+    return (_jsx(View, { style: [styles.groupContainer, containerStyle, style], testID: testID, children: childArray.map((child, index) => (_jsx(PuffPop, { effect: effect, duration: duration, delay: getChildDelay(index), easing: easing, skeleton: skeleton, visible: visible, animateOnMount: animateOnMount, onAnimationComplete: handleChildComplete, onAnimationStart: index === 0 ? handleChildStart : undefined, respectReduceMotion: respectReduceMotion, children: child }, index))) }));
+}
 export default PuffPop;

package/lib/typescript/src/index.d.ts

@@ -88,4 +88,105 @@ export interface PuffPopProps {
  * PuffPop - Animate children with beautiful entrance effects
  */
 export declare function PuffPop({ children, effect, duration, delay, easing, skeleton, visible, onAnimationComplete, onAnimationStart, style, animateOnMount, loop, loopDelay, respectReduceMotion, testID, }: PuffPopProps): ReactElement;
+/**
+ * Props for PuffPopGroup component
+ */
+export interface PuffPopGroupProps {
+    /**
+     * Children to animate with stagger effect
+     */
+    children: ReactNode;
+    /**
+     * Animation effect type applied to all children
+     * @default 'scale'
+     */
+    effect?: PuffPopEffect;
+    /**
+     * Base animation duration in milliseconds for each child
+     * @default 400
+     */
+    duration?: number;
+    /**
+     * Delay between each child's animation start in milliseconds
+     * @default 100
+     */
+    staggerDelay?: number;
+    /**
+     * Initial delay before the first child animates in milliseconds
+     * @default 0
+     */
+    initialDelay?: number;
+    /**
+     * Easing function for all children
+     * @default 'easeOut'
+     */
+    easing?: PuffPopEasing;
+    /**
+     * If true, reserves space for children before animation
+     * @default true
+     */
+    skeleton?: boolean;
+    /**
+     * Whether children are visible
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Whether to animate on mount
+     * @default true
+     */
+    animateOnMount?: boolean;
+    /**
+     * Callback when all children animations complete
+     */
+    onAnimationComplete?: () => void;
+    /**
+     * Callback when the first child animation starts
+     */
+    onAnimationStart?: () => void;
+    /**
+     * Custom style for the group container
+     */
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Respect system reduce motion accessibility setting
+     * @default true
+     */
+    respectReduceMotion?: boolean;
+    /**
+     * Test ID for testing purposes
+     */
+    testID?: string;
+    /**
+     * Direction of stagger animation
+     * - 'forward': First to last child
+     * - 'reverse': Last to first child
+     * - 'center': From center outward
+     * - 'edges': From edges toward center
+     * @default 'forward'
+     */
+    staggerDirection?: 'forward' | 'reverse' | 'center' | 'edges';
+    /**
+     * If true, children are rendered in a row (horizontal layout)
+     * @default false
+     */
+    horizontal?: boolean;
+    /**
+     * Gap between children (uses flexbox gap)
+     */
+    gap?: number;
+}
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ *
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export declare function PuffPopGroup({ children, effect, duration, staggerDelay, initialDelay, easing, skeleton, visible, animateOnMount, onAnimationComplete, onAnimationStart, style, respectReduceMotion, testID, staggerDirection, horizontal, gap, }: PuffPopGroupProps): ReactElement;
 export default PuffPop;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-puff-pop",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A React Native animation library for revealing children components with beautiful puff and pop effects",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.tsx

@@ -4,6 +4,7 @@ import {
   useState,
   useCallback,
   useMemo,
+  Children,
   type ReactNode,
   type ReactElement,
 } from 'react';
@@ -370,6 +371,12 @@ export function PuffPop({
         // Stop any existing loop animation
         if (loopAnimationRef.current) {
           loopAnimationRef.current.stop();
+          loopAnimationRef.current = null;
+        }
+        // Clear any existing timeout
+        if (loopTimeoutRef.current) {
+          clearTimeout(loopTimeoutRef.current);
+          loopTimeoutRef.current = null;
         }
 
         const loopCount = typeof loop === 'number' ? loop : -1;
@@ -377,6 +384,8 @@ export function PuffPop({
 
         const runLoop = () => {
           resetValues();
+          // Store the current animation reference so it can be stopped
+          loopAnimationRef.current = animation;
           animation.start(({ finished }) => {
             if (finished) {
               currentIteration++;
@@ -391,14 +400,18 @@ export function PuffPop({
                 } else {
                   runLoop();
                 }
-              } else if (onAnimationComplete) {
-                onAnimationComplete();
+              } else {
+                // Loop finished, clear reference
+                loopAnimationRef.current = null;
+                if (onAnimationComplete) {
+                  onAnimationComplete();
+                }
               }
             }
           });
         };
 
-        // Store reference and start
+        // Start the loop
         runLoop();
       } else {
         // Stop any existing loop animation
@@ -602,7 +615,236 @@ const styles = StyleSheet.create({
   hidden: {
     opacity: 0,
   },
+  groupContainer: {},
 });
 
+/**
+ * Props for PuffPopGroup component
+ */
+export interface PuffPopGroupProps {
+  /**
+   * Children to animate with stagger effect
+   */
+  children: ReactNode;
+
+  /**
+   * Animation effect type applied to all children
+   * @default 'scale'
+   */
+  effect?: PuffPopEffect;
+
+  /**
+   * Base animation duration in milliseconds for each child
+   * @default 400
+   */
+  duration?: number;
+
+  /**
+   * Delay between each child's animation start in milliseconds
+   * @default 100
+   */
+  staggerDelay?: number;
+
+  /**
+   * Initial delay before the first child animates in milliseconds
+   * @default 0
+   */
+  initialDelay?: number;
+
+  /**
+   * Easing function for all children
+   * @default 'easeOut'
+   */
+  easing?: PuffPopEasing;
+
+  /**
+   * If true, reserves space for children before animation
+   * @default true
+   */
+  skeleton?: boolean;
+
+  /**
+   * Whether children are visible
+   * @default true
+   */
+  visible?: boolean;
+
+  /**
+   * Whether to animate on mount
+   * @default true
+   */
+  animateOnMount?: boolean;
+
+  /**
+   * Callback when all children animations complete
+   */
+  onAnimationComplete?: () => void;
+
+  /**
+   * Callback when the first child animation starts
+   */
+  onAnimationStart?: () => void;
+
+  /**
+   * Custom style for the group container
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Respect system reduce motion accessibility setting
+   * @default true
+   */
+  respectReduceMotion?: boolean;
+
+  /**
+   * Test ID for testing purposes
+   */
+  testID?: string;
+
+  /**
+   * Direction of stagger animation
+   * - 'forward': First to last child
+   * - 'reverse': Last to first child
+   * - 'center': From center outward
+   * - 'edges': From edges toward center
+   * @default 'forward'
+   */
+  staggerDirection?: 'forward' | 'reverse' | 'center' | 'edges';
+
+  /**
+   * If true, children are rendered in a row (horizontal layout)
+   * @default false
+   */
+  horizontal?: boolean;
+
+  /**
+   * Gap between children (uses flexbox gap)
+   */
+  gap?: number;
+}
+
+/**
+ * PuffPopGroup - Animate multiple children with staggered entrance effects
+ * 
+ * @example
+ * ```tsx
+ * <PuffPopGroup staggerDelay={100} effect="scale">
+ *   <Card title="First" />
+ *   <Card title="Second" />
+ *   <Card title="Third" />
+ * </PuffPopGroup>
+ * ```
+ */
+export function PuffPopGroup({
+  children,
+  effect = 'scale',
+  duration = 400,
+  staggerDelay = 100,
+  initialDelay = 0,
+  easing = 'easeOut',
+  skeleton = true,
+  visible = true,
+  animateOnMount = true,
+  onAnimationComplete,
+  onAnimationStart,
+  style,
+  respectReduceMotion = true,
+  testID,
+  staggerDirection = 'forward',
+  horizontal = false,
+  gap,
+}: PuffPopGroupProps): ReactElement {
+  const childArray = Children.toArray(children);
+  const childCount = childArray.length;
+  const completedCount = useRef(0);
+  const hasCalledStart = useRef(false);
+
+  // Calculate delay for each child based on stagger direction
+  const getChildDelay = useCallback(
+    (index: number): number => {
+      let delayIndex: number;
+
+      switch (staggerDirection) {
+        case 'reverse':
+          delayIndex = childCount - 1 - index;
+          break;
+        case 'center': {
+          const center = (childCount - 1) / 2;
+          delayIndex = Math.abs(index - center);
+          break;
+        }
+        case 'edges': {
+          const center = (childCount - 1) / 2;
+          delayIndex = center - Math.abs(index - center);
+          break;
+        }
+        case 'forward':
+        default:
+          delayIndex = index;
+          break;
+      }
+
+      return initialDelay + delayIndex * staggerDelay;
+    },
+    [childCount, initialDelay, staggerDelay, staggerDirection]
+  );
+
+  // Handle individual child animation complete
+  const handleChildComplete = useCallback(() => {
+    completedCount.current += 1;
+    if (completedCount.current >= childCount && onAnimationComplete) {
+      onAnimationComplete();
+    }
+  }, [childCount, onAnimationComplete]);
+
+  // Handle first child animation start
+  const handleChildStart = useCallback(() => {
+    if (!hasCalledStart.current && onAnimationStart) {
+      hasCalledStart.current = true;
+      onAnimationStart();
+    }
+  }, [onAnimationStart]);
+
+  // Reset counters when visibility changes
+  useEffect(() => {
+    if (visible) {
+      completedCount.current = 0;
+      hasCalledStart.current = false;
+    }
+  }, [visible]);
+
+  const containerStyle = useMemo(() => {
+    const baseStyle: ViewStyle = {
+      flexDirection: horizontal ? 'row' : 'column',
+    };
+    if (gap !== undefined) {
+      baseStyle.gap = gap;
+    }
+    return baseStyle;
+  }, [horizontal, gap]);
+
+  return (
+    <View style={[styles.groupContainer, containerStyle, style]} testID={testID}>
+      {childArray.map((child, index) => (
+        <PuffPop
+          key={index}
+          effect={effect}
+          duration={duration}
+          delay={getChildDelay(index)}
+          easing={easing}
+          skeleton={skeleton}
+          visible={visible}
+          animateOnMount={animateOnMount}
+          onAnimationComplete={handleChildComplete}
+          onAnimationStart={index === 0 ? handleChildStart : undefined}
+          respectReduceMotion={respectReduceMotion}
+        >
+          {child}
+        </PuffPop>
+      ))}
+    </View>
+  );
+}
+
 export default PuffPop;