_scss/_include-media.scss

   1 @charset 'UTF-8';
   2
   3 //     _            _           _                           _ _
   4 //    (_)          | |         | |                         | (_)
   5 //     _ _ __   ___| |_   _  __| | ___   _ __ ___   ___  __| |_  __ _
   6 //    | | '_ \ / __| | | | |/ _` |/ _ \ | '_ ` _ \ / _ \/ _` | |/ _` |
   7 //    | | | | | (__| | |_| | (_| |  __/ | | | | | |  __/ (_| | | (_| |
   8 //    |_|_| |_|\___|_|\__,_|\__,_|\___| |_| |_| |_|\___|\__,_|_|\__,_|
   9 //
  10 //      Simple, elegant and maintainable media queries in Sass
  11 //                        v1.4.2
  12 //
  13 //                http://include-media.com
  14 //
  15 //         Authors: Eduardo Boucas (@eduardoboucas)
  16 //                  Hugo Giraudel (@hugogiraudel)
  17 //
  18 //      This project is licensed under the terms of the MIT license
  19
  20
  21 ////
  22 /// include-media library public configuration
  23 /// @author Eduardo Boucas
  24 /// @access public
  25 ////
  26
  27
  28 ///
  29 /// Creates a list of global breakpoints
  30 ///
  31 /// @example scss - Creates a single breakpoint with the label `phone`
  32 ///  $breakpoints: ('phone': 320px);
  33 ///
  34 $breakpoints: (
  35   'phone': 320px,
  36   'tablet': 768px,
  37   'desktop': 1024px
  38 ) !default;
  39
  40
  41 ///
  42 /// Creates a list of static expressions or media types
  43 ///
  44 /// @example scss - Creates a single media type (screen)
  45 ///  $media-expressions: ('screen': 'screen');
  46 ///
  47 /// @example scss - Creates a static expression with logical disjunction (OR operator)
  48 ///  $media-expressions: (
  49 ///    'retina2x': '(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)'
  50 ///  );
  51 ///
  52 $media-expressions: (
  53   'all': 'all',
  54   'screen': 'screen',
  55   'print': 'print',
  56   'handheld': 'handheld',
  57   'landscape': '(orientation: landscape)',
  58   'portrait': '(orientation: portrait)',
  59   'retina2x': '(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi)',
  60   'retina3x': '(-webkit-min-device-pixel-ratio: 3), (min-resolution: 350dpi)'
  61 ) !default;
  62
  63
  64 ///
  65 /// Defines a number to be added or subtracted from each unit when declaring breakpoints with exclusive intervals
  66 ///
  67 /// @example scss - Interval for pixels is defined as `1` by default
  68 ///  @include media('>128px') {}
  69 ///
  70 ///  /* Generates: */
  71 ///  @media (min-width: 129px) {}
  72 ///
  73 /// @example scss - Interval for ems is defined as `0.01` by default
  74 ///  @include media('>20em') {}
  75 ///
  76 ///  /* Generates: */
  77 ///  @media (min-width: 20.01em) {}
  78 ///
  79 /// @example scss - Interval for rems is defined as `0.1` by default, to be used with `font-size: 62.5%;`
  80 ///  @include media('>2.0rem') {}
  81 ///
  82 ///  /* Generates: */
  83 ///  @media (min-width: 2.1rem) {}
  84 ///
  85 $unit-intervals: (
  86   'px': 1,
  87   'em': 0.01,
  88   'rem': 0.1
  89 ) !default;
  90
  91 ///
  92 /// Defines whether support for media queries is available, useful for creating separate stylesheets
  93 /// for browsers that don't support media queries.
  94 ///
  95 /// @example scss - Disables support for media queries
  96 ///  $im-media-support: false;
  97 ///  @include media('>=tablet') {
  98 ///    .foo {
  99 ///      color: tomato;
 100 ///    }
 101 ///  }
 102 ///
 103 ///  /* Generates: */
 104 ///  .foo {
 105 ///    color: tomato;
 106 ///  }
 107 ///
 108 $im-media-support: true !default;
 109
 110 ///
 111 /// Selects which breakpoint to emulate when support for media queries is disabled. Media queries that start at or
 112 /// intercept the breakpoint will be displayed, any others will be ignored.
 113 ///
 114 /// @example scss - This media query will show because it intercepts the static breakpoint
 115 ///  $im-media-support: false;
 116 ///  $im-no-media-breakpoint: 'desktop';
 117 ///  @include media('>=tablet') {
 118 ///    .foo {
 119 ///      color: tomato;
 120 ///    }
 121 ///  }
 122 ///
 123 ///  /* Generates: */
 124 ///  .foo {
 125 ///    color: tomato;
 126 ///  }
 127 ///
 128 /// @example scss - This media query will NOT show because it does not intercept the desktop breakpoint
 129 ///  $im-media-support: false;
 130 ///  $im-no-media-breakpoint: 'tablet';
 131 ///  @include media('>=desktop') {
 132 ///    .foo {
 133 ///      color: tomato;
 134 ///    }
 135 ///  }
 136 ///
 137 ///  /* No output */
 138 ///
 139 $im-no-media-breakpoint: 'desktop' !default;
 140
 141 ///
 142 /// Selects which media expressions are allowed in an expression for it to be used when media queries
 143 /// are not supported.
 144 ///
 145 /// @example scss - This media query will show because it intercepts the static breakpoint and contains only accepted media expressions
 146 ///  $im-media-support: false;
 147 ///  $im-no-media-breakpoint: 'desktop';
 148 ///  $im-no-media-expressions: ('screen');
 149 ///  @include media('>=tablet', 'screen') {
 150 ///    .foo {
 151 ///      color: tomato;
 152 ///    }
 153 ///  }
 154 ///
 155 ///   /* Generates: */
 156 ///   .foo {
 157 ///     color: tomato;
 158 ///   }
 159 ///
 160 /// @example scss - This media query will NOT show because it intercepts the static breakpoint but contains a media expression that is not accepted
 161 ///  $im-media-support: false;
 162 ///  $im-no-media-breakpoint: 'desktop';
 163 ///  $im-no-media-expressions: ('screen');
 164 ///  @include media('>=tablet', 'retina2x') {
 165 ///    .foo {
 166 ///      color: tomato;
 167 ///    }
 168 ///  }
 169 ///
 170 ///  /* No output */
 171 ///
 172 $im-no-media-expressions: ('screen', 'portrait', 'landscape') !default;
 173
 174 ////
 175 /// Cross-engine logging engine
 176 /// @author Hugo Giraudel
 177 /// @access private
 178 ////
 179
 180
 181 ///
 182 /// Log a message either with `@error` if supported
 183 /// else with `@warn`, using `feature-exists('at-error')`
 184 /// to detect support.
 185 ///
 186 /// @param {String} $message - Message to log
 187 ///
 188 @function log($message) {
 189   @if feature-exists('at-error') {
 190     @error $message;
 191   } @else {
 192     @warn $message;
 193     $_: noop();
 194   }
 195
 196   @return $message;
 197 }
 198
 199
 200 ///
 201 /// Wrapper mixin for the log function so it can be used with a more friendly
 202 /// API than `@if log('..') {}` or `$_: log('..')`. Basically, use the function
 203 /// within functions because it is not possible to include a mixin in a function
 204 /// and use the mixin everywhere else because it's much more elegant.
 205 ///
 206 /// @param {String} $message - Message to log
 207 ///
 208 @mixin log($message) {
 209   @if log($message) {}
 210 }
 211
 212
 213 ///
 214 /// Function with no `@return` called next to `@warn` in Sass 3.3
 215 /// to trigger a compiling error and stop the process.
 216 ///
 217 @function noop() {}
 218
 219 ///
 220 /// Determines whether a list of conditions is intercepted by the static breakpoint.
 221 ///
 222 /// @param {Arglist}   $conditions  - Media query conditions
 223 ///
 224 /// @return {Boolean} - Returns true if the conditions are intercepted by the static breakpoint
 225 ///
 226 @function im-intercepts-static-breakpoint($conditions...) {
 227   $no-media-breakpoint-value: map-get($breakpoints, $im-no-media-breakpoint);
 228
 229   @if not $no-media-breakpoint-value {
 230     @if log('`#{$im-no-media-breakpoint}` is not a valid breakpoint.') {}
 231   }
 232
 233   @each $condition in $conditions {
 234     @if not map-has-key($media-expressions, $condition) {
 235       $operator: get-expression-operator($condition);
 236       $prefix: get-expression-prefix($operator);
 237       $value: get-expression-value($condition, $operator);
 238
 239       // scss-lint:disable SpaceAroundOperator
 240       @if ($prefix == 'max' and $value <= $no-media-breakpoint-value) or
 241           ($prefix == 'min' and $value > $no-media-breakpoint-value) {
 242         @return false;
 243       }
 244     } @else if not index($im-no-media-expressions, $condition) {
 245       @return false;
 246     }
 247   }
 248
 249   @return true;
 250 }
 251
 252 ////
 253 /// Parsing engine
 254 /// @author Hugo Giraudel
 255 /// @access private
 256 ////
 257
 258
 259 ///
 260 /// Get operator of an expression
 261 ///
 262 /// @param {String} $expression - Expression to extract operator from
 263 ///
 264 /// @return {String} - Any of `>=`, `>`, `<=`, `<`, `≥`, `≤`
 265 ///
 266 @function get-expression-operator($expression) {
 267   @each $operator in ('>=', '>', '<=', '<', '≥', '≤') {
 268     @if str-index($expression, $operator) {
 269       @return $operator;
 270     }
 271   }
 272
 273   // It is not possible to include a mixin inside a function, so we have to
 274   // rely on the `log(..)` function rather than the `log(..)` mixin. Because
 275   // functions cannot be called anywhere in Sass, we need to hack the call in
 276   // a dummy variable, such as `$_`. If anybody ever raise a scoping issue with
 277   // Sass 3.3, change this line in `@if log(..) {}` instead.
 278   $_: log('No operator found in `#{$expression}`.');
 279 }
 280
 281
 282 ///
 283 /// Get dimension of an expression, based on a found operator
 284 ///
 285 /// @param {String} $expression - Expression to extract dimension from
 286 /// @param {String} $operator - Operator from `$expression`
 287 ///
 288 /// @return {String} - `width` or `height` (or potentially anything else)
 289 ///
 290 @function get-expression-dimension($expression, $operator) {
 291   $operator-index: str-index($expression, $operator);
 292   $parsed-dimension: str-slice($expression, 0, $operator-index - 1);
 293   $dimension: 'width';
 294
 295   @if str-length($parsed-dimension) > 0 {
 296     $dimension: $parsed-dimension;
 297   }
 298
 299   @return $dimension;
 300 }
 301
 302
 303 ///
 304 /// Get dimension prefix based on an operator
 305 ///
 306 /// @param {String} $operator - Operator
 307 ///
 308 /// @return {String} - `min` or `max`
 309 ///
 310 @function get-expression-prefix($operator) {
 311   @return if(index(('<', '<=', '≤'), $operator), 'max', 'min');
 312 }
 313
 314
 315 ///
 316 /// Get value of an expression, based on a found operator
 317 ///
 318 /// @param {String} $expression - Expression to extract value from
 319 /// @param {String} $operator - Operator from `$expression`
 320 ///
 321 /// @return {Number} - A numeric value
 322 ///
 323 @function get-expression-value($expression, $operator) {
 324   $operator-index: str-index($expression, $operator);
 325   $value: str-slice($expression, $operator-index + str-length($operator));
 326
 327   @if map-has-key($breakpoints, $value) {
 328     $value: map-get($breakpoints, $value);
 329   } @else {
 330     $value: to-number($value);
 331   }
 332
 333   $interval: map-get($unit-intervals, unit($value));
 334
 335   @if not $interval {
 336     // It is not possible to include a mixin inside a function, so we have to
 337     // rely on the `log(..)` function rather than the `log(..)` mixin. Because
 338     // functions cannot be called anywhere in Sass, we need to hack the call in
 339     // a dummy variable, such as `$_`. If anybody ever raise a scoping issue with
 340     // Sass 3.3, change this line in `@if log(..) {}` instead.
 341     $_: log('Unknown unit `#{unit($value)}`.');
 342   }
 343
 344   @if $operator == '>' {
 345     $value: $value + $interval;
 346   } @else if $operator == '<' {
 347     $value: $value - $interval;
 348   }
 349
 350   @return $value;
 351 }
 352
 353
 354 ///
 355 /// Parse an expression to return a valid media-query expression
 356 ///
 357 /// @param {String} $expression - Expression to parse
 358 ///
 359 /// @return {String} - Valid media query
 360 ///
 361 @function parse-expression($expression) {
 362   // If it is part of $media-expressions, it has no operator
 363   // then there is no need to go any further, just return the value
 364   @if map-has-key($media-expressions, $expression) {
 365     @return map-get($media-expressions, $expression);
 366   }
 367
 368   $operator: get-expression-operator($expression);
 369   $dimension: get-expression-dimension($expression, $operator);
 370   $prefix: get-expression-prefix($operator);
 371   $value: get-expression-value($expression, $operator);
 372
 373   @return '(#{$prefix}-#{$dimension}: #{$value})';
 374 }
 375
 376 ///
 377 /// Slice `$list` between `$start` and `$end` indexes
 378 ///
 379 /// @access private
 380 ///
 381 /// @param {List} $list - List to slice
 382 /// @param {Number} $start [1] - Start index
 383 /// @param {Number} $end [length($list)] - End index
 384 ///
 385 /// @return {List} Sliced list
 386 ///
 387 @function slice($list, $start: 1, $end: length($list)) {
 388   @if length($list) < 1 or $start > $end {
 389     @return ();
 390   }
 391
 392   $result: ();
 393
 394   @for $i from $start through $end {
 395     $result: append($result, nth($list, $i));
 396   }
 397
 398   @return $result;
 399 }
 400
 401 ////
 402 /// String to number converter
 403 /// @author Hugo Giraudel
 404 /// @access private
 405 ////
 406
 407
 408 ///
 409 /// Casts a string into a number
 410 ///
 411 /// @param {String | Number} $value - Value to be parsed
 412 ///
 413 /// @return {Number}
 414 ///
 415 @function to-number($value) {
 416   @if type-of($value) == 'number' {
 417     @return $value;
 418   } @else if type-of($value) != 'string' {
 419     $_: log('Value for `to-number` should be a number or a string.');
 420   }
 421
 422   $result: 0;
 423   $digits: 0;
 424   $minus: str-slice($value, 1, 1) == '-';
 425   $numbers: ('0': 0, '1': 1, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9);
 426
 427   @for $i from if($minus, 2, 1) through str-length($value) {
 428     $character: str-slice($value, $i, $i);
 429
 430     @if not (index(map-keys($numbers), $character) or $character == '.') {
 431       @return to-length(if($minus, -$result, $result), str-slice($value, $i))
 432     }
 433
 434     @if $character == '.' {
 435       $digits: 1;
 436     } @else if $digits == 0 {
 437       $result: $result * 10 + map-get($numbers, $character);
 438     } @else {
 439       $digits: $digits * 10;
 440       $result: $result + map-get($numbers, $character) / $digits;
 441     }
 442   }
 443
 444   @return if($minus, -$result, $result);
 445 }
 446
 447
 448 ///
 449 /// Add `$unit` to `$value`
 450 ///
 451 /// @param {Number} $value - Value to add unit to
 452 /// @param {String} $unit - String representation of the unit
 453 ///
 454 /// @return {Number} - `$value` expressed in `$unit`
 455 ///
 456 @function to-length($value, $unit) {
 457   $units: ('px': 1px, 'cm': 1cm, 'mm': 1mm, '%': 1%, 'ch': 1ch, 'pc': 1pc, 'in': 1in, 'em': 1em, 'rem': 1rem, 'pt': 1pt, 'ex': 1ex, 'vw': 1vw, 'vh': 1vh, 'vmin': 1vmin, 'vmax': 1vmax);
 458
 459   @if not index(map-keys($units), $unit) {
 460     $_: log('Invalid unit `#{$unit}`.');
 461   }
 462
 463   @return $value * map-get($units, $unit);
 464 }
 465
 466 ///
 467 /// This mixin aims at redefining the configuration just for the scope of
 468 /// the call. It is helpful when having a component needing an extended
 469 /// configuration such as custom breakpoints (referred to as tweakpoints)
 470 /// for instance.
 471 ///
 472 /// @author Hugo Giraudel
 473 ///
 474 /// @param {Map} $tweakpoints [()] - Map of tweakpoints to be merged with `$breakpoints`
 475 /// @param {Map} $tweak-media-expressions [()] - Map of tweaked media expressions to be merged with `$media-expression`
 476 ///
 477 /// @example scss - Extend the global breakpoints with a tweakpoint
 478 ///  @include media-context(('custom': 678px)) {
 479 ///    .foo {
 480 ///      @include media('>phone', '<=custom') {
 481 ///       // ...
 482 ///      }
 483 ///    }
 484 ///  }
 485 ///
 486 /// @example scss - Extend the global media expressions with a custom one
 487 ///  @include media-context($tweak-media-expressions: ('all': 'all')) {
 488 ///    .foo {
 489 ///      @include media('all', '>phone') {
 490 ///       // ...
 491 ///      }
 492 ///    }
 493 ///  }
 494 ///
 495 /// @example scss - Extend both configuration maps
 496 ///  @include media-context(('custom': 678px), ('all': 'all')) {
 497 ///    .foo {
 498 ///      @include media('all', '>phone', '<=custom') {
 499 ///       // ...
 500 ///      }
 501 ///    }
 502 ///  }
 503 ///
 504 @mixin media-context($tweakpoints: (), $tweak-media-expressions: ()) {
 505   // Save global configuration
 506   $global-breakpoints: $breakpoints;
 507   $global-media-expressions: $media-expressions;
 508
 509   // Update global configuration
 510   $breakpoints: map-merge($breakpoints, $tweakpoints) !global;
 511   $media-expressions: map-merge($media-expressions, $tweak-media-expressions) !global;
 512
 513   @content;
 514
 515   // Restore global configuration
 516   $breakpoints: $global-breakpoints !global;
 517   $media-expressions: $global-media-expressions !global;
 518 }
 519
 520 ////
 521 /// include-media public exposed API
 522 /// @author Eduardo Boucas
 523 /// @access public
 524 ////
 525
 526
 527 ///
 528 /// Generates a media query based on a list of conditions
 529 ///
 530 /// @param {Arglist}   $conditions  - Media query conditions
 531 ///
 532 /// @example scss - With a single set breakpoint
 533 ///  @include media('>phone') { }
 534 ///
 535 /// @example scss - With two set breakpoints
 536 ///  @include media('>phone', '<=tablet') { }
 537 ///
 538 /// @example scss - With custom values
 539 ///  @include media('>=358px', '<850px') { }
 540 ///
 541 /// @example scss - With set breakpoints with custom values
 542 ///  @include media('>desktop', '<=1350px') { }
 543 ///
 544 /// @example scss - With a static expression
 545 ///  @include media('retina2x') { }
 546 ///
 547 /// @example scss - Mixing everything
 548 ///  @include media('>=350px', '<tablet', 'retina3x') { }
 549 ///
 550 @mixin media($conditions...) {
 551   // scss-lint:disable SpaceAroundOperator
 552   @if ($im-media-support and length($conditions) == 0) or
 553       (not $im-media-support and im-intercepts-static-breakpoint($conditions...)) {
 554     @content;
 555   } @else if ($im-media-support and length($conditions) > 0) {
 556     @media #{unquote(parse-expression(nth($conditions, 1)))} {
 557       // Recursive call
 558       @include media(slice($conditions, 2)...) {
 559         @content;
 560       }
 561     }
 562   }
 563 }