Core Animation

/**
 * Animates properties to specified values
 * @param targets - Elements, objects, or selectors to animate
 * @param vars - Animation properties and configuration
 * @returns Tween instance for further control
 */
gsap.to(targets: gsap.TweenTarget, vars: gsap.TweenVars): gsap.core.Tween;

// Basic property animation
gsap.to(".box", { duration: 2, x: 100, y: 50, rotation: 360 });

// CSS properties
gsap.to("#element", { 
  duration: 1, 
  backgroundColor: "red",
  borderRadius: "50%",
  scale: 1.5
});

// Multiple targets
gsap.to([".box1", ".box2", ".box3"], { 
  duration: 1, 
  y: 100, 
  stagger: 0.2 // animate each 0.2s apart
});

/**
 * Animates properties from specified values to current values
 * @param targets - Elements, objects, or selectors to animate  
 * @param vars - Starting values and animation configuration
 * @returns Tween instance for further control
 */
gsap.from(targets: gsap.TweenTarget, vars: gsap.TweenVars): gsap.core.Tween;

// Animate from invisible to visible
gsap.from(".element", { duration: 1, opacity: 0, y: -50 });

// Scale up from zero
gsap.from(".logo", { duration: 2, scale: 0, rotation: -360 });

/**
 * Animates properties from one set of values to another
 * @param targets - Elements, objects, or selectors to animate
 * @param fromVars - Starting values and configuration
 * @param toVars - Ending values and animation configuration
 * @returns Tween instance for further control
 */
gsap.fromTo(
  targets: gsap.TweenTarget, 
  fromVars: gsap.TweenVars, 
  toVars: gsap.TweenVars
): gsap.core.Tween;

// Explicit from and to values
gsap.fromTo(".box", 
  { x: 0, opacity: 0 },
  { x: 100, opacity: 1, duration: 2 }
);

// Color transitions
gsap.fromTo(".element",
  { backgroundColor: "blue" },
  { backgroundColor: "red", duration: 1 }
);

/**
 * Immediately sets properties without animation
 * @param targets - Elements, objects, or selectors to modify
 * @param vars - Properties to set
 * @returns Tween instance (with zero duration)
 */
gsap.set(targets: gsap.TweenTarget, vars: gsap.TweenVars): gsap.core.Tween;

// Initial setup
gsap.set(".modal", { opacity: 0, scale: 0.8, display: "block" });

// Reset elements
gsap.set([".box1", ".box2"], { x: 0, y: 0, rotation: 0 });

/**
 * Executes a function after a delay
 * @param delay - Delay in seconds before execution
 * @param callback - Function to execute
 * @param params - Parameters to pass to the callback
 * @returns Tween instance for the delayed call
 */
gsap.delayedCall(
  delay: number, 
  callback: Function, 
  params?: any[]
): gsap.core.Tween;

// Simple delayed execution
gsap.delayedCall(2, () => console.log("Hello after 2 seconds"));

// With parameters
gsap.delayedCall(1.5, showMessage, ["Animation complete!"]);

function showMessage(text) {
  alert(text);
}

interface TweenVars {
  // Timing
  duration?: number;           // Animation duration in seconds
  delay?: number;             // Delay before animation starts
  
  // Easing
  ease?: string | EaseFunction; // Easing function
  
  // Repetition
  repeat?: number;            // Number of repeats (-1 for infinite)
  repeatDelay?: number;       // Delay between repeats
  yoyo?: boolean;            // Whether to alternate direction on repeat
  
  // Control
  paused?: boolean;          // Start paused
  overwrite?: boolean | "auto"; // How to handle conflicting animations
  immediateRender?: boolean; // Render immediately or wait for start
  
  // Callbacks
  onStart?: Function;        // Called when animation starts
  onUpdate?: Function;       // Called on each frame update
  onComplete?: Function;     // Called when animation completes
  onRepeat?: Function;       // Called on each repeat
  onReverseComplete?: Function; // Called when reverse completes
  
  // Callback parameters
  onStartParams?: any[];
  onUpdateParams?: any[];
  onCompleteParams?: any[];
  callbackScope?: object;    // 'this' context for callbacks
  
  // Data
  data?: any;               // Custom data storage
  id?: string | number;     // Unique identifier
}

interface StaggerVars {
  amount?: number;          // Total time to distribute across all targets
  each?: number;           // Time between each target's animation start
  from?: "start" | "center" | "end" | "edges" | "random" | number;
  grid?: [number, number]; // For 2D grid layouts
  axis?: "x" | "y";       // Grid axis for distribution
  ease?: string | EaseFunction; // Easing for the stagger timing
}

// Sequential stagger
gsap.to(".item", { 
  duration: 1, 
  y: 100, 
  stagger: 0.2  // Each item starts 0.2s after the previous
});

// Advanced stagger configuration
gsap.to(".grid-item", {
  duration: 1,
  scale: 1.2,
  stagger: {
    amount: 2,      // Total 2 seconds distributed across all items
    from: "center", // Start from center item
    grid: [5, 5],   // 5x5 grid layout
    ease: "power2.out"
  }
});

interface SpecialProperties {
  // Shortcuts
  autoAlpha?: number;       // opacity + visibility combined
  alpha?: number;          // Alias for opacity
  
  // Transform shortcuts
  x?: number | string;     // translateX
  y?: number | string;     // translateY
  z?: number | string;     // translateZ
  
  // Percentage-based positioning
  xPercent?: number;       // Percentage of element's width
  yPercent?: number;       // Percentage of element's height
  
  // Transform origin
  transformOrigin?: string; // Transform origin point
  svgOrigin?: string;      // SVG-specific transform origin
}

// Different value for each target
gsap.to(".box", {
  duration: 2,
  x: (index, target) => index * 100, // Each box moves further
  rotation: () => Math.random() * 360 // Random rotation
});

gsap.to(".element", {
  duration: 3,
  keyframes: [
    { x: 100, duration: 1 },
    { y: 100, duration: 1 },
    { x: 0, y: 0, duration: 1 }
  ]
});

// Move 50px right from current position
gsap.to(".box", { duration: 1, x: "+=50" });

// Rotate 180 degrees from current rotation
gsap.to(".element", { duration: 2, rotation: "+=180" });