@ulu/frontend 0.0.3

package/scss/_index.scss

@@ -0,0 +1,29 @@
+////
+/// @group index
+////
+/// Main entry for library as single module use
+/// - All modules get namespaced
+/// @example scss - Example of color modules
+///   // Namespaced
+///   ulu.color-get();
+///   // Versus
+///   color.get();
+///
+
+@forward "path" as path-*;
+@forward "cssvar" as cssvar-*;
+@forward "color" as color-*;
+@forward "units" as units-*;
+@forward "calculate" as calculate-*;
+@forward "breakpoint" as breakpoint-*;
+@forward "selector" as selector-*;
+@forward "element" as element-*;
+@forward "typography" as typography-*;
+@forward "button" as button-*;
+@forward "utility" as utility-*;
+@forward "layout" as layout-*;
+@forward "grid" as grid-*;
+@forward "base" as base-*;
+@forward "components" as component-*;
+@forward "helpers" as helper-*;
+@forward "utils" as utils-*;

package/scss/_layout.scss

@@ -0,0 +1,202 @@
+////
+/// @group layout
+////
+
+@use "sass:map";
+@use "sass:list";
+@use "sass:meta";
+@use "utils";
+@use "calculate";
+@use "breakpoint";
+
+/// Module Settings
+/// @type Map
+/// @prop {Number} $config.max-width Common max-width for site
+/// @prop {Number} $config.margin Common margin for site
+/// @prop {Number} $config.z-index-fixed Common z-index, above everything
+/// @prop {Number} $config.z-index-sticky Common z-index for sticky or stuck items
+/// @prop {Number} $config.z-index-above Common z-index, below sticky
+
+$config: (
+  "max-width":         90rem,
+  "margin":            2rem,
+  "z-index-sticky":    100,
+  "z-index-above":     450,
+  "z-index-fixed":     1000
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+///   @include module-name.set(( "property" : value ));
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {Map} $name Name of property
+///   @include module-name.get("property");
+
+@function get($name) {
+  @return utils.require-map-get($config, $name, "layout [config]");
+}
+
+$containers: (
+  "container" : (
+    "width" : 100%,
+    "max-width" : get("max-width"),
+    "padding" : (get("margin") get("margin")),
+    "breakpoints" : null,
+    "responsive" : false,
+    "responsive-amount" : 3vw
+  )
+) !default;
+
+@mixin set-containers($changes, $deep: false, $overwrite: false) {
+  $containers: utils.map-merge-or-overwrite($containers, $changes, $deep, $overwrite) !global;
+}
+
+@function get-container($name, $breakpoint: false) {
+  $container: utils.require-map-get($containers, $name, "Layout [get-container]");
+  $breakpoints: map.get($container, "breakpoints");
+  @if ($breakpoint) {
+    @return utils.require-map-get($breakpoints, $breakpoint, "[container breakpoint]");
+  } @else {
+    @return $container;
+  }
+}
+/// Returns padding to another property including breakpoints
+/// ie. { top: $containers-padding; }
+@mixin match-container-padding($property, $name: "container", $sides: true) {
+  $container: get-container($name);
+  $breakpoints: map.get($container, "breakpoints");
+  #{ $property }: get-container-padding($name, $sides);
+  @if $breakpoints {
+    @each $breakpoint, $props in $breakpoints {
+      $direction: map.get($props, "direction");
+      @include breakpoint.from($breakpoint, $direction) {
+        #{ $property }: get-container-padding($name, $sides, $breakpoint);
+      }
+    }
+  }
+}
+
+/// For a given property for every breakpoint in a given container
+/// creates a css calc value that will match the containers side margin
+/// The margin is created via empty space when the container hits the max-width
+/// If passing inlude padding it would be the containers
+/// side (x) + the padding. This accounts for the containers max-width to give an absoute value
+@mixin match-container-margin($property, $name: "container", $include-padding: true) {
+  $container: get-container($name);
+  $breakpoints: map.get($container, "breakpoints");
+  $padding: if($include-padding, get-container-padding($name, true), 0);
+  $max: map.get($container, "max-width");
+  #{ $property }: max(((100vw - $max) / 2) + $padding, $padding);
+  @if $breakpoints {
+    @each $breakpoint, $props in $breakpoints {
+      $direction: map.get($props, "direction");
+      @include breakpoint.from($breakpoint, $direction) {
+        $pad: if($include-padding, get-container-padding($name, true, $breakpoint), 0);
+        #{ $property }: max(((100vw - $max) / 2) + $pad, $pad);
+      }
+    }
+  }
+}
+
+@function get-container-padding($name, $sides: true, $specific-breakpoint: false) {
+  $container: get-container($name, $specific-breakpoint);
+  $padding: map.get($container, "padding");
+  $is-list: meta.type-of($padding) == "list"; // Else number
+  @if (not $is-list) {
+    @return $padding;
+  } @else {
+    @return list.nth($padding, if($sides, 2, 1));
+  }
+}
+
+@mixin container-padding($name, $sides: true, $ends: true, $specific-breakpoint: false) {
+  $container: get-container($name, $specific-breakpoint);
+  $responsive: map.get($container, "responsive");
+  $x: get-container-padding-x($name, $specific-breakpoint);
+  $y: get-container-padding-y($name, $specific-breakpoint);
+  $resp-amount: if(meta.type-of($responsive) == number, $responsive, calculate.get("responsive-change"));
+  
+  @if $responsive {
+    @if $sides {
+      @include calculate.responsive-property("padding-left", $x, $resp-amount);
+      @include calculate.responsive-property("padding-right", $x, $resp-amount);
+    }
+    @if $ends {
+      @include calculate.responsive-property("padding-top", $y, $resp-amount);
+      @include calculate.responsive-property("padding-bottom", $y, $resp-amount);
+    }
+  } @else {
+    @if $sides {
+      padding-left: $x;
+      padding-right: $x;
+    }
+    @if $ends {
+      padding-top: $y;
+      padding-bottom: $y;
+    }
+  }
+}
+@function get-container-padding-x($name, $specific-breakpoint: false) {
+  @return get-container-padding($name, true, $specific-breakpoint);
+}
+@function get-container-padding-y($name, $specific-breakpoint: false) {
+  @return get-container-padding($name, false, $specific-breakpoint);
+}
+@mixin container-styles($name: "container", $specific-breakpoint: false) {
+  $container: get-container($name,  $specific-breakpoint);
+  $breakpoints: map.get($container, "breakpoints");
+  
+  $width: map.get($container, "width");
+  // @debug $specific-breakpoint;
+  // @if $specific-breakpoint {
+  //   @debug $container;
+  // }
+  @if ($width == null) {
+    $width: 100%;
+  }
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+  width: $width;
+  max-width: map.get($container, "max-width");
+  @include container-padding($name, $specific-breakpoint: $specific-breakpoint);
+
+  // Recursive print other breakpoints
+  @if $breakpoints and not $specific-breakpoint {
+    @each $breakpoint, $props in $breakpoints {
+      $direction: map.get($props, "direction");
+      @include breakpoint.from($breakpoint, $direction) {
+        @include container-styles($name, $breakpoint);
+      }
+    }
+  }
+}
+
+/// Prints clearfix styles
+
+@mixin clearfix() {
+  &:before,
+  &:after {
+    content: "";
+    display: table;
+    flex-basis: 0; // Flexbox, clear fix for pseudo elements in Safari
+    order: 1;
+  }
+  &:after { 
+    clear: both; 
+  }
+  *zoom: 1;
+}
+
+/// Removes scrollbar with CSS
+@mixin remove-scrollbar() {
+  -ms-overflow-style: none; /* for Internet Explorer, Edge */
+  scrollbar-width: none; /* for Firefox */
+  &::-webkit-scrollbar {
+    display: none; /* for Chrome, Safari, and Opera */
+  }
+}

package/scss/_path.scss

@@ -0,0 +1,58 @@
+////
+/// @group path
+////
+
+@use "sass:map";
+@use "sass:string";
+@use "utils";
+
+/// Aliases 
+/// @type Map
+/// - Important: alias could be used for directory or file so omit trailing slash for directories
+/// - All aliases must start with "#"
+
+$aliases: (
+  "#Images" : "/images",
+) !default;
+
+/// Set aliases or change defaults
+/// @param {Map} $changes Map of changes
+
+@mixin set-aliases($changes) {
+  $aliases: map.merge($aliases, $changes) !global;
+}
+
+/// Get an aliase's path
+/// @param {String} Name Name of alias
+
+@function get-alias($name) {
+  @return utils.require-map-get($aliases, $name, '[path alias]');
+}
+
+/// Resolves a Path 
+/// - Checks if path is an alias if so rewrite's it
+/// - Future could include rewrites for easier updating or rearranging of legacy things
+/// - Aliases work by starting with "#", Since it's an illegal uri character, needs to be escaped if used as literal, we felt that it was the safest way to mix aliases in with real URLs (so that a dev of a module using path.resolve can always pass paths through (user input unknown if alias)
+/// @example scss
+///   .img {
+///     background-image: url(path.resolve("#Images/branding/logo"));
+///   }
+///
+
+@function resolve($path) {
+  $is-alias: string.index($path, "#") == 1;
+  $dir-index: string.index($path, "/");
+  $resolved-path: $path;
+  @if $is-alias {
+    // Extract alias
+    @if $dir-index {
+      $alias: string.slice($path, 1, $dir-index - 1);
+      @return "#{ get-alias($alias) }#{ string.slice($path, $dir-index) }";
+    // Must just be only an alias
+    } @else {
+      @return "#{ get-alias($path) }";
+    }
+  } @else {
+    @return $path;
+  }
+}

package/scss/_selector.scss

@@ -0,0 +1,81 @@
+////
+/// @group selector
+////
+
+@use "sass:string";
+@use "sass:map";
+@use "utils";
+
+/// Module Settings
+/// - This module can be used for dynamic classnames (used in base and some components). Some components selectors are too complex or coupled for dynamic classnames. 
+/// @todo See about documenting when a component doesn't run through the selecotr module to get it's base classname
+/// @type Map
+/// @prop {String} $config.prefix Global prefix for selectors (would be used for classname prefix for example)
+
+$config: (
+  "prefix" : ""
+) !default;
+
+// Map to store class overrides ("button" : "site-button") for example
+$-class-overrides: ();
+$-class-wildcards: ();
+
+/// 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 ));
+@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");
+
+@function get($name) {
+  @return utils.require-map-get($config, $name, "selector [config]");
+}
+
+/// Set the class selector overrides
+/// @param {Map} $changes Changes to merge
+
+@mixin set-class-overrides($changes) {
+  @each $key, $prop in $changes {
+    $index: string.index($key, "*");
+    @if ($index) {
+      $wild-key: string.slice($key, 1, $index - 1);
+      $-class-wildcards: map.set($-class-wildcards, $wild-key, $prop) !global;
+      $changes: map.remove($changes, $key);
+    }
+  }
+  $-class-overrides: map.merge($-class-overrides, $changes) !global;
+}
+
+/// Used to allow global prefixing of classes, and also the ability to 
+/// Change a class used in the system (ie. like a component for example)
+/// @param {String} $class The classname to set
+
+@function class($class, $name-only: false) {
+  // Check if it's a wildcard
+  $wildcard: get-class-wildcard($class);
+  $override: map.get($-class-overrides, $class);
+  $updated: if($override, $override, if($wildcard, $wildcard, $class));
+  $name: "#{ get("prefix") }#{ $updated }";
+  @if $name-only {
+    @return $name;
+  } @else {
+    @return ".#{ $name }";
+  }
+}
+
+@function get-class-wildcard($class) {
+  $change: $class;
+  @each $key, $prop in $-class-wildcards {
+    $index: string.index($class, $key);
+    @if ($index) {
+      $change: utils.string-replace($class, $key, $prop);
+    }
+  }
+  @return $change;
+}

package/scss/_typography.scss

@@ -0,0 +1,320 @@
+////
+/// @group typography
+/// @todo Idea: Should the maps value be processes when using the set-sizes, set? Instead of recalculated each time get-size is or get is used.
+//// @version 1.0.2
+////
+
+@use "sass:map";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
+
+@use "color";
+@use "utils";
+@use "utility";
+@use "calculate";
+@use "breakpoint";
+
+/// Module Settings
+/// @type Map
+/// @prop {Number} $config.font-size Default font size (use pixels, converted, is used for rem base)
+/// @prop {Number} $config.font-family Default font family
+/// @prop {Number} $config.font-family-monospace Base font-family for monospace
+/// @prop {Number} $config.line-height Default line height
+/// @prop {Number} $config.line-height-dense Default dense line height
+/// @prop {Number} $config.size-ratio Font size scale when using preset sizes, ratio mixin)
+/// @prop {Number} $config.size-line-height-ratio Default line height scaling (when using preset sizes, ratio mixin). Can shrink line-height as size increase if desrireable
+/// @prop {Number} $config.responsive-change Amount to scale typography by browser's width (use viewport units)
+/// @prop {Number} $config.margin Default margin for typography (like paragraphs)
+
+$config: (
+  "font-size" : 16px, 
+  "font-family" : (ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif),
+  "font-family-sans" : (ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif),
+  "font-family-serif" : (Cambria, Georgia, serif),
+  "font-family-monospace" : (Menlo, Consolas, Monaco, monospace),
+  "font-weight" : inherit,
+  "font-weight-headline" : bold,
+  "font-weight-light" : 300,
+  "font-weight-normal" : normal,
+  "font-weight-semibold" : 600,
+  "font-weight-bold" : bold,
+  "line-height" : 1.5,
+  "line-height-dense": 1.3,
+  "line-height-spaced": 1.75,
+  "size-ratio": 2,
+  "size-line-height-ratio": 0.97,
+  "scale-steps": 5,
+  "responsive-change": 0.05vw, 
+  "margin-bottom":  1em,
+  "margin-top":  false,
+  "letter-spacing-uppercase" : 0.04em,
+  "max-width" : 60rem,
+  "max-width-small" : 50rem
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+///   @include typography.set-options(( "font-size" : 14px ));
+
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {Map} $changes Map of changes
+///   @include typography.set-options(( "font-size" : 14px ));
+
+@function get($name) {
+  @return utils.require-map-get($config, $name, 'typography [config]');
+}
+
+/// Get scale of the base font-size
+/// @param {Number} $step Current size in the scale you want to calculate
+/// @return {Number} Scaled value
+
+@function scale($step) {
+  @return calculate.ratio-scale-size(get("font-size"), get("size-ratio"), get("scale-steps"), $step);
+}
+
+/// Get scale of the line-height
+/// @param {Number} $step Current size in the scale you want to calculate
+/// @return {Number} Scaled value
+/// @todo Setup breakpoints
+
+@function scale-line-height($step) {
+  @return calculate.ratio-scale-size(get("line-height"), get("size-line-height-ratio"), get("scale-steps"), $step);
+}
+
+/// Convert pixel value to rem value based on typography $font-size
+/// @param {Number} $pixels Pixel value to convert from
+/// @return {Number} Rem value
+
+@function rem($pixels) {
+  @if math.unit($pixels) == "px"  {
+    @return math.div($pixels, get("font-size")) * 1rem;
+  } @else {
+    @return $pixels + 1rem;
+  }
+}
+
+/// Changes pixels to em
+/// @param {Number} $value Pixel value to convert from
+/// @param {Number} $base Conversion base (defaults to font-size)
+/// @return {Number} Rem value
+
+@function em($value, $base: null) {
+  @if (math.unit($value) == "px") {
+    $base: if($base, $base, get("font-size"));
+    @return math.div($base, $value) * 1em;
+  } @else  {
+    @return $value;
+  }
+}
+
+/// Break word stradegy
+/// @param {Boolean} $force Force words to break (will have unusual breaks)
+
+@mixin word-break($force: false) {
+  word-break: if($force, break-all, normal);
+  word-break: break-word;
+  hyphens: auto;
+}
+
+/// Creates a size map 
+/// - This is just an accelerator for creating a size map
+/// - You can pass your own size maps using set-sizes()
+/// @param {Number} $font-size Font size
+/// @param {Number} $line-height Line height
+/// @param {Boolean} $is-headline Is a headline
+
+@function new-size($font-size, $line-height: true, $is-headline: false) {
+  @return (
+    "font-size": $font-size,
+    "font-weight" : if($is-headline, get("font-weight-headline"), null), 
+    "line-height": $line-height,
+    "responsive" : true,
+    "helper-class" : if($is-headline, false, true),
+    "helper-class-prefixed" : true,
+    "base-class" : if($is-headline, true, false),
+    "base-class-prefixed" : false
+  );
+}
+
+/// Default size presets
+/// @type Map
+/// @prop {Number} $size.name Name of size
+/// @prop {Number} $size.name.font-size Font size in rems or pixels
+/// @prop {Number} $size.name.line-height Line height (unitless)
+/// @prop {Number} $size.name.responsive Apply responsive sizes
+/// @prop {Boolean} $size.name.base-class This style should be included in the base (top can be overriden)
+/// @prop {Boolean} $size.name.helper-class This style should be included in the helpers (overrides)
+/// @todo Add adaptive and use a map of breakpoints and whether it's up or down
+/// @todo Add headlines
+
+$sizes: (
+  "small-x" :       new-size(scale(-2)),
+  "small" :         new-size(scale(-1)),
+  "base" :          new-size(scale(0)),
+  "large" :         new-size(scale(1),   scale-line-height(1)),
+  "large-x" :       new-size(scale(2),   scale-line-height(2)),
+  "large-xx" :      new-size(scale(3),   scale-line-height(3)),
+  "large-xxx" :     new-size(scale(4),   scale-line-height(4)),
+  "h1" :            new-size(scale(6),   scale-line-height(6),   true),
+  "h2" :            new-size(scale(5),   scale-line-height(5),   true),
+  "h3" :            new-size(scale(4),   scale-line-height(4),   true),
+  "h4" :            new-size(scale(3),   scale-line-height(3),   true),
+  "h5" :            new-size(scale(2),   scale-line-height(2),   true),
+  "h6" :            new-size(scale(1),   scale-line-height(1),   true)
+) !default;
+
+/// Update the typography presets map
+/// @param {Map} $changes A map to merge into the color palette
+/// @param {Map} $deep Use deep merge
+/// @param {Map} $overwrite Overwrite the presets completly (cannot be used with deep)
+/// @example scss Setting the error and type color
+///   @include typography.set((
+///     "small" : 0.8rem
+///   ));
+
+@mixin set-sizes($changes, $deep: false, $overwrite: false) {
+  $sizes: utils.map-merge-or-overwrite($sizes, $changes, $deep, $overwrite) !global;
+}
+
+/// Get a size's map
+/// @param {String} $name Name of size
+/// @return {Map} 
+
+@function get-size($name) {
+  @return utils.require-map-get($sizes, $name, 'typography [size]');
+}
+
+/// Print a font-size for a given size
+/// @todo Remove doesn't work for breakpoints or responsive 
+/// @param {String} $value Size name
+
+@function font-size($name: null) {
+  $size: get-size($name);
+  $font-size: map.get($size, "font-size");
+  @return rem($font-size);
+}
+
+/// Forces conversion to unitless line-height
+/// @param {Number} $line-height Line height size in px, em, or rem
+/// @param {Number} $font-size Font size in px, em, or rem
+
+@function unitless-line-height($line-height, $font-size) {
+  // Font size is rems, line-height is unkown
+  @if (math.is-unitless($line-height)) {
+    @return $line-height;
+  }
+  $unit: math.unit($line-height);
+  @if ($unit == "em") {
+    @return utility.strip-unit($line-height);
+  } @else if ($unit == "pixels" or $unit == "rem") {
+    $calc: math.div(rem($line-height), rem($font-size));
+    @return utility.strip-unit($calc);
+  } @else {
+    @error "ULU: Unable to convert to unitless line-height for: #{ $line-height }";
+  }
+}
+/// Print a value from the size and convert it (to appropriate unit for framework)
+/// @param {Map} $size Size's map 
+/// @param {String} $props The property to get
+
+@function get-size-converted-value($size, $prop) {
+  // Font size is calculated differently
+  $value: map.get($size, $prop);
+  $font-size: map.get($size, "font-size");
+  $type: meta.type-of($value);
+  
+  @if ($value == false or $value == null) {
+    @return null;
+  // Numbers and true (default) need to be converted
+  } @else if ($value == true or $type == number) {
+    // Get default value
+    @if ($value == true)  {
+      $value: get($prop);
+    }
+    // Force line-height to be unitless
+    @if ($prop == "line-height") {
+      @return unitless-line-height($value, $font-size);
+    }
+    // Convert to REM
+    @if (math.unit($value) == "px") {
+      $value: rem($value);
+    }
+    @return $value;
+  } @else {
+    @return $value;
+  }
+}
+
+
+/// Get a sizes property value that doesn't need conversion 
+/// - Reason: Will map to default if user set's size prop to true
+/// @param {Map} $size Size's map 
+/// @param {String} $props The property to get
+
+@function get-size-value($size, $prop) {
+  $value: map.get($size, $prop);
+  // Default
+  @if ($value == true) {
+    $value: get($prop);
+  }
+  @return $value;
+}
+
+/// Print's the responsive type formula
+/// @param {String} $font-size Name to retrieve from sizes map or a unique size map that follows the API
+/// @param {Map} $changes Modifications to be merged into size before using
+
+@mixin font-size-responsive($font-size, $amount: get("responsive-change")) {
+  font-size: calc(#{ $font-size } + #{ $amount });
+}
+
+/// Print a typography size (font-size, line-height)
+/// @param {String} $nameOrMap Name to retrieve from sizes map or a unique size map that follows the API
+/// @param {Map} $changes Modifications to be merged into size before using
+
+@mixin size($name, $changes: false, $only-font-size: null) {
+  $size: $name;
+  // Allow custom maps
+  @if (meta.type-of($name) == "string") {
+    $size: get-size($name);
+  }
+  @if ($changes) {
+    $size: map.merge($size, $changes);
+  }
+  $font-size: get-size-converted-value($size, "font-size");
+  $breakpoints: map.get($size, "breakpoints");
+  $responsive: map.get($size, "responsive");
+  $color: map.get($size, "color");
+
+  font-size: $font-size;
+  @if ($responsive) {
+    @if (meta.type-of($responsive) == "number") {
+      @include font-size-responsive($font-size, $responsive);
+    } @else {
+      @include font-size-responsive($font-size);
+    }
+  }
+  @if (not $only-font-size) {
+    font-weight: get-size-value($size, "font-weight");
+    font-family: get-size-value($size, "font-family");
+    line-height: get-size-converted-value($size, "line-height");
+    margin-top: get-size-converted-value($size, "margin-top");
+    margin-bottom: get-size-converted-value($size, "margin-bottom");
+    color: if($color, color.get($color), null);
+  }
+
+  // If they have breakpoints, process them
+  @if $breakpoints {
+    @each $name, $breakpoint in $breakpoints {
+      $direction: map.get($breakpoint, "direction");
+      @include breakpoint.from($name, $direction) {
+        @include size($breakpoint, null, $only-font-size);
+      }
+    }
+  }
+}