susy 3.0.0.alpha.5 → 3.0.0.alpha.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0ad2ba7ba1ffa176bd5e088bb88302f82271e300
-  data.tar.gz: 6dcab4d0500c60ce0190bf8e62493a0821aeaf16
+  metadata.gz: 519e857203e1b3d776c16243765fd668de840a69
+  data.tar.gz: 51c147b2f1ff268e307bee275c6ad3922ecfc753
 SHA512:
-  metadata.gz: 0411d5aabf76072b480b7417688091aed3db372eb179f8000dda8ca9ce5f7d7dc6bfb43286418eeb6c0231e656fe5d254f435cd9b176e3c52074a1d280848cb2
-  data.tar.gz: dfc62728c21d37227ceb3311a0802618863f23f1c2a7e709ed34968f3f8d4d05c436bd6b9899b328fd3e2adde718b56ceb8c2066c4803cfd149433ea38d29e97
+  metadata.gz: b2d21d7284ebe3e8ca7aa3539fec194ecbfc63f5b88fc2ec6e1db47adea2f3f4fa9bd9be3e654402272a2344ba6b1da31e50d3ddb12f37fc2586da6b00c82b18
+  data.tar.gz: b6742401269cd54803d6544a1ad5371502204958620aa9111633a49751aaf16294d372880be52f7b41e0105d6e6ca583eb425ca1e02308b293fe24ecf945217f

data/CHANGELOG.md

@@ -1,6 +1,56 @@
 Changelog
 =========
 
+3.0.0.rc.1 - UNRELEASED
+-----------------------
+
+- Add `susy-repeat()` function
+  to generate repeating gradients with the same syntax
+  provided in CSS Grid templates
+- Add `susy-compile()` and `susy-call()` plugin helpers,
+  to aide with conversions between the user API and
+  internal math functions.
+
+
+3.0.0.alpha.5 - Feb 14, 2017
+----------------------------
+
+- SVG Grid plugin, to provide grid-debugging options:
+  - `svg-grid-colors` global setting accepts one or more colors
+  - `susy-svg-grid()` function returns inline svg
+    for use in the `background` or generated `content` properties
+- Add `set-gutters $n` shorthand to override global gutter settings
+- Allow gutters function to take either context-only,
+  or full span/context shorthand —
+  useful when passing in details from a combined mixin
+- More test coverage, including error-handling!
+
+
+3.0.0.alpha.1 - Sep 6, 2016
+---------------------------
+
+- No Mixins!
+- Trim down to the core math, and a thin layer of api functions:
+  - `susy-span()` to return a column-spanning width
+  - `susy-gutter()` to return a gutter width
+  - `susy-slice()` to return a slice of asymmetrical grid
+- Simplify to four settings:
+  - `columns` to define the grid columns
+    as a list of comparable or unitless relative numbers
+  - `gutters` to define the size of a gutter
+    in units comparable to the columns,
+    or a unitless relative number
+  - `spread` to define the default spread of a span
+    across adjacent gutters
+  - `container-spread` to define the default spread of a container
+    across side-edge gutters
+- Shorthand syntax for overriding settings on-the-fly:
+  - starting with a count, length, or column-list span
+  - `at $n`, `first`, or `last` location on asymmetrical grids
+  - `narrow`, `wide`, or `wider` for spread
+  - `of $n <spread>` for available grid columns and container-spread
+
+
 2.2.5 - May 14 2015
 -------------------
 

data/README.md

@@ -16,14 +16,6 @@ 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
 ---------------
@@ -36,13 +28,17 @@ npm install susy@pre
 ```
 
 There are two imports to choose from.
-The default `sass/_susy.scss` comes with
+The default `sass/susy` comes with
 un-prefixed versions of the core API functions.
 If you want Susy to be name-spaced,
-import `sass/_prefix.scss` instead.
+import `sass/prefix` instead.
 
 ```scss
-@import '../node_modules/susy/sass/susy';
+// un-prefixed api functions
+@import '<path-to>/susy/sass/susy';
+
+// fully-prefixed functions
+@import '<path-to>/susy/sass/prefix';
 ```
 
 
@@ -83,6 +79,8 @@ 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)`.
+To define new gutter-values in the shorthand syntax,
+use `set-gutters $n`.
 
 You can use these two functions
 to build all sorts of grids:
@@ -99,6 +97,7 @@ to build all sorts of grids:
   padding: gutter() / 2;
 }
 
+
 // Make your own class system!
 .span {
   float: left;
@@ -138,7 +137,7 @@ $static: (5em 5em 5em 5em 5em 5em);
 // six unequal fluid columns
 $asymmetrical: (1 1 2 3 5 8);
 
-// six unequal fluid columns
+// six unequal static columns
 // you can mix units, as long as they are comparable...
 $strange: (1in 1cm 2pt 3mm 5in 8cm);
 ```
@@ -156,6 +155,22 @@ $fluid: 6;
 $static: 6 x 120px;
 ```
 
+We also provide a function
+that mimics CSS Grids `repeat()`
+to generate repetative grid definitions:
+
+```scss
+// six equal fluid columns
+$fluid: susy-repeat(6);
+
+// six 120px static columns
+$static: susy-repeat(6, 120px);
+
+// 12 columns, alternating 4em and 6em
+$static: susy-repeat(6, 4em 6em);
+```
+
+
 **Gutters**
 are defined relative to columns,
 in comparable units.
@@ -183,14 +198,56 @@ will be treated as a global default
 across your project.
 
 
+Debugging Plugin: SVG Grid Image
+--------------------------------
+
+If you want to generate svg-backgrounds
+for help visualizing and debugging your grids,
+import the SVG Grid Plugin:
+
+```
+// unprefixed
+@import '<path-to>/susy/sass/plugins/svg-grid';
+
+// prefixed
+@import '<path-to>/susy/sass/plugins/svg-grid/prefix';
+```
+
+The plugin adds `svg-grid-colors` setting
+to your global defaults,
+which you can override in `$susy`.
+It also provides you with a new function,
+`susy-svg-grids()`,
+which will return inline svg for use in
+backgrounds or generated content:
+
+```scss
+// usage
+background: susy-svg-grids() no-repeat scroll;
+
+// output sample
+background: url('data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg"
+                 fill="%239cc" %3E%3Crect x="1em" width="44.44444%"
+                 height="100%" /%3E%3Crect x="55.55556%" width="44.44444%"
+                 height="100%" style="transform:translateX(1em)"
+                 /%3E%3C/svg%3E') no-repeat scroll;
+```
+
+
 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.
+you can dig into some of the more advanced features:
+
+- Use the `spread` and `container-spread` options
+  to include extra gutters in a span, or it's container.
+- Use the `susy-slice()` function
+  to handle nesting-context with asymmetrical grids.
+- Use `susy-compile()` and `susy-call`
+  to quickly access the full power of our
+  syntax-parsing and math engines,
+  while building plugins of your own.
 
 Happy grid-building!
 

data/VERSION

@@ -1 +1 @@
-3.0.0.alpha.5
+3.0.0.alpha.6

data/sass/_prefix.scss

@@ -8,4 +8,5 @@ $susy-version: 3;
 @import 'susy/settings';
 @import 'susy/validation';
 @import 'susy/parser';
+@import 'susy/plugin-helpers';
 @import 'susy/api';

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

@@ -28,20 +28,7 @@
   $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);
+  $grid: susy-compile($grid, $context-only: true);
 
 
   // Color and gradient handling

data/sass/susy/_api.scss

@@ -47,21 +47,10 @@
   $span,
   $config: ()
 ) {
-  $input: susy-settings($config, susy-parse($span));
-  $normal: susy-normalize($input);
+  $output: susy-compile($span, $config);
 
-  @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...);
+  @if map-get($output, 'span') {
+    @return susy-call('su-span', $output);
   }
 
   $actual: '[#{type-of($span)}] `#{inspect($span)}`';
@@ -100,25 +89,9 @@
   $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');
+  $context: susy-compile($context, $config, 'context-only');
 
-  @each $key in map-keys($normal) {
-    @if not (index($args, $key)) {
-      $normal: map-remove($normal, $key);
-    }
-  }
-
-  @return su-gutter($normal...);
+  @return susy-call('su-gutter', $context);
 }
 
 
@@ -152,14 +125,7 @@
   $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)));
-  }
+  $span: susy-compile($span, $config);
 
-  @return su-slice($output...);
+  @return susy-call('su-slice', $span);
 }

data/sass/susy/_parser.scss

@@ -25,7 +25,7 @@
 ///   - `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 -
+/// @param {Bool} $context-only [false] -
 ///   Allow the parser to ignore span and span-spread values,
 ///   only parsing context and container-spread
 ///
@@ -34,7 +34,8 @@
 ///   (`span`, `location`, `columns`, `gutters`, `spread`, `container-spread`)
 ///   parsed from shorthand input
 @function susy-parse(
-  $shorthand
+  $shorthand,
+  $context-only: false
 ) {
   $parse-error: 'Unknown shorthand property:';
   $options: (
@@ -54,6 +55,15 @@
   $of: null;
   $next: false;
 
+  // Allow context-only shorthand, without span
+  @if ($context-only) and (not index($shorthand, 'of')) {
+    @if su-valid-columns($shorthand, 'fail-silent') {
+      $shorthand: 'of' $shorthand;
+    } @else {
+      $shorthand: join('of', $shorthand);
+    }
+  }
+
   // loop through the shorthand list
   @for $i from 1 through length($shorthand) {
     $item: nth($shorthand, $i);
@@ -170,8 +180,13 @@
 
     @if $value {
       $function: if(($setting == 'container-spread'), 'spread', $setting);
-      $function: _susy-get-function($function);
-      $value: call('susy-normalize-#{$function}', $value);
+      $function: 'susy-normalize-#{$function}';
+
+      @if function-exists('get-function') {
+        $function: get-function($function);
+      }
+
+      $value: call($function, $value);
     }
 
     $config: map-merge($config, ($setting: $value));
@@ -196,6 +211,37 @@
 
 
 
+// Repeat
+// ------
+/// Similar to the `repeat(<count>, <value>)` function
+/// that is available in CSS Grid templates,
+/// repeats any value a given number of times —
+/// a useful shortcut for defining symetrical static grids
+///
+/// @group a-config
+///
+/// @param {Integer} $count -
+///   The number of repetitions
+/// @param {Any} $value -
+///   Any value can be repeated
+///
+/// @return {List} -
+///   List of repeated values
+@function susy-repeat(
+  $count,
+  $value: 1
+) {
+  $return: ();
+
+  @for $i from 1 through $count {
+    $return: join($return, $value);
+  }
+
+  @return $return;
+}
+
+
+
 // Normalize Columns
 // -----------------
 /// Normalize `columns` shorthand for Su
@@ -213,19 +259,11 @@
   $return: ();
 
   @if (type-of($columns) == 'number') and unitless($columns) {
-    @for $i from 1 through $columns {
-      $return: append($return, 1);
-    }
-
-    @return $return;
+    @return susy-repeat($columns);
   } @else if index($columns, 'x') and length($columns) == 3 {
+    $count: nth($columns, 1);
     $width: nth($columns, -1);
-
-    @for $i from 1 through nth($columns, 1) {
-      $return: append($return, $width);
-    }
-
-    @return $return;
+    @return susy-repeat($count, $width);
   }
 
   @return $columns;

data/sass/susy/_plugin-helpers.scss

@@ -0,0 +1,99 @@
+// Plugin Helpers
+// ==============
+// - susy-compile [function]
+// - susy-call [function]
+
+
+
+// Compile
+// -------
+/// Combines parsed shorthand
+/// with local and global config,
+/// normalizing the results
+/// into a standard Susy settings map.
+///
+/// @group plugin-helpers
+///
+/// @param {List | Map} $shorthand -
+///   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
+/// @param {Bool} $context-only [false] -
+///   Allow the parser to ignore span and span-spread values,
+///   only parsing context and container-spread
+///
+/// @return {Map} -
+///   Parsed and normalized map of settings,
+///   based on global and local configuration,
+///   alongwith shorthad adjustments.
+///
+/// @example scss -
+///   $grid-data: susy-compile($user-input, $config);
+///   width: susy-call('su-span', $grid-data);
+@function susy-compile(
+  $short,
+  $config: (),
+  $context-only: false
+) {
+  @if (type-of($short) != 'map') and (length($short) > 0) {
+    $short: susy-parse($short, $context-only);
+  }
+
+  $merge: susy-settings($config, $short);
+  $normal: susy-normalize($merge);
+
+  @return $normal;
+}
+
+
+
+// Call
+// ----
+/// Calls a given grid function
+/// using the approapriate arguments
+/// from the passed-in config.
+///
+/// @group plugin-helpers
+///
+/// @param {String} $name -
+///   Name of the `su-` function to call
+/// @param {Map} $config -
+///   Map of Susy configuration settings to use as needed for arguments
+///
+/// @return {Any} -
+///   Results of the called function
+///
+/// @example scss -
+///   $grid-data: susy-compile($user-input, $config);
+///   width: susy-call('su-span', $grid-data);
+@function susy-call(
+  $name,
+  $config
+) {
+  $grid-function-args: (
+    'su-span': ('span', 'columns', 'gutters', 'spread', 'container-spread', 'location' ),
+    'su-gutter': ('columns', 'gutters', 'container-spread'),
+    'su-slice': ('span', 'columns', 'location'),
+    'su-sum': ('columns', 'gutters', 'spread'),
+  );
+
+  $args: map-get($grid-function-args, $name);
+  $call: if(function-exists('get-function'), get-function($name), $name);
+  $output: ();
+
+  @each $arg in $args {
+    $value: map-get($config, $arg);
+    $output: if($value, map-merge($output, ($arg: $value)), $output);
+  }
+
+  @return call($call, $output...);
+}

data/sass/susy/_unprefix.scss

@@ -5,8 +5,9 @@
 // Span
 // ----
 /// Un-prefixed alias for `susy-span`
+/// (available by default)
 ///
-/// @group unprefix
+/// @group api
 /// @alias susy-span
 ///
 /// @param {List} $span
@@ -22,25 +23,27 @@
 // Gutter
 // ------
 /// Un-prefixed alias for `susy-gutter`
+/// (available by default)
 ///
-/// @group unprefix
+/// @group api
 /// @alias susy-gutter
 ///
-/// @param {Integer | List} $nested [null] -
+/// @param {Integer | List} $context [null] -
 /// @param {Map} $config [()]
 @function gutter(
-  $nested: null,
+  $context: susy-get('columns'),
   $config: ()
 ) {
-  @return susy-gutter($nested, $config);
+  @return susy-gutter($context, $config);
 }
 
 
 // Slice
 // -----
 /// Un-prefixed alias for `susy-slice`
+/// (available by default)
 ///
-/// @group unprefix
+/// @group api
 /// @alias susy-slice
 ///
 /// @param {List} $span

data/sass/susy/_utilities.scss

@@ -1,44 +1,10 @@
 // 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;

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: susy
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha.5
+  version: 3.0.0.alpha.6
 platform: ruby
 authors:
 - Miriam Eric Suzanne
@@ -14,20 +14,20 @@ dependencies:
   name: sass
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.3.0
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '3.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.3.0
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '3.5'
 description: Susy is a toolkit for building layouts of all types with a simple, natural
@@ -42,6 +42,10 @@ extra_rdoc_files:
 - README.md
 - lib/susy.rb
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- VERSION
 - lib/compass-susy.rb
 - lib/susy.rb
 - sass/_prefix.scss
@@ -56,41 +60,38 @@ files:
 - sass/susy/_api.scss
 - sass/susy/_grids.scss
 - sass/susy/_parser.scss
+- sass/susy/_plugin-helpers.scss
 - sass/susy/_settings.scss
 - sass/susy/_unprefix.scss
 - sass/susy/_utilities.scss
 - sass/susy/_validation.scss
-- CHANGELOG.md
-- LICENSE.txt
-- README.md
-- VERSION
 homepage: http://susy.oddbird.net/
 licenses:
 - BSD-3-Clause
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --line-numbers
-- --inline-source
-- --title
+- "--line-numbers"
+- "--inline-source"
+- "--title"
 - Susy
-- --main
+- "--main"
 - README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '1.2'
 requirements: []
 rubyforge_project: susy
-rubygems_version: 2.1.10
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 3
 summary: Responsive layout toolkit for Sass.