SassyIcons 0.0.10 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 10e92bd647200dba94cad0c3dff8cbc8b8294573
-  data.tar.gz: f4a6cf6ea8a8c1e7603545473d16671187896c96
+  metadata.gz: f03ecf0b13d130ed13c61cf91889548e9b1314ff
+  data.tar.gz: 215f06661d40027eded677a032749ca0d7f94722
 SHA512:
-  metadata.gz: 866eadb6b258f1dfafeffab20aac77c5844866b3c6090e8a4234e3f6b563b413e493b4a4b9c433d7b524fe7abaa6c686d616b53f1c0f2701f67fb797ff4263ad
-  data.tar.gz: 6acd1406ac4acc9336f1cd062d61ea82ff997986d7e943d8ebb3c63bc5371abb519d61b352c2c39e1dd2208dfbe566963829ce4ad2bb3afec5df72b59632e174
+  metadata.gz: 0cfbc5a56375f46a6bfadc086977cebd2b25f52163ed3c4404388e18d1f5cf8b28d337ca6d8cfd619541751b13cea9a4f268f0e62820afe9158d8d36951c832d
+  data.tar.gz: 19f972b41e25e952d1a721274e7a9102e9fc7a0dfbfe2521dc684e5ae50f83d3397dcc8cb1e931ccfc27f8669755e4e6d880e70ed0a1c0a57f99e8de8cd4369f

data/README.md

@@ -10,32 +10,17 @@ SVG first with PNG sprite fallback, or PNG first with hidpi sprite support.
 Also managing several "thematic" sprites a breeze.  
 
 
-*Best workflow used in conjunction with [grunt-svg2png](https://github.com/pascalduez/grunt-svg2png)*
+*Best workflow used in conjunction with [grunt-svg2png](https://github.com/pascalduez/grunt-svg2png).*
 
+*Online [preview](http://pascalduez.github.io/SassyIcons/test) (test folder).*  
+*Online [Documentation](http://pascalduez.github.io/SassyIcons/docs) (generated with SassDoc).*
 
 ## Mixins
 
 `sprite-map-create($name [, $spacing])`  
-`icon($name, $sprite [, $offset, $format])`  
-`icon-single($name, $sprite [, $format])`  
-`icon-generated($name, $sprite [, $pos, $centered, $format])`
-
-
-## Documentation
-
-**sprite-map-create($name)**  
-Create a new sprite map from folder.  
-
-**icon($name, $sprite [, $offset, $format])**  
-Main icon mixin.  
-
-**icon-single($name, $sprite [, $format])**  
-Embed a single icon as inline-image (no sprite).  
-Should be used sporadically.  
-
-**icon-generated($name, $sprite [, $pos, $centered, $format])**  
-Include the icon in a generated "pseudo-element". Default to :before.  
-Allows for easier positioning or centering.  
+`icon($map, $sprite [, $offset, $format])`  
+`icon-single($map, $sprite [, $format])`  
+`icon-generated($map, $sprite [, $pos, $centered, $format])`
 
 
 ## Configuration
@@ -44,13 +29,13 @@ Allows for easier positioning or centering.
 // Default settings.
 $icons-defaults: (
 
-  // Space around sprites in generated sprite map.
+  // Space around sprites in generated spritemap.
   // Useful with `$offset` parameter.
-  // This setting is global for all sprite-maps.
-  // Can be set per sprite-map with the `$spacing` parameter.
+  // This setting is global for all spritemaps.
+  // Can be set per spritemap with the `$spacing` parameter.
   spacing: 0,
 
-  // Main icons directory. sprite-map-create() allows to use sub dirs.
+  // Main icons directory. `sprite-map-create()`, base for sub dirs.
   dir: "icons",
 
   // Name of the png sub-folders.
@@ -65,7 +50,7 @@ $icons-defaults: (
   // Minimum resolution ratio used in the hidpi media query.
   hidpi-ratio: 1.3,
 
-  // Whether to embed icons as data URI in the icon-single() mixin.
+  // Whether to embed icons as data URI in the `icon-single()` mixin.
   single-embed: true,
 
   // Default file format unless overridden by parameter, svg | png.
@@ -82,7 +67,7 @@ Override default values in a new `$icons-settings` map.
 ## Requirements
 
 * Sass ~> 3.3.0
-* Compass ~> 1.0.0.alpha.19
+* Compass ~> 1.0.0.rc.1
 
 
 ## Install
@@ -107,33 +92,22 @@ bower install SassyIcons --save
 
 #### Compass extension
 
-1. `bundle install SassyIcons` or `gem install SassyIcons`
-2. Add `require 'SassyIcons'` to your `config.rb`
-3. Import it in your stylesheets with `@import 'SassyIcons'`
+Since SassyIcons is dependant on Compass, this is the recommended installation and usage.
 
+1. Add `gem 'SassyIcons', '~>0.1.0'` to your `Gemfile`
+2. `bundle install --path .` (manage your gems in project dir, not globally)
+3. Add `require 'SassyIcons'` to your `config.rb`
+4. Import it in your stylesheets with `@import 'SassyIcons'`
 
-## Usage
 
-*Provided that [path] = path to SassyIcons*
+## Usage
 
 #### Example usage with [Compass](http://compass-style.org/help/tutorials/command-line)
 ```css
 @import 'SassyIcons';
 ```
 ```
-bundle exec compass watch --import-path [path]/dist
-```
-
-#### Example config with [grunt-contrib-sass](https://github.com/gruntjs/grunt-contrib-sass)
-
-```js
-sass: {
-  options: {
-    bundleExec: true, // Optional usage of Bundler, but recommended.
-    compass: true,
-    loadPath: ['[path]/dist/_SassyIcons.scss']
-  }
-}
+bundle exec compass watch
 ```
 
 

data/lib/SassyIcons.rb

@@ -2,14 +2,3 @@ require 'compass'
 
 extension_path = File.expand_path(File.join(File.dirname(__FILE__), ".."))
 Compass::Frameworks.register('SassyIcons', :path => extension_path)
-
-#  Version is a number. If a version contains alphas, it will be created as a prerelease version
-#  Date is in the form of YYYY-MM-DD
-module SassyIcons
-  VERSION = "0.0.10"
-  DATE = "2014-06-09"
-end
-
-module Sass::Script::Functions
-
-end

data/stylesheets/_SassyIcons.scss

@@ -1,12 +1,12 @@
-// -------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 // SassyIcons - Flexible icons system.
-// -------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 // Repository: https://github.com/pascalduez/SassyIcons
-// -------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 // A bit of terminology:
 // sprite = a single image/icon
-// "sprite sheet" or "sprite map" == all sprites combined together
+// 'sprite-sheet' or 'sprite-map' == all sprites combined together
 
 //
 // Import configuration
@@ -18,7 +18,6 @@
 //
 @import "helpers/helpers";
 
-
 //
 // Import icons
 //

data/stylesheets/config/_config.scss

@@ -1,19 +1,22 @@
-//
-// SassyIcons
-//
 
-// Configuration
+// SassyIcons: configuration
+// -------------------------
 
-// Default settings.
+
+/**
+ * Default settings.
+ * ---
+ * @type Map
+ */
 $icons-defaults: (
 
-  // Space around sprites in generated sprite map.
+  // Space around sprites in generated spritemap.
   // Useful with `$offset` parameter.
-  // This setting is global for all sprite-maps.
-  // Can be set per sprite-map with the `$spacing` parameter.
+  // This setting is global for all spritemaps.
+  // Can be set per spritemap with the `$spacing` parameter.
   spacing: 0,
 
-  // Main icons directory. sprite-map-create() allows to use sub dirs.
+  // Main icons directory. `sprite-map-create()`, base for sub dirs.
   dir: "icons",
 
   // Name of the png sub-folders.
@@ -28,7 +31,7 @@ $icons-defaults: (
   // Minimum resolution ratio used in the hidpi media query.
   hidpi-ratio: 1.3,
 
-  // Whether to embed icons as data URI in the icon-single() mixin.
+  // Whether to embed icons as data URI in the `icon-single()` mixin.
   single-embed: true,
 
   // Default file format unless overridden by parameter, svg | png.
@@ -39,10 +42,24 @@ $icons-defaults: (
 
 );
 
-// User settings.
+
+/**
+ * User settings.
+ * ---
+ * @type Map
+ */
 $icons-settings: () !default;
 
-// Retreive a configuration item.
+
+/**
+ * Retrieve a configuration item.
+ * ---
+ * @access private
+ * ---
+ * @param {String} $key - configuration item key
+ * ---
+ * @return {*}
+ */
 @function conf($key) {
   @if not map-has-key($icons-defaults, $key) {
     @warn "No item `#{$key}` found in configuration.";

data/stylesheets/helpers/_helpers.scss

@@ -1,28 +1,24 @@
 
-// Push new entry to `$map`
-// -----------------------------------------------------------------------------
-// @param [map] $map
-// @param $key
-// @param $value
-// -----------------------------------------------------------------------------
-// @return [map]
-
-@function _map-set($map, $key, $value) {
-  @return map-merge($map, ($key: $value));
-}
-
-
-
-// Join `$list` into a string
-// -----------------------------------------------------------------------------
-// @param [list] $list
-// @param [string] $glue
-// -----------------------------------------------------------------------------
-// @return [string]
-
-@function _join($list, $glue: "") {
-  $result: "";
+// SassyIcons: helpers
+// -------------------
+
+
+/**
+ * Helper: join `$list` into a string.
+ * ---
+ * @access private
+ * ---
+ * @param {List} $list - the list to convert
+ * @param {String} $glue ('') - a string to separate each element of the list
+ * ---
+ * @return {String}
+ */
+@function _join(
+  $list,
+  $glue: ''
+) {
   $length: length($list);
+  $result: '';
 
   @if $length < 1 {
     @return $result;
@@ -31,52 +27,66 @@
   @for $i from 1 through $length {
     $result: $result
              + nth($list, $i)
-             + if($i != $length, $glue, "");
+             + if($i != $length, $glue, '');
   }
 
   @return $result;
 }
 
 
-
-// Helper: retreive a sprite map.
-// -----------------------------------------------------------------------------
-// @param [string] $name
-// @param [string] $factor
-// -----------------------------------------------------------------------------
-// @return [spritemap]
-
-@function _sprite-map-get($name, $factor: 1x) {
-  @return map-get(map-get($icons-maps, $name), $factor);
+/**
+ * Helper: retrieve a spritemap.
+ * ---
+ * @access private
+ * ---
+ * @param {String} $name - spritemap name
+ * @param {String} $factor (1x) - dpi factor
+ * ---
+ * @return {Spritemap}
+ */
+@function _sprite-map-get(
+  $name,
+  $factor: 1x
+) {
+  @return map-get(map-get($icons-spritemaps, $name), $factor);
 }
 
 
-
-// Helper: return correct sprites-map `background-position`.
-// -----------------------------------------------------------------------------
-// @param [spritemap] $map
-// @param [string] $sprite
-// @param [number] $offset-x
-// @param [number] $offset-y
-// @param [number] $scale
-// -----------------------------------------------------------------------------
-// @return [list]
-
-@function _sprite-position($map, $sprite, $offset-x: 0, $offset-y: 0, $scale: 1) {
+/**
+ * Helper: return correct spritemap `background-position`.
+ * ---
+ * @access private
+ * ---
+ * @param {Spritemap} $map - spritemap name
+ * @param {String} $sprite - sprite name
+ * @param {Number} $offset-x (0) - adjustment along the x axis
+ * @param {Number} $offset-y (0) - adjustment along the y axis
+ * @param {Number} $scale    (1) - spritemap scale
+ * ---
+ * @return {List} (x-pos y-pos)
+ */
+@function _sprite-position(
+  $map,
+  $sprite,
+  $offset-x: 0,
+  $offset-y: 0,
+  $scale: 1
+) {
   $pos: sprite-position($map, $sprite, $offset-x, $offset-y * $scale);
   @return (nth($pos, 1) nth($pos, 2) / $scale);
 }
 
 
-
-// Hidpi media query builder.
-// -----------------------------------------------------------------------------
-// http://bjango.com/articles/min-device-pixel-ratio/
-// http://brettjankord.com/2012/11/28/cross-browser-retinahigh-resolution-media-queries
-// http://w3.org/blog/CSS/2012/06/14/unprefix-webkit-device-pixel-ratio
-// -----------------------------------------------------------------------------
-
-@mixin hidpi-mq() {
+/**
+ * Hidpi media query builder.
+ * ---
+ * @access private
+ * ---
+ * @link http://bjango.com/articles/min-device-pixel-ratio/
+ * @link http://brettjankord.com/2012/11/28/cross-browser-retinahigh-resolution-media-queries
+ * @link http://w3.org/blog/CSS/2012/06/14/unprefix-webkit-device-pixel-ratio
+ */
+@mixin hidpi-mq {
   $hidpi-ratio: conf(hidpi-ratio);
 
   @media (-webkit-min-device-pixel-ratio: $hidpi-ratio),

data/stylesheets/icons/_generated.scss

@@ -1,20 +1,37 @@
 
-//
-// Generated content.
-//
-@mixin generated($width: false, $height: false, $top: false, $right: false, $bottom: false, $left: false) {
-  //
-  //  Boilerplate styles for generated content .before :after
-  //
-  @if ($width) { width: $width };
-  @if ($height) { height: $height };
+// SassyIcons: generated
+// ---------------------
+
+
+/**
+ * Boilerplate styles for generated content `:before` or `:after`.
+ * ---
+ * @access private
+ * ---
+ * @param {Number} $width
+ * @param {Number} $height
+ * @param {Number} $top
+ * @param {Number} $right
+ * @param {Number} $bottom
+ * @param {Number} $left
+ */
+@mixin generated(
+  $width: false,
+  $height: false,
+  $top: false,
+  $right: false,
+  $bottom: false,
+  $left: false
+) {
+  @if $width { width: $width };
+  @if $height { height: $height };
   content: "";
   display: block;
   position: absolute;
-  @if($top) { top: $top; }
-  @if($right) { right: $right; }
-  @if($bottom) { bottom: $bottom; }
-  @if($left) { left: $left; }
+  @if $top { top: $top; }
+  @if $right { right: $right; }
+  @if $bottom { bottom: $bottom; }
+  @if $left { left: $left; }
   z-index: 1;
 
   @content;

data/stylesheets/icons/_icon-generated.scss

@@ -1,37 +1,49 @@
-//
-// SassyIcons
-//
-
-//
-// Include the icon in a generated "pseudo-element".
-// Default to :before
-// Allows for easier positioning or centering.
-//
+
+// SassyIcons: icon-generated
+// --------------------------
+
+
+/**
+ * Include the icon in a generated pseudo-element.
+ * Default to `:before`.
+ * Allows for easier positioning or centering.
+ * ---
+ * @requires conf
+ * @requires _sprite-map-get
+ * @requires {mixin} generated
+ * @requires {mixin} icon
+ * ---
+ * @param {String} $map - spritemap name
+ * @param {String} $sprite - sprite name
+ * @param {String} $pos ('before') - pseudo-element position
+ * @param {Bool} $centered (false) - whether to center the icon, relative to its parent
+ * @param {String} $format (conf(format)) - file format 'svg' | 'png'
+ */
 @mixin icon-generated(
-  $name,
+  $map,
   $sprite,
-  $pos: "before",
+  $pos: 'before',
   $centered: false,
   $format: conf(format)
 ) {
   position: relative;
 
   &:#{$pos} {
-    $sprite-file: sprite-file(_sprite-map-get($name), $sprite);
+    $sprite-file: sprite-file(_sprite-map-get($map), $sprite);
 
     $width: image-width($sprite-file);
     $height: image-height($sprite-file);
 
     @include generated($width, $height);
 
-    @if ($centered) {
+    @if $centered {
       top: 35%;
       top: calc(50% - #{$height} / 2);
       left: 35%;
       left: calc(50% - #{$width} / 2);
     }
 
-    @include icon($name: $name, $sprite: $sprite, $format: $format);
+    @include icon($map: $map, $sprite: $sprite, $format: $format);
 
     @content;
   }

data/stylesheets/icons/_icon-single.scss

@@ -1,13 +1,21 @@
-//
-// SassyIcons
-//
 
-//
-// Embed a single icon as inline-image (no sprite).
-// Should be used sporadically.
-//
+// SassyIcons: icon-single
+// -----------------------
+
+
+/**
+ * Embed a single icon as inline-image (no spritemap).
+ * Should be used sporadically.
+ * ---
+ * @requires conf
+ * @requires _join
+ * ---
+ * @param {String} $map - spritemap name
+ * @param {String} $sprite - sprite name
+ * @param {String} $format (conf(format)) - file format 'svg' | 'png'
+ */
 @mixin icon-single(
-  $name,
+  $map,
   $sprite,
   $format: conf(format)
 ) {
@@ -16,9 +24,9 @@
   // @see https://github.com/chriseppstein/compass/issues/951
 
   $dir: conf(dir);
-  $svg-file: _join(($dir, $name, "#{$sprite}.svg"), "/");
-  $png-file-1x: _join(($dir, $name, conf(dir-png), "#{$sprite}.png"), "/");
-  $png-file-2x: _join(($dir, $name, conf(dir-hidpi), "#{$sprite}.png"), "/");
+  $svg-file: _join(($dir, $map, '#{$sprite}.svg'), '/');
+  $png-file-1x: _join(($dir, $map, conf(dir-png), '#{$sprite}.png'), '/');
+  $png-file-2x: _join(($dir, $map, conf(dir-hidpi), '#{$sprite}.png'), '/');
 
   $function: if(conf(single-embed), inline-image, image-url);
   $svg-url: call($function, $svg-file);
@@ -27,9 +35,10 @@
 
   $legacy-support: conf(legacy);
 
+  // Allow to pass format as uppercase.
   $format: to-lower-case($format);
 
-  @if $format == "svg" {
+  @if $format == 'svg' {
 
     background: {
       image: $svg-url;
@@ -48,7 +57,7 @@
     }
 
   }
-  @else if $format == "png" {
+  @else if $format == 'png' {
 
     background: {
       image: $png-url-1x;

data/stylesheets/icons/_icon.scss

@@ -1,18 +1,30 @@
-//
-// SassyIcons
-//
 
-//
-// Main icon mixin.
-//
+// SassyIcons: icon
+// ----------------
+
+
+/**
+ * Main icon mixin,
+ * default choice unless there are specific needs.
+ * ---
+ * @requires conf
+ * @requires _sprite-map-get
+ * @requires _join
+ * @requires _sprite-position
+ * ---
+ * @param {String} $map - spritemap name
+ * @param {String} $sprite - sprite name
+ * @param {List}   $offset (0 0) - adjustment along the x y axis
+ * @param {String} $format (conf(format)) - file format 'svg' | 'png'
+ */
 @mixin icon(
-  $name,
+  $map,
   $sprite,
   $offset: 0 0,
   $format: conf(format)
 ) {
-  $map-1x: _sprite-map-get($name);
-  $map-2x: _sprite-map-get($name, 2x);
+  $map-1x: _sprite-map-get($map);
+  $map-2x: _sprite-map-get($map, 2x);
 
   // Shorter mixin calls.
   $offset-x: nth($offset, 1);
@@ -20,11 +32,12 @@
 
   $legacy-support: conf(legacy);
 
+  // Allow to pass format as uppercase.
   $format: to-lower-case($format);
 
-  @if $format == "svg" {
+  @if $format == 'svg' {
 
-    $svg-file: _join((conf(dir), $name, "#{$sprite}.svg"), "/");
+    $svg-file: _join((conf(dir), $map, '#{$sprite}.svg'), '/');
 
     background: {
       image: inline-image($svg-file);
@@ -39,20 +52,20 @@
       .no-svg &,
       .no-js & {
 
-        @extend %sprite-map-#{$name}-image-map;
+        @extend %sprite-map-#{$map}-image-map;
 
         background-position: _sprite-position($map-1x, $sprite, $offset-x, $offset-y);
       }
     }
 
   }
-  @else if $format == "png" {
+  @else if $format == 'png' {
 
-    @extend %sprite-map-#{$name}-image-map;
+    @extend %sprite-map-#{$map}-image-map;
 
     background-position: _sprite-position($map-1x, $sprite, $offset-x, $offset-y);
 
-    @extend %sprite-map-#{$name}-2x-image-map;
+    @extend %sprite-map-#{$map}-2x-image-map;
 
     @include hidpi-mq {
       background-position: _sprite-position($map-2x, $sprite, $offset-x, $offset-y, conf(hidpi-scale));

data/stylesheets/icons/_sprite-map-create.scss

@@ -1,25 +1,39 @@
-//
-// SassyIcons
-//
 
-// Storage
-$icons-maps: ();
+// SassyIcons: sprite-map-create
+// -----------------------------
 
-//
-// Create a new sprite map from folder.
-//
+
+/**
+ * Spritemaps storage.
+ * ---
+ * @access private
+ * ---
+ * @type Map
+ */
+$icons-spritemaps: ();
+
+
+/**
+ * Create a new spritemap from folder.
+ * ---
+ * @requires conf
+ * @requires _join
+ * ---
+ * @param {String} $name - spritemap name, which is also the folder name
+ * @param {Number} $spacing (conf(spacing)) - Whether to add space around sprites in generated spritemap
+ */
 @mixin sprite-map-create(
   $name,
   $spacing: conf(spacing)
 ) {
-
   $sprites-1x: _join((conf(dir), $name, conf(dir-png), "*.png"), "/");
   $sprites-2x: _join((conf(dir), $name, conf(dir-hidpi), "*.png"), "/");
 
   $map-1x: sprite-map($sprites-1x, $spacing: $spacing);
   $map-2x: sprite-map($sprites-2x, $spacing: $spacing);
 
-  $icons-maps: _map-set($icons-maps, $name, (1x: $map-1x, 2x: $map-2x)) !global;
+  $new: ($name: (1x: $map-1x, 2x: $map-2x));
+  $icons-spritemaps: map-merge($icons-spritemaps, $new) !global;
 
   @at-root %sprite-map-#{$name}-image-map {
     background: {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: SassyIcons
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.0
 platform: ruby
 authors:
 - Pascal Duez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-09 00:00:00.000000000 Z
+date: 2014-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sass
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: 1.0.0.alpha.19
+        version: 1.0.0.rc.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: 1.0.0.alpha.19
+        version: 1.0.0.rc.1
 description: Flexible icons system.
 email: 
 executables: []
@@ -56,7 +56,8 @@ files:
 - stylesheets/icons/_icon.scss
 - stylesheets/icons/_sprite-map-create.scss
 homepage: http://github.com/pascalduez/SassyIcons
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []