////
///
/// Flash Animations Mixin Module
/// ===========================================================================
///
/// Provides flashing and blinking animations for attention-grabbing effects.
/// Includes standard flash, strobe, and fade variants with customizable
/// opacity levels and timing. Useful for alerts, notifications, and warnings.
///
/// @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
// ============================================================================


///
/// Flash Animation
/// ---------------------------------------------------------------------------
/// Creates a flash animation that transitions between different opacity
/// levels.
///
/// @name animate_flash
/// @param {Number} $start_opacity [1] - Initial opacity of the element
/// @param {Number} $mid_opacity [0] - Opacity at midpoint of animation
/// @param {Number} $end_opacity [1] - Final opacity of the element
/// @param {Time} $duration [$animate_base_duration] - Animation duration
/// @param {String} $timing_function [ease-in-out] - Timing function
/// @param {Number|String} $iteration_count - Number of iterations
///
/// @example scss - Basic usage
///   .alert {
///     @include animate_flash;
///   }
///
@mixin animate_flash(
    $start_opacity: 1,
    $mid_opacity: 0,
    $end_opacity: 1,
    $duration: $animate_base_duration,
    $timing_function: ease-in-out,
    $iteration_count: $animate_base_iteration_count
) {
    @include animate_base(
        animate_flash,
        $duration,
        $timing_function,
        $iteration_count,
    );
    @keyframes animate_flash {
        0%, 100% { opacity: $start_opacity; }
        50% { opacity: $mid_opacity; }
    }
}


///
/// Flash Fade Animation
/// ---------------------------------------------------------------------------
/// Creates a flash fade effect that smoothly transitions in and out of view.
///
/// @name animate_flash_fade
/// @param {Time} $duration [2s] - Animation duration
/// @param {String} $timing_function [ease-in-out] - Timing function
///
/// @example scss - Usage
///   .notification {
///     @include animate_flash_fade;
///   }
///
@mixin animate_flash_fade(
    $duration: 2s,
    $timing_function: ease-in-out
) {
    @include animate_base(
        animate_flash_fade,
        $duration,
        $timing_function, infinite
    );
    @keyframes animate_flash_fade {
        0%, 100% { opacity: 0; }
        50% { opacity: 1; }
    }
}


///
/// Strobe Flash Animation
/// ---------------------------------------------------------------------------
/// Creates a strobe flash effect with a configurable frequency.
///
/// @name animate_flash_strobe
/// @param {Time} $frequency [0.1s] - Frequency of the strobe effect
/// @param {Time} $duration [$animate_base_duration] - Animation duration
/// @param {String} $timing_function [steps(1, end)] - Timing function
///
/// @example scss - Usage
///   .warning {
///     @include animate_flash_strobe;
///   }
///
@mixin animate_flash_strobe(
    $frequency: 0.1s,
    $duration: $animate_base_duration,
    $timing_function: steps(1, end)
) {
    @include animate_base(
        animate_flash_strobe,
        $duration,
        $timing_function,
        infinite
    );
    @keyframes animate_flash_strobe {
        0%, 100% { opacity: 1; }
        50% { opacity: 0; }
    }
    animation-duration: $frequency;
}


///
/// Slow Fade Flash Animation
/// ---------------------------------------------------------------------------
/// Creates a slow fading flash effect, fading in and out of view.
///
/// @name animate_flash_fade_slow
/// @param {Time} $duration [$animate_base_duration_slow] - Animation duration
/// @param {String} $timing_function [ease-in-out] - Timing function
///
/// @example scss - Usage
///   .gentle-pulse {
///     @include animate_flash_fade_slow;
///   }
///
@mixin animate_flash_fade_slow(
    $duration: $animate_base_duration_slow,
    $timing_function: ease-in-out
) {
    @include animate_base(
        animate_flash_fade_slow,
        $duration,
        $timing_function,
        infinite
    );
    @keyframes animate_flash_fade_slow {
        0%, 100% { opacity: 1; }
        50% { opacity: 0; }
    }
}