////
///
/// Ripple Animations Mixin Module
/// ===========================================================================
///
/// Provides expanding ripple effects that scale and fade. Creates material
/// design-style touch feedback and water ripple effects. Ideal for buttons,
/// click feedback, and ambient decorations.
///
/// @group Animations
/// @author Scape Agency
/// @link https://move.gl
/// @since 0.1.0 initial release
/// @access public
///
////


// ============================================================================
// Use
// ============================================================================

@use "../../dev" as *;
@use "../../variables" as *;
@use "../keyframes" as *;
@use "base" as *;


// ============================================================================
// Mixins
// ============================================================================


///
/// Ripple Animation
/// ---------------------------------------------------------------------------
/// Creates a ripple effect where the element scales up and fades out.
///
/// @name animate_ripple
/// @param {Number} $scale_start [1] - Initial scale of the ripple
/// @param {Number} $scale_end [1.5] - Final scale of the ripple
/// @param {Number} $opacity_start [1] - Initial opacity of the ripple
/// @param {Number} $opacity_end [0] - Final opacity of the ripple
/// @param {Time} $duration [$animate_base_duration] - Animation duration
/// @param {String} $timing_function [ease-out] - Timing function
///
/// @example scss - Basic usage
///   .touch-ripple {
///     @include animate_ripple;
///   }
///
@mixin animate_ripple(
    $scale_start: 1,
    $scale_end: 1.5,
    $opacity_start: 1,
    $opacity_end: 0,
    $duration: $animate_base_duration,
    $timing_function: ease-out
) {
    @include animate_base(
        animate_ripple,
        $duration,
        $timing_function,
        infinite,
    );
    @include keyframes_animate_ripple($scale_start, $scale_end, $opacity_start, $opacity_end);
}


///
/// Slow Ripple Animation
/// ---------------------------------------------------------------------------
/// Creates a slower ripple effect where the element scales up and fades out.
///
/// @name animate_ripple_slow
/// @param {Number} $scale_end [1.5] - Final scale of the ripple
/// @param {Number} $opacity_end [0] - Final opacity of the ripple
/// @param {Time} $duration [2s] - Animation duration
/// @param {String} $timing_function [ease-out] - Timing function
///
/// @example scss - Usage
///   .water-ripple {
///     @include animate_ripple_slow;
///   }
///
@mixin animate_ripple_slow(
    $scale_end: 1.5,
    $opacity_end: 0,
    $duration: 2s,
    $timing_function: ease-out
) {
    @include animate_base(
        animate_ripple_slow,
        $duration,
        $timing_function,
        infinite,
    );
    @include keyframes_animate_ripple_slow($scale_end, $opacity_end);
}


// Multi-Ripple Animation
// ----------------------------------------------------------------------------

///
/// Multi-Ripple Animation
/// Creates a ripple effect with multiple stages of scaling and fading.
/// @name animate_ripple_multi
/// @param {Number} $scale_first [1.2] - The scale of the ripple at the first stage.
/// @param {Number} $scale_second [1.5] - The scale of the ripple at the second stage.
/// @param {Number} $opacity_end [0] - The final opacity of the ripple.
/// @param {Number|String} $duration [$animate_base_duration] - The duration of the ripple animation.
/// @param {String} $timing_function [ease-out] - The timing function for the ripple animation.
///
@mixin animate_ripple_multi(
    $scale_first: 1.2,
    $scale_second: 1.5,
    $opacity_end: 0,
    $duration: $animate_base_duration,
    $timing_function: ease-out
) {
    @include animate_base(
        animate_ripple_multi,
        $duration,
        $timing_function,
        infinite,
    );
    @include keyframes_animate_ripple_multi($scale_first, $scale_second, $opacity_end);
}


// Ripple with Color Change
// ----------------------------------------------------------------------------

///
/// Ripple with Color Change
/// Creates a ripple effect where the element scales up, fades out, and changes color.
/// @name animate_ripple_color
/// @param {Number} $scale_end [1.5] - The final scale of the ripple.
/// @param {Number} $opacity_end [0] - The final opacity of the ripple.
/// @param {Color} $color_start [$animate_base_color_start] - The starting color of the ripple.
/// @param {Color} $color_end [$animate_base_color_end] - The ending color of the ripple.
/// @param {Number|String} $duration [$animate_base_duration] - The duration of the ripple animation.
/// @param {String} $timing_function [ease-out] - The timing function for the ripple animation.
///
@mixin animate_ripple_color(
    $scale_end: 1.5,
    $opacity_end: 0,
    $color_start: $animate_base_color_start,
    $color_end: $animate_base_color_end,
    $duration: $animate_base_duration,
    $timing_function: ease-out
) {
    @include animate_base(
        animate_ripple_color,
        $duration,
        $timing_function,
        infinite,
    );
    @include keyframes_animate_ripple_color($scale_end, $opacity_end, $color_start, $color_end);
}