@guinetik/gcanvas 1.0.0

package/src/motion/spiral.js

@@ -0,0 +1,144 @@
+import { Motion } from "./motion";
+import { Tween } from "./tween";
+/**
+ * Spiral motion animation
+ *
+ * @param {number} centerX - X coordinate of spiral center
+ * @param {number} centerY - Y coordinate of spiral center
+ * @param {number} startRadius - Starting radius of the spiral
+ * @param {number} endRadius - Ending radius of the spiral
+ * @param {number} startAngle - Starting angle in radians
+ * @param {number} revolutions - Number of complete revolutions
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of animation in seconds
+ * @param {boolean} [loop=false] - Whether animation should loop (restart from beginning)
+ * @param {boolean} [yoyo=false] - Whether animation should reverse direction at the end
+ * @param {Function} [easingFn=null] - Optional easing function to apply
+ * @param {Object} [callbacks] - Optional callback functions
+ * @param {Object} [state] - Internal state tracking for callbacks
+ * @returns {Object} Animation result with x, y coordinates and metadata
+ */
+export function spiralV1(
+  centerX,
+  centerY,
+  startRadius,
+  endRadius,
+  startAngle,
+  revolutions,
+  elapsedTime,
+  duration,
+  loop = false,
+  yoyo = false,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Initialize state if needed
+  if (!state) {
+    state = {
+      started: false,
+      loopCount: 0,
+      direction: 1, // 1 = forward, -1 = backward (for yoyo)
+      lastDirection: 1,
+    };
+  }
+  // Calculate normalized time (0-1)
+  let t = duration > 0 ? elapsedTime / duration : 1;
+  let completed = false;
+  let activeCallbacks = { ...callbacks };
+  // Handle yoyo and loop logic
+  if (yoyo || loop) {
+    // For yoyo + loop, or just loop: calculate cycle
+    if (loop) {
+      if (yoyo) {
+        // For yoyo + loop: full cycle is 2x duration (forward + backward)
+        const fullCycle = duration * 2;
+        const cycleTime = elapsedTime % fullCycle;
+        const cycleCount = Math.floor(elapsedTime / fullCycle);
+        // Determine direction and adjusted t
+        const newDirection = cycleTime < duration ? 1 : -1;
+        t =
+          newDirection === 1 ? cycleTime / duration : 2 - cycleTime / duration;
+        // Check for direction change for callbacks
+        if (newDirection !== state.direction) {
+          state.direction = newDirection;
+          if (state.direction === 1 && activeCallbacks.onLoop) {
+            activeCallbacks.onLoop(cycleCount);
+          }
+        }
+        // Track loop count
+        if (cycleCount > state.loopCount) {
+          state.loopCount = cycleCount;
+        }
+      } else {
+        // Just loop, no yoyo: reset t at each cycle
+        t = t % 1;
+        // Track loop count for callbacks
+        const newLoopCount = Math.floor(elapsedTime / duration);
+        if (newLoopCount > state.loopCount && activeCallbacks.onLoop) {
+          activeCallbacks.onLoop(newLoopCount);
+          state.loopCount = newLoopCount;
+        }
+      }
+    } else if (yoyo && !loop) {
+      // Yoyo without loop: complete one cycle then stop
+      if (t <= 1) {
+        // Forward part of the cycle
+        state.direction = 1;
+      } else if (t <= 2) {
+        // Backward part of the cycle
+        t = 2 - t;
+        state.direction = -1;
+      } else {
+        // Complete
+        t = 0;
+        completed = true;
+        state.direction = 1;
+      }
+    }
+  } else {
+    // No loop or yoyo: standard behavior
+    if (t >= 1) {
+      t = 1;
+      completed = true;
+    }
+  }
+  // Call onStart callback once
+  if (!state.started && activeCallbacks.onStart) {
+    activeCallbacks.onStart();
+    state.started = true;
+  }
+  // Call onComplete callback once when non-looping animation completes
+  if (completed && !state.completed && activeCallbacks.onComplete) {
+    activeCallbacks.onComplete();
+    state.completed = true;
+  }
+  // Apply easing if provided
+  const easedT = easingFn ? easingFn(t) : t;
+  // Calculate current radius using linear interpolation
+  const radius = Tween.lerp(startRadius, endRadius, easedT);
+  // Calculate current angle (start angle + number of revolutions)
+  const angle = startAngle + easedT * revolutions * Math.PI * 2;
+  // Convert polar coordinates to Cartesian
+  const x = centerX + radius * Math.cos(angle);
+  const y = centerY + radius * Math.sin(angle);
+  // Update state for next frame
+  const newState = {
+    ...state,
+    lastDirection: state.direction,
+  };
+  // Return standardized result
+  return Motion.animationResult(
+    {
+      x,
+      y,
+      radius,
+      angle,
+      direction: state.direction, // Include current direction (1 = forward, -1 = backward)
+    },
+    t,
+    loop || (yoyo && !completed),
+    completed,
+    newState
+  );
+}

package/src/motion/spring.js

@@ -0,0 +1,150 @@
+import { Easing } from "./easing";
+import { Motion } from "./motion";
+import { Tween } from "./tween";
+
+/**
+ * Spring animation that uses elastic easing functions for a bouncy spring effect
+ * Stateless implementation that doesn't require previous frame state
+ *
+ * @param {number} initial - Initial value (starting position)
+ * @param {number} target - Target value (ending position)
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one complete cycle in seconds
+ * @param {boolean} [loop=false] - Whether animation should loop
+ * @param {boolean} [yoyo=false] - Whether animation should return to initial value
+ * @param {Object} [springParams] - Spring parameters
+ * @param {number} [springParams.stiffness=0.3] - Spring stiffness (0-1)
+ * @param {number} [springParams.damping=0.6] - Damping factor (0-1)
+ * @param {Object} [callbacks] - Optional callback functions
+ * @param {Function} [callbacks.onStart] - Called when animation starts
+ * @param {Function} [callbacks.onComplete] - Called when animation completes
+ * @param {Function} [callbacks.onLoop] - Called when animation loops
+ * @param {Function} [callbacks.onYoyoTurn] - Called when yoyo animation changes direction
+ * @returns {Object} Animation result with value, velocity and metadata
+ */
+export function springV1(
+  initial,
+  target,
+  elapsedTime,
+  duration,
+  loop = false,
+  yoyo = false,
+  springParams = {},
+  callbacks = {}
+) {
+  // Early return for zero duration
+  if (duration <= 0) {
+    return this.animationResult(
+      { value: target, velocity: 0, done: true, phase: "complete" },
+      1,
+      false,
+      true
+    );
+  }
+  // Normalize time (0-1) within current cycle
+  let t = elapsedTime / duration;
+  let yoyoPhase = "forward";
+  let loopCount = 0;
+  // Handle looping vs. non-looping
+  if (loop) {
+    // Calculate loop count (for callbacks)
+    loopCount = Math.floor(t);
+    // Use only the fractional part for looping (0-1 repeating)
+    t = t % 1;
+    // Call onLoop callback if provided and we crossed a loop boundary
+    if (loopCount > 0 && callbacks.onLoop) {
+      callbacks.onLoop(loopCount);
+    }
+  } else {
+    // Clamp to 1 for non-looping animations
+    if (t > 1) t = 1;
+  }
+  // Call onStart callback if needed (only when animation begins)
+  if (t > 0 && elapsedTime <= duration && callbacks.onStart) {
+    callbacks.onStart();
+  }
+  // For yoyo, adjust the target value based on which half of the cycle we're in
+  let currentTarget, currentInitial, adjustedT;
+  if (yoyo) {
+    // If in the second half of the animation, we're going back
+    if (t >= 0.5) {
+      // Swap target and initial
+      currentTarget = initial;
+      currentInitial = target;
+      // Rescale t to 0-1 for the second half
+      adjustedT = (t - 0.5) * 2;
+      yoyoPhase = "return";
+      // Call onYoyoTurn callback at the turning point
+      if (t >= 0.5 && t < 0.51 && callbacks.onYoyoTurn) {
+        callbacks.onYoyoTurn();
+      }
+    } else {
+      // First half of animation
+      currentTarget = target;
+      currentInitial = initial;
+      adjustedT = t * 2;
+      yoyoPhase = "forward";
+    }
+  } else {
+    currentTarget = target;
+    currentInitial = initial;
+    adjustedT = t;
+  }
+  // Get spring parameters with defaults
+  const stiffness =
+    springParams.stiffness !== undefined ? springParams.stiffness : 0.3;
+  const damping =
+    springParams.damping !== undefined ? springParams.damping : 0.6;
+  // Convert stiffness and damping to elastic easing parameters
+  const amplitude = Math.max(0.1, 1.0 / (damping * 1.5)); // Higher damping = lower amplitude
+  const period = Math.max(0.1, 0.8 / (stiffness * 1.5 + 0.5)); // Higher stiffness = higher frequency
+  // Use the elastic easing to generate spring-like motion
+  // For springs, easeOutElastic works best (starts fast, then oscillates to rest)
+  let easedT;
+  if (adjustedT < 0.99) {
+    // Use elastic easing for most of the animation
+    easedT = Easing.easeOutElastic(adjustedT, amplitude, period);
+  } else {
+    // Smoothly settle to the exact target value at the end
+    // This prevents small oscillations at t=1
+    const blendFactor = (adjustedT - 0.99) / 0.01;
+    const elasticT = Easing.easeOutElastic(0.99, amplitude, period);
+    easedT = elasticT * (1 - blendFactor) + 1 * blendFactor;
+  }
+  // Interpolate between initial and target values using the eased time
+  const position = Tween.lerp(currentInitial, currentTarget, easedT);
+  // Calculate approximate velocity by comparing positions at t and t+dt
+  const dt = 0.01;
+  const nextT = Math.min(adjustedT + dt, 1);
+  // Calculate next position for velocity estimation
+  let nextEasedT;
+  if (nextT < 0.99) {
+    nextEasedT = Easing.easeOutElastic(nextT, amplitude, period);
+  } else {
+    const blendFactor = (nextT - 0.99) / 0.01;
+    const elasticT = Easing.easeOutElastic(0.99, amplitude, period);
+    nextEasedT = elasticT * (1 - blendFactor) + 1 * blendFactor;
+  }
+  const nextPosition = Tween.lerp(currentInitial, currentTarget, nextEasedT);
+  // Calculate velocity (scaled by duration to account for time)
+  const velocity = ((nextPosition - position) / dt) * duration;
+  // Check if non-looping animation is complete
+  const isDone = !loop && t >= 1;
+  // Call onComplete if animation has completed
+  if (isDone && callbacks.onComplete) {
+    callbacks.onComplete();
+  }
+  // Return standardized result with additional spring metadata
+  return Motion.animationResult(
+    {
+      value: position,
+      velocity: velocity,
+      delta: yoyoPhase === "forward" ? target - position : initial - position,
+      done: isDone,
+      phase: yoyoPhase,
+    },
+    t,
+    loop,
+    isDone
+  );
+}

package/src/motion/swing.js

@@ -0,0 +1,47 @@
+import { Motion } from "./motion";
+
+/**
+ * Swing animation - oscillates around a fixed center angle
+ *
+ * @param {number} centerX - X pivot (not used for angle, just for semantic)
+ * @param {number} centerY - Y pivot (not used for angle, just for semantic)
+ * @param {number} maxAngle - Maximum swing angle in radians (e.g. Math.PI / 6)
+ * @param {number} elapsedTime - Total elapsed time in seconds
+ * @param {number} duration - Duration of one full swing cycle
+ * @param {boolean} [loop=true] - Whether the animation loops
+ * @param {boolean} [yoyo=true] - Whether the swing reverses
+ * @param {Function} [easingFn=null] - Optional easing function
+ * @param {Object} [callbacks={}] - Optional callbacks (onStart, onComplete, etc)
+ * @param {Object} [state=null] - Internal state tracking
+ * @returns {Object} Animation result with angle and metadata
+ */
+export function swingV1(
+  centerX,
+  centerY,
+  maxAngle,
+  elapsedTime,
+  duration,
+  loop = true,
+  yoyo = true,
+  easingFn = null,
+  callbacks = {},
+  state = null
+) {
+  // Process time and easing
+  const {
+    t,
+    easedT,
+    completed,
+    state: newState,
+  } = Motion._frame(elapsedTime, duration, loop, easingFn, callbacks, state);
+
+  // Swing back and forth using sine curve
+  const phase = yoyo
+    ? Math.sin(easedT * Math.PI * 2)
+    : Math.sin(easedT * Math.PI);
+
+  // Calculate angle: center ± maxAngle
+  const angle = phase * maxAngle;
+
+  return Motion.animationResult({ angle }, t, loop, completed, newState);
+}

package/src/motion/tween.js

@@ -0,0 +1,92 @@
+/**
+ * Tween module providing core interpolation utilities for animations.
+ *
+ * @class Tween
+ * @description
+ * Tween is a stateless utility class for performing basic and advanced interpolation operations.
+ * These methods are low-level math tools used across both simulation-driven animations (like {@link Motion})
+ * and UI-driven transitions (like {@link Tweenetik}).
+ *
+ * The class includes:
+ * - Scalar and angle interpolation
+ * - Color blending in RGB and HSL spaces
+ * - Angle-safe easing
+ *
+ * All functions are deterministic, pure, and suitable for use in render loops or transition systems.
+ *
+ * @example
+ * const x = Tween.lerp(0, 100, 0.25); // 25
+ * const angle = Tween.lerpAngle(Math.PI, -Math.PI, 0.5); // shortest-path rotation
+ * const rgb = Tween.tweenColor([255, 0, 0], [0, 0, 255], 0.5); // purple
+ *
+ * @see {@link Motion} for game-loop-driven animation patterns
+ * @see {@link Tweenetik} for time-based UI transitions
+ */
+export class Tween {
+  /**
+   * Linear interpolation between two scalar values.
+   * Also known as Lerp.
+   * @param {number} start
+   * @param {number} end
+   * @param {number} t - Normalized interpolation factor (0 to 1)
+   * @returns {number} Interpolated scalar
+   */
+  static lerp(start, end, t) {
+    return start + (end - start) * t;
+  }
+
+  /**
+   * Smoothly interpolates between two angles (in radians),
+   * always taking the shortest path around the circle.
+   *
+   * Prevents snapping when angles wrap across -π to π boundaries.
+   *
+   * @param {number} a - Starting angle in radians
+   * @param {number} b - Target angle in radians
+   * @param {number} t - Interpolation factor (0 to 1)
+   * @returns {number} Interpolated angle in radians
+   */
+  static lerpAngle(a, b, t) {
+    // Calculate raw difference
+    let diff = b - a;
+    // Wrap difference to range [-PI, PI] for shortest rotation
+    while (diff < -Math.PI) diff += Math.PI * 2;
+    while (diff > Math.PI) diff -= Math.PI * 2;
+    // Interpolate from a toward b using the wrapped difference
+    return a + diff * t;
+  }
+
+  /**
+   * Interpolate between two colors in RGB space
+   * @param {Array<number>} color1 - Start color [r, g, b] (0-255)
+   * @param {Array<number>} color2 - End color [r, g, b] (0-255)
+   * @param {number} t - Interpolation factor (0-1)
+   * @returns {Array<number>} Interpolated color [r, g, b]
+   */
+  static tweenColor(color1, color2, t) {
+    return color1.map((c, i) => Tween.lerp(c, color2[i], t));
+  }
+
+  /**
+   * Interpolate between two HSL colors
+   * @param {Array<number>} color1 - Start color [h, s, l]
+   * @param {Array<number>} color2 - End color [h, s, l]
+   * @param {number} t - Interpolation factor (0-1)
+   * @returns {Array<number>} Interpolated color [h, s, l]
+   */
+  static tweenGradient(color1, color2, t) {
+    // Special handling for hue to handle the circular nature
+    let h1 = color1[0];
+    let h2 = color2[0];
+    // Find the shortest path around the circle
+    if (Math.abs(h2 - h1) > 180) {
+      if (h1 < h2) h1 += 360;
+      else h2 += 360;
+    }
+    // tween each channel individually
+    const h = Tween.lerp(h1, h2, t) % 360;
+    const s = Tween.lerp(color1[1], color2[1], t);
+    const l = Tween.lerp(color1[2], color2[2], t);
+    return [h, s, l];
+  }
+}

package/src/motion/tweenetik.js

@@ -0,0 +1,139 @@
+// Tweenetik.js
+import { Easing } from "./easing.js";
+import { Tween } from "./tween.js";
+/**
+ * Tweenetik module for declarative, time-managed UI animations.
+ *
+ * @class Tweenetik
+ * @description
+ * Tweenetik provides a lightweight, self-managed tweening system that animates object properties over time.
+ * Unlike {@link Motion}, which returns stateless values for use in real-time game loops,
+ * Tweenetik mutates the target object directly and manages its own internal time progression.
+ * <br/>
+ * It is ideal for UI transitions, hover effects, attention animations, or any element
+ * that animates independently of the simulation/game loop logic.
+ * <br/>
+ * Tweenetik is declarative: you configure a tween once and let it run in the background.
+ * You must call {@link Tweenetik.updateAll} on each frame to drive all active tweens.
+ * <br/>
+ * @example
+ * Tweenetik.to(button, { scaleX: 1.2, scaleY: 1.2 }, 0.5, Easing.easeOutBack);
+ *
+ * @see {@link Tween} for interpolation utilities
+ * @see {@link Motion} for stateless simulation-driven animations
+ */
+
+export class Tweenetik {
+  /**
+   * @param {Object} target - The object whose properties will be tweened.
+   * @param {Object} toProps - An object containing the property values we want to end up at (e.g. { x: 100, y: 200 }).
+   * @param {number} duration - How long (in seconds) the tween should take.
+   * @param {Function} easingFn - One of the easing functions from the Tween class (e.g. Easing.easeOutBounce).
+   * @param {Object} [options]
+   * @param {number} [options.delay=0] - Delay in seconds before starting.
+   * @param {Function} [options.onStart] - Callback invoked once when the tween actually begins.
+   * @param {Function} [options.onComplete] - Callback invoked once when the tween finishes.
+   * @param {Function} [options.onUpdate] - Callback invoked every frame (after the object’s properties are updated).
+   */
+  constructor(target, toProps, duration, easingFn, options = {}) {
+    this.target = target;
+    this.toProps = { ...toProps };
+    this.duration = duration;
+    this.easingFn = easingFn || Easing.easeOutQuad;
+
+    // Options
+    this.delay = options.delay || 0;
+    this.onStart = options.onStart || null;
+    this.onComplete = options.onComplete || null;
+    this.onUpdate = options.onUpdate || null;
+
+    // Internal
+    this._elapsed = 0;
+    this._started = false;
+    this._finished = false;
+    this._startProps = {};
+
+    for (const prop in this.toProps) {
+      if (prop in this.target) {
+        this._startProps[prop] = this.target[prop];
+      }
+    }
+  }
+
+  /**
+   * Creates and registers a new Tweenetik instance in the global list.
+   * @param {Object} target
+   * @param {Object} toProps
+   * @param {number} duration
+   * @param {Function} easingFn
+   * @param {Object} [options]
+   */
+  static to(target, toProps, duration, easingFn, options) {
+    const tween = new Tweenetik(target, toProps, duration, easingFn, options);
+    Tweenetik._active.push(tween);
+    return tween;
+  }
+
+  /**
+   * Updates this tween by the given delta time (in seconds).
+   * @param {number} dt
+   */
+  update(dt) {
+    if (this._finished) return;
+
+    this._elapsed += dt;
+
+    // Wait until the delay has passed
+    if (this._elapsed < this.delay) {
+      return;
+    }
+
+    // Time in tween (after delay)
+    const timeSinceDelay = this._elapsed - this.delay;
+    const t = Math.min(timeSinceDelay / this.duration, 1);
+
+    // onStart callback (once)
+    if (!this._started && t > 0) {
+      this._started = true;
+      if (this.onStart) {
+        this.onStart();
+      }
+    }
+
+    // Calculate eased factor
+    const eased = this.easingFn(t);
+    //console.log("Tweenetik.update", this._startProps);
+    // Apply interpolations for each property
+    for (const prop in this._startProps) {
+      const startVal = this._startProps[prop];
+      const endVal = this.toProps[prop];
+      // Use Tween.go(...) to interpolate
+      this.target[prop] = Tween.lerp(startVal, endVal, eased);
+    }
+
+    // onUpdate callback (each frame)
+    if (this.onUpdate) {
+      this.onUpdate();
+    }
+
+    // Check if finished
+    if (t >= 1) {
+      this._finished = true;
+      if (this.onComplete) {
+        this.onComplete();
+      }
+    }
+  }
+
+  /**
+   * Update all active tweens by dt. Call this once each frame in your main loop.
+   * @param {number} dt
+   */
+  static updateAll(dt) {
+    for (const tween of Tweenetik._active) {
+      tween.update(dt);
+    }
+    // Remove finished tweens from the list
+    Tweenetik._active = Tweenetik._active.filter((t) => !t._finished);
+  }
+}