elementdrawing 1.0.0

package/src/js/animation.js

@@ -0,0 +1,655 @@
+/**
+ * Animation Utilities
+ * ElementDrawing Framework - requestAnimationFrame wrapper, easing functions,
+ * tween engine, spring physics, keyframes, scroll/intersection animation,
+ * sequencing, and CSS animation helpers.
+ */
+
+'use strict';
+
+// ─── requestAnimationFrame Wrapper ────────────────────────────────────────────
+
+let rafId = 0;
+const rafCallbacks = new Map();
+
+/**
+ * Request an animation frame with a cancel function.
+ * @param {Function} callback
+ * @returns {number} RAF ID
+ */
+function requestFrame(callback) {
+  const id = ++rafId;
+  const wrapped = (time) => {
+    rafCallbacks.delete(id);
+    callback(time);
+  };
+  rafCallbacks.set(id, wrapped);
+  return window.requestAnimationFrame(wrapped);
+}
+
+/**
+ * Cancel a requested animation frame.
+ * @param {number} id
+ */
+function cancelFrame(id) {
+  window.cancelAnimationFrame(id);
+  rafCallbacks.delete(id);
+}
+
+/**
+ * Cancel all pending animation frames.
+ */
+function cancelAllFrames() {
+  rafCallbacks.forEach((cb, id) => window.cancelAnimationFrame(id));
+  rafCallbacks.clear();
+}
+
+// ─── Easing Functions ─────────────────────────────────────────────────────────
+
+const easing = {
+  linear: (t) => t,
+
+  easeIn: (t) => t * t * t,
+  easeOut: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOut: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => 1 - (1 - t) * (1 - t),
+  easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+
+  easeInQuart: (t) => t * t * t * t,
+  easeOutQuart: (t) => 1 - Math.pow(1 - t, 4),
+  easeInOutQuart: (t) => t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2,
+
+  bounce: (t) => {
+    const n1 = 7.5625, d1 = 2.75;
+    if (t < 1 / d1) return n1 * t * t;
+    if (t < 2 / d1) return n1 * (t -= 1.5 / d1) * t + 0.75;
+    if (t < 2.5 / d1) return n1 * (t -= 2.25 / d1) * t + 0.9375;
+    return n1 * (t -= 2.625 / d1) * t + 0.984375;
+  },
+
+  elastic: (t) => {
+    if (t === 0 || t === 1) return t;
+    return -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * ((2 * Math.PI) / 3));
+  },
+
+  back: (t) => {
+    const c1 = 1.70158, c3 = c1 + 1;
+    return c3 * t * t * t - c1 * t * t;
+  },
+
+  expo: (t) => t === 0 ? 0 : Math.pow(2, 10 * t - 10),
+  circ: (t) => 1 - Math.sqrt(1 - t * t),
+
+  spring: (t, stiffness, damping) => {
+    stiffness = stiffness || 100;
+    damping = damping || 10;
+    const omega = Math.sqrt(stiffness);
+    const zeta = damping / (2 * omega);
+    if (zeta < 1) {
+      const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+      return 1 - Math.exp(-zeta * omega * t) * (Math.cos(omegaD * t) + (zeta * omega / omegaD) * Math.sin(omegaD * t));
+    }
+    return 1 - (1 + omega * t) * Math.exp(-omega * t);
+  },
+};
+
+// ─── Animation Timeline ───────────────────────────────────────────────────────
+
+/**
+ * Create an animation timeline for sequencing animations.
+ * @returns {Object} Timeline controller
+ */
+function createTimeline() {
+  const animations = [];
+  let startTime = null;
+  let isPlaying = false;
+  let rafId = null;
+
+  return {
+    /**
+     * Add an animation to the timeline.
+     * @param {Object} anim
+     * @param {number} anim.delay - Start delay in ms
+     * @param {number} anim.duration - Duration in ms
+     * @param {Function} anim.onUpdate - Called with (progress) each frame
+     * @param {Function} [anim.onComplete] - Called when animation completes
+     * @param {string} [anim.easing='linear'] - Easing function name
+     */
+    add: function (anim) {
+      animations.push(Object.assign({ delay: 0, duration: 1000, easing: 'linear' }, anim));
+      return this;
+    },
+
+    /**
+     * Start playing the timeline.
+     */
+    play: function () {
+      if (isPlaying) return;
+      isPlaying = true;
+      startTime = performance.now();
+
+      function tick(now) {
+        if (!isPlaying) return;
+        const elapsed = now - startTime;
+
+        let allComplete = true;
+        animations.forEach((anim) => {
+          const localTime = elapsed - anim.delay;
+          if (localTime < 0) { allComplete = false; return; }
+
+          const rawProgress = Math.min(localTime / anim.duration, 1);
+          if (rawProgress < 1) allComplete = false;
+
+          const easeFn = easing[anim.easing] || easing.linear;
+          const progress = easeFn(rawProgress);
+          anim.onUpdate(progress, rawProgress);
+
+          if (rawProgress >= 1 && anim.onComplete) {
+            anim.onComplete();
+            anim.onComplete = null;
+          }
+        });
+
+        if (!allComplete) {
+          rafId = requestFrame(tick);
+        } else {
+          isPlaying = false;
+        }
+      }
+
+      rafId = requestFrame(tick);
+      return this;
+    },
+
+    /**
+     * Pause the timeline.
+     */
+    pause: function () {
+      isPlaying = false;
+      if (rafId) cancelFrame(rafId);
+      return this;
+    },
+
+    /**
+     * Reset the timeline.
+     */
+    reset: function () {
+      this.pause();
+      startTime = null;
+      return this;
+    },
+  };
+}
+
+// ─── Tween Engine ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a tween animation from a start value to an end value.
+ * @param {Object} options
+ * @param {*} options.from - Starting value
+ * @param {*} options.to - Ending value
+ * @param {number} options.duration - Duration in ms
+ * @param {string} [options.easing='easeInOut'] - Easing function
+ * @param {Function} options.onUpdate - Called with (currentValue) each frame
+ * @param {Function} [options.onComplete] - Called when complete
+ * @returns {Object} Tween controller with play, pause, reset
+ */
+function tween(options) {
+  const from = options.from;
+  const to = options.to;
+  const duration = options.duration || 1000;
+  const easeFn = easing[options.easing || 'easeInOut'] || easing.easeInOut;
+  const onUpdate = options.onUpdate;
+  const onComplete = options.onComplete;
+
+  let startTime = null;
+  let isPlaying = false;
+  let rafId = null;
+  let currentValue = from;
+
+  function tick(now) {
+    if (!isPlaying) return;
+    if (!startTime) startTime = now;
+
+    const elapsed = now - startTime;
+    const rawProgress = Math.min(elapsed / duration, 1);
+    const progress = easeFn(rawProgress);
+
+    currentValue = from + (to - from) * progress;
+    onUpdate(currentValue, progress, rawProgress);
+
+    if (rawProgress < 1) {
+      rafId = requestFrame(tick);
+    } else {
+      isPlaying = false;
+      if (onComplete) onComplete(currentValue);
+    }
+  }
+
+  return {
+    play: function () {
+      if (isPlaying) return this;
+      isPlaying = true;
+      startTime = null;
+      rafId = requestFrame(tick);
+      return this;
+    },
+    pause: function () {
+      isPlaying = false;
+      if (rafId) cancelFrame(rafId);
+      return this;
+    },
+    reset: function () {
+      this.pause();
+      startTime = null;
+      currentValue = from;
+      onUpdate(from, 0, 0);
+      return this;
+    },
+    getCurrentValue: function () { return currentValue; },
+    isPlaying: function () { return isPlaying; },
+  };
+}
+
+/**
+ * Create a tween from a starting value.
+ * @param {*} from
+ * @param {*} to
+ * @param {number} duration
+ * @returns {Object} Tween builder
+ */
+function fromTo(from, to, duration) {
+  return tween({ from, to, duration });
+}
+
+/**
+ * Create a tween from current value to a target.
+ * @param {*} from
+ * @param {*} to
+ * @param {number} duration
+ * @returns {Object} Tween builder
+ */
+function to(from, to, duration) {
+  return tween({ from, to, duration });
+}
+
+/**
+ * Create staggered tweens for multiple targets.
+ * @param {Array} targets
+ * @param {Object} options
+ * @param {number} options.stagger - Delay between each target in ms
+ * @param {*} options.from
+ * @param {*} options.to
+ * @param {number} options.duration
+ * @param {Function} options.onUpdate
+ * @returns {Array} Array of tween controllers
+ */
+function stagger(targets, options) {
+  const staggerDelay = options.stagger || 50;
+  return targets.map((target, i) => {
+    return tween({
+      from: options.from,
+      to: options.to,
+      duration: options.duration || 1000,
+      easing: options.easing || 'easeInOut',
+      onUpdate: function (value) {
+        if (options.onUpdate) options.onUpdate(value, target, i);
+      },
+      onComplete: options.onComplete ? () => options.onComplete(target, i) : undefined,
+    });
+  });
+}
+
+// ─── Spring Physics ───────────────────────────────────────────────────────────
+
+/**
+ * Create a spring-based animation.
+ * @param {Object} options
+ * @param {number} [options.stiffness=100]
+ * @param {number} [options.damping=10]
+ * @param {number} [options.mass=1]
+ * @param {number} [options.initialVelocity=0]
+ * @param {number} options.from
+ * @param {number} options.to
+ * @param {Function} options.onUpdate
+ * @param {Function} [options.onComplete]
+ * @returns {Object} Spring controller
+ */
+function spring(options) {
+  const stiffness = options.stiffness || 100;
+  const damping = options.damping || 10;
+  const mass = options.mass || 1;
+  let velocity = options.initialVelocity || 0;
+  const from = options.from;
+  const to = options.to;
+  const onUpdate = options.onUpdate;
+  const onComplete = options.onComplete;
+
+  let currentValue = from;
+  let isPlaying = false;
+  let rafId = null;
+  let lastTime = null;
+  const precision = 0.01;
+
+  function step(now) {
+    if (!isPlaying) return;
+    if (!lastTime) lastTime = now;
+    const dt = Math.min((now - lastTime) / 1000, 0.064);
+    lastTime = now;
+
+    const displacement = currentValue - to;
+    const springForce = -stiffness * displacement;
+    const dampingForce = -damping * velocity;
+    const acceleration = (springForce + dampingForce) / mass;
+
+    velocity += acceleration * dt;
+    currentValue += velocity * dt;
+
+    onUpdate(currentValue);
+
+    // Check if settled
+    if (Math.abs(velocity) < precision && Math.abs(displacement) < precision) {
+      currentValue = to;
+      onUpdate(to);
+      isPlaying = false;
+      if (onComplete) onComplete(to);
+      return;
+    }
+
+    rafId = requestFrame(step);
+  }
+
+  return {
+    play: function () {
+      if (isPlaying) return this;
+      isPlaying = true;
+      lastTime = null;
+      rafId = requestFrame(step);
+      return this;
+    },
+    pause: function () {
+      isPlaying = false;
+      if (rafId) cancelFrame(rafId);
+      return this;
+    },
+    reset: function () {
+      this.pause();
+      currentValue = from;
+      velocity = options.initialVelocity || 0;
+      lastTime = null;
+      onUpdate(from);
+      return this;
+    },
+    setVelocity: function (v) { velocity = v; return this; },
+    getCurrentValue: function () { return currentValue; },
+    isPlaying: function () { return isPlaying; },
+  };
+}
+
+// ─── Keyframe Animation ───────────────────────────────────────────────────────
+
+/**
+ * Create a keyframe animation with multiple steps.
+ * @param {Object} options
+ * @param {Array<{offset: number, value: *}>} options.keyframes
+ * @param {number} options.duration
+ * @param {string} [options.easing]
+ * @param {Function} options.onUpdate
+ * @param {Function} [options.onComplete]
+ * @returns {Object} Keyframe controller
+ */
+function keyframe(options) {
+  const frames = options.keyframes.sort((a, b) => a.offset - b.offset);
+  const duration = options.duration || 1000;
+  const easeFn = easing[options.easing || 'linear'] || easing.linear;
+  const onUpdate = options.onUpdate;
+  const onComplete = options.onComplete;
+
+  let startTime = null;
+  let isPlaying = false;
+  let rafId = null;
+
+  function interpolate(progress) {
+    if (frames.length === 0) return 0;
+    if (frames.length === 1) return frames[0].value;
+
+    // Find surrounding keyframes
+    let lower = frames[0], upper = frames[frames.length - 1];
+    for (let i = 0; i < frames.length - 1; i++) {
+      if (progress >= frames[i].offset && progress <= frames[i + 1].offset) {
+        lower = frames[i];
+        upper = frames[i + 1];
+        break;
+      }
+    }
+
+    const range = upper.offset - lower.offset;
+    const localProgress = range === 0 ? 1 : (progress - lower.offset) / range;
+    return lower.value + (upper.value - lower.value) * localProgress;
+  }
+
+  function tick(now) {
+    if (!isPlaying) return;
+    if (!startTime) startTime = now;
+
+    const elapsed = now - startTime;
+    const rawProgress = Math.min(elapsed / duration, 1);
+    const easedProgress = easeFn(rawProgress);
+    const value = interpolate(easedProgress);
+
+    onUpdate(value, easedProgress, rawProgress);
+
+    if (rawProgress < 1) {
+      rafId = requestFrame(tick);
+    } else {
+      isPlaying = false;
+      if (onComplete) onComplete(value);
+    }
+  }
+
+  return {
+    play: function () { isPlaying = true; startTime = null; rafId = requestFrame(tick); return this; },
+    pause: function () { isPlaying = false; if (rafId) cancelFrame(rafId); return this; },
+    reset: function () { this.pause(); startTime = null; onUpdate(interpolate(0), 0, 0); return this; },
+  };
+}
+
+// ─── Scroll Animation ─────────────────────────────────────────────────────────
+
+/**
+ * Animate elements based on scroll position.
+ * @param {HTMLElement} el - Element to observe
+ * @param {Object} options
+ * @param {Function} options.onProgress - Called with (progress: 0-1) on scroll
+ * @param {number} [options.start=0] - Start offset in viewport (0=top, 1=bottom)
+ * @param {number} [options.end=1] - End offset
+ * @returns {Function} Cleanup function
+ */
+function scrollAnimate(el, options) {
+  const onProgress = options.onProgress;
+  const start = options.start || 0;
+  const end = options.end || 1;
+
+  function update() {
+    const rect = el.getBoundingClientRect();
+    const viewportHeight = window.innerHeight;
+    const elementProgress = (viewportHeight - rect.top) / (viewportHeight + rect.height);
+    const progress = Math.max(0, Math.min(1, (elementProgress - start) / (end - start)));
+    onProgress(progress);
+  }
+
+  window.addEventListener('scroll', update, { passive: true });
+  update();
+
+  return function cleanup() {
+    window.removeEventListener('scroll', update);
+  };
+}
+
+// ─── Intersection Observer Animation ──────────────────────────────────────────
+
+/**
+ * Trigger animation when element enters viewport.
+ * @param {HTMLElement} el
+ * @param {Object} options
+ * @param {Function} options.onEnter - Called when element enters viewport
+ * @param {Function} [options.onExit] - Called when element exits viewport
+ * @param {number} [options.threshold=0.1]
+ * @returns {Function} Cleanup function
+ */
+function intersectionAnimate(el, options) {
+  if (typeof IntersectionObserver === 'undefined') {
+    options.onEnter(el);
+    return function () {};
+  }
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          options.onEnter(el, entry);
+        } else if (options.onExit) {
+          options.onExit(el, entry);
+        }
+      });
+    },
+    { threshold: options.threshold || 0.1 }
+  );
+
+  observer.observe(el);
+  return function cleanup() { observer.disconnect(); };
+}
+
+// ─── Animation Queue & Sequencing ─────────────────────────────────────────────
+
+/**
+ * Create an animation queue that runs animations sequentially.
+ * @returns {Object} Queue controller
+ */
+function createQueue() {
+  const queue = [];
+  let isRunning = false;
+
+  function runNext() {
+    if (queue.length === 0) { isRunning = false; return; }
+    isRunning = true;
+    const anim = queue.shift();
+    anim(function onComplete() {
+      runNext();
+    });
+  }
+
+  return {
+    add: function (animFn) { queue.push(animFn); if (!isRunning) runNext(); return this; },
+    clear: function () { queue.length = 0; isRunning = false; return this; },
+    isRunning: function () { return isRunning; },
+    length: function () { return queue.length; },
+  };
+}
+
+/**
+ * Run animations in sequence.
+ * @param {...Object} anims - Tween/keyframe controllers
+ * @returns {Promise} Resolves when all animations complete
+ */
+function sequence(anims) {
+  return anims.reduce((promise, anim) => {
+    return promise.then(() => new Promise((resolve) => {
+      anim.play();
+      const originalComplete = anim.onComplete;
+      anim.onComplete = function () {
+        if (originalComplete) originalComplete();
+        resolve();
+      };
+    }));
+  }, Promise.resolve());
+}
+
+/**
+ * Run animations in parallel.
+ * @param {Array} anims
+ * @returns {Promise} Resolves when all animations complete
+ */
+function parallel(anims) {
+  return Promise.all(anims.map((anim) => new Promise((resolve) => {
+    anim.play();
+    const originalComplete = anim.onComplete;
+    anim.onComplete = function () {
+      if (originalComplete) originalComplete();
+      resolve();
+    };
+  })));
+}
+
+// ─── CSS Animation Helpers ────────────────────────────────────────────────────
+
+/**
+ * Apply a CSS transition to an element.
+ * @param {HTMLElement} el
+ * @param {string} property
+ * @param {number} [duration=300]
+ * @param {string} [easing='ease']
+ * @param {number} [delay=0]
+ */
+function cssTransition(el, property, duration, easingName, delay) {
+  duration = duration || 300;
+  easingName = easingName || 'ease';
+  delay = delay || 0;
+  el.style.transition = property + ' ' + duration + 'ms ' + easingName + ' ' + delay + 'ms';
+}
+
+/**
+ * Apply a CSS keyframe animation.
+ * @param {HTMLElement} el
+ * @param {string} name - Animation name
+ * @param {number} [duration=300]
+ * @param {string} [easing='ease']
+ * @param {string} [fill='forwards']
+ * @returns {Promise}
+ */
+function cssAnimate(el, name, duration, easingName, fill) {
+  duration = duration || 300;
+  easingName = easingName || 'ease';
+  fill = fill || 'forwards';
+
+  el.style.animation = name + ' ' + duration + 'ms ' + easingName + ' ' + fill;
+
+  return new Promise((resolve) => {
+    function handler(e) {
+      if (e.animationName === name) {
+        el.removeEventListener('animationend', handler);
+        resolve(el);
+      }
+    }
+    el.addEventListener('animationend', handler);
+  });
+}
+
+/**
+ * Remove CSS animation from element.
+ * @param {HTMLElement} el
+ */
+function cssAnimateStop(el) {
+  el.style.animation = '';
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  requestFrame, cancelFrame, cancelAllFrames,
+  easing,
+  createTimeline,
+  tween, fromTo, to, stagger,
+  spring,
+  keyframe,
+  scrollAnimate,
+  intersectionAnimate,
+  createQueue, sequence, parallel,
+  cssTransition, cssAnimate, cssAnimateStop,
+};