// ============================================================================
// Poster
// ============================================================================

////
/// 
/// Cursors Mixin Module
/// ===========================================================================
///
/// This module provides a comprehensive set of mixins for managing cursor
/// styles in CSS. It includes utility mixins for common cursor types, 
/// custom cursors with fallback options, animated cursors, and advanced 
/// use cases involving state-based and responsive cursor handling.
/// 
/// 
/// @group Mouse
/// @author Scape Agency
/// @link https://move.gl
/// @since 0.1.0 initial release
/// @todo None
/// @see https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
/// @access public
/// 
////


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

@use "../variables" as *;
@use "../maps" as *;
@use "../mixins" as *;







///
/// Mixin for applying a cursor style using predefined cursor types from the map.
/// 
/// @mixin cursor_style
/// @param {String} $type ['default'] - The cursor style to apply.
/// @example scss - Usage
///   .element { @include cursor_style('pointer'); } // Applies pointer cursor
///
@mixin cursor_style($type: "default") {
    @if map-has-key($cursor_styles, $type) {
        cursor: map-get($cursor_styles, $type);
    } @else {
        cursor: $type; // Fallback if type is not in map
    }
}

///
/// Mixin for custom cursor images with fallback options.
/// 
/// @mixin cursor_custom
/// @param {String} $url - URL of the custom cursor image.
/// @param {String} $fallback ['pointer'] - Fallback cursor style.
/// @example scss - Usage
///   .element { @include cursor_custom('path/to/cursor.png', 'pointer'); }
///
@mixin cursor_custom($url, $fallback: pointer) {
    cursor: url($url), $fallback;
    // cursor: url(#{$url}), #{$fallback};
}






// ============================================================================
// Utility Mixins for Common Cursor Styles
// ============================================================================

@mixin cursor_pointer { @include cursor_style('pointer'); }
@mixin cursor_text { @include cursor_style('text'); }
@mixin cursor_disabled { @include cursor_style('not-allowed'); }
@mixin cursor_move { @include cursor_style('move'); }
@mixin cursor_grab { @include cursor_style('grab'); }
@mixin cursor_grabbing { @include cursor_style('grabbing'); }
@mixin cursor_help { @include cursor_style('help'); }
@mixin cursor_wait { @include cursor_style('wait'); }
@mixin cursor_crosshair { @include cursor_style('crosshair'); }
@mixin cursor_zoom_in { @include cursor_style('zoom-in'); }
@mixin cursor_zoom_out { @include cursor_style('zoom-out'); }

// ============================================================================
// Advanced Mixins
// ============================================================================

///
/// Mixin for hover and focus cursor effects.
/// 
/// @mixin hover_focus_cursor
/// @param {String} $hover ['pointer'] - Cursor style on hover.
/// @param {String} $focus ['pointer'] - Cursor style on focus.
///
@mixin hover_focus_cursor($hover: pointer, $focus: pointer) {
    &:hover { cursor: $hover; }
    &:focus {
        cursor: $focus;
        outline: none; // Customize focus styles as needed
    }
}

///
/// Mixin for responsive cursor handling based on device capability.
/// 
/// @mixin cursor_responsive
/// @param {String} $desktop ['pointer'] - Cursor for desktop devices.
/// @param {String} $touch ['default'] - Cursor for touch devices.
///
@mixin cursor_responsive($desktop: pointer, $touch: default) {
    @media (pointer: fine) { cursor: $desktop; }
    @media (pointer: coarse) { cursor: $touch; }
}

///
/// Mixin for animated cursors using a series of images.
/// 
/// @mixin cursor_animated
/// @param {List} $images - A list of image URLs for animation frames.
/// @param {Time} $interval ['0.5s'] - Interval between frames.
///
@mixin cursor_animated($images, $interval: 0.5s) {
    $animation-frames: ();
    $index: 0;

    @each $image in $images {
        $index: $index + 1;
        $percentage: percentage($index / length($images));
        $animation-frames: append($animation-frames, ($percentage $image), comma);
    }

    @keyframes cursor-animation {
        @each $frame in $animation-frames {
            #{nth($frame, 1)} {
                cursor: url(#{nth($frame, 2)}), auto;
            }
        }
    }

    animation: cursor-animation $interval infinite;
}

// ============================================================================
// Utility Class Generator for Common Cursors
// ============================================================================

// $cursors: ('pointer', 'text', 'wait', 'crosshair', 'not-allowed', 'zoom-in', 'grab', 'grabbing');

@each $cursor in $cursors {
    .cursor-#{$cursor} {
        @include cursor_style($cursor);
    }
}

// ============================================================================
// Examples of Using Advanced Mixins
// ============================================================================

// /// Example: Advanced hover and focus with cursor change and background effect
// .interactive-element {
//     @include hover_focus_cursor(pointer, pointer);
//     &:hover { background-color: lighten($primaryColor, 5%); }
//     &:focus { background-color: lighten($primaryColor, 10%); }
// }

// /// Example: Responsive cursor handling for different devices
// .button {
//     @include cursor_responsive(pointer, default);
// }

// /// Example: Using animated cursor with a series of images
// .cursor-animated-element {
//     @include cursor_animated(('image1.png', 'image2.png', 'image3.png'));
// }