Sass mixin library#
This is the included Sass mixin library you should use to build CSS manifest from Sass.
Copy the following source into your Sass project and import it, we recommend you to
name it _styleguide_helpers.scss.
Once imported you will be able to write manifest using your Sass variables, remember to define compiler behavior support in your Sass settings:
$pycssstyleguide-compiler-support: "libsass";
Or:
$pycssstyleguide-compiler-support: "dartsass";
Depending you are using a Libsass or Dart Sass compiler. This variable have to be set after the library import.
_styleguide_helpers.scss#
/* Helper functions from py-css-styleguide==1.0.0 */
///
/// Determine behavior to endorse at runtime.
$pycssstyleguide-compiler-support: "libsass" !default;
/// Replace every occurences of a character with a substition string.
/// Useful to strip some characters.
///
/// @arg {String} $string [null]
/// A string to parse, this must be a real string type.
///
/// @arg {String} $search [null]
/// Character to replace.
///
/// @arg {String} $replace ['']
/// String which will replace searched character.
///
/// @return {String} - Modified string following given arguments.
///
@function _strip-token($string, $search, $replace: '') {
$index: str-index($string, $search);
@if $index {
@return str-slice($string, 1, $index - 1) + $replace + _strip-token(str-slice($string, $index + str-length($search)), $search, $replace);
}
@return $string;
}
/// Enforce safe string with escaping simple and double quote
///
/// @arg {String} $string [null]
/// A string to parse, `#{}` is used on given value so it always enforce
/// given value will be a real string type. (So you may give it a list or
/// map or whatever).
///
/// @arg {Bool} $apply [true]
/// If false, will return the given string unmodified.
///
/// @return {String} - Escaped string if $apply is enabled.
///
@function _safe-string($string, $apply: true) {
@if $apply {
$value: #{$string};
@return _strip-token(_strip-token($value, '"', $replace: '\\u0022'), "'", $replace: '\\u0027');
}
@return $string;
}
///
/// Convert a list to a string
/// Copied from https://hugogiraudel.com/2013/08/08/advanced-sass-list-functions/
///
/// @arg {List} $list [null]
/// A list.
///
/// @arg {String} $glue ['']
/// A string used to join elements.
///
/// @arg {Bool} $is-nested [false]
/// A pointer used when function does call itself.
///
@function to-string($list, $glue: '', $is-nested: false) {
$result: null;
@if length($list) > 0{
@for $i from 1 through length($list) {
$e: nth($list, $i);
@if type-of($e) == list {
$result: $result#{to-string($e, $glue, true)};
} @else {
$result: if(
$i != length($list) or $is-nested,
$result#{$e}#{$glue},
$result#{$e}
);
}
}
}
@return $result;
}
///
/// Convert a list to a JSON list for Libsass compatibility.
///
/// Libsass does not enforce quote type around string, we can so produce valid JSON.
/// NOTE: Not sure if libsass could endore the dartsass behavior so we would not need
/// to support two functions for a same feature.
///
/// @arg {List} $list [null]
/// A list.
///
@function list-to-json_libsass($list) {
$glue: '", "';
$result: to-string($list, $glue);
@return '["#{$result}"]';
}
///
/// Convert a list to a JSON list for Dart sass compatibility.
///
/// Dart sass enforce double quotes around a string so we can't produce valid JSON, we
/// have to quote with double quotes the value which contains JSON. So in this
/// pseudo JSON we need to quote strings with simple quote to not break compiled CSS.
///
/// @arg {List} $list [null]
/// A list.
///
@function list-to-json_dartsass($list) {
$glue: "', '";
$result: to-string($list, $glue);
@return "['#{$result}']";
}
///
/// Convert a list to a JSON list depending the enabled compiler support.
///
/// @arg {List} $list [null]
/// A list.
///
@function list-to-json($list) {
@if $pycssstyleguide-compiler-support == "dartsass" {
@return list-to-json_dartsass($list);
} @else {
@return list-to-json_libsass($list);
}
}
///
/// Get key names from a map to return a string of key names separated by
/// an empty space.
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
@function get-names($map, $prefix: "") {
$values: ();
@each $name in map-keys($map) {
$values: append($values, $prefix+$name);
}
@return to-string($values, $glue: ' ');
}
///
/// Get key names from a map to return a JSON list of key names
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
@function get-names-to-json($map, $prefix: "") {
$values: ();
@each $name in map-keys($map) {
$values: append($values, $prefix+$name);
}
@return list-to-json($values);
}
///
/// Get item values from a map to return a string of names separated by
/// an empty space.
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
@function get-values($map, $prefix: "") {
$values: ();
@each $name in map-values($map) {
$values: append($values, $prefix+$name);
}
@return to-string($values, $glue: ' ');
}
///
/// Get item values from a map to return a JSON list of names separated by
/// an empty space.
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
/// @arg {Bool} $safe-string [true]
/// If true, every item value are escaped from single and double quotes. This
/// is often required to avoid invalid JSON with values which contain quotes.
///
@function get-values-to-json($map, $prefix: "", $safe-string: true) {
$values: ();
@each $name in map-values($map) {
$val: _safe-string($name, $apply: $safe-string);
$values: append($values, $prefix+$val);
}
@return list-to-json($values);
}
///
/// Get property values from a map to return a string of values separated by
/// an empty space.
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $property [null]
/// Property name to get.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
@function get-props($map, $property, $prefix: "") {
$values: ();
@each $name, $scheme in $map {
$values: append($values, $prefix+map-get($scheme, $property));
}
@return to-string($values, $glue: ' ');
}
///
/// Get property values from a map to return a JSON list of values.
///
/// @arg {Map} $map [null]
/// A map.
///
/// @arg {String} $property [null]
/// Property name to get.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
/// @arg {Bool} $safe-string [true]
/// If true, every item value are escaped from single and double quotes. This
/// is often required to avoid invalid JSON with values which contain quotes.
///
@function get-props-to-json($map, $property, $prefix: "", $safe-string: true) {
$values: ();
@each $name, $scheme in $map {
$val: _safe-string(map-get($scheme, $property), $apply: $safe-string);
$values: append($values, $prefix+$val);
}
@return list-to-json($values);
}
///
/// Get numbers from a list to return a string of floor number separated by an
/// empty space.
///
/// Floor number can so be used as valid class names, since decimals are not
/// valid selector.
///
/// @arg {List} $list [null]
/// A list of number.
///
/// @arg {String} $prefix ['']
/// A string to preprend to each item.
///
@function floor-number-items($list, $prefix: "") {
$values: ();
@each $number in $list {
$number: floor($number);
$values: append($values, $prefix+$number);
}
@return to-string($values, $glue: ' ');
}
Usage of these mixins depends of your Sass settings, see See Samples for some usages with this Sass library.