@use 'sass:color';
@use 'sass:list';
@use 'sass:meta';
@use 'sass:string';
@use 'conv-color' as *;
@use 'get-color-type' as *;
@use 'is-color' as *;
@use 'is-string' as *;

/// Takes a given color and gives its complement in the specified color syntax.
/// This extends the functionality of Sass' color.complement and is the
/// equivalent of doing color.adjust($color, $hue: 180deg) while being able to
/// choose the output color format.
///
/// @param {Color} $color - The color to find the complement. Must be a color
/// type recognized by Sass.
/// @param {String} $syntax [get-color-type($color)] - The desired syntax of the
/// returned color. Defaults to the color notation used by `$color`.
///
/// @return {Color} - The color's complement in the given syntax.
///
/// @access public
/// @group Utilities
/// @require {function} conv-color
/// @require {function} get-color-type
/// @require {function} is-color
/// @require {function} is-string
///
/// @throw Invalid $color data type, must be a color.
/// @throw Invalid $syntax data type, must be a string.
/// @throw Invalid $syntax value, must be a color syntax string.
@function color-complement($color, $syntax: get-color-type($color)) {
  $valid-syntax-values: (
    'hex', '#', 'rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'function', 'name', 'cmyk'
  );

  @if not is-color($color) {
    @error 'Invalid $color data type of #{meta.inspect(meta.type-of($color))} ' +
        'passed to the [ color-complement() ] function. This value is not ' +
        'currently recognized as a color by your version of Sass.';
  }

  @if $syntax and is-string($syntax) {
    $syntax: string.to-lower-case($syntax);
  } @else if not $syntax {
    $syntax: get-color-type($color);
  } @else {
    @error 'Invalid $sytax data type of #{meta.type-of($syntax)} passed to ' +
        'the [ color-complement() ] function. The $syntax parameter must be ' +
        'of type \'string\' or be `null` or `false`. This function supports ' +
        'converting into the following $syntax values: ' +
        '[ \'hex\', \'#\', \'rgb\', \'rgba\', \'hsl\', \'hsla\', \'hwb\', ' +
        '\'function\', \'name\', \'cmyk\' ].';
  }

  @if not list.index($valid-syntax-values, $syntax) {
    @error 'Invalid $syntax value of #{meta.inspect($syntax)} passed to ' +
        'the [ color-complement() ] function. Value of $syntax must be a string ' +
        'representing a valid CSS color function specification. This function ' +
        'supports converting into the following $syntax values: ' +
        '[ \'hex\', \'#\', \'rgb\', \'rgba\', \'hsl\', \'hsla\', \'hwb\', ' +
        '\'function\', \'name\', \'cmyk\' ].';
  }

  @return conv-color(color.complement($color), $syntax);
}

/// Takes a given color and gives its complement in the specified color syntax.
/// This extends the functionality of Sass' color.complement and is the
/// equivalent of doing color.adjust($color, $hue: 180deg) while being able to
/// choose the output color format.
///
/// @param {Color} $color - The color to find the complement. Must be a color
/// type recognized by Sass.
/// @param {String} $syntax [get-color-type($color)] - The desired syntax of the
/// returned color. Defaults to the color notation used by `$color`.
///
/// @return {Color} - The color's complement in the given syntax.
///
/// @access public
/// @group Utilities
/// @require {function} conv-color
/// @require {function} get-color-type
/// @require {function} is-color
/// @require {function} is-string
///
/// @throw Invalid $color data type, must be a color.
/// @throw Invalid $syntax data type, must be a string.
/// @throw Invalid $syntax value, must be a color syntax string.
@function complement-color($color, $syntax: get-color-type($color)) {
  @return color-complement($color, $syntax);
}