@use '../internal/function';
@use 'tokens';
@use 'contrast';
@use 'sass:color';
@use 'sass:meta';

/// # Color Utility Functions
/// @group color-utils

// Tint
// ----
/// Mix a color with `contrast-light`
/// (defaults to `white`)
/// to get a lighter tint of your color.
/// Make sure to override `$light` when using `tint`
/// to define the value of `contrast-light`
///
/// @since 2.0.0 -
/// - BREAKING: Use `contrast-light` for default mix, rather than `white`.
/// - NEW: Accept `$light` color to use in place of `contrast-light` default
///
/// @group color-utils
///
/// @param {string | list} $color -
///   The name of a color in your palette,
///   with optional adjustments in the form of `(<function-name>: <args>)`.
/// @param {percentage} $percentage -
///   The percentage of a `$light` color to mix in.
///   Higher percentages will result in a lighter tint.
/// @param {color | String} $light [null] -
///   The lighter color to be mixed in for tinting.
/// @return {color} -
///   A calculated CSS-ready color value based on your global color palette.
@function tint($color, $percentage, $light: null) {
  $light: $light or contrast.default-contrast('light');

  @return color.mix(tokens.color($light), tokens.color($color), $percentage);
}

@include function.internal(meta.get-function('tint'), 'tint');

// Shade
// -----
/// Mix a color with `contrast-dark`
/// (defaults to `black`)
/// to get a darker shade of your color.
/// Make sure to override `$dark` when using `shade`
/// to define the value of `contrast-dark`
///
/// @since 2.0.0 -
/// - BREAKING: Use `contrast-dark` for default mix, rather than `black`
/// - NEW: Accept `$dark` color to use in place of `contrast-dark` default
///
/// @group color-utils
///
/// @param {string | list} $color -
///   The name of a color in your palette,
///   with optional adjustments in the form of `(<function-name>: <args>)`.
/// @param {Percentage} $percentage -
///   The percentage of a `$dark` color to mix in.
///   Higher percentages will result in a lighter tint.
/// @param {color | String} $dark [null] -
///   The darker color to be mixed in for shading.
/// @return {color} -
///   A calculated CSS-ready color value based on your global color palette.
@function shade($color, $percentage, $dark: null) {
  $dark: $dark or contrast.default-contrast('dark');

  @return color.mix(tokens.color($dark), tokens.color($color), $percentage);
}

@include function.internal(meta.get-function('shade'), 'shade');