Source: breakpoints.scss

  1. /**
  2.  * @namespace Breakpoints
  3.  */
  7. @use 'sass:meta';
  8. @use 'sass:list';
  9. @use 'sass:map';
  11. @use 'globals' as *;
  12. @use 'util';
  16. $jig---auto-breakpoint: list.nth(map.keys($jig---breakpoint-config), 1);
  20. /**
  21.  * @namespace Breakpoints:get-auto-breakpoint
  22.  */
  24. /**
  25.  * Returns the current auto breakpoint value.
  26.  *
  27.  * @memberof Breakpoints:get-auto-breakpoint
  28.  * @function
  29.  * @name get-auto-breakpoint
  30.  * @alias get-auto-breakpoint
  31.  *
  32.  * @returns {String} the name of the current named auto breakpoint
  33.  *
  34.  * @see set-auto-breakpoint
  35.  * @see reset-auto-breakpoint
  36.  *
  37.  * @example
  38.  * get-auto-breakpoint()
  39.  *   => 'medium'
  40.  */
  41. @function get-auto-breakpoint(){
  42. 	@return $jig---auto-breakpoint;
  43. }
  47. /**
  48.  * @namespace Breakpoints:set-auto-breakpoint
  49.  */
  51. /**
  52.  * Sets the auto breakpoint to a named breakpoint value.
  53.  * Hint: in Sass we do _not_ have to do this manually, if we want to use auto breakpoint values,
  54.  * since blocks are always evaluated _after_ the block mixin around the block, which results
  55.  * in the block knowing the breakpoint value automatically from the mixin around it.
  56.  *
  57.  * @memberof Breakpoints:set-auto-breakpoint
  58.  * @function
  59.  * @name set-auto-breakpoint
  60.  * @alias set-auto-breakpoint
  61.  *
  62.  * @param {String} $breakpoint - a named breakpoint defined in the jig config
  63.  * @throws error if breakpoint is unknown
  64.  *
  65.  * @see reset-auto-breakpoint
  67.  * @example
  68.  * \@include set-auto-breakpoint(medium);
  69.  * \@include breakpoint(medium){
  70.  *   ...
  71.  * }
  72.  */
  73. @mixin set-auto-breakpoint($breakpoint){
  74. 	@if map.has-key($jig---breakpoint-config, $breakpoint) {
  75. 		$jig---auto-breakpoint: $breakpoint !global;
  76. 	} @else {
  77. 		@error 'jig:set-current-breakpoint | unknown named breakpoint "#{$breakpoint}"';
  78. 	}
  79. }
  83. /**
  84.  * @namespace Breakpoints:reset-auto-breakpoint
  85.  */
  87. /**
  88.  * Resets the auto breakpoint to the first/smallest named breakpoint defined in the jig config.
  89.  * Hint: this is automatically called at the end of the breakpoint mixin, so usually you should be fine
  90.  * never calling this manually
  91.  *
  92.  * @memberof Breakpoints:reset-auto-breakpoint
  93.  * @function
  94.  * @name reset-auto-breakpoint
  95.  * @alias reset-auto-breakpoint
  96.  *
  97.  * @see set-auto-breakpoint
  99.  * @example
  100.  * \@include reset-auto-breakpoint();
  101.  */
  102. @mixin reset-auto-breakpoint(){
  103. 	$jig---auto-breakpoint: list.nth(map.keys($jig---breakpoint-config), 1) !global;
  104. }
  108. /**
  109.  * @namespace Breakpoints:is-named-breakpoint
  110.  */
  112. /**
  113.  * Returns if the given breakpoint is a registered named breakpoint to be found in the jig config.
  114.  *
  115.  * @memberof Breakpoints:is-named-breakpoint
  116.  * @function
  117.  * @name is-named-breakpoint
  118.  * @alias is-named-breakpoint
  119.  *
  120.  * @param {String} $breakpoint - a named breakpoint defined in the jig config
  121.  * @returns {Boolean} true if breakpoint is a registered named breakpoint name
  122.  *
  123.  * @example
  124.  * is-named-breakpoint(medium)
  125.  *   => true
  126.  */
  127. @function is-named-breakpoint($breakpoint){
  128. 	@return map.has-key($jig---breakpoint-config, $breakpoint);
  129. }
  133. /**
  134.  * @namespace Breakpoints:build-breakpoint-range
  135.  */
  137. /**
  138.  * Returns a string to be used in a media query, which defines the range/bounds of a breakpoint with
  139.  * min and/or max value.
  140.  *
  141.  * @memberof Breakpoints:build-breakpoint-range
  142.  * @function
  143.  * @name build-breakpoint-range
  144.  * @alias build-breakpoint-range
  145.  *
  146.  * @param {?Number} [$min=null] - the min width of the breakpoint
  147.  * @param {?Number} [$max=null] - the max width of the breakpoint
  148.  * @returns {String} the media query string for the breakpoint range
  149.  *
  150.  * @example
  151.  * build-breakpoint-range(0, 767px)
  152.  *   => '(min-width: 0) and (max-width: 767px)'
  153.  * build-breakpoint-range(null, 100rem)
  154.  *   => '(max-width: 100rem)'
  155.  */
  156. @function build-breakpoint-range($min:null, $max:null){
  157. 	@return util.str-join(
  158. 		[
  159. 			if($min != null, '(min-width: #{$min})', null),
  160. 			if($max != null, '(max-width: #{$max})', null)
  161. 		],
  162. 		' and '
  163. 	);
  164. }
  168. /**
  169.  * @namespace Breakpoints:build-breakpoint-query
  170.  */
  172. /**
  173.  * Constructs a query to be used in a media query, based on a breakpoint definition.
  174.  * Also automatically converts values to rem.
  175.  *
  176.  * Directions in composite definitions may be "up", "down" or "only".
  177.  *
  178.  * You may also define the special breakpoints "landscape" or "portrait" to cover device orientations.
  179.  *
  180.  * @memberof Breakpoints:build-breakpoint-query
  181.  * @function
  182.  * @name build-breakpoint-query
  183.  * @alias build-breakpoint-query
  184.  *
  185.  * @param {?Number|Literal|List<String>} [$breakpoint-definition=0] - either a simple number or a composite definition of width and direction, where the width may either be a number or a name defined in the named breakpoints
  186.  * @returns {String} the media query string for the breakpoint definition
  187.  * @throws error if named breakpoint is unknown
  188.  * @throws error if an unnamed breakpoint has an "only" direction
  189.  *
  190.  * @example
  191.  * build-breakpoint-query(200rem)
  192.  *   => '(min-width: 200rem)'
  193.  * build-breakpoint-query(small down)
  194.  *   => '(max-width: 199rem)'
  195.  * build-breakpoint-query(('large' 'only'))
  196.  *   => '(min-width: 200rem) and (max-width: 499rem)'
  197.  * build-breakpoint-query(1024px only)
  198.  *   => '(min-width: 64rem) and (max-width: 64rem)'
  199.  * build-breakpoint-query(landscape)
  200.  *   => '(orientation: landscape)'
  201.  */
  202. @function build-breakpoint-query($breakpoint-definition:0){
  203. 	$breakpoint: if($breakpoint-definition and (list.length($breakpoint-definition) > 0), list.nth($breakpoint-definition, 1), 0);
  204. 	$direction: if($breakpoint-definition and (list.length($breakpoint-definition) > 1), list.nth($breakpoint-definition, 2), 'up');
  205. 	$breakpoint-name: null;
  206. 	$next-breakpoint: null;
  207. 	$min: null;
  208. 	$max: null;
  209. 	$query-em-conversion-base: 16px; // this is always 16px, no matter what is defined on <html>
  211. 	@if $breakpoint == 'overwrite' {
  212. 		@return '(min-width: 0)';
  213. 	} @else if ($breakpoint == 'landscape') or ($breakpoint == 'portrait') {
  214. 		@return '(orientation: #{$breakpoint})';
  215. 	} @else if meta.type-of($breakpoint) == 'string' {
  216. 		@if is-named-breakpoint($breakpoint) {
  217. 			$breakpoint-name: $breakpoint;
  218. 			$breakpoint: map.get($jig---breakpoint-config, $breakpoint-name);
  219. 			$next-breakpoint: util.map-next($jig---breakpoint-config, $breakpoint-name);
  220. 		} @else {
  221. 			@error 'jig:build-breakpoint-query | "#{$breakpoint-definition}" is not a defined breakpoint';
  222. 		}
  223. 	}
  225. 	@if ($breakpoint-name == null) and ($direction == 'only') {
  226. 		@error 'jig:build-breakpoint-query | only named media queries can have an "only" range';
  227. 	}
  229. 	// we are building media queries with em instead of rem and px
  230. 	// why? => https://zellwk.com/blog/media-query-units/
  232. 	@if ($direction == 'only') or ($direction == 'up') {
  233. 		$min: util.to-em($breakpoint, $query-em-conversion-base);
  234. 	}
  236. 	@if ($direction == 'only') or ($direction == 'down') {
  237. 		@if $breakpoint-name == null {
  238. 			$max: util.to-em($breakpoint, $query-em-conversion-base);
  239. 		} @else if $next-breakpoint != null {
  240. 			$max: util.to-em($next-breakpoint, $query-em-conversion-base) - util.to-em(1px, $query-em-conversion-base);
  241. 		}
  242. 	}
  244. 	@if ($min == 0) and ($max == null){
  245. 		$min: null;
  246. 	}
  248. 	@return build-breakpoint-range($min, $max);
  249. }
  253. /**
  254.  * @namespace Breakpoints:breakpoint
  255.  */
  257. /**
  258.  * Renders media queries based one one or more breakpoint definitions.
  259.  *
  260.  * @memberof Breakpoints:breakpoint
  261.  * @function
  262.  * @name breakpoint
  263.  * @alias breakpoint
  264.  *
  265.  * @param {Number|Literal|List<String>|List<Literal>|List<List<String>>} $breakpoint-definitions - a list of breakpoint definitions according to build-breakpoint-query
  266.  *
  267.  * @example
  268.  * \@include breakpoint(small){
  269.  *   ...
  270.  * }
  271.  * \@include breakpoint(small down, large up){
  272.  *   ...
  273.  * }
  274.  */
  275. @mixin breakpoint($breakpoint-definitions...){
  276. 	@each $breakpoint-definition in $breakpoint-definitions {
  277. 		$query: build-breakpoint-query($breakpoint-definition);
  278. 		$breakpoint: if(list.length($breakpoint-definition) > 0, list.nth($breakpoint-definition, 1), 0);
  279. 		$direction: if(list.length($breakpoint-definition) > 1, list.nth($breakpoint-definition, 2), 'up');
  280. 		$breakpoint-index: index(map.keys($jig---breakpoint-config), list.nth($breakpoint-definition, 1));
  281. 		$print-breakpoint-index: list.index(map.keys($jig---breakpoint-config), $jig---print-breakpoint);
  283. 		// set current breakpoint var to mixin breakpoint value to allow for auto-evaluation inside
  284. 		@if is-named-breakpoint($breakpoint){
  285. 			@include set-auto-breakpoint($breakpoint);
  286. 		}
  288. 		@if $query == '' {
  289. 			@content;
  290. 		} @else {
  291. 			@if(
  292. 				($breakpoint-index != null)
  293. 				and (
  294. 					($breakpoint-index <= $print-breakpoint-index)
  295. 					or ($direction == 'down')
  296. 				)
  297. 			){
  298. 				@media print, screen and #{$query} {
  299. 					@content;
  300. 				}
  301. 			} @else {
  302. 				@media screen and #{$query} {
  303. 					@content;
  304. 				}
  305. 			}
  306. 		}
  308. 		// restore initial value after mixin has been rendered
  309. 		@include reset-auto-breakpoint();
  310. 	}
  311. }
  315. /**
  316.  * @namespace Breakpoints:breakpoint-value
  317.  */
  319. /**
  320.  * Search for a value, defined for a breakpoint, in a given map of values.
  321.  * The function escalates in a mobile-first manner. So we take the value for the smallest breakpoint
  322.  * and step up the breakpoints one by one until we reach the defined breakpoint. So, if we want the
  323.  * according value for "large", but we only have a value for "medium", we'll get the "medium" value, which,
  324.  * in mobile-first manner, escalates upwards and is the "large" value if nothing else is defined.
  325.  *
  326.  * @memberof Breakpoints:breakpoint-value
  327.  * @function
  328.  * @name breakpoint-value
  329.  * @alias breakpoint-value
  330.  *
  331.  * @param {*|Map} $value - a map of breakpoint-keyed map of values, or a simple value
  332.  * @param {Literal|String} $breakpoint - either "auto" (to use the current breakpoint) or one of the defined named breakpoints
  333.  * @returns {*|null} the breakpoint value or null if nothing was found
  334.  * @throws error if named breakpoint is unknown
  335.  *
  336.  * @example
  337.  * breakpoint-value(
  338.  *   (
  339.  *     'small' : 10px,
  340.  *     'medium' : 20px
  341.  *   ),
  342.  *   large
  343.  * )
  344.  *   => 20px
  345.  */
  346. @function breakpoint-value($value, $breakpoint:'auto'){
  347. 	@if ($breakpoint != 'auto') and not map.has-key($jig---breakpoint-config, $breakpoint) {
  348. 		@error 'jig:breakpoint-value | given breakpoint "#{$breakpoint}" not defined';
  349. 	}
  351. 	@if meta.type-of($value) == 'map' {
  352. 		$res: null;
  354. 		@if $breakpoint == 'auto' {
  355. 			$breakpoint: get-auto-breakpoint();
  356. 		}
  358. 		@each $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config {
  359. 			$breakpoint-value: map.get($value, $breakpoint-name);
  361. 			@if $breakpoint-value != null {
  362. 				$res: $breakpoint-value;
  363. 			}
  365. 			@if $breakpoint-name == $breakpoint {
  366. 				@return $res;
  367. 			}
  368. 		}
  370. 		@return null;
  371. 	} @else {
  372. 		@return $value;
  373. 	}
  374. }
  378. /**
  379.  * @namespace Breakpoints:attributes-for-breakpoints
  380.  */
  382. /**
  383.  * Renders attribute values for given attributes for defined breakpoints.
  384.  *
  385.  * Definitions will be rendered together if possible, minimizing the amount of media queries.
  386.  * However, each call of this mixin will, most likely, render multiple media queries, so keep a close eye
  387.  * on your media query structure to avoid unnecessarily doubled definitions and keep media queries to a minimum.
  388.  * If in doubt, it might be a better idea to write the queries manually, perhaps rather using `map.get` or
  389.  * `breakpoint-value` to automatically pull values from breakpoint value maps.
  390.  *
  391.  * @memberof Breakpoints:attributes-for-breakpoints
  392.  * @function
  393.  * @name attributes-for-breakpoints
  394.  * @alias attributes-for-breakpoints
  395.  *
  396.  * @see attribute-for-breakpoints
  397.  *
  398.  * @param {Map} $attributes - keys are attribute names, while values are either plain values or maps with breakpoint name keys, providing different values per breakpoint
  399.  * @param {Number} [$factor=null] - if a float factor is provided all values will be multiplied with this factor
  400.  *
  401.  * @example
  402.  * \@include attributes-for-breakpoints(
  403.  *   (
  404.  *     'font-size' : 12px,
  405.  *     'line-height' : (
  406.  *       'small' : 1,
  407.  *       'large' : 1.25
  408.  *     ),
  409.  *     'margin-top' : (
  410.  *       'small' : 10px,
  411.  *       'medium' : 20px
  412.  *     )
  413.  *   ),
  414.  *   2.0
  415.  * );
  416.  */
  417. @mixin attributes-for-breakpoints($attributes, $factor:null){
  418. 	$attributes-for-breakpoints: ();
  419. 	@each $attribute-name, $attribute-value in $attributes {
  420. 		@if meta.type-of($attribute-value) != 'map' {
  421. 			@if $factor == null {
  422. 				#{$attribute-name}: $attribute-value;
  423. 			} @else {
  424. 				#{$attribute-name}: ($factor * $attribute-value);
  425. 			}
  426. 		} @else {
  427. 			@each $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config {
  428. 				$breakpoint-value: map.get($attribute-value, $breakpoint-name);
  429. 				@if $breakpoint-value != null {
  430. 					$breakpoint-attributes: map.get($attributes-for-breakpoints, $breakpoint-name);
  431. 					@if $breakpoint-attributes == null {
  432. 						$breakpoint-attributes: ();
  433. 					}
  435. 					$breakpoint-attributes: map.merge(
  436. 						$breakpoint-attributes,
  437. 						($attribute-name : $breakpoint-value)
  438. 					);
  440. 					$attributes-for-breakpoints: map.merge(
  441. 						$attributes-for-breakpoints,
  442. 						($breakpoint-name : $breakpoint-attributes)
  443. 					);
  444. 				}
  445. 			}
  446. 		}
  447. 	}
  449. 	@each $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config {
  450. 		$breakpoint-attributes: map.get($attributes-for-breakpoints, $breakpoint-name);
  451. 		@if ($breakpoint-attributes != null) and (list.length(map.keys($breakpoint-attributes)) > 0) {
  452. 			@include breakpoint($breakpoint-name){
  453. 				@each $attribute-name, $attribute-value in $breakpoint-attributes {
  454. 					@if $factor == null {
  455. 						#{$attribute-name}: $attribute-value;
  456. 					} @else {
  457. 						#{$attribute-name}: ($factor * $attribute-value);
  458. 					}
  459. 				}
  460. 			}
  461. 		}
  462. 	}
  463. }
  467. /**
  468.  * @namespace Breakpoints:attribute-for-breakpoints
  469.  */
  471. /**
  472.  * Renders attribute values for given attribute for defined breakpoints.
  473.  *
  474.  * This is the single attribute version of `attributes-for-breakpoints`.
  475.  * Since this version does not optimize the usage of media queries, please make sure to only use this mixin,
  476.  * if you'll definitely only have one attribute to be defined in multiple breakpoints.
  477.  *
  478.  * @memberof Breakpoints:attribute-for-breakpoints
  479.  * @function
  480.  * @name attribute-for-breakpoints
  481.  * @alias attribute-for-breakpoints
  482.  *
  483.  * @see attributes-for-breakpoints
  484.  *
  485.  * @param {String} $attribute - the name of the attribute you want to set
  486.  * @param {*} $value - the value to set the attribute to
  487.  * @param {Number} [$factor=null] - if a float factor is provided the value will be multiplied with this factor
  488.  *
  489.  * @example
  490.  * \@include attribute-for-breakpoints(
  491.  *   'line-height',
  492.  *   (
  493.  *     'small' : 1,
  494.  *     'large' : 1.25
  495.  *   ),
  496.  *   1.0
  497.  * );
  498.  */
  499. @mixin attribute-for-breakpoints($attribute, $value, $factor:null){
  500. 	$attributes: ();
  501. 	$attributes: map.merge($attributes, ('#{$attribute}' : $value));
  502. 	@include attributes-for-breakpoints($attributes, $factor);
  503. }
  507. /**
  508.  * @namespace Breakpoints:overwrite-breakpoint-for-attributes
  509.  */
  511. /**
  512.  * Use this, if you need to overwrite attribute values previously defined in (a) breakpoint(s).
  513.  *
  514.  * A use case might be, for example, to set a font-size to a static value in an element with a responsive,
  515.  * breakpoint-based font-size definition.
  516.  *
  517.  * @memberof Breakpoints:overwrite-breakpoint-for-attributes
  518.  * @function
  519.  * @name overwrite-breakpoint-for-attributes
  520.  * @alias overwrite-breakpoint-for-attributes
  521.  *
  522.  * @param {Map} $attributes - keys are attribute names, while values are either plain values or maps with breakpoint name keys, providing different values per breakpoint
  523.  * @param {Number} [$factor=null] - if a float factor is provided all values will be multiplied with this factor
  524.  *
  525.  * @see overwrite-breakpoint-for-attribute
  526.  *
  527.  * @example
  528.  * \@include overwrite-breakpoint-for-attributes(
  529.  *   (
  530.  *     'font-size' : 12px,
  531.  *     'line-height' : 1.25
  532.  *     'margin-top' : 20px
  533.  *   ),
  534.  *   2.0
  535.  * );
  536.  */
  537. @mixin overwrite-breakpoint-for-attributes($attributes, $factor:null){
  538. 	@include breakpoint('overwrite'){
  539. 		@each $attribute-name, $attribute-value in $attributes {
  540. 			@if $factor == null {
  541. 				#{$attribute-name}: $attribute-value;
  542. 			} @else {
  543. 				#{$attribute-name}: ($factor * $attribute-value);
  544. 			}
  545. 		}
  546. 	}
  547. }
  551. /**
  552.  * @namespace Breakpoints:overwrite-breakpoint-for-attribute
  553.  */
  555. /**
  556.  * Use this, if you need to overwrite an attribut value previously defined in (a) breakpoint(s).
  557.  *
  558.  * A use case might be, for example, to set a font-size to a static value in an element with a responsive,
  559.  * breakpoint-based font-size definition.
  560.  *
  561.  * @memberof Breakpoints:overwrite-breakpoint-for-attribute
  562.  * @function
  563.  * @name overwrite-breakpoint-for-attribute
  564.  * @alias overwrite-breakpoint-for-attribute
  565.  *
  566.  * @see overwrite-breakpoint-for-attributes
  567.  *
  568.  * @param {String} $attribute - the name of the attribute you want to set
  569.  * @param {*} $value - the value to set the attribute to
  570.  * @param {Number} [$factor=null] - if a float factor is provided the value will be multiplied with this factor
  571.  *
  572.  * @example
  573.  * \@include overwrite-breakpoint-for-attribute(font-size, 12px, 2.0);
  574.  */
  575. @mixin overwrite-breakpoint-for-attribute($attribute, $value, $factor:null){
  576. 	$attributes: ();
  577. 	$attributes: map.merge($attributes, ('#{$attribute}' : $value));
  578. 	@include overwrite-breakpoint-for-attributes($attributes, $factor);
  579. }
  583. /**
  584.  * @namespace Breakpoints:overwrite-breakpoint
  585.  */
  587. /**
  588.  * Use this, if you need to overwrite something previously defined in (a) breakpoint(s).
  589.  *
  590.  * A use case might be, for example, to redefine something statically in an override situation, which has
  591.  * been defined responsively before.
  592.  *
  593.  * @memberof Breakpoints:overwrite-breakpoint
  594.  * @function
  595.  * @name overwrite-breakpoint
  596.  * @alias overwrite-breakpoint
  597.  *
  598.  * @example
  599.  * \@include overwrite-breakpoint(){
  600.  *   font-size: 12xp;
  601.  *   margin-top: 20px;
  602.  * }
  603.  */
  604. @mixin overwrite-breakpoint(){
  605. 	@include breakpoint('overwrite'){
  606. 		@content;
  607. 	}
  608. }