Source: breakpoints.styl

  1. /**
  2.  * @namespace Breakpoints
  3.  */
  7. $jig---auto-breakpoint = keys($jig---breakpoint-config)[0]
  11. /**
  12.  * @namespace Breakpoints:get-auto-breakpoint
  13.  */
  15. /**
  16.  * Returns the current auto breakpoint value.
  17.  *
  18.  * @memberof Breakpoints:get-auto-breakpoint
  19.  * @function
  20.  * @name get-auto-breakpoint
  21.  * @alias get-auto-breakpoint
  22.  *
  23.  * @returns {String} the name of the current named auto breakpoint
  24.  *
  25.  * @see set-auto-breakpoint
  26.  * @see reset-auto-breakpoint
  27.  *
  28.  * @example
  29.  * get-auto-breakpoint()
  30.  *   => 'medium'
  31.  */
  32. get-auto-breakpoint()
  33. 	return $jig---auto-breakpoint
  37. /**
  38.  * @namespace Breakpoints:set-auto-breakpoint
  39.  */
  41. /**
  42.  * Sets the auto breakpoint to a named breakpoint value.
  43.  * Hint: in Stylus we have to do this manually, if we want to use auto breakpoint values,
  44.  * since blocks are always evaluated _before_ the block mixin around the block, which results
  45.  * in the block only knowing the breakpoint before the mixin.
  46.  *
  47.  * @memberof Breakpoints:set-auto-breakpoint
  48.  * @function
  49.  * @name set-auto-breakpoint
  50.  * @alias set-auto-breakpoint
  51.  *
  52.  * @param {String} $breakpoint - a named breakpoint defined in the jig config
  53.  * @throws error if breakpoint is unknown
  54.  *
  55.  * @see reset-auto-breakpoint
  57.  * @example
  58.  * set-auto-breakpoint(medium)
  59.  * +breakpoint(medium)
  60.  *   ...
  61.  */
  62. set-auto-breakpoint($breakpoint)
  63. 	$breakpoint = to-str($breakpoint)
  65. 	if $breakpoint in $jig---breakpoint-config
  66. 		define('$jig---auto-breakpoint', $breakpoint, true)
  67. 	else
  68. 		error('jig:set-current-breakpoint | unknown named breakpoint "'+$breakpoint+'"')
  72. /**
  73.  * @namespace Breakpoints:reset-auto-breakpoint
  74.  */
  76. /**
  77.  * Resets the auto breakpoint to the first/smallest named breakpoint defined in the jig config.
  78.  * Hint: although you may do this manually in Stylus, this is automatically called at the end of the
  79.  * breakpoint mixin, so usually you should be fine with set-auto-breakpoint, without resetting, if you
  80.  * use a breakpoint directly after the call.
  81.  *
  82.  * @memberof Breakpoints:reset-auto-breakpoint
  83.  * @function
  84.  * @name reset-auto-breakpoint
  85.  * @alias reset-auto-breakpoint
  86.  *
  87.  * @see set-auto-breakpoint
  89.  * @example
  90.  * reset-auto-breakpoint()
  91.  */
  92. reset-auto-breakpoint()
  93. 	define('$jig---auto-breakpoint', keys($jig---breakpoint-config)[0], true)
  97. /**
  98.  * @namespace Breakpoints:is-named-breakpoint
  99.  */
  101. /**
  102.  * Returns if the given breakpoint is a registered named breakpoint to be found in the jig config.
  103.  *
  104.  * @memberof Breakpoints:is-named-breakpoint
  105.  * @function
  106.  * @name is-named-breakpoint
  107.  * @alias is-named-breakpoint
  108.  *
  109.  * @param {String} $breakpoint - a named breakpoint defined in the jig config
  110.  * @returns {Boolean} true if breakpoint is a registered named breakpoint name
  111.  *
  112.  * @example
  113.  * is-named-breakpoint(medium)
  114.  *   => true
  115.  */
  116. is-named-breakpoint($breakpoint)
  117. 	$breakpoint = to-str($breakpoint)
  119. 	return $breakpoint in $jig---breakpoint-config
  123. /**
  124.  * @namespace Breakpoints:build-breakpoint-range
  125.  */
  127. /**
  128.  * Returns a string to be used in a media query, which defines the range/bounds of a breakpoint with
  129.  * min and/or max value.
  130.  *
  131.  * @memberof Breakpoints:build-breakpoint-range
  132.  * @function
  133.  * @name build-breakpoint-range
  134.  * @alias build-breakpoint-range
  135.  *
  136.  * @param {?Number} [$min=null] - the min width of the breakpoint
  137.  * @param {?Number} [$max=null] - the max width of the breakpoint
  138.  * @returns {String} the media query string for the breakpoint range
  139.  *
  140.  * @example
  141.  * build-breakpoint-range(0, 767px)
  142.  *   => '(min-width: 0) and (max-width: 767px)'
  143.  * build-breakpoint-range(null, 100rem)
  144.  *   => '(max-width: 100rem)'
  145.  */
  146. build-breakpoint-range($min=null, $max=null)
  147. 	$min-query = ($min != null) ? '(min-width: '+$min+')' : null
  148. 	$max-query = ($max != null) ? '(max-width: '+$max+')' : null
  150. 	return str-join(($min-query $max-query), ' and ')
  154. /**
  155.  * @namespace Breakpoints:build-breakpoint-query
  156.  */
  158. /**
  159.  * Constructs a query to be used in a media query, based on a breakpoint definition.
  160.  * Also automatically converts values to rem.
  161.  *
  162.  * Directions in composite definitions may be "up", "down" or "only".
  163.  *
  164.  * You may also define the special breakpoints "landscape" or "portrait" to cover device orientations.
  165.  *
  166.  * @memberof Breakpoints:build-breakpoint-query
  167.  * @function
  168.  * @name build-breakpoint-query
  169.  * @alias build-breakpoint-query
  170.  *
  171.  * @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
  172.  * @returns {String} the media query string for the breakpoint definition
  173.  * @throws error if named breakpoint is unknown
  174.  * @throws error if an unnamed breakpoint has an "only" direction
  175.  *
  176.  * @example
  177.  * build-breakpoint-query(200rem)
  178.  *   => '(min-width: 200rem)'
  179.  * build-breakpoint-query(small down)
  180.  *   => '(max-width: 199rem)'
  181.  * build-breakpoint-query(('large' 'only'))
  182.  *   => '(min-width: 200rem) and (max-width: 499rem)'
  183.  * build-breakpoint-query(1024px only)
  184.  *   => '(min-width: 64rem) and (max-width: 64rem)'
  185.  * build-breakpoint-query(landscape)
  186.  *   => '(orientation: landscape)'
  187.  */
  188. build-breakpoint-query($breakpoint-definition=0)
  189. 	$breakpoint = $breakpoint-definition[0] ? to-str($breakpoint-definition[0], $only-ident:true) : 0
  190. 	$direction = $breakpoint-definition[1] ? to-str($breakpoint-definition[1]) : 'up'
  191. 	$breakpoint-name = null
  192. 	$next-breakpoint = null
  193. 	$min = null
  194. 	$max = null
  195. 	$query-em-conversion-base = 16px // this is always 16px, no matter what is defined on <html>
  197. 	if $breakpoint == 'overwrite'
  198. 		return '(min-width: 0)'
  199. 	else if ($breakpoint == 'landscape') or ($breakpoint == 'portrait')
  200. 		return '(orientation: '+$breakpoint+')'
  201. 	else if type($breakpoint) == 'string'
  202. 		if is-named-breakpoint($breakpoint)
  203. 			$breakpoint-name = $breakpoint
  204. 			$breakpoint = $jig---breakpoint-config[$breakpoint-name]
  205. 			$next-breakpoint = hash-next($jig---breakpoint-config, $breakpoint-name)
  206. 		else
  207. 			error('jig:build-breakpoint-query | "'+$breakpoint-definition+'" is not a defined breakpoint')
  209. 	if ($breakpoint-name == null) and ($direction == 'only')
  210. 		error('jig:build-breakpoint-query | only named media queries can have an "only" range')
  212. 	// we are building media queries with em instead of rem and px
  213. 	// why? => https://zellwk.com/blog/media-query-units/
  215. 	if ($direction == 'only') or ($direction == 'up')
  216. 		$min = to-em($breakpoint, $query-em-conversion-base)
  218. 	if ($direction == 'only') or ($direction == 'down')
  219. 		if $breakpoint-name == null
  220. 			$max = to-em($breakpoint, $query-em-conversion-base)
  221. 		else if $next-breakpoint-name != null
  222. 			$max = to-em($next-breakpoint, $query-em-conversion-base) - to-em(1px, $query-em-conversion-base)
  224. 	if ($min == 0) and ($max == null)
  225. 		$min = null
  227. 	return build-breakpoint-range($min, $max)
  231. /**
  232.  * @namespace Breakpoints:breakpoint
  233.  */
  235. /**
  236.  * Renders media queries based one one or more breakpoint definitions.
  237.  *
  238.  * @memberof Breakpoints:breakpoint
  239.  * @function
  240.  * @name breakpoint
  241.  * @alias breakpoint
  242.  *
  243.  * @param {Number|Literal|List<String>|List<Literal>|List<List<String>>} $breakpoint-definitions - a list of breakpoint definitions according to build-breakpoint-query
  244.  *
  245.  * @see set-auto-breakpoint
  246.  *
  247.  * @example
  248.  * +breakpoint(small)
  249.  *   ...
  250.  * +breakpoint(small down, large up)
  251.  *   ...
  252.  */
  253. breakpoint($breakpoint-definitions...)
  254. 	for $breakpoint-definition in $breakpoint-definitions
  255. 		$query = build-breakpoint-query($breakpoint-definition)
  256. 		$breakpoint = $breakpoint-definition[0] ? to-str($breakpoint-definition[0], $only-ident:true) : 0
  257. 		$direction = $breakpoint-definition[1] ? to-str($breakpoint-definition[1]) : 'up'
  258. 		$breakpoint-index = index(keys($jig---breakpoint-config), $breakpoint)
  259. 		$print-breakpoint-index = index(keys($jig---breakpoint-config), $jig---print-breakpoint)
  261. 		// set current breakpoint var to mixin breakpoint value to allow for auto-evaluation inside
  262. 		if is-named-breakpoint($breakpoint)
  263. 			set-auto-breakpoint($breakpoint)
  265. 		if $query == ''
  266. 			{block}
  267. 		else
  268. 			if	($breakpoint-index != null) and (($breakpoint-index <= $print-breakpoint-index) or ($direction == 'down'))
  269. 				$media-query = s('print, screen and %s', unquote($query))
  270. 				@media $media-query
  271. 					{block}
  272. 			else
  273. 				$media-query = s('screen and %s', unquote($query))
  274. 				@media $media-query
  275. 					{block}
  277. 		// restore initial value after mixin has been rendered
  278. 		reset-auto-breakpoint()
  282. /**
  283.  * @namespace Breakpoints:breakpoint-value
  284.  */
  286. /**
  287.  * Search for a value, defined for a breakpoint, in a given hash of values.
  288.  * The function escalates in a mobile-first manner. So we take the value for the smallest breakpoint
  289.  * and step up the breakpoints one by one until we reach the defined breakpoint. So, if we want the
  290.  * according value for "large", but we only have a value for "medium", we'll get the "medium" value, which,
  291.  * in mobile-first manner, escalates upwards and is the "large" value if nothing else is defined.
  292.  *
  293.  * @memberof Breakpoints:breakpoint-value
  294.  * @function
  295.  * @name breakpoint-value
  296.  * @alias breakpoint-value
  297.  *
  298.  * @param {*|Hash} $value - a hash of breakpoint-keyed map of values, or a simple value
  299.  * @param {Literal|String} $breakpoint - either "auto" (to use the current breakpoint) or one of the defined named breakpoints
  300.  * @returns {*|null} the breakpoint value or null if nothing was found
  301.  * @throws error if named breakpoint is unknown
  302.  *
  303.  * @example
  304.  * breakpoint-value(
  305.  *   {
  306.  *     'small' : 10px,
  307.  *     'medium' : 20px
  308.  *   },
  309.  *   large
  310.  * )
  311.  *   => 20px
  312.  */
  313. breakpoint-value($value, $breakpoint='auto')
  314. 	$breakpoint = to-str($breakpoint)
  316. 	if ($breakpoint != 'auto') and !($breakpoint in $jig---breakpoint-config)
  317. 		error('jig:breakpoint-value | given breakpoint "'+$breakpoint+'" not defined')
  319. 	if type($value) == 'object'
  320. 		$res = null
  322. 		if $breakpoint == 'auto'
  323. 			$breakpoint = get-auto-breakpoint()
  325. 		for $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config
  326. 			$breakpoint-value = $value[$breakpoint-name]
  328. 			if $breakpoint-value != null
  329. 				$res = $breakpoint-value
  331. 			if $breakpoint-name == $breakpoint
  332. 				return $res
  334. 		return null
  335. 	else
  336. 		return $value
  340. /**
  341.  * @namespace Breakpoints:attributes-for-breakpoints
  342.  */
  344. /**
  345.  * Renders attribute values for given attributes for defined breakpoints.
  346.  *
  347.  * Definitions will be rendered together if possible, minimizing the amount of media queries.
  348.  * However, each call of this mixin will, most likely, render multiple media queries, so keep a close eye
  349.  * on your media query structure to avoid unnecessarily doubled definitions and keep media queries to a minimum.
  350.  * If in doubt, it might be a better idea to write the queries manually, perhaps rather using `[]` or
  351.  * `breakpoint-value` to automatically pull values from breakpoint value hashes.
  352.  *
  353.  * @memberof Breakpoints:attributes-for-breakpoints
  354.  * @function
  355.  * @name attributes-for-breakpoints
  356.  * @alias attributes-for-breakpoints
  357.  *
  358.  * @see attribute-for-breakpoints
  359.  *
  360.  * @param {Hash} $attributes - keys are attribute names, while values are either plain values or hashes with breakpoint name keys, providing different values per breakpoint
  361.  * @param {Number} [$factor=null] - if a float factor is provided all values will be multiplied with this factor
  362.  *
  363.  * @example
  364.  * attributes-for-breakpoints(
  365.  *   {
  366.  *     'font-size' : 12px,
  367.  *     'line-height' : {
  368.  *       'small' : 1,
  369.  *       'large' : 1.25
  370.  *     },
  371.  *     'margin-top' : {
  372.  *       'small' : 10px,
  373.  *       'medium' : 20px
  374.  *     }
  375.  *   },
  376.  *   2.0
  377.  * )
  378.  */
  379. attributes-for-breakpoints($attributes, $factor=null)
  380. 	$attributes-for-breakpoints = {}
  381. 	for $attribute-name, $attribute-value in $attributes
  382. 		if type($attribute-value) != 'object'
  383. 			if $factor == null
  384. 				{$attribute-name} $attribute-value
  385. 			else
  386. 				{$attribute-name} ($factor * $attribute-value)
  387. 		else
  388. 			for $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config
  389. 				$breakpoint-value = $attribute-value[$breakpoint-name]
  390. 				if ($breakpoint-value != null) or (type($breakpoint-value) == 'call')
  391. 					if !($breakpoint-name in $attributes-for-breakpoints)
  392. 						$attributes-for-breakpoints[$breakpoint-name] = {}
  393. 					$attributes-for-breakpoints[$breakpoint-name][$attribute-name] = $breakpoint-value;
  395. 	for $breakpoint-name, $breakpoint-definition in $jig---breakpoint-config
  396. 		$breakpoint-attributes = $attributes-for-breakpoints[$breakpoint-name]
  397. 		if ($breakpoint-attributes != null) and (length($breakpoint-attributes) > 0)
  398. 			+breakpoint($breakpoint-name)
  399. 				for $attribute-name, $attribute-value in $breakpoint-attributes
  400. 					if $factor == null
  401. 						{$attribute-name} $attribute-value
  402. 					else
  403. 						{$attribute-name} ($factor * $attribute-value)
  407. /**
  408.  * @namespace Breakpoints:attribute-for-breakpoints
  409.  */
  411. /**
  412.  * Renders attribute values for given attribute for defined breakpoints.
  413.  *
  414.  * This is the single attribute version of `attributes-for-breakpoints`.
  415.  * Since this version does not optimize the usage of media queries, please make sure to only use this mixin,
  416.  * if you'll definitely only have one attribute to be defined in multiple breakpoints.
  417.  *
  418.  * @memberof Breakpoints:attribute-for-breakpoints
  419.  * @function
  420.  * @name attribute-for-breakpoints
  421.  * @alias attribute-for-breakpoints
  422.  *
  423.  * @see attributes-for-breakpoints
  424.  *
  425.  * @param {String} $attribute - the name of the attribute you want to set
  426.  * @param {*} $value - the value to set the attribute to
  427.  * @param {Number} [$factor=null] - if a float factor is provided the value will be multiplied with this factor
  428.  *
  429.  * @example
  430.  * attribute-for-breakpoints(
  431.  *   'line-height',
  432.  *   {
  433.  *     'small' : 1,
  434.  *     'large' : 1.25
  435.  *   },
  436.  *   1.0
  437.  * )
  438.  */
  439. attribute-for-breakpoints($attribute, $value, $factor=null)
  440. 	$attributes = {}
  441. 	$attributes[to-str($attribute)] = $value
  442. 	attributes-for-breakpoints($attributes, $factor)
  446. /**
  447.  * @namespace Breakpoints:overwrite-breakpoint-for-attributes
  448.  */
  450. /**
  451.  * Use this, if you need to overwrite attribute values previously defined in (a) breakpoint(s).
  452.  *
  453.  * A use case might be, for example, to set a font-size to a static value in an element with a responsive,
  454.  * breakpoint-based font-size definition.
  455.  *
  456.  * @memberof Breakpoints:overwrite-breakpoint-for-attributes
  457.  * @function
  458.  * @name overwrite-breakpoint-for-attributes
  459.  * @alias overwrite-breakpoint-for-attributes
  460.  *
  461.  * @param {Hash} $attributes - keys are attribute names, while values are either plain values or hashes with breakpoint name keys, providing different values per breakpoint
  462.  * @param {Number} [$factor=null] - if a float factor is provided all values will be multiplied with this factor
  463.  *
  464.  * @see overwrite-breakpoint-for-attribute
  465.  *
  466.  * @example
  467.  * overwrite-breakpoint-for-attributes(
  468.  *   {
  469.  *     'font-size' : 12px,
  470.  *     'line-height' : 1.25
  471.  *     'margin-top' : 20px
  472.  *   },
  473.  *   2.0
  474.  * )
  475.  */
  476. overwrite-breakpoint-for-attributes($attributes, $factor=null)
  477. 	+breakpoint('overwrite')
  478. 		for $attribute-name, $attribute-value in $attributes
  479. 			if $factor == null
  480. 				{$attribute-name} $attribute-value
  481. 			else
  482. 				{$attribute-name} ($factor * $attribute-value)
  486. /**
  487.  * @namespace Breakpoints:overwrite-breakpoint-for-attribute
  488.  */
  490. /**
  491.  * Use this, if you need to overwrite an attribut value previously defined in (a) breakpoint(s).
  492.  *
  493.  * A use case might be, for example, to set a font-size to a static value in an element with a responsive,
  494.  * breakpoint-based font-size definition.
  495.  *
  496.  * @memberof Breakpoints:overwrite-breakpoint-for-attribute
  497.  * @function
  498.  * @name overwrite-breakpoint-for-attribute
  499.  * @alias overwrite-breakpoint-for-attribute
  500.  *
  501.  * @see overwrite-breakpoint-for-attributes
  502.  *
  503.  * @param {String} $attribute - the name of the attribute you want to set
  504.  * @param {*} $value - the value to set the attribute to
  505.  * @param {Number} [$factor=null] - if a float factor is provided the value will be multiplied with this factor
  506.  *
  507.  * @example
  508.  * overwrite-breakpoint-for-attribute(font-size, 12px, 2.0)
  509.  */
  510. overwrite-breakpoint-for-attribute($attribute, $value, $factor=null)
  511. 	$attributes = {}
  512. 	$attributes[to-str($attribute)] = $value
  513. 	overwrite-breakpoint-for-attributes($attributes, $factor)
  517. /**
  518.  * @namespace Breakpoints:overwrite-breakpoint
  519.  */
  521. /**
  522.  * Use this, if you need to overwrite something previously defined in (a) breakpoint(s).
  523.  *
  524.  * A use case might be, for example, to redefine something statically in an override situation, which has
  525.  * been defined responsively before.
  526.  *
  527.  * @memberof Breakpoints:overwrite-breakpoint
  528.  * @function
  529.  * @name overwrite-breakpoint
  530.  * @alias overwrite-breakpoint
  531.  *
  532.  * @example
  533.  * +overwrite-breakpoint()
  534.  *   font-size 12xp
  535.  *   margin-top 20px
  536.  */
  537. overwrite-breakpoint()
  538. 	+breakpoint('overwrite')
  539. 		{block}