Jump To:

  1. Variables
    1. $config
  2. Mixins
    1. set()
    2. require-list-has()
    3. require-list-contains()
    4. file-header()
    5. responsive-property()
  3. Functions
    1. get()
    2. require-map-get()
    3. included()
    4. if-type()
    5. number-info()
    6. add-unit()
    7. map-merge()
    8. map-has()
    9. map-merge-or-overwrite()
    10. fallback()
    11. map-fallback()
    12. map-contains-any()
    13. function-fallback()
    14. string-replace()
    15. list-remove()
    16. list-without()
    17. list-join()
    18. get-spacing()
    19. get-spacing-top()
    20. get-spacing-right()
    21. get-spacing-bottom()
    22. get-spacing-left()
    23. strip-unit()
    24. ratio-scale-size()
    25. pixel-to-em()
    26. hypotenuse()
    27. box-shadow-info()
    28. box-shadow-extent()
    29. is-list()
    30. is-map()
    31. is-number()
    32. is-string()
    33. is-color()
    34. is-even()
    35. is-odd()
    36. ensure-map()
    37. is-end()
    38. is-side()
  4. CSS
    1. // Could be made into multiple arguments in future if needed

Utils

Basic utility functions/mixins used throughout system

Variables

$config

Variable Type: Map

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

set()

Mixin

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

require-list-has()

Mixin

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): 74-78
  • Lines (code): 80-90

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-list-contains()

Mixin

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: mixin
  • Lines (comments): 92-96
  • Lines (code): 98-102

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

file-header()

Mixin

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: mixin
  • Lines (comments): 113-115
  • Lines (code): 117-125

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)

responsive-property()

Mixin

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: mixin
  • Lines (comments): 526-529
  • Lines (code): 531-538

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()

Function

Get a config option

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 35-42
  • Lines (code): 44-46

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

Require

require-map-get()

Function

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): 48-60
  • Lines (code): 62-72

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

included()

Function

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 104-106
  • Lines (code): 108-111

Parameters

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

Require

if-type()

Function
File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 128-130
  • Lines (code): 132-138

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

number-info()

Function
File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 141-142
  • Lines (code): 144-164

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

add-unit()

Function

Adds unit to unitless number

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 166-169
  • Lines (code): 171-173

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)

map-merge()

Function

Reusable merge method

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 185-189
  • Lines (code): 191-199

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

Type Description
Map New map with changes

map-has()

Function

Returns true/false if map has property

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 201-204
  • Lines (code): 206-211

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

map-merge-or-overwrite()

Function

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): 213-214
  • Lines (code): 216-224

Require

fallback()

Function

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): 226-227
  • Lines (code): 229-236

Returns

Type Description
* The first truthy value

map-fallback()

Function

Provides fallback values from the same map

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 238-238
  • Lines (code): 239-247

Require

map-contains-any()

Function

Checks if a map contains one or more of the keys

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 250-254
  • Lines (code): 255-274

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

function-fallback()

Function

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): 276-280
  • Lines (code): 282-308

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

string-replace()

Function

Replaces all or one occurrence of a string within a string

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 310-314
  • Lines (code): 316-332

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

list-remove()

Function

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): 334-338
  • Lines (code): 340-348

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

list-without()

Function

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): 350-354
  • Lines (code): 356-364

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

list-join()

Function

Join a list with a separator

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 366-370
  • Lines (code): 372-387

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

get-spacing()

Function

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): 389-404
  • Lines (code): 406-422

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)

get-spacing-top()

Function

Resolve the top spacing value for margin/padding like arguments

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 424-433
  • Lines (code): 435-437

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-spacing-right()

Function

Resolve the right spacing value for margin/padding like arguments

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 439-448
  • Lines (code): 450-452

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-spacing-bottom()

Function

Resolve the bottom spacing value for margin/padding like arguments

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 454-463
  • Lines (code): 465-467

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-spacing-left()

Function

Resolve the left spacing value for margin/padding like arguments

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 469-478
  • Lines (code): 480-482

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

strip-unit()

Function

Strips the unit from the number

  • Normally this shouldn't be needed
File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 484-492
  • Lines (code): 494-504

Examples

Example usage

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

Throw

  • Expected number, got #{ $value }

Require

ratio-scale-size()

Function

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 506-511
  • Lines (code): 513-515

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

pixel-to-em()

Function

Convert from pixel to em

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 517-520
  • Lines (code): 522-524

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

hypotenuse()

Function

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): 540-544
  • Lines (code): 546-548

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

box-shadow-info()

Function

Get's the info about a box shadow

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 550-553
  • Lines (code): 555-586

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)

box-shadow-extent()

Function

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): 588-592
  • Lines (code): 594-612

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

is-list()

Function

Determines if value passed is a list

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

Parameters

Name Type Description
$value * Value to check

Returns

Type Description
Boolean Whether the item was type list

is-map()

Function

Determines if value passed is a map

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 622-624
  • Lines (code): 626-628

Parameters

Name Type Description
$value * Value to check

Returns

Type Description
Boolean Whether the item was type map

is-number()

Function

Determines if value passed is a number

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 630-632
  • Lines (code): 634-636

Parameters

Name Type Description
$value * Value to check

Returns

Type Description
Boolean Whether the item was type number

is-string()

Function

Determines if value passed is a string

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 638-640
  • Lines (code): 642-644

Parameters

Name Type Description
$value * Value to check

Returns

Type Description
Boolean Whether the item was type string

is-color()

Function

Determines if value passed is a color

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 646-648
  • Lines (code): 650-652

Parameters

Name Type Description
$value * Value to check

Returns

Type Description
Boolean Whether the item was type color

is-even()

Function

Returns true if number passed is even

  • Allows unit and unitless numbers
File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 672-675
  • Lines (code): 677-683

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-odd()

Function

Returns true if number passed is odd

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 685-687
  • Lines (code): 689-691

Parameters

Name Type Description
$number Number The number to check

Returns

Type Description
Boolean Whether or not it is an odd number

Require

ensure-map()

Function

Always returns a map

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 693-695
  • Lines (code): 697-699

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-end()

Function

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 701-704
  • Lines (code): 706-714

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 }

is-side()

Function

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

File Information
  • File: _utils.scss
  • Group: utils
  • Type: function
  • Lines (comments): 716-719
  • Lines (code): 721-723

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

CSS

// Could be made into multiple arguments in future if needed

@function units-match($number, $other-number) {#css-// Could be made into multiple arguments in future if needed

@function units-match($number, $other-number)}

Css

Checks if two numbers are the same unit

{
  @return math.unit($number) == math.unit($other-number);
 }
File Information
  • File: _utils.scss
  • Group: utils
  • Type: css
  • Lines (comments): 175-178
  • Lines (code): 181-723