falling-animation 0.1.0

package/dist/falling-animation.umd.js

@@ -0,0 +1,676 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+    typeof define === 'function' && define.amd ? define(['exports'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.FallingAnimation = {}));
+})(this, (function (exports) { 'use strict';
+
+    /**
+     * Utility functions for falling-animation
+     */
+    /**
+     * Generate a random number between min and max
+     */
+    function randomRange(min, max) {
+        return Math.random() * (max - min) + min;
+    }
+    /**
+     * Generate a random number from a RangeValue
+     */
+    function randomFromRange(range) {
+        return randomRange(range.min, range.max);
+    }
+    /**
+     * Pick a random item from an array
+     */
+    function randomPick(array) {
+        return array[Math.floor(Math.random() * array.length)];
+    }
+    /**
+     * Pick a random item based on weights
+     */
+    function weightedRandomPick(items) {
+        var _a;
+        const totalWeight = items.reduce((sum, item) => { var _a; return sum + ((_a = item.weight) !== null && _a !== void 0 ? _a : 1); }, 0);
+        let random = Math.random() * totalWeight;
+        for (const item of items) {
+            random -= (_a = item.weight) !== null && _a !== void 0 ? _a : 1;
+            if (random <= 0) {
+                return item;
+            }
+        }
+        return items[items.length - 1];
+    }
+    /**
+     * Generate a unique ID
+     */
+    let idCounter = 0;
+    function generateId() {
+        return ++idCounter;
+    }
+    /**
+     * Resolve container from element or selector
+     */
+    function resolveContainer(container) {
+        if (!container) {
+            return document.body;
+        }
+        if (typeof container === 'string') {
+            const element = document.querySelector(container);
+            if (!element) {
+                console.warn(`[falling-animation] Container "${container}" not found, using document.body`);
+                return document.body;
+            }
+            return element;
+        }
+        return container;
+    }
+    /**
+     * Throttle function calls
+     */
+    function throttle(func, limit) {
+        let inThrottle = false;
+        return function (...args) {
+            if (!inThrottle) {
+                func.apply(this, args);
+                inThrottle = true;
+                setTimeout(() => (inThrottle = false), limit);
+            }
+        };
+    }
+
+    /**
+     * Animation functions for falling particles
+     * Each animation modifies particle state based on deltaTime and elapsed time
+     */
+    /**
+     * Simple vertical fall - no special effects
+     */
+    const fall = (particle, deltaTime) => {
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        particle.y += particle.vy * deltaTime;
+        particle.x += particle.vx * deltaTime;
+    };
+    /**
+     * Swing - pendulum-like swinging motion while falling
+     */
+    const swing = (particle, deltaTime, elapsed) => {
+        const swingAmplitude = 30; // pixels
+        const swingFrequency = 0.002; // oscillations per ms
+        // Slight rotation based on swing - always animate
+        particle.rotation = Math.sin((elapsed + particle.phase) * swingFrequency) * 20;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        particle.y += particle.vy * deltaTime;
+        // Calculate swing offset
+        const swingOffset = Math.sin((elapsed + particle.phase) * swingFrequency) * swingAmplitude;
+        particle.x += particle.vx * deltaTime + (swingOffset * 0.05);
+    };
+    /**
+     * Rotate - continuous 360° rotation while falling
+     */
+    const rotate = (particle, deltaTime) => {
+        // Continuous rotation - always animate
+        particle.rotation += particle.rotationSpeed * deltaTime;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        particle.y += particle.vy * deltaTime;
+        particle.x += particle.vx * deltaTime;
+    };
+    /**
+     * Flutter - butterfly-like fluttering motion
+     */
+    const flutter = (particle, deltaTime, elapsed) => {
+        const flutterFrequency = 0.005;
+        // Tilt based on direction - always animate
+        particle.rotation = Math.sin((elapsed + particle.phase) * flutterFrequency) * 30;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        const flutterAmplitude = 40;
+        const verticalWobble = 0.3;
+        // Horizontal flutter
+        const flutter = Math.sin((elapsed + particle.phase) * flutterFrequency) * flutterAmplitude;
+        particle.x += particle.vx * deltaTime + flutter * 0.03;
+        // Vertical movement with slight wobble
+        const wobble = Math.sin((elapsed + particle.phase) * flutterFrequency * 2) * verticalWobble;
+        particle.y += (particle.vy + wobble) * deltaTime;
+    };
+    /**
+     * Spiral - spiraling down pattern
+     */
+    const spiral = (particle, deltaTime, elapsed) => {
+        const spiralSpeed = 0.003;
+        const angle = (elapsed + particle.phase) * spiralSpeed;
+        // Rotate with spiral - always animate
+        particle.rotation = angle * (180 / Math.PI);
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        const spiralRadius = 25;
+        particle.y += particle.vy * deltaTime;
+        // Spiral motion
+        particle.x += particle.vx * deltaTime + Math.cos(angle) * spiralRadius * 0.02;
+    };
+    /**
+     * Tumble - chaotic tumbling motion
+     */
+    const tumble = (particle, deltaTime, elapsed) => {
+        var _a, _b, _c;
+        const tumbleSpeed = (_a = particle.data.tumbleSpeed) !== null && _a !== void 0 ? _a : 5;
+        // Fast tumbling rotation - always animate
+        particle.rotation += tumbleSpeed * deltaTime;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        const wobbleX = (_b = particle.data.wobbleX) !== null && _b !== void 0 ? _b : 0.02;
+        const wobbleY = (_c = particle.data.wobbleY) !== null && _c !== void 0 ? _c : 0.01;
+        particle.y += particle.vy * deltaTime;
+        // Chaotic horizontal movement
+        particle.x += particle.vx * deltaTime +
+            Math.sin((elapsed + particle.phase) * wobbleX) * 20 * 0.02;
+        // Add some vertical variation
+        particle.y += Math.sin((elapsed + particle.phase * 1.5) * wobbleY) * 0.5;
+    };
+    /**
+     * Zigzag - zigzag falling pattern
+     */
+    const zigzag = (particle, deltaTime, elapsed) => {
+        const zigzagFrequency = 0.002;
+        const period = 1 / zigzagFrequency;
+        const t = ((elapsed + particle.phase) % period) / period;
+        const triangleWave = Math.abs(t * 2 - 1) * 2 - 1;
+        // Tilt in direction of movement - always animate
+        particle.rotation = triangleWave * 25;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        const zigzagWidth = 50;
+        particle.y += particle.vy * deltaTime;
+        // Create zigzag using triangle wave
+        particle.x += particle.vx * deltaTime + triangleWave * zigzagWidth * 0.02;
+    };
+    /**
+     * Float - slow floating descent with gentle movement
+     */
+    const float = (particle, deltaTime, elapsed) => {
+        const floatFrequency = 0.001;
+        // Gentle rotation - always animate
+        particle.rotation = Math.sin((elapsed + particle.phase) * floatFrequency) * 10;
+        // Skip movement if speed is 0
+        if (particle.vy === 0 && particle.vx === 0)
+            return;
+        const floatAmplitudeX = 20;
+        const floatAmplitudeY = 5;
+        // Very slow descent with vertical wobble
+        const yWobble = Math.sin((elapsed + particle.phase) * floatFrequency * 2) * floatAmplitudeY;
+        particle.y += (particle.vy * 0.5 + yWobble * 0.01) * deltaTime;
+        // Gentle horizontal drift
+        const xDrift = Math.sin((elapsed + particle.phase) * floatFrequency) * floatAmplitudeX;
+        particle.x += particle.vx * deltaTime + xDrift * 0.01;
+    };
+    /**
+     * Animation registry - all available animations
+     */
+    const animations = {
+        fall,
+        swing,
+        rotate,
+        flutter,
+        spiral,
+        tumble,
+        zigzag,
+        float
+    };
+    /**
+     * Get animation function by name
+     */
+    function getAnimation(name) {
+        var _a;
+        return (_a = animations[name]) !== null && _a !== void 0 ? _a : fall;
+    }
+
+    /**
+     * Particle class - manages individual falling objects
+     */
+    /**
+     * Speed multiplier to convert user-friendly speed units to px/ms
+     * speed = 1 means ~40 pixels per second (~1cm/s at 96 DPI)
+     * speed = 0.1 means ~4 pixels per second (~1mm/s)
+     * speed = 0 means standing still
+     */
+    const SPEED_MULTIPLIER = 0.04; // 40 px/s per unit, divided by 1000 for ms
+    class Particle {
+        constructor(options) {
+            this.options = options;
+            this.id = generateId();
+            this.age = 0;
+            this.phase = Math.random() * Math.PI * 2;
+            this.data = {};
+            // Get container dimensions
+            this.containerWidth = options.container.clientWidth;
+            this.containerHeight = options.container.clientHeight;
+            // Pick random object
+            const object = weightedRandomPick(options.objects);
+            // Initialize position at top with random x
+            this.x = randomRange(-50, this.containerWidth + 50);
+            this.y = -50;
+            // Initialize velocity (apply speed multiplier for intuitive units)
+            // speed=1 → ~40px/s (1cm/s), speed=0.1 → ~4px/s (1mm/s)
+            this.vy = randomFromRange(options.speed) * SPEED_MULTIPLIER;
+            this.vx = options.wind * SPEED_MULTIPLIER * randomRange(0.5, 1.5);
+            // Initialize size and opacity
+            this.size = randomFromRange(options.size);
+            this.opacity = randomFromRange(options.opacity);
+            // Initialize rotation
+            this.rotation = randomRange(0, 360);
+            this.rotationSpeed = randomRange(-3, 3);
+            // Pick animation
+            this.animation = randomPick(options.animation);
+            // Initialize animation-specific data
+            this.initAnimationData();
+            // Create DOM element
+            this.element = this.createElement(object);
+        }
+        /**
+         * Initialize animation-specific data
+         */
+        initAnimationData() {
+            if (this.animation === 'tumble') {
+                this.data.tumbleSpeed = randomRange(3, 8);
+                this.data.wobbleX = randomRange(0.01, 0.03);
+                this.data.wobbleY = randomRange(0.005, 0.015);
+            }
+        }
+        /**
+         * Create DOM element for the particle
+         */
+        createElement(object) {
+            var _a, _b, _c, _d;
+            const element = document.createElement('div');
+            element.className = 'falling-particle';
+            element.setAttribute('data-particle-id', String(this.id));
+            // Set content based on type
+            switch (object.type) {
+                case 'emoji':
+                    element.textContent = (_a = object.content) !== null && _a !== void 0 ? _a : '❄️';
+                    element.style.fontSize = `${this.size}px`;
+                    element.style.lineHeight = '1';
+                    break;
+                case 'image':
+                    const img = document.createElement('img');
+                    img.src = (_c = (_b = object.src) !== null && _b !== void 0 ? _b : object.content) !== null && _c !== void 0 ? _c : '';
+                    img.alt = '';
+                    img.style.width = `${this.size}px`;
+                    img.style.height = `${this.size}px`;
+                    img.style.objectFit = 'contain';
+                    img.draggable = false;
+                    element.appendChild(img);
+                    break;
+                case 'html':
+                    element.innerHTML = (_d = object.content) !== null && _d !== void 0 ? _d : '';
+                    break;
+            }
+            // Apply base styles
+            Object.assign(element.style, {
+                position: 'absolute',
+                pointerEvents: 'none',
+                userSelect: 'none',
+                willChange: 'transform, opacity',
+                opacity: String(this.opacity),
+                left: '0',
+                top: '0',
+                transform: this.getTransform()
+            });
+            return element;
+        }
+        /**
+         * Get CSS transform string
+         */
+        getTransform() {
+            return `translate3d(${this.x}px, ${this.y}px, 0) rotate(${this.rotation}deg)`;
+        }
+        /**
+         * Update particle state
+         */
+        update(deltaTime, elapsed) {
+            this.age += deltaTime;
+            // Apply animation
+            const animationFn = getAnimation(this.animation);
+            animationFn(this, deltaTime, elapsed);
+            // Update DOM
+            this.element.style.transform = this.getTransform();
+        }
+        /**
+         * Check if particle is out of bounds
+         */
+        isOutOfBounds() {
+            return (this.y > this.containerHeight + 100 ||
+                this.x < -100 ||
+                this.x > this.containerWidth + 100);
+        }
+        /**
+         * Update container dimensions (for resize handling)
+         */
+        updateContainerSize(width, height) {
+            this.containerWidth = width;
+            this.containerHeight = height;
+        }
+        /**
+         * Remove particle from DOM
+         */
+        destroy() {
+            this.element.remove();
+        }
+    }
+
+    /**
+     * FallingAnimation - Main class for creating falling object animations
+     */
+    /** Default configuration values */
+    const DEFAULTS = {
+        speed: { min: 2, max: 5 },
+        spawnRate: 3,
+        maxParticles: 50,
+        animation: ['fall'],
+        size: { min: 20, max: 40 },
+        opacity: { min: 0.6, max: 1 },
+        wind: 0,
+        autoStart: true,
+        zIndex: 9999,
+        responsive: true
+    };
+    class FallingAnimation {
+        constructor(options) {
+            this.particles = [];
+            this.wrapper = null;
+            this.isRunning = false;
+            this.isPaused = false;
+            this.animationId = null;
+            this.lastSpawnTime = 0;
+            this.startTime = 0;
+            this.lastFrameTime = 0;
+            this.resizeHandler = null;
+            /**
+             * Main animation loop
+             */
+            this.animate = (currentTime) => {
+                if (!this.isRunning)
+                    return;
+                // Calculate delta time
+                if (this.lastFrameTime === 0) {
+                    this.lastFrameTime = currentTime;
+                    this.startTime = currentTime;
+                }
+                const deltaTime = Math.min(currentTime - this.lastFrameTime, 50); // Cap at 50ms
+                const elapsed = currentTime - this.startTime;
+                this.lastFrameTime = currentTime;
+                // Spawn new particles based on rate
+                const spawnInterval = 1000 / this.options.spawnRate;
+                if (currentTime - this.lastSpawnTime >= spawnInterval) {
+                    this.spawnParticle();
+                    this.lastSpawnTime = currentTime;
+                }
+                // Update particles
+                const particlesToRemove = [];
+                for (const particle of this.particles) {
+                    particle.update(deltaTime, elapsed);
+                    if (particle.isOutOfBounds()) {
+                        particlesToRemove.push(particle);
+                    }
+                }
+                // Remove out-of-bounds particles
+                particlesToRemove.forEach(p => this.removeParticle(p));
+                // Continue animation loop
+                this.animationId = requestAnimationFrame(this.animate);
+            };
+            // Validate required options
+            if (!options.objects || options.objects.length === 0) {
+                throw new Error('[falling-animation] "objects" option is required and must not be empty');
+            }
+            // Resolve options with defaults
+            this.options = this.resolveOptions(options);
+            // Create wrapper element
+            this.createWrapper();
+            // Setup resize handler if responsive
+            if (this.options.responsive) {
+                this.setupResizeHandler();
+            }
+            // Auto start if enabled
+            if (this.options.autoStart) {
+                this.start();
+            }
+        }
+        /**
+         * Merge user options with defaults
+         */
+        resolveOptions(options) {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            const container = resolveContainer(options.container);
+            // Normalize animation to array
+            let animation;
+            if (!options.animation) {
+                animation = DEFAULTS.animation;
+            }
+            else if (typeof options.animation === 'string') {
+                animation = [options.animation];
+            }
+            else {
+                animation = options.animation;
+            }
+            return {
+                container,
+                objects: options.objects,
+                speed: (_a = options.speed) !== null && _a !== void 0 ? _a : DEFAULTS.speed,
+                spawnRate: (_b = options.spawnRate) !== null && _b !== void 0 ? _b : DEFAULTS.spawnRate,
+                maxParticles: (_c = options.maxParticles) !== null && _c !== void 0 ? _c : DEFAULTS.maxParticles,
+                animation,
+                size: (_d = options.size) !== null && _d !== void 0 ? _d : DEFAULTS.size,
+                opacity: (_e = options.opacity) !== null && _e !== void 0 ? _e : DEFAULTS.opacity,
+                wind: (_f = options.wind) !== null && _f !== void 0 ? _f : DEFAULTS.wind,
+                autoStart: (_g = options.autoStart) !== null && _g !== void 0 ? _g : DEFAULTS.autoStart,
+                zIndex: (_h = options.zIndex) !== null && _h !== void 0 ? _h : DEFAULTS.zIndex,
+                responsive: (_j = options.responsive) !== null && _j !== void 0 ? _j : DEFAULTS.responsive
+            };
+        }
+        /**
+         * Create wrapper element for particles
+         */
+        createWrapper() {
+            this.wrapper = document.createElement('div');
+            this.wrapper.className = 'falling-animation-wrapper';
+            // Apply styles
+            Object.assign(this.wrapper.style, {
+                position: this.options.container === document.body ? 'fixed' : 'absolute',
+                top: '0',
+                left: '0',
+                width: '100%',
+                height: '100%',
+                overflow: 'hidden',
+                pointerEvents: 'none',
+                zIndex: String(this.options.zIndex)
+            });
+            // Ensure container has position for absolute wrapper
+            if (this.options.container !== document.body) {
+                const containerPosition = getComputedStyle(this.options.container).position;
+                if (containerPosition === 'static') {
+                    this.options.container.style.position = 'relative';
+                }
+            }
+            this.options.container.appendChild(this.wrapper);
+        }
+        /**
+         * Setup resize handler for responsive behavior
+         */
+        setupResizeHandler() {
+            this.resizeHandler = throttle(() => {
+                const width = this.options.container.clientWidth;
+                const height = this.options.container.clientHeight;
+                this.particles.forEach(particle => {
+                    particle.updateContainerSize(width, height);
+                });
+            }, 200);
+            window.addEventListener('resize', this.resizeHandler);
+        }
+        /**
+         * Spawn a new particle
+         */
+        spawnParticle() {
+            if (this.particles.length >= this.options.maxParticles) {
+                return;
+            }
+            const particle = new Particle(this.options);
+            this.particles.push(particle);
+            if (this.wrapper) {
+                this.wrapper.appendChild(particle.element);
+            }
+        }
+        /**
+         * Remove a particle
+         */
+        removeParticle(particle) {
+            const index = this.particles.indexOf(particle);
+            if (index > -1) {
+                this.particles.splice(index, 1);
+                particle.destroy();
+            }
+        }
+        /**
+         * Start the animation
+         */
+        start() {
+            if (this.isRunning)
+                return;
+            this.isRunning = true;
+            this.isPaused = false;
+            this.lastFrameTime = 0;
+            this.lastSpawnTime = 0;
+            this.animationId = requestAnimationFrame(this.animate);
+        }
+        /**
+         * Stop the animation and clear all particles
+         */
+        stop() {
+            this.isRunning = false;
+            this.isPaused = false;
+            if (this.animationId !== null) {
+                cancelAnimationFrame(this.animationId);
+                this.animationId = null;
+            }
+            // Clear all particles
+            this.particles.forEach(p => p.destroy());
+            this.particles = [];
+        }
+        /**
+         * Pause the animation (keeps particles in place)
+         */
+        pause() {
+            if (!this.isRunning || this.isPaused)
+                return;
+            this.isPaused = true;
+            this.isRunning = false;
+            if (this.animationId !== null) {
+                cancelAnimationFrame(this.animationId);
+                this.animationId = null;
+            }
+        }
+        /**
+         * Resume a paused animation
+         */
+        resume() {
+            if (this.isRunning || !this.isPaused)
+                return;
+            this.isRunning = true;
+            this.isPaused = false;
+            this.lastFrameTime = 0;
+            this.animationId = requestAnimationFrame(this.animate);
+        }
+        /**
+         * Update options dynamically
+         */
+        setOptions(newOptions) {
+            // Merge new options
+            if (newOptions.speed) {
+                this.options.speed = newOptions.speed;
+            }
+            if (newOptions.spawnRate !== undefined) {
+                this.options.spawnRate = newOptions.spawnRate;
+            }
+            if (newOptions.maxParticles !== undefined) {
+                this.options.maxParticles = newOptions.maxParticles;
+            }
+            if (newOptions.animation) {
+                this.options.animation = typeof newOptions.animation === 'string'
+                    ? [newOptions.animation]
+                    : newOptions.animation;
+            }
+            if (newOptions.size) {
+                this.options.size = newOptions.size;
+            }
+            if (newOptions.opacity) {
+                this.options.opacity = newOptions.opacity;
+            }
+            if (newOptions.wind !== undefined) {
+                this.options.wind = newOptions.wind;
+            }
+            if (newOptions.objects) {
+                this.options.objects = newOptions.objects;
+            }
+        }
+        /**
+         * Get current particle count
+         */
+        getParticleCount() {
+            return this.particles.length;
+        }
+        /**
+         * Check if animation is running
+         */
+        getIsRunning() {
+            return this.isRunning;
+        }
+        /**
+         * Check if animation is paused
+         */
+        getIsPaused() {
+            return this.isPaused;
+        }
+        /**
+         * Destroy the animation and clean up
+         */
+        destroy() {
+            this.stop();
+            // Remove wrapper
+            if (this.wrapper) {
+                this.wrapper.remove();
+                this.wrapper = null;
+            }
+            // Remove resize handler
+            if (this.resizeHandler) {
+                window.removeEventListener('resize', this.resizeHandler);
+                this.resizeHandler = null;
+            }
+        }
+    }
+
+    /**
+     * falling-animation
+     * A lightweight, customizable falling objects animation library
+     *
+     * @author phongdh
+     * @license MIT
+     */
+    // Main class
+
+    exports.FallingAnimation = FallingAnimation;
+    exports.animations = animations;
+    exports.default = FallingAnimation;
+    exports.getAnimation = getAnimation;
+
+    Object.defineProperty(exports, '__esModule', { value: true });
+
+}));
+//# sourceMappingURL=falling-animation.umd.js.map