Core Animation

/**
 * Creates and starts an animation on specified targets
 * @param targets - DOM elements, selectors, or JS objects to animate
 * @param parameters - Animation configuration and properties
 * @returns JSAnimation instance with playback controls
 */
function animate(
  targets: TargetsParam,
  parameters: AnimationParams
): JSAnimation;

import { animate } from 'animejs';

// Animate CSS properties
animate('.box', {
  translateX: 250,
  rotate: '1turn',
  backgroundColor: '#FFF',
  borderRadius: ['0%', '50%'],
  duration: 800,
  ease: 'outQuad'
});

// Animate with delays and callbacks
animate('div', {
  opacity: [0, 1],
  translateY: [-30, 0],
  duration: 600,
  delay: (el, i) => i * 100,
  onBegin: (anim) => console.log('started'),
  onComplete: (anim) => console.log('completed')
});

// Animate JavaScript objects
const myObject = { progress: 0, value: 0 };
animate(myObject, {
  progress: 100,
  value: [0, 1000],
  duration: 2000,
  ease: 'linear',
  onUpdate: (anim) => {
    console.log(myObject.progress, myObject.value);
  }
});

/**
 * Animation instance extending Timer with rendering capabilities
 */
interface JSAnimation extends Timer {
  /** Array of animation targets */
  targets: TargetsArray;

  /** Render callback invoked on each frame */
  onRender: Callback<JSAnimation>;

  /**
   * Stretch the animation to a new duration
   * @param newDuration - The target duration in milliseconds
   * @returns The animation instance for chaining
   */
  stretch(newDuration: number): this;

  /**
   * Refresh the animation's starting values
   * @returns The animation instance for chaining
   */
  refresh(): this;

  /**
   * Cancel the animation and revert all values to their original state
   * @returns The animation instance for chaining
   */
  revert(): this;

  /**
   * Promise-like interface for animation completion
   * @param callback - Function called when animation completes
   * @returns Promise that resolves with the animation
   */
  then(callback?: Callback<JSAnimation>): Promise<JSAnimation>;
}

const anim = animate('.element', {
  x: 100,
  duration: 1000
});

// Control playback
anim.pause();
anim.play();
anim.reverse();
anim.restart();

// Seek to specific time
anim.seek(500); // Jump to 500ms

// Stretch duration
anim.stretch(2000); // Change to 2 seconds

// Revert to original values
anim.revert();

// Promise-like completion
anim.then(() => console.log('Animation complete'));

// Or with async/await
await anim;
console.log('Animation complete');

animate('.box', {
  // CSS properties (camelCase)
  translateX: 100,
  translateY: 50,
  rotate: 180,
  scale: 1.5,
  opacity: 0.5,
  backgroundColor: '#FF0000',
  borderRadius: '50%',

  // SVG attributes
  points: '0,0 100,50 50,100',
  d: 'M0,0 L100,100',

  // DOM attributes
  value: 100,

  // Object properties
  progress: 100
});

type TweenOptions =
  | number
  | string
  | FunctionValue
  | TweenKeyValue
  | Array<TweenKeyValue>;

interface TweenKeyValue {
  /** Starting value (optional) */
  from?: number | string | FunctionValue;

  /** Ending value */
  to?: number | string | FunctionValue;

  /** Both from and to as a tuple */
  fromTo?: [number | string, number | string];

  /** Duration for this property */
  duration?: number | FunctionValue;

  /** Delay for this property */
  delay?: number | FunctionValue;

  /** Easing for this property */
  ease?: EasingParam;

  /** Value modifier function */
  modifier?: (value: number) => number | string;

  /** Composition mode */
  composition?: 'none' | 'replace' | 'blend';
}

animate('.box', {
  // Simple value
  x: 100,

  // From-to array
  y: [0, 50],

  // Function value (per-target)
  rotate: (el, i) => i * 45,

  // Object notation
  scale: {
    from: 0.5,
    to: 1.5,
    ease: 'outElastic'
  },

  // Keyframe array
  translateX: [
    { to: 100, duration: 500 },
    { to: 0, duration: 500 }
  ]
});

interface AnimationParams {
  /** Animation duration in milliseconds or with unit */
  duration?: number | string | FunctionValue;

  /** Delay before animation starts */
  delay?: number | string | FunctionValue;

  /** Delay between loop iterations */
  loopDelay?: number;

  /** Number of loops or true for infinite */
  loop?: number | boolean;

  /** Alternate direction on each loop */
  alternate?: boolean;

  /** Start in reversed direction */
  reversed?: boolean;

  /** Auto-start animation or link to scroll */
  autoplay?: boolean | ScrollObserver;

  /** Frame rate limit (fps) */
  frameRate?: number;

  /** Playback speed multiplier */
  playbackRate?: number;
}

// Duration with units
animate('.box', { x: 100, duration: '1s' });
animate('.box', { x: 100, duration: 1000 }); // milliseconds

// Function-based delays
animate('.box', {
  x: 100,
  delay: (el, i, total) => i * 100 // Stagger effect
});

// Looping
animate('.box', {
  rotate: 360,
  loop: true, // Infinite
  duration: 2000
});

// Alternating loop
animate('.box', {
  x: [0, 100],
  loop: 5,
  alternate: true, // Goes 0→100→0→100...
  duration: 500
});

// Slow motion
animate('.box', {
  x: 100,
  duration: 1000,
  playbackRate: 0.5 // 2x slower
});

interface AnimationParams {
  /** Easing function for property interpolation */
  ease?: EasingParam;

  /** Easing for timeline playback */
  playbackEase?: EasingParam;
}

type EasingParam = string | EasingFunction | Spring;
type EasingFunction = (time: number) => number;

// String easings
animate('.box', { x: 100, ease: 'inOutQuad' });
animate('.box', { x: 100, ease: 'outElastic' });

// Spring physics
import { spring } from 'animejs';
animate('.box', {
  x: 100,
  ease: spring({ stiffness: 100, damping: 10 })
});

// Custom function
animate('.box', {
  x: 100,
  ease: (t) => t * t // Custom quadratic
});

// Per-property easing
animate('.box', {
  x: { to: 100, ease: 'outQuad' },
  y: { to: 50, ease: 'outCubic' }
});

interface AnimationParams {
  /** Percentage-based keyframes */
  keyframes?: PercentageKeyframes;
}

type PercentageKeyframes = Record<string, Record<string, number | string>>;

// Percentage keyframes
animate('.box', {
  keyframes: {
    '0%': { x: 0, y: 0 },
    '50%': { x: 100, y: 50 },
    '100%': { x: 0, y: 100 }
  },
  duration: 2000
});

// Duration-based keyframes (array syntax)
animate('.box', {
  x: [
    { to: 100, duration: 500, ease: 'outQuad' },
    { to: 200, duration: 300, ease: 'outCubic' },
    { to: 0, duration: 500, ease: 'inQuad' }
  ]
});

interface AnimationParams {
  /** Called when animation begins (after delay) */
  onBegin?: Callback<JSAnimation>;

  /** Called before each update */
  onBeforeUpdate?: Callback<JSAnimation>;

  /** Called on each frame */
  onUpdate?: Callback<JSAnimation>;

  /** Called on each render frame */
  onRender?: Callback<JSAnimation>;

  /** Called on each loop iteration */
  onLoop?: Callback<JSAnimation>;

  /** Called when paused */
  onPause?: Callback<JSAnimation>;

  /** Called when completed */
  onComplete?: Callback<JSAnimation>;
}

type Callback<T> = (self: T) => any;

animate('.box', {
  x: 100,
  duration: 1000,
  onBegin: (anim) => {
    console.log('Animation started');
  },
  onUpdate: (anim) => {
    console.log('Progress:', anim.progress);
  },
  onComplete: (anim) => {
    console.log('Animation finished');
  }
});

// Replace previous animations (default)
animate('.box', { x: 100, composition: 'replace' });

// Blend with previous animations
animate('.box', { x: 100, composition: 'blend' });

// Don't affect other animations
animate('.box', { x: 100, composition: 'none' });

animate('.box', {
  x: {
    to: 100,
    modifier: (value) => Math.round(value) + 'px'
  }
});

animate('.box', {
  x: (el, i, total) => {
    return (i / total) * 100;
  },
  rotate: (el) => {
    return el.dataset.rotate || 0;
  }
});

type TargetsParam =
  | string
  | HTMLElement
  | SVGElement
  | object
  | NodeList
  | Array<HTMLElement | SVGElement | object>;

type TargetsArray = Array<HTMLElement | SVGElement | object>;

type FunctionValue = (target: any, index: number, length: number) => any;

interface SpringParams {
  mass?: number;
  stiffness?: number;
  damping?: number;
  velocity?: number;
  bounce?: number;
  duration?: number;
}

interface Spring {
  mass: number;
  stiffness: number;
  damping: number;
  velocity: number;
  bounce: number;
  duration: number;
  ease: EasingFunction;
  solve(time: number): number;
}