////
///
/// Color Functions
/// ===========================================================================
///
/// Utility functions for color manipulation and calculations.
///
/// @group Functions
/// @author Scape Agency
/// @link https://scape.style
/// @since 0.1.0 initial release
/// @access public
///
////

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

@use "sass:color";
@use "sass:math";
@use "sass:meta";

// ============================================================================
// Functions
// ============================================================================

/// Calculate the relative luminance of a color
/// @param {Color} $color - The color to analyze
/// @return {Number} - Relative luminance value (0-1)
@function luminance($color) {
    $red: color.red($color) / 255;
    $green: color.green($color) / 255;
    $blue: color.blue($color) / 255;

    @if $red <= 0.03928 {
        $red: math.div($red, 12.92);
    } @else {
        $red: math.pow(math.div($red + 0.055, 1.055), 2.4);
    }

    @if $green <= 0.03928 {
        $green: math.div($green, 12.92);
    } @else {
        $green: math.pow(math.div($green + 0.055, 1.055), 2.4);
    }

    @if $blue <= 0.03928 {
        $blue: math.div($blue, 12.92);
    } @else {
        $blue: math.pow(math.div($blue + 0.055, 1.055), 2.4);
    }

    @return 0.2126 * $red + 0.7152 * $green + 0.0722 * $blue;
}

/// Calculate contrast ratio between two colors
/// @param {Color} $color1 - First color
/// @param {Color} $color2 - Second color
/// @return {Number} - Contrast ratio (1-21)
@function contrast-ratio($color1, $color2) {
    $lum1: luminance($color1) + 0.05;
    $lum2: luminance($color2) + 0.05;

    @return math.div(math.max($lum1, $lum2), math.min($lum1, $lum2));
}

/// Get optimal text color (black or white) for a given background
/// @param {Color} $background - Background color
/// @param {Color} $light [#ffffff] - Light text color option
/// @param {Color} $dark [#000000] - Dark text color option
/// @return {Color} - Optimal text color
@function text-contrast($background, $light: #ffffff, $dark: #000000) {
    $light-contrast: contrast-ratio($background, $light);
    $dark-contrast: contrast-ratio($background, $dark);

    @if $light-contrast > $dark-contrast {
        @return $light;
    } @else {
        @return $dark;
    }
}

/// Create a color shade (darken)
/// @param {Color} $color - Base color
/// @param {Number} $percentage - Amount to darken (0-100)
/// @return {Color} - Shaded color
@function shade($color, $percentage) {
    @return color.mix(#000000, $color, $percentage);
}

/// Create a color tint (lighten)
/// @param {Color} $color - Base color
/// @param {Number} $percentage - Amount to lighten (0-100)
/// @return {Color} - Tinted color
@function tint($color, $percentage) {
    @return color.mix(#ffffff, $color, $percentage);
}

/// Create a color tone (add grey)
/// @param {Color} $color - Base color
/// @param {Number} $percentage - Amount of grey (0-100)
/// @return {Color} - Toned color
@function tone($color, $percentage) {
    @return color.mix(#808080, $color, $percentage);
}

/// Check if a color is light or dark
/// @param {Color} $color - Color to check
/// @return {String} - "light" or "dark"
@function color-type($color) {
    @if luminance($color) > 0.5 {
        @return "light";
    } @else {
        @return "dark";
    }
}

/// Generate an accessible color pair
/// @param {Color} $background - Background color
/// @param {Number} $min-ratio [4.5] - Minimum contrast ratio (WCAG AA = 4.5, AAA = 7)
/// @return {Map} - Map with background and text colors
@function accessible-pair($background, $min-ratio: 4.5) {
    $text: text-contrast($background);

    @return (
        background: $background,
        text: $text,
        ratio: contrast-ratio($background, $text)
    );
}