@use 'sass:list';
@use 'sass:meta';

/// Iterates over a list and returns it as a converted string.
///
/// @param {List} $list - The list to convert into a string.
/// @param {String} $separator [' '] - The separator to use between
/// the list elements. By default this is the separator used in $list.
/// @param {Bool} $extra-space [false] - Pass true to use extra space between
/// list items in the resulting string.
///
/// @return {String} The converted string.
///
/// @access public
/// @group Utilities
///
/// @throw Invalid $list type error.
/// @throw Invalid $separator type error.
@function list-to-string(
  $list,
  $separator: if(meta.type-of($list) == 'list', list.separator($list), ' '),
  $extra-space: false
) {
  $str: '';

  @if meta.type-of($list) == 'string' {
    @warn 'You passed a string value to the [ list-to-string() ] function.' +
        'Returning original string of #{$list}';

    @return $list;
  }

  @if meta.type-of($list) != 'list' {
    @error 'Invalid $list type passed to the [ list-to-string() ] function. You ' +
        'passed `#{meta.inspect($list)}`, which is of type: '
        '[ #{meta.type-of($list)} ].';
  }

  @if $separator == comma or $separator == ',' or $separator == ', ' {
    @if $extra-space {
      $separator: ', ';
    } @else {
      $separator: ',';
    }
  } @else if $separator == space or $separator == ' ' or $separator == '  ' {
    @if $extra-space {
      $separator: '  ';
    } @else {
      $separator: ' ';
    }
  } @else if $separator == slash or $separator == '/' or $separator == ' / '{
    @if $extra-space {
      $separator: ' / ';
    } @else {
      $separator: '/';
    }
  } @else {
    @error 'Invalid $separator type passed to the [ list-to-string() ]' +
        'function. You passed `#{meta.inspect($list)}`, which is not ' +
        'a valid separator string. Use something like comma, space, or slash.';
  }

  @each $item in $list {
    @if $str == '' {
      $str: $item;
    } @else {
      $str: $str + $separator + $item;
    }
  }

  @return $str;
}

/// Iterates over a list and returns it as a converted string.
///
/// @param {List} $list - The list to convert into a string.
/// @param {String} $separator [' '] - The separator to use between
/// the list elements. By default this is the separator used in $list.
/// @param {Bool} $extra-space [false] - Pass true to use extra space between
/// list items in the resulting string.
///
/// @return {String} The converted string.
///
/// @access public
/// @group Utilities
/// @require {function} list-to-string
///
/// @throw Invalid $list type error.
/// @throw Invalid $separator type error.
///
/// @alias list-to-string
@function list-to-str(
  $list,
  $separator: if(meta.type-of($list) == 'list', list.separator($list), ' '),
  $extra-space: false
) {
  @return list-to-string($list, $extra-space, $separator);
}

/// Iterates over a list and returns it as a converted string.
///
/// @param {List} $list - The list to convert into a string.
/// @param {String} $separator [' '] - The separator to use between
/// the list elements. By default this is the separator used in $list.
/// @param {Bool} $extra-space [false] - Pass true to use extra space between
/// list items in the resulting string.
///
/// @return {String} The converted string.
///
/// @access public
/// @group Utilities
/// @require {function} list-to-string
///
/// @throw Invalid $list type error.
/// @throw Invalid $separator type error.
///
/// @alias list-to-string
@function list-join(
  $list,
  $separator: if(meta.type-of($list) == 'list', list.separator($list), ' '),
  $extra-space: false
) {
  @return list-to-string($list, $extra-space, $separator);
}