Animation Control

interface Animation {
  /**
   * Start or resume animation playback
   * @param from - Optional time to start from
   * @returns Animation instance for chaining
   */
  play(from?: number): Animation;
  
  /**
   * Pause the animation
   * @returns Animation instance for chaining
   */
  pause(): Animation;
  
  /**
   * Resume a paused animation
   * @returns Animation instance for chaining
   */
  resume(): Animation;
  
  /**
   * Reverse the animation direction
   * @param from - Optional time to reverse from
   * @returns Animation instance for chaining
   */
  reverse(from?: number): Animation;
  
  /**
   * Restart the animation from the beginning
   * @param includeDelay - Whether to include the initial delay
   * @returns Animation instance for chaining
   */
  restart(includeDelay?: boolean): Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2, paused: true });

// Control playback
tween.play();           // Start animation
tween.pause();          // Pause animation
tween.resume();         // Resume from pause
tween.reverse();        // Play in reverse
tween.restart();        // Restart from beginning

// Chaining controls
tween.play().delay(1);  // Play after 1 second delay

interface Animation {
  /**
   * Get or set the current time position
   * @param value - Time to seek to (omit to get current time)
   * @param suppressEvents - Whether to suppress events during seek
   * @returns Current time or Animation instance
   */
  time(value?: number, suppressEvents?: boolean): number | Animation;
  
  /**
   * Get or set total time including delays and repeats
   * @param value - Total time to set (omit to get current)
   * @param suppressEvents - Whether to suppress events during seek
   * @returns Current total time or Animation instance
   */
  totalTime(value?: number, suppressEvents?: boolean): number | Animation;
  
  /**
   * Seek to a specific time without affecting playback state
   * @param time - Time position to seek to
   * @param suppressEvents - Whether to suppress events during seek
   * @returns Animation instance for chaining
   */
  seek(time: number, suppressEvents?: boolean): Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2 });

// Time control
console.log(tween.time());     // Get current time
tween.time(1);                 // Seek to 1 second
tween.seek(0.5);              // Seek to 0.5 seconds

// Jump to end without triggering events
tween.seek(tween.duration(), true);

interface Animation {
  /**
   * Get or set animation progress (0-1)
   * @param value - Progress value between 0 and 1
   * @param suppressEvents - Whether to suppress events during change
   * @returns Current progress or Animation instance
   */
  progress(value?: number, suppressEvents?: boolean): number | Animation;
  
  /**
   * Get or set total progress including repeats (0-1)
   * @param value - Total progress value between 0 and 1
   * @param suppressEvents - Whether to suppress events during change
   * @returns Current total progress or Animation instance
   */
  totalProgress(value?: number, suppressEvents?: boolean): number | Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2 });

// Progress control
console.log(tween.progress());  // Get current progress (0-1)
tween.progress(0);             // Jump to start
tween.progress(0.5);           // Jump to middle
tween.progress(1);             // Jump to end

// Animate progress smoothly
gsap.to(tween, { progress: 1, duration: 3 });

interface Animation {
  /**
   * Get or set the animation duration
   * @param value - Duration in seconds (omit to get current)
   * @returns Current duration or Animation instance
   */
  duration(value?: number): number | Animation;
  
  /**
   * Get total duration including repeats and delays
   * @returns Total duration in seconds
   */
  totalDuration(): number;
  
  /**
   * Get the time when animation ends
   * @param includeRepeats - Whether to include repeat time
   * @returns End time in seconds
   */
  endTime(includeRepeats?: boolean): number;
  
  /**
   * Get the time when animation starts (including delay)
   * @returns Start time in seconds
   */
  startTime(): number;
}

const tween = gsap.to(".box", { x: 100, duration: 2, repeat: 2, delay: 1 });

console.log(tween.duration());      // 2 (base duration)
console.log(tween.totalDuration()); // 7 (2 + 2*2 + 1 delay)
console.log(tween.startTime());     // 1 (delay)
console.log(tween.endTime());       // 8 (start + total duration)

// Change duration dynamically
tween.duration(3); // Slow down the animation

interface Animation {
  /**
   * Check if animation is currently paused
   * @param value - Set paused state (omit to get current)
   * @returns Current paused state or Animation instance
   */
  paused(value?: boolean): boolean | Animation;
  
  /**
   * Check if animation is currently reversed
   * @param value - Set reversed state (omit to get current)
   * @returns Current reversed state or Animation instance
   */
  reversed(value?: boolean): boolean | Animation;
  
  /**
   * Check if animation is currently active/running
   * @returns True if animation is active
   */
  isActive(): boolean;
  
  /**
   * Get current iteration number (for repeating animations)
   * @param value - Set iteration number (omit to get current)
   * @returns Current iteration or Animation instance
   */
  iteration(value?: number): number | Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2, repeat: 3 });

// Check state
if (tween.isActive()) {
  console.log("Animation is running");
}

if (tween.paused()) {
  tween.resume();
}

// Control state
tween.paused(true);    // Pause
tween.reversed(true);  // Set to reversed

console.log(tween.iteration()); // Current repeat iteration

interface Animation {
  /**
   * Get or set the animation time scale (playback speed)
   * @param value - Speed multiplier (1 = normal, 2 = double speed, 0.5 = half speed)
   * @returns Current time scale or Animation instance
   */
  timeScale(value?: number): number | Animation;
  
  /**
   * Get or set the animation delay
   * @param value - Delay in seconds (omit to get current)
   * @returns Current delay or Animation instance
   */
  delay(value?: number): number | Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2 });

// Speed control
tween.timeScale(2);     // Double speed
tween.timeScale(0.5);   // Half speed
tween.timeScale(-1);    // Reverse at normal speed

// Delay control
tween.delay(1);         // Add 1 second delay
console.log(tween.delay()); // Get current delay

interface Animation {
  /**
   * Get or set the number of repeats
   * @param value - Number of repeats (-1 for infinite)
   * @returns Current repeat count or Animation instance
   */
  repeat(value?: number): number | Animation;
  
  /**
   * Get or set delay between repeats
   * @param value - Delay between repeats in seconds
   * @returns Current repeat delay or Animation instance
   */
  repeatDelay(value?: number): number | Animation;
  
  /**
   * Get or set yoyo behavior (reverse on alternate repeats)
   * @param value - Enable/disable yoyo behavior
   * @returns Current yoyo state or Animation instance
   */
  yoyo(value?: boolean): boolean | Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 1 });

// Repeat configuration
tween.repeat(3);        // Repeat 3 times (4 total plays)
tween.repeat(-1);       // Infinite repeats
tween.repeatDelay(0.5); // 0.5 second delay between repeats
tween.yoyo(true);       // Reverse direction on alternate repeats

// Check current settings
console.log(`Repeats: ${tween.repeat()}`);
console.log(`Yoyo: ${tween.yoyo()}`);

interface Animation {
  /**
   * Set or get event callback functions
   * @param type - Callback type
   * @param callback - Function to call (null to remove)
   * @param params - Parameters to pass to callback
   * @param scope - 'this' context for callback
   * @returns Current callback or Animation instance
   */
  eventCallback(
    type: "onStart" | "onUpdate" | "onComplete" | "onRepeat" | "onReverseComplete",
    callback?: Function | null,
    params?: any[],
    scope?: object
  ): Function | Animation;
  
  /**
   * Add a promise-like then method for chaining
   * @param callback - Function to call when animation completes
   * @returns Animation instance for chaining
   */
  then(callback: Function): Animation;
}

const tween = gsap.to(".box", { x: 100, duration: 2 });

// Set callbacks
tween.eventCallback("onStart", () => console.log("Started"));
tween.eventCallback("onUpdate", (progress) => console.log(`Progress: ${progress}`), [tween.progress()]);
tween.eventCallback("onComplete", () => console.log("Completed"));

// Promise-like chaining
tween.then(() => {
  console.log("Animation finished");
  // Start next animation
  return gsap.to(".box", { y: 100, duration: 1 });
}).then(() => {
  console.log("Second animation finished");
});

// Remove callback
tween.eventCallback("onUpdate", null);

interface Animation {
  /**
   * Kill (destroy) the animation and remove from timelines
   * @param vars - Specific properties to kill, or undefined for all
   * @param target - Specific target to kill (for multi-target animations)
   * @returns Animation instance
   */
  kill(vars?: object, target?: object): Animation;
  
  /**
   * Reset animation to initial state (before any rendering)
   * @returns Animation instance for chaining
   */
  invalidate(): Animation;
  
  /**
   * Revert animation to pre-animation state
   * @param config - Revert configuration options
   * @returns Animation instance
   */
  revert(config?: { kill?: boolean }): Animation;
}

const tween = gsap.to(".box", { x: 100, y: 100, duration: 2 });

// Selective killing
tween.kill({ x: true }); // Kill only x animation, y continues

// Complete kill
tween.kill(); // Kill entire animation

// Reset to initial state
tween.invalidate(); // Clear all recorded start/end values

// Revert changes
tween.revert(); // Return elements to pre-animation state