susy 3.0.0.alpha.1 → 3.0.0.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa2aa38b4ee8f4a92e3d6cecb470ebcdde3dbb29
-  data.tar.gz: 74d57ae39653cb41f6d13d667b9205f0163eef35
+  metadata.gz: 8abe53f196f31e63a27a0457d54af4b1586a60b0
+  data.tar.gz: 084c64a7897e0b887078063b6ddbe410d8f46616
 SHA512:
-  metadata.gz: 2b2b113cad8db26b6f4b10a73893f15339dfcddb4a2f35bfb36774faa85f46a294ee0667d271d75c56fdff104d085b6f98e352c8a5b3e4a46e3ae7e841741a97
-  data.tar.gz: eb5cb812bcc15d7fbf1eb51d3d0246f2ab583e5ed32a155f4fb32b301f216afdf288875b7981c60538dec5806e3fd06a26cd0106e76249853999ccfbd3c99709
+  metadata.gz: 1164998a065a00be67b0b8253b4d0fd60f7e974d80f22a12dbb5b29b3cd09d9c2295c5a2580a79b987f4ab6fb9cade596d9d78fda428ab91df81eaa9dca64d7a
+  data.tar.gz: 73c1eddf36ad9161bdac645fe76db17cfd8227fbe50b8baddf392df75444625b72fc7e9076c2f1f72f7a3f8974ccbbd204e1b35586027afc5b8a60cd7dea81bb

data/README.md

@@ -10,136 +10,189 @@ full of rules and restrictions —
 we wanted a power tool
 for building our own damn systems.
 
-Do It Yourself.
-Your Markup,
-Your Layout —
-*Our Math*
+Version Three is trimmed down to it's most basic components —
+functions that can be used to build any grid system.
+This is truely a grids-on-demand approach,
+where you build your own system,
+and we handle the math.
+
+We're planning to build various output-modules
+with mixins to help you get started.
+We'll probably start with a float-based module,
+and a flexbox module.
+If you have ideas for another plugin,
+or want to help move floats or flexbox along,
+pull requests are welcome!
 
 
 Getting Started
 ---------------
 
-Susy v3 is trimmed down to it's most basic components —
-functions that can be used to build any grid system.
+You can install Susy as a rubygem,
+npm module, bower package, or git repo.
 
-There are four global settings to understand,
-and two of them are identical:
+```
+npm install susy@pre
+```
 
+There are two imports to choose from.
+The default `sass/_susy.scss` comes with
+un-prefixed versions of the core API functions.
+If you want Susy to be name-spaced,
+import `sass/_prefix.scss` instead.
 
-### Columns
+```scss
+@import '../node_modules/susy/sass/susy';
+```
 
-The `columns` setting describes the columns in your grid.
-The most basic syntax uses a list of numbers
-to describe the relative size of each column.
 
-```scss
-// five equal columns
-$symmetrical: (1 1 1 1 1);
+Spanning Columns & Gutters
+--------------------------
 
-// six fibonacci columns
-$asymmetrical: (1 1 2 3 5 8);
+There are two core funtions:
+`span()` (or `susy-span()`),
+and `gutter()` (or `susy-gutter()`).
+
+The **gutter** function returns
+the width of a single gutter on your grid —
+to be applied as you see fit:
+
+```scss
+.example {
+  margin: susy-gutter();
+}
 ```
 
-If you want static grids,
-you can add units to the numbers —
-as long as all the units are comparable.
+The **span** function
+describes a span of one or more columns,
+and any relevant gutters along the way:
 
 ```scss
-// five equal static columns
-$symmetrical: (120px 120px 120px 120px 120px);
+.example {
+  // the width of three columns, and the two intervening gutters
+  width: susy-span(3);
+}
+```
+
+When nesting fluid grids,
+you can use the old `of $n` syntax
+to describe changes in context —
+e.g. `susy-span(3 of 6)`.
+When using asymmetrical grids,
+you can use the old `at $n`, `first`, or `last` syntax
+to describe the specific columns you want to span —
+e.g. `susy-span(3 at 2 of (1 2 3 4 5 6))`
+to span across `(2 3 4)`.
+
+You can use these two functions
+to build all sorts of grids:
 
-// six not-fibonacci static columns
-$asymmetrical: (1in 1cm 2pt 3mm 5in 8cm);
+```scss
+.float {
+  float: left;
+  width: span(3);
+  margin-right: gutter();
+}
+
+.flexbox {
+  flex-basis: span(3);
+  padding: gutter() / 2;
+}
+
+// Make your own class system!
+.span {
+  float: left;
+  margin-right: gutter();
+
+  &.last {
+    margin-right: 0;
+  }
+}
+
+@for $span from 1 through susy-get('columns') {
+  .span-#{$i} {
+    width: span($i);
+  }
+}
 ```
 
-That can get repetative
-when you are working with symmetrical grids,
-so we've provided a symmetrical shorthand.
+
+Defining Grids
+--------------
+
+A grid is defined by a series of `columns`
+with optional `gutters` between them.
+
+**Columns** are described by a list of numbers,
+representing the relative width of each column.
+By default, a grid is fluid —
+but you can add units to create a static layout:
 
 ```scss
-// five equal fluid columns (shorthand)
-$fluid: 5;
+// six equal fluid columns
+$equal: (1 1 1 1 1 1);
+
+// six equal 5em columns
+$static: (5em 5em 5em 5em 5em 5em);
+
+// six unequal fluid columns
+$asymmetrical: (1 1 2 3 5 8);
 
-// five equal static columns (shorthand)
-$static: 5 x 120px;
+// six unequal fluid columns
+// you can mix units, as long as they are comparable...
+$strange: (1in 1cm 2pt 3mm 5in 8cm);
 ```
 
-That static-symmetrical shorthand
-is technically a list.
-The first value is a unitless number,
-representing the number of columns in the grid.
-The second value is the letter "x"
-(not a star or times symbol).
-The third value is the static width of your columns.
+Since `(1 1 1 1 1 1)` is so repetative,
+we've provided a shorthand syntax
+for describung equal columns:
 
+```scss
+// six equal fluid columns (shorthand)
+$fluid: 6;
 
-### Gutters
+// six 120px static columns (shorthand)
+// that's a lowercase 'x' — not a star or any other symbol...
+$static: 6 x 120px;
+```
 
-The `gutters` setting describes the space between
-(and sometimes around)
-your columns.
-It is always defined in units
-comparable to the rest of your grid.
+**Gutters**
+are defined relative to columns,
+in comparable units.
+Both settings go together
+in a single map variable:
 
 ```scss
-// fluid 4-column grid, with gutters 1/4 the size of a column
-$columns: (1 1 1 1);
-$gutters: 0.25;
-
-// Static em-based grid, with 0.25em gutters
-$columns: (1em 1em 2em 3em 5em 8em)
-$gutters: 0.25em;
+// fluid 4-column grid
+// with gutters 1/4 the size of a column
+$fluid: (
+  'columns': 4;
+  'gutters': 0.25;
+);
+
+// Static un-equal grid
+// with comparable gutters
+$static: (
+  'columns': (1em 1em 2em 3em 5em 8em)
+  'gutters': 0.25em;
+);
 ```
 
-There is a special case
-allowing you to use static gutters in a fluid grid,
-but that's too advanced for a quick-start guide.
-
-
-### Spread & Container-Spread
-
-The concept of `spread`
-helps us describe what gutters to include
-in a grid span or container.
-There are three options:
-`narrow`, `wide`, and `wider`.
-
-Imagine a four-column grid.
-How many gutters are in that grid?
-
-- The most common answer is `3`.
-  Gutters only exist between the columns —
-  `c1 (g1) c2 (g2) c3 (g3) c4`.
-  We call that option `narrow`,
-  and it is the default value for both
-  spans and containers.
-
-- The other common answer is `5`,
-  if we want to include gutters on the outside edges —
-  `(g1) c1 (g2) c2 (g3) c3 (g4) c4 (g5)`.
-  We call that option `wider`.
-
-- Less commonly,
-  you might want only one edge gutter
-  either before or after —
-  `c1 (g1) c2 (g2) c3 (g3) c4 (g4)` —
-  leaving your with `4` gutters.
-  We call that `wide`.
-
-Spread and container-spread work in the same way,
-but one applies to a span,
-and the other applies to the parent context
-when calculating relative widths.
-If you are using static grids,
-the `container-spread` isn't used.
-
-In most cases,
-you can set the default spread for a project,
-and never look back.
-Sometimes,
-when you are pushing and pulling
-elements around on the grid,
-it is helpful to add and remove gutters on the fly.
+Anything you put in the root `$susy` variable map
+will be treated as a global default
+across your project.
+
+
+Advanced Features
+-----------------
+
+Once you get used to the basics,
+you can dig into the `spread` options —
+allowing you to include extra gutters in a span —
+and the `susy-slice()` function
+that can help you handle nesting-context with asymmetrical grids.
+
+Happy grid-building!
 
 
 Resources

data/VERSION

@@ -1 +1 @@
-3.0.0.alpha.0
+3.0.0.alpha.2

data/sass/_prefix.scss

@@ -3,6 +3,7 @@
 
 $susy-version: 3;
 
+@import 'susy/utilities';
 @import 'susy/grids';
 @import 'susy/settings';
 @import 'susy/validation';

data/sass/plugins/_svg-grid.scss

@@ -0,0 +1,5 @@
+// SVG Grid Background
+// ===================
+
+@import 'svg-grid/prefix';
+@import 'svg-grid/svg-unprefix';

data/sass/plugins/svg-grid/_prefix.scss

@@ -0,0 +1,7 @@
+// Prefixed SVG Plugin
+// ===================
+
+@import 'svg-settings';
+@import 'svg-utilities';
+@import 'svg-grid-math';
+@import 'svg-api';

data/sass/plugins/svg-grid/_svg-api.scss

@@ -0,0 +1,78 @@
+// SVG API
+// =======
+
+
+
+// SVG Grid
+// --------
+/// Return inline svg-data in  to display the grid
+/// (import `plugins/svg-grid/prefix` to remove unprefixed alias)
+///
+/// @group plugin_svg-grid
+///
+/// @param {Map | List} $grid [$susy] -
+///   Map or shorthand defining the current grid
+/// @param {Color | List | null} $colors [null] -
+///   Column color, or list of colors for column-gradient,
+///   used to override the global `svg-grid-colors` setting
+/// @param {Length | null} $offset [null] -
+///   Manually override the default grid-image offset,
+///   to account for grid edges
+///
+/// @return {String} -
+///   CSS inline-data SVG string, in `url(<svg>)` format,
+///   for use in image or content properties
+@function susy-svg-grid(
+  $grid: $susy,
+  $colors: null,
+  $offset: null
+) {
+  // Grid parsing & normalizing
+  @if (type-of($grid) != 'map') and (length($grid) > 0) {
+    @if (not index($grid, 'of')) {
+      @if su-valid-columns($grid, 'fail-silent') {
+        $grid: 'of' $grid;
+      } @else {
+        $grid: join('of', $grid);
+      }
+    }
+
+    $grid: susy-parse($grid);
+  }
+
+  $grid: susy-settings($grid);
+  $grid: susy-normalize($grid);
+
+
+  // Color and gradient handling
+  $gradient: '';
+
+  @if (not $colors) {
+    $colors: susy-get('svg-grid-colors');
+  }
+
+  @if length($colors) > 1 {
+    $gradient: _susy-svg-gradient($colors);
+    $colors: 'url(%23susy-svg-gradient)';
+  } @else {
+    $colors: _susy-svg-color($colors);
+  }
+
+
+  // SVG construction
+  $columns: map-get($grid, 'columns');
+  $offset: $offset or _susy-svg-offset($grid);
+
+  $svg: 'data:image/svg+xml,';
+  $svg: $svg + '%3Csvg xmlns="http://www.w3.org/2000/svg" fill="#{$colors}" %3E';
+  $svg: $svg + $gradient;
+
+  @for $column from 1 through length($columns) {
+    $width: susy-span(1 at $column, $grid);
+    $x: _susy-svg-column-position($column, $grid);
+
+    $svg: $svg + _susy-svg-rect($x, $width, $offset);
+  }
+
+  @return url('#{$svg}%3C/svg%3E');
+}

data/sass/plugins/svg-grid/_svg-grid-math.scss

@@ -0,0 +1,72 @@
+// SVG Grid Math
+// =============
+
+
+
+// SVG Column Position
+// -------------------
+/// Determine the proper horizontal position
+/// for a column rectangle
+///
+/// @access private
+///
+/// @param {Integer} $column -
+///   1-indexed column location on the grid
+/// @param {Map} $grid -
+///   Normalized settings map representing the current grid
+///
+/// @return {Length} -
+///   Horizontal position of svg column rectangle,
+///   as distance from the grid edge
+@function _susy-svg-column-position(
+  $column,
+  $grid
+) {
+  $x: $column - 1;
+
+  @if ($x > 0) {
+    $x: susy-span(first $x wide, $grid);
+  }
+
+  @return $x;
+}
+
+
+
+// SVG Offset
+// ----------
+/// Determine if a grid image needs to be offset,
+/// to account for edge gutters.
+///
+/// @access private
+///
+/// @param {Map} $grid -
+///   Normalized settings map representing the current grid
+///
+/// @return {Length | null} -
+///   Expected distance from container edge to first column,
+///   based on spread values and gutter-widths
+@function _susy-svg-offset(
+  $grid
+) {
+  $columns: su-valid-columns(map-get($grid, 'columns'));
+  $gutters: su-valid-gutters(map-get($grid, 'gutters'), $columns);
+  $first: nth($columns, 1);
+
+  @if (unitless($first)) and (not unitless($gutters)) {
+    @return null;
+  }
+
+  $container: map-get($grid, 'container-spread');
+  $span: map-get($grid, 'spread');
+  $extra: $container - $span;
+
+  @if $extra == 0 {
+    @return null;
+  }
+
+  @return $extra * susy-gutter($config: $grid) / 2;
+}
+
+
+

data/sass/plugins/svg-grid/_svg-settings.scss

@@ -0,0 +1,14 @@
+// SVG Settings
+// ============
+
+
+// Susy SVG Defaults
+// =================
+/// This plugin adds the `svg-grid-colors` property
+/// and default value to `$susy-defaults` —
+/// you can override that value in `$susy`
+/// or any other grid settings map.
+/// @group plugin_svg-grid
+$susy-defaults: map-merge((
+    'svg-grid-colors': hsla(120, 50%, 50%, 0.5) hsla(120, 50%, 75%, 0.5),
+  ), $susy-defaults);

data/sass/plugins/svg-grid/_svg-unprefix.scss

@@ -0,0 +1,18 @@
+// Unprefix Susy SVG Grid
+// ======================
+
+
+
+// SVG Grid
+// --------
+/// Un-prefixed alias for `susy-svg-grid`
+///
+/// @group plugin_svg-grid
+/// @alias susy-svg-grid
+@function svg-grid(
+  $grid: $susy,
+  $colors: susy-get('svg-grid-colors'),
+  $offset: null
+) {
+  @return susy-svg-grid($grid, $colors, $offset);
+}

data/sass/plugins/svg-grid/_svg-utilities.scss

@@ -0,0 +1,127 @@
+// SVG Utilities
+// =============
+
+
+
+// SVG Validate Units
+// ------------------
+/// Make sure a length is supported in svg
+///
+/// @access private
+///
+/// @param {Length} $length -
+///   The length to validate
+/// @param {String} $name [null] -
+///   Optional name of length origin,
+///   for error reporting
+///
+/// @return {Length} -
+///   An svg-validated length, or comparable valid length
+@function _susy-svg-validate-units(
+  $length,
+  $name: null
+) {
+  $_svg-units: ('em', 'ex', 'px', 'pt', 'pc', 'cm', 'mm', 'in', '%');
+
+  @if ($length == 0) or index($_svg-units, unit($length)) {
+    @return $length;
+  }
+
+  @return _susy-error(
+    '`#{unit($length)}` #{$name} units are not supported in SVG',
+    '_susy-svg-validate-units');
+}
+
+
+
+// SVG Rect
+// --------
+/// Build a single svg rectangle
+///
+/// @access private
+///
+/// @param {Length} $x -
+///   Horizontal position for the rectangle
+/// @param {Length} $width -
+///   Width of the rectangle
+/// @param {Length} $offset [null] -
+///   Offset the rectangle, to account for edge gutters
+///
+/// @return {String} -
+///   Escaped string representing one svg rectangle
+@function _susy-svg-rect(
+  $x,
+  $width,
+  $offset: null
+) {
+  $x: _susy-svg-validate-units($x);
+  $width: _susy-svg-validate-units($width);
+  $offset: if($offset == 0, null, $offset);
+
+  @if $offset and comparable($x, $offset) {
+    $x: $x + $offset;
+    $offset: null;
+  } @else if $offset {
+    $offset: 'style="transform:translateX(#{$offset})"';
+  }
+
+  @return '%3Crect x="#{$x}" width="#{$width}" height="100%" #{$offset}/%3E';
+}
+
+
+
+// SVG Color
+// ---------
+/// Stringify colors, and escape hex symbol
+///
+/// @access private
+///
+/// @param {Color} $color -
+///   Color to stringify and escape
+///
+/// @return {String} -
+///   Escaped string value of color
+@function _susy-svg-color(
+  $color
+) {
+  $color: inspect($color); // convert to string
+
+  @if (str-index($color, '#') == 1) {
+    $color: '%23' + str-slice($color, 2);
+  }
+
+  @return $color;
+}
+
+
+
+// SVG Gradient
+// ------------
+/// Create a multi-color svg gradient
+///
+/// @access private
+///
+/// @param {List} $colors -
+///   List of colors to be equally spaced from `0%` to `100%`
+///   in each column rectangle
+///
+/// @return {String} -
+///   Escaped string representing one svg gradient
+///   (`id="susy-svg-gradient"`)
+@function _susy-svg-gradient(
+  $colors
+) {
+  $gradient: '%3Cdefs%3E%3ClinearGradient spreadMethod="pad"';
+  $gradient: '#{$gradient} id="susy-svg-gradient"';
+  $gradient: '#{$gradient} x1="0%" y1="0%" x2="100%" y2="0%"%3E';
+
+  @for $i from 1 through length($colors) {
+    $color: _susy-svg-color(nth($colors, $i));
+    $offset: percentage(($i - 1) / (length($colors) - 1));
+    $stop: '%3Cstop offset="#{$offset}" style="stop-color:#{$color};" /%3E';
+
+    $gradient: $gradient + $stop;
+  }
+
+  @return $gradient + '%3C/linearGradient%3E%3C/defs%3E';
+}

data/sass/susy/_api.scss

@@ -18,13 +18,15 @@
 /// @group api
 ///
 /// @param {List} $span -
-///   Shorthand expression to define the width of the span —
-///   containing a unitless column-span;
-///   'of $n' for available grid columns [optional];
-///   'at $n', 'first', or 'last' for location on asymmetrical grids;
-///   and 'narrow', 'wide', or 'wider' for
-///   optionally spreading over adjacent gutters
-///   with either the `span` or `columns` value
+///   Shorthand expression to define the width of the span,
+///   optionally containing:
+///   - a count, length, or column-list span;
+///   - `at $n`, `first`, or `last` location on asymmetrical grids;
+///   - `narrow`, `wide`, or `wider` for optionally spreading
+///     across adjacent gutters;
+///   - `of $n <spread>` for available grid columns
+///     and spread of the container;
+///   - and `set-gutters $n` to override global gutter settings
 /// @param {Map} $config [()] -
 ///   Optional map of Susy grid configuration settings
 ///
@@ -48,7 +50,24 @@
   $input: susy-settings($config, susy-parse($span));
   $normal: susy-normalize($input);
 
-  @return su-span($normal...);
+  @if map-get($normal, 'span') {
+    $args: (
+      'span', 'columns', 'gutters', 'spread', 'container-spread', 'location'
+    );
+
+    @each $key in map-keys($normal) {
+      @if not (index($args, $key)) {
+        $normal: map-remove($normal, $key);
+      }
+    }
+
+    @return su-span($normal...);
+  }
+
+  $actual: '[#{type-of($span)}] `#{inspect($span)}`';
+  @return _susy-error(
+    'Unable to determine span value from #{$actual}.',
+    'susy-span');
 }
 
 
@@ -62,7 +81,10 @@
 /// @group api
 ///
 /// @param {Number | List} $context [null] -
-///   Optional columns in a nested context
+///   Optional context for nested gutters,
+///   including shorthand for
+///   `columns`, `gutters`, and `container-spread`
+///   (additional shorthand will be ignored)
 /// @param {Map} $config [()] -
 ///   Optional map of Susy grid configuration settings
 ///
@@ -78,16 +100,25 @@
   $context: susy-get('columns'),
   $config: ()
 ) {
+  @if (not index($context, 'of')) {
+    @if su-valid-columns($context, 'fail-silent') {
+      $context: 'of' $context;
+    } @else {
+      $context: join('of', $context);
+    }
+  }
+
+  $parsed: susy-settings($config, susy-parse($context));
+  $normal: susy-normalize($parsed);
   $args: ('columns', 'gutters', 'container-spread');
-  $input: susy-settings($config, ('columns': $context));
-  $normal: susy-normalize($input);
-  $output: ();
 
-  @each $setting in $args {
-    $output: map-merge($output, ($setting: map-get($normal, $setting)));
+  @each $key in map-keys($normal) {
+    @if not (index($args, $key)) {
+      $normal: map-remove($normal, $key);
+    }
   }
 
-  @return su-gutter($output...);
+  @return su-gutter($normal...);
 }
 
 

data/sass/susy/_grids.scss

@@ -38,18 +38,18 @@
   $container-spread: $spread,
   $location: 1
 ) {
+  $span: su-valid-span($span);
   $columns: su-valid-columns($columns);
   $gutters: su-valid-gutters($gutters, $columns);
   $spread: su-valid-spread($spread);
 
   @if (type-of($span) == 'number') {
-    @if unitless($span) {
-      $location: su-valid-location($span, $location, $columns);
-      $span: su-slice($span, $columns, $location, $validate: false);
-    } @else {
-      // if you give us e.g. 3em, fine, we'll give it right back
+    @if (not unitless($span)) {
       @return $span;
     }
+
+    $location: su-valid-location($span, $location, $columns);
+    $span: su-slice($span, $columns, $location, $validate: false);
   }
 
   $span-width: su-sum($span, $gutters, $spread, $validate: false);
@@ -135,10 +135,8 @@
     $column-sum: $column-sum + $column;
   }
 
-  // Gutters are removed from the math if they use non-comparable static units
-  $not-comparable: not comparable($column-sum, $gutters);
-  $is-mismatch: unitless($column-sum) and (not unitless($gutters));
-  @if ($not-comparable or $is-mismatch) {
+  // Gutters are removed from the math if they are non-comparable
+  @if (unitless($column-sum)) and (not unitless($gutters)) {
     @return $column-sum;
   }
 

data/sass/susy/_parser.scss

@@ -8,6 +8,7 @@
 // - susy-normalize-location [function]
 
 
+
 // Parse
 // -----
 /// Parse shorthand span expression
@@ -15,23 +16,27 @@
 /// @access private
 ///
 /// @param {List} $shorthand -
-///   Shorthand expression to define the width of the span —
-///   containing a unitless column-span;
-///   'of $n' for available grid columns [optional];
-///   'at $n', 'first', or 'last' for location on asymmetrical grids;
-///   and 'narrow', 'wide', or 'wider' for
-///   optionally spreading over adjacent gutters
-///   with either the `span` or `columns` value
+///   Shorthand expression to define the width of the span,
+///   optionally containing:
+///   - a count, length, or column-list span;
+///   - `at $n`, `first`, or `last` location on asymmetrical grids;
+///   - `narrow`, `wide`, or `wider` for optionally spreading
+///     across adjacent gutters;
+///   - `of $n <spread>` for available grid columns
+///     and spread of the container;
+///   - and `set-gutters $n` to override global gutter settings
+/// @param {Bool} $context-only -
+///   Allow the parser to ignore span and span-spread values,
+///   only parsing context and container-spread
 ///
 /// @return {Map} -
 ///   Map of span settings
-///   (`span`, `location`, `columns`, `spread`, `container-spread`)
+///   (`span`, `location`, `columns`, `gutters`, `spread`, `container-spread`)
 ///   parsed from shorthand input
 @function susy-parse(
   $shorthand
 ) {
-  $span-error: 'Not able to determine column-span from `#{$shorthand}`';
-  $parse-error: 'Unknown span property:';
+  $parse-error: 'Unknown shorthand property:';
   $options: (
     'first': 'location',
     'last': 'location',
@@ -46,80 +51,106 @@
   $span: null;
   $columns: null;
 
-  $of: false;
+  $of: null;
   $next: false;
 
+  // loop through the shorthand list
   @for $i from 1 through length($shorthand) {
     $item: nth($shorthand, $i);
     $type: type-of($item);
+    $details: '[#{$type}] `#{$item}`';
 
+    // if we know what's supposed to be coming next…
     @if $next {
+      // If it's supposed to be a column width…
       @if ($next == 'column-width') {
+        // if it looks like a column width…
         @if ($type == 'number') and (not unitless($item)) {
-          @if $columns {
+          // could be either span or context width…
+          @if $of {
             $columns: join($columns, ('x' $item));
           } @else {
             $span: join($span, ('x' $item));
           }
-        } @else {
-          @error '`#{item}` is not a valid column-width';
+
+        } @else { // Column-width error
+          @return _susy-error(
+            '`#{$item}` is not a valid column-width',
+            'susy-parse');
         }
-      } @else {
+
+      } @else { // For other values of next, we simply add to the return map
         $return: map-merge($return, ($next: $item));
       }
 
+      // Reset next to `false`
       $next: false;
-    } @else {
+
+    } @else { // If we don't know what's supposed to be coming…
+      // Keywords…
       @if ($type == 'string') {
+        // Check the map for keywords…
         @if map-has-key($options, $item) {
           $setting: map-get($options, $item);
 
-          @if ($setting == 'spread') and $of {
+          // Spread could be on the span or the container…
+          @if ($setting == 'spread') and ($of) {
             $return: map-merge($return, ('container-spread': $item));
           } @else {
             $return: map-merge($return, ($setting: $item));
           }
-        } @else if $item == 'all' {
+
+        } @else if ($item == 'all') { // `All` is a span shortcut
           $span: 'all';
-        } @else if not $span {
-          @error $span-error;
-        } @else if ($item == 'at') {
+
+        } @else if ($item == 'at') { // Some keywords setup what's next…
           $next: 'location';
         } @else if ($item == 'x') {
           $next: 'column-width';
+        } @else if ($item == 'set-gutters') {
+          $next: 'gutters';
         } @else if ($item == 'of') {
           $of: true;
-        } @else {
-          @error '#{$parse-error} `#{$item}`';
+
+        } @else { // Error if we're out of ideas
+          @return _susy-error('#{$parse-error} #{$details}', 'susy-parse');
         }
-      } @else if ($type == 'number') or ($type == 'list') {
-        @if not $span {
+
+      } @else if ($type == 'number') or ($type == 'list') { // Numbers & lists…
+
+        // We don't have a span, and we're not expecting context…
+        @if not ($span or $of) {
           $span: $item;
-        } @else if $of {
+
+        } @else if ($of) and (not $columns) { // We are expecting context…
           $columns: $item;
-        } @else {
-          @error '#{$parse-error} `#{$item}`';
+
+        } @else { // Error if we don't understand…
+          @return _susy-error('#{$parse-error} #{$details}', 'susy-parse');
         }
-      } @else {
-        @error '#{$parse-error} `#{$item}`';
+
+      } @else { // Error if we don't know this type…
+        @return _susy-error('#{$parse-error} #{$details}', 'susy-parse');
       }
     }
   }
 
+  // If we have span, merge it in
   @if $span {
     $return: map-merge($return, ('span': $span));
-  } @else {
-    @error $span-error;
   }
 
+  // If we have columns, merge them in
   @if $columns {
     $return: map-merge($return, ('columns': $columns));
   }
 
+  // Return the map of settings…
   @return $return;
 }
 
 
+
 // Susy Normalize
 // --------------
 /// Normalize the values in a configuration map
@@ -139,6 +170,7 @@
 
     @if $value {
       $function: if(($setting == 'container-spread'), 'spread', $setting);
+      $function: _susy-get-function($function);
       $value: call('susy-normalize-#{$function}', $value);
     }
 
@@ -163,6 +195,7 @@
 }
 
 
+
 // Normalize Columns
 // -----------------
 /// Normalize `columns` shorthand for Su
@@ -199,6 +232,7 @@
 }
 
 
+
 // Normalize Span
 // --------------
 /// Normalize `span` shorthand for Su
@@ -226,6 +260,7 @@
 }
 
 
+
 // Normalize Spread
 // ----------------
 /// Normalize `spread` shorthand for Su
@@ -251,6 +286,7 @@
 }
 
 
+
 // Normalize Location
 // ------------------
 /// Normalize `location` shorthand for Su

data/sass/susy/_settings.scss

@@ -6,6 +6,7 @@
 // - susy-get [function]
 
 
+
 // Susy
 // ----
 /// Custom user configuration map for Susy
@@ -40,6 +41,7 @@
 $susy: () !default;
 
 
+
 // Susy Defaults
 // -------------
 /// Configuration map of Susy factory defaults
@@ -95,6 +97,7 @@ $susy-defaults: (
 }
 
 
+
 // Susy Get
 // --------
 /// Return the current value of any Susy setting
@@ -113,7 +116,9 @@ $susy-defaults: (
   $settings: susy-settings();
 
   @if not map-has-key($settings, $key) {
-    @error 'There is no Susy setting called `#{$key}`';
+    @return _susy-error(
+      'There is no Susy setting called `#{$key}`',
+      'susy-get');
   }
 
   @return map-get($settings, $key);

data/sass/susy/_utilities.scss

@@ -0,0 +1,60 @@
+// Sass Utilities
+// ==============
+// - Susy Get Function [function]
+// - Susy Error Output Override [variable]
+// - Susy Error [function]
+
+
+
+// Susy Get Function
+// -----------------
+/// Get a first-class function in Sass 3.5+,
+/// or the function name string (unchanged)
+/// in older Sass versions.
+///
+/// @access private
+///
+/// @param {String} $function -
+///   The name (string) of a function to be called.
+/// @return {String | Function} -
+///   Returns a first-class function in Sass 3.5+,
+///   or the function name string in older Sass versions.
+@function _susy-get-function(
+  $function
+) {
+  $type: type-of($function);
+
+  @if ($type != 'string') {
+    @return _susy-error(
+      'Invalid function-name [#{$type}] `#{$function}`, name must be a string.',
+      '_susy-get-function');
+  }
+
+  @if function-exists('get-function') {
+    @return get-function($function);
+  }
+
+  @return $function;
+}
+
+
+
+// Susy Error Output Override
+// --------------------------
+$_susy-error-output-override: false !default;
+
+
+
+// Susy Error
+// ----------
+@function _susy-error(
+  $message,
+  $source,
+  $override: $_susy-error-output-override
+) {
+  @if $override {
+    @return 'ERROR [#{$source}] #{$message}';
+  }
+
+  @error '[#{$source}] #{$message}';
+}

data/sass/susy/_validation.scss

@@ -6,6 +6,37 @@
 // - su-valid-location [function]
 
 
+
+// Valid Span
+// ----------
+/// Check that the `span` argument
+/// is a number, length, or column-list
+///
+/// @access private
+///
+/// @param {Number | List} $span -
+///   Number of columns, or length of span
+///
+/// @return {Number | List} -
+///   Validated `$span` number, length, or columns list
+@function su-valid-span(
+  $span
+) {
+  $type: type-of($span);
+  @if ($type == 'number') {
+    @return $span;
+  } @else if ($type == 'list') and su-valid-columns($span, 'silent-failure') {
+    @return $span;
+  }
+
+  $actual: '[#{type-of($span)}] `#{inspect($span)}`';
+  @return _susy-error(
+    '#{$actual} is not a valid number, length, or column-list for $span.',
+    'su-valid-span');
+}
+
+
+
 // Valid Columns
 // -------------
 /// Check that the `columns` argument is a valid
@@ -15,25 +46,36 @@
 ///
 /// @param {List} $columns -
 ///   List of column-lengths using comparable units
+/// @param {Bool} $silent-failure [true] -
+///   Set false to return null on failure
 ///
 /// @return {List} -
 ///   Validated `$columns` list
 @function su-valid-columns(
-  $columns
+  $columns,
+  $silent-failure: false
 ) {
   $first: nth($columns, 1);
 
   @each $col in $columns {
-    @if (type-of($col) != 'number') or (not comparable($col, $first)) {
+    @if (type-of($col) != 'number') or (not comparable($col, $first)) or (unitless($col) and not unitless($first)) or (unitless($first) and not unitless($col)) {
+      @if $silent-failure {
+        @return null;
+      }
+
       $actual: '[#{type-of($columns)}] `#{inspect($columns)}`';
-      @error '#{$actual} is not a value for $columns.';
+      @return _susy-error(
+        '#{$actual} is not a valid list of comparable lengths for $columns.',
+        'su-valid-columns');
     }
+
   }
 
   @return $columns;
 }
 
 
+
 // Valid Gutters
 // -------------
 /// Check that the `gutters` argument is a valid number
@@ -54,18 +96,31 @@
   $type: type-of($gutters);
 
   @if ($type == 'number') {
-    @if unitless($gutters) and (not unitless(nth($columns, 1))) {
-      @error 'Gutters must have units for a static grid.';
+    $first: nth($columns, 1);
+
+    @if (unitless($gutters) and not unitless($first)) {
+      @return _susy-error(
+        'Gutters must have units for a static grid.',
+        'su-valid-gutters');
+    }
+
+    @if (not comparable($gutters, $first)) {
+      @return _susy-error(
+        'Gutter and column units must be comparable.',
+        'su-valid-gutters');
     }
 
     @return $gutters;
   }
 
   $actual: '[#{$type}] `#{inspect($gutters)}`';
-  @error '#{$actual} is not a value for $gutters.';
+  @return _susy-error(
+    '#{$actual} is not a value for $gutters.',
+    'su-valid-gutters');
 }
 
 
+
 // Valid Spread
 // ------------
 /// Check that the `spread` argument is a valid
@@ -87,10 +142,13 @@
   }
 
   $actual: '[#{type-of($spread)}] `#{inspect($spread)}`';
-  @error '#{$actual} is not a value for $spread.';
+  @return _susy-error(
+    '#{$actual} is not a normalized [0 | 1 | -1] value for `$spread`.',
+    'su-valid-spread');
 }
 
 
+
 // Valid Location
 // --------------
 /// Check that the `location` argument is a valid number,
@@ -117,14 +175,22 @@
   @if $location {
     @if (type-of($location) != 'number') or (not unitless($location)) {
       $actual: '[#{type-of($location)}] `#{$location}`';
-      @error '#{$actual} is not a value for $location.';
+      @return _susy-error(
+        '#{$actual} is not a unitless number for $location.',
+        'su-valid-location');
     } @else if (round($location) != $location) {
-      @error 'Location (`#{$location}`) must be a 1-indexed intiger position.';
-    } @else if ($location > $count) {
-      @error 'Position `#{$location}` does not exist in grid `#{$columns}`.';
+      @return _susy-error(
+        'Location (`#{$location}`) must be a 1-indexed intiger position.',
+        'su-valid-location');
+    } @else if ($location > $count) or ($location < 1) {
+      @return _susy-error(
+        'Position `#{$location}` does not exist in grid `#{$columns}`.',
+        'su-valid-location');
     } @else if ($location + $span - 1 > $count) {
       $details: 'grid `#{$columns}` for span `#{$span}` at `#{$location}`';
-      @error 'There are not enough columns in #{$details}';
+      @return _susy-error(
+        'There are not enough columns in #{$details}.',
+        'su-valid-location');
     }
   }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: susy
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha.1
+  version: 3.0.0.alpha.2
 platform: ruby
 authors:
 - Miriam Eric Suzanne
@@ -46,11 +46,19 @@ files:
 - lib/susy.rb
 - sass/_prefix.scss
 - sass/_susy.scss
+- sass/plugins/_svg-grid.scss
+- sass/plugins/svg-grid/_prefix.scss
+- sass/plugins/svg-grid/_svg-api.scss
+- sass/plugins/svg-grid/_svg-grid-math.scss
+- sass/plugins/svg-grid/_svg-settings.scss
+- sass/plugins/svg-grid/_svg-unprefix.scss
+- sass/plugins/svg-grid/_svg-utilities.scss
 - sass/susy/_api.scss
 - sass/susy/_grids.scss
 - sass/susy/_parser.scss
 - sass/susy/_settings.scss
 - sass/susy/_unprefix.scss
+- sass/susy/_utilities.scss
 - sass/susy/_validation.scss
 - CHANGELOG.md
 - LICENSE.txt
@@ -77,9 +85,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '1.2'
 requirements: []
 rubyforge_project: susy
 rubygems_version: 2.1.10