react-native-puff-pop 1.0.6 → 1.0.8

package/README.md

@@ -15,7 +15,13 @@ Works with both **React Native CLI** and **Expo** projects - no native dependenc
 
 ## Features
 
-- 🎬 **11 Animation Effects**: scale, rotate, fade, slideUp, slideDown, slideLeft, slideRight, bounce, flip, zoom, rotateScale
+- 🎬 **16 Animation Effects**: scale, rotate, fade, slideUp/Down/Left/Right, bounce, flip, zoom, rotateScale, shake, pulse, swing, wobble, elastic
+- 🎯 **Exit Animations**: Different effects for enter and exit animations
+- 🔄 **Reverse Mode**: Reverse animation direction with a single prop
+- 🎛️ **Custom Initial Values**: Fine-tune starting opacity, scale, rotation, and position
+- 📊 **Animation Intensity**: Control how dramatic your animations are (0-1)
+- 📍 **Anchor Point**: Set transform origin for scale/rotate (top, bottom, corners, etc.)
+- 🧲 **Spring Physics**: Use physics-based spring animations with customizable tension/friction
 - 🦴 **Skeleton Mode**: Reserve space before animation or expand from zero height
 - ⚡ **Native Driver Support**: Smooth 60fps animations
 - 🎯 **Easy to Use**: Just wrap your components with `<PuffPop>`
@@ -181,6 +187,295 @@ function App() {
 </PuffPop>
 ```
 
+### Exit Animation
+
+Use different effects for enter and exit animations:
+
+```tsx
+// Scale in, fade out
+<PuffPop 
+  effect="scale" 
+  exitEffect="fade"
+  visible={isVisible}
+>
+  <Modal />
+</PuffPop>
+
+// Slide up to enter, slide down to exit
+<PuffPop 
+  effect="slideUp" 
+  exitEffect="slideDown"
+  exitDuration={200}
+  visible={isVisible}
+>
+  <Toast />
+</PuffPop>
+
+// Different timing for enter and exit
+<PuffPop 
+  effect="zoom"
+  duration={400}
+  easing="spring"
+  exitEffect="fade"
+  exitDuration={150}
+  exitEasing="easeIn"
+  exitDelay={50}
+  visible={isVisible}
+>
+  <Notification />
+</PuffPop>
+```
+
+With `PuffPopGroup`:
+
+```tsx
+<PuffPopGroup
+  effect="slideUp"
+  exitEffect="fade"
+  exitDuration={150}
+  staggerDelay={50}
+  visible={isVisible}
+>
+  <ListItem />
+  <ListItem />
+  <ListItem />
+</PuffPopGroup>
+```
+
+### Exit Stagger Animation
+
+Stagger the exit animation of group children:
+
+```tsx
+// Children exit one by one in reverse order (last first)
+<PuffPopGroup
+  staggerDelay={50}
+  exitStaggerDelay={50}
+  exitStaggerDirection="reverse"
+  visible={isVisible}
+>
+  <ListItem />
+  <ListItem />
+  <ListItem />
+</PuffPopGroup>
+
+// Children exit from center outward
+<PuffPopGroup
+  exitStaggerDelay={30}
+  exitStaggerDirection="center"
+  visible={isVisible}
+>
+  <MenuItem />
+  <MenuItem />
+  <MenuItem />
+  <MenuItem />
+  <MenuItem />
+</PuffPopGroup>
+```
+
+Exit stagger directions:
+- `forward`: First child exits first
+- `reverse`: Last child exits first (default, LIFO)
+- `center`: Center children exit first
+- `edges`: Edge children exit first
+
+### Custom Initial Values
+
+Fine-tune the starting values of your animations:
+
+```tsx
+// Start from 50% opacity instead of 0
+<PuffPop initialOpacity={0.5}>
+  <Card />
+</PuffPop>
+
+// Start from a larger scale
+<PuffPop effect="scale" initialScale={0.5}>
+  <Avatar />
+</PuffPop>
+
+// Custom slide distance
+<PuffPop effect="slideUp" initialTranslateY={200}>
+  <Modal />
+</PuffPop>
+
+// Combine multiple custom values
+<PuffPop
+  effect="rotateScale"
+  initialOpacity={0.3}
+  initialScale={0.2}
+  initialRotate={-90}
+>
+  <Icon />
+</PuffPop>
+```
+
+### Reverse Mode
+
+Reverse the animation direction:
+
+```tsx
+// slideUp now slides from top instead of bottom
+<PuffPop effect="slideUp" reverse>
+  <Toast />
+</PuffPop>
+
+// slideLeft now slides from left instead of right
+<PuffPop effect="slideLeft" reverse>
+  <Drawer />
+</PuffPop>
+
+// rotate spins clockwise instead of counter-clockwise
+<PuffPop effect="rotate" reverse>
+  <Spinner />
+</PuffPop>
+```
+
+With `PuffPopGroup`:
+
+```tsx
+<PuffPopGroup effect="slideRight" reverse staggerDelay={50}>
+  <MenuItem />
+  <MenuItem />
+  <MenuItem />
+</PuffPopGroup>
+```
+
+### Animation Intensity
+
+Control how dramatic your animations are with the `intensity` prop (0-1):
+
+```tsx
+// Full animation (default)
+<PuffPop effect="slideUp" intensity={1}>
+  <Card />
+</PuffPop>
+
+// Half the movement distance (25px instead of 50px)
+<PuffPop effect="slideUp" intensity={0.5}>
+  <Card />
+</PuffPop>
+
+// Subtle animation (10px slide)
+<PuffPop effect="slideUp" intensity={0.2}>
+  <Tooltip />
+</PuffPop>
+
+// No movement, just fade (intensity 0)
+<PuffPop effect="slideUp" intensity={0}>
+  <Content />
+</PuffPop>
+```
+
+Works with all effects:
+
+```tsx
+// Smaller scale range (starts at 0.5 instead of 0)
+<PuffPop effect="scale" intensity={0.5}>
+  <Avatar />
+</PuffPop>
+
+// Less rotation (180deg instead of 360deg)
+<PuffPop effect="rotate" intensity={0.5}>
+  <Icon />
+</PuffPop>
+```
+
+With `PuffPopGroup`:
+
+```tsx
+<PuffPopGroup effect="slideLeft" intensity={0.3} staggerDelay={50}>
+  <ListItem />
+  <ListItem />
+  <ListItem />
+</PuffPopGroup>
+```
+
+### Anchor Point
+
+Set the transform origin for scale/rotate animations:
+
+```tsx
+// Scale from top (expands downward)
+<PuffPop effect="scale" anchorPoint="top">
+  <DropdownMenu />
+</PuffPop>
+
+// Scale from bottom-left corner
+<PuffPop effect="scale" anchorPoint="bottomLeft">
+  <Tooltip />
+</PuffPop>
+
+// Rotate from top-left (door-opening effect)
+<PuffPop effect="rotate" anchorPoint="topLeft">
+  <Panel />
+</PuffPop>
+
+// Flip from right edge
+<PuffPop effect="flip" anchorPoint="right">
+  <Card />
+</PuffPop>
+```
+
+Available anchor points:
+
+| Value | Description |
+|-------|-------------|
+| `center` | Default center point |
+| `top` | Top center |
+| `bottom` | Bottom center |
+| `left` | Left center |
+| `right` | Right center |
+| `topLeft` | Top-left corner |
+| `topRight` | Top-right corner |
+| `bottomLeft` | Bottom-left corner |
+| `bottomRight` | Bottom-right corner |
+
+### Spring Animation
+
+Use physics-based spring animations for more natural, bouncy effects:
+
+```tsx
+// Enable spring animation
+<PuffPop effect="scale" useSpring>
+  <Card />
+</PuffPop>
+
+// Customize spring physics
+<PuffPop
+  effect="slideUp"
+  useSpring
+  springConfig={{
+    tension: 150,    // Higher = faster, snappier
+    friction: 8,     // Higher = less bouncy
+  }}
+>
+  <Modal />
+</PuffPop>
+
+// Very bouncy spring
+<PuffPop
+  effect="scale"
+  useSpring
+  springConfig={{
+    tension: 200,
+    friction: 5,
+    bounciness: 12,
+  }}
+>
+  <Button />
+</PuffPop>
+```
+
+Spring config options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `tension` | `100` | Spring stiffness (higher = faster) |
+| `friction` | `10` | Damping (higher = less oscillation) |
+| `speed` | `12` | Animation speed multiplier |
+| `bounciness` | `8` | Bounce amount (higher = more bouncy) |
+
 ## Props
 
 | Prop | Type | Default | Description |
@@ -200,6 +495,20 @@ function App() {
 | `loopDelay` | `number` | `0` | Delay between loop iterations in ms |
 | `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
 | `testID` | `string` | - | Test ID for testing purposes |
+| `exitEffect` | `PuffPopEffect` | - | Animation effect for exit (defaults to enter effect) |
+| `exitDuration` | `number` | - | Duration for exit animation (defaults to duration) |
+| `exitEasing` | `PuffPopEasing` | - | Easing for exit animation (defaults to easing) |
+| `exitDelay` | `number` | `0` | Delay before exit animation starts in ms |
+| `initialOpacity` | `number` | - | Custom initial opacity (0-1) |
+| `initialScale` | `number` | - | Custom initial scale value |
+| `initialRotate` | `number` | - | Custom initial rotation in degrees |
+| `initialTranslateX` | `number` | - | Custom initial X translation in pixels |
+| `initialTranslateY` | `number` | - | Custom initial Y translation in pixels |
+| `reverse` | `boolean` | `false` | Reverse animation direction |
+| `intensity` | `number` | `1` | Animation intensity multiplier (0-1) |
+| `anchorPoint` | `PuffPopAnchorPoint` | `'center'` | Transform origin for scale/rotate |
+| `useSpring` | `boolean` | `false` | Use physics-based spring animation |
+| `springConfig` | `PuffPopSpringConfig` | - | Spring animation settings (tension, friction, etc.) |
 
 ### PuffPopGroup Props
 
@@ -222,6 +531,22 @@ function App() {
 | `gap` | `number` | - | Gap between children |
 | `respectReduceMotion` | `boolean` | `true` | Respect system reduce motion setting |
 | `testID` | `string` | - | Test ID for testing purposes |
+| `exitEffect` | `PuffPopEffect` | - | Exit animation effect for all children |
+| `exitDuration` | `number` | - | Exit duration for all children |
+| `exitEasing` | `PuffPopEasing` | - | Exit easing for all children |
+| `exitDelay` | `number` | `0` | Exit delay for all children |
+| `initialOpacity` | `number` | - | Custom initial opacity for all children |
+| `initialScale` | `number` | - | Custom initial scale for all children |
+| `initialRotate` | `number` | - | Custom initial rotation for all children |
+| `initialTranslateX` | `number` | - | Custom initial X translation for all children |
+| `initialTranslateY` | `number` | - | Custom initial Y translation for all children |
+| `reverse` | `boolean` | `false` | Reverse animation direction for all children |
+| `intensity` | `number` | `1` | Animation intensity multiplier for all children |
+| `anchorPoint` | `PuffPopAnchorPoint` | `'center'` | Transform origin for all children |
+| `useSpring` | `boolean` | `false` | Use spring animation for all children |
+| `springConfig` | `PuffPopSpringConfig` | - | Spring settings for all children |
+| `exitStaggerDelay` | `number` | `0` | Delay between each child's exit animation |
+| `exitStaggerDirection` | `'forward' \| 'reverse' \| 'center' \| 'edges'` | `'reverse'` | Direction of exit stagger |
 
 ### Animation Effects (`PuffPopEffect`)
 
@@ -238,6 +563,11 @@ function App() {
 | `flip` | 3D flip effect |
 | `zoom` | Zoom with slight overshoot |
 | `rotateScale` | Rotate + Scale combined |
+| `shake` | Shake left-right (for alerts, errors) |
+| `pulse` | Pulse heartbeat effect (for emphasis) |
+| `swing` | Swing like pendulum (for menus) |
+| `wobble` | Wobble with tilt (playful entrance) |
+| `elastic` | Elastic stretch effect (springy feel) |
 
 ### Easing Types (`PuffPopEasing`)