@ulu/frontend 0.1.0-beta.8 → 0.1.0-beta.81

package/scss/_element.scss

@@ -69,6 +69,8 @@ $config: (
   "ul-list-style-type":               disc,
   "ul-list-style-type-2":             circle,
   "ul-list-style-type-3":             square,
+  "cap-color" :                       "accent",
+  "cap-size" :                        5px
 ) !default;
 
 /// Rule style map, redefine defaults or add to
@@ -114,9 +116,10 @@ $rule-margins: (
 
 /// Sets rule margins
 /// @param {Map} $changes Map of changes
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 
-@mixin set-rule-margins($changes) {
-  $rule-margins: map.merge($rule-margins, $changes) !global;
+@mixin set-rule-margins($changes, $merge-mode: null) {
+  $rule-margins: utils.map-merge($rule-margins, $changes, $merge-mode) !global;
 }
 
 /// Get a rule style
@@ -290,4 +293,107 @@ $rule-margins: (
     white-space: normal;
     width: auto;
   }
+}
+
+
+/// Layout utility to add a colored bar (cap) to an element's edge, positioned over the element and its border
+/// - You need to set position (relative, fixed) on parent
+/// @param {String} $side The side to place the cap (top, bottom, left, right)
+/// @param {Map} $options Options for the appearance of the cap
+/// @param {Color} $options.color [$config.cap-color] The color for the end cap
+/// @param {Number} $options.size [$config.cap-size] The width/height of the cap
+/// @param {Number} $options.offset [0] A positive number of the amount the cap should extend outside the box (to account for border-width) 
+/// @param {Number} $options.border-radius [null] An optional border-radius to apply to the outward-facing edges of the cap (used to match parent)
+/// @param {Boolean} $before [true] Whether or not to use the ::before element (if not uses :after)
+
+@mixin cap(
+  $side,
+  $options: (),
+  $before: true,
+) {
+  $defaults: (
+    "color" : get("cap-color"), 
+    "size" : get("cap-size"), 
+    "offset" : 0, 
+    "color-hover" : null,
+    "border-radius" : null,
+    "padding-adjust" : null,
+  );
+  $config: map.merge($defaults, $options);
+  $element: if($before, "::before", "::after");
+
+  &#{ $element } {
+    content: "";
+    position: absolute;
+    display: block;
+  }
+
+  @include cap-appearance($side, $config, $before);
+}
+
+
+
+/// Provides the appearance styles for a given cap
+/// - If an option is not provided it won't be output
+/// - This is used to update the caps styling (states, modifiers, etc)
+/// @param {String} $side The side to place the cap (top, bottom, left, right)
+/// @param {Map} $options Options for the appearance of the cap (see options from element.cap)
+/// @param {Boolean} $before Whether or not to use the ::before element (if not uses :after)
+
+@mixin cap-appearance(
+  $side,
+  $options: (),
+  $before: true
+) {
+  $element: if($before, "::before", "::after");
+  $size: map.get($options, "size");
+  $offset: map.get($options, "offset");
+  $border-radius: map.get($options, "border-radius");
+  $padding-adjust: map.get($options, "padding-adjust");
+  
+  $end: $side == "top" or $side == "bottom";
+  $position: if($offset, 0 - $offset, null);
+
+  @if ($padding-adjust and $size) {
+    padding-#{ $side }: calc($padding-adjust + $size);
+  }
+
+  &#{ $element } {
+    background-color: color.get(map.get($options, "color"));
+    #{ $side }: $position;
+
+    @if $end {
+      left: $position;
+      right: $position;
+      height: $size;
+    } @else {
+      top: $position;
+      bottom: $position;
+      width: $size;
+    }
+    
+    @if $border-radius {
+      @if $end {
+        border-#{ $side }-left-radius: $border-radius;
+        border-#{ $side }-right-radius: $border-radius;
+      } @else {
+        border-top-#{ $side }-radius: $border-radius;
+        border-bottom-#{ $side }-radius: $border-radius;
+      }
+    }
+  }
+}
+
+/// Add backdrop-filter blur
+/// @param {CssUnit} $amount [get("backdrop-blur")] Amount to blur
+/// 
+@mixin backdrop-filter-blur($amount: get("backdrop-blur")) {
+  backdrop-filter: blur($amount);
+}
+
+/// Accessibly hide focus ring while keeping it when it's required
+@mixin focus-ring-required-only() {
+  &:focus:not(:focus-visible) {
+    outline: none;
+  }
 }

package/scss/_layout.scss

@@ -7,6 +7,7 @@
 @use "sass:meta";
 @use "utils";
 @use "breakpoint";
+@use "color";
 
 /// Module Settings
 /// @type Map
@@ -215,10 +216,7 @@ $containers: (
   $breakpoints: map.get($container, "breakpoints");
   
   $width: map.get($container, "width");
-  // @debug $specific-breakpoint;
-  // @if $specific-breakpoint {
-  //   @debug $container;
-  // }
+
   @if ($width == null) {
     $width: 100%;
   }
@@ -243,14 +241,14 @@ $containers: (
 /// Prints clearfix styles
 
 @mixin clearfix() {
-  &:before,
-  &:after {
+  &::before,
+  &::after {
     content: "";
     display: table;
     flex-basis: 0; // Flexbox, clear fix for pseudo elements in Safari
     order: 1;
   }
-  &:after { 
+  &::after { 
     clear: both; 
   }
 }
@@ -267,6 +265,7 @@ $containers: (
 /// Layout utility for absolute (zero on all sides)
 /// - Probably helpful for gzip if we use this when these exact styles are needed
 ///   so they are identical for compression
+/// @param {Boolean} $set-size [false] Whether or not to use sizes to fill the space (height/width 100%) versus setting bottom and right to 0)
 @mixin absolute-fill($set-size: false) {
   position: absolute;
   top: 0;
@@ -278,4 +277,4 @@ $containers: (
     width: 100%;
     height: 100%;
   }
-}
+}

package/scss/_units.scss

@@ -27,13 +27,14 @@ $config: (
 
 /// Update the units config
 /// @param {Map} $changes A map to merge into the color palette
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
 /// @example scss Setting the error and type color
 ///   @include ulu.units-set((
 ///     "default" : 1.5em
 ///   ));
 
-@mixin set($changes) {
-  $config: map.merge($config, $changes) !global;
+@mixin set($changes, $merge-mode: null) {
+  $config: utils.map-merge($config, $changes, $merge-mode) !global;
 }
 
 /// Get a unit by name (preset) or number (multiplier of base)

package/scss/_utils.scss

@@ -20,7 +20,7 @@ $config: (
   "debug-maps": true,
   "file-header-comments": true,
   "responsive-change": 0.5vw,
-  "pixel-em-base" : 16px
+  "pixel-em-base" : 16px,
 ) !default;
 
 /// Change modules $config
@@ -34,8 +34,11 @@ $config: (
 
 /// Get a config option
 /// @param {Map} $name Name of property
-/// @example scss - General example
-///   @include ulu.utils-get("property");
+/// @example scss {compile} Example usage
+///   .test-em-to-pixel {
+///     width: ulu.utils-get("pixel-em-base");
+///   }
+/// @return {Dimension} 
 
 @function get($name) {
   @return require-map-get($config, $name, 'utils');
@@ -46,6 +49,11 @@ $config: (
 /// @param {Map} $map The map to get the value from
 /// @param {String} $key The key in the map to get value from
 /// @param {String} $context The context of using this function for debugging help
+/// @example scss {compile} Example usage
+///   .test-require-map {
+///     $test-map: ("test-font-size": 12px);
+///     font-size: ulu.utils-require-map-get($test-map, "test-font-size");
+///   }
 /// @return {*} The value from the map
 
 @function require-map-get($map, $key, $context: "unknown") {
@@ -93,6 +101,21 @@ $config: (
 /// Returns true if we should include something (map of booleans)
 /// @param {String} $name Name of item to see if it's included
 /// @param {Map} $includes Map of includes
+/// @example scss {compile} 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;
+///     }
+///   }
 
 @function included($name, $includes) {
   $value: map.get($includes, $name);
@@ -113,10 +136,21 @@ $config: (
   }
 }
 
-// Provide a default when value type is not correct
+/// Provide a default when value type is not correct
 /// @param {String} $type type of value it should be
 /// @param {String} $value the value to provide if it is that type
 /// @param {String} $fallback the fallback value
+/// @example scss {compile} 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);
+///   }
+/// @return {CssValue} Returns the value or the fallback.
 
 @function if-type($type, $value, $fallback) {
   @if meta.type-of($value) == $type {
@@ -126,31 +160,112 @@ $config: (
   }
 }
 
-// Returns number unit info, and strips the unit
+/// Returns number unit info, and strips the unit
 /// @param {String} $number Number to get meta info for
-/// @return {Map} With properties (unit, value)
+/// @return {Map} With properties (unit, value, invalid [true/false if not number])
+/// @example scss {compile} 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);
+///   }
+///
 
-@function number-info($number) {
-  $is-number: meta.type-of($number) != 'number';
-  $is-unitless: math.is-unitless($number);
-  @if ($is-unitless or not $is-number) {
+@function number-info($number, $errors: false) {
+
+  @if (meta.type-of($number) == 'number') {
+    $is-unitless: math.is-unitless($number);
     @return (
-      "unit": null,
-      "value": $number 
+      "unit": if($is-unitless, null, math.unit($number)),
+      "value": if($is-unitless, $number, strip-unit($number)),
+      "invalid" : false
     );
+
   } @else {
+    @if ($errors) {
+      @error "Expected Number, got #{ meta.type-of($number) } for #{ $number }";
+    }
     @return (
-      "unit" : math.unit($value), 
-      "value": math.div($number, ($number * 0 + 1))
+      "unit": null,
+      "value": $number,
+      "invalid" : true
     );
   }
 }
 
+/// Adds unit to unitless number
+/// @param {Number} $number The unitless number to add unit to
+/// @param {String} $unit The unit to add to number
+/// @return {String} Number with unit attached (can't be used in maths)
+/// @example scss {compile} Example usage
+///   $number: 12;
+///   $unit: "px";
+///   $number-with-unit: ulu.utils-add-unit($number, $unit);
+///   .add-unit-result {
+///     content: $number-with-unit;
+///   }
+///
+
+@function add-unit($number, $unit) {
+  @return $number + string.unquote($unit);
+}
+
+/// Checks if two numbers are the same unit
+/// @param {Number} $number 
+/// @param {String} $other-number 
+/// @return {Boolean} Whether they have the same unit type
+/// Could be made into multiple arguments in future if needed 
+/// @example scss {compile} 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);
+///   }
+///
+
+@function units-match($number, $other-number) {
+  @return math.unit($number) == math.unit($other-number);
+}
+
 /// Reusable merge method 
 /// @param {Map} $original Source map 
 /// @param {Map} $changes Changes to merge into source map
 /// @param {String} $mode How to merge changes (merge [defualt], deep, or overwrite)
-/// @return {Map} New map with changes
+/// @example scss {compile} 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);
+///   }
+///
 
 @function map-merge($original, $changes, $mode: null) {
   @if ($mode == "deep") {
@@ -166,6 +281,20 @@ $config: (
 /// @param {Map} $map Source map 
 /// @param {String} $key Property to check for
 /// @return {Boolean}
+/// @example scss {compile} 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");
+///   }
+///
 
 @function map-has($map, $key) {
   @if (meta.type-of($map) != "map") {
@@ -189,6 +318,17 @@ $config: (
 
 /// Utility for providing fallbacks, the first truthy value (non false or null) will be returned
 /// @return {*} The first truthy value
+/// @example scss {compile} 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);
+///   }
+///
 
 @function fallback($args...) {
   @each $arg in $args {
@@ -200,6 +340,19 @@ $config: (
 }
 
 /// Provides fallback values from the same map
+/// @return {*} 
+/// @example scss {compile} 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");
+///   }
+///
+
 @function map-fallback($map, $properties...) {
   @each $prop in $properties {
     $value: map.get($map, $prop);
@@ -216,6 +369,18 @@ $config: (
 /// @param {List} $keys The list of keys to check for
 /// @param {List} $options Options for how this behaves
 /// @param {List} $options.with-value Requires that at least one of the map entries from the list has a value other than null
+/// @example scss {compile} Example usage
+///   $map : (
+///     "has-key" : true
+///   );
+///   $keys : (
+///     "has-key",
+///     "needs-key",
+///   );
+///   .map-contains-any-result {
+///     content: ulu.utils-map-contains-any($map, $keys);
+///   }
+///
 @function map-contains-any($map, $keys, $options: ()) {
   @if (meta.type-of($map) != "map") {
     @error "map-contains-any(): Incorrect type for $map (should be map)";
@@ -242,6 +407,8 @@ $config: (
 /// @param {*} $value The value that may need the fallback
 /// @param {Map} $lookup Map of properties to functions (use sass:meta > meta.get-function to populate)
 /// @return {*} The user's original value, or if the value is true get the default value from the provided function
+/// @example scss {compile} Example usage
+///
 
 @function function-fallback($prop, $value, $lookup) {
   $arguments: null;
@@ -448,9 +615,21 @@ $config: (
 /// Strips the unit from the number
 /// - Normally this shouldn't be needed
 /// @link https://stackoverflow.com/questions/12328259/how-do-you-strip-the-unit-from-any-number-in-sass/12335841#12335841 Original source (Miriam Suzanne)
+/// @example scss {compile} Example usage
+///   .test {
+///     line-height: ulu.utils-strip-unit(4rem);
+///   }
 
 @function strip-unit($value) {
-  @return math.div($value, ($value * 0 + 1));
+  @if (is-number($value)) {
+    @if (math.is-unitless($value)) {
+      @return $value;
+    } @else {
+      @return math.div($value, ($value * 0 + 1));
+    }
+  } @else {
+    @error "Expected number, got #{ $value }";
+  }
 }
 
 /// Calculate the size of something at a given scale (percentage/exponential)
@@ -485,4 +664,189 @@ $config: (
 ) {
   #{ $property } : $value;
   #{ $property } : calc(#{ $value } + #{ $responsive-change });
+}
+
+/// Calculates the hypotenuse of a triangle
+/// - Can be used to get length between two corners of a rectangle
+/// @param {Number} $width The width of the triangle
+/// @param {Number} $height The height of the triangle
+/// @return {Number} Hypotenuse of a triangle
+
+@function hypotenuse($width, $height) {
+  @return math.sqrt(math.pow($width, 2) + math.pow($height, 2));
+}
+
+/// Get's the info about a box shadow 
+/// @param {List} $shadow The box shadow property (ie. 0 0 4px red)
+/// @return {Map} Map with info about the shadow with the following keys (inset, offset-x, offset-y, blur, spread, color)
+/// @throw When shadow is not type list
+
+@function box-shadow-info($shadow) {
+  @if (meta.type-of($shadow) != "list") {
+    @error "Box shadow passed is not correct type (list)";
+  }
+  $result: (
+    "inset": false,
+    "offset-x": 0,
+    "offset-y": 0,
+    "blur": 0,
+    "spread": 0,
+    "color": null,
+  );
+
+  $number-keys: ("offset-x", "offset-y", "blur", "spread");
+  $number-index: 1;
+
+  @each $value in $shadow {
+    $type: meta.type-of($value);
+    @if $type == "color" {
+      $result: map.merge($result, ("color": $value));
+    } @else if $type == "string" and $value == inset {
+      $result: map.merge($result, ("inset": true));
+    } @else if $type == "number" and $number-index <= 4 {
+      // Add each back in by key in the order they appear
+      // if not found it's the default
+      $result: map.merge($result, (list.nth($number-keys, $number-index): $value));
+      $number-index: $number-index + 1;
+    }
+  }
+  
+  @return $result;
+}
+
+/// 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
+/// @param {List} $shadow The box shadow property (ie. 0 0 4px red)
+/// @param {String} $side 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
+/// @return {Number} The size the shadow extends past it's box
+
+@function box-shadow-extent($shadow, $side: null) {
+  $info: box-shadow-info($shadow);
+  $extent: map.get($info, "spread") + map.get($info, "blur");
+  $offset-x: map.get($info, "offset-x");
+  $offset-y: map.get($info, "offset-y");
+  @if (not $side) {
+    @return $extent;
+  } @else {
+    @if ($side == "top") {
+      @return $extent - $offset-y;
+    } @else if ($side == "bottom") {
+      @return $extent + $offset-y;
+    } @else if ($side == "left") {
+      @return $extent - $offset-x;
+    } @else if ($side == "right") {
+      @return $extent + $offset-x;
+    }
+  }
+}
+
+/// Determines if value passed is a list
+/// @param {*} $value Value to check
+/// @return {Boolean} Whether the item was type list
+
+@function is-list($value) {
+  @return meta.type-of($value) == "list";
+}
+
+/// Determines if value passed is a map
+/// @param {*} $value Value to check
+/// @return {Boolean} Whether the item was type map
+
+@function is-map($value) {
+  @return meta.type-of($value) == "map";
+}
+
+/// Determines if value passed is a number
+/// @param {*} $value Value to check
+/// @return {Boolean} Whether the item was type number
+
+@function is-number($value) {
+  @return meta.type-of($value) == "number";
+}
+
+/// Determines if value passed is a string
+/// @param {*} $value Value to check
+/// @return {Boolean} Whether the item was type string
+
+@function is-string($value) {
+  @return meta.type-of($value) == "string";
+}
+
+/// Determines if value passed is a color
+/// @param {*} $value Value to check
+/// @return {Boolean} Whether the item was type color
+
+@function is-color($value) {
+  @return meta.type-of($value) == "color";
+}
+
+
+
+// /// Determines if value passed is a bool
+// /// @param {*} $value Value to check
+// /// @return {Boolean} Whether the item was type bool
+
+// @function is-bool($value) {
+//   @return meta.type-of($value) == "bool";
+// }
+
+// /// Determines if value passed is a null
+// /// @param {*} $value Value to check
+// /// @return {Boolean} Whether the item was type null
+
+// @function is-null($value) {
+//   @return meta.type-of($value) == "null";
+// }
+
+/// Returns true if number passed is even
+/// - Allows unit and unitless numbers
+/// @param {Number} $number The number to check
+/// @return {Boolean} Whether or not it is an even number
+
+@function is-even($number) {
+  @if (is-number($number)) {
+    @return strip-unit($number) % 2 == 0;
+  } @else {
+    @error "Expected Number, got #{ $number }";
+  }
+}
+
+/// Returns true if number passed is odd
+/// @param {Number} $number The number to check
+/// @return {Boolean} Whether or not it is an odd number
+
+@function is-odd($number) {
+  @return not is-even($number);
+}
+
+/// Always returns a map
+/// @param {*} $value The value to check if is map
+/// @return {Map} The $value if it was a map, else empty map
+
+@function ensure-map($value) {
+  @return if(is-map($value), $value, ());
+}
+
+/// Returns true if edge passed is an end (top/bottom)
+/// @param {String} $edge The edge string to test
+/// @return {Boolean} Whether the edge was an end (versus side/x-axis)
+/// @throw If $edge is not a valid value (not top/bottom/left/right)
+
+@function is-end($edge) {
+  @if ($edge == "top" or $edge == "bottom") {
+    @return true;
+  } @else if ($edge == "left" or $edge == "right") {
+    @return false;
+  } @else {
+    @error "Expected side to be top/bottom/left/right, got #{ $edge }";
+  }
+}
+
+/// Returns true if edge passed is an side (left/right)
+/// @param {String} $edge The edge string to test
+/// @return {Boolean} Whether the edge was an side (versus end/y-axis)
+/// @throw If $edge is not a valid value (not top/bottom/left/right)
+
+@function is-side($edge) {
+  @return not is-end($edge);
 }