@ue-too/animate 0.9.5 → 0.11.0

package/composite-animation.d.ts

@@ -1,5 +1,27 @@
 import { AnimatableAttributeHelper, Keyframe } from "./animatable-attribute";
+/**
+ * Linear easing function (no easing).
+ *
+ * @param percentage - Animation progress (0.0 to 1.0)
+ * @returns Same as input (linear progression)
+ *
+ * @category Easing
+ */
 export declare const linear: (percentage: number) => number;
+/**
+ * Core interface for all animators in the animation system.
+ *
+ * @remarks
+ * The Animator interface defines the contract for both individual animations ({@link Animation})
+ * and composite animations ({@link CompositeAnimation}). All animators support:
+ * - Lifecycle control (start, stop, pause, resume)
+ * - Duration management with delays and drag time
+ * - Looping with optional max loop count
+ * - Parent-child relationships for composition
+ * - Event callbacks for start and end
+ *
+ * @category Core
+ */
 export interface Animator {
     loops: boolean;
     duration: number;
@@ -24,12 +46,63 @@ export interface Animator {
     maxLoopCount: number | undefined;
     playing: boolean;
 }
+/**
+ * Function type for unsubscribing from animation events.
+ *
+ * @category Core
+ */
 export type UnSubscribe = () => void;
+/**
+ * Interface for containers that hold and manage child animators.
+ *
+ * @remarks
+ * Implemented by {@link CompositeAnimation} to manage hierarchical animation structures.
+ * Handles duration updates and prevents cyclic dependencies.
+ *
+ * @category Core
+ */
 export interface AnimatorContainer {
     updateDuration(): void;
     checkCyclicChildren(): boolean;
     containsAnimation(animationInInterest: Animator): boolean;
 }
+/**
+ * Container for sequencing and composing multiple animations.
+ *
+ * @remarks
+ * CompositeAnimation allows you to orchestrate complex animation sequences by:
+ * - **Sequencing**: Add animations to play one after another
+ * - **Overlapping**: Start animations before previous ones complete
+ * - **Synchronizing**: Play multiple animations simultaneously
+ * - **Nesting**: Compose animations contain other composite animations
+ *
+ * ## Key Features
+ *
+ * - Add animations at specific time offsets
+ * - Position animations relative to other animations (`addAnimationAfter`, `addAnimationBefore`)
+ * - Automatic duration calculation based on child animations
+ * - Hierarchical composition for complex sequences
+ * - Prevent cyclic animation dependencies
+ *
+ * @example
+ * Basic sequence
+ * ```typescript
+ * const sequence = new CompositeAnimation();
+ *
+ * // Add first animation at start (time 0)
+ * sequence.addAnimation('fadeIn', fadeAnimation, 0);
+ *
+ * // Add second animation after first completes
+ * sequence.addAnimationAfter('slideIn', slideAnimation, 'fadeIn');
+ *
+ * // Add third animation to overlap with second (100ms after second starts)
+ * sequence.addAnimationAdmist('scaleUp', scaleAnimation, 'slideIn', 100);
+ *
+ * sequence.start();
+ * ```
+ *
+ * @category Core
+ */
 export declare class CompositeAnimation implements Animator, AnimatorContainer {
     private animations;
     private localTime;
@@ -102,6 +175,54 @@ export declare class CompositeAnimation implements Animator, AnimatorContainer {
     get maxLoopCount(): number | undefined;
     set maxLoopCount(maxLoopCount: number | undefined);
 }
+/**
+ * Keyframe-based animation for a single value.
+ *
+ * @remarks
+ * The Animation class interpolates a value through a series of keyframes over time.
+ * It handles:
+ * - Keyframe interpolation with binary search for efficiency
+ * - Easing functions for smooth motion curves
+ * - Reverse playback
+ * - Looping with optional max loop count
+ * - Delays before start and drag time after completion
+ * - Lifecycle callbacks
+ *
+ * ## How It Works
+ *
+ * 1. Define keyframes at percentages (0.0 to 1.0) along the timeline
+ * 2. Provide a callback to apply the animated value
+ * 3. Provide an interpolation helper for the value type
+ * 4. Call `animate(deltaTime)` each frame to progress the animation
+ *
+ * @typeParam T - The type of value being animated
+ *
+ * @example
+ * Animating a number with easing
+ * ```typescript
+ * let opacity = 0;
+ *
+ * const fadeIn = new Animation(
+ *   [
+ *     { percentage: 0, value: 0 },
+ *     { percentage: 1, value: 1, easingFn: (t) => t * t } // Ease-in
+ *   ],
+ *   (value) => { opacity = value; },
+ *   numberHelperFunctions,
+ *   1000 // 1 second duration
+ * );
+ *
+ * fadeIn.start();
+ *
+ * // In animation loop
+ * function loop(deltaTime: number) {
+ *   fadeIn.animate(deltaTime);
+ *   element.style.opacity = opacity;
+ * }
+ * ```
+ *
+ * @category Core
+ */
 export declare class Animation<T> implements Animator {
     private localTime;
     private _duration;

package/index.d.ts

@@ -1,2 +1,102 @@
+/**
+ * @packageDocumentation
+ * Keyframe-based animation library for TypeScript.
+ *
+ * @remarks
+ * The `@ue-too/animate` package provides a flexible, composable animation system based on keyframes.
+ * It supports animating various types (numbers, points, colors, strings) with easing functions,
+ * delays, and complex animation sequencing through composition.
+ *
+ * ## Core Concepts
+ *
+ * - **Keyframes**: Define animation values at specific points in time (0.0 to 1.0)
+ * - **Animation**: Interpolates between keyframes to animate a single value
+ * - **Composite Animation**: Sequences and overlaps multiple animations
+ * - **Animation Helpers**: Type-specific interpolation logic (lerp functions)
+ * - **Easing Functions**: Transform animation timing curves
+ *
+ * ## Key Features
+ *
+ * - **Type-Safe Interpolation**: Built-in helpers for numbers, points, colors, strings
+ * - **Composite Animations**: Sequence, overlap, and synchronize multiple animations
+ * - **Lifecycle Hooks**: `onStart`, `onEnd`, `setUp`, `tearDown` callbacks
+ * - **Looping**: Support for finite and infinite loops
+ * - **Delays and Drag**: Add delays before animation start and drag time after completion
+ * - **Reverse Playback**: Animations can play in reverse
+ * - **Hierarchical Composition**: Nest composite animations to create complex sequences
+ *
+ * ## Main Exports
+ *
+ * - {@link Animation}: Single keyframe animation for a value
+ * - {@link CompositeAnimation}: Container for sequencing multiple animations
+ * - {@link Keyframe}: Type defining a value at a percentage point in time
+ * - {@link AnimatableAttributeHelper}: Interface for type-specific interpolation
+ * - Helper functions: {@link pointHelperFunctions}, {@link numberHelperFunctions}, {@link rgbHelperFunctions}
+ *
+ * @example
+ * Basic number animation
+ * ```typescript
+ * import { Animation, numberHelperFunctions } from '@ue-too/animate';
+ *
+ * let currentValue = 0;
+ *
+ * const animation = new Animation(
+ *   [
+ *     { percentage: 0, value: 0 },
+ *     { percentage: 0.5, value: 50 },
+ *     { percentage: 1, value: 100 }
+ *   ],
+ *   (value) => { currentValue = value; }, // Apply function
+ *   numberHelperFunctions,
+ *   1000 // Duration in ms
+ * );
+ *
+ * animation.start();
+ *
+ * // In your animation loop
+ * function animate(deltaTime: number) {
+ *   animation.animate(deltaTime);
+ *   console.log('Current value:', currentValue);
+ *   requestAnimationFrame(animate);
+ * }
+ * ```
+ *
+ * @example
+ * Composite animation sequence
+ * ```typescript
+ * import { Animation, CompositeAnimation, numberHelperFunctions } from '@ue-too/animate';
+ *
+ * let x = 0, y = 0;
+ *
+ * const moveRight = new Animation(
+ *   [{ percentage: 0, value: 0 }, { percentage: 1, value: 100 }],
+ *   (value) => { x = value; },
+ *   numberHelperFunctions,
+ *   500
+ * );
+ *
+ * const moveDown = new Animation(
+ *   [{ percentage: 0, value: 0 }, { percentage: 1, value: 100 }],
+ *   (value) => { y = value; },
+ *   numberHelperFunctions,
+ *   500
+ * );
+ *
+ * const sequence = new CompositeAnimation();
+ * sequence.addAnimation('moveRight', moveRight, 0);
+ * sequence.addAnimationAfter('moveDown', moveDown, 'moveRight');
+ *
+ * sequence.start();
+ *
+ * // Animate in your loop
+ * function loop(deltaTime: number) {
+ *   sequence.animate(deltaTime);
+ *   requestAnimationFrame(loop);
+ * }
+ * ```
+ *
+ * @see {@link Animation} for single value animations
+ * @see {@link CompositeAnimation} for animation sequencing
+ */
 export * from "./animatable-attribute";
 export * from "./composite-animation";