typey 1.0.0.beta.5 → 1.0.0.beta.6

data/stylesheets/_typey.scss

@@ -1,9 +1,15 @@
+@import "typey/functions/helpers";
+@import "typey/functions/validators";
+@import "typey/functions/em-calculators";
+@import "typey/functions/outputters";
+@import "typey/functions/sizers";
+@import "typey/functions/extras";
+@import "typey/functions/depreciated";
 @import "typey/defaults";
-@import "typey/helpers";
 @import "typey/font-stacks";
-@import "typey/font-size";
-@import "typey/line-height";
-@import "typey/type-layout";
-@import "typey/weight";
-@import "typey/margin";
-@import "typey/padding";
+@import "typey/mixins/define-type-sizing";
+@import "typey/mixins/font-size";
+@import "typey/mixins/line-height";
+@import "typey/mixins/type-layout";
+@import "typey/mixins/margin";
+@import "typey/mixins/padding";

data/stylesheets/typey/_defaults.scss

@@ -2,16 +2,26 @@
 // Allowed units: px
 $browser-font-size:        16px !default;
 
+// Allowed units: rem, em or px
+$base-unit:                rem !default;
+
 // The base font size will be used for most calculations involving font-size.
 // Allowed units: px
 $base-font-size:           16px !default;
 
 // The base line height will be used for most calculations involving height.
 // Allowed units: px
-$base-line-height:         21px !default;
+$base-line-height:         20px !default;
 
-// Allowed units: rem, em or px
-$base-unit:                rem !default;
+// The method to calculate line-height. Allowed values: rhythm or ratio.
+// Rhytm uses a vertical rhythm approach where line-height is specified as
+// a multiple of the $base-line-height.
+// Ratio uses a ratio approach where line-height is specified as a ratio
+// of the elements font-size.
+$line-height-method:       rhythm !default;
+
+// The default ratio of line-height to font-size.
+$base-line-height-ratio:   1.25 !default;
 
 // By default we will provide fallbacks when rem is the base unit.
 $rem-fallback:             true !default;
@@ -72,39 +82,3 @@ $font-weight: (
     @error "Size '#{$key}' in $font-size map is not specified in px";
   }
 }
-
-// Define defaults (in the HTML element).
-//
-// @param number $base-font-size
-//   (optional) Use to set to anything other than the base value.
-//   Allowed units: px
-// @param number $base-line-height
-//   (optional) Use to set to anything other than the base value.
-//   Allowed units: px
-@mixin define-type-sizing($base-font-size: $base-font-size, $base-line-height: $base-line-height) {
-  @if $base-unit == rem {
-    font-size: $base-font-size / $browser-font-size * 100%;
-    @if $rem-fallback == true {
-      line-height: $base-line-height;
-    }
-    line-height: output-unit($base-line-height / $base-font-size);
-  }
-  @if $base-unit == px {
-    font-size: $base-font-size;
-    line-height: $base-line-height;
-  }
-  @if $base-unit == em {
-    font-size: $base-font-size / $browser-font-size * 100%;
-    line-height: output-unit($base-line-height / $base-font-size);
-  }
-  @if $auto-print-sizing == true {
-    @if $base-unit == rem or $base-unit == em {
-      @media print {
-        font-size: $print-font-size;
-      }
-    }
-    @else {
-      @warn "As you are not using a relative base unit (rem or em) automatic print media sizing will not work. Set $auto-print-sizing to false to hide this warning"
-    }
-  }
-}

data/stylesheets/typey/_font-stacks.scss

@@ -9,17 +9,3 @@ $helvetica-stack:     "Helvetica Neue", Helvetica, Arial, sans-serif;
 $baskerville-stack:   Baskerville, "Baskerville Old Face", "Hoefler Text", Garamond, "Times New Roman", serif;
 $monaco-stack:        Monaco, Consolas, "Lucida Console", monospace, monospace;
 $trebuchet-ms-stack:  "Trebuchet MS", "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Tahoma, sans-serif;
-
-// Extend a font by adding a web-safe stack to it.
-//
-// Example usage:
-//   $new-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
-//
-// @param string $font
-//   The name of the font. Use inverted commas if there are spaces in the font
-//   name. i.e "Open sans"
-// @param list $font-stack
-//   The font stack variable to extend.
-@function extend-font-stack($font, $font-stack) {
-  @return join($font, $font-stack, $separator: comma);
-}

data/stylesheets/typey/functions/_depreciated.scss

@@ -0,0 +1,55 @@
+// DEPRECIATED FUNCTIONS
+// The names of these functions have been refined and namespaced (above) to avoid
+// potential confusion with functions from other libraries.
+
+// (Depreciated) Output a number in the $base-unit..
+//
+// @param string $weight
+//   A weight from the $font-weight map.
+//
+// @return string
+//   The selected font-weight.
+@function output-unit($number) {
+  @warn "output-unit() is depreciated. Please use typey-output-in-base-unit() instead.";
+  @return typey-output-in-base-unit($number);
+}
+
+// (Depreciated) Remove the unit from a number.
+//
+// @param number $number
+//   The number (with unit) to convert. Allowed units: any
+//
+// @return number
+//   The number without the unit.
+@function strip-unit($number) {
+  @warn "strip-unit() is depreciated. Please use typey-strip-unit() instead.";
+  @return typey-strip-unit($number);
+}
+
+// (Depreciated) Convert px to the $base-unit.
+//
+// @param number $number
+//   The number (with unit) to convert. Allowed units: px
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The number converted to the base unit.
+@function convert-unit($number, $context: $base-font-size) {
+  @warn "convert-unit() is depreciated. Please use output-from-px() instead.";
+  @return output-from-px($number, $context);
+}
+
+// (Depreciated) Retrieve a font weight.
+//
+// @param string $weight
+//   A weight from the $font-weight map.
+//
+// @return string
+//   The selected font-weight.
+@function font-weight($weight) {
+  @warn "font-weight() is depreciated. Please use weight() instead.";
+  @return weight($weight);
+}

data/stylesheets/typey/functions/_em-calculators.scss

@@ -0,0 +1,41 @@
+// Calculate relative sizing for em when a px value is used.
+//
+// @param number $number
+//   The px value
+// @param number|string $context
+//   The relative value to perform the calculation.
+//
+// @return number
+//   The calculated value in the base unit.
+@function calculate-em-px($x, $context) {
+  $allowed-types: "font-size", "px";
+  $type: typey-validator($context, $allowed-types);
+  @if $type == "font-size" {
+    $context-map-size: map-get($font-size, $context);
+    @return typey-output-in-base-unit(($x / $context-map-size));
+  }
+  @if $type == "px" {
+    @return typey-output-in-base-unit(($x / $context));
+  }
+}
+
+// Calculate relative sizing for em when a multiplier is used.
+//
+// @param number $number
+//   Multiple of line height to be used.
+// @param number|string $context
+//   The relative value to perform the calculation.
+//
+// @return number
+//   The calculated value in the base unit.
+@function calculate-em-multiplier($x, $context) {
+  $allowed-types: "font-size", "px";
+  $type: typey-validator($context, $allowed-types);
+  @if $type == "font-size" {
+    $context-map-size: map-get($font-size, $context);
+    @return typey-output-in-base-unit(($x * $base-line-height) / $context-map-size);
+  }
+  @if $type == "px" {
+    @return typey-output-in-base-unit(($x * $base-line-height) / $context);
+  }
+}

data/stylesheets/typey/{_weight.scss → functions/_extras.scss}

@@ -19,14 +19,16 @@
   }
 }
 
-// (Depreciated) Retrieve a font weight.
+// Extend a font by adding a web-safe stack to it.
 //
-// @param string $weight
-//   A weight from the $font-weight map.
+// Example usage:
+//   $new-font-stack: extend-font-stack("Open sans", $sans-serif-stack);
 //
-// @return string
-//   The selected font-weight.
-@function font-weight($weight) {
-  @warn "font-weight() is depreciated. Please use weight() instead.";
-  @return weight($weight);
+// @param string $font
+//   The name of the font. Use inverted commas if there are spaces in the font
+//   name. i.e "Open sans"
+// @param list $font-stack
+//   The font stack variable to extend.
+@function extend-font-stack($font, $font-stack) {
+  @return join($font, $font-stack, $separator: comma);
 }

data/stylesheets/typey/functions/_helpers.scss

@@ -0,0 +1,32 @@
+// Output a number in the $base-unit.
+//
+// @param number $number
+//   The number (without unit) to output.
+//
+// @return number
+//   The number with the base unit
+@function typey-output-in-base-unit($number) {
+  @if $base-unit == rem {
+    @return $number * 1rem;
+  }
+  @if $base-unit == px {
+    @return $number * 1px;
+  }
+  @if $base-unit == em {
+    @return $number * 1em;
+  }
+}
+
+// Remove the unit from a number.
+//
+// @param number $number
+//   The number (with unit) to convert. Allowed units: any
+//
+// @return number
+//   The number without the unit.
+@function typey-strip-unit($number) {
+  @if type-of($number) == "number" and not unitless($number) {
+    @return $number / ($number * 0 + 1);
+  }
+  @return $number;
+}

data/stylesheets/typey/functions/_outputters.scss

@@ -0,0 +1,83 @@
+// Take a px value and output converted value.
+//
+// @param number $number
+//   A px value to convert.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The number converted to the base unit.
+@function output-from-px($number, $context: $base-font-size) {
+  @if $base-unit == rem {
+    @return typey-output-in-base-unit(($number / $base-font-size));
+  }
+  @if $base-unit == px {
+    @return typey-output-in-base-unit(typey-strip-unit($number));
+  }
+  @if $base-unit == em {
+    @return calculate-em-px($number, $context);
+  }
+}
+
+// Take a key from the $font-size map and output converted value.
+//
+// @param string $size
+//   A size from the $font-size map.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the parent
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The selected font-size in $base-unit.
+@function output-from-font-size-map($size, $context: $base-font-size) {
+  $map-size: map-get($font-size, $size);
+  @if $base-unit == rem {
+    @return typey-output-in-base-unit(($map-size / $base-font-size));
+  }
+  @if $base-unit == px or $base-unit == pt {
+    @return typey-output-in-base-unit(typey-strip-unit($map-size));
+  }
+  @if $base-unit == em {
+    @return calculate-em-px($map-size, $context);
+  }
+}
+
+// Take a line-height multipler and output converted value.
+//
+// @param number $number
+//   Multiple of line height to be used.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The value of the line-height multiple converted to the base unit.
+@function output-from-multiplier($x, $context: $base-font-size) {
+  @if $base-unit == rem {
+    @return typey-output-in-base-unit(($x * $base-line-height) / $base-font-size);
+  }
+  @if $base-unit == px {
+    @return typey-output-in-base-unit(typey-strip-unit($x * $base-line-height));
+  }
+  @if $base-unit == em {
+    @return calculate-em-multiplier($x, $context);
+  }
+}
+
+// Take a line-height ratio and output as em.
+//
+// @param number $ratio
+//   Multiple of the $font-size to be used.
+// @param number|string $context
+//  (optional) used to ensure function outputs the ratio regardless of whether
+//  it is the same as the $base-line-height-ratio.
+//
+// @return number
+//   The ratio in em.
+@function output-from-ratio($ratio: $base-line-height-ratio) {
+  @return $ratio * 1em;
+}

data/stylesheets/typey/functions/_sizers.scss

@@ -0,0 +1,117 @@
+// Takes a sizing from the $font-size map (m, xl, xxl, etc) and convert it to
+// the base unit. Alternatively convert a px font-size into the base unit.
+//
+// @param number|string $size
+//   A size from the $font-size map or px value to be converted
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the parent
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The selected font-size in $base-unit.
+@function font-size($size, $context: $base-font-size) {
+  $allowed-types: "font-size", "px";
+  $type: typey-validator($size, $allowed-types);
+  @if $type == "font-size" {
+    @return output-from-font-size-map($size, $context);
+  }
+  @if $type == "px" {
+    @return output-from-px($size, $context);
+  }
+}
+
+// Generate a value to be used as line-height from either:
+//   a) a multiple of $base-line-height
+//   b) a static px value
+//   c) a ratio of the font-size
+//
+// Example usage with multiple:
+//   line-height: line-height(2);
+// Example usage with static value:
+//   line-height: line-height(18px);
+// Example usage with ratio:
+//   line-height: line-height(1.5);
+//
+// @param number $x
+//   Multiple of line height to be used, px value to be converted, or ratio of
+//   font-size.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the
+//   elements/parents font-size if it differs from $base-font-size.
+//   Specified as a t-shirt size or value in px.
+// @return number
+//   The calculated height in $base-unit.
+@function line-height($x, $context: $base-font-size) {
+  $allowed-types: "multiplier", "px";
+  $type: typey-validator($x, $allowed-types);
+  @if $type == "multiplier" {
+    @if ($line-height-method == "ratio") {
+      @return output-from-ratio($x);
+    }
+    @else {
+      @return output-from-multiplier($x, $context);
+    }
+  }
+  @if $type == "px" {
+    @return output-from-px($x, $context);
+  }
+}
+
+// Generate a value to be used as margin from either:
+//   a) a multiple of $base-line-height
+//   b) a static px value
+//
+// Example usage with multiple:
+//   line-height: line-height(2);
+// Example usage with static value:
+//   line-height: line-height(18px);
+//
+// @param number $x
+//   Multiple of line height to be used or px value to be converted.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The calculated height in $base-unit.
+@function margin($x, $context: $base-font-size) {
+  $allowed-types: "multiplier", "px";
+  $type: typey-validator($x, $allowed-types);
+  @if $type == "multiplier" {
+    @return output-from-multiplier($x, $context);
+  }
+  @if $type == "px" {
+    @return output-from-px($x, $context);
+  }
+}
+
+// Generate a value to be used as padding from either:
+//   a) a multiple of $base-line-height
+//   b) a static px value
+//
+// Example usage with multiple:
+//   line-height: line-height(2);
+// Example usage with static value:
+//   line-height: line-height(18px);
+//
+// @param number $x
+//   Multiple of line height to be used or px value to be converted.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+//
+// @return number
+//   The calculated height in $base-unit.
+@function padding($x, $context: $base-font-size) {
+  $allowed-types: "multiplier", "px";
+  $type: typey-validator($x, $allowed-types);
+  @if $type == "multiplier" {
+    @return output-from-multiplier($x, $context);
+  }
+  @if $type == "px" {
+    @return output-from-px($x, $context);
+  }
+}

data/stylesheets/typey/functions/_validators.scss

@@ -0,0 +1,77 @@
+// Takes a value and checks to ensure it's expressed correctly then returns
+// the type.
+//
+// @param number|string|list $x
+//   A multiple of $base-line-height.
+//   A px value.
+//   A size from the $font-size map.
+//   A space seperated list container multiples and/or px values.
+//
+// @return string
+//   multiplier, px, font-size, list
+@function typey-check-value($x) {
+  @if type-of($x) == "number" {
+    @if unitless($x) {
+      @return "multiplier";
+    }
+    @if not unitless($x) {
+      @if unit($x) == px {
+        @return "px";
+      }
+      @else {
+        @error "All units must be expressed in px";
+      }
+    }
+  }
+  @if type-of($x) == "string" {
+    @if map-has-key($font-size, $x) {
+      @return "font-size";
+    }
+    @else {
+      @error "'#{$x}' not found in $font-size map";
+    }
+  }
+  @if type-of($x) == "list" {
+    @if list-separator($x) == space {
+      @each $value in $x {
+        @if type-of($value) == "number" {
+          @if not unitless($value) and unit($value) != px {
+            @error "All units must be expressed in px";
+          }
+        }
+        @else {
+          @error "Values specified inside lists must be a number";
+        }
+      }
+      @return "list";
+    }
+    @else {
+      @error "All lists must use a space as their seperator";
+    }
+  }
+  @else {
+    @return type-of($x);
+  }
+}
+
+// Takes a value and validates it against a specified type.
+//
+// @param number|string|list $x
+//   A multiple of $base-line-height.
+//   A px value.
+//   A size from the $font-size map.
+//   A space seperated list container multiples and/or px values.
+// @param string|list $allowed-types
+//   Either multiplier, px, font-size, list, or a comibation specified in a list.
+//
+// @return string
+//   The values type.
+@function typey-validator($x, $allowed-types) {
+  $type: typey-check-value($x);
+  @if index($allowed-types, $type) != null {
+    @return $type;
+  }
+  @else {
+    @error "'#{$type}' is not a valid type for this function (allowed types are: #{$allowed-types})";
+  }
+}

data/stylesheets/typey/mixins/_define-type-sizing.scss

@@ -0,0 +1,49 @@
+// Define defaults (use this in the HTML element).
+//
+// @param number $size
+//   (optional) The font-size. Use to set to anything other than $base-font-size.
+// @param number $line-height
+//   (optional) The line-height. Use to set to anything other than $base-line-height.
+//   Set to a ratio when $line-height-as-ratio is true. Will default to $base-line-height-ratio.
+//   Set to false if you do not want to change a ratio of line-height already set.
+@mixin define-type-sizing($size: $base-font-size, $line-height: $base-line-height) {
+  @if $base-unit == rem or $base-unit == em {
+    font-size: $size / $browser-font-size * 100%;
+  }
+  @if $base-unit == px {
+    font-size: $size;
+  }
+
+  @if $line-height != false {
+    @if $line-height-method == "ratio" {
+      @if $line-height == $base-line-height {
+        $line-height: $base-line-height-ratio;
+      }
+      line-height: $line-height * 1em;
+    }
+    @else {
+      @if $base-unit == rem {
+        @if $rem-fallback == true {
+          line-height: $line-height;
+        }
+      }
+      @if $base-unit == rem or $base-unit == em {
+        line-height: typey-output-in-base-unit($line-height / $size);
+      }
+      @if $base-unit == px {
+        line-height: $line-height;
+      }
+    }
+  }
+
+  @if $auto-print-sizing == true {
+    @if $base-unit == rem or $base-unit == em {
+      @media print {
+        font-size: $print-font-size;
+      }
+    }
+    @else {
+      @warn "As you are not using a relative base unit (rem or em) automatic print media sizing will not work. Set $auto-print-sizing to false to hide this warning"
+    }
+  }
+}

data/stylesheets/typey/mixins/_font-size.scss

@@ -0,0 +1,24 @@
+// Define font-size (with fallback)
+//
+// @param number|string $size
+//   A size from the $font-size map or px value to be converted
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the elements/parents
+//   font-size if it differs from $base-font-size. Specified as a t-shirt size or
+//   value in px.
+@mixin font-size($size, $context: $base-font-size) {
+  $allowed-types: "font-size", "px";
+  $type: typey-validator($size, $allowed-types);
+  @if $base-unit == rem {
+    @if $rem-fallback == true {
+      @if $type == "font-size" {
+        $map-size: map-get($font-size, $size);
+        font-size: $map-size;
+      }
+      @if $type == "px" {
+        font-size: $size;
+      }
+    }
+  }
+  font-size: font-size($size, $context);
+}

data/stylesheets/typey/mixins/_line-height.scss

@@ -0,0 +1,25 @@
+// Define line-height (with fallback).
+// This is only necessary to use if you want to provide fallbacks when you are
+// using rem as $base-unit.
+//
+// @param number $x
+//   Multiple of line height to be used or px value to be converted.
+// @param number|string $context
+//   (optional) Only used if em is the $base-unit. The value of the
+//   elements/parents font-size if it differs from $base-font-size.
+//   Specified as a t-shirt size or value in px.
+@mixin line-height($x, $context: $base-font-size) {
+  $allowed-types: "multiplier", "px";
+  $type: typey-validator($x, $allowed-types);
+  @if $base-unit == rem and $line-height-method == "rhythm" {
+    @if $rem-fallback == true {
+      @if $type == "multiplier" {
+        line-height: $x * $base-line-height;
+      }
+      @if $type == "px" {
+        line-height: $x;
+      }
+    }
+  }
+  line-height: line-height($x, $context);
+}