houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
204 lines (203 loc) • 7.36 kB
TypeScript
/**
* @module AnimationUtils
* @description A collection of utility functions for handling animations in web applications.
* Provides methods for CSS transitions, requestAnimationFrame animations, keyframe animations,
* and spring physics-based animations.
*
* @example
* ```typescript
* import { AnimationUtils } from 'houser-js-utils';
*
* // Animate an element using CSS transitions
* const element = document.querySelector('.box');
* await AnimationUtils.animate(element, {
* transform: 'translateX(100px)',
* opacity: '0.5'
* });
*
* // Create a spring animation
* await AnimationUtils.createSpringAnimation(element, {
* transform: 'translateY(200px)'
* }, {
* stiffness: 170,
* damping: 26
* });
* ```
*/
/**
* Spring animation configuration options
*/
interface SpringOptions {
/** Spring stiffness coefficient (default: 170) */
stiffness?: number;
/** Damping coefficient (default: 26) */
damping?: number;
/** Mass of the animated object (default: 1) */
mass?: number;
/** Maximum duration of the animation in milliseconds (default: 300) */
duration?: number;
}
export declare const AnimationUtils: {
/**
* Animates an element using CSS transitions
* @param element - The HTML element to animate
* @param properties - CSS properties to animate
* @param duration - Animation duration in milliseconds (default: 300)
* @param easing - CSS easing function (default: 'ease')
* @returns Promise that resolves when animation completes
* @example
* ```typescript
* const element = document.querySelector('.box');
* await AnimationUtils.animate(element, {
* transform: 'translateX(100px)',
* opacity: '0.5'
* }, 500, 'ease-in-out');
* ```
*/
animate(element: HTMLElement, properties: Partial<CSSStyleDeclaration>, duration?: number, easing?: string): Promise<void>;
/**
* Animates an element using requestAnimationFrame for smoother animations
* @param element - The HTML element to animate
* @param properties - CSS properties to animate
* @param duration - Animation duration in milliseconds (default: 300)
* @param easing - Custom easing function (default: linear)
* @returns Promise that resolves when animation completes
* @example
* ```typescript
* const element = document.querySelector('.box');
* await AnimationUtils.animateWithRAF(element, {
* transform: 'translateX(100px)'
* }, 500, (t) => t * t); // Quadratic easing
* ```
*/
animateWithRAF(element: HTMLElement, properties: Partial<CSSStyleDeclaration>, duration?: number, easing?: (t: number) => number): Promise<void>;
/**
* Creates a keyframe animation using the Web Animations API
* @param element - The HTML element to animate
* @param keyframes - Array of keyframe objects
* @param options - Animation options
* @returns Animation object
* @example
* ```typescript
* const element = document.querySelector('.box');
* const animation = AnimationUtils.createKeyframeAnimation(element, [
* { transform: 'translateX(0)', opacity: 1 },
* { transform: 'translateX(100px)', opacity: 0.5 }
* ], {
* duration: 500,
* easing: 'ease-in-out'
* });
* ```
*/
createKeyframeAnimation(element: HTMLElement, keyframes: Keyframe[], options?: KeyframeAnimationOptions): Animation;
/**
* Creates a spring physics-based animation
* @param element - The HTML element to animate
* @param properties - CSS properties to animate
* @param options - Spring animation configuration
* @returns Promise that resolves when animation completes
* @example
* ```typescript
* const element = document.querySelector('.box');
* await AnimationUtils.createSpringAnimation(element, {
* transform: 'translateY(200px)'
* }, {
* stiffness: 170,
* damping: 26,
* mass: 1
* });
* ```
*/
createSpringAnimation(element: HTMLElement, properties: Partial<CSSStyleDeclaration>, options?: SpringOptions): Promise<void>;
/**
* Gets all animations currently running on an element
* @param element - The HTML element to check
* @returns Array of Animation objects
* @example
* ```typescript
* const element = document.querySelector('.box');
* const animations = AnimationUtils.getAnimations(element);
* ```
*/
getAnimations(element: HTMLElement): Animation[];
/**
* Gets the current animation state of an element
* @param element - The HTML element to check
* @returns Current animation state: 'idle', 'running', or 'paused'
* @example
* ```typescript
* const element = document.querySelector('.box');
* const state = AnimationUtils.getAnimationState(element);
* if (state === 'running') {
* console.log('Element is currently animating');
* }
* ```
*/
getAnimationState(element: HTMLElement): "idle" | "running" | "paused";
/**
* Checks if an element has any active animations
* @param element - The HTML element to check
* @returns True if the element has any animations
* @example
* ```typescript
* const element = document.querySelector('.box');
* if (AnimationUtils.hasAnimations(element)) {
* console.log('Element has active animations');
* }
* ```
*/
hasAnimations(element: HTMLElement): boolean;
/**
* Pauses all animations on an element
* @param element - The HTML element to pause animations on
* @example
* ```typescript
* const element = document.querySelector('.box');
* AnimationUtils.pauseAnimations(element);
* ```
*/
pauseAnimations(element: HTMLElement): void;
/**
* Resumes all paused animations on an element
* @param element - The HTML element to resume animations on
* @example
* ```typescript
* const element = document.querySelector('.box');
* AnimationUtils.resumeAnimations(element);
* ```
*/
resumeAnimations(element: HTMLElement): void;
/**
* Reverses the direction of all animations on an element
* @param element - The HTML element to reverse animations on
* @example
* ```typescript
* const element = document.querySelector('.box');
* AnimationUtils.reverseAnimations(element);
* ```
*/
reverseAnimations(element: HTMLElement): void;
/**
* Stops and removes all animations from an element
* @param element - The HTML element to stop animations on
* @example
* ```typescript
* const element = document.querySelector('.box');
* AnimationUtils.stopAnimations(element);
* ```
*/
stopAnimations(element: HTMLElement): void;
/**
* Waits for all animations on an element to complete
* @param element - The HTML element to wait for
* @returns Promise that resolves when all animations complete
* @example
* ```typescript
* const element = document.querySelector('.box');
* await AnimationUtils.waitForAnimations(element);
* console.log('All animations completed');
* ```
*/
waitForAnimations(element: HTMLElement): Promise<void>;
};
export {};