Utils

Variables

Module Settings

$config: (
  "debug-maps": true,
  "file-header-comments": true,
  "responsive-change": 0.5vw,
  "pixel-em-base" : 16px,
);

File Information

• File: _utils.scss
• Group: utils
• Type: variable
• Lines (comments): 12-17
• Lines (code): 19-24

Map Properties

Name	Type	Default	Description
debug-maps	Boolean	true	Enable or disable debug map output
file-header-comments	Boolean	true	Enable or disable module/file header comments
responsive-change	Number	0.5vw	Default responsive amount to modify items using responsive-property mixin
pixel-em-base	Number	16px	Default base pixel font size for pixel-to-em

Mixins

Change modules $config

File Information

• File: _utils.scss
• Group: utils
• Type: mixin
• Lines (comments): 26-29
• Lines (code): 31-33

Examples

General example

@include ulu.utils-set(( "property" : value ));

Parameters

Name	Type	Description
$changes	Map	Map of changes

Require

• $config

Ensure a value is present in the list, throw an error if not found

File Information

• File: _utils.scss
• Group: utils
• Type: mixin
• Lines (comments): 71-75
• Lines (code): 77-87

Parameters

Name	Type	Description
$list	List	The map to get the value from
$value	String	The value to search for in the list
$context	String	The context of using this function for debugging help
$warn	String	Display warning instead of throwing error

Require that the list only is only made up of allowed items

File Information

• File: _utils.scss
• Group: utils
• Type: mixin
• Lines (comments): 89-93
• Lines (code): 95-99

Parameters

Name	Type	Description
$allowed	List	The list of allowed items
$list	String	The list to test allowed against
$context	String	The context of using this function for debugging help
$warn	String	Display warning instead of throwing error

Require

• require-list-has()

Returns true if we should include something (used for output checking)

File Information

• File: _utils.scss
• Group: utils
• Type: mixin
• Lines (comments): 125-127
• Lines (code): 129-137

Parameters

Name	Type	Description
$context	List	The root area of the framework this file comes from
$name	List	The name of the specific area/file (optional)

Provides user with a fallback for a calc that's just an enhancement

File Information

• File: _utils.scss
• Group: utils
• Type: mixin
• Lines (comments): 662-665
• Lines (code): 667-674

Parameters

Name	Type	Description
$property	String	The CSS property to set
$value	*	The value to set on the property
$responsive-change	Css	The amount to change (vw or vh units) (combined with unit past)

Functions

Get a config option

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 35-41
• Lines (code): 43-45

Examples

Example usage

.test-em-to-pixel {
  width: ulu.utils-get("pixel-em-base");
}

.test-em-to-pixel {
  width: 16px;
}

Parameters

Name	Type	Description
$name	Map	Name of property

Returns

Type
Dimension

Require

• require-map-get()
• $config

Get a required value from a map, throw an error if not found

• Remember that that maps cannot intentionally use null (use false instead, if trying to avoid output if not configured)

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 47-57
• Lines (code): 59-69

Examples

Example usage

.test-require-map {
  $test-map: ("test-font-size": 12px);
  font-size: ulu.utils-require-map-get($test-map, "test-font-size");
}

.test-require-map {
  font-size: 12px;
}

Parameters

Name	Type	Description
$map	Map	The map to get the value from
$key	String	The key in the map to get value from
$context	String	The context of using this function for debugging help

Returns

Type	Description
*	The value from the map

Throw

• ULU: Unable to find

Require

• get()

Returns true if we should include something (map of booleans)

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 101-118
• Lines (code): 120-123

Examples

Example usage

$include-styles : (
  "h2" : true,
  "h3" : false
);
@if(ulu.utils-included("h2", $include-styles)) {
  h2 {
    font-size: 24px;
  }
}
@if(ulu.utils-included("h3", $include-styles)) {
  h3 {
    font-size: 18px;
  }
}

h2 {
  font-size: 24px;
}

Parameters

Name	Type	Description
$name	String	Name of item to see if it's included
$includes	Map	Map of includes

Require

• get()

Provide a default when value type is not correct

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 139-153
• Lines (code): 155-161

Examples

Example usage

$user-accent-color: #FE5F55;
$user-error-color: "##C6ECAE";
$default-color: #777DA7;
.accent-color {
  background-color: ulu.utils-if-type("color", $user-accent-color, $default-color);
}
.error-color {
  background-color: ulu.utils-if-type("color", $user-error-color, $default-color);
}

.accent-color {
  background-color: #FE5F55;
}

.error-color {
  background-color: #777DA7;
}

Parameters

Name	Type	Description
$type	String	type of value it should be
$value	String	the value to provide if it is that type
$fallback	String	the fallback value

Returns

Type	Description
CssValue	Returns the value or the fallback.

Returns number unit info, and strips the unit

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 163-175
• Lines (code): 177-197

Examples

Example usage

$size-info: ulu.utils-number-info(24px);
$size-info-invalid: ulu.utils-number-info("Twenty Four Pixels");
.number-info-result {
  content: meta.inspect($size-info);
}
.number-info-invalid-result {
  content: meta.inspect($size-info-invalid);
}

.number-info-result {
  content: ("unit": "px", "value": 24, "invalid": false);
}

.number-info-invalid-result {
  content: ("unit": null, "value": "Twenty Four Pixels", "invalid": true);
}

Parameters

Name	Type	Description
$number	String	Number to get meta info for

Returns

Type	Description
Map	With properties (unit, value, invalid [true/false if not number])

Throw

• Expected Number, got #{ meta.type-of($number) } for #

Require

• strip-unit()

Adds unit to unitless number

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 199-210
• Lines (code): 212-214

Examples

Example usage

$number: 12;
$unit: "px";
$number-with-unit: ulu.utils-add-unit($number, $unit);
.add-unit-result {
  content: $number-with-unit;
}

.add-unit-result {
  content: 12px;
}

Parameters

Name	Type	Description
$number	Number	The unitless number to add unit to
$unit	String	The unit to add to number

Returns

Type	Description
String	Number with unit attached (can't be used in maths)

Checks if two numbers are the same unit

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 216-231
• Lines (code): 233-235

Examples

Example usage

$number-1: 12px;
$number-2: 12px;
$number-3: 12rem;
.positive-result {
  content: ulu.utils-units-match($number-1, $number-2);
}
.negative-result {
  content: ulu.utils-units-match($number-1, $number-3);
}

.positive-result {
  content: true;
}

.negative-result {
  content: false;
}

Parameters

Name	Type
$number	Number
$other-number	String

Returns

Type	Description
Boolean	Whether they have the same unit type
Could be made into multiple arguments in future if needed

Reusable merge method

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 237-268
• Lines (code): 270-278

Examples

Example usage

$map-1: (
  "inner-map" : (
    "color" : "green",
    "secondary-color" : "green"
  ),
  "color" : "green",
  "secondary-color" : "green"
);
$map-2: (
  "inner-map" : (
    "color" : "red"
  ),
  "color" : "red",
);
.result-default {
  $merged-map: ulu.utils-map-merge($map-1, $map-2);
  content: meta.inspect($merged-map);
}
.result-deep {
  $merged-map-deep: ulu.utils-map-merge($map-1, $map-2, "deep");
  content: meta.inspect($merged-map-deep);
}
.result-overwrite {
  $merged-map-overwrite: ulu.utils-map-merge($map-1, $map-2, "overwrite");
  content: meta.inspect($merged-map-overwrite);
}

.result-default {
  content: ("inner-map": ("color": "red"), "color": "red", "secondary-color": "green");
}

.result-deep {
  content: ("inner-map": ("color": "red", "secondary-color": "green"), "color": "red", "secondary-color": "green");
}

.result-overwrite {
  content: ("inner-map": ("color": "red"), "color": "red");
}

Parameters

Name	Type	Description
$original	Map	Source map
$changes	Map	Changes to merge into source map
$mode	String	How to merge changes (merge [defualt], deep, or overwrite)

Returns true/false if map has property

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 280-297
• Lines (code): 299-304

Examples

Example usage

$map-1 : (
  "has-key" : true
);
$map-2 : (
  "missing-key" : true
);
.map-1 {
  content: ulu.utils-map-has($map-1, "has-key");
}
.map-2 {
  content: ulu.utils-map-has($map-2, "has-key");
}

.map-1 {
  content: true;
}

.map-2 {
  content: false;
}

Parameters

Name	Type	Description
$map	Map	Source map
$key	String	Property to check for

Returns

Type
Boolean

Throw

• map-has(): Incorrect type for $map (should be map)

Require

• get()

Repeatable pattern in core

Deprecated

Left in for compatibility, will be removed, use map-merge with mode

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 306-307
• Lines (code): 309-317

Require

• map-merge()

Utility for providing fallbacks, the first truthy value (non false or null) will be returned

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 319-331
• Lines (code): 333-340

Examples

Example usage

$fallback-text: "No input received";
.user-name:after {
  $user-name: "Johnny";
  content: ulu.utils-fallback($user-name, $fallback-text);
}
.user-birthdate:after {
  $user-birthdate: null;
  content: ulu.utils-fallback($user-birthdate, $fallback-text);
}

.user-name:after {
  content: "Johnny";
}

.user-birthdate:after {
  content: "No input received";
}

Returns

Type	Description
*	The first truthy value

Provides fallback values from the same map

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 342-354
• Lines (code): 356-364

Examples

Example usage

$map: (
  "name": doug,
  "gpa": "3",
  "grade": "B",
);
.fallback-map {
  // iterates through properties until it finds one that is a key in the map. 
  content: ulu.utils-map-fallback($map, "gpa", "grade", "average");
}

.fallback-map {
  content: "3";
}

Returns

Type
*

Require

• get()

Checks if a map contains one or more of the keys

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 367-383
• Lines (code): 384-403

Examples

Example usage

$map : (
  "has-key" : true
);
$keys : (
  "has-key",
  "needs-key",
);
.map-contains-any-result {
  content: ulu.utils-map-contains-any($map, $keys);
}

.map-contains-any-result {
  content: true;
}

Parameters

Name	Type	Description
$map	Map	The map to check
$keys	List	The list of keys to check for
$options	List	Options for how this behaves
$options.with-value	List	Requires that at least one of the map entries from the list has a value other than null

Throw

• map-contains-any(): Incorrect type for $map (should be map)
• map-contains-any(): Incorrect type for $keys (should be list)

Require

• get()

Helps in providing a dynamic fallback for modules whose defaults should come from another

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 405-411
• Lines (code): 413-439

Examples

Example usage

Parameters

Name	Type	Description
$prop	String	Property trying to get fallback for
$value	*	The value that may need the fallback
$lookup	Map	Map of properties to functions (use sass:meta > meta.get-function to populate)

Returns

Type	Description
*	The user's original value, or if the value is true get the default value from the provided function

Throw

• Arguments must be a list, use single list for single argument ie

Require

• get()

If the value passed is equal to true use the default, else return the value

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 441-443
• Lines (code): 444-446

Parameters

Name	Type	Description
$value	*	The value to check
$default	*	The value to return when true

Replaces all or one occurrence of a string within a string

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 448-452
• Lines (code): 454-470

Parameters

Name	Type	Description
$string	String	String to operate on
$find	String	String to find within string
$replace	String	String to replace found strings
$all	Boolean	Default true replace all matches, if false replace only first

Remove an item from a list (not map)

• Used for excluding things or as general utility

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 472-476
• Lines (code): 478-486

Parameters

Name	Type	Description
$list	List	String to operate on
$remove	*	Element in the list to remove

Returns

Type	Description
List	New list with item removed

Remove an item from a list (not map)

• Used for excluding things or as general utility

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 488-492
• Lines (code): 494-502

Parameters

Name	Type	Description
$list	List	String to operate on
$remove	List	List elements that should each be removed

Returns

Type	Description
List	New list with item removed

Join a list with a separator

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 504-508
• Lines (code): 510-525

Parameters

Name	Type	Description	Default
$list	List	List to join
$separator	String	Separator to use	", "
$to-string	Boolean	The resulting list with join separator will be converted to a string (false will return new list with separators added between original items	true

Returns

Type	Description
String	List

Resolve spacing info (ie. margin/padding like arguments)

• Will normalize the argument that may be shorthand or single value
• Used for programmatic things with single value config options for padding/margin

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 527-542
• Lines (code): 544-560

Examples

Example of getting left value

$user-padding: (1em, 2em, 4em);
$spacing: get-spacing($user-padding);
// $spacing ("top" : 1em, "right" : 2em, "bottom" : 4em, "left" : 2em);

.example {
  left: map.get($spacing, "left");
  // left = 2em
}

Parameters

Name	Type	Description
$value	`Number	List`

Returns

Type	Description
Map	Map with spacing info for each side (top, right, bottom, left)

Throw

• Spacing has more than 4 arguments (not correct shorthand)

Resolve the top spacing value for margin/padding like arguments

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 562-571
• Lines (code): 573-575

Examples

Example of getting top value

$user-padding: (1em, 2em, 4em);

.example {
  top: get-spacing-top($user-padding);
  // top = 2em
}

Parameters

Name	Type	Description
$value	`Number	List`

Returns

Type
Number

Require

• get()
• get-spacing()

Resolve the right spacing value for margin/padding like arguments

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 577-586
• Lines (code): 588-590

Examples

Example of getting right value

$user-padding: (1em, 2em, 4em);

.example {
  right: get-spacing-right($user-padding);
  // right = 2em
}

Parameters

Name	Type	Description
$value	`Number	List`

Returns

Type
Number

Require

• get()
• get-spacing()

Resolve the bottom spacing value for margin/padding like arguments

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 592-601
• Lines (code): 603-605

Examples

Example of getting bottom value

$user-padding: (1em, 2em, 4em);

.example {
  bottom: get-spacing-bottom($user-padding);
  // bottom = 2em
}

Parameters

Name	Type	Description
$value	`Number	List`

Returns

Type
Number

Require

• get()
• get-spacing()

Resolve the left spacing value for margin/padding like arguments

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 607-616
• Lines (code): 618-620

Examples

Example of getting left value

$user-padding: (1em, 2em, 4em);

.example {
  left: get-spacing-left($user-padding);
  // left = 2em
}

Parameters

Name	Type	Description
$value	`Number	List`

Returns

Type
Number

Require

• get()
• get-spacing()

Strips the unit from the number

• Normally this shouldn't be needed

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 622-628
• Lines (code): 630-640

Examples

Example usage

.test {
  line-height: ulu.utils-strip-unit(4rem);
}

.test {
  line-height: 4;
}

Throw

• Expected number, got #{ $value }

Related Links

• Original source (Miriam Suzanne)

Require

• is-number()

Calculate the size of something at a given scale (percentage/exponential)

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 642-647
• Lines (code): 649-651

Parameters

Name	Type	Description
$base	Number	The number the scale starts at
$ratio	Number	The amount the scale changes over one set
$sizes	Number	The number of steps in the scale
$size	Number	The step you are trying to calculate

Returns

Type
Number

Require

• $sizes

Convert from pixel to em

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 653-656
• Lines (code): 658-660

Parameters

Name	Type	Description
$pixels	Number	The number the scale starts at
$base	Number	How many pixels equal 1em

Returns

Type	Description
Number	Em Conversion

Calculates the hypotenuse of a triangle

• Can be used to get length between two corners of a rectangle

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 676-680
• Lines (code): 682-684

Parameters

Name	Type	Description
$width	Number	The width of the triangle
$height	Number	The height of the triangle

Returns

Type	Description
Number	Hypotenuse of a triangle

Get's the info about a box shadow

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 686-689
• Lines (code): 691-722

Parameters

Name	Type	Description
$shadow	List	The box shadow property (ie. 0 0 4px red)

Returns

Type	Description
Map	Map with info about the shadow with the following keys (inset, offset-x, offset-y, blur, spread, color)

Throw

• Box shadow passed is not correct type (list)

Get's the extent (how far the shadow extends past the box's edge)

• This will only work on box-shadows that have matching units for the numbers

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 724-728
• Lines (code): 730-748

Parameters

Name	Type	Description
$shadow	List	The box shadow property (ie. 0 0 4px red)
$side	String	Optionally pass the side of box to get extend for, if not specified offsets are ignored and just the extent of the shadow is passed

Returns

Type	Description
Number	The size the shadow extends past it's box

Require

• box-shadow-info()
• get()

Determines if value passed is a list

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 750-752
• Lines (code): 754-756

Parameters

Name	Type	Description
$value	*	Value to check

Returns

Type	Description
Boolean	Whether the item was type list

Determines if value passed is a map

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 758-760
• Lines (code): 762-764

Parameters

Name	Type	Description
$value	*	Value to check

Returns

Type	Description
Boolean	Whether the item was type map

Determines if value passed is a number

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 766-768
• Lines (code): 770-772

Parameters

Name	Type	Description
$value	*	Value to check

Returns

Type	Description
Boolean	Whether the item was type number

Determines if value passed is a string

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 774-776
• Lines (code): 778-780

Parameters

Name	Type	Description
$value	*	Value to check

Returns

Type	Description
Boolean	Whether the item was type string

Determines if value passed is a color

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 782-784
• Lines (code): 786-788

Parameters

Name	Type	Description
$value	*	Value to check

Returns

Type	Description
Boolean	Whether the item was type color

Returns true if number passed is even

• Allows unit and unitless numbers

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 808-811
• Lines (code): 813-819

Parameters

Name	Type	Description
$number	Number	The number to check

Returns

Type	Description
Boolean	Whether or not it is an even number

Throw

• Expected Number, got #{ $number }

Require

• is-number()
• strip-unit()

Returns true if number passed is odd

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 821-823
• Lines (code): 825-827

Parameters

Name	Type	Description
$number	Number	The number to check

Returns

Type	Description
Boolean	Whether or not it is an odd number

Require

• is-even()

Always returns a map

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 829-831
• Lines (code): 833-835

Parameters

Name	Type	Description
$value	*	The value to check if is map

Returns

Type	Description
Map	The $value if it was a map, else empty map

Require

• is-map()

Returns true if edge passed is an end (top/bottom)

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 837-840
• Lines (code): 842-850

Parameters

Name	Type	Description
$edge	String	The edge string to test

Returns

Type	Description
Boolean	Whether the edge was an end (versus side/x-axis)

Throw

• Expected side to be top/bottom/left/right, got #{ $edge }

Returns true if edge passed is an side (left/right)

File Information

• File: _utils.scss
• Group: utils
• Type: function
• Lines (comments): 852-855
• Lines (code): 857-859

Parameters

Name	Type	Description
$edge	String	The edge string to test

Returns

Type	Description
Boolean	Whether the edge was an side (versus end/y-axis)

Throw

• If $edge is not a valid value (not top/bottom/left/right)

Require

• is-end()