@littlemissrobot/sass-functions

Little Miss Robot - Sass functions

This package contains Sass (Dart Sass) based functions that we, at Little Miss Robot, like to use to make our wonderful lives in the world of SASS more wondeful. These functions are also mainly used throughout our other libraries to manage recurring tasks.

This package does not contain or generate any CSS. It simply provides a couple of @function statements for you to make use of.

IMPORTANT

• Make use of Dart Sass:

  This library makes use of Dart Sass, which is the primary implementation of Sass. Make sure that your Sass compiler is making use of Dart Sass.

• Generate only what you need:

  This library generates classes based on your configuration. The larger the configuration, the more css, the larger the CSS file. DO NOT enable all the config options, but only the ones you actually use and need!

Install

# As a dependency
$ npm install @littlemissrobot/sass-functions
# As a dev-dependency
$ npm install --save-dev @littlemissrobot/sass-functions

Usage

Through the main entry point

1. Import the library from the node_modules folder:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-functions" as _functions;

1. Functions are now available within the _functions namespace:

h1 {
  margin-bottom: _functions.math_px-rem(16px);
}

1. That's (mind-blowingly) it! The functions are seperated with internal namespaces, where functions related to a map are namespaced with _functions.map_[FUNCTION-NAME] or a list would be _functions.list_[FUNCTION-NAME].

Through the partial entry points

1. Import the partial of the library from the node_modules folder.

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-functions/lib/math" as _math;

1. Functions are now available within the _math namespace:

h1 {
  margin-bottom: _math.px-rem(16px);
}

1. That's (mind-blowingly) it! There are a number of partials to use the functions from:

   • "sass-functions/lib/list" as _list;
   • "sass-functions/lib/map" as _map;
   • "sass-functions/lib/math" as _math;
   • "sass-functions/lib/number" as _number;
   • "sass-functions/lib/string" as _string;

Functions

List

These functions are namespace with list_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.list_includes($list, 5);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/lib/list" as _list;

_list.includes($list, 5);

includes($list, $item)

Checks if the list contains a certain item. Returns a boolean.

Parameters:

• $list: the list to search within
• $item: the item to search for in the list

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (1, 2, 3, 4, 5);

_list.includes($list, 5); // true
_list.includes($list, 10); // false

is-numbers-order-low-high($list)

Checks if the numbers in the list are ordered lowest to highest.

Parameters:

• $list: the list which contains the numbers.

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list1: (2, 1, 3);
$list2: (1, 2, 3);

_list.is-numbers-order-low-high($list1); // false
_list.is-numbers-order-low-high($list2); // true

merge-uniques($lists...)

Merges multiple lists and removes any duplicates.

Parameters:

• $lists...: any amount of lists to merge together

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list1: (1, 2, 3);
$list2: (1, 2, 3, 4, 5);
$list3: (4, 5, 6, 7, 8);

_list.merge-uniques($list1, $list2, $list3); // (1, 2, 3, 4, 5, 6, 7, 8)

remove-duplicates($list)

Loops through the list and removes duplicate values.

Parameters:

• $list: the list to remove the duplicates from

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (1, 2, 3, 1, 3, 4, 5);

_list.remove-duplicates($list); // (1, 2, 3, 4, 5)

remove-values($list, $values)

Removes a list of values from the passed list.

Parameters:

• $list: the list to remove the values from.
• $values: the list of values to remove from the list.

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (1, 2, 3, 4, 5);
$values: (1, 2);

_list.remove-values($list, $values); // (3, 4, 5)

remove-value($list, $value)

Removes a value from the passed list.

Parameters:

• $list: the list to remove the value from.
• $value: the value to remove from the list.

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (1, 2, 3, 4, 5);
$value: 1;

_list.remove-value($list, $value); // (2, 3, 4, 5)

reverse($list)

Reverses the order of the values within a list.

Parameters:

• $list: the list to reverse the order of the items.

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (1, 2, 3, 4, 5);

_list.reverse($list); // (5, 4, 3, 2, 1)

order-numbers-low-high($list)

Sorts a list of numbers from lowest to highest.

Parameters:

• $list: the list to sort.

@use "@littlemissrobot/sass-functions/lib/list" as _list;

$list: (2, 1, 5, 3, 4);

_list.order-numbers-low-high($list); // (1, 2, 3, 4, 5)

Map

These functions are namespace with map_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.map_includes($map, color);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/lib/map" as _map;

_map.includes($map, color);

collect($maps...)

The standard map-merge function only lets you merge 2 maps. This function makes use of the method, but merges as many maps together as you want.

Parameters:

• $maps: any amount of maps to merge together

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$map1: (
    display: flex;
    justify-content: center,
    align-items: center,
);

$map2: (
    font-size: 16px,
    line-height: 24px,
);

$map3: (
    color: white,
    background-color: black,
);

_map.collect($map1, $map2, $map3);
// result: (
//  display: flex;
//  justify-content: center,
//  align-items: center,
//  font-size: 16px,
//  line-height: 24px,
//  color: white,
//  background-color: black,
// );

get($map, $path)

Retrieve a value from a map which can contain mulitple more maps with values. Pass a path as a string, where each key is seperated by a space. Each key within that string represents the keys until you reach a certain value within the map.

Parameters:

• $map: The map to retrieve the value from
• $path: The path of keys to the value

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$colors: (
    brand: (
        primary: black,
        secondary: white
    ),
    typo: (
        title: (
            h1: black,
            h2: red,
            h3: blue
        ),
        text: (
            p: black,
            small: (
                base: gray,
                inverse: white,
            ),
        )
    )
);

_map.get($colors, "brand primary"); // black
_map.get($colors, "typo title h1"); // black
_map.get($colors, "typo text small base"); // gray

filter-by-list($map, $list)

Generate a new map of items, based on the values within the list, which represent the keys in the map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new map from

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (viewport-7, viewport-9);
$list2: (viewport-3, viewport-9, viewport-12);

_map.filter-by-list($breakpoints, $list1);
// result: (
//  viewport-7: 720px,
//  viewport-9: 992px,
// );

_map.filter-by-list($breakpoints, $list2);
// result: (
//  viewport-3: 360px,
//  viewport-9: 992px,
//  viewport-12: 1200px,
// );

filter-keys-by-list($map, $list)

Generate a new list of keys from a map, based on the items within a map and a list representing the values in that map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new list from

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (720px, 992px);
$list2: (360px, 992px, 1200px);

_map.filter-keys-by-list($breakpoints, $list1);
// result: (viewport-7, viewport-9);

_map.filter-keys-by-list($breakpoints, $list2);
// result: (viewport-3, viewport-9, viewport-12);

filter-values-by-list($map, $list)

Generate a new list of values from a map, based on the items within a map and a list representing the keys in that map.

Parameters:

• $map: The map with the keys and values
• $list: The list to create a new list from

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

$list1: (viewport-7, viewport-9);
$list2: (viewport-3, viewport-9, viewport-12);

_map.filter-values-by-list($breakpoints, $list1);
// result: (720px, 992px);

_map.filter-values-by-list($breakpoints, $list2);
// result: (360px, 992px, 1200px);

includes($map, $key)

Checks if a map contains a certain key.

Parameters:

• $map: The map to search
• $key: The item to search for

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.includes($breakpoints, viewport-7); // true
_map.includes($breakpoints, viewport-2); // false

is-numbers-order-low-high($map)

Checks if the numbers, as values, in the map are ordered lowest to highest.

Parameters:

• $map: the map which contains the keys with its number.

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$map1: (
    viewport-7: 720px,
    viewport-3: 360px,
    viewport-9: 960px
);

$map2: (
    viewport-3: 360px,
    viewport-7: 720px,
    viewport-9: 960px
);

_map.is-numbers-order-low-high($map1); // false
_map.is-numbers-order-low-high($map2); // true

none-destructive-merge($parent-map, $child-map)

Merge 2 maps together, but respect and preserve the order of the keys in $parent-map and attack any unique keys at the end.

Parameters:

• $parent-map: The first map to merge
• $child-map: The second map to merge

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$map1: (
    font-size: 16px,
    line-height: 24px,
);

$map2: (
  line-height: 30px,
  font-size: 24px,
);

_map.none-destructive-merge($map1, $map2);

reverse($map)

Reverses the order of the items within a map.

Parameters:

• $map: the map to reverse the order of the items.

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.reverse($breakpoints);
// result: (
//  viewport-12: 1200px
//  viewport-9: 992px,
//  viewport-7: 720px,
//  viewport-4: 480px,
//  viewport-3: 360px,
// );

trim($map, $target)

Trims a map to a certain target key. Returns a new map that is trimmed down until the key is met.

Parameters:

• $map: the map to trim
• $target: the target key to trim the map to.

@use "@littlemissrobot/sass-functions/lib/map" as _map;

$breakpoints: (
    viewport-3: 360px,
    viewport-4: 480px,
    viewport-7: 720px,
    viewport-9: 992px,
    viewport-12: 1200px
);

_map.trim($breakpoints, viewport-7);
// result: (
//   viewport-3: 360px,
//   viewport-4: 480px,
//   viewport-7: 720px
// );

Math

These functions are namespace with math_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.math_pow(8, 2);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/lib/math" as _math;

_math.pow(8, 2);

round-decimal($value, $amount)

Round a number's value after the comma (decimals) to a certain amount.

Parameters:

• $value: The number and its decimals to round
• $target: The target amount to round the decimals to

@use "@littlemissrobot/sass-functions/lib/math" as _math;

_math.round-decimal(1.12345, 2); // 1.12
_math.round-decimal(1.123456789, 5); // 1.12346

pow($number, $exponent)

Power function / exponent operator which accepts positive, negative (integer, float) exponents.

Parameters:

• $number: The number to apply the exponent operator to
• $exponent: The exponent used ont he number

@use "@littlemissrobot/sass-functions/lib/math" as _math;

_math.pow(2, 8); // 256
_math.pow(4, 2); // 16

randomize($min, $max)

Generate a random number between a minimum and maximum value.

Parameters:

• $min: The minimum number to randomize a number between
• $max: The maximum number to randomize a number between

@use "@littlemissrobot/sass-functions/lib/math" as _math;

_math.randomize(0, 10); // 4
_math.randomize(0, 10); // 5
_math.randomize(2, 8); // 6
_math.randomize(2, 8); // 7

Number

These functions are namespace with number_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.number_strip-unit(16px);

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.strip-unit(16px);

is-integer($value)

Check if a number is of type integer (no decimals).

Parameters:

• $value: The value to check

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.is-integer("sass-functions"); // false
_number.is-integer(20); // true
_number.is-integer(20.5); // false

strip-unit($value)

Removes the unit from a value.

Parameters:

• $value: The number to remove the unit from

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.strip-unit(10px); // 10
_number.strip-unit(7rem); // 7

is-number($value)

Checks whether or not the passed value is a number. Very similar to is-integer, but this value can have decimals.

Parameters:

• $value: The number to validate

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.is-number(10px); // true
_number.is-number(7rem); // true
_number.is-number(2.5px); // true
_number.is-number("sass-functions"); // false
_number.is-number(center); // false

px-em($value, $base)

Converts a pixel value to em.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.px-em(16px); // 1em
_number.px-em(10px, 16px); // 0.625em
_number.px-em(32px); // 2em
_number.px-em(20px, 10px); // 2em

px-rem($value, $base)

Converts a pixel value to rem.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.px-rem(16px); // 1rem
_number.px-rem(10px, 16px); // 0.625rem
_number.px-rem(32px); // 2rem
_number.px-rem(20px, 10px); // 2rem

rem-px($value, $base)

Converts a rem value to px.

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.rem-px(1rem); // 16px
_number.rem-px(2rem); // 32px
_number.rem-px(1rem, 10px); // 10px
_number.rem-px(2rem, 10px); // 20px

px($value, $base)

Converts a value to a value in px. Supported conversions (at the moment) are:

• from rem to px
• from em to px

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.rem(16px, 16px); // 1rem
_number.rem(32px); // 2rem

rem($value, $base)

Converts a value to a value in rem. Supported conversions (at the moment) are:

• from px to rem

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.rem(16px, 16px); // 1rem
_number.rem(32px); // 2rem

em($value, $base)

Converts a value to a value in em. Supported conversions (at the moment) are:

• from px to em

Parameters:

• $value: The value to convert
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.em(16px, 16px); // 1em
_number.em(32px); // 2em

convert($value, $to, $base)

Converts a value from unit value to another. Supported conversions (at the moment) are:

• From px to:
  • rem
  • em
• From rem to:
  • px

Parameters:

• $value: The value to convert
• $to: The unit the value should be converted to
• $base (optional): The base font-size on the body, by default is 16.

@use "@littlemissrobot/sass-functions/lib/number" as _number;

_number.convert(16px, rem, 16px); // 1rem
_number.convert(1rem, px, 16px); // 16px

String

These functions are namespace with string_:

@use "@littlemissrobot/sass-functions" as _functions;

_functions.string_includes("Functions", "F");

Or can be included through the partial:

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.includes("Functions", "F");

escape($value)

Escapes a value and adds extra slashes to special characters. This can be useful for creating a class with special characters.

Parameters:

• $value: The number to escape

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.escape(100%); // 100\%
_string.escape(l-grid__col:12/12); // l-grid__col\:12\/12

includes($string, $characters)

Check if string contains certain characters. Returns a boolean.

Parameters:

• $string: The string to search
• $characters: The characters to search for

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.escape(100%); // 100\%
_string.escape(l-grid__col:12/12); // l-grid__col\:12\/12

replace($string, $search, $replace)

Replace a certain part of a string by another string.

Parameters:

• $string: The string containing the characters to replace
• $search: The characters to search for
• $replace: The characters to replace the searched with

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.replace("sass-functions", "sass", "dart-sass"); // dart-sass-functions

split($string, $separator)

Create a list from a string by defining a character to split the string at.

Parameters:

• $string: The string to split
• $separator: The character to split the string at

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.split("sass-functions", "-"); // (sass, functions)

to($string, $separator)

Converts a value to a string

Parameters:

• $value: The value to convert to

@use "@littlemissrobot/sass-functions/lib/string" as _string;

_string.to(10px); // "10px"