Timeline

/**
 * Creates a timeline for sequencing and synchronizing multiple animations
 * @param parameters - Optional timeline configuration parameters
 * @returns Timeline instance with sequencing capabilities
 */
function createTimeline(parameters?: TimelineParams): Timeline;

import { createTimeline, animate } from "animejs";

const tl = createTimeline({
  loop: 2,
  direction: "alternate",
  autoplay: false,
});

// Add animations with relative timing
tl.add(".box1", { translateX: 250 })
  .add(".box2", { translateX: 250 }, "-=200") // Start 200ms before previous ends
  .add(".box3", { translateX: 250 }, "+=100"); // Start 100ms after previous ends

tl.play();

/**
 * Timeline class for sequencing and synchronizing multiple animations
 * Extends Timer to inherit all timing controls
 */
class Timeline extends Timer {
  /** Named timeline positions for reusable timing references */
  labels: Record<string, number>;

  /** Default parameters applied to all child animations */
  defaults: DefaultsParams;

  /** Callback function called on each render update */
  onRender: Callback<Timeline>;

  /**
   * Add animation to timeline at specified position
   * @param targets - Animation targets (DOM elements, objects, etc.)
   * @param parameters - Animation parameters
   * @param position - Timeline position (ms, '+=ms', '-=ms', label, or stagger)
   * @returns Timeline instance for chaining
   */
  add(
    targets: TargetsParam,
    parameters: AnimationParams,
    position?: TimelineAnimationPosition
  ): Timeline;

  /**
   * Add timer or animation to timeline
   * @param timerParams - Timer configuration
   * @param position - Timeline position
   * @returns Timeline instance for chaining
   */
  add(timerParams: TimerParams, position?: TimelinePosition): Timeline;

  /**
   * Synchronize external animation with timeline
   * @param animation - External animation or timer to sync
   * @param position - Timeline position to sync at
   * @returns Timeline instance for chaining
   */
  sync(
    animation: Tickable | WAAPIAnimation,
    position?: TimelinePosition
  ): Timeline;

  /**
   * Set property values instantly at timeline position
   * @param targets - Target elements or objects
   * @param parameters - Properties to set
   * @param position - Timeline position
   * @returns Timeline instance for chaining
   */
  set(
    targets: TargetsParam,
    parameters: AnimationParams,
    position?: TimelinePosition
  ): Timeline;

  /**
   * Call function at specific timeline position
   * @param callback - Callback function to execute
   * @param position - Timeline position
   * @returns Timeline instance for chaining
   */
  call(callback: Callback<Timer>, position?: TimelinePosition): Timeline;

  /**
   * Create named position in timeline for timing references
   * @param labelName - Name for the label
   * @param position - Timeline position (defaults to current time)
   * @returns Timeline instance for chaining
   */
  label(labelName: string, position?: TimelinePosition): Timeline;

  /**
   * Remove animations from timeline
   * @param targets - Targets to remove animations from
   * @param propertyName - Specific property to remove (optional)
   * @returns Timeline instance for chaining
   */
  remove(targets: TargetsParam, propertyName?: string): Timeline;

  /**
   * Stretch timeline to new duration, adjusting all child timings proportionally
   * @param newDuration - New total duration in milliseconds
   * @returns Timeline instance for chaining
   */
  stretch(newDuration: number): Timeline;

  /**
   * Refresh timeline and all child animations
   * @returns Timeline instance for chaining
   */
  refresh(): Timeline;

  /**
   * Revert all timeline animations to initial state
   * @returns Timeline instance for chaining
   */
  revert(): Timeline;

  /**
   * Promise-like interface for timeline completion
   * @param callback - Function to call when timeline completes
   * @returns Timeline instance for chaining
   */
  then(callback: (timeline: Timeline) => void): Timeline;
}

import { createTimeline } from "animejs";

// Complex sequence with labels
const tl = createTimeline();

tl.add(".intro", { opacity: [0, 1], duration: 1000 })
  .label("intro-complete")
  .add(".title", { translateY: [-50, 0], duration: 800 }, "intro-complete")
  .add(".subtitle", { translateY: [-30, 0] }, "-=400")
  .label("text-complete")
  .add(".button", { scale: [0, 1] }, "text-complete+=200");

// Synchronized animations
const animation1 = animate(".element1", { rotate: 360 });
tl.sync(animation1, 500); // Sync animation1 at 500ms

// Set values instantly
tl.set(".hidden", { opacity: 0 }, 0); // Set at timeline start

// Call functions at specific times
tl.call(() => console.log("Halfway!"), "50%").call(
  () => console.log("Done!"),
  tl.duration
);

/**
 * Timeline position specifier
 * Accepts:
 * - Number: Absolute position in milliseconds (e.g., 500)
 * - '+=Number': Addition relative to previous animation end (e.g., '+=100')
 * - '-=Number': Subtraction relative to previous animation end (e.g., '-=100')
 * - '*=Number': Multiplier, fraction of total duration (e.g., '*=.5')
 * - '<': At end of previous animation (default behavior)
 * - '<<': At start of previous animation
 * - '<<+=Number': Relative to previous animation start (e.g., '<<+=250')
 * - '<<-=Number': Before previous animation start (e.g., '<<-=100')
 * - 'labelName': At named label position
 */
type TimelinePosition =
  | number
  | `+=${number}`
  | `-=${number}`
  | `*=${number}`
  | "<"
  | "<<"
  | `<<+=${number}`
  | `<<-=${number}`
  | string;

/**
 * Timeline animation position (includes stagger support)
 */
type TimelineAnimationPosition = TimelinePosition | StaggerFunction<number | string>;

tl.add(".box", { x: 100 }, 1000); // At 1000ms
tl.add(".box", { x: 100 }, "+=500"); // 500ms after previous ends
tl.add(".box", { x: 100 }, "-=200"); // 200ms before previous ends
tl.add(".box", { x: 100 }, "*=0.5"); // At 50% of timeline duration
tl.add(".box", { x: 100 }, "myLabel"); // At label position
tl.add(".box", { x: 100 }, "myLabel+=300"); // 300ms after label
tl.add(".box", { x: 100 }, "<"); // At previous animation end (default)
tl.add(".box", { x: 100 }, "<<"); // At previous animation start
tl.add(".box", { x: 100 }, "<<+=100"); // 100ms after previous start
tl.add(".box", { x: 100 }, "<<-=50"); // 50ms before previous start

const tl = createTimeline({
  defaults: {
    duration: 1000,
    ease: "outQuad",
  },
});

// These will use default duration and easing
tl.add(".box1", { x: 100 })
  .add(".box2", { x: 100 })
  .add(".box3", { x: 100, duration: 500 }); // Override default

const tl = createTimeline({
  onBegin: (tl) => console.log("Timeline started"),
  onUpdate: (tl) => console.log(`Progress: ${tl.progress}`),
  onLoop: (tl) => console.log("Timeline looped"),
  onComplete: (tl) => console.log("Timeline completed"),
  onRender: (tl) => console.log("Render frame"),
});

const main = createTimeline();
const intro = createTimeline();
const outro = createTimeline();

intro
  .add(".title", { opacity: [0, 1] })
  .add(".subtitle", { opacity: [0, 1] });

outro
  .add(".content", { opacity: [1, 0] })
  .add(".footer", { opacity: [1, 0] });

main.add(intro, 0).add(outro, 3000);

const tl = createTimeline();
tl.add(".box1", { x: 100, duration: 1000 }).add(".box2", {
  x: 100,
  duration: 1000,
});

console.log(tl.duration); // 2000ms

// Stretch to 4 seconds, all child animations scale proportionally
tl.stretch(4000);
console.log(tl.duration); // 4000ms

const tl = createTimeline();
tl.add(".box", { x: 100, y: 100, rotate: 360 });

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

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

/**
 * Timeline configuration parameters
 */
interface TimelineParams extends TimerParams {
  /** Default parameters for all child animations */
  defaults?: DefaultsParams;

  /** Callback called on each render update */
  onRender?: Callback<Timeline>;
}

/**
 * Default parameters applied to child animations
 */
interface DefaultsParams {
  /** Default animation duration */
  duration?: number;

  /** Default easing function */
  ease?: EasingParam;

  /** Default composition mode */
  composition?: TweenComposition;

  /** Default modifier function */
  modifier?: TweenModifier;

  /** Any other animation parameter */
  [key: string]: any;
}

/**
 * Timeline position specifier
 */
type TimelinePosition = number | string;