@ulu/frontend 0.0.23 → 0.1.0-beta.1

package/scss/_utils.scss

@@ -1,5 +1,6 @@
 ////
 /// @group utils
+/// Basic utility functions/mixins used throughout system
 ////
 
 @use "sass:map";
@@ -10,33 +11,38 @@
 
 /// Module Settings
 /// @type Map
-/// @prop {Boolean} $config.debug-maps Debugs include map print outs
-/// @prop {Boolean} $config.file-header-comments Remove comment headers if you'd like
+/// @prop {Boolean} debug-maps [true] Enable or disable debug map output
+/// @prop {Boolean} file-header-comments [true] Enable or disable module/file header comments
+/// @prop {Number} responsive-change [0.5vw] Default responsive amount to modify items using responsive-property mixin
+/// @prop {Number} pixel-em-base [16px] Default base pixel font size for pixel-to-em
 
 $config: (
   "debug-maps": true,
-  "file-header-comments": true
+  "file-header-comments": true,
+  "responsive-change": 0.5vw,
+  "pixel-em-base" : 16px
 ) !default;
 
 /// Change modules $config
 /// @param {Map} $changes Map of changes
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.set(( "property" : value ));
+/// @example scss - General example
+///   @include ulu.utils-set(( "property" : value ));
+
 @mixin set($changes) {
   $config: map.merge($config, $changes) !global;
 }
 
 /// Get a config option
 /// @param {Map} $name Name of property
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.get("property");
+/// @example scss - General example
+///   @include ulu.utils-get("property");
 
 @function get($name) {
   @return require-map-get($config, $name, 'utils');
 }
 
 /// Get a required value from a map, throw an error if not found
-/// - Remeber that that maps cannot intentionally use null (use false instead, if trying to avoid output if unconfigured)
+/// - Remember that that maps cannot intentionally use null (use false instead, if trying to avoid output if not configured)
 /// @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
@@ -58,21 +64,29 @@ $config: (
 /// @param {List} $list The map to get the value from
 /// @param {String} $value The value to search for in the list
 /// @param {String} $context The context of using this function for debugging help
+/// @param {String} $warn Display warning instead of throwing error
 
-@mixin require-list-has($list, $value, $context: "unknown") {
-  $index: list.index($list, $value) != null;
+@mixin require-list-has($list, $value, $context: "unknown", $warn: false) {
+  $index: list.index($list, $value);
   @if ($index == null) {
-    @error 'ULU: Unable to find item "#{ $value }" in #{ $context } list.';
+    $message: 'ULU: Unable to find item "#{ $value }" in #{ $context } list.';
+    @if ($warn) {
+      @warn $message;
+    } @else {
+      @error $message;
+    }
   }
 }
 
 /// Require that the list only is only made up of allowed items
 /// @param {List} $allowed The list of allowed items
 /// @param {String} $list The list to test allowed against
+/// @param {String} $context The context of using this function for debugging help
+/// @param {String} $warn Display warning instead of throwing error
 
-@mixin require-list-contains($allowed, $list, $context: "unknown") {
+@mixin require-list-contains($allowed, $list, $context: "unknown", $warn: false) {
   @each $item in $list {
-    @include require-list-has($allowed, $item, $context);
+    @include require-list-has($allowed, $item, $context, $warn);
   }
 }
 
@@ -148,8 +162,20 @@ $config: (
   }
 }
 
+/// Returns true/false if map has property
+/// @param {Map} $map Source map 
+/// @param {String} $key Property to check for
+/// @return {Boolean}
+
+@function map-has($map, $key) {
+  @if (meta.type-of($map) != "map") {
+    @error "map-has(): Incorrect type for $map (should be map)";
+  }
+  @return map.get($map, $key) != null;
+}
+
 /// Repeatable pattern in core
-/// @deprecated Left in for compatability, will be removed, use map-merge with mode
+/// @deprecated Left in for compatibility, will be removed, use map-merge with mode
 
 @function map-merge-or-overwrite($original, $changes, $deep: false, $overwrite: false) {
   $mode: null;
@@ -184,6 +210,33 @@ $config: (
   @return null;
 }
 
+
+/// Checks if a map contains one or more of the keys
+/// @param {Map} $map The map to check
+/// @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
+@function map-contains-any($map, $keys, $options: ()) {
+  @if (meta.type-of($map) != "map") {
+    @error "map-contains-any(): Incorrect type for $map (should be map)";
+  }
+  @if (meta.type-of($keys) != "list") {
+    @error "map-contains-any(): Incorrect type for $keys (should be list)";
+  }
+  @each $key in $keys {
+    @if map.has-key($map, $key) {
+      @if map.get($options, "with-value") {
+        @if map.get($map, $key) != null {
+          @return true;
+        }
+      } @else {
+        @return true;
+      }
+    }
+  }
+  @return false;
+}
+
 /// Helps in providing a dynamic fallback for modules whose defaults should come from another
 /// @param {String} $prop Property trying to get fallback for
 /// @param {*} $value The value that may need the fallback
@@ -191,17 +244,34 @@ $config: (
 /// @return {*} The user's original value, or if the value is true get the default value from the provided function
 
 @function function-fallback($prop, $value, $lookup) {
+  $arguments: null;
   // If there was already a value return it else resolve through passed function
   @if ($value == true)  {
-    $fn: map.get($lookup, $prop);
-    @if ($fn) {
-      @return meta.call($fn, $prop);
+    $function: map.get($lookup, $prop);
+    // Allow user to pass a nested map to route to another property
+    @if (meta.type-of($function) == "map") {
+      $functionMap: $function;
+      $function: map.get($functionMap, "function");
+      $prop: map.get($functionMap, "property");
+      // Arguments will override everything (allow calling functions with args)
+      $arguments: map.get($functionMap, "arguments");
+    }
+    @if ($function) { 
+      @if ($arguments) {
+        @if (meta.type-of($arguments) == "list") {
+          @return meta.call($function, $arguments...);
+        } @else {
+          @error "Arguments must be a list, use single list for single argument ie '(3,)'";
+        }
+      } @else {
+        @return meta.call($function, $prop);
+      }
     } 
   }
   @return $value;
 }
 
-/// Replaces all or one occurence of a string within a string
+/// Replaces all or one occurrence of a string within a string
 /// @param {String} $string String to operate on
 /// @param {String} $find String to find within string
 /// @param {String} $replace String to replace found strings
@@ -224,3 +294,195 @@ $config: (
     @return $string;
   }
 }
+
+/// Remove an item from a list (not map)
+/// - Used for excluding things or as general utility
+/// @param {List} $list String to operate on
+/// @param {*} $remove Element in the list to remove
+/// @return {List} New list with item removed
+
+@function list-remove($list, $remove) {
+  $new-list: (); 
+  @each $item in $list {
+    @if $item != $remove {
+      $new-list: list.append($new-list, $item); 
+    }
+  }
+  @return $new-list;
+}
+
+/// Remove an item from a list (not map)
+/// - Used for excluding things or as general utility
+/// @param {List} $list String to operate on
+/// @param {List} $remove List elements that should each be removed
+/// @return {List} New list with item removed
+
+@function list-without($list, $removal-list) {
+  $new-list: ();
+  @each $item in $list {
+    @if not list.index($removal-list, $item) { 
+      $new-list: list.append($new-list, $item);
+    }
+  }
+  @return $new-list;
+}
+
+/// Join a list with a separator
+/// @param {List} $list List to join
+/// @param {String} $separator [", "] Separator to use
+/// @param {Boolean} $to-string [true] The resulting list with join separator will be converted to a string (false will return new list with separators added between original items
+/// @return {String|List} If separator was +, the result would be "value1 + value2" or (value1, "+", value2) depending on $to-string argument
+
+@function list-join($list, $separator: ", ", $to-string: true) {
+  $joined: ();
+  $length: list.length($list);
+  @for $i from 1 through $length {
+    $item: list.nth($list, $i);
+    $joined: list.append($joined, $item);
+    @if $i < $length {
+      $joined: list.append($joined, $separator);
+    }
+  }
+  @if ($to-string) {
+    @return #{ $joined };
+  } @else {
+    @return $joined;
+  }
+}
+
+/// 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
+/// 
+/// @param {Number|List} $value The value to resolve (usually a config option)
+/// @example scss 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
+///   }
+/// @return {Map} Map with spacing info for each side (top, right, bottom, left)
+/// @throw If the list length > 4 (incorrect syntax for shorthand)
+
+@function get-spacing($value) {
+  $is-list: meta.type-of($value) == "list";
+  $length: if($is-list, list.length($value), 1);
+  $single: $length == 1;
+  $top: if($is-list, list.nth($value, 1), $value);  // Top is always the same
+
+  @if ($length > 4) {
+    @error "Spacing has more than 4 arguments (not correct shorthand)";
+  }
+
+  @return (
+    "top" :    $top,
+    "right" :  if($single, $top, list.nth($value, 2)),
+    "bottom" : if($single, $top, list.nth($value, if($length >= 3, 3, 1))),
+    "left" :   if($single, $top, list.nth($value, if($length == 4, 4, 2)))
+  );
+}
+
+/// Resolve the top spacing value for margin/padding like arguments
+/// @param {Number|List} $value The value to resolve (usually a config option)
+/// @example scss Example of getting top value
+///   $user-padding: (1em, 2em, 4em);
+/// 
+///   .example {
+///     top: get-spacing-top($user-padding);
+///     // top = 2em
+///   }
+/// @return {Number}
+
+@function get-spacing-top($value) {
+  @return map.get(get-spacing($value), "top");
+}
+
+/// Resolve the right spacing value for margin/padding like arguments
+/// @param {Number|List} $value The value to resolve (usually a config option)
+/// @example scss Example of getting right value
+///   $user-padding: (1em, 2em, 4em);
+/// 
+///   .example {
+///     right: get-spacing-right($user-padding);
+///     // right = 2em
+///   }
+/// @return {Number}
+
+@function get-spacing-right($value) {
+  @return map.get(get-spacing($value), "right");
+}
+
+/// Resolve the bottom spacing value for margin/padding like arguments
+/// @param {Number|List} $value The value to resolve (usually a config option)
+/// @example scss Example of getting bottom value
+///   $user-padding: (1em, 2em, 4em);
+/// 
+///   .example {
+///     bottom: get-spacing-bottom($user-padding);
+///     // bottom = 2em
+///   }
+/// @return {Number}
+
+@function get-spacing-bottom($value) {
+  @return map.get(get-spacing($value), "bottom");
+}
+
+/// Resolve the left spacing value for margin/padding like arguments
+/// @param {Number|List} $value The value to resolve (usually a config option)
+/// @example scss Example of getting left value
+///   $user-padding: (1em, 2em, 4em);
+/// 
+///   .example {
+///     left: get-spacing-left($user-padding);
+///     // left = 2em
+///   }
+/// @return {Number}
+
+@function get-spacing-left($value) {
+  @return map.get(get-spacing($value), "left");
+}
+
+/// 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)
+
+@function strip-unit($value) {
+  @return math.div($value, ($value * 0 + 1));
+}
+
+/// Calculate the size of something at a given scale (percentage/exponential)
+/// @param {Number} $base The number the scale starts at
+/// @param {Number} $ratio The amount the scale changes over one set
+/// @param {Number} $sizes The number of steps in the scale
+/// @param {Number} $size The step you are trying to calculate
+/// @return {Number}
+
+@function ratio-scale-size($base, $ratio, $sizes, $size) {
+  @return $base * math.pow($ratio, math.div($size, $sizes));
+}
+
+/// Convert from pixel to em
+/// @param {Number} $pixels The number the scale starts at
+/// @param {Number} $base How many pixels equal 1em
+/// @return {Number} Em Conversion
+
+@function pixel-to-em($pixels, $base: get("pixel-em-base")) {
+  @return math.div($pixels, $base) + 1em;
+}
+
+/// Provides user with a fallback for a calc that's just an enhancement
+/// @param {String} $property The CSS property to set
+/// @param {*} $value The value to set on the property
+/// @param {Css} $responsive-change The amount to change (vw or vh units) (combined with unit past)
+
+@mixin responsive-property(
+  $property, 
+  $value, 
+  $responsive-change: get("responsive-change")
+) {
+  #{ $property } : $value;
+  #{ $property } : calc(#{ $value } + #{ $responsive-change });
+}

package/scss/base/_color.scss

@@ -1,11 +1,12 @@
 ////
 /// @group color
+/// Outputs color base classes
 ////
 
 @use "../utils";
 @use "../color";
 
-/// Prints color-context styles as base classes (top of stylesheet)
+/// Outputs color-context styles as base classes (top of stylesheet)
 
 @mixin styles {
   @include utils.file-header('base', 'color');

package/scss/base/_elements.scss

@@ -1,5 +1,6 @@
 ////
 /// @group elements
+/// Outputs general HTML element styles (body, a, etc)
 ////
 
 @use "sass:map";
@@ -14,32 +15,36 @@
 
 /// Module Settings
 /// @type Map
-/// @prop {Number} $config.links-state-styling Just color/defaults vs hover/visited/active
+/// @prop {CssValue} details-animation [(UluFadeInDown 350ms ease-in-out)] Animation for the details element when toggled.
+/// @prop {Boolean} link [true] Enables link styling.
+/// @prop {Boolean} link-hover [true] Enables link hover and focus styling.
+/// @prop {Boolean} link-visited [true] Enables visited link styling.
 
 $config: (
+  "details-animation" : (UluFadeInDown 350ms ease-in-out),
   "link" : true,
-  "link:hover" : true,
-  "link:visited" : false
+  "link-hover" : true,
+  "link-visited" : false,
 ) !default;
 
 /// Change modules $config
 /// @param {Map} $changes Map of changes
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.set(( "property" : value ));
+/// @example scss - General example
+///   @include ulu.base-elements-set(( "property" : value ));
 @mixin set($changes) {
   $config: map.merge($config, $changes) !global;
 }
 
 /// Get a config option
 /// @param {Map} $name Name of property
-/// @example scss - General example, replace module-name with module's name
-///   @include module-name.get("property");
+/// @example scss - General example
+///   @include ulu.base-elements-get("property");
 
 @function get($name) {
   @return utils.require-map-get($config, $name, "element [config]");
 }
 
-/// Prints elements base styles
+/// Output the elements base styles
 /// @name base-elements-styles
 /// @example scss
 ///  @include ulu.base-elements-styles();
@@ -47,7 +52,6 @@ $config: (
 @mixin styles {
 
   @include utils.file-header('base', 'elements');
-
   *,
   ::before,
   ::after {
@@ -60,15 +64,7 @@ $config: (
     }
   }
   body {
-    color: color.get('type');
-    background-color: color.get("background");
-    font-family: typography.get("font-family");
-    margin: 0;
-    // Note we are using relative units here instead of setting a 
-    // pixel base like we use to on the HTML
-    // This will allow the user preference in font size
-    // Useful for accessibility
-    @include typography.size("base");
+    @include styles-body();
     @include breakpoint.embed-for-scripts();
   }
   h1, 
@@ -118,6 +114,9 @@ $config: (
   form {
     width: 100%;
   }
+  video {
+    display: block;
+  }
   code,
   kbd,
   samp,
@@ -147,33 +146,30 @@ $config: (
     border-style: none;
   }
   // Not styling ordered lists because they are used in navigation and other UI components
-  ul { 
+  // - Would rather explicitly style numbered lists so menus and things 
+  //   don't have to reset. Usually there's only a few type of in content 
+  //   numbered lists and those are styled via classes or wysiwyg
+  ul,
+  ol { 
     list-style: none; 
   }
-  // Style ordered lists since we don't use them much in the UI components
-  ol {
-    list-style: none; 
-  }
-  
   a {
     // User can disable link styling if they want to add more specific styling
     // and omit this in element base
     @if (get("link")) {
       @include element.link-defaults(
-        $hover: get("link:hover"),
-        $visited: get("link:visited"),
+        $hover: get("link-hover"),
+        $visited: get("link-visited"),
       );
     }
   }
-  // button,
-  // [type="button"],
-  // [type="reset"],
-  // [type="submit"] {
-  //   @include button.reset();
-  // }
-  // For accessible tabs
-  [role="tab"] {
-    cursor: pointer;
+  [disabled],
+  :disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  button[disabled] {
+    pointer-events: none;
   }
   dt { 
     font-weight: bold;
@@ -185,4 +181,34 @@ $config: (
   blockquote {
     margin: 0;
   }
+  @if get("details-animation") {
+    details {
+      &[open] {
+        summary {
+          ~ * {
+            // Prevent issues with opening these programmatically on firefox
+            // - Animation would not be complete in the clone on firefox (looks empty)
+            @media screen {
+              animation: get("details-animation");
+            }
+          }
+        }
+      }
+    }
+  }
+  audio {
+    display: block;
+    margin: 1rem 0;
+  }
+}
+
+@mixin styles-body() {
+  color: color.get('type');
+  background-color: color.get("background");
+  font-family: typography.get("font-family");
+  // Note we are using relative units here instead of setting a 
+  // pixel base like we use to on the HTML
+  // This will allow the user preference in font size
+  // Useful for accessibility
+  @include typography.size("base");
 }

package/scss/base/_index.scss

@@ -1,62 +1,99 @@
 ////
-/// @group all
+/// @group index
+/// Output all base styles
 ////
 
+@forward "root" as root-*;
 @forward "normalize" as normalize-*;
+@forward "print" as print-*;
+@forward "color" as color-*;
 @forward "elements" as elements-*;
 @forward "keyframes" as keyframes-*;
 @forward "typography" as typography-*;
 @forward "layout" as layout-*;
 
-@use "sass:map";
+@use "sass:list";
+
 @use "../utils";
 @use "normalize";
-@use "typography";
+@use "root";
 @use "elements";
+@use "print";
+@use "typography";
 @use "color";
 @use "keyframes";
 @use "layout";
 
-// Used to check against user's includes
+/// Default includes, all modules
+/// @type List
 
-$-all-includes: (
-  "normalize" : true, 
-  "elements" : true, 
-  "keyframes" : true, 
-  "typography" : true,
-  "color" : true,
-  "layout" : true
+$all-includes: (
+  "normalize",
+  "root"
+  "elements," 
+  "print", 
+  "elements", 
+  "keyframes", 
+  "typography",
+  "color",
+  "layout"
 );
 
+/// Current included modules (for output when using styles), defaults to all
+/// @type List
+
+$current-includes: $all-includes;
+
+/// Change default includes (when user prints modules)
+/// - This available as configuration so that it can be configured (to allow easily copying configuration)
+/// @param {List} $includes List of modules by name to be included when styles are printed
+
+@mixin set-includes($includes) {
+  @include utils.require-list-contains($all-includes, $includes, "base.set-includes", true);
+  $current-includes: $includes !global;
+}
+
+/// Exclude certain items from includes
+/// @param {List} $excludes List of item names
+
+@mixin set-excludes($excludes) {
+  $current-includes: utils.list-without($current-includes, $excludes) !global;
+}
+
 /// Prints all Base styles
 /// @name base-styles
-/// @param {List} $includes A list of changes to this module's includes
+/// @param {List} $includes [$all-includes] A list of components to include (defaults to current)
 /// @example scss
 ///  @include ulu.base-styles();
 
-@mixin styles($includes: null) {
+@mixin styles($includes: $current-includes) {
   @include utils.file-header("base");
-  @if $includes {
-    @include utils.require-list-contains($-all-includes, $includes);
-    $-all-includes: map.merge($-all-includes, $includes) !global;
-  }
-  @if (map.get($-all-includes, "normalize")) {
+  
+  @include utils.require-list-contains($all-includes, $includes, "base.$includes", true);
+  
+  @if (list.index($includes, "normalize")) {
     @include normalize.styles;
   }
-  @if (map.get($-all-includes, "elements")) {
+  @if (list.index($includes, "root")) {
+    @include root.styles;
+  }
+  @if (list.index($includes, "elements")) {
     @include elements.styles;
   }
-  @if (map.get($-all-includes, "keyframes")) {
+  @if (list.index($includes, "keyframes")) {
     @include keyframes.styles;
   }
-  @if (map.get( $-all-includes, "typography")) {
+  @if (list.index($includes, "typography")) {
     @include typography.styles;
   }
-  @if (map.get($-all-includes, "color")) {
+  @if (list.index($includes, "color")) {
     @include color.styles;
   }
-  @if (map.get($-all-includes, "layout")) {
+  @if (list.index($includes, "layout")) {
     @include layout.styles;
   }
+  @if (list.index($includes, "print")) {
+    @include normalize.styles;
+  }
 }