_mq.scss

@use 'sass:math';
@use 'sass:map';
@use 'sass:list';

/// Breakpoint list
///
/// Name your breakpoints in a way that creates a ubiquitous language
/// across team members. It will improve communication between
/// stakeholders, designers, developers, and testers.
///
/// @type Map
/// @link https://github.com/mcaskill/sass-mq#seeing-the-currently-active-breakpoint Full documentation and examples
$breakpoints: (
  mobile: 320px,
  tablet: 740px,
  desktop: 980px,
  wide: 1300px,
) !default;

/// Show breakpoints in the top right corner
///
/// If you want to display the currently active breakpoint in the top
/// right corner of your site during development, add the breakpoints
/// to this list, ordered by length. For example: (mobile, tablet, desktop).
///
/// @example scss
///   @use 'path/to/mq' with ($show-breakpoints: ('mobile', 'tablet', 'desktop'));
///
///
/// @type map
$show-breakpoints: () !default;

/// Customize the media range feature (for example: `@media (min-width…)`
/// or `@media (min-height:…)`)
/// By default sass-mq uses an `width` range feature.
///
/// If you want to overried the range feature, you can use this option.
/// @example scss
///   @use 'path/to/mq' with ($range-feature: height);
///
/// @type String
/// @link https://github.com/mcaskill/sass-mq#changing-range-feature Full documentation and example
$range-feature: width !default;

/// Customize the media type (for example: `@media screen` or `@media print`)
/// By default sass-mq uses an "all" media type (`@media all and …`)
///
/// If you want to overried the media type, you can use this option.
/// @example scss
///   @use 'path/to/mq' with ($media-type: 'screen');
///
/// @type String
/// @link https://github.com/mcaskill/sass-mq#changing-media-type Full documentation and example
$media-type: all !default;

/// Convert pixels to ems
///
/// @param {Number} $px - value to convert
///
/// @example scss
///  $font-size-in-ems: px2em(16px);
///  p { font-size: px2em(16px); }
///
/// @returns {Number}
@function px2em($px) {
  @if math.is-unitless($px) {
    @warn "Assuming #{$px} to be in pixels, attempting to convert it into pixels.";
    @return px2em($px * 1px);
  }
  // if $px is compatible with em units, then return value unchanged
  @if math.compatible($px, 1em) {
    @return $px;
  }
  @return math.div($px, 16px) * 1em;
}

/// Get a breakpoint's length
///
/// @param {String} $name - Name of the breakpoint. One of $breakpoints
///
/// @example scss
///  $tablet-width: get-breakpoint-length(tablet);
///  @media (min-width: get-breakpoint-length(tablet)) {}
///
/// @requires {Variable} $breakpoints
///
/// @returns {Number} Value in pixels
@function get-breakpoint-length($name, $breakpoints: $breakpoints) {
  @if map.has-key($breakpoints, $name) {
    @return map.get($breakpoints, $name);
  } @else {
    @warn "Breakpoint #{$name} wasn't found in $breakpoints.";
    @return null;
  }
}

/// Joins all elements of `$list` with `$glue`.
///
/// @ignore Documentation: https://github.com/at-import/SassyLists/blob/master/stylesheets/functions/_to-string.scss
///
/// @param {List} $list - list to cast
/// @param {String} $glue [' and '] - value to use as a join string
///
/// @example scss
///  stringify(a b c)
///  // a and b and c
///
/// @example scss
///  stringify(a b c, ', ')
///  // a, b, c
///
/// @returns {String}
@function stringify($list, $glue: ' and ') {
  $result: '';

  @each $item in $list {
    $result: $result + if(length($item) > 1, stringify($item, $glue), $item);

    @if $item != nth($list, -1) {
      $result: $result + $glue;
    }
  }

  @return quote($result);
}

/// Media Query function
///
/// Computes a media query based on a list of conditions.
///
/// @param {String | Boolean} $from [false] - One of $breakpoints
/// @param {String | Boolean} $until [false] - One of $breakpoints
/// @param {String | Boolean} $and [false] - Additional media query parameters
/// @param {String | Boolean} $or [false] - Alternative media query parameters
/// @param {String} $range-feature [$range-feature] - Media range feature: width, height…
/// @param {String} $media-type [$media-type] - Media type: screen, print…
///
/// @ignore Undocumented API, for advanced use only:
/// @ignore @param {Map} $breakpoints [$breakpoints]
///
/// @requires {Variable} $range-feature
/// @requires {Variable} $media-type
/// @requires {Variable} $breakpoints
/// @requires {function} stringify
///
/// @example scss
///  $mq-lap-and-up: mq($from: mobile);
///
///  $mq-palm: mq($until: tablet);
///
///  $mq-lap: mq(mobile, tablet);
///
///  $mq-portable: mq($from: tablet, $and: '(orientation: landscape)');
///
///  $mq-desk-small: mq(950px) {
///
///  $mq-portable-screen: mq(tablet, $media-type: screen) {
///
///  // Advanced use:
///  $my-breakpoints: (L: 900px, XL: 1200px);
///  $mq-custom: mq(L, $breakpoints: $my-breakpoints);
@function mq(
  $from: false,
  $until: false,
  $and: false,
  $or: false,
  $range-feature: $range-feature,
  $media-type: $media-type,
  $breakpoints: $breakpoints
) {
  $min-value: 0;
  $max-value: 0;
  $media-query: ();

  // From: this breakpoint (inclusive)
  @if $from {
    @if type-of($from) == number {
      $min-value: px2em($from);
    } @else {
      $min-value: px2em(get-breakpoint-length($from, $breakpoints));
    }
  }

  // Until: that breakpoint (exclusive)
  @if $until {
    @if type-of($until) == number {
      $max-value: px2em($until);
    } @else {
      $max-value: px2em(get-breakpoint-length($until, $breakpoints)) - 0.01em;
    }
  }

  @if $range-feature {
    @if $min-value != 0 {
      $media-query: append($media-query, '(min-#{$range-feature}: #{$min-value})');
    }
    @if $max-value != 0 {
      $media-query: append($media-query, '(max-#{$range-feature}: #{$max-value})');
    }
  }

  @if $and {
    $media-query: append($media-query, '#{$and}');
  }

  $media-query: stringify($media-query, ' and ');

  // Prevent unnecessary media query prefix 'all and '
  @if ($media-type != 'all' and $media-query != '') {
    $media-query: '#{$media-type} and #{$media-query}';
  }
  @else if $media-query == '' {
    $media-query: $media-type;
  }

  @if $or {
    $media-query: append($media-query, '#{$or}');
    $media-query: stringify($media-query, ', ');
  }

  $media-query: unquote("#{$media-query}");

  @return $media-query;
}

/// Media Query mixin
///
/// Generates a media query block, based on a list of conditions, around a set
/// of nested CSS statements.
///
/// @param {String | Boolean} $from [false] - One of $breakpoints
/// @param {String | Boolean} $until [false] - One of $breakpoints
/// @param {String | Boolean} $and [false] - Additional media query parameters
/// @param {String | Boolean} $or [false] - Alternative media query parameters
/// @param {String} $range-feature [$range-feature] - Media range feature: width, height…
/// @param {String} $media-type [$media-type] - Media type: screen, print…
///
/// @ignore Undocumented API, for advanced use only:
/// @ignore @param {Map} $breakpoints [$breakpoints]
///
/// @content styling rules, wrapped into a @media query
///
/// @requires {Variable} $range-feature
/// @requires {Variable} $media-type
/// @requires {Variable} $breakpoints
/// @requires {function} mq
///
/// @link https://github.com/mcaskill/sass-mq#responsive-mode Full documentation and examples
///
/// @example scss
///  @use 'path/to/mq' as *;
///  .element {
///    @include mq($from: mobile) {
///      color: red;
///    }
///    @include mq($until: tablet) {
///      color: blue;
///    }
///    @include mq(mobile, tablet) {
///      color: green;
///    }
///    @include mq($from: tablet, $and: '(orientation: landscape)') {
///      color: teal;
///    }
///    @include mq(950px) {
///      color: hotpink;
///    }
///    @include mq(tablet, $media-type: screen) {
///      color: hotpink;
///    }
///    // Advanced use:
///    $my-breakpoints: (L: 900px, XL: 1200px);
///    @include mq(L, $breakpoints: $my-breakpoints) {
///      color: hotpink;
///    }
///  }
@mixin mq(
  $from: false,
  $until: false,
  $and: false,
  $or: false,
  $range-feature: $range-feature,
  $media-type: $media-type,
  $breakpoints: $breakpoints
) {
  $media-query: mq(
    $from,
    $until,
    $and,
    $or,
    $range-feature,
    $media-type,
    $breakpoints
  );

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

/// Quick sort
///
/// @author Sam Richards
/// @access private
/// @param {List} $list - List to sort
/// @returns {List} Sorted List
@function _quick-sort($list) {
  $less: ();
  $equal: ();
  $large: ();

  @if length($list) > 1 {
    $seed: list.nth($list, math.ceil(math.div(length($list), 2)));

    @each $item in $list {
      @if ($item == $seed) {
        $equal: list.append($equal, $item);
      } @else if ($item < $seed) {
        $less: list.append($less, $item);
      } @else if ($item > $seed) {
        $large: list.append($large, $item);
      }
    }

    @return join(join(_quick-sort($less), $equal), _quick-sort($large));
  }

  @return $list;
}

/// Sort a map by values (works with numbers only)
///
/// @access private
/// @param {Map} $map - Map to sort
/// @returns {Map} Map sorted by value
@function _map-sort-by-value($map) {
  $map-sorted: ();
  $map-keys: map.keys($map);
  $map-values: map.values($map);
  $map-values-sorted: _quick-sort($map-values);

  // Reorder key/value pairs based on key values
  @each $value in $map-values-sorted {
    $index: index($map-values, $value);
    $key: list.nth($map-keys, $index);
    $map-sorted: map.merge(
      $map-sorted,
      (
        $key: $value,
      )
    );

    // Unset the value in $map-values to prevent the loop
    // from finding the same index twice
    $map-values: list.set-nth($map-values, $index, 0);
  }

  @return $map-sorted;
}

/// Add a breakpoint
///
/// @param {String} $name - Name of the breakpoint
/// @param {Number} $length - Length of the breakpoint
///
/// @requires {Variable} $breakpoints
///
/// @example scss
///  @include add-breakpoint(tvscreen, 1920px);
///  @include mq(tvscreen) {}
@mixin add-breakpoint($name, $length) {
  $new-breakpoint: (
    $name: $length,
  );
  $breakpoints: map.merge($breakpoints, $new-breakpoint) !global;
  $breakpoints: _map-sort-by-value($breakpoints) !global;
}

/// Show the active breakpoint in the top right corner of the viewport
/// @link https://github.com/mcaskill/sass-mq#seeing-the-currently-active-breakpoint
///
/// @param {List} $show-breakpoints [$show-breakpoints] - List of breakpoints to show in the top right corner
/// @param {Map} $breakpoints [$breakpoints] - Breakpoint names and sizes
///
/// @requires {Variable} $breakpoints
/// @requires {Variable} $show-breakpoints
///
/// @example scss
///  // Show breakpoints using global settings
///  @include show-breakpoints;
///
///  // Show breakpoints using custom settings
///  @include show-breakpoints((L, XL), (S: 300px, L: 800px, XL: 1200px));
@mixin show-breakpoints(
  $show-breakpoints: $show-breakpoints,
  $breakpoints: $breakpoints
) {
  body:before {
    background-color: #fcf8e3;
    border-bottom: 1px solid #fbeed5;
    border-left: 1px solid #fbeed5;
    color: #c09853;
    font: small-caption;
    padding: 3px 6px;
    pointer-events: none;
    position: fixed;
    right: 0;
    top: 0;
    z-index: 100;

    // Loop through the breakpoints that should be shown
    @each $show-breakpoint in $show-breakpoints {
      $length: get-breakpoint-length($show-breakpoint, $breakpoints);
      @include mq($show-breakpoint, $breakpoints: $breakpoints) {
        content: '#{$show-breakpoint} ≥ #{$length} (#{px2em($length)})';
      }
    }
  }
}

@if list.length($show-breakpoints) > 0 {
  @include show-breakpoints;
}