neat 1.7.0.pre → 1.7.0.rc

data/app/assets/stylesheets/grid/{_direction.scss → _direction-context.scss}

@@ -1,29 +1,28 @@
 /**
  * Changes the direction property used by other mixins called in the code block argument.
  *
- * @param {String} $direction (left-to-right) - Layout direction to be used within the block. Can be `left-to-right` or `right-to-left`.
+ * @param {String} $direction (left-to-right)
+ *   Layout direction to be used within the block. Can be `left-to-right` or `right-to-left`.
  *
- * @example scss
+ * @example scss - Usage
  *   @include direction(right-to-left) {
  *    .right-to-left-block {
  *      @include span-columns(6);
  *     }
  *   }
  *
- * @example css
- *   // CSS
+ * @example css - CSS Output
  *   .right-to-left-block {
  *     float: right;
  *      ...
  *   }
  */
-
-@mixin direction($direction: left-to-right) {
+@mixin direction-context($direction: left-to-right) {
   $scope-direction: $layout-direction;
 
-  @if $direction == left-to-right {
+  @if to-lower-case($direction) == "left-to-right" {
     $layout-direction: LTR !global;
-  } @else if $direction == right-to-left {
+  } @else if to-lower-case($direction) == "right-to-left" {
     $layout-direction: RTL !global;
   }
 

data/app/assets/stylesheets/grid/{_display.scss → _display-context.scss}

@@ -1,7 +1,8 @@
 /**
  * Changes the display property used by other mixins called in the code block argument.
  *
- * @param {String} $display (block) - Display value to be used within the block. Can be `table` or `block`.
+ * @param {String} $display (block)
+ *   Display value to be used within the block. Can be `table` or `block`.
  *
  * @example scss
  *   @include display(table) {
@@ -11,16 +12,14 @@
  *   }
  *
  * @example css
- *   // CSS
  *   .display-table {
  *      display: table-cell;
  *      ...
  *   }
  */
-
-@mixin display($display: block) {
+@mixin display-context($display: block) {
   $scope-display: $container-display-table;
-  $container-display-table: if($display == table, true, false) !global;
+  $container-display-table: $display == table !global;
 
   @content;
 

data/app/assets/stylesheets/grid/_fill-parent.scss

@@ -1,3 +1,19 @@
+/**
+ * Forces the element to fill its parent container.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include fill-parent;
+ *   }
+ *
+ * @example css - CSS Output
+ *   .element {
+ *     width: 100%;
+ *     -webkit-box-sizing: border-box;
+ *     -moz-box-sizing: border-box;
+ *     box-sizing: border-box;
+ *   }
+ */
 @mixin fill-parent() {
   width: 100%;
 

data/app/assets/stylesheets/grid/_media.scss

@@ -1,4 +1,59 @@
-@mixin media($query:$feature $value $columns, $total-columns: $grid-columns) {
+/**
+ * Outputs a media-query block with an optional grid context (the total number of columns used in the grid).
+ *
+ * @param {List} $query
+ *   A list of media query features and values, where each `$feature` should have a corresponding `$value`.
+ *   For a list of valid values for `$feature`, click [here](http://www.w3.org/TR/css3-mediaqueries/#media1).
+ *
+ *   If there is only a single `$value` in `$query`, `$default-feature` is going to be used.
+ *
+ *   The number of total columns in the grid can be set by passing `$columns` at the end of the list (overrides `$total-columns`).
+ *
+ *
+ * @param {Number (unitless)} $total-columns ($grid-columns)
+ *   - Number of columns to use in the new grid context. Can be set as a shorthand in the first parameter.
+ *
+ * @example scss - Usage
+ *   .responsive-element {
+ *      @include media(769px) {
+ *        @include span-columns(6);
+ *      }
+ *   }
+ *
+ *  .new-context-element {
+ *    @include media(min-width 320px max-width 480px, 6) {
+ *      @include span-columns(6);
+ *    }
+ *  }
+ *
+ * @example css - CSS Output
+ *  @media screen and (min-width: 769px) {
+ *    .responsive-element {
+ *      display: block;
+ *      float: left;
+ *      margin-right: 2.35765%;
+ *      width: 48.82117%;
+ *    }
+ *
+ *    .responsive-element:last-child {
+ *      margin-right: 0;
+ *    }
+ *  }
+ *
+ *  @media screen and (min-width: 320px) and (max-width: 480px) {
+ *    .new-context-element {
+ *      display: block;
+ *      float: left;
+ *      margin-right: 4.82916%;
+ *      width: 100%;
+ *    }
+ *
+ *    .new-context-element:last-child {
+ *      margin-right: 0;
+ *    }
+ *  }
+ */
+@mixin media($query: $feature $value $columns, $total-columns: $grid-columns) {
   @if length($query) == 1 {
     @media screen and ($default-feature: nth($query, 1)) {
       $default-grid-columns: $grid-columns;
@@ -9,28 +64,28 @@
   }
 
   @else {
-    $loopTo: length($query);
-    $mediaQuery: 'screen and ';
+    $loop-to: length($query);
+    $media-query: 'screen and ';
     $default-grid-columns: $grid-columns;
     $grid-columns: $total-columns !global;
 
-    @if length($query) % 2 != 0 {
-      $grid-columns: nth($query, $loopTo) !global;
-      $loopTo: $loopTo - 1;
+    @if not is-even(length($query)) {
+      $grid-columns: nth($query, $loop-to) !global;
+      $loop-to: $loop-to - 1;
     }
 
     $i: 1;
-    @while $i <= $loopTo {
-      $mediaQuery: $mediaQuery + '(' + nth($query, $i) + ': ' + nth($query, $i + 1) + ') ';
+    @while $i <= $loop-to {
+      $media-query: $media-query + '(' + nth($query, $i) + ': ' + nth($query, $i + 1) + ') ';
 
-      @if ($i + 1) != $loopTo {
-        $mediaQuery: $mediaQuery + 'and ';
+      @if ($i + 1) != $loop-to {
+        $media-query: $media-query + 'and ';
       }
 
       $i: $i + 2;
     }
 
-    @media #{$mediaQuery} {
+    @media #{$media-query} {
       @content;
       $grid-columns: $default-grid-columns !global;
     }

data/app/assets/stylesheets/grid/_omega.scss

@@ -1,7 +1,38 @@
-// Remove last element gutter
+/**
+ * Removes the element's gutter margin, regardless of its position in the grid hierarchy or display property. It can target a specific element, or every `nth-child` occurrence. Works only with `block` layouts.
+ *
+ * @param {List} $query (block)
+ *   List of arguments. Supported arguments are `nth-child` selectors (targets a specific pseudo element) and `auto` (targets `last-child`).
+ *
+ *   When passed an `nth-child` argument of type `*n` with `block` display, the omega mixin automatically adds a clear to the `*n+1` th element. Note that composite arguments such as `2n+1` do not support this feature.
+ *
+ *   **Deprecation warning**: The omega mixin will no longer take a `$direction` argument. To change the layout direction, use `row($direction)` or set `$default-layout-direction` instead.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include omega;
+ *   }
+ *
+ *   .nth-element {
+ *     @include omega(4n);
+ *   }
+ *
+ * @example css - CSS Output
+ *   .element {
+ *     margin-right: 0;
+ *   }
+ *
+ *   .nth-element:nth-child(4n) {
+ *     margin-right: 0;
+ *   }
+ *
+ *   .nth-element:nth-child(4n+1) {
+ *     clear: left;
+ *   }
+ */
 @mixin omega($query: block, $direction: default) {
-  $table: if(belongs-to(table, $query), true, false);
-  $auto: if(belongs-to(auto, $query), true, false);
+  $table: belongs-to(table, $query);
+  $auto: belongs-to(auto, $query);
 
   @if $direction != default {
     @include -neat-warn("The omega mixin will no longer take a $direction argument. To change the layout direction, use the direction(){...} mixin.");

data/app/assets/stylesheets/grid/_outer-container.scss

@@ -1,33 +1,32 @@
 /**
  * Makes an element a outer container by centring it in the viewport, clearing its floats, and setting its `max-width`.
- *
  * Although optional, using `outer-container` is recommended. The mixin can be called on more than one element per page, as long as they are not nested.
  *
- * @param {Number} $local-max-width ($max-width) - Max width to be applied to the element. Can be a percentage or a measure.
+ * @param {Number (unit)} $local-max-width ($max-width)
+ *   Max width to be applied to the element. Can be a percentage or a measure.
  *
- * @example scss
- *  .element {
- *    @include outer-container(100%);
- *  }
+ * @example scss - Usage
+ *   .element {
+ *     @include outer-container(100%);
+ *   }
  *
- * @example css
- *  .element {
- *    *zoom: 1;
- *    max-width: 100%;
- *    margin-left: auto;
- *    margin-right: auto;
- *  }
+ * @example css - CSS Output
+ *   .element {
+ *     *zoom: 1;
+ *     max-width: 100%;
+ *     margin-left: auto;
+ *     margin-right: auto;
+ *   }
  *
- *  .element:before, .element:after {
- *    content: " ";
- *    display: table;
- *  }
+ *   .element:before, .element:after {
+ *     content: " ";
+ *     display: table;
+ *   }
  *
- *  .element:after {
- *    clear: both;
- *  }
+ *   .element:after {
+ *     clear: both;
+ *   }
  */
-
 @mixin outer-container($local-max-width: $max-width) {
   @include clearfix;
   max-width: $local-max-width;

data/app/assets/stylesheets/grid/_pad.scss

@@ -1,3 +1,19 @@
+/**
+ * Adds padding to the element.
+ *
+ * @param {List} $padding (flex-gutter())
+ *   A list of padding value(s) to use. Passing `default` in the list will result in using the gutter width as a padding value.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include pad(30px -20px 10px default);
+ *   }
+ *
+ * @example css - CSS Output
+ *   .element {
+ *     padding: 30px -20px 10px 2.35765%;
+ *   }
+ */
 @mixin pad($padding: flex-gutter()) {
   $padding-list: null;
   @each $value in $padding {

data/app/assets/stylesheets/grid/_private.scss

@@ -3,7 +3,7 @@ $fg-column: $column;
 $fg-gutter: $gutter;
 $fg-max-columns: $grid-columns;
 $container-display-table: false !default;
-$layout-direction: nil !default;
+$layout-direction: LTR !default;
 
 @function flex-grid($columns, $container-columns: $fg-max-columns) {
   $width: $columns * $fg-column + ($columns - 1) * $fg-gutter;
@@ -31,13 +31,5 @@ $layout-direction: nil !default;
 }
 
 @function is-display-table($container-is-display-table, $display) {
-  $display-table: false;
-
-  @if $container-is-display-table == true {
-    $display-table: true;
-  } @else if $display == table {
-    $display-table: true;
-  }
-
-  @return $display-table;
+  @return $container-is-display-table == true or $display == table;
 }

data/app/assets/stylesheets/grid/_row.scss

@@ -1,3 +1,32 @@
+/**
+ * Designates the element as a row of columns in the grid layout. It clears the floats on the element and sets its display property. Rows can't be nested, but there can be more than one row element—with different display properties—per layout.
+ *
+ * @param {String} $display (default)
+ *   Sets the display property of the element and the display context that will be used by its children. Can be `block` or `table`.
+ *
+ * @param {String} $direction ($default-layout-direction)
+ *   Sets the layout direction. Can be `LTR` (left-to-right) or `RTL` (right-to-left).
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include row();
+ *   }
+ *
+ * @example css - CSS Output
+ *   .element {
+ *     *zoom: 1;
+ *     display: block;
+ *   }
+ *
+ *  .element:before, .element:after {
+ *    content: " ";
+ *    display: table;
+ *  }
+ *
+ *  .element:after {
+ *    clear: both;
+ *  }
+ */
 @mixin row($display: default, $direction: $default-layout-direction) {
   @if $direction != $default-layout-direction {
     @include -neat-warn("The $direction argument will be deprecated in future versions in favor of the direction(){...} mixin.");

data/app/assets/stylesheets/grid/_shift.scss

@@ -1,7 +1,41 @@
+/**
+ * Translates an element horizontally by a number of columns. Positive arguments shift the element to the active layout direction, while negative ones shift it to the opposite direction.
+ *
+ * @param {Number (unitless)} $n-columns (1)
+ *   Number of columns by which the element shifts.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include shift(-3);
+ *   }
+ *
+ * @example css - CSS output
+ *   .element {
+ *     margin-left: -25.58941%;
+ *   }
+ */
 @mixin shift($n-columns: 1) {
   @include shift-in-context($n-columns);
 }
 
+/**
+ * Translates an element horizontally by a number of columns, in a specific nesting context.
+ *
+ * @param {List} $shift
+ *   A list containing the number of columns to shift (`$columns`) and the number of columns of the parent element (`$container-columns`).
+ *
+ *   The two values can be separated with any string such as `of`, `/`, etc.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include shift(-3 of 6);
+ *   }
+ *
+ * @example css - CSS output
+ *   .element {
+ *     margin-left: -52.41458%;
+ *   }
+ */
 @mixin shift-in-context($shift: $columns of $container-columns) {
   $n-columns: nth($shift, 1);
   $parent-columns: container-shift($shift) !global;

data/app/assets/stylesheets/grid/_span-columns.scss

@@ -1,8 +1,56 @@
+/**
+ * Specifies the number of columns an element should span. If the selector is nested the number of columns of its parent element should be passed as an argument as well.
+ *
+ * @param {List} $span
+ *   A list containing `$columns`, the unitless number of columns the element spans (required), and `$container-columns`, the number of columns the parent element spans (optional).
+ *
+ *   If only one value is passed, it is assumed that it's `$columns` and that that `$container-columns` is equal to `$grid-columns`, the total number of columns in the grid.
+ *
+ *   The values can be separated with any string such as `of`, `/`, etc.
+ *
+ * @param {String} $display (block)
+ *   Sets the display property of the element. By default it sets the display propert of the element to `block`.
+ *
+ *   If passed `block-collapse`, it also removes the margin gutter by adding it to the element width.
+ *
+ *   If passed `table`, it sets the display property to `table-cell` and calculates the width of the element without taking gutters into consideration. The result does not align with the block-based grid.
+ *
+ * @example scss - Usage
+ *   .element {
+ *     @include span-columns(6);
+
+ *    .nested-element {
+ *      @include span-columns(2 of 6);
+ *    }
+ *  }
+ *
+ * @example css - CSS Output
+ *   .element {
+ *     display: block;
+ *     float: left;
+ *     margin-right: 2.35765%;
+ *     width: 48.82117%;
+ *   }
+ *
+ *   .element:last-child {
+ *     margin-right: 0;
+ *   }
+ *
+ *   .element .nested-element {
+ *     display: block;
+ *     float: left;
+ *     margin-right: 4.82916%;
+ *     width: 30.11389%;
+ *   }
+ *
+ *   .element .nested-element:last-child {
+ *     margin-right: 0;
+ *   }
+ */
 @mixin span-columns($span: $columns of $container-columns, $display: block) {
   $columns: nth($span, 1);
   $container-columns: container-span($span);
 
-  // Set nesting context (used by shift())
   $parent-columns: get-parent-columns($container-columns) !global;
 
   $direction: get-direction($layout-direction, $default-layout-direction);