sass-aleksi 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 893674e8c5f9e9905e811efeb9e46a42f5105ba2
+  data.tar.gz: f03afa65e82e3b4e5aaad93dcc1b7c760e1e96c9
+SHA512:
+  metadata.gz: 31591aa865f29353917dcd9a22cf487a381175cd7b2a6104fb8dffe856876d0becb031cfaf2f91566987f38ca52b6af60c7d91887bb6bbb98e5b2f78526ae8eb
+  data.tar.gz: e8e0941ecede6e1231dcd420e8dd588bdbb2999cd34c30b8ee65254521a76cb87880391ae426cdd9b090579e116ec2407a3d6823aa8aa135e9488a58c8e96c3c

data/README.md

@@ -0,0 +1,44 @@
+# Aleksi
+
+Aleksi is a collection of Sass helper functions and mixins. It bundles other libraries and provides its own functions and mixins on top.
+
+The russian firstname *Aleksi* means *helper of man*.
+
+## Installation
+
+### RubyGem & Compass
+
+Open the Terminal and install the ruby gem:
+
+    gem install sass-aleksi
+
+Require gem in your compass project configuration file
+
+    require sass-aleksi;
+
+Import files in your project's stylesheets
+
+    @import "aleksi";
+
+### Bower
+
+Open the Terminal, `cd` to your project folder and enter the following command:
+
+    bower install sass-aleksi --save
+
+Import files in your project's stylesheets
+
+    @import "path/to/bower_components/sass-aleksi/aleksi";
+
+## Dependencies and Bundling
+
+Aleski requires Compass and will import only the needed parts from compass. Additionally, it depends on the following Sass/Compass extensions:
+
++ [Sass (~> 3.3)](https://github.com/sass/sass)
++ [SassyCast (~> 1.1.1)](https://github.com/HugoGiraudel/SassyCast)
++ [SassyMath (~> 1.5)](https://github.com/at-import/sassy-math)
++ [SassyStrings (~> 1.1.4)](https://github.com/at-import/Sassy-Strings)
++ [SassyLists (~> 2.2)](https://github.com/at-import/SassyLists)
++ [Sassy-Maps (0.4.0)](https://github.com/at-import/Sassy-Maps/)
+
+These extensions are bundled with Aleksi, adding `@import "aleksi";` to your stylesheet will give you access to all their functionalities. Be sure to check out their respective documentations to take the most out of Aleksi.

data/lib/sass-aleksi.rb

@@ -0,0 +1,31 @@
+require 'compass/import-once/activate'
+# Require additional compass plugins here
+require 'SassyCast'
+require 'sassy-math'
+require 'SassyStrings'
+require 'SassyLists'
+require 'sassy-maps'
+
+# Extension Paths
+extension_path = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+stylesheets_path = File.join(extension_path, 'stylesheets')
+
+# Register Extension
+if (defined? Compass)
+    # Register as a Compass extension
+    Compass::Frameworks.register('sass-aleksi', :path => extension_path)
+else
+    # Compass not found, register on the Sass path via the environment.
+    if ENV.has_key?("SASS_PATH")
+        ENV["SASS_PATH"] = ENV["SASS_PATH"] + File::PATH_SEPARATOR + stylesheets_path
+    else
+        ENV["SASS_PATH"] = stylesheets_path
+    end
+end
+
+# 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 SassAleksi
+    VERSION = "0.1.2"
+    DATE = "2015-08-25"
+end

data/stylesheets/_aleksi.scss

@@ -0,0 +1,23 @@
+// =============================================================================
+// =Aleksi
+// =============================================================================
+//// Aleksi is a collection of useful Sass functions and mixins. It bundles
+//// other libraries and provides its own functions and mixins on top.
+////
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// LIBRARIES/FRAMEWORKS
+@import "SassyCast";
+@import "SassyStrings";
+@import "SassyLists";
+@import "sassy-maps";
+
+// PARTIALS
+@import "aleksi/config";
+@import "aleksi/general";
+@import "aleksi/math";
+@import "aleksi/lengths";
+@import "aleksi/colors";
+@import "aleksi/lists";
+@import "aleksi/maps";
+@import "aleksi/sides";

data/stylesheets/aleksi/_config.scss

@@ -0,0 +1,11 @@
+// =============================================================================
+// =ALEKSI - CONFIG
+// =============================================================================
+
+@import "aleksi/config/constants";
+
+// =sass constants
+// =============================================================================
+
+@include const('CSS_SIDES', 'top' 'right' 'bottom' 'left');
+@include const('CSS_POSITIONS', 'top' 'right' 'bottom' 'left' 'center');

data/stylesheets/aleksi/_general.scss

@@ -0,0 +1,11 @@
+// =============================================================================
+// =ALEKSI - GENERAL
+// =============================================================================
+//// Imports all general tools.
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+@import "aleksi/general/is-of-type";
+@import "aleksi/general/default-to";
+@import "aleksi/general/apply";
+@import "aleksi/general/css-rule";

data/stylesheets/aleksi/_lengths.scss

@@ -0,0 +1,8 @@
+// =============================================================================
+// =ALEKSI - UNIT
+// =============================================================================
+////
+//// @group aleksi-units
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/lengths/strip-unit";

data/stylesheets/aleksi/_lists.scss

@@ -0,0 +1,16 @@
+// =============================================================================
+// =ALEKSI - LISTS
+// =============================================================================
+//// Tools to work with lists.
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/lists/is-list";
+@import "aleksi/lists/set-list-separator";
+@import "aleksi/lists/prepend";
+@import "aleksi/lists/next";
+@import "aleksi/lists/previous";
+@import "aleksi/lists/get-nth";
+@import "aleksi/lists/contained-in";
+@import "aleksi/lists/walk";
+@import "aleksi/lists/list-filter";
+@import "aleksi/lists/depth";

data/stylesheets/aleksi/_maps.scss

@@ -0,0 +1,21 @@
+// =============================================================================
+// =ALEKSI - MAPS
+// =============================================================================
+//// Tools to work with maps.
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/maps/is-map";
+@import "aleksi/maps/debug-map";
+@import "aleksi/maps/map-get-tuple";
+@import "aleksi/maps/map-find";
+@import "aleksi/maps/map-depth";
+@import "aleksi/maps/map-has-keys";
+@import "aleksi/maps/map-walk";
+@import "aleksi/maps/map-unique";
+@import "aleksi/maps/map-clean";
+@import "aleksi/maps/map-filter";
+@import "aleksi/maps/map-select";
+@import "aleksi/maps/map-sort";
+@import "aleksi/maps/map-zip";
+@import "aleksi/maps/map-merge-deep";
+@import "aleksi/maps/map-extend";

data/stylesheets/aleksi/_math.scss

@@ -0,0 +1,10 @@
+// =============================================================================
+// =ALEKSI - MATH
+// =============================================================================
+//// Tools to work with mathemacitcal operations.
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/math/add";
+@import "aleksi/math/subtract";
+@import "aleksi/math/multiply";
+@import "aleksi/math/divide";

data/stylesheets/aleksi/_sides.scss

@@ -0,0 +1,11 @@
+// =============================================================================
+// =ALEKSI - SIDES
+// =============================================================================
+
+@import "sides/sides-shorthand";
+@import "sides/side-name";
+@import "sides/to-sides-map";
+@import "sides/to-sides-list";
+@import "sides/reduce-sides";
+@import "sides/output-sides";
+@import "sides/side-value";

data/stylesheets/aleksi/config/_constants.scss

@@ -0,0 +1,73 @@
+// =============================================================================
+// =ALEKSI - CONSTANTS
+// =============================================================================
+
+@import "sassy-maps";
+
+$CONSTANTS: () !default;
+
+// =const( $name )
+// -----------------------------------------------------------------------------
+/// Constant getter. Safely retrieves the value of a constant.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {string} $name - Name of the constant to retrieve.
+///
+/// @return {any} - The value of the constant.
+/// @throw Error if constant doesn't exist.
+///
+/// @example scss
+///   $foo: const('CSS_SIDES');
+///     // => 'top' 'right' 'bottom' 'left'
+///
+/// @access public
+/// @since 0.1.0
+
+@function const( $name )
+{
+  @if type-of($name) != string {
+    @return throw-error("const():: $name must be a string. Was #{inspect($name)}.");
+  }
+
+  @if not map-has-key($CONSTANTS, $name) {
+    @return throw-error("Unknown constant #{$name}");
+  }
+
+  @return map-get($CONSTANTS, $name);
+}
+
+// =const( $name, $value )
+// -----------------------------------------------------------------------------
+/// Constant setter. Stores the given value in a constant and prevents existing
+/// constants to be modified.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {string} $name - The name of the constant tp store.
+/// @param {any} $value - The stored constant's value.
+///
+/// @throw Error if $name is not a string.
+/// @throw Error if $name is not a full-caps name or contains hyphens.
+/// @throw Error if $name is already a defined constant.
+///
+/// @example scss
+///   @include const('HOURS_IN_DAY', 24);
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin const( $name, $value )
+{
+  @if type-of($name) != string {
+    @include throw-error('const():: $name must be string. Was #{inspect($name)}.');
+  }
+
+  @else if to-upper-case($name) != $name or str-index($name, '-') {
+    @include throw-error('const():: Constant name #{inspect($name)} is not valid. Must be upper-case and without hyphens.');
+  }
+
+  @else if map-has-key($CONSTANTS, $name) {
+    @include throw-error('Constant #{inspect($name)} already defined.');
+  }
+
+  $CONSTANTS: map-set($CONSTANTS, $name, $value) !global;
+}

data/stylesheets/aleksi/general/_apply.scss

@@ -0,0 +1,42 @@
+// =============================================================================
+// =ALEKSI - APPLY
+// =============================================================================
+////
+//// @group aleksi-general
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/lists/walk";
+@import "aleksi/maps/map-walk";
+
+// =apply( $value, $func[, $args... ])
+// -----------------------------------------------------------------------------
+/// Applies the given function to a value. Delegates to `walk()` if `$value is
+/// a list, arglist or map. On any other value types, it acts like an alias to
+/// `call()` (with `$name` and `$value` arguments inverted). That means that,
+/// contrary to how `call()` behaves, simple values won't be returned as a
+/// single item list.
+///
+/// @param {any} $value - The value to modify.
+/// @param {string} $func - The name of the function to apply to `$value`.
+/// @param {argList} $args... - Additional arguments to pass to `$func`.
+///
+/// @return {any} - The modified value for `$value`.
+/// @throw Can not apply function '#{$func}' because it doesn't exist.
+///
+/// @example scss
+///   $foo: apply(rgb(120,70,20), 'hue');
+///     // => 18.75deg
+///   $bar: apply('lots' 'of' 'laugh', 'str-slice', 1, 2);
+///     // => 'l' 'o' 'l'
+///
+/// @access public
+/// @since 0.1.0
+
+@function apply( $value, $func, $args... )
+{
+  @if is-of-type($value, 'list' 'map') {
+    @return walk($value, $func, $args...);
+  }
+
+  @return call($func, $value, $args...);
+}

data/stylesheets/aleksi/general/_css-rule.scss

@@ -0,0 +1,88 @@
+// =============================================================================
+// =ALEKSI - CSS-RULE
+// =============================================================================
+
+// =css-value( $value[, $important ])
+// -----------------------------------------------------------------------------
+/// Optionally appends the !important flag to a css-value. Can also run the
+/// value through a function before if needed.
+///
+/// @param {any} $value - The value of the css rule to modify
+/// @param {bool} $important - Whether to append the `!important` flag
+/// @param {string} $func - The name of a function to run $value through
+/// @param {arglist} $args... - Additional arguments for $func
+///
+/// @example scss - SCSS stylesheet
+///   .foo {
+///     color: css-value(aqua);
+///     font-size: css-value(2em, true);
+///     content: css-value('hello world', false, 'to-upper-case');
+///   }
+///
+/// @example css - CSS output
+///   .foo {
+///     color: aqua;
+///     font-size: 2em !important;
+///     content: 'HELLO WORLD';
+///   }
+///
+/// @access public
+/// @since 0.1.0
+
+@function css-value( $value, $important: false, $func: null, $args...  )
+{
+  // optionally apply a given funtion to modify the value
+  $value: if($func, call($func, $value, $args...), $value);
+
+  // don't append the '!important' flag to `null` because that will make SASS
+  // output it in the final CSS, when `null` alone will be left out.
+  @return if( $important and ($value != null), $value !important, $value );
+}
+
+// =css-rule( $property, $value[, $important, $func, $args... ])
+// -----------------------------------------------------------------------------
+/// Outputs a css rule dynamically. Optionally modifies the value with a
+/// function and/or appending the '!important' flag. Delegates to the
+/// 'css-value()' function.
+///
+/// @param {string} $name - The property of the css rule to output
+/// @param {any} $value - The value of the css rule to output
+/// @param {bool} $important - Whether to append the `!important` flag
+/// @param {string} $func - The name of a function to run $value through
+/// @param {arglist} $args... - Additional arguments for $func
+///
+/// @see {function} css-value
+///
+/// @example scss - SCSS stylesheet
+///   .foo {
+///     @include css-rule('color', aqua);
+///     @include css-rule(font-size, 2em, true);
+///     @include css-rule(content, 'hello world', false, 'to-upper-case');
+///   }
+///
+/// @example css - CSS output
+///   .foo {
+///     color: aqua;
+///     font-size: 2em !important;
+///     content: 'HELLO WORLD';
+///   }
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin css-rule( $property, $value, $important: false, $func: null, $args... )
+{
+  #{$property}: css-value( $value, $important, $func, $args... );
+}
+
+// =css( $property, $value[, $important, $func, $args... ])
+// -----------------------------------------------------------------------------
+/// @alias css-rule
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin css( $property, $value, $important: false, $func: null, $args... )
+{
+  @include css-rule($property, $value, $important, $func, $args...);
+}

data/stylesheets/aleksi/general/_default-to.scss

@@ -0,0 +1,35 @@
+// =============================================================================
+// =ALEKSI - DEFAULT-TO
+// =============================================================================
+////
+//// @group aleksi-general
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =default-to( $values... )
+// -----------------------------------------------------------------------------
+/// Returns the first truethy value in the given argument's list. You'll usually
+/// want to provide a raw, truethy value as last argument to serve as default.
+///
+/// @param {argList} $values... - The ordered list of values to
+/// @return {any} - The first truethy value in `$values` or `null` if none was found.
+///
+/// @example scss
+///   $foo: default-to(null, false, 'bar');
+///     // => 'bar'
+///   $bar: default-to(false, 'wiz', 'baz');
+///     // => 'wiz'
+///   $baz: default-to( 10, 'foo', null, true);
+///     // => 10
+///
+/// @access public
+
+@function default-to( $values... )
+{
+  @each $value in $values {
+    @if $value {
+      @return $value;
+    }
+  }
+
+  @return null;
+}

data/stylesheets/aleksi/general/_is-of-type.scss

@@ -0,0 +1,72 @@
+// =============================================================================
+// =ALEKSI - IS-OF-TYPE
+// =============================================================================
+////
+//// @group aleksi-general
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "SassyLists";
+@import "aleksi/general/throw";
+@import "aleksi/lists/is-list";
+@import "aleksi/maps/is-map";
+
+// =is-of-type( $value, $type )
+// -----------------------------------------------------------------------------
+/// Checks if a value is of the given type. Also accepts a list of types to
+/// allow multiple types.
+/// **Note**: delegates to `is-list()` so arglists are also considered to be of
+/// type `list`.
+/// **Note**: delegates to `is-map()` so the empty map `()` is also considered
+/// to be of type `map`.
+///
+/// @param {any} $value - The value to analyze.
+/// @param {any} $type - The type(s) to check `$value` against.
+///
+/// @return {bool} - Whether the value's type corresponds to `$type`.
+///
+/// @example scss
+///   $foo: is-of-type('hello', 'string');
+///     // => true
+///   $bar: is-of-type('hello', number string null);
+///     // => true
+///   $baz: is-of-type(10, string bool null);
+///     // => false
+///   $wiz: is-of-type((), map);
+///     // => true
+///
+/// @access public
+/// @since 0.1.0
+
+@function is-of-type( $value, $type )
+{
+  // accept a list of multiple types to test against
+  @if is-list($type) {
+    @each $t in $type {
+      @if is-of-type($value, $t) {
+        @return true;
+      }
+    }
+    // stop if none of the types in $type correspond
+    @return false;
+  }
+
+  // accept the unquoted `null` as a data-type
+  @if $type == null {
+    @return if( $value == null, true, false );
+  }
+
+  // only test against valid type names
+  @else if type-of($type) != string {
+    $e: throw-error('$type must be a string or a list of strings, was #{inspect($type)}.');
+  }
+
+  @else if $type == list {
+    @return is-list($value);
+  }
+
+  @else if $type == map {
+    @return is-map($value);
+  }
+
+  @return (type-of($value) == $type);
+}

data/stylesheets/aleksi/general/_throw.scss

@@ -0,0 +1,125 @@
+// =============================================================================
+// =ALEKSI - THROW
+// =============================================================================
+//// Tools to throw errors and warnings.
+////
+//// @group aleksi-general
+//// @author [Yoannis Jamar](http://yoannis.me)
+////
+//// @todo Fork SassyLogger to add support inside of functions and implement it.
+
+// =_throw( $type, $message )
+// -----------------------------------------------------------------------------
+/// Throws a warning or an error to the console with the given `$message`.
+///
+/// @param {string} $type - The type of log message you want to throw (either 'warn' or 'error')
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @return {null} - Always returns null
+/// @throw `$type` is not a valid Sass logging directive.
+/// @throw `$message` must be a string.
+///
+/// @access private
+/// @since 0.1.0
+
+@function _throw( $type, $message )
+{
+  @if not index('warn' 'error', $type) {
+    @return _throw('error', '#{inspect($type)} is not a valid directive for Sass\'s console.');
+  }
+
+  @if type-of($message) != string {
+    @return _throw('error', '$message must be a string, was #{inspect($message)}.');
+  }
+
+  @if $type == 'warn' {
+    @warn #{$message};
+  }
+
+  @else if $type == 'error' {
+    @error #{$message};
+  }
+
+  @return null;
+}
+
+// =throw-warning( $message )
+// -----------------------------------------------------------------------------
+/// Throws a warning to the console with the given `$message`.
+///
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @return {null} - Always returns `null`.
+///
+/// @access public
+/// @since 0.1.0
+
+@function throw-warning( $message )
+{
+  @return _throw('warn', $message);
+}
+
+// =throw-error( $message )
+// -----------------------------------------------------------------------------
+/// Throws an error to the console with the given `$message`.
+///
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @return {null} - Always returns `null`.
+///
+/// @access public
+/// @since 0.1.0
+
+@function throw-error( $message )
+{
+  @return _throw('error', $message);
+}
+
+// =MIXINS
+// =============================================================================
+
+// =_throw( $type, $message )
+// -----------------------------------------------------------------------------
+/// Throws a warning or an error to the console with the given `$message`.
+///
+/// @param {string} $type - The type of log message you want to throw (either 'warn' or 'error')
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @throw `$type` is not a valid Sass logging directive.
+/// @throw `$message` must be a string.
+///
+/// @access private
+/// @since 0.1.0
+
+@mixin _throw( $type, $message )
+{
+  $exception: _throw($type, $message);
+}
+
+// =throw-warning( $message )
+// -----------------------------------------------------------------------------
+/// Throws a warning to the console with the given `$message`.
+///
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin throw-warning( $message )
+{
+  @include _throw('warn', $message);
+}
+
+// =throw-error( $message )
+// -----------------------------------------------------------------------------
+/// Throws an error to the console with the given `$message`.
+///
+/// @param {string} $message - The message to print in the Sass console.
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin throw-error( $message )
+{
+  @include _throw('error', $message );
+}