index.scss

////
/// @author Andrey Mikhaylov (lolmaus) <https://github.com/lolmaus>
/// @group api
////

@use "sass:list";
@use "sass:map";
@use "sass:math";
@use "sass:meta";
@use "sass:string";

/// The default slices map.
/// @type Map
/// @access public
$slices: (
  xxs:     0px,
  xs:    200px,
  s:     400px,
  m:     600px,
  l:     800px,
  xl:   1000px,
  xxl:  1200px,
  xxxl: 1400px,
) !default;


/// A list of media types and features to be prepended to every media query generated by breakpoint-slicer.
/// Can assume one of the following values:
/// * `null` (default) — nothing is prepended
/// * a single media query, e. g. `monochrome and (orientation: portrait)`
/// * a comma-separated list of media queries, e. g. `screen, print`
/// @type null | list
/// @access public
/// @example scss
///  $media: null;
///
///  .foo {
///    @include from(s) {
///      color: red;
///    }
///  }
///
///  // produces:
///
///  @media (min-width: 400px) {
///    .foo {
///      color: red;
///    }
///  }
/// @example scss
///  $media: monochrome and (orientation: portrait);
///
///  .foo {
///    @include from(s) {
///      color: red;
///    }
///  }
///
///  // produces:
///
///  @media monochrome and (orientation: portrait) and (min-width: 400px) {
///    .foo {
///      color: red;
///    }
///  }
/// @example scss
///  $media: screen, print;
///
///  .foo {
///    @include from(s) {
///      color: red;
///    }
///  }
///
///  // produces:
///
///  @media screen and (min-width: 400px), print and (min-width: 400px) {
///    .foo {
///      color: red;
///    }
///  }
$media: null !default;



// // https://github.com/boltdesignsystem/bolt/blob/v3.0.1/packages/core-v3.x/styles/02-tools/tools-list-remove/_tools-list-remove.scss
// @function list-remove($list, $index) {
//   $separator: list.separator($list);
//   $newList: ();
//   @for $i from 1 through list.length($list) {
//     @if $i != $index {
//       $newList: list.append($newList, list.nth($list, $i), $separator);
//     }
//   }
//   @return $newList;
// }



// // @function list-swap($list, $index-a, $index-b) {
// //   @if math.abs($index-a) > list.length($list) or
// //                math.abs($index-b) > list.length($list) {
// //     @return $list;
// //   }
// //   $temp: list.nth($list, $index-a);
// //   $list: list.set-nth($list, $index-a, list.nth($list, $index-b));
// //   $list: list.set-nth($list, $index-b, $temp);
// //   @return $list;
// // }



// // https://github.com/boltdesignsystem/bolt/blob/v3.0.1/packages/core-v3.x/styles/02-tools/tools-list-sort/_tools-list-sort.scss
// @function list-sort-numeric($list) {
//   $separator: list.separator($list);
//   $sortedlist: ();
//   @while list.length($list) > 0 {
//       $value: list.nth($list, 1);
//       @each $item in $list {
//         @if meta.type-of($item) == "number" and meta.type-of($value) == "number" {
//           @if $item < $value {
//               $value: $item;
//           }
//         } @else {
//           @error 'These values are not sortable: ' + $item + ' and ' + $value;
//         }
//       }
//       $sortedlist: list.append($sortedlist, $value, $separator);
//       $list: list-remove($list, index($list, $value));
//   }
//   @return $sortedlist;
// }



// // https://github.com/boltdesignsystem/bolt/blob/v3.0.1/packages/core-v3.x/styles/02-tools/tools-map-sort/_tools-map-sort.scss
// @function map-sort-keys($map) {
//   $keys: list-sort-numeric(map.keys($map));
//   $sorted-map: ();
//   @each $key in $keys {
//     $sorted-map: map.merge($sorted-map, ($key: map.get($map, $key)));
//   }
//   @return $sorted-map;
// }


/// Sorts a Sass map by its values. Values must be numeric.
/// @access private
/// @arg {Map} $map - a map to sort
/// @return {Map} sorted map
/// @example sass
///   map-sort-values((a: 200, b: 0))
///   // => (b: 0, a: 200)
/// @link https://github.com/iamandrewluca/map-sort-by-values/blob/8ad9fb6b4fa3eee8e8f79ddb305c6b3f8f4ad2c3/_index.scss
/// @author Andrew Luca <https://github.com/iamandrewluca>
@function map-sort-values($map) {
  // Transform map to zipped list
  $keys: ();
  $values: ();

  @each $key, $val in $map {
    $keys: list.append($keys, $key);
    $values: list.append($values, $val);
  }

  $list: list.zip($keys, $values);

  // Sort zipped list and create sorted map
  $sortedMap: ();
  @while list.length($list) > 0 {

    // Find smallest pair
    $smallestPair: list.nth($list, 1);
    @each $pair in $list {
      $value: list.nth($pair, 2);
      $smallestValue: list.nth($smallestPair, 2);
      @if $value < $smallestValue {
        $smallestPair: $pair;
      }
    }

    // Add smallest pair to sorted map
    $key: list.nth($smallestPair, 1);
    $value: list.nth($smallestPair, 2);
    $sortedMap: map.merge($sortedMap, ($key: $value));

    // Remove from list smallest pair
    $newList: ();
    $smallestPairIndex: list.index($list, $smallestPair);
    @for $i from 1 through list.length($list) {
      @if $i != $smallestPairIndex {
        $newList: list.append($newList, list.nth($list, $i), "space");
      }
    }
    $list: $newList;
  }

  @return $sortedMap;
}



/// Checks whether given value is a number with px unit.
/// @access private
/// @arg {Any} $value - a value to check
/// @return {Bool} whether the value is a number with px unit
/// @example sass
///   is-number-px(100px) // => true
///   is-number-px(100em) // => false
///   is-number-px(100) // => false
///   is-number-px('text') // => false
@function is-number-px($value) {
  @return meta.type-of($value) == 'number' and math.unit($value) == 'px';
}



/// Returns the index of given slice.
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {Number} index of the slice (1-indexed)
/// @example sass
///  index-of-slice(xl) // => 6
///  index-of-slice(large, $slices: (small: 0px, large: 600px)) // => 2
@function index-of-slice($slice, $slices: $slices) {
  $slices-sorted: map-sort-values($slices);
  $keys: map.keys($slices-sorted);
  $index: list.index($keys, $slice);

  @return $index;
}



/// Checks whether given slice is the first one in the map.
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {Bool} whether the slice is the first
/// @example sass
///   is-first-slice(xxs) // => true
///   is-first-slice(s) // => false
///   is-first-slice(small, $slices: (small: 0px, large: 600px)) // => true
@function is-first-slice($slice, $slices: $slices) {
  $index: index-of-slice($slice, $slices);

  @return $index == 1;
}



/// Checks whether given slice is the last one in the map.
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {Bool} whether the slice is the last
/// @example sass
///   is-last-slice(xxl) // => false
///   is-last-slice(xxxl) // => true
///   is-last-slice(small, $slices: (small: 0px, large: 600px)) // => false
@function is-last-slice($slice, $slices: $slices) {
  $index: index-of-slice($slice, $slices);
  $length: list.length(map.keys($slices));

  @return $index == $length;
}



/// Returns the name of the next slice
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {string | null} the name of the next slice, or null if given slice was the last
/// @example sass
///   next-slice(s) // => m
///   next-slice(xxxl) // => null
///   next-slice(small, $slices: (small: 0px, large: 600px)) // => large
@function next-slice($slice, $slices: $slices) {
  $slices-sorted: map-sort-values($slices);
  $keys: map.keys($slices-sorted);
  $index: list.index($keys, $slice);

  @if $index == null {
    @error "Slice not found", $slice;
  }

  @if ($index >= list.length($keys)) {
    @return null;
  }

  @return list.nth($keys, $index + 1);
}



/// Returns the starting (normally left) breakpoint of given slice
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {number | null} the breakpoint, or null if the slice is the first one
/// @example sass
///   start-bp-of-slice(xxs) // => null
///   start-bp-of-slice(xs) // => 200px
///   start-bp-of-slice(small, $slices: (small: 0px, large: 600px)) // => null
///   start-bp-of-slice(large, $slices: (small: 0px, large: 600px)) // => 600px
@function start-bp-of-slice($slice, $slices: $slices) {
  @if is-first-slice($slice, $slices) {
    @return null;
  }

  $bp: map.get($slices, $slice);

  @return $bp;
}



/// Returns the ending (normally right) breakpoint of given slice,
/// which is the left breakpoint of the next slice minus 1px,
/// or null if the slice is the last one.
/// @access private
/// @arg {String} $slice - a slice to look up
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @return {number | null} the breakpoint, or null if the slice is the first one
/// @example sass
///   end-bp-of-slice(l) // => 999px
///   end-bp-of-slice(xxxl) // => null
///   end-bp-of-slice(small, $slices: (small: 0px, large: 600px)) // => 599px
///   start-bp-of-slice(large, $slices: (small: 0px, large: 600px)) // => null
@function end-bp-of-slice($slice, $slices: $slices) {
  @if is-last-slice($slice, $slices) {
    @return null;
  }

  $next-slice: next-slice($slice, $slices);

  $bp: map.get($slices, $next-slice);

  @return $bp - 1;
}



/// Generates a media query for a given slice or a range of two slices
/// @access private
/// @arg {String | Null} $slice-start - a slice whose left breakpoint will be used
/// @arg {String | Null} $slice-end - a slice whose right breakpoint will be used
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @return {string} resulting media query
/// @example sass
///   query-for-slice(l) // => (min-width: 800px) and (max-width: 999px)
///   query-for-slice(null, l) // => (max-width: 999px)
///   query-for-slice(l, null) // => (min-width: 800px)
///   query-for-slice(xxxl) // => (min-width: 1400px)
///   query-for-slice(xxxl, null) // => (min-width: 1400px)
///   query-for-slice(xxs) // => (max-width: 199px)
///   query-for-slice(null, xxs) // => (max-width: 199px)
///   query-for-slice(s l) // => (min-width: 400px) and (max-width: 999px)
///   query-for-slice(small, $slices: (small: 0px, large: 600px)) // => (max-width: 999px)
///   query-for-slice(l, $media: screen) // => screen and (min-width: 800px) and (max-width: 999px)
@function query-for-slice($slice-start, $slice-end: "__undefined__", $slices: $slices, $media: $media) {
  $result: null;

  @if ($slice-end == "__undefined__") {
    $slice-end: $slice-start;
  }

  $start: $slice-start and start-bp-of-slice($slice-start, $slices);
  $end: $slice-end and end-bp-of-slice($slice-end, $slices);

  @if $start == null and $end == null {
    @error "This query spans the whole range of viewports and is redundant.";
  }

  @else if $start != null and not is-number-px($start) {
    @error "Expected left breakpoint of slice #{$slice-start} (#{$start}) to be a number with unit px.";
  }

  @else if $end != null and not is-number-px($end) {
    @error "Expected right breakpoint of slice #{$slice-end} (#{$end}) to be a number with unit px.";
  }

  @else if $start != null and $end != null {
    @if ($start >= $end) {
      @error "Expected left breakpoint of slice #{$slice-start} (#{$start}) to be smaller than right breakpoint of slice #{$slice-end} (#{$end}). Try reversing the order of slices.";
    }

    $result: "(min-width: #{$start}) and (max-width: #{$end})";
  }

  @else if $start == null {
    $result: "(max-width: #{$end})";
  }

  @else if $end == null {
    $result: "(min-width: #{$start})";
  }

  @else {
    @error "Neither left nor right breakpoint found for slices: #{$slice-start} #{$slice-end}";
  }

  @if ($media) {
    $result: "#{$media} and #{$result}";
  }

  @return $result;
}



@function _query-for-slices($query, $slices: $slices, $media: $media) {
  $result: "";

  @if list.separator($query) == "space" {
    @if list.length($query) > 2 or list.length($query) == 0 {
      @error "Inavlid usage of query-for-slices: it accepts a comma-separated list of items where each item is a number or a space-separated list of two numbers";
    }

    @return query-for-slice($query..., $slices: $slices, $media: $media)
  }

  @each $slice-or-slices in $query {
    @if string.length($result) > 0 {
      $result: "#{$result}, ";
    }

    @if list.length($slice-or-slices) == 0 or list.length($slice-or-slices) > 2 {
      @error "Inavlid usage of query-for-slices: it accepts a comma-separated list of items where each item is a number or a space-separated list of two numbers";
    }


    $result-item: query-for-slice($slice-or-slices..., $slices: $slices, $media: $media);
    $result: "#{$result}#{$result-item}";
  }

  @return $result;
}



/// Generates a media query for a given comma-separated list of slices and ranges of two slices
/// @access private
/// @arg {Map} $query - a comma-separated list of slices and ranges of two slices
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @return {string} resulting media query
/// @example sass
///   query-for-slices(l) // => (min-width: 800px) and (max-width: 999px)
///   query-for-slices((null l)) // => (max-width: 999px)
///   query-for-slices((null l), xxxl) // => (max-width: 999px), (min-width: 1400px)
///   query-for-slices((s l), xxxl) // => (min-width: 400px) and (max-width: 999px), (min-width: 1400px)
///   query-for-slices(small, $slices: (small: 0px, large: 600px)) // => (max-width: 999px)
///   query-for-slices(l, $media: screen) // => screen and (min-width: 800px) and (max-width: 999px)
@function query-for-slices($query, $slices: $slices, $media: $media) {
  @if $media and list.separator($media) == "comma" and list.length($media) > 1 {
    $result: "";

    @each $medium in $media {
      @if string.length($result) > 0 {
        $result: "#{$result}, ";
      }

      $result-item: _query-for-slices($query, $slices: $slices, $media: $medium);
      $result: "#{$result}#{$result-item}";
    }

    @return $result;
  }

  @else {
    @return _query-for-slices($query, $slices: $slices, $media: $media);
  }
}


/// Wraps CSS code with a media query confined by a given slice
/// @access public
/// @arg {String} $slice - name of slice
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @content Any CSS to wrap with a media query. Note: requires a selector either inside or outside of the mixin invocation.
/// @output CSS wrapped in a media query
/// @example scss
///   .foo {
///     @include at(s) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media (min-width: 400px) and (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
/// @example scss
///   .foo {
///     @include at(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media screen and (min-width: 300px) and (max-width: 599px), print and (min-width: 300px) and (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
@mixin at($slice, $slices: $slices, $media: $media) {
  $media: query-for-slices($slice, $slices: $slices, $media: $media);

  @media #{$media} {
    @content;
  }
}


/// Wraps CSS code with a media query confined by a given slice and larger
/// @access public
/// @arg {String} $slice - name of slice
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @content Any CSS to wrap with a media query. Note: requires a selector either inside or outside of the mixin invocation.
/// @output CSS wrapped in a media query
/// @example scss
///   .foo {
///     @include from(s) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media (min-width: 400px) {
///     .foo {
///       color: red;
///     }
///   }
/// @example scss
///   .foo {
///     @include from(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media screen and (min-width: 300px), print and (min-width: 300px) {
///     .foo {
///       color: red;
///     }
///   }
@mixin from($slice, $slices: $slices, $media: $media) {
  $media: query-for-slices(($slice null), $slices: $slices, $media: $media);

  @media #{$media} {
    @content;
  }
}


/// Wraps CSS code with a media query confined by a given slice and smaller
/// @access public
/// @arg {String} $slice - name of slice
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @content Any CSS to wrap with a media query. Note: requires a selector either inside or outside of the mixin invocation.
/// @output CSS wrapped in a media query
/// @example scss
///   .foo {
///     @include to(s) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
/// @example scss
///   .foo {
///     @include to(medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media screen and (max-width: 599px), print and (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
@mixin to($slice, $slices: $slices, $media: $media) {
  $media: query-for-slices((null $slice), $slices: $slices, $media: $media);

  @media #{$media} {
    @content;
  }
}


/// Wraps CSS code with a media query confined within two slices
/// @access public
/// @arg {String} $slice-start - name of starting slice
/// @arg {String} $slice-end - name of ending slice, inclusive
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @content Any CSS to wrap with a media query. Note: requires a selector either inside or outside of the mixin invocation.
/// @output CSS wrapped in a media query
/// @example scss
///   .foo {
///     @include between(s, l) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media (min-width: 400px) and (max-width: 999px) {
///     .foo {
///       color: red;
///     }
///   }
/// @example scss
///   .foo {
///     @include between(small, medium, $slices: (small: 0px, medium: 300px, large: 600px), $media: (screen, print)) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media screen and (max-width: 599px), print and (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
@mixin between($slice-start, $slice-end, $slices: $slices, $media: $media) {
  $media: query-for-slices(($slice-start $slice-end), $slices: $slices, $media: $media);

  @media #{$media} {
    @content;
  }
}


/// Wraps CSS code with a compound media query, using flexible syntax
/// @access public
/// @arg {Map} $query - a comma-separated list of slices and ranges of two slices
/// @arg {Map} $slices [globally defined $slices] - a map of slices to work with
/// @arg {Map | null} $media [globally defined $media] - a media query to prend the result with
/// @content Any CSS to wrap with a media query. Note: requires a selector either inside or outside of the mixin invocation.
/// @output CSS wrapped in a media query
/// @example scss
///   .foo {
///     @include query((s l), xxxl) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media (min-width: 400px) and (max-width: 999px), (min-width: 1400px) {
///     .foo {
///       color: red;
///     }
///   }
/// @example scss
///   .foo {
///     @include query(small, $slices: (small: 0px, large: 600px), $media: (screen, print)) {
///       color: red;
///     }
///   }
///
///   // produces:
///
///   @media screen and (max-width: 599px), print and (max-width: 599px) {
///     .foo {
///       color: red;
///     }
///   }
@mixin query($query, $slices: $slices, $media: $media) {
  $media: query-for-slices($query, $slices: $slices, $media: $media);

  @media #{$media} {
    @content;
  }
}