armas_basic/animation/

mod.rs

//! Animation utilities for smooth, physics-based motion.
//!
//! Provides timed animations with easing, spring physics, staggered
//! entrance effects, and looping support.

/// Easing functions for smooth animations
pub mod easing;
/// Interpolation trait for animating values
pub mod interpolate;
pub mod momentum;
pub mod staggered;
pub mod velocity_drag;

pub use easing::EasingFunction;
pub use interpolate::Interpolate;
pub use momentum::{
    ContinuousWithMomentum, MomentumBehavior, MomentumPosition, SnapToPageBoundaries,
};
pub use staggered::{AnimationSequence, LoopMode, LoopingAnimation, StaggeredAnimation};
pub use velocity_drag::{DoubleClickReset, DragMode, VelocityDrag, VelocityDragConfig};

/// Animation state
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AnimationState {
    /// Animation hasn't started yet
    NotStarted,
    /// Animation is currently running
    Running,
    /// Animation is paused
    Paused,
    /// Animation has completed
    Completed,
}

/// A generic animation that interpolates between two values over time
///
/// # Example
///
/// ```rust
/// use armas_basic::animation::{Animation, EasingFunction};
///
/// let mut anim = Animation::new(0.0_f32, 1.0, 0.3)
///     .easing(EasingFunction::EaseOut);
/// anim.start();
/// anim.update(0.15);
/// let value = anim.value(); // interpolated between 0.0 and 1.0
/// ```
#[derive(Debug, Clone)]
pub struct Animation<T: Interpolate> {
    /// Starting value
    pub start: T,
    /// Target value
    pub end: T,
    /// Duration of the animation in seconds
    pub duration: f32,
    /// Elapsed time in seconds
    pub elapsed: f32,
    /// Easing function to apply
    pub easing: EasingFunction,
    /// Current state of the animation
    pub state: AnimationState,
}

impl<T: Interpolate> Animation<T> {
    /// Create a new animation from start to end over duration
    pub const fn new(start: T, end: T, duration: f32) -> Self {
        Self {
            start,
            end,
            duration,
            elapsed: 0.0,
            easing: EasingFunction::EaseInOut,
            state: AnimationState::NotStarted,
        }
    }

    /// Set the easing function
    #[must_use]
    pub const fn easing(mut self, easing: EasingFunction) -> Self {
        self.easing = easing;
        self
    }

    /// Start the animation
    pub const fn start(&mut self) {
        self.state = AnimationState::Running;
        self.elapsed = 0.0;
    }

    /// Pause the animation
    pub fn pause(&mut self) {
        if self.state == AnimationState::Running {
            self.state = AnimationState::Paused;
        }
    }

    /// Resume the animation
    pub fn resume(&mut self) {
        if self.state == AnimationState::Paused {
            self.state = AnimationState::Running;
        }
    }

    /// Reset the animation to the beginning
    pub const fn reset(&mut self) {
        self.elapsed = 0.0;
        self.state = AnimationState::NotStarted;
    }

    /// Update the animation with delta time
    pub fn update(&mut self, dt: f32) {
        if self.state != AnimationState::Running {
            return;
        }

        self.elapsed += dt;
        if self.elapsed >= self.duration {
            self.elapsed = self.duration;
            self.state = AnimationState::Completed;
        }
    }

    /// Get the current value of the animation
    pub fn value(&self) -> T {
        let t = if self.duration <= 0.0 {
            1.0
        } else {
            (self.elapsed / self.duration).clamp(0.0, 1.0)
        };

        let eased_t = self.easing.apply(t);
        self.start.interpolate(&self.end, eased_t)
    }

    /// Get the normalized progress (0.0 to 1.0)
    pub fn progress(&self) -> f32 {
        if self.duration <= 0.0 {
            1.0
        } else {
            (self.elapsed / self.duration).clamp(0.0, 1.0)
        }
    }

    /// Check if the animation is complete
    pub fn is_complete(&self) -> bool {
        self.state == AnimationState::Completed
    }

    /// Check if the animation is running
    pub fn is_running(&self) -> bool {
        self.state == AnimationState::Running
    }
}

/// Spring-based animation for smooth, physics-based motion
///
/// This uses a damped spring physics model for natural-looking animations.
/// Unlike timed animations, springs don't have a fixed duration - they settle over time.
///
/// # Example
///
/// ```rust
/// use armas_basic::animation::SpringAnimation;
///
/// let mut spring = SpringAnimation::new(0.0, 1.0)
///     .params(200.0, 20.0);
/// spring.update(0.016); // one frame at 60fps
/// let current = spring.value;
/// ```
#[derive(Debug, Clone)]
pub struct SpringAnimation {
    /// Current value
    pub value: f32,
    /// Current velocity
    pub velocity: f32,
    /// Target value
    pub target: f32,
    /// Spring stiffness (higher = faster oscillation, typical: 100-300)
    pub stiffness: f32,
    /// Spring damping (higher = less oscillation, typical: 10-30)
    pub damping: f32,
}

impl SpringAnimation {
    /// Create a new spring animation
    #[must_use]
    pub const fn new(initial: f32, target: f32) -> Self {
        Self {
            value: initial,
            velocity: 0.0,
            target,
            stiffness: 200.0,
            damping: 20.0,
        }
    }

    /// Set spring parameters
    #[must_use]
    pub const fn params(mut self, stiffness: f32, damping: f32) -> Self {
        self.stiffness = stiffness;
        self.damping = damping;
        self
    }

    /// Update the spring simulation using semi-implicit Euler integration
    pub fn update(&mut self, dt: f32) {
        // Spring force: F = -k * (x - target)
        let spring_force = -self.stiffness * (self.value - self.target);

        // Damping force: F = -c * v
        let damping_force = -self.damping * self.velocity;

        // Total force and acceleration (assuming mass = 1)
        let acceleration = spring_force + damping_force;

        // Semi-implicit Euler integration (more stable than explicit Euler)
        self.velocity += acceleration * dt;
        self.value += self.velocity * dt;
    }

    /// Set a new target value
    pub const fn set_target(&mut self, target: f32) {
        self.target = target;
    }

    /// Check if the spring has approximately settled at the target
    #[must_use]
    pub fn is_settled(&self, position_threshold: f32, velocity_threshold: f32) -> bool {
        let position_error = (self.value - self.target).abs();
        let velocity_mag = self.velocity.abs();

        position_error < position_threshold && velocity_mag < velocity_threshold
    }

    /// Reset the spring to a new position with zero velocity
    pub const fn reset(&mut self, value: f32, target: f32) {
        self.value = value;
        self.target = target;
        self.velocity = 0.0;
    }
}