partycles 1.1.5 → 1.2.1

package/README.md

@@ -12,7 +12,7 @@ A lightweight, performant React library for adding delightful animation effects
 ## ✨ Features
 
 - 🎯 **Simple API** - Just one hook to rule them all
-- 🎨 **19 Beautiful Animations** - Confetti, sparkles, hearts, stars, fireworks, bubbles, snow, emoji, coins, petals, aurora, fireflies, paint, balloons, galaxy, glitch, magicdust, crystals, and leaves
+- 🎨 **20 Beautiful Animations** - Confetti, sparkles, hearts, stars, fireworks, bubbles, snow, emoji, coins, petals, aurora, fireflies, paint, balloons, galaxy, glitch, magicdust, crystals, leaves, and mortar
 - 📦 **Tiny Bundle** - Zero dependencies, optimized for performance
 - 🚀 **Performant** - Optimized animations using requestAnimationFrame
 - 🎮 **Full Control** - Customize colors, particle count, physics, and more
@@ -33,13 +33,15 @@ pnpm add partycles
 ## 🚀 Quick Start
 
 ```tsx
+import { useRef } from 'react';
 import { useReward } from 'partycles';
 
 function App() {
-  const { reward, isAnimating } = useReward('rewardId', 'confetti');
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const { reward, isAnimating } = useReward(buttonRef, 'confetti');
 
   return (
-    <button id="rewardId" onClick={reward} disabled={isAnimating}>
+    <button ref={buttonRef} onClick={reward} disabled={isAnimating}>
       Click me for a surprise! 🎉
     </button>
   );
@@ -48,31 +50,50 @@ function App() {
 
 That's it! No configuration needed - it just works. 🎊
 
+### Using String IDs (Legacy)
+
+For backward compatibility, you can still use element IDs:
+
+```tsx
+const { reward, isAnimating } = useReward('my-button', 'confetti');
+
+<button id="my-button" onClick={reward}>
+  Click me! 🎉
+</button>
+```
+
 ## 🤔 Why Partycles?
 
 - **Zero Dependencies** - No bloat, just pure React code
 - **One Hook** - Simple `useReward` hook handles everything  
-- **19 Animations** - From confetti to magical effects, we've got you covered
+- **20 Animations** - From confetti to explosive effects, we've got you covered
 - **Fully Typed** - Great TypeScript support out of the box
 - **Customizable** - Tweak colors, physics, particle count, and more
 - **Performant** - Optimized animations that won't slow down your app
 
 ## 📖 API Reference
 
-### `useReward(elementId, animationType, config?)`
+### `useReward(targetRef, animationType, config?)` (Recommended)
+### `useReward(elementId, animationType, config?)` (Legacy)
 
 The main hook for creating reward animations.
 
 #### Parameters
 
-- `elementId` (string): The ID of the element to animate from
-- `animationType` (string): One of: `'confetti'`, `'sparkles'`, `'hearts'`, `'stars'`, `'fireworks'`, `'bubbles'`, `'snow'`, `'emoji'`, `'coins'`, `'petals'`, `'aurora'`, `'fireflies'`, `'paint'`, `'balloons'`, `'galaxy'`, `'glitch'`, `'magicdust'`, `'crystals'`, `'leaves'`
+- `targetRef` (RefObject<HTMLElement>): A React ref to the element to animate from (recommended)
+- `elementId` (string): The ID of the element to animate from (legacy, for backward compatibility)
+- `animationType` (string): One of: `'confetti'`, `'sparkles'`, `'hearts'`, `'stars'`, `'fireworks'`, `'bubbles'`, `'snow'`, `'emoji'`, `'coins'`, `'petals'`, `'aurora'`, `'fireflies'`, `'paint'`, `'balloons'`, `'galaxy'`, `'glitch'`, `'magicdust'`, `'crystals'`, `'leaves'`, `'mortar'`
 - `config` (optional): Animation configuration object
 
 #### Returns
 
-- `reward` (function): Triggers the animation
+- `reward` (function): Triggers the animation, returns a Promise that resolves when complete
 - `isAnimating` (boolean): Whether the animation is currently running
+- `pause` (function): Pauses the current animation
+- `resume` (function): Resumes a paused animation
+- `replay` (function): Stops current animation and starts a new one
+- `isPaused` (boolean): Whether the animation is currently paused
+- `targetRef` (RefObject<HTMLElement>): The ref object (only returned when using ref-based API)
 
 ### Configuration Options
 
@@ -109,7 +130,8 @@ interface AnimationConfig {
 Classic celebration effect with colorful paper pieces.
 
 ```tsx
-const { reward } = useReward('buttonId', 'confetti', {
+const buttonRef = useRef<HTMLButtonElement>(null);
+const { reward } = useReward(buttonRef, 'confetti', {
   particleCount: 30,
   spread: 60,
   colors: ['#ff0000', '#00ff00', '#0000ff'],
@@ -313,8 +335,72 @@ const { reward } = useReward('buttonId', 'leaves', {
 });
 ```
 
+### Mortar 💥
+Explosive mortar-style bursts with galaxy-like explosions.
+
+```tsx
+const { reward } = useReward('buttonId', 'mortar', {
+  particleCount: 2,
+  spread: 45,
+  physics: { gravity: 0.35 }
+});
+```
+
 ## 💡 Examples
 
+### Animation Controls
+
+Control your animations with pause, resume, and replay:
+
+```tsx
+import { useRef } from 'react';
+import { useReward } from 'partycles';
+
+function ControlledAnimation() {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const { reward, isAnimating, pause, resume, replay, isPaused } = useReward(
+    buttonRef,
+    'confetti',
+    { particleCount: 50 }
+  );
+
+  return (
+    <div>
+      <button ref={buttonRef} onClick={reward}>
+        Start Animation
+      </button>
+      
+      <button onClick={pause} disabled={!isAnimating || isPaused}>
+        Pause
+      </button>
+      
+      <button onClick={resume} disabled={!isAnimating || !isPaused}>
+        Resume
+      </button>
+      
+      <button onClick={replay}>
+        Replay
+      </button>
+      
+      <p>Status: {isAnimating ? (isPaused ? 'Paused' : 'Playing') : 'Idle'}</p>
+    </div>
+  );
+}
+```
+
+### Promise-based Completion
+
+Chain actions after animations complete:
+
+```tsx
+const { reward } = useReward(buttonRef, 'confetti');
+
+const handleSuccess = async () => {
+  await reward(); // Wait for animation to complete
+  console.log('Animation finished!');
+  // Navigate, show message, etc.
+};
+
 ### Form Submission Success
 ```tsx
 function ContactForm() {
@@ -529,7 +615,18 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## 📈 Changelog
 
-### v1.1.3 (Latest)
+### v1.2.1 (Latest)
+- 🎆 Added new `mortar` animation with galaxy-style explosions
+- 🐛 Fixed particle rendering issues with dynamic particle creation
+- 🎨 Updated emoji assignments for better consistency (fireflies: 🌟, coins: 💰)
+- ⚡ Optimized mortar explosion performance for mobile devices
+- 🔧 Improved animation manager to handle particles created during updates
+
+### v1.1.5
+- ✨ Added optional enhanced effects (flutter, twinkle, pulse, spin3D, wobble, windDrift)
+- 📱 Improved mobile performance with automatic optimizations
+
+### v1.1.3
 - 🚀 Added automatic mobile performance optimizations
 - 🐛 Fixed Safari compatibility issues
 - 📦 Streamlined bundle size by removing 7 animations

package/dist/index.d.mts

@@ -0,0 +1,149 @@
+import { RefObject } from 'react';
+
+interface Particle {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    opacity: number;
+    size: number;
+    rotation: number;
+    color: string;
+    element?: React.ReactNode | string;
+    config?: AnimationConfig;
+}
+interface AnimationConfig {
+    particleCount?: number;
+    spread?: number;
+    startVelocity?: number;
+    decay?: number;
+    lifetime?: number;
+    colors?: string[];
+    elementSize?: number;
+    duration?: number;
+    physics?: {
+        gravity?: number;
+        wind?: number;
+        friction?: number;
+    };
+    effects?: {
+        flutter?: boolean;
+        twinkle?: boolean;
+        pulse?: boolean;
+        spin3D?: boolean;
+        wobble?: boolean;
+        windDrift?: boolean;
+    };
+}
+type AnimationType = 'confetti' | 'sparkles' | 'fireworks' | 'hearts' | 'stars' | 'bubbles' | 'snow' | 'emoji' | 'coins' | 'petals' | 'aurora' | 'fireflies' | 'paint' | 'balloons' | 'galaxy' | 'leaves' | 'glitch' | 'magicdust' | 'crystals' | 'mortar';
+interface UseRewardConfig extends AnimationConfig {
+    animationType: AnimationType;
+}
+interface AnimationControls {
+    pause: () => void;
+    resume: () => void;
+    replay: () => Promise<void>;
+    isPaused: boolean;
+}
+
+interface UseRewardReturn extends AnimationControls {
+    reward: () => Promise<void>;
+    isAnimating: boolean;
+    targetRef?: RefObject<HTMLElement>;
+}
+declare function useReward(elementId: string, animationType: AnimationType, config?: AnimationConfig): UseRewardReturn;
+declare function useReward(targetRef: RefObject<HTMLElement>, animationType: AnimationType, config?: AnimationConfig): UseRewardReturn;
+
+declare const emojiPresets: {
+    celebration: string[];
+    love: string[];
+    happy: string[];
+    nature: string[];
+    food: string[];
+    default: string[];
+};
+
+declare const isMobileDevice: () => boolean;
+declare const optimizeConfigForMobile: (config: AnimationConfig) => AnimationConfig;
+
+interface PooledParticle extends Particle {
+    _pooled?: boolean;
+}
+declare class ParticlePool {
+    private pool;
+    private maxSize;
+    private created;
+    constructor(maxSize?: number);
+    acquire(): PooledParticle;
+    release(particle: PooledParticle): void;
+    releaseAll(particles: PooledParticle[]): void;
+    clear(): void;
+    getStats(): {
+        poolSize: number;
+        totalCreated: number;
+        maxSize: number;
+    };
+}
+declare const particlePool: ParticlePool;
+
+interface AnimationInstance {
+    id: string;
+    particles: Particle[];
+    containerElement: HTMLDivElement;
+    renderFunction: (particle: Particle) => React.ReactNode;
+    updateCallback?: (particles: Particle[]) => void;
+    onComplete?: () => void;
+    physics: {
+        gravity: number;
+        friction: number;
+        wind: number;
+    };
+    animationType: string;
+    config?: {
+        effects?: {
+            flutter?: boolean;
+            windDrift?: boolean;
+            wobble?: boolean;
+            twinkle?: boolean;
+        };
+    };
+    frameCount: number;
+    isPaused?: boolean;
+    pausedAt?: number;
+}
+declare class AnimationManager {
+    private animations;
+    private rafId;
+    private isRunning;
+    private lastFrameTime;
+    private frameInterval;
+    private frameCount;
+    private fpsUpdateInterval;
+    private lastFpsUpdate;
+    private currentFps;
+    constructor();
+    addAnimation(animation: AnimationInstance): void;
+    removeAnimation(id: string): void;
+    private start;
+    private stop;
+    private update;
+    private applyEffects;
+    private handleMortarExplosion;
+    private updateOpacity;
+    getStats(): {
+        activeAnimations: number;
+        currentFps: number;
+        isRunning: boolean;
+        totalParticles: number;
+    };
+    setTargetFPS(fps: number): void;
+    pauseAnimation(id: string): void;
+    resumeAnimation(id: string): void;
+    isAnimationPaused(id: string): boolean;
+    getAnimation(id: string): AnimationInstance | undefined;
+}
+declare const animationManager: AnimationManager;
+
+export { type AnimationConfig, type AnimationType, type UseRewardConfig, animationManager, emojiPresets, isMobileDevice, optimizeConfigForMobile, particlePool, useReward };

package/dist/index.d.ts

@@ -1,5 +1,149 @@
-export { useReward } from './useReward';
-export type { AnimationType, AnimationConfig, UseRewardConfig } from './types';
-export { emojiPresets } from './animations/emoji';
-export { isMobileDevice, optimizeConfigForMobile } from './mobileOptimizations';
-//# sourceMappingURL=index.d.ts.map
+import { RefObject } from 'react';
+
+interface Particle {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    opacity: number;
+    size: number;
+    rotation: number;
+    color: string;
+    element?: React.ReactNode | string;
+    config?: AnimationConfig;
+}
+interface AnimationConfig {
+    particleCount?: number;
+    spread?: number;
+    startVelocity?: number;
+    decay?: number;
+    lifetime?: number;
+    colors?: string[];
+    elementSize?: number;
+    duration?: number;
+    physics?: {
+        gravity?: number;
+        wind?: number;
+        friction?: number;
+    };
+    effects?: {
+        flutter?: boolean;
+        twinkle?: boolean;
+        pulse?: boolean;
+        spin3D?: boolean;
+        wobble?: boolean;
+        windDrift?: boolean;
+    };
+}
+type AnimationType = 'confetti' | 'sparkles' | 'fireworks' | 'hearts' | 'stars' | 'bubbles' | 'snow' | 'emoji' | 'coins' | 'petals' | 'aurora' | 'fireflies' | 'paint' | 'balloons' | 'galaxy' | 'leaves' | 'glitch' | 'magicdust' | 'crystals' | 'mortar';
+interface UseRewardConfig extends AnimationConfig {
+    animationType: AnimationType;
+}
+interface AnimationControls {
+    pause: () => void;
+    resume: () => void;
+    replay: () => Promise<void>;
+    isPaused: boolean;
+}
+
+interface UseRewardReturn extends AnimationControls {
+    reward: () => Promise<void>;
+    isAnimating: boolean;
+    targetRef?: RefObject<HTMLElement>;
+}
+declare function useReward(elementId: string, animationType: AnimationType, config?: AnimationConfig): UseRewardReturn;
+declare function useReward(targetRef: RefObject<HTMLElement>, animationType: AnimationType, config?: AnimationConfig): UseRewardReturn;
+
+declare const emojiPresets: {
+    celebration: string[];
+    love: string[];
+    happy: string[];
+    nature: string[];
+    food: string[];
+    default: string[];
+};
+
+declare const isMobileDevice: () => boolean;
+declare const optimizeConfigForMobile: (config: AnimationConfig) => AnimationConfig;
+
+interface PooledParticle extends Particle {
+    _pooled?: boolean;
+}
+declare class ParticlePool {
+    private pool;
+    private maxSize;
+    private created;
+    constructor(maxSize?: number);
+    acquire(): PooledParticle;
+    release(particle: PooledParticle): void;
+    releaseAll(particles: PooledParticle[]): void;
+    clear(): void;
+    getStats(): {
+        poolSize: number;
+        totalCreated: number;
+        maxSize: number;
+    };
+}
+declare const particlePool: ParticlePool;
+
+interface AnimationInstance {
+    id: string;
+    particles: Particle[];
+    containerElement: HTMLDivElement;
+    renderFunction: (particle: Particle) => React.ReactNode;
+    updateCallback?: (particles: Particle[]) => void;
+    onComplete?: () => void;
+    physics: {
+        gravity: number;
+        friction: number;
+        wind: number;
+    };
+    animationType: string;
+    config?: {
+        effects?: {
+            flutter?: boolean;
+            windDrift?: boolean;
+            wobble?: boolean;
+            twinkle?: boolean;
+        };
+    };
+    frameCount: number;
+    isPaused?: boolean;
+    pausedAt?: number;
+}
+declare class AnimationManager {
+    private animations;
+    private rafId;
+    private isRunning;
+    private lastFrameTime;
+    private frameInterval;
+    private frameCount;
+    private fpsUpdateInterval;
+    private lastFpsUpdate;
+    private currentFps;
+    constructor();
+    addAnimation(animation: AnimationInstance): void;
+    removeAnimation(id: string): void;
+    private start;
+    private stop;
+    private update;
+    private applyEffects;
+    private handleMortarExplosion;
+    private updateOpacity;
+    getStats(): {
+        activeAnimations: number;
+        currentFps: number;
+        isRunning: boolean;
+        totalParticles: number;
+    };
+    setTargetFPS(fps: number): void;
+    pauseAnimation(id: string): void;
+    resumeAnimation(id: string): void;
+    isAnimationPaused(id: string): boolean;
+    getAnimation(id: string): AnimationInstance | undefined;
+}
+declare const animationManager: AnimationManager;
+
+export { type AnimationConfig, type AnimationType, type UseRewardConfig, animationManager, emojiPresets, isMobileDevice, optimizeConfigForMobile, particlePool, useReward };