@ulu/frontend 0.1.0-beta.66 → 0.1.0-beta.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.1.0-beta.66",
+  "version": "0.1.0-beta.67",
   "description": "Modular Sass Theming Library",
   "browser": "js/index.js",
   "main": "index.js",

package/scss/_breakpoint.scss

@@ -31,8 +31,6 @@ $config: (
 }
 
 /// Get a config option
-/// @compiler
-///   @use "index" as ulu;
 /// @example scss {compile} Example usage
 ///   .test-get {
 ///     font-size: ulu.breakpoint-get("base");
@@ -70,15 +68,13 @@ $sizes: (
 }
 
 /// Get all breakpoint sizes
-/// @return {Map} Map of breakpoints (equivalent to $sizes)
 /// @compiler
-///   @use "index" as ulu;
-///   @use "sass:map";
 /// @example scss {compile} Example usage
-///   .test-get {
+///   .test-get-sizes {
 ///     $sizes: ulu.breakpoint-get-sizes();
 ///     height: map.get($sizes, "medium");
 ///   }
+/// @return {Map} Map of breakpoints (equivalent to $sizes)
 
 @function get-sizes() {
   @return $sizes;
@@ -86,14 +82,25 @@ $sizes: (
 
 /// Get a specific breakpoint's raw value/size
 /// @param {String} $size The name of the size to get
+/// @compiler
+/// @example scss {compile} Example usage
+///   .test-get-size {
+///     height: ulu.breakpoint-get-size("medium");
+///   }
 /// @return {Number} The sizes value
- 
+
 @function get-size($size) {
   @return utils.require-map-get($sizes, $size, "breakpoint size");
 }
 
 /// Get a specific breakpoint's size's value and optionally specify max to get the ending/max value for a breakpoint
 /// @param {Boolean} $max [false] Get the max value
+/// @compiler
+/// @example scss {compile} Example usage
+///   .test-get-size-value {
+///     height: ulu.breakpoint-get-size-value("medium", true);
+///     max-height: ulu.breakpoint-get-size-value("medium");
+///   }
 /// @return {Number} The value for the given size
 
 @function get-size-value($size, $max: false) {
@@ -107,6 +114,20 @@ $sizes: (
 /// Check if a specific size exist
 /// @param {String} $name The breakpoint size to check if exists
 /// @return {Boolean} 
+/// @example scss {compile} Example usage
+///   .test-exists {
+///     @if(ulu.breakpoint-exists("medium")) {
+///       @include ulu.breakpoint-min("medium") {
+///         padding: 2rem;
+///       }
+///     }
+///     // The below content doesn't print because the size doesn't exist.
+///     @if(ulu.breakpoint-exists("too-large")) {
+///       @include ulu.breakpoint-min("too-large") {
+///         padding: 20000rem;
+///       }
+///     }
+///   }
 
 @function exists($name) {
   $size: map.get($sizes, $name);

package/scss/_utils.scss

@@ -34,12 +34,11 @@ $config: (
 
 /// Get a config option
 /// @param {Map} $name Name of property
-/// @compiler
-///   @use "index" as ulu;
 /// @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');
@@ -50,14 +49,12 @@ $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
-/// @return {*} The value from the map
-/// @compiler
-///   @use "index" as ulu;
 /// @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") {
   // $value: map.get($map, $key);
@@ -104,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);
@@ -124,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 {
@@ -137,9 +160,19 @@ $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, 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, $errors: false) {
 
@@ -167,6 +200,14 @@ $config: (
 /// @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);
@@ -176,7 +217,18 @@ $config: (
 /// @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 
+/// 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);
@@ -186,7 +238,34 @@ $config: (
 /// @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") {
@@ -202,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") {
@@ -225,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 {
@@ -236,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);
@@ -252,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)";
@@ -278,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;
@@ -484,8 +615,6 @@ $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)
-/// @compiler
-///   @use "index" as ulu;
 /// @example scss {compile} Example usage
 ///   .test {
 ///     line-height: ulu.utils-strip-unit(4rem);

package/scss/components/_counter-list.scss

@@ -3,6 +3,8 @@
 /// Outputs a styled list with counters
 
 @use "sass:map";
+@use "sass:selector" as sassSelector;
+
 @use "../utils";
 @use "../selector";
 @use "../color";
@@ -21,6 +23,7 @@
 /// @prop {CssUnit} counter-font-size [1.2em] The font-size of the counter text.
 /// @prop {Color|String} counter-color [white] The text color of the counter. Accepts color names or hex codes.
 /// @prop {Color|String} counter-background-color ["accent"] The background color of the counter. Refers to a color in the color module.
+/// @prop {String} extra-selector [null] Additional selectors to include table styling.
 
 $config: (
   "margin" : (2rem 0),
@@ -36,6 +39,7 @@ $config: (
   "counter-font-family" : null,
   "counter-color" : white,
   "counter-background-color" : "accent",
+  "extra-selector" : null
 ) !default;
 
 /// Change modules $config
@@ -67,16 +71,26 @@ $config: (
 
 @mixin styles {
   $prefix: selector.class("counter-list");
-  $width: get("counter-width");
-  $height: utils.fallback(get("counter-height"), $width);
+  $prefix-item: sassSelector.parse("#{ $prefix }__item");
+  $extra-selector: get("extra-selector");
+
+  $selector: $prefix;
+  $selector-item: sassSelector.parse("#{ $prefix } > li, #{ $prefix-item }");
 
-  #{ $prefix } {
+  @if ($extra-selector) {
+    $selector: sassSelector.parse("#{ $prefix }, #{ $extra-selector }");
+    $selector-item: sassSelector.parse("#{ $selector-item }, #{ $extra-selector } > li");
+  }
+
+  #{ $selector } {
     margin: get("margin");
     counter-reset: ulu-counter-list;
   }
 
-  #{ $prefix } > li,
-  #{ $prefix }__item {
+  #{ $selector-item } {
+    $width: get("counter-width");
+    $height: utils.fallback(get("counter-height"), $width);
+
     display: flex;
     gap: get("counter-gap");
     align-items: get("align-items");
@@ -121,13 +135,13 @@ $config: (
   // Modifiers
   #{ $prefix }--alphabetical {
     & > li::before,
-    & > #{ $prefix }__item::before {
+    & > #{ $prefix-item }::before {
       content: counter(ulu-counter-list, upper-alpha);
     }
   }
   #{ $prefix }--numeric {
     & > li::before,
-    & > #{ $prefix }__item::before {
+    & > #{ $prefix-item }::before {
       content: counter(ulu-counter-list, numeric);
     }
   }