@use 'sass:color';
@use 'sass:math';
@use 'sass:meta';
@use 'is-color' as *;
@use 'is-number' as *;
@use 'is-percentage' as *;

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} is-color
/// @require {function} is-number
/// @require {function} is-percentage
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
@function tint($color, $percentage) {
  @if not is-color($color) {
    @error 'Invalid data type passed to [ tint() ] function. You passed ' +
      '#{meta.inspect($color)} for the $color argument, which is not a ' +
      'a color that can be lightened by this function, as it is not currently ' +
      'recognized as a color by Sass.';
  }

  // If $percentage is a unitless number, convert to a percentage.
  @if is-number($percentage) and math.is-unitless($percentage) {
    // When converting, if it is between -1 and 1, assume the user meant it as a
    // decimal that represents a percentage (ex: 0.6 = 60%). Otherwise, assume
    // it is just a percentage missing its % sign (ex: 60 = 60%).
    @if $percentage > -1 and $percentage < 1 {
      $percentage: math.percentage($percentage);
    } @else {
      $percentage: $percentage * 1%;
    }
  }

  @if not is-percentage($percentage) {
    @error 'Invalid data type passed to [ tint() ] function. You passed ' +
      '#{meta.inspect($percentage)} for the $percentage argument, which is ' +
      'not a valid perecentage.';
  }

  @return color.scale($color, $lightness: $percentage);
}

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} tint
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
///
/// @alias tint
@function lighter($color, $percentage) {
  @return tint($color, $percentage);
}

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} tint
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
///
/// @alias tint
@function lighten($color, $percentage) {
  @return tint($color, $percentage);
}

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} tint
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
///
/// @alias tint
@function color-tint($color, $percentage) {
  @return tint($color, $percentage);
}

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} tint
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
///
/// @alias tint
@function color-lighter($color, $percentage) {
  @return tint($color, $percentage);
}

/// Lighten a color by a given percentage using the built-in color.scale() method.
///
/// @param {Color} $color - The color being lightened.
/// @param {Number} $percentage - The percentage of lightness to add to the color.
///
/// @return {Color} - The lightened color.
///
/// @access public
/// @group Utilities
/// @require {function} tint
///
/// @throw Invalid $color data type error, must be of type 'color'.
/// @throw Invalid $percentage data type error.
///
/// @alias tint
@function color-lighten($color, $percentage) {
  @return tint($color, $percentage);
}