falling-animation 0.1.0

package/dist/falling-animation.cjs.js

@@ -0,0 +1,670 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * 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;
+//# sourceMappingURL=falling-animation.cjs.js.map