@use "sass:list";

/// Returns a copy of `$list` with `$val` appended to the end.
/// @param {List} $list - The list to process.
/// @param {Any} $val - The value to append to `$list`.
/// @param {String} $separator - The separator to use between `$list` and `$val`.
/// @return {List} - A copy of `$list` with `$val` appended to the end.
///
/// @example scss - Usage
///   @debug k-list-append( ( "foo", "bar" ), "baz" ); // => "foo, bar, baz"
@function k-list-append( $list, $val, $separator: auto ) {
    @return list.append( $list, $val, $separator );
}

/// Checks whether `$list` contains `$value`.
/// @param {List} $list - The list to check.
/// @param {Any} $value - The value to check for.
/// @return {Boolean} - Whether `$list` contains `$value`.
///
/// @example scss - Usage
///   @debug k-list-includes( ( "foo", "bar" ), "foo" ); // => true
///   @debug k-list-includes( ( "foo", "bar" ), "baz" ); // => false
@function k-list-includes( $list, $value ) {
    @return k-list-index( $list, $value ) != null;
}

/// Returns the index of `$value` in `$list`.
/// @param {List} $list - The list to check.
/// @param {Any} $value - The value to check for.
/// @return {Number} - The index of `$value` in `$list`.
///
/// @example scss - Usage
///   @debug k-list-index( ( "foo", "bar" ), "foo" ); // => 1
@function k-list-index( $list, $value ) {
    @return list.index( $list, $value );
}

/// Returns whether `$list` is bracketed.
/// @param {List} $list - The list to check.
/// @return {Boolean} - Whether `$list` is bracketed.
///
/// @example scss - Usage
///   @debug k-list-is-bracketed( ( "foo", "bar" ) ); // => false
///   @debug k-list-is-bracketed( [ "foo", "bar" ] ); // => true
@function k-list-is-bracketed( $list ) {
    @return list.is-bracketed( $list );
}

/// Joins two lists together.
/// @param {List} $list1 - The first list to join.
/// @param {List} $list2 - The second list to join.
/// @param {String} $separator - The separator to use between `$list1` and `$list2`.
/// @param {Boolean} $bracketed - Whether the result should be bracketed.
/// @return {List} - The joined list.
///
/// @example scss - Usage
///   @debug k-list-join( ( "foo", "bar" ), ( "baz", "qux" ) ); // => "foo, bar, baz, qux"
///   @debug k-list-join( ( "foo", "bar" ), ( "baz", "qux" ), " " ); // => "foo bar baz qux"
@function k-list-join( $list1, $list2, $separator: auto, $bracketed: auto ) {
    @return list.join( $list1, $list2, $separator, $bracketed );
}

/// Returns the length of `$list`.
/// @param {List} $list - The list to check.
/// @return {Number} - The length of `$list`.
///
/// @example scss - Usage
///   @debug k-list-length( ( "foo", "bar" ) ); // => 2
@function k-list-length( $list ) {
    @return list.length( $list );
}

/// Returns the nth item in `$list`.
/// @param {List} $list - The list to check.
/// @param {Number} $n - The index of the item to return.
/// @return {Any} - The nth item in `$list`.
///
/// @example scss - Usage
///   @debug k-list-nth( ( "foo", "bar" ), 1 ); // => "foo"
@function k-list-nth( $list, $n ) {
    @return list.nth( $list, $n );
}

/// Reverse the order of items in `$list`.
/// @param {List} $list - The list to reverse.
/// @return {List} - The reversed list.
///
/// @example scss - Usage
///   @debug k-list-reverse( ( "foo", "bar" ) ); // => "bar, foo"
@function k-list-reverse( $list: null ) {
    $result: ();

    @if ($list) {
        $len: k-list-length( $list );

        @for $i from $len through 1 {
            $result: k-list-append( $result, k-list-nth( $list, $i ) );
        }

        @return $result;
    }

    @warn "No list passed.";
    @return $result;
}

/// Returns the separator of `$list`.
/// @param {List} $list - The list to check.
/// @return {String} - The separator of `$list`.
///
/// @example scss - Usage
///   @debug k-list-separator( ( "foo", "bar" ) ); // => ","
@function k-list-separator( $list ) {
    @return list.list-separator( $list );
}

/// Returns a copy of `$list` with `$val` inserted at `$n`.
/// @param {List} $list - The list to process.
/// @param {Number} $n - The index at which to insert `$val`.
/// @param {Any} $val - The value to insert.
/// @return {List} - A copy of `$list` with `$val` inserted at `$n`.
///
/// @example scss - Usage
///   @debug k-list-set-nth( ( "foo", "bar" ), 1, "baz" ); // => "baz, bar"
@function k-list-set-nth( $list, $n, $value ) {
    @return list.set-nth( $list, $n, $value );
}

/// Combines two lists into a single list of two-item lists.
/// @param {List} $list1 - The first list to combine.
/// @param {List} $list2 - The second list to combine.
/// @return {List} - A list of two-item lists.
///
/// @example scss - Usage
///   @debug k-list-zip( ( "foo", "bar" ), ( "baz", "qux" ) ); // => ((foo, baz), (bar, qux))
@function k-list-zip( $lists... ) {
    @return list.zip( $lists... );
}