////
///
/// Hover Controls Mixin Module
/// =========================================================================
///
/// Provides a comprehensive set of hover effect mixins for creating
/// interactive UI elements. Includes scale, lift, glow, color
/// transitions, and advanced hover patterns.
///
/// @group Controls
/// @author Scape Agency
/// @link https://move.gl
/// @since 0.1.0 initial release
/// @access public
///
////


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

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


// ============================================================================
// Basic Hover Transition Mixin
// ============================================================================

///
/// Applies a smooth transition effect on hover for specified properties.
///
/// @param {List} $properties [all] - Properties to transition.
/// @param {Time} $duration [$hover-duration-default] - Duration.
/// @param {String} $timing [$hover-timing-default] - Timing function.
///
@mixin hover_transition($properties: all, $duration: $hover-duration-default, $timing: $hover-timing-default) {
    transition: #{$properties} #{$duration} #{$timing};

    &:hover {
        @content;
    }
}


// ============================================================================
// Transform Hover Effects
// ============================================================================

///
/// Scales an element when hovered.
///
/// @param {Number} $scale [$hover-scale-default] - Scale factor on hover.
/// @param {Time} $duration [$hover-duration-default] - Transition duration.
///
@mixin hover_scale($scale: $hover-scale-default, $duration: $hover-duration-default) {
    transition: transform $duration ease-in-out;

    &:hover {
        transform: scale($scale);
    }
}

///
/// Scale with additional transform origin control.
///
/// @param {Number} $scale [1.1] - Scale factor.
/// @param {String} $origin [center center] - Transform origin.
///
@mixin hover_scale_from($scale: 1.1, $origin: center center) {
    transform-origin: $origin;
    transition: transform 0.3s ease;

    &:hover {
        transform: scale($scale);
    }
}

///
/// Lifts element upward on hover with shadow.
///
/// @param {Length} $distance [$hover-lift-default] - Lift distance.
/// @param {Time} $duration [$hover-duration-default] - Duration.
///
@mixin hover_lift($distance: $hover-lift-default, $duration: $hover-duration-default) {
    transition: transform $duration ease, box-shadow $duration ease;

    &:hover {
        transform: translateY($distance);
        box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
    }
}

///
/// Rotate element on hover.
///
/// @param {Angle} $degrees [5deg] - Rotation angle.
///
@mixin hover_rotate($degrees: 5deg) {
    transition: transform 0.3s ease;

    &:hover {
        transform: rotate($degrees);
    }
}

///
/// Translate element on hover.
///
/// @param {Length} $x [0] - Horizontal translation.
/// @param {Length} $y [-10px] - Vertical translation.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_translate($x: 0, $y: -10px, $duration: 0.3s) {
    transition: transform $duration ease;
    cursor: pointer;

    &:hover {
        transform: translate($x, $y);
    }
}

///
/// Skew element on hover.
///
/// @param {Angle} $x [5deg] - X-axis skew.
/// @param {Angle} $y [0deg] - Y-axis skew.
///
@mixin hover_skew($x: 5deg, $y: 0deg) {
    transition: transform 0.3s ease;

    &:hover {
        transform: skew($x, $y);
    }
}

///
/// 3D tilt effect on hover.
///
/// @param {Angle} $x [10deg] - X rotation.
/// @param {Angle} $y [10deg] - Y rotation.
///
@mixin hover_tilt($x: 10deg, $y: 10deg) {
    transition: transform 0.3s ease;
    transform-style: preserve-3d;

    &:hover {
        transform: perspective(500px) rotateX($x) rotateY($y);
    }
}


// ============================================================================
// Color Hover Effects
// ============================================================================

///
/// Background color transition on hover.
///
/// @param {Color} $default - Default background color.
/// @param {Color} $hover - Hover background color.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_bg($default, $hover, $duration: 0.3s) {
    background-color: $default;
    transition: background-color $duration ease;

    &:hover {
        background-color: $hover;
    }
}

///
/// Text color transition on hover.
///
/// @param {Color} $default - Default text color.
/// @param {Color} $hover - Hover text color.
///
@mixin hover_color($default, $hover) {
    color: $default;
    transition: color 0.3s ease;

    &:hover {
        color: $hover;
    }
}

///
/// Border color transition on hover.
///
/// @param {Color} $default - Default border color.
/// @param {Color} $hover - Hover border color.
///
@mixin hover_border_color($default, $hover) {
    border-color: $default;
    transition: border-color 0.3s ease;

    &:hover {
        border-color: $hover;
    }
}

///
/// Darken background on hover.
///
/// @param {Number} $amount [10%] - Darken amount.
///
@mixin hover_darken($amount: 10%) {
    transition: filter 0.3s ease;

    &:hover {
        filter: brightness(#{100% - $amount});
    }
}

///
/// Lighten background on hover.
///
/// @param {Number} $amount [10%] - Lighten amount.
///
@mixin hover_lighten($amount: 10%) {
    transition: filter 0.3s ease;

    &:hover {
        filter: brightness(#{100% + $amount});
    }
}


// ============================================================================
// Shadow & Glow Hover Effects
// ============================================================================

///
/// Shadow on hover.
///
/// @param {String} $shadow [0 8px 25px rgba(0,0,0,0.15)] - Shadow value.
///
@mixin hover_shadow($shadow: 0 8px 25px rgba(0, 0, 0, 0.15)) {
    transition: box-shadow 0.3s ease;

    &:hover {
        box-shadow: $shadow;
    }
}

///
/// Glow effect on hover.
///
/// @param {Color} $color [#3b82f6] - Glow color.
/// @param {Number} $intensity [0.5] - Glow intensity.
/// @param {Length} $spread [20px] - Spread radius.
///
@mixin hover_glow($color: #3b82f6, $intensity: 0.5, $spread: 20px) {
    transition: box-shadow 0.3s ease;

    &:hover {
        box-shadow: 0 0 $spread rgba($color, $intensity);
    }
}

///
/// Ring/outline on hover.
///
/// @param {Color} $color [#3b82f6] - Ring color.
/// @param {Length} $width [3px] - Ring width.
/// @param {Length} $offset [2px] - Ring offset.
///
@mixin hover_ring($color: #3b82f6, $width: 3px, $offset: 2px) {
    transition: box-shadow 0.2s ease;

    &:hover {
        box-shadow: 0 0 0 $offset transparent, 0 0 0 ($offset + $width) $color;
    }
}


// ============================================================================
// Opacity Hover Effects
// ============================================================================

///
/// Opacity change on hover.
///
/// @param {Number} $default [1] - Default opacity.
/// @param {Number} $hover [0.7] - Hover opacity.
///
@mixin hover_opacity($default: 1, $hover: 0.7) {
    opacity: $default;
    transition: opacity 0.3s ease;

    &:hover {
        opacity: $hover;
    }
}

///
/// Fade in on hover (start transparent).
///
/// @param {Number} $from [0.6] - Starting opacity.
///
@mixin hover_fade_in($from: 0.6) {
    opacity: $from;
    transition: opacity 0.3s ease;

    &:hover {
        opacity: 1;
    }
}


// ============================================================================
// Combined Hover Effects
// ============================================================================

///
/// Scale and rotate combined hover effect.
///
/// @param {Number} $scale [1.2] - Scale factor.
/// @param {Angle} $rotate [10deg] - Rotation angle.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_scale_rotate($scale: 1.2, $rotate: 10deg, $duration: 0.3s) {
    transition: transform $duration ease;
    cursor: pointer;

    &:hover {
        transform: scale($scale) rotate($rotate);
    }
}

///
/// Lift and scale combined hover effect.
///
/// @param {Length} $lift [-10px] - Lift distance.
/// @param {Number} $scale [1.1] - Scale factor.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_lift_scale($lift: -10px, $scale: 1.1, $duration: 0.3s) {
    transition: transform $duration ease;
    cursor: pointer;

    &:hover {
        transform: translateY($lift) scale($scale);
    }
}

///
/// 3D rotate combined hover effect.
///
/// @param {Angle} $rotateY [30deg] - Y-axis rotation.
/// @param {Angle} $rotateX [15deg] - X-axis rotation.
/// @param {Number} $scale [1.1] - Scale factor.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_3d_rotate($rotateY: 30deg, $rotateX: 15deg, $scale: 1.1, $duration: 0.3s) {
    transition: transform $duration ease;
    cursor: pointer;

    &:hover {
        transform: rotateY($rotateY) rotateX($rotateX) scale($scale);
    }
}

///
/// Brighten on hover effect.
///
/// @param {Color} $color [#e0f2fe] - Hover background color.
/// @param {Time} $duration [0.3s] - Transition duration.
///
@mixin hover_brighten($color: #e0f2fe, $duration: 0.3s) {
    transition: background-color $duration ease;
    cursor: pointer;

    &:hover {
        background-color: $color;
    }
}


// ============================================================================
// Advanced Hover Patterns
// ============================================================================

///
/// Underline animation on hover.
///
/// @param {Color} $color [currentColor] - Underline color.
/// @param {Length} $thickness [2px] - Underline thickness.
/// @param {String} $position [bottom] - Position: bottom or top.
///
@mixin hover_underline($color: currentColor, $thickness: 2px, $position: bottom) {
    position: relative;

    &::after {
        content: '';
        position: absolute;
        left: 0;
        #{$position}: 0;
        width: 0;
        height: $thickness;
        background-color: $color;
        transition: width 0.3s ease;
    }

    &:hover::after {
        width: 100%;
    }
}

///
/// Underline sliding from center.
///
/// @param {Color} $color [currentColor] - Underline color.
/// @param {Length} $thickness [2px] - Thickness.
///
@mixin hover_underline_center($color: currentColor, $thickness: 2px) {
    position: relative;

    &::after {
        content: '';
        position: absolute;
        left: 50%;
        bottom: 0;
        width: 0;
        height: $thickness;
        background-color: $color;
        transition: width 0.3s ease, left 0.3s ease;
    }

    &:hover::after {
        width: 100%;
        left: 0;
    }
}

///
/// Background slide effect on hover.
///
/// @param {Color} $color [#3b82f6] - Background color.
/// @param {String} $direction [left] - Slide direction: left, right, top, bottom.
///
@mixin hover_bg_slide($color: #3b82f6, $direction: left) {
    position: relative;
    overflow: hidden;
    z-index: 1;

    &::before {
        content: '';
        position: absolute;
        z-index: -1;
        background-color: $color;
        transition: transform 0.3s ease;

        @if $direction == left {
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            transform: translateX(-100%);
        } @else if $direction == right {
            top: 0;
            right: 0;
            width: 100%;
            height: 100%;
            transform: translateX(100%);
        } @else if $direction == top {
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            transform: translateY(-100%);
        } @else if $direction == bottom {
            bottom: 0;
            left: 0;
            width: 100%;
            height: 100%;
            transform: translateY(100%);
        }
    }

    &:hover::before {
        transform: translate(0);
    }
}

///
/// Icon slide on hover (for buttons with icons).
///
/// @param {Length} $distance [5px] - Slide distance.
/// @param {String} $direction [right] - Direction.
///
@mixin hover_icon_slide($distance: 5px, $direction: right) {
    display: inline-flex;
    align-items: center;
    gap: 8px;

    > svg,
    > .icon {
        transition: transform 0.3s ease;
    }

    &:hover > svg,
    &:hover > .icon {
        @if $direction == right {
            transform: translateX($distance);
        } @else if $direction == left {
            transform: translateX(-$distance);
        } @else if $direction == up {
            transform: translateY(-$distance);
        } @else if $direction == down {
            transform: translateY($distance);
        }
    }
}

///
/// Shake animation on hover.
///
@mixin hover_shake {
    &:hover {
        animation: shake-hover 0.5s ease;
    }
}

///
/// Bounce animation on hover.
///
@mixin hover_bounce {
    transition: transform 0.2s ease;

    &:hover {
        animation: bounce-hover 0.5s ease;
    }
}

///
/// Pulse animation on hover.
///
@mixin hover_pulse {
    &:hover {
        animation: pulse-hover 1s ease infinite;
    }
}


// ============================================================================
// Group/Container Hover Effects
// ============================================================================

///
/// Show element when parent is hovered.
///
/// @param {String} $parent ['.group'] - Parent selector.
///
@mixin hover_show_on_parent($parent: '.group') {
    opacity: 0;
    visibility: hidden;
    transition: opacity 0.3s ease, visibility 0.3s ease;

    #{$parent}:hover & {
        opacity: 1;
        visibility: visible;
    }
}

///
/// Transform when parent is hovered.
///
/// @param {String} $parent ['.group'] - Parent selector.
/// @param {String} $transform [scale(1.1)] - Transform value.
///
@mixin hover_transform_on_parent($parent: '.group', $transform: scale(1.1)) {
    transition: transform 0.3s ease;

    #{$parent}:hover & {
        transform: $transform;
    }
}

///
/// Highlight current item, fade siblings on parent hover.
///
@mixin hover_highlight_item {
    transition: opacity 0.3s ease;

    .parent:hover &:not(:hover) {
        opacity: 0.5;
    }
}


// ============================================================================
// Accessibility-Aware Hover
// ============================================================================

///
/// Hover effect that respects reduced motion preference.
///
@mixin hover_safe($duration: 0.3s) {
    transition: all $duration ease;

    @media (prefers-reduced-motion: reduce) {
        transition: none;
    }

    &:hover {
        @content;
    }
}

///
/// Focus-visible styling for keyboard navigation.
///
@mixin hover_focus_visible {
    &:hover,
    &:focus-visible {
        @content;
    }

    &:focus:not(:focus-visible) {
        outline: none;
    }
}