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

////
///
/// Contrast Functions Module
/// ===========================================================================
///
///
/// @group Contrast
/// @author Scape Agency
/// @link https://hue.gl
/// @since 0.1.0 initial release
/// @todo None
/// @access public
///
////


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

@use "sass:math";

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

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



///
/// Contrast Function
/// ---------------------------------------------------------------------------
///
/// Function to determine the ideal text color (light or dark) for optimal
/// readability against a specified background color.
///
/// @name color_contrast
/// @param {Color} $background-color - The background color to analyze.
/// @return {Color} - Returns `black` for light backgrounds and `white` for dark backgrounds.
///
/// @example scss - Usage
///   color: color_contrast(#fff); // Returns 'black'
///
@function color_contrast(
    $background-color
) {
    @if (lightness($background-color) > 50%) {
        @return black; // Dark text on light background
    } @else {
        @return white; // Light text on dark background
    }
}


///
/// Contrast Checker
/// ---------------------------------------------------------------------------
///
/// Calculates the contrast ratio between two colors to ensure they meet
/// accessibility guidelines.
///
/// @name color_contrast_checker
/// @param {String} $color1_name - The name of the first color.
/// @param {String} $color2_name - The name of the second color.
/// @return {Number} - The contrast ratio between the two colors.
///
/// @example scss - Usage
///   $contrast: color_contrast_checker('blue', 'white');
///
@function color_contrast_checker(
    $color1_name,
    $color2_name
) {
    $color1: hue-color($color1_name);
    $color2: hue-color($color2_name);
    @return contrast-ratio($color1, $color2);
}


///
///  Color Contrast Ratio
/// ---------------------------------------------------------------------------
///
/// Generates a dynamic text color (black or white) based on the given
/// background color to enhance readability.
///
/// @name color_contrast_dynamic
/// @param {String} $background_color_name - The name of the background color.
/// @return {Color} - Optimal text color for the given background.
///
/// @example scss - Usage
///   color: color_contrast_dynamic('darkblue');
///
@function hue_contrast_ratio(
    $color_name1,
    $color_name2
) {
    $color1: hue_color($color_name1);
    $color2: hue_color($color_name2);

    @if type-of($color1) != 'color' or type-of($color2) != 'color' {
        @warn "One or both specified colors could not be found.";
        @return null;
    }

    // Implement contrast ratio formula
    // Placeholder for actual calculation
    @return 'Contrast Ratio Calculation Placeholder';
}


///
/// Dynamic Text Color
/// ---------------------------------------------------------------------------
///
/// Generates a dynamic text color (black or white) based on the given
/// background color to enhance readability.
///
/// @name color_contrast_dynamic
/// @param {String} $background_color_name - The name of the background color.
/// @return {Color} - Optimal text color for the given background.
/// @example scss - Usage
///   color: color_contrast_dynamic('darkblue');
///
@function color_contrast_dynamic($background_color_name) {
    $background-color: hue-color($background_color_name);
    @if (hue-contrast($background-color, black) > 4.5) {
        @return black;
    } @else {
        @return white;
    }
}


///
/// Contrast Text Color
/// ---------------------------------------------------------------------------
/// Returns a high-contrast text color (black or white) based on the specified
/// background color.
///
/// @name hue_contrast_text_color
/// @param {String} $background_color_name - The name of the background color from the color map.
/// @return {Color} - Either black or white, depending on which has higher contrast against the background.
///
/// @example scss - Usage
///   color: hue_contrast_text_color('lightgrey'); // Returns 'black'
///
///
@function hue_contrast_text_color(
    $background_color_name
) {
    $background_color: hue_color($background_color_name);

    @if type-of($background_color) != 'color' {
        @warn "The specified color `#{$background_color_name}` could not be found.";
        @return null;
    }

    @if lightness($background_color) > 60% {
        @return black;
    } @else {
        @return white;
    }
}


///
/// Readable Overlay Text Color
/// ---------------------------------------------------------------------------
/// Determines an overlay text color that is readable over any background by
/// adjusting opacity.
///
/// @name hue_readable_overlay
/// @param {String} $background_color_name - The name of the background color.
/// @return {Color} - A semi-transparent black or white color for text overlays.
///
/// @example scss - Usage
///   background-color: hue_readable_overlay('limegreen');
///
@function hue_readable_overlay($background_color_name) {
    $background_color: hue_color($background_color_name);

    @if type-of($background_color) != 'color' {
        @warn "The specified color `#{$background_color_name}` could not be found.";
        @return null;
    }

    @if lightness($background_color) > 50% {
        @return rgba(black, 0.7);
    } @else {
        @return rgba(white, 0.7);
    }
}