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

/// Helper function that mixes white 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 white 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 white($opacity: 1) {
  @if meta.type-of($opacity) != 'number' {
    @error 'Invalid data type passed to white(). Opacity must be a number.';
  }

  @if not math.is-unitless($opacity) and math.unit($opacity) != '%' {
    @error 'Invalid opacity unit type of [ #{meta.inspect(math.unit($opacity))} ] ' +
        'passed to the [ white() ] function. 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 [ white() ] function.';
  }

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

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