Timeline System

/**
 * Creates a new Timeline for sequencing animations
 * @param vars - Timeline configuration options
 * @returns Timeline instance for chaining operations
 */
gsap.timeline(vars?: gsap.TimelineVars): gsap.core.Timeline;

interface TimelineVars extends gsap.AnimationVars {
  autoRemoveChildren?: boolean;  // Auto-remove completed children
  smoothChildTiming?: boolean;   // Smooth child timing adjustments
  defaults?: gsap.TweenVars;    // Default properties for child tweens
  delay?: number;               // Timeline start delay
}

// Basic timeline
const tl = gsap.timeline();

// Timeline with configuration
const tl = gsap.timeline({
  repeat: 2,
  yoyo: true,
  defaults: { duration: 1, ease: "power2.out" }
});

// Paused timeline (start manually)
const tl = gsap.timeline({ paused: true });

interface Timeline extends gsap.core.Animation {
  /**
   * Add animation, timeline, or callback to the timeline
   * @param child - Animation, timeline, callback, or label
   * @param position - When to insert (relative to timeline end)
   * @returns Timeline instance for chaining
   */
  add(
    child: gsap.core.Animation | Function | string, 
    position?: string | number
  ): Timeline;
  
  /**
   * Add a label at the specified position
   * @param label - Label name
   * @param position - Position to place the label
   * @returns Timeline instance for chaining
   */
  addLabel(label: string, position?: string | number): Timeline;
}

const tl = gsap.timeline();

// Sequential animations (each starts when previous ends)
tl.add(gsap.to(".box1", { x: 100, duration: 1 }))
  .add(gsap.to(".box2", { y: 100, duration: 1 }))
  .add(gsap.to(".box3", { rotation: 360, duration: 1 }));

// Using position parameter
tl.add(gsap.to(".box1", { x: 100, duration: 1 }))
  .add(gsap.to(".box2", { y: 100, duration: 1 }), "-=0.5") // Start 0.5s before previous ends
  .add(gsap.to(".box3", { rotation: 360, duration: 1 }), "+=0.2"); // Start 0.2s after previous ends

// Adding labels
tl.addLabel("section1")
  .add(gsap.to(".box", { x: 100, duration: 1 }))
  .addLabel("section2", "+=0.5")
  .add(gsap.to(".box", { y: 100, duration: 1 }));

interface Timeline extends gsap.core.Animation {
  /**
   * Create and add a "to" tween to the timeline
   * @param targets - Elements to animate
   * @param vars - Animation properties
   * @param position - When to insert the animation
   * @returns Timeline instance for chaining
   */
  to(
    targets: gsap.TweenTarget, 
    vars: gsap.TweenVars, 
    position?: string | number
  ): Timeline;
  
  /**
   * Create and add a "from" tween to the timeline
   */
  from(
    targets: gsap.TweenTarget, 
    vars: gsap.TweenVars, 
    position?: string | number
  ): Timeline;
  
  /**
   * Create and add a "fromTo" tween to the timeline
   */
  fromTo(
    targets: gsap.TweenTarget,
    fromVars: gsap.TweenVars,
    toVars: gsap.TweenVars,
    position?: string | number
  ): Timeline;
  
  /**
   * Create and add a "set" call to the timeline
   */
  set(
    targets: gsap.TweenTarget, 
    vars: gsap.TweenVars, 
    position?: string | number
  ): Timeline;
  
  /**
   * Add a callback function to the timeline
   */
  call(
    callback: Function, 
    params?: any[], 
    scope?: object, 
    position?: string | number
  ): Timeline;
}

const tl = gsap.timeline();

// Chained inline animations
tl.to(".box", { x: 100, duration: 1 })
  .to(".box", { y: 100, duration: 1 })
  .to(".box", { rotation: 360, duration: 1 });

// Mixed positioning
tl.set(".element", { opacity: 0 })
  .from(".element", { scale: 0, duration: 1 })
  .to(".element", { opacity: 1, duration: 0.5 }, "-=0.5")
  .call(() => console.log("Animation complete!"));

interface Timeline extends gsap.core.Animation {
  /**
   * Get all child animations and timelines
   * @param nested - Include nested timeline children
   * @param tweensOnly - Return only tweens, not timelines
   * @param timelines - Return only timelines, not tweens
   * @returns Array of child animations
   */
  getChildren(nested?: boolean, tweensOnly?: boolean, timelines?: boolean): gsap.core.Animation[];
  
  /**
   * Get the most recently added child
   * @returns Most recent child animation
   */
  recent(): gsap.core.Animation;
  
  /**
   * Remove a child animation from the timeline
   * @param child - Animation to remove
   * @returns Timeline instance
   */
  remove(child: gsap.core.Animation): Timeline;
  
  /**
   * Remove all child animations
   * @returns Timeline instance
   */
  clear(): Timeline;
  
  /**
   * Shift all child positions by the specified amount
   * @param amount - Time to shift (positive or negative)
   * @param adjustLabels - Whether to adjust labels too
   * @param ignoreBeforeTime - Ignore children before this time
   * @returns Timeline instance
   */
  shiftChildren(amount: number, adjustLabels?: boolean, ignoreBeforeTime?: number): Timeline;
}

const tl = gsap.timeline();

// Add animations
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 100, duration: 1 });

// Get all children
const children = tl.getChildren();
console.log(`Timeline has ${children.length} children`);

// Remove the most recent animation
const lastChild = tl.recent();
tl.remove(lastChild);

// Clear all animations
tl.clear();

interface Timeline extends gsap.core.Animation {
  /**
   * Animate timeline playhead to a specific time
   * @param time - Target time position
   * @param vars - Animation configuration for the playhead tween
   * @returns Tween that animates the playhead
   */
  tweenTo(time: string | number, vars?: gsap.TweenVars): gsap.core.Tween;
  
  /**
   * Animate timeline playhead from one time to another
   * @param fromTime - Starting time position
   * @param toTime - Ending time position  
   * @param vars - Animation configuration for the playhead tween
   * @returns Tween that animates the playhead
   */
  tweenFromTo(fromTime: string | number, toTime: string | number, vars?: gsap.TweenVars): gsap.core.Tween;
}

const tl = gsap.timeline({ paused: true });
tl.to(".box", { x: 100, duration: 2 })
  .to(".box", { y: 100, duration: 2 })
  .addLabel("end");

// Animate playhead to specific position
tl.tweenTo("end", { duration: 1, ease: "power2.out" });

// Animate between two positions
tl.tweenFromTo(1, 3, { duration: 0.5 });

type PositionParameter = 
  | number              // Absolute time (e.g., 2 = 2 seconds)
  | string              // Relative to timeline end (e.g., "+=1", "-=0.5")
  | string;             // Label-based (e.g., "myLabel", "myLabel+=1")

const tl = gsap.timeline();

// Absolute positioning
tl.to(".box1", { x: 100, duration: 1 }, 0)     // Start at 0 seconds
  .to(".box2", { x: 100, duration: 1 }, 1)     // Start at 1 second
  .to(".box3", { x: 100, duration: 1 }, 2);    // Start at 2 seconds

// Relative positioning  
tl.to(".box1", { x: 100, duration: 1 })        // Default: end of timeline
  .to(".box2", { x: 100, duration: 1 }, "+=0.5") // 0.5s after previous ends
  .to(".box3", { x: 100, duration: 1 }, "-=0.5"); // 0.5s before previous ends

// Label-based positioning
tl.addLabel("start")
  .to(".box1", { x: 100, duration: 1 })
  .addLabel("middle")
  .to(".box2", { x: 100, duration: 1 }, "start+=0.5") // 0.5s after "start"
  .to(".box3", { x: 100, duration: 1 }, "middle");     // At "middle" label

// Master timeline
const masterTL = gsap.timeline();

// Sub-timelines
const intro = gsap.timeline()
  .from(".logo", { scale: 0, duration: 1 })
  .from(".nav", { y: -50, opacity: 0, duration: 0.5 });

const main = gsap.timeline()
  .to(".content", { x: 100, duration: 1 })
  .to(".sidebar", { x: -100, duration: 1 }, "-=0.5");

// Add sub-timelines to master
masterTL.add(intro)
  .add(main, "+=0.5")
  .to(".footer", { opacity: 1, duration: 0.5 });

interface Timeline extends gsap.core.Animation {
  // Properties
  labels: { [key: string]: number };    // Label positions
  autoRemoveChildren: boolean;          // Auto-removal setting
  smoothChildTiming: boolean;           // Smooth timing setting
  
  // Inherited from Animation
  duration(): number;                   // Total duration
  totalDuration(): number;              // Duration including repeats
  progress(): number;                   // Progress (0-1)
  time(): number;                       // Current time position
}

const tl = gsap.timeline();
tl.addLabel("start")
  .to(".box", { x: 100, duration: 2 })
  .addLabel("end");

// Access labels
console.log(tl.labels); // { start: 0, end: 2 }

// Timeline state
console.log(`Duration: ${tl.duration()}`);
console.log(`Progress: ${tl.progress()}`);
console.log(`Current time: ${tl.time()}`);