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

////
/// 
/// Pointers Mixin Module
/// ===========================================================================
///
/// This module provides mixins for managing pointer events in CSS, allowing 
/// for easy application of the `pointer-events` property with support for both 
/// global and keyword values. These mixins are useful for managing user 
/// interactions on various elements, including SVGs and standard HTML 
/// elements. The module includes simplified mixins for frequently used 
/// pointer-event states and utility mixins to handle hover styles based on 
/// pointer-event settings.
/// 
/// 
/// @group Mouse
/// @author Scape Agency
/// @link https://move.gl
/// @since 0.1.0 initial release
/// @todo None
/// @access public
/// 
////




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

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


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

///
/// Mixin for setting pointer-events property with support for both global and 
/// keyword values. This mixin can be used to enable or disable pointer events 
/// on an element.
///
/// @name pointer_events
/// @param {String} $state ['auto'] - The desired pointer-events state (e.g., 'auto', 'none', 'inherit').
/// @example scss - Usage
///   .interactive-element { @include pointer_events(auto); } // Enable pointer events
///   .non-interactive-element { @include pointer_events(none); } // Disable pointer events
///
@mixin pointer_events($state: auto) {
    pointer-events: $state;
}



// ============================================================================
// Global Pointer Event Values
// ============================================================================

///
/// Mixin for setting pointer-events to inherit from parent element.
/// 
/// @name pointer_inherit
/// @example scss - Usage
///   .element { @include pointer_inherit; } // Inherits pointer-events from parent
///
@mixin pointer_inherit { 
    @include pointer_events(inherit); 
}

///
/// Mixin for setting pointer-events to initial value.
/// 
/// @name pointer_initial
/// @example scss - Usage
///   .element { @include pointer_initial; } // Sets pointer-events to initial
///
@mixin pointer_initial { 
    @include pointer_events(initial); 
}

///
/// Mixin for setting pointer-events to revert.
/// 
/// @name pointer_revert
/// @example scss - Usage
///   .element { @include pointer_revert; } // Reverts pointer-events to previous value
///
@mixin pointer_revert { 
    @include pointer_events(revert); 
}

///
/// Mixin for setting pointer-events to revert-layer.
/// 
/// @name pointer_revert-layer
/// @example scss - Usage
///   .element { @include pointer_revert-layer; } // Sets pointer-events to revert-layer
///
@mixin pointer_revert-layer { 
    @include pointer_events(revert-layer); 
}

///
/// Mixin for setting pointer-events to unset.
/// 
/// @name pointer_unset
/// @example scss - Usage
///   .element { @include pointer_unset; } // Sets pointer-events to unset
///
@mixin pointer_unset { 
    @include pointer_events(unset); 
}

// ============================================================================
// Keyword Pointer Event Values
// ============================================================================

///
/// Mixin for setting pointer-events to auto, enabling all interactions.
/// 
/// @name pointer_auto
/// @example scss - Usage
///   .element { @include pointer_auto; } // Enables pointer events
///
@mixin pointer_auto { 
    @include pointer_events(auto); 
}

///
/// Mixin for setting pointer-events to none, disabling all interactions.
/// 
/// @name pointer_none
/// @example scss - Usage
///   .element { @include pointer_none; } // Disables pointer events
///
@mixin pointer_none { 
    @include pointer_events(none); 
}

///
/// Mixin for setting pointer-events to all (SVG Only).
/// 
/// @name pointer_all
/// @example scss - Usage
///   .svg-element { @include pointer_all; } // Enables all pointer events on SVG
///
@mixin pointer_all { 
    @include pointer_events(all); 
}

// Additional SVG-specific pointer-events mixins

@mixin pointer_fill { 
    @include pointer_events(fill); 
}

@mixin pointer_painted { 
    @include pointer_events(painted); 
}

@mixin pointer_stroke { 
    @include pointer_events(stroke); 
}

@mixin pointer_visible { 
    @include pointer_events(visible); 
}

@mixin pointer_visible-fill { 
    @include pointer_events(visibleFill); 
}

@mixin pointer_visible-painted { 
    @include pointer_events(visiblePainted); 
}

@mixin pointer_visible-stroke { 
    @include pointer_events(visibleStroke); 
}

// ============================================================================
// Utility Mixins
// ============================================================================

///
/// Mixin for applying hover styles only when pointer events are enabled.
/// This ensures hover styles do not apply if the element is non-interactive.
/// 
/// @name pointer_hover_check
/// @example scss - Usage
///   .interactive-element {
///     @include pointer_hover_check {
///       color: red;
///     }
///   }
///
@mixin pointer_hover_check {
    @if pointer-events != 'none' {
        &:hover { 
            @content; 
        }
    }
}

///
/// Simplified mixin for commonly used global pointer-events values.
/// Accepts 'inherit', 'initial', 'revert', 'revert-layer', and 'unset'.
/// 
/// @name pointer_global
/// @param {String} $value - The global value for pointer-events.
/// @example scss - Usage
///   .element { @include pointer_global(inherit); }
///
@mixin pointer_global($value) {
    @include pointer_events($value);
}

///
/// Simplified mixin for commonly used keyword pointer-events values.
/// Accepts 'auto', 'none', 'all' and SVG-specific values.
/// 
/// @name pointer_keyword
/// @param {String} $value - The keyword value for pointer-events.
/// @example scss - Usage
///   .element { @include pointer_keyword(auto); }
///
@mixin pointer_keyword($value) {
    @include pointer_events($value);
}







// ============================================================================
// Predefined Classes for Common Use Cases
// ============================================================================

.interactive-element {
    @include pointer_auto; // Enables pointer events
}
  
.non-interactive-element {
    @include pointer_none; // Disables pointer events
}
  
.custom-element {
    @include pointer_visible-painted; // Applies visiblePainted for SVG elements
}