susy 2.2.14 → 3.0.0.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2def2e5a8a611e82f515fff1e2d8fddb967aabe5
-  data.tar.gz: d148a7596ae43cbe245b0f617e09876b1364461f
+  metadata.gz: fa2aa38b4ee8f4a92e3d6cecb470ebcdde3dbb29
+  data.tar.gz: 74d57ae39653cb41f6d13d667b9205f0163eef35
 SHA512:
-  metadata.gz: dc4feae38f46b441dc5939897d90500a57692a70e220ec09f5a5b469610adb12c0bef9c9bcfa5d1e943dd914b56fad5a87a25d9e6f977c8335b97edbf8e74c12
-  data.tar.gz: 4e9db7e2baf10a970bdb8b35b76bb6357979b2d1b92ab5e99b06dc172434a18e1468692d578f52bca70eadd858eff24ac2d7f7f13d39afea70fcab9ae1caf59e
+  metadata.gz: 2b2b113cad8db26b6f4b10a73893f15339dfcddb4a2f35bfb36774faa85f46a294ee0667d271d75c56fdff104d085b6f98e352c8a5b3e4a46e3ae7e841741a97
+  data.tar.gz: eb5cb812bcc15d7fbf1eb51d3d0246f2ab583e5ed32a155f4fb32b301f216afdf288875b7981c60538dec5806e3fd06a26cd0106e76249853999ccfbd3c99709

data/{docs/changelog.rst → CHANGELOG.md}

@@ -1,40 +1,6 @@
 Changelog
 =========
 
-2.2.13 - Apr 10 2018
---------------------
-
-- Support Sass 3.5+ `get-function` requirements.
-- Doc updates & typo fixes.
-
-
-2.2.12 - Jan 25 2016
---------------------
-
-- Fix bug in validation-errors.
-
-
-2.2.11 - Jan 15 2016
---------------------
-
-- Fix bug with `susy-inspect`.
-
-
-2.2.10 - Jan 7 2016
--------------------
-
-- Add `$pixel-values-only` setting to SusyOne,
-  for turning off Compass `rem` support.
-
-
-2.2.6 - Sep 1 2015
-------------------
-
-- Fix a bug with overlay grids.
-- Fix a bug with 0-width split gutters.
-- Other small bug fixes.
-
-
 2.2.5 - May 14 2015
 -------------------
 

data/README.md

@@ -1,21 +1,146 @@
 Power Tools For The Web
 =======================
 
-[![Build Status](https://travis-ci.org/oddbird/susy.png?branch=susy-next)](https://travis-ci.org/oddbird/susy)
+[![Build Status](https://travis-ci.org/oddbird/susy.png?branch=threeish)](https://travis-ci.org/oddbird/susy)
 
 Susy is an agnostic set of tools
 for creating powerful, custom layouts.
-We provide the language,
-but you provide all the opinions.
-Use a grid, don't use a grid,
-or use a combination of grids —
-it's all up to you.
+We didn't want another grid system
+full of rules and restrictions —
+we wanted a power tool
+for building our own damn systems.
 
-We didn't want to build another system,
-we wanted to build power tools
-that you could use in any system.
+Do It Yourself.
+Your Markup,
+Your Layout —
+*Our Math*
+
+
+Getting Started
+---------------
+
+Susy v3 is trimmed down to it's most basic components —
+functions that can be used to build any grid system.
+
+There are four global settings to understand,
+and two of them are identical:
+
+
+### Columns
+
+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);
+
+// six fibonacci columns
+$asymmetrical: (1 1 2 3 5 8);
+```
+
+If you want static grids,
+you can add units to the numbers —
+as long as all the units are comparable.
+
+```scss
+// five equal static columns
+$symmetrical: (120px 120px 120px 120px 120px);
+
+// six not-fibonacci static columns
+$asymmetrical: (1in 1cm 2pt 3mm 5in 8cm);
+```
+
+That can get repetative
+when you are working with symmetrical grids,
+so we've provided a symmetrical shorthand.
+
+```scss
+// five equal fluid columns (shorthand)
+$fluid: 5;
+
+// five equal static columns (shorthand)
+$static: 5 x 120px;
+```
+
+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.
+
+
+### Gutters
+
+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.
+
+```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;
+```
+
+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.
 
-Your markup, your layout | *our math*
 
 Resources
 ---------

data/VERSION

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

data/sass/_prefix.scss

@@ -0,0 +1,10 @@
+// Susy (Prefixed)
+// ===============
+
+$susy-version: 3;
+
+@import 'susy/grids';
+@import 'susy/settings';
+@import 'susy/validation';
+@import 'susy/parser';
+@import 'susy/api';

data/sass/_susy.scss

@@ -1,4 +1,5 @@
-// Susy
-// ====
+// Susy (Un-Prefixed)
+// ==================
 
-@import 'susy/language/susy';
+@import 'prefix';
+@import 'susy/unprefix';

data/sass/susy/_api.scss

@@ -0,0 +1,134 @@
+// Grids
+// =====
+// - susy-span [function]
+// - susy-gutter [function]
+// - susy-slice [function]
+
+
+// Susy Span
+// ---------
+/// This is the primary function in Susy —
+/// used to return the width of any grid-span —
+/// such as the `width` property of grid elements,
+/// or `margin` and `padding`
+/// to push, pull, and pad your elements
+/// (un-prefixed alias `span()` is available
+/// unless you import `susy/prefix` explicitly)
+///
+/// @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
+/// @param {Map} $config [()] -
+///   Optional map of Susy grid configuration settings
+///
+/// @return {Length} -
+///   Fluid `%` length when no `column-width` is given,
+///   or a static length in the same units as `column-width`
+///
+/// @example scss - Span half the grid
+///   .foo
+///     width: susy-span(6 of 12);
+///   }
+///
+/// @example scss - Span a specific segment of asymmetrical grid
+///   .foo {
+///     width: susy-span(3 at 3 of (1 2 3 5 8));
+///   }
+@function susy-span(
+  $span,
+  $config: ()
+) {
+  $input: susy-settings($config, susy-parse($span));
+  $normal: susy-normalize($input);
+
+  @return su-span($normal...);
+}
+
+
+// Susy Gutter
+// -----------
+/// Return the width of a single gutter
+/// in your current grid context
+/// (un-prefixed alias `gutter()` is available
+/// unless you import `susy/prefix` explicitly)
+///
+/// @group api
+///
+/// @param {Number | List} $context [null] -
+///   Optional columns in a nested context
+/// @param {Map} $config [()] -
+///   Optional map of Susy grid configuration settings
+///
+/// @return {Length} -
+///   Width of a gutter as `%` of current context,
+///   or in the units defined by `column-width` when available
+///
+/// @example scss - Add gutters before or after an element
+///   .foo {
+///     margin-left: gutter();
+///   }
+@function susy-gutter(
+  $context: susy-get('columns'),
+  $config: ()
+) {
+  $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)));
+  }
+
+  @return su-gutter($output...);
+}
+
+
+// Susy Slice
+// ----------
+/// Return a sub-slice of asymmetrical columns to use
+/// for a nested context
+/// (un-prefixed alias `slice()` is available
+/// unless you import `susy/prefix` explicitly)
+///
+/// @group api
+///
+/// @param {List} $span -
+///   Shorthand expression to define the subset span —
+///   containing a unitless column-count;
+///   '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
+///
+/// @param {Map} $config [()] -
+///   Optional map of Susy grid configuration settings
+///
+/// @return {List} -
+///   Subset list of columns for use for a nested context
+///
+/// @example scss - Return a nested segment of asymmetrical grid
+///   $context: susy-slice(3 at 3 of (1 2 3 5 8)); // returns `(3 5 8)`
+@function susy-slice(
+  $span,
+  $config: ()
+) {
+  $args: ('span', 'columns', 'location');
+  $input: susy-settings($config, susy-parse($span));
+  $normal: susy-normalize($input);
+  $output: ();
+
+  @each $setting in $args {
+    $output: map-merge($output, ($setting: map-get($normal, $setting)));
+  }
+
+  @return su-slice($output...);
+}

data/sass/susy/_grids.scss

@@ -0,0 +1,192 @@
+// Grids
+// =====
+// - su-span [function]
+// - su-gutter [function]
+// - su-sum [function]
+// - su-slice [function]
+
+
+// Su Span
+// -------
+/// Return a usable span width
+/// in either relative or static units
+///
+/// @group math
+///
+/// @param {Number | List} $span -
+///   Number or list of grid columns to span
+/// @param {List} $columns -
+///   List of columns available
+/// @param {Number} $gutters -
+///   Width of a gutter in column-comparable units
+/// @param {0 | 1 | -1} $spread -
+///   Number of gutters spanned,
+///   relative to `span` count
+/// @param {0 | 1 | -1} $container-spread [$spread] -
+///   Number of gutters spanned,
+///   relative to `columns` count
+/// @param {Integer} $location [1] -
+///   Optional position of sub-span among full set of columns
+///
+/// @return {Length} -
+///   Relative or static length of a span on the grid
+@function su-span(
+  $span,
+  $columns,
+  $gutters,
+  $spread,
+  $container-spread: $spread,
+  $location: 1
+) {
+  $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
+      @return $span;
+    }
+  }
+
+  $span-width: su-sum($span, $gutters, $spread, $validate: false);
+
+  @if unitless($span-width) {
+    $container-spread: su-valid-spread($container-spread);
+    $container: su-sum($columns, $gutters, $container-spread, $validate: false);
+    @return percentage($span-width / $container);
+  }
+
+  @return $span-width;
+}
+
+
+// Su Gutter
+// ---------
+/// Return a usable gutter length
+/// in either relative or static units
+///
+/// @group math
+///
+/// @param {List} $columns -
+///   List of columns in the grid
+/// @param {Number} $gutters -
+///   Width of a gutter in column-comparable units
+/// @param {0 | 1 | -1} $container-spread -
+///   Number of gutters spanned,
+///   relative to `columns` count
+///
+/// @return {Length} -
+///   Relative or static length of one gutter in a grid
+@function su-gutter(
+  $columns,
+  $gutters,
+  $container-spread
+) {
+  @if (type-of($gutters) == 'number') {
+    @if ($gutters == 0) or (not unitless($gutters)) {
+      @return $gutters;
+    }
+  }
+
+  $container: su-sum($columns, $gutters, $container-spread);
+  @return percentage($gutters / $container);
+}
+
+
+// Su Sum
+// ------
+/// Get the total sum of column-units in a layout.
+/// If static-gutter units aren't comparable to column-units,
+/// gutters will be removed from the resulting sum
+///
+/// @group math
+///
+/// @param {List} $columns -
+///   List of columns in the grid
+/// @param {Number} $gutters -
+///   Width of a gutter in column-comparable units
+/// @param {0 | 1 | -1} $spread -
+///   Number of gutters spanned,
+///   relative to `columns` count
+/// @param {Bool} $validate [true] -
+///   Check that arguments are valid before proceeding
+///
+/// @return {Number} -
+///   Total sum of column-units in a grid
+@function su-sum(
+  $columns,
+  $gutters,
+  $spread,
+  $validate: true
+) {
+  @if $validate {
+    $columns: su-valid-columns($columns);
+    $gutters: su-valid-gutters($gutters, $columns);
+    $spread: su-valid-spread($spread);
+  }
+
+  // Calculate column-sum
+  $column-sum: 0;
+  @each $column in $columns {
+    $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) {
+    @return $column-sum;
+  }
+
+  $gutter-sum: (ceil(length($columns)) + $spread) * $gutters;
+  @return $column-sum + $gutter-sum;
+}
+
+
+// Su Slice
+// --------
+/// Return a subset of columns at a given location
+///
+/// @group math
+///
+/// @param {Number} $span -
+///   Number of grid columns to span
+/// @param {List} $columns -
+///   List of columns in the grid
+/// @param {Number} $location [1] -
+///   Starting index of a span in the list of columns
+/// @param {Bool} $validate [true] -
+///   Check that arguments are valid before proceeding
+///
+/// @return {List} -
+///   Subset list of grid columns, based on span and location
+@function su-slice(
+  $span,
+  $columns,
+  $location: 1,
+  $validate: true
+) {
+  @if $validate {
+    $columns: su-valid-columns($columns);
+    $location: su-valid-location($span, $location, $columns);
+  }
+
+  $floor: floor($span);
+  $sub-columns: ();
+
+  @for $i from $location to ($location + $floor) {
+    $sub-columns: append($sub-columns, nth($columns, $i));
+  }
+
+  @if $floor != $span {
+    $remainder: $span - $floor;
+    $column: $location + $floor;
+    $sub-columns: append($sub-columns, nth($columns, $column) * $remainder);
+  }
+
+  @return $sub-columns;
+}