Utilities

/**
 * Get property value from target
 * @param targetSelector - Target element or object
 * @param propName - Property name to get
 * @param unit - Optional unit to append or boolean to get with unit
 * @returns Property value
 */
function get(
  targetSelector: TargetsParam,
  propName: string,
  unit?: string | boolean
): string | number;

import { get } from "animejs/utils";

// Get CSS property
const width = get(".box", "width"); // "200px"
const widthNum = get(".box", "width", false); // 200

// Get with specific unit
const widthRem = get(".box", "width", "rem"); // "12.5rem"

// Get transform property
const x = get(".box", "translateX"); // "100px"

// Get JS object property
const obj = { x: 100 };
const value = get(obj, "x"); // 100

/**
 * Set properties on targets instantly (no animation)
 * @param targets - Target elements or objects
 * @param parameters - Properties to set
 * @returns JSAnimation instance
 */
function set(targets: TargetsParam, parameters: AnimationParams): JSAnimation;

import { set } from "animejs/utils";

// Set CSS properties
set(".box", {
  opacity: 0.5,
  translateX: 100,
  scale: 1.5,
});

// Set multiple targets
set(".items", {
  backgroundColor: "#ff0000",
  x: 0,
  y: 0,
});

// Set JS object properties
const obj = { value: 0 };
set(obj, { value: 100 });
console.log(obj.value); // 100

/**
 * Remove animations from targets
 * @param targets - Target elements or objects
 * @param renderable - Specific animation to remove (optional)
 * @param propertyName - Specific property to remove (optional)
 * @returns TargetsArray
 */
function remove(
  targets: TargetsParam,
  renderable?: Renderable | WAAPIAnimation,
  propertyName?: string
): TargetsArray;

import { animate, remove } from "animejs";

const anim = animate(".box", { x: 100, y: 100, rotate: 360 });

// Remove specific animation
remove(".box", anim);

// Remove specific property animation
remove(".box", anim, "rotate");

// Remove all animations from target
remove(".box");

/**
 * Register targets for animation
 * Resolves selectors and caches results
 * @param targets - Target selector, element(s), or objects
 * @returns Registered targets array
 */
function registerTargets(targets: TargetsParam): TargetsArray;

/** Alias for registerTargets */
function $(targets: TargetsParam): TargetsArray;

import { $, animate } from "animejs";

// Register targets
const targets = $(".boxes");

// Use registered targets
animate(targets, { x: 100 });
animate(targets, { y: 100 });

// Also works with elements
const elements = document.querySelectorAll(".items");
const registered = $(elements);

/**
 * Clean inline styles from target elements
 * Removes styles set by animations
 * @param targets - Target elements to clean
 */
function cleanInlineStyles(targets: TargetsParam): void;

import { animate, cleanInlineStyles } from "animejs";

// Animate elements
animate(".boxes", {
  x: 100,
  opacity: 0.5,
});

// Later, remove all inline styles
cleanInlineStyles(".boxes");

/**
 * Create staggered value distribution
 * @param value - Single value, range [start, end], or array of values
 * @param params - Stagger configuration
 * @returns StaggerFunction
 */
function stagger(
  value: number | string | [number, number] | [string, string],
  params?: StaggerParams
): StaggerFunction<number | string>;

import { animate, stagger } from "animejs";

// Basic stagger
animate(".boxes", {
  translateX: 250,
  delay: stagger(100), // 0ms, 100ms, 200ms, 300ms...
});

// Stagger with range
animate(".boxes", {
  translateX: stagger([0, 250]), // Distribute values 0 to 250
  duration: 1000,
});

// Stagger from center
animate(".grid-items", {
  scale: stagger([1, 1.5], {
    from: "center",
  }),
  delay: stagger(50, {
    from: "center",
  }),
});

// Stagger from specific index
animate(".items", {
  opacity: stagger([0, 1], {
    from: 5, // Start from 5th item
  }),
});

// Grid stagger
animate(".grid", {
  scale: stagger([0.5, 1], {
    grid: [10, 10], // 10x10 grid
    from: "center",
  }),
  delay: stagger(20, {
    grid: [10, 10],
    from: "center",
  }),
});

// Ease stagger distribution
animate(".boxes", {
  translateY: stagger([100, 0], {
    ease: "outQuad", // Apply easing to stagger distribution
  }),
});

// Direction
animate(".boxes", {
  delay: stagger(50, {
    direction: "reverse", // Reverse stagger order
  }),
});

// Axis (for grids)
animate(".grid", {
  delay: stagger(30, {
    grid: [5, 5],
    axis: "x", // Stagger along x-axis first
  }),
});

/**
 * Generate random number within range
 * @param min - Minimum value (default: 0)
 * @param max - Maximum value (default: 1)
 * @param decimalLength - Number of decimal places (default: 0)
 * @returns Random number
 */
function random(min?: number, max?: number, decimalLength?: number): number;

import { animate, random } from "animejs";

// Random integer 0-100
random(0, 100); // e.g., 42

// Random decimal
random(0, 1, 2); // e.g., 0.73

// Random in animation
animate(".boxes", {
  translateX: () => random(-200, 200),
  translateY: () => random(-200, 200),
  rotate: () => random(-180, 180),
  scale: () => random(0.5, 1.5, 2),
});

/**
 * Create seeded random number generator
 * @param seed - Random seed
 * @param seededMin - Default minimum value
 * @param seededMax - Default maximum value
 * @param seededDecimalLength - Default decimal places
 * @returns Random number generator function
 */
function createSeededRandom(
  seed?: number,
  seededMin?: number,
  seededMax?: number,
  seededDecimalLength?: number
): RandomNumberGenerator;

/**
 * Random number generator type
 */
type RandomNumberGenerator = (
  min?: number,
  max?: number,
  decimalLength?: number
) => number;

import { animate, createSeededRandom } from "animejs";

// Create seeded random
const seededRandom = createSeededRandom(12345);

// Same seed = same sequence
animate(".boxes", {
  translateX: () => seededRandom(-100, 100),
  translateY: () => seededRandom(-100, 100),
  // Will generate same positions every time
});

// With defaults
const rangedRandom = createSeededRandom(67890, -200, 200, 0);
rangedRandom(); // Uses default range and no decimals

/**
 * Pick random item from array or character from string
 * @param items - Array or string to pick from
 * @returns Random item or character
 */
function randomPick<T>(items: string | Array<T>): string | T;

import { animate, randomPick } from "animejs";

// Pick from array
const colors = ["#ff0000", "#00ff00", "#0000ff"];
const color = randomPick(colors); // Random color

// Pick from string
const char = randomPick("ABCDEFGHIJKLMNOPQRSTUVWXYZ");

// In animation
animate(".boxes", {
  backgroundColor: () => randomPick(["#ff6b6b", "#4ecdc4", "#45b7d1"]),
});

/**
 * Shuffle array items randomly
 * Modifies array in place
 * @param items - Array to shuffle
 * @returns Shuffled array
 */
function shuffle<T>(items: Array<T>): Array<T>;

import { shuffle } from "animejs";

const items = [1, 2, 3, 4, 5];
shuffle(items); // e.g., [3, 1, 5, 2, 4]

// Shuffle animation order
const elements = Array.from(document.querySelectorAll(".box"));
const shuffled = shuffle([...elements]);

shuffled.forEach((el, i) => {
  animate(el, {
    translateX: 100,
    delay: i * 50,
  });
});

/**
 * Synchronize callback with animation engine loop
 * @param callback - Function to call on each frame
 * @returns Timer instance
 */
function sync(callback?: Callback<Timer>): Timer;

import { sync } from "animejs";

// Sync with animation loop
const timer = sync((t) => {
  console.log(`Frame: ${t.currentTime}`);
  // Custom per-frame logic
});

// Stop syncing
timer.cancel();

/**
 * Keep animation time when refreshing
 * Wraps constructor to maintain timing state
 * @param constructor - Function that returns Tickable animation
 * @returns Wrapped constructor function
 */
function keepTime(constructor: () => Tickable): () => Tickable;

import { keepTime, animate } from "animejs";

const createAnimation = keepTime(() => {
  return animate(".box", {
    rotate: 360,
    duration: 5000,
    loop: true,
  });
});

let anim = createAnimation();

// Later, recreate while maintaining time
anim.cancel();
anim = createAnimation(); // Continues from where it left off

/**
 * Clamp value between min and max
 * @param value - Value to clamp
 * @param min - Minimum value
 * @param max - Maximum value
 * @returns Clamped value
 */
function clamp(value: number, min: number, max: number): number;

import { clamp } from "animejs/utils";

clamp(150, 0, 100); // 100
clamp(-10, 0, 100); // 0
clamp(50, 0, 100); // 50

// In animation
animate(".box", {
  translateX: (el, i) => clamp(i * 50, 0, 300),
});

/**
 * Round to decimal places
 * @param value - Value to round
 * @param decimalLength - Number of decimal places
 * @returns Rounded value
 */
function round(value: number, decimalLength: number): number;

import { round } from "animejs/utils";

round(3.14159, 2); // 3.14
round(123.456, 0); // 123
round(1.5, 0); // 2

/**
 * Snap value to increment or array of values
 * @param value - Value to snap
 * @param increment - Snap increment or array of snap points
 * @returns Snapped value
 */
function snap(value: number, increment: number | Array<number>): number;

import { snap } from "animejs/utils";

// Snap to increment
snap(47, 10); // 50
snap(123, 25); // 125

// Snap to array values
snap(47, [0, 25, 50, 75, 100]); // 50
snap(12, [0, 25, 50, 75, 100]); // 0

// In draggable
createDraggable(".slider", {
  onRelease: (self) => {
    self.x = snap(self.x, 50);
  },
});

/**
 * Wrap value within range
 * @param value - Value to wrap
 * @param min - Minimum value
 * @param max - Maximum value
 * @returns Wrapped value
 */
function wrap(value: number, min: number, max: number): number;

import { wrap } from "animejs/utils";

wrap(150, 0, 100); // 50
wrap(-10, 0, 100); // 90
wrap(50, 0, 100); // 50

// Circular rotation
animate(".wheel", {
  rotate: (el, i) => wrap(i * 45, 0, 360),
});

/**
 * Linear interpolation
 * @param start - Start value
 * @param end - End value
 * @param amount - Interpolation amount (0-1)
 * @returns Interpolated value
 */
function lerp(start: number, end: number, amount: number): number;

import { lerp } from "animejs/utils";

lerp(0, 100, 0.5); // 50
lerp(0, 100, 0.25); // 25
lerp(50, 150, 0.5); // 100

// Smooth following
let currentX = 0;
const targetX = 100;

function update() {
  currentX = lerp(currentX, targetX, 0.1);
}

/**
 * Damped interpolation
 * @param start - Start value
 * @param end - End value
 * @param deltaTime - Time delta in milliseconds
 * @param factor - Damping factor (higher = slower)
 * @returns Damped value
 */
function damp(
  start: number,
  end: number,
  deltaTime: number,
  factor: number
): number;

import { damp } from "animejs/utils";

let position = 0;
const target = 100;
const dampingFactor = 0.1;
let lastTime = performance.now();

function update(currentTime) {
  const deltaTime = currentTime - lastTime;
  position = damp(position, target, deltaTime, dampingFactor);
  lastTime = currentTime;
  requestAnimationFrame(update);
}

/**
 * Map value from one range to another
 * @param value - Input value
 * @param inLow - Input range minimum
 * @param inHigh - Input range maximum
 * @param outLow - Output range minimum
 * @param outHigh - Output range maximum
 * @returns Mapped value
 */
function mapRange(
  value: number,
  inLow: number,
  inHigh: number,
  outLow: number,
  outHigh: number
): number;

import { mapRange } from "animejs/utils";

mapRange(50, 0, 100, 0, 1); // 0.5
mapRange(25, 0, 100, 0, 255); // 63.75
mapRange(5, 0, 10, -1, 1); // 0

// Map scroll to animation progress
window.addEventListener("scroll", () => {
  const scrollY = window.scrollY;
  const maxScroll = document.body.scrollHeight - window.innerHeight;
  const progress = mapRange(scrollY, 0, maxScroll, 0, 1);

  anim.progress = progress;
});

/**
 * Round with padding
 * @param value - Value to round
 * @param decimalLength - Decimal places with padding
 * @returns Rounded and padded string
 */
function roundPad(value: number, decimalLength: number): string;

import { roundPad } from "animejs/utils";

roundPad(3.1, 2); // "3.10"
roundPad(123.456, 2); // "123.46"
roundPad(5, 3); // "5.000"

/**
 * Pad start of string
 * @param value - Value to pad
 * @param totalLength - Total desired length
 * @param padString - String to pad with
 * @returns Padded string
 */
function padStart(
  value: string | number,
  totalLength: number,
  padString: string
): string;

import { padStart } from "animejs/utils";

padStart("5", 3, "0"); // "005"
padStart("42", 5, "0"); // "00042"
padStart(7, 2, "0"); // "07"

/**
 * Pad end of string
 * @param value - Value to pad
 * @param totalLength - Total desired length
 * @param padString - String to pad with
 * @returns Padded string
 */
function padEnd(
  value: string | number,
  totalLength: number,
  padString: string
): string;

import { padEnd } from "animejs/utils";

padEnd("5", 3, "0"); // "500"
padEnd("42", 5, "0"); // "42000"

/**
 * Convert degrees to radians
 * @param degrees - Angle in degrees
 * @returns Angle in radians
 */
function degToRad(degrees: number): number;

import { degToRad } from "animejs/utils";

degToRad(180); // 3.14159...
degToRad(90); // 1.5708...
degToRad(45); // 0.7854...

/**
 * Convert radians to degrees
 * @param radians - Angle in radians
 * @returns Angle in degrees
 */
function radToDeg(radians: number): number;

import { radToDeg } from "animejs/utils";

radToDeg(Math.PI); // 180
radToDeg(Math.PI / 2); // 90
radToDeg(Math.PI / 4); // 45

import { utils } from "animejs";

// Chain utility methods
const result = utils
  .clamp(150, 0, 100)
  .round(2)
  .padStart(5, "0");

// Use in complex calculations
const value = utils
  .mapRange(scrollY, 0, maxScroll, 0, 360)
  .wrap(0, 360)
  .round(0);

/**
 * Stagger configuration parameters
 */
interface StaggerParams {
  /** Start position: 'first', 'center', 'last', 'random', or index number */
  from?: "first" | "center" | "last" | "random" | number;

  /** Reverse stagger order */
  reversed?: boolean;

  /** Grid dimensions [columns, rows] for 2D stagger */
  grid?: [number, number];

  /** Grid axis: 'x' or 'y' */
  axis?: "x" | "y";

  /** Easing function for stagger distribution */
  ease?: EasingParam;

  /** Start value (alternative to value array) */
  start?: number | string;

  /** Property to use for distance calculation or custom function */
  use?: string | ((target: any, index: number, length: number) => number);

  /** Total number of elements (override automatic count) */
  total?: number;

  /** Value modifier function */
  modifier?: TweenModifier;
}

/**
 * Stagger function type
 */
type StaggerFunction<T> = (target: any, index: number, total: number) => T;

/**
 * Random number generator type
 */
type RandomNumberGenerator = (
  min?: number,
  max?: number,
  decimalLength?: number
) => number;

/**
 * Targets parameter type
 */
type TargetsParam =
  | string
  | HTMLElement
  | SVGElement
  | NodeList
  | Array<HTMLElement | SVGElement>
  | object
  | Array<object>;

/**
 * Targets array type
 */
type TargetsArray = Array<HTMLElement | SVGElement | object>;

/**
 * Callback function type
 */
type Callback<T> = (instance: T) => void;

/**
 * Tickable animation or timer
 */
type Tickable = Timer | JSAnimation | Timeline;