locomotive-boilerplate/assets/styles/tools/_functions.scss

// ==========================================================================
// Tools / Functions
// ==========================================================================

// Check if the given value is a number in pixel
//
// @param  {Number} $number - The value to check
// @return {Boolean}

@function is-pixel-number($number) {
    @return type-of($number) == number and unit($number) == "px";
}

// Converts the given pixel value to its EM quivalent.
//
// @param  {Number} $size                     - The pixel value to convert.
// @param  {Number} $base [$font-size] - The assumed base font size.
// @return {Number} Scalable pixel value in EMs.

@function em($size, $base: $font-size) {
    @if not is-pixel-number($size) {
        @error "`#{$size}` needs to be a number in pixel.";
    }

    @if not is-pixel-number($base) {
        @error "`#{$base}` needs to be a number in pixel.";
    }

    @return ($size / $base) * 1em;
}

// Converts the given pixel value to its REM quivalent.
//
// @param  {Number} $size                     - The pixel value to convert.
// @param  {Number} $base [$font-size] - The assumed base font size.
// @return {Number} Scalable pixel value in REMs.

@function rem($size, $base: $font-size) {

    @if not is-pixel-number($size) {
        @error "`#{$size}` needs to be a number in pixel.";
    }

    @if not is-pixel-number($base) {
        @error "`#{$base}` needs to be a number in pixel.";
    }

    @return ($size / $base) * 1rem;
}

// Retrieves the z-index from the {@see $layers master list}.
//
// @link on http://css-tricks.com/handling-z-index/
//
// @param  {string} $layer    The name of the z-index.
// @param  {number} $modifier A positive or negative modifier to apply
//     to the returned z-index value.
// @throw  Error if the $layer does not exist.
// @throw  Warning if the $modifier might overlap another master z-index.
// @return {number}           The computed z-index of $layer and $modifier.

@function z($layer, $modifier: 0) {
    @if not map-has-key($z-indexes, $layer) {
        @error "Unknown master z-index layer: #{$layer}";
    }

    @if ($modifier >= 50 or $modifier <= -50) {
        @warn "Modifier may overlap the another master z-index layer: #{$modifier}";
    }

    $index: map-get($z-indexes, $layer);

    @return $index + $modifier;
}

// Converts a number to a percentage.
//
// @alias  percentage()
// @link   http://sassdoc.com/annotations/#alias
// @param  {Number} $number - The value to convert.
// @return {Number} A percentage.

@function span($number) {
    @return percentage($number);
}

// Checks if a list contains a value(s).
//
// @link   https://github.com/thoughtbot/bourbon/blob/master/core/bourbon/validators/_contains.scss
// @param  {List} $list   - The list to check against.
// @param  {List} $values - A single value or list of values to check for.
// @return {Boolean}
// @access private

@function list-contains(
    $list,
    $values...
) {
    @each $value in $values {
        @if type-of(index($list, $value)) != "number" {
            @return false;
        }
    }

    @return true;
}

// Resolve whether a rule is important or not.
//
// @param  {Boolean}     $flag - Whether a rule is important (TRUE) or not (FALSE).
// @return {String|Null} Returns `!important` or NULL.

@function important($flag: false) {
    @if ($flag == true) {
        @return !important;
    } @else if ($important == false) {
        @return null;
    } @else {
        @error "`#{$flag}` needs to be `true` or `false`.";
    }
}

// Determine if the current context is for a WYSIWYG editor.
//
// @requires {String} $context - The global context of the stylesheet.
// @return   {Boolean} If the $context is set to "editor".

@function is-editor() {
    @return ('editor' == $context);
}

// Determine if the current context is for the front-end.
//
// @requires {String} $context - The global context of the stylesheet.
// @return   {Boolean} If the $context is set to "frontend".

@function is-frontend() {
    @return ('frontend' == $context);
}

$context: 'frontend' !default;



/**
 * Calculate grid space
 * @param  {number} $number The percentage spacer
 * @return {number} in calc
 */
@function grid-space($percentage, $offset: 0) {
    // @return calc(#{$percentage} * (100vw - 2 * var(--grid-margin)) - (1 - #{$percentage}) * var(--grid-gutter) + #{$offset} * var(--grid-gutter));
    @return calc(#{$percentage} * (100vw - 2 * var(--grid-margin, 0px)) - (1 - #{$percentage}) * var(--grid-gutter, 0px) + #{$offset} * var(--grid-gutter, 0px));
}


/**
 * Calculate vh percentage from number
 * @param  {number} $number The percentage number
 * @return {number} in vh
 */
@function vh($number) {
    @return calc(#{$number} * var(--vh, 1vh));
}

/**
 * Remove the unit of a length
 * @param {Number} $number - Number to remove unit from
 * @return {Number} - Unitless number
 */
@function strip-unit($number) {
  @if type-of($number) == 'number' and not unitless($number) {
    @return $number / ($number * 0 + 1);
  }

  @return $number;
}


/**
 * Responsive font size
 * @param {Number} $min-size - Minimum font size in pixel
 * @param {Number} $max-size - Maximum font size in pixel
 * @param {Number} $breakpoint - The breakpoint
 * @return {Number} - Clamped font size based on breakpoint
 */
@function responsive-type($min-size, $max-size, $breakpoint) {
    @return clamp($min-size, calc(#{strip-unit($max-size)}/#{strip-unit(#{$breakpoint})} * 100vw), $max-size);
}