Animations and Effects

/**
 * Animate CSS properties over time
 * @param properties - Object of CSS properties to animate
 * @param duration - Animation duration in milliseconds or preset ('slow', 'fast')
 * @param easing - Easing function name ('linear', 'swing')
 * @param complete - Callback function when animation completes
 * @returns jQuery object for chaining
 */
animate(properties: object): jQuery;
animate(properties: object, duration: number | string): jQuery;
animate(properties: object, duration: number | string, easing: string): jQuery;
animate(properties: object, duration: number | string, complete: function): jQuery;
animate(properties: object, duration: number | string, easing: string, complete: function): jQuery;
animate(properties: object, options: AnimationOptions): jQuery;

interface AnimationOptions {
  duration?: number | string;
  easing?: string;
  complete?: function;
  step?: function;
  progress?: function;
  done?: function;
  fail?: function;
  always?: function;
  queue?: boolean | string;
  specialEasing?: object;
}

// Basic property animation
$('#box').animate({
  width: '200px',
  height: '200px',
  opacity: 0.5
}, 1000);

// Multiple properties with easing
$('.item').animate({
  left: '100px',
  top: '50px',
  opacity: 1
}, 500, 'swing');

// With completion callback
$('#element').animate({
  width: 'toggle',
  height: 'toggle'
}, {
  duration: 1000,
  complete: function() {
    alert('Animation complete!');
  }
});

// Advanced options
$('.box').animate({
  width: '+=50px',      // Relative values
  height: '-=20px',
  'font-size': '20px',  // CSS properties
  rotate: '45deg'       // Custom properties (with plugins)
}, {
  duration: 2000,
  easing: 'linear',
  step: function(now, fx) {
    // Called for each animation step
    console.log(fx.prop + ': ' + now);
  },
  progress: function(animation, progress, remainingMs) {
    // Called on each animation frame
    console.log('Progress: ' + Math.round(progress * 100) + '%');
  },
  done: function() {
    console.log('Animation succeeded');
  },
  fail: function() {
    console.log('Animation was stopped');
  },
  always: function() {
    console.log('Animation finished (success or failure)');
  }
});

/**
 * Stop running animations
 * @param clearQueue - Clear remaining queued animations
 * @param jumpToEnd - Jump to final animation state
 * @returns jQuery object for chaining
 */
stop(): jQuery;
stop(clearQueue: boolean): jQuery;
stop(queue: string): jQuery;
stop(clearQueue: boolean, jumpToEnd: boolean): jQuery;
stop(queue: string, clearQueue: boolean, jumpToEnd: boolean): jQuery;

/**
 * Complete all queued animations immediately
 * @param queue - Queue name to finish (default is 'fx')
 * @returns jQuery object for chaining
 */
finish(queue?: string): jQuery;

// Stop current animation
$('#element').stop();

// Stop and clear queue
$('#element').stop(true);

// Stop and jump to end
$('#element').stop(true, true);

// Stop specific queue
$('#element').stop('myQueue');

// Finish all animations
$('#element').finish();

// Interactive control
$('#startBtn').click(function() {
  $('#box').animate({ left: '200px' }, 3000);
});

$('#stopBtn').click(function() {
  $('#box').stop();
});

$('#finishBtn').click(function() {
  $('#box').finish();
});

/**
 * Show hidden elements with optional animation
 * @param duration - Animation duration
 * @param easing - Easing function
 * @param complete - Completion callback
 * @returns jQuery object for chaining
 */
show(): jQuery;
show(duration: number | string): jQuery;
show(duration: number | string, complete: function): jQuery;
show(duration: number | string, easing: string, complete: function): jQuery;
show(options: AnimationOptions): jQuery;

/**
 * Hide visible elements with optional animation
 */
hide(): jQuery;
hide(duration: number | string): jQuery;
hide(duration: number | string, complete: function): jQuery;
hide(duration: number | string, easing: string, complete: function): jQuery;
hide(options: AnimationOptions): jQuery;

/**
 * Toggle element visibility with optional animation
 */
toggle(): jQuery;
toggle(duration: number | string): jQuery;
toggle(duration: number | string, complete: function): jQuery;
toggle(duration: number | string, easing: string, complete: function): jQuery;
toggle(options: AnimationOptions): jQuery;
toggle(state: boolean): jQuery;

// Instant show/hide
$('#element').show();
$('#element').hide();

// Animated show/hide
$('#element').show(500);
$('#element').hide('slow');

// With callback
$('#element').show(1000, function() {
  console.log('Element is now visible');
});

// Toggle visibility
$('#element').toggle();
$('#element').toggle(500);

// Force state
$('#element').toggle(true);  // Always show
$('#element').toggle(false); // Always hide

/**
 * Fade elements in by animating opacity to 1
 */
fadeIn(): jQuery;
fadeIn(duration: number | string): jQuery;
fadeIn(duration: number | string, complete: function): jQuery;
fadeIn(duration: number | string, easing: string, complete: function): jQuery;
fadeIn(options: AnimationOptions): jQuery;

/**
 * Fade elements out by animating opacity to 0
 */
fadeOut(): jQuery;
fadeOut(duration: number | string): jQuery;
fadeOut(duration: number | string, complete: function): jQuery;
fadeOut(duration: number | string, easing: string, complete: function): jQuery;
fadeOut(options: AnimationOptions): jQuery;

/**
 * Animate opacity to specific value
 * @param to - Target opacity value (0-1)
 * @param duration - Animation duration
 * @param easing - Easing function
 * @param complete - Completion callback
 */
fadeTo(to: number): jQuery;
fadeTo(duration: number | string, to: number): jQuery;
fadeTo(duration: number | string, to: number, complete: function): jQuery;
fadeTo(duration: number | string, to: number, easing: string, complete: function): jQuery;

/**
 * Toggle element visibility using fade effect
 */
fadeToggle(): jQuery;
fadeToggle(duration: number | string): jQuery;
fadeToggle(duration: number | string, complete: function): jQuery;
fadeToggle(duration: number | string, easing: string, complete: function): jQuery;
fadeToggle(options: AnimationOptions): jQuery;

// Basic fading
$('#message').fadeIn();
$('#notification').fadeOut(2000);

// Fade to specific opacity
$('#overlay').fadeTo(500, 0.7);
$('#background').fadeTo('slow', 0.3);

// Fade toggle
$('#panel').fadeToggle();

// Chained fading effects
$('#element')
  .fadeOut(300)
  .delay(500)
  .fadeIn(300);

// With callbacks
$('#old-content').fadeOut(500, function() {
  $('#new-content').fadeIn(500);
});

/**
 * Show elements by sliding down (animating height)
 */
slideDown(): jQuery;
slideDown(duration: number | string): jQuery;
slideDown(duration: number | string, complete: function): jQuery;
slideDown(duration: number | string, easing: string, complete: function): jQuery;
slideDown(options: AnimationOptions): jQuery;

/**
 * Hide elements by sliding up (animating height to 0)
 */
slideUp(): jQuery;
slideUp(duration: number | string): jQuery;
slideUp(duration: number | string, complete: function): jQuery;
slideUp(duration: number | string, easing: string, complete: function): jQuery;
slideUp(options: AnimationOptions): jQuery;

/**
 * Toggle element visibility using slide effect
 */
slideToggle(): jQuery;
slideToggle(duration: number | string): jQuery;
slideToggle(duration: number | string, complete: function): jQuery;
slideToggle(duration: number | string, easing: string, complete: function): jQuery;
slideToggle(options: AnimationOptions): jQuery;

// Basic sliding
$('#menu').slideDown();
$('#content').slideUp(1000);

// Toggle sliding
$('#accordion-panel').slideToggle();

// Accordion pattern
$('.accordion-header').click(function() {
  $(this).next('.accordion-content').slideToggle();
  $(this).parent().siblings().find('.accordion-content').slideUp();
});

// Smooth reveal
$('#details').slideDown(300, function() {
  $(this).find('input:first').focus();
});

/**
 * Add delay between animations
 * @param duration - Delay duration in milliseconds
 * @param queueName - Queue name (default 'fx')
 * @returns jQuery object for chaining
 */
delay(duration: number): jQuery;
delay(duration: number, queueName: string): jQuery;

/**
 * Add custom function to animation queue
 * @param queueName - Queue name
 * @param callback - Function to add to queue
 * @returns jQuery object for chaining
 */
queue(): Array<function>;
queue(queueName: string): Array<function>;
queue(callback: function): jQuery;
queue(queueName: string, callback: function): jQuery;
queue(queueName: string, newQueue: Array<function>): jQuery;

/**
 * Execute next function in queue
 * @param queueName - Queue name (default 'fx')
 * @returns jQuery object for chaining
 */
dequeue(): jQuery;
dequeue(queueName: string): jQuery;

/**
 * Clear animation queue
 * @param queueName - Queue name (default 'fx')
 * @returns jQuery object for chaining
 */
clearQueue(): jQuery;
clearQueue(queueName: string): jQuery;

/**
 * Get promise that resolves when animations complete
 * @param type - Queue type (default 'fx')
 * @param target - Optional target object
 * @returns Promise that resolves when queue is empty
 */
promise(): Promise<jQuery>;
promise(type: string): Promise<jQuery>;
promise(type: string, target: object): Promise<jQuery>;

// Animation sequence with delays
$('#element')
  .fadeIn(500)
  .delay(1000)
  .animate({ left: '100px' }, 500)
  .delay(500)
  .fadeOut(500);

// Custom queue functions
$('#element')
  .animate({ width: '200px' }, 500)
  .queue(function(next) {
    $(this).addClass('expanded');
    next(); // Must call next() to continue queue
  })
  .animate({ height: '200px' }, 500);

// Promise-based animation handling
$('#element')
  .fadeOut()
  .promise()
  .done(function() {
    console.log('Fade out complete');
    $(this).remove();
  });

// Multiple elements promise
$('.items')
  .animate({ opacity: 0 }, 1000)
  .promise()
  .done(function() {
    console.log('All items faded out');
  });

// Queue management
$('#element').queue('custom', function(next) {
  // Custom animation logic
  setTimeout(next, 1000);
});

$('#element').dequeue('custom'); // Start custom queue

/**
 * Create Animation object for advanced animation control
 * @param element - Target element
 * @param properties - Properties to animate
 * @param options - Animation options
 * @returns Animation object
 */
$.Animation(element: Element, properties: object, options: AnimationOptions): Animation;

/**
 * Normalize animation options
 * @param speed - Duration or options object
 * @param easing - Easing function name
 * @param fn - Completion callback
 * @returns Normalized options object
 */
$.speed(speed: number | string | object, easing?: string, fn?: function): object;

// Global animation settings
$.fx.off: boolean;        // Disable all animations globally
$.fx.interval: number;    // Animation frame interval (default 13ms)

// Predefined speeds
$.fx.speeds = {
  slow: 600,
  fast: 200,
  _default: 400
};

// Animation system methods
$.fx.timer(timer: function): void;  // Add animation timer
$.fx.tick(): void;                  // Process animation frame
$.fx.start(): void;                 // Start animation loop
$.fx.stop(): void;                  // Stop animation loop

// Disable all animations globally
$.fx.off = true;
$('#element').fadeIn(); // Happens instantly

// Custom animation speeds
$.fx.speeds.verySlow = 2000;
$('#element').fadeIn('verySlow');

// Custom animation timer
$.fx.timer(function() {
  if (customAnimationCondition) {
    processCustomAnimation();
  }
});

// Animation tweeners for custom properties
$.Animation.tweener(props: string, callback: function): void;

// Animation prefilters
$.Animation.prefilter(callback: function, prepend?: boolean): void;

// Step hooks for all animations
$.fx.step[property: string] = function(fx: object): void;

// Custom property tweener
$.Animation.tweener('rotate', function(fx) {
  fx.elem.style.transform = 'rotate(' + fx.now + 'deg)';
});

// Now you can animate rotation
$('#element').animate({ rotate: 180 }, 1000);

// Animation prefilter
$.Animation.prefilter(function(element, properties, options) {
  // Modify properties or options before animation starts
  if (properties.customProp) {
    properties.left = properties.customProp;
    delete properties.customProp;
  }
});

// Step hook for monitoring all width animations
$.fx.step.width = function(fx) {
  // Custom logic for width animations
  console.log('Width animating to:', fx.now);
};

// Efficient animation patterns
$('.items').each(function(index) {
  $(this).delay(index * 100).fadeIn(300);
});

// Batch DOM changes
$('#element')
  .animate({
    left: '100px',
    top: '50px',
    width: '200px',
    height: '150px'
  }, 1000); // Single animation is more efficient

// Use CSS transforms when possible (with plugins)
$('#element').animate({
  translateX: '100px',
  translateY: '50px',
  scale: 1.2
}, 500);

// Memory cleanup
$('#element')
  .animate({ opacity: 0 }, 500)
  .promise()
  .done(function() {
    $(this).remove(); // Clean up DOM
  });