Utils

Module Settings

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

Map Properties

Change modules $config

Examples

General example

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

Parameters

Require

• $config

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

Parameters

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

Parameters

Require

• require-list-has()

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

Parameters

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

Parameters

Get a config option

Examples

Example usage

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

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

Parameters

Returns

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)

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

Returns

Throw

• ULU: Unable to find

Require

• get()

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

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

Require

• get()

Selects a value based on a condition (Ternary Function)

• To replace SASS if() which is deprecated see
• Eagerly evaluates arguments (use native @if or if(sass()... if you need lazy evaluation).

Examples

Example usage

.test {
  color: ulu.utils-when(true, red, blue)
}

.test {
  color: red;
}

Parameters

Returns

Related Links

• https://sass-lang.com/documentation/breaking-changes/if-function/

Provide a default when value type is not correct

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

Returns

Returns number unit info, and strips the unit

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

Returns

Throw

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

Require

• strip-unit()

Adds unit to unitless number

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

Returns

Checks if two numbers are the same unit

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

Returns

Reusable merge method

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

Returns true/false if map has property

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

Returns

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

Require

• map-merge()

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

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

Provides fallback values from the same map

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

Require

• get()

Checks if a map contains one or more of the keys

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

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

Examples

Example usage

Parameters

Returns

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

Parameters

Require

• when()

Replaces all or one occurrence of a string within a string

Parameters

Require

• when()

Remove an item from a list (not map)

• Used for excluding things or as general utility

Parameters

Returns

Remove an item from a list (not map)

• Used for excluding things or as general utility

Parameters

Returns

Join a list with a separator

Parameters

Returns

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

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

Returns

Throw

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

Require

• when()

Resolve the top spacing value for margin/padding like arguments

Examples

Example of getting top value

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

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

Parameters

Returns

Require

• get()
• get-spacing()

Resolve the right spacing value for margin/padding like arguments

Examples

Example of getting right value

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

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

Parameters

Returns

Require

• get()
• get-spacing()

Resolve the bottom spacing value for margin/padding like arguments

Examples

Example of getting bottom value

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

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

Parameters

Returns

Require

• get()
• get-spacing()

Resolve the left spacing value for margin/padding like arguments

Examples

Example of getting left value

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

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

Parameters

Returns

Require

• get()
• get-spacing()

Strips the unit from the number

• Normally this shouldn't be needed

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)

Parameters

Returns

Require

• $sizes

Convert from pixel to em

Parameters

Returns

Calculates the hypotenuse of a triangle

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

Parameters

Returns

Get's the info about a box shadow

Parameters

Returns

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

Parameters

Returns

Require

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

Determines if value passed is a list

Parameters

Returns

Determines if value passed is a map

Parameters

Returns

Determines if value passed is a number

Parameters

Returns

Determines if value passed is a string

Parameters

Returns

Determines if value passed is a color

Parameters

Returns

Returns true if number passed is even

• Allows unit and unitless numbers

Parameters

Returns

Throw

• Expected Number, got #{ $number }

Require

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

Returns true if number passed is odd

Parameters

Returns

Require

• is-even()

Always returns a map

Parameters

Returns

Require

• when()
• is-map()

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

Parameters

Returns

Throw

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

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

Parameters

Returns

Throw

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

Require

• is-end()

For legacy aspect ratio conversion

• For a given value if it's a percentage number convert to css aspect ratio like 16/9

Parameters

Returns

Require

• is-number()
• number-info()
• get()
• is-string()