@use 'sass:math';
@use 'sass:meta';

/// Mixes black with a given opacity level.
///
/// @param {Number} $opacity [1] - An opacity level between either 0 and 1
/// or 0% and 100%, inclusive.
///
/// @return {Color} The black color at the given opacity level.
///
/// @access public
/// @group Utilities
///
/// @throw Invalid data type for $opacity
/// @throw Invalid unit type for $opacity
/// @throw $opacity value out of range
@function black($opacity: 1) {
  @if meta.type-of($opacity) != 'number' {
    @error 'Invalid data type for $opacity passed to the [ black() ] ' +
        'function. The value for $opacity must be a number.';
  }
  @if not math.is-unitless($opacity) and math.unit($opacity) != '%' {
    @error 'Invalid $opacity unit type of \'#{math.unit($opacity)}\' passed ' +
        'to the [ black() ] function. The value for $opacity must be a ' +
        'unitless decimal or a percentage.';
  }
  @if (math.unit($opacity) == '%' and ($opacity < 0% or $opacity > 100%)) or
      (math.is-unitless($opacity) and ($opacity < 0 or $opacity > 1))
  {
    @error 'Invalid $opacity level of #{meta.inspect($opacity)} passed to the ' +
        '[ black() ] function.';
  }

  @if math.unit($opacity) == '%' {
    $opacity: math.div($opacity, 100%);
  }

  @if $opacity == 1 {
    @return #000;
  } @else if $opacity == 0 {
    @return transparent;
  } @else {
    @return hsla(0, 0%, 0%, $opacity);
  }
}