////
///
/// Keyframes Mixin Module
/// ===========================================================================
///
/// This module provides a comprehensive set of keyframe animation mixins
/// including the base keyframes generator and common animation patterns.
/// Supports vendor prefixes and CSS custom properties for flexibility.
///
/// @group Keyframes
/// @author Scape Agency
/// @link https://move.gl
/// @since 0.1.0 initial release
/// @todo None
/// @access public
///
////


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

@use "sass:math";
@use "../../variables" as *;


// ============================================================================
// Base Keyframes Mixin
// ============================================================================

///
/// Keyframes Mixin
/// ---------------------------------------------------------------------------
///
/// A versatile mixin for defining CSS keyframes with vendor prefixes.
/// This mixin allows embedding keyframe content with the ability to specify
/// prefixes or additional settings easily.
///
/// @name keyframes
/// @param {String} $name - The name of the keyframe animation.
/// @content - The keyframe rules defined within the mixin block.
/// @example scss - Usage
///   @include keyframes(animate_bounce) {
///       0% { transform: translateY(0); }
///       50% { transform: translateY(-30px); }
///       100% { transform: translateY(0); }
///   }
///
@mixin keyframes($name) {
    @keyframes #{$name} {
        @content;
    }

    @-webkit-keyframes #{$name} {
        @content;
    }
}


// ============================================================================
// Animation Application Mixin
// ============================================================================

///
/// Apply animation with full control.
///
/// @param {String} $name - Animation name.
/// @param {Time} $duration [$keyframe-duration-default] - Duration.
/// @param {String} $timing [$keyframe-timing-default] - Timing function.
/// @param {Time} $delay [0s] - Delay before animation.
/// @param {Number|String} $iteration [$keyframe-iteration-default] - Iteration count.
/// @param {String} $direction [normal] - Direction.
/// @param {String} $fill-mode [forwards] - Fill mode.
/// @param {String} $play-state [running] - Play state.
///
@mixin animate(
    $name,
    $duration: $keyframe-duration-default,
    $timing: $keyframe-timing-default,
    $delay: 0s,
    $iteration: $keyframe-iteration-default,
    $direction: normal,
    $fill-mode: forwards,
    $play-state: running
) {
    animation-name: $name;
    animation-duration: $duration;
    animation-timing-function: $timing;
    animation-delay: $delay;
    animation-iteration-count: $iteration;
    animation-direction: $direction;
    animation-fill-mode: $fill-mode;
    animation-play-state: $play-state;
}

///
/// Shorthand animation mixin.
///
/// @param {String} $animation - Full animation shorthand value.
///
@mixin animation($animation) {
    animation: $animation;
}

///
/// Infinite looping animation.
///
/// @param {String} $name - Animation name.
/// @param {Time} $duration [1s] - Duration per cycle.
/// @param {String} $timing [linear] - Timing function.
///
@mixin animate_infinite($name, $duration: 1s, $timing: linear) {
    animation: $name $duration $timing infinite;
}


// ============================================================================
// Loading Animation Keyframes
// ============================================================================

///
/// Spinner rotation.
///
@mixin keyframes_spinner {
    @include keyframes(spinner) {
        from { transform: rotate(0deg); }
        to { transform: rotate(360deg); }
    }
}

///
/// Dots loading animation.
///
@mixin keyframes_dots {
    @include keyframes(dots) {
        0%, 80%, 100% {
            transform: scale(0);
            opacity: 0.5;
        }
        40% {
            transform: scale(1);
            opacity: 1;
        }
    }
}

///
/// Progress bar animation.
///
@mixin keyframes_progress {
    @include keyframes(progress) {
        from { width: 0%; }
        to { width: 100%; }
    }
}

///
/// Skeleton loading shimmer.
///
@mixin keyframes_shimmer {
    @include keyframes(shimmer) {
        from {
            background-position: -200% 0;
        }
        to {
            background-position: 200% 0;
        }
    }
}


// ============================================================================
// Animation Control Mixins
// ============================================================================

///
/// Pause animation.
///
@mixin animation_pause {
    animation-play-state: paused;
}

///
/// Resume animation.
///
@mixin animation_play {
    animation-play-state: running;
}

///
/// Reduce motion for accessibility.
///
@mixin animation_reduce_motion {
    @media (prefers-reduced-motion: reduce) {
        animation: none !important;
        transition: none !important;
    }
}