@ulu/frontend 0.0.23 → 0.1.0-beta.1

package/scss/_typography.scss

@@ -1,6 +1,6 @@
 ////
 /// @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.
+/// Manages typography settings, sizes and provides typography related utilities
 ////
 
 @use "sass:map";
@@ -10,51 +10,62 @@
 
 @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)
+/// @prop {Dimension} letter-spacing-uppercase [0.04em]
+/// @prop {Number} margin-bottom [1em] Default margin for typography (like paragraphs)
+/// @prop {Number} margin-top [null] Default margin for typography (like paragraphs)
+/// @prop {Number} responsive-change [0.05vw] Amount to scale typography by browser's width (use viewport units)
+/// @prop {Number} scale-steps [5]
+/// @prop {Number} size-ratio [1.8] Font size scale when using preset sizes, ratio mixin)
+/// @prop {Number} size-line-height-ratio [0.97] Default line height scaling (when using preset sizes, ratio mixin). Can shrink line-height as size increase if desirable
+/// @prop {Number} font-family [(ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif)] Default font family
+/// @prop {Number} font-family-monospace [(Menlo, Consolas, Monaco, monospace)] Base font-family for monospace
+/// @prop {CssValue} font-family-sans [(ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif)]
+/// @prop {CssValue} font-family-serif [(Cambria, Georgia, serif]
+/// @prop {Number} font-size [16px] Default font size (use pixels, converted, is used for rem base)
+/// @prop {CssValue} font-weight [inherit]
+/// @prop {CssValue} font-weight-bold [bold]
+/// @prop {CssValue} font-weight-light [300]
+/// @prop {CssValue} font-weight-normal [normal]
+/// @prop {CssValue} font-weight-semibold [600]
+/// @prop {Number} line-height [1.5] Default line height
+/// @prop {Number} line-height-dense [1.3] Default dense line height
+/// @prop {Number} line-height-densest [1.1]
+/// @prop {Number} line-height-spaced [1.75]
 
 $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
+  "letter-spacing-uppercase": 0.04em,
+  "margin-bottom":            1em,
+  "margin-top":               null,
+  "responsive-change":        0.05vw,
+  "scale-steps":              5,
+  "size-ratio":               1.8,
+  "size-line-height-ratio":   0.97,
+  "font-family":              (ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif),
+  "font-family-monospace":    (Menlo, Consolas, Monaco, monospace),
+  "font-family-sans":         (ui-sans-serif, "Open Sans", Helvetica, Arial, sans-serif),
+  "font-family-serif":        (Cambria, Georgia, serif),
+  "font-size":                16px,
+  "font-weight":              inherit,
+  "font-weight-bold":         bold,
+  "font-weight-light":        300,
+  "font-weight-normal":       normal,
+  "font-weight-semibold":     600,
+  "line-height":              1.5,
+  "line-height-dense":        1.3,
+  "line-height-densest":      1.1,
+  "line-height-spaced":       1.75,
+  "max-width":                60em,
+  "max-width-large":          75em,
+  "max-width-small":          45em,
 ) !default;
 
 /// Change modules $config
 /// @param {Map} $changes Map of changes
-///   @include typography.set-options(( "font-size" : 14px ));
+///   @include ulu.typography-set(( "font-size" : 14px ));
 
 @mixin set($changes) {
   $config: map.merge($config, $changes) !global;
@@ -62,7 +73,7 @@ $config: (
 
 /// Get a config option
 /// @param {Map} $changes Map of changes
-///   @include typography.set-options(( "font-size" : 14px ));
+///   @include ulu.typography-get(( "font-size" : 14px ));
 
 @function get($name) {
   @return utils.require-map-get($config, $name, 'typography [config]');
@@ -73,7 +84,7 @@ $config: (
 /// @return {Number} Scaled value
 
 @function scale($step) {
-  @return calculate.ratio-scale-size(get("font-size"), get("size-ratio"), get("scale-steps"), $step);
+  @return utils.ratio-scale-size(get("font-size"), get("size-ratio"), get("scale-steps"), $step);
 }
 
 /// Get scale of the line-height
@@ -82,7 +93,7 @@ $config: (
 /// @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);
+  @return utils.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
@@ -111,7 +122,7 @@ $config: (
   }
 }
 
-/// Break word stradegy
+/// Output CSS Break word strategy
 /// @param {Boolean} $force Force words to break (will have unusual breaks)
 
 @mixin word-break($force: false) {
@@ -122,6 +133,7 @@ $config: (
 
 /// Creates a size map 
 /// - This is just an accelerator for creating a size map
+/// - This is opinionated about how sizes are setup, headlines get (margins, bold, headline color) and are base classes while non-headlines are added as helper classes and do not get (margins, bold, color)
 /// - You can pass your own size maps using set-sizes()
 /// @param {Number} $font-size Font size
 /// @param {Number} $line-height Line height
@@ -130,13 +142,39 @@ $config: (
 @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), 
+    "font-weight" : if($is-headline, get("font-weight-bold"), null), 
     "line-height": $line-height,
+    "margin-bottom" : if($is-headline, get("margin-bottom"), null),
+    "margin-top" : if($is-headline, get("margin-top"), null),
     "responsive" : true,
     "helper-class" : if($is-headline, false, true),
     "helper-class-prefixed" : true,
     "base-class" : if($is-headline, true, false),
-    "base-class-prefixed" : false
+    "base-class-prefixed" : false,
+    "color" : if($is-headline, color.get("headline"), null)
+  );
+}
+
+/// Function that returns default sizes
+/// - Used to set the sizes initially and 
+/// - You can use this if you've reconfigured typography settings and want to update the default sizes with the new settings
+/// @return {Map} The default typography sizes
+
+@function get-default-sizes() {
+  @return (
+    "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)),
+    "h6" :            new-size(scale(1),   scale-line-height(1),   true),
+    "h5" :            new-size(scale(2),   scale-line-height(2),   true),
+    "h4" :            new-size(scale(3),   scale-line-height(3),   true),
+    "h3" :            new-size(scale(4),   scale-line-height(4),   true),
+    "h2" :            new-size(scale(5),   scale-line-height(5),   true),
+    "h1" :            new-size(scale(6),   scale-line-height(6),   true),
   );
 }
 
@@ -146,41 +184,37 @@ $config: (
 /// @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 {Number} $size.name.breakpoints Map of breakpoints where each key is breakpoint with map of changes (ie. font-size, etc)  
+/// @prop {Number} $size.name.breakpoints.breakpoint.direction Direction the breakpoint should be applied to (ie. min/max)
+/// @prop {Boolean} $size.name.base-class This style should be included in the base (top can be overridden)
 /// @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
+$sizes: get-default-sizes() !default;
+
+/// Configure the typography sizes
 /// @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
-///   ));
+/// @param {Map} $merge-mode [null] Merge strategy see, utils.map-merge options
+/// @example scss - Adjusting the h1 and h2 sizes while keeping pre-existing sizes by using deep merge
+///   @include ulu.typography-set-sizes((
+///     "h1" : (
+///       "color" : "accent",
+///       "font-size": 50px,
+///       "margin-top" : null,
+///       "margin-bottom" : 0.5em
+///     ),
+///     "h2" : (
+///       "font-size": 38px,
+///       "color" : blue,
+///       "margin-top" : 2.5em,
+///       "margin-bottom" : 1em,
+///     ),
+///   ), "deep");
 
 @mixin set-sizes($changes, $merge-mode: null) {
   $sizes: utils.map-merge($sizes, $changes, $merge-mode) !global;
 }
 
-/// Get a size's map
+/// Get a specific size's settings map
 /// @param {String} $name Name of size
 /// @return {Map} 
 
@@ -188,14 +222,12 @@ $sizes: (
   @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
+/// Check if a typography size exists
+/// @param {String} $name Name of size
+/// @return {Boolean} 
 
-@function font-size($name: null) {
-  $size: get-size($name);
-  $font-size: map.get($size, "font-size");
-  @return rem($font-size);
+@function has-size($name) {
+  @return utils.map-has($sizes, $name);
 }
 
 /// Forces conversion to unitless line-height
@@ -203,20 +235,21 @@ $sizes: (
 /// @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
+  // Font size is rems, line-height is unknown
   @if (math.is-unitless($line-height)) {
     @return $line-height;
   }
   $unit: math.unit($line-height);
   @if ($unit == "em") {
-    @return utility.strip-unit($line-height);
+    @return utils.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);
+    @return utils.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
@@ -249,7 +282,6 @@ $sizes: (
   }
 }
 
-
 /// 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 
@@ -274,8 +306,8 @@ $sizes: (
 
 /// 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
-/// @param {Boolean} $only-font-size Only print the font size
+/// @param {Map} $changes Modifications to be merged into size before output
+/// @param {Boolean} $only-font-size Only output the font size
 
 @mixin size($name, $changes: false, $only-font-size: null) {
   $size: $name;
@@ -302,6 +334,7 @@ $sizes: (
   @if (not $only-font-size) {
     font-weight: get-size-value($size, "font-weight");
     font-family: get-size-value($size, "font-family");
+    font-variation-settings: get-size-value($size, "font-variation-settings");
     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");

package/scss/_units.scss

@@ -1,5 +1,6 @@
 ////
 /// @group units
+/// Manages common spacing values (used by utility classes like margin/padding)
 ////
 
 @use "sass:meta";
@@ -8,26 +9,26 @@
 
 /// Module Settings
 /// @type Map
-/// @prop {Number} small-x 
-/// @prop {Number} small 
-/// @prop {Number} default Base unit of measurent
-/// @prop {Number} large 
-/// @prop {Number} large-x 
-/// @prop {Number} large-xx 
+/// @prop {Number} default [1rem] Base unit of measure
+/// @prop {Number} large [1rem * 2]
+/// @prop {Number} large-x [1rem * 3]
+/// @prop {Number} large-xx [1rem * 4]
+/// @prop {Number} small [1rem * 0.75]
+/// @prop {Number} small-x [1rem * 0.5]
 
 $config: (
-  "small-x" : 1rem * 0.5,
-  "small" : 1rem * 0.75,
-  "default" : 1rem,
-  "large" : 1rem * 2,
-  "large-x" : 1rem * 3,
-  "large-xx" : 1rem * 4
+  "default":  1rem,
+  "large":    1rem * 2,
+  "large-x":  1rem * 3,
+  "large-xx": 1rem * 4,
+  "small":    1rem * 0.75,
+  "small-x":  1rem * 0.5,
 ) !default;
 
 /// Update the units config
 /// @param {Map} $changes A map to merge into the color palette
 /// @example scss Setting the error and type color
-///   @include units.set((
+///   @include ulu.units-set((
 ///     "default" : 1.5em
 ///   ));