sass-aleksi 0.1.2

data/stylesheets/aleksi/lists/_walk.scss

@@ -0,0 +1,96 @@
+// =============================================================================
+// =ALEKSI - WALK
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "SassyLists";
+@import "aleksi/general/throw";
+@import "aleksi/maps/map-walk";
+@import "aleksi/lists/set-list-separator";
+
+// =walk( $list, $func[, $args... ])
+// -----------------------------------------------------------------------------
+/// Applies the given function to each value inside a list, arglist or a map.
+/// **Note**: SassyLists offers the similar `sl-walk()` function. The difference
+/// is that Aleksi's `walk()` function will delegate to `map-walk()` when the
+/// first argument is a map.
+/// **Note**: When passed a simple value (not a list, arglist or map), it will
+/// apply the function to it and return the result inside a single item list.
+///
+/// @param {list|map} $list [default] - The values to walk over.
+/// @param {string} $func - The name of the function to apply to each value.
+/// @param {arglist} $args... - Additional arguments passed to '$func`.
+///
+/// @return {list|map} - The list, arglist or map with modified values.
+/// @throw Warning when walking over a simple value.
+///
+/// @example scss
+///   $foo: map-walk(('foo': 'bar', 'bar': 'baz'), 'to-upper-case');
+///     // => ('foo': 'BAR', 'bar': 'BAZ')
+///   $bar: list-walk('foo' 'bar' 'baz', 'to-upper-case');
+///     // => 'FOO' 'BAR' 'BAZ'
+///   $baz: list-walk('foo', 'to-upper-case');
+///     // => 'FOO'
+///
+/// @access public
+/// @since 0.1.0
+
+@function walk( $list, $func, $args... )
+{
+  @if type-of($list) == 'map' {
+    @return map-walk($list, $func, $args...);
+  }
+
+  @else if is-list($list) {
+    @return list-walk($list, $func, $args...);
+  }
+
+  $w: throw-warning("Walking over a simple value #{inspect($list)} — resulting value will be returned inside a list.");
+  @return call($func, $list, $args...);
+}
+
+// =list-walk( $list, $func[, $args... ])
+// -----------------------------------------------------------------------------
+/// Applies the given function to each value inside a list or arglist or a map.
+/// **Note**: SassyLists offers the similar `sl-walk()` function but it throws
+/// an wrong-type error in Libsass when passing a function that only accepts one
+/// argument and an empty arglist as third parameter.
+///
+/// @param {list} $list [default] - The list of values to walk over.
+/// @param {string} $func - The name of the function to apply to each value.
+/// @param {arglist} $args... - Additional arguments passed to '$func`.
+///
+/// @return {list|map} - The list, arglist or map with modified values.
+/// @throw Error if `$value` is not a list.
+/// @throw Warning when walking over a simple value.
+///
+/// @example scss
+///   $foo: map-walk(('foo': 'bar', 'bar': 'baz'), 'to-upper-case');
+///     // => ('foo': 'BAR', 'bar': 'BAZ')
+///   $bar: list-walk('foo' 'bar' 'baz', 'to-upper-case');
+///     // => 'FOO' 'BAR' 'BAZ'
+///   $baz: list-walk('foo', 'to-upper-case');
+///     // => 'FOO'
+///
+/// @access public
+/// @since 0.1.0
+
+@function list-walk( $list, $func, $args... )
+{
+  @if not is-list($list) {
+    $e: throw-error("list-walk():: $list must be a list, was #{inspect($list)}.");
+  }
+
+  $sep: list-separator($list);
+  $res: ();
+
+  @each $item in $list {
+    $new: if( length($args) == 0, call($func, $item), call($func, $item, $args...) );
+    $res: append($res, $new);
+  }
+
+  // keep original list separator
+  @return set-list-separator($res, $sep);
+}

data/stylesheets/aleksi/lists/_wrap-in-list.scss

@@ -0,0 +1,42 @@
+// =============================================================================
+// =ALEKSI - WRAP-IN-LIST
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/lists/set-list-separator";
+
+// =wrap-in-list( $value[, $separator ])
+// -----------------------------------------------------------------------------
+/// Wraps any value inside a single-item list.
+/// **Note**: contrary to SassyCast's `to-list()` function, maps won't be
+/// transformed into lists, and lists will get nested.
+///
+/// @param {any} $value - The value to wrap inside a list.
+/// @param {string} $separator ['space'] - The separator type the list should use.
+///
+/// @return {list} - A single item list with `$value` inside, and using `$separator`.
+///
+/// @example scss
+///   $foo: wrap-in-list(10);
+///     // => 10
+///   type-of($foo);
+///     // => list
+///   $bar: wrap-in-list('foo' 'bar');
+///     // => 'foo' 'bar'
+///   length($bar);
+///     // => 1
+///   $baz: wrap-in-list( ('a': 'foo', 'b': 'bar') );
+///     // => ('a': 'foo', 'b': 'bar')
+///   type-of($baz);
+///     // => list
+///
+/// @access public
+/// @since 0.1.0
+
+@function wrap-in-list( $value, $separator: 'space' )
+{
+  $value: ($value,);
+  @return if($separator == 'space', to-space-list($value), $value);
+}

data/stylesheets/aleksi/maps/_debug-map.scss

@@ -0,0 +1,39 @@
+// =============================================================================
+// =ALEKSI - DEBUG-MAP
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/maps/map-depth";
+
+// =debug-map( $map )
+// -----------------------------------------------------------------------------
+/// Prints out the given map's contents and useful information for debugging
+/// purposes.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {map} $map - The map to print out.
+///
+/// @throw Error if `$map` is not a map.
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin debug-map( $map )
+{
+  @at-root {
+    @debug-map {
+      __toString__: inspect($map);
+      __length__: length($map);
+      __depth__: map-depth($map);
+      __keys__: map-keys($map);
+      __properties__ {
+        @each $key, $value in $map {
+          $key-str: '(#{type-of($value)})-#{$key}';
+          #{$key-str}: inspect($value);
+        }
+      }
+    }
+  }
+}

data/stylesheets/aleksi/maps/_is-map.scss

@@ -0,0 +1,31 @@
+// =============================================================================
+// =ALEKSI - IS-MAP
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =is-map( $value )
+// -----------------------------------------------------------------------------
+/// Verifies if the given value is a map. Also accepts `()`, contrary to testing
+/// manually `type-of(()) == map`.
+///
+/// @param {any} $value - The value to test.
+///
+/// @return {bool} - Whether `$value` is a map.
+///
+/// @example scss
+///   $foo: is-map(('a': 10, 'b': 'foo'));
+///     // => true
+///   $bar: is-map(());
+///     // => true
+///   $baz: is-map('a' 10 'b' 'foo');
+///     // => false
+///
+/// @access public
+/// @since 0.1.0
+
+@function is-map( $value )
+{
+  @return (type-of($value) == map or $value == ());
+}

data/stylesheets/aleksi/maps/_map-clean.scss

@@ -0,0 +1,45 @@
+// =============================================================================
+// =ALEKSI - MAP-CLEAN
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =map-clean( $map )
+// -----------------------------------------------------------------------------
+/// Removes all falsy values from a map.
+/// **Note**: if all item shave been removed, it will return `()` to act like
+/// all other map filtering functions (emptying a list with `map-remove()` would
+/// normally return a *real* empty map ``);
+///
+/// @param {map} $map - The map to clean.
+///
+/// @return {map} - A new map, without falsy values.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-clean( ('a': 10, 'b': false, 'c': 'foo', 'd': null) );
+///     // => ('a': 10, 'c': 'foo')
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-clean( $map )
+{
+  @if not is-map($map) {
+    @return throw-error('map-clean():: $map must be a map. Was #{inspect($map)}');
+  }
+
+  @each $key, $value in $map {
+    @if not $value {
+      $map: map-remove($map, $key);
+    }
+  }
+
+  // return the empty map `()` instead of `` if all map
+  // items have been remove.
+  @return if(length($map) == 0, (), $map);
+}

data/stylesheets/aleksi/maps/_map-depth.scss

@@ -0,0 +1,46 @@
+// =============================================================================
+// =ALEKSI - MAP-DEPTH
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =map-depth( $map )
+// -----------------------------------------------------------------------------
+/// Returns the depth level of a given map.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {map} $map - The map to analyze.
+///
+/// @return {number} - The depth of `$map`.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-depth( ('a': 'foo', 'b': ( 'ba': 'bar', 'bb': 'baz' )));
+///     // => 2
+///   $bar: map-depht('a': 'foo', 'b': 'bar', 'c': 'baz');
+///     // => 1
+///
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-depth( $map )
+{
+  @if not is-map($map) {
+    @return throw-error('map-depth():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  $lvl: 1;
+
+  @each $key, $val in $map {
+    @if type-of($val) == 'map' {
+      $lvl: max(map-depth($val) + 1, $lvl);
+    }
+  }
+
+  @return $lvl;
+}

data/stylesheets/aleksi/maps/_map-extend.scss

@@ -0,0 +1,50 @@
+// =============================================================================
+// =ALEKSI - MAP-EXTEND
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "SassyLists";
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+@import "aleksi/maps/map-merge-deep";
+
+// =map-extend( $maps... )
+// -----------------------------------------------------------------------------
+/// Merges the given maps successively. Allows to merge more then two maps
+/// together.
+
+@function map-extend( $maps... )
+{
+  @if length($maps) < 2 {
+    $e: throw-warning('map-extend():: trying to extend one map only. Returning the map as is.');
+    @return $nth($maps, 1);
+  }
+
+  $res: nth($maps, 1);
+  @each $map in sl-slice($maps, 2) {
+    $res: map-merge($res, $map);
+  }
+
+  @return $res;
+}
+
+// =map-extend-deep( $maps... )
+// -----------------------------------------------------------------------------
+
+@function map-extend-deep( $maps... )
+{
+  @if length($maps) < 2 {
+    $e: throw-warning('map-extend-deep():: trying to extend one map only. Returning the map as is.');
+    @return $nth($maps, 1);
+  }
+
+  $res: nth($maps, 1);
+
+  @each $map in sl-slice($maps, 2) {
+    $res: map-merge-deep($res, $map);
+  }
+
+  @return $res;
+}

data/stylesheets/aleksi/maps/_map-filter.scss

@@ -0,0 +1,84 @@
+// =============================================================================
+// =ALEKSI - MAP-FILTER
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "sassy-maps";
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =map-filter( $map, $test, $args... )
+// -----------------------------------------------------------------------------
+/// Removes items in a map with a value that doesn't pass a given test function.
+/// **Note**: to pass the test, the test function must return a truethy value —
+/// not per se the boolean `true`.
+///
+/// @param {map} $map - The map with the item values to test.
+/// @param {string} $test - The name of the test function to run on each item's value.
+/// @param {arglist} $args... - Additional arguments for `$test`.
+///
+/// @return {map} - `$map` without the items that didn't pass the `$test` function.
+///
+/// @example scss
+///   $foo: map-filter( ('foo': 10, 'bar': 5px, 'baz': 7, 'wiz' 3), 'unitless');
+///     // => ('foo': 10, 'baz': 7, 'wiz': 3)
+///   $bar: map-filter( ('foo': 10px, 'bar': 2%, 'baz': 4px, 'wiz': 8em), 'comparable', 1px);
+///     // => ('foo': 10px, 'baz': 4px)
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-filter( $map, $test, $args... )
+{
+  @if not is-map($map) {
+    @return throw-error('map-filter():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  $res: ();
+
+  @each $key, $val in $map {
+    @if call($test, $val, $args...) {
+      $res: map-set($res, $key, $val);
+    }
+  }
+
+  @return $res;
+}
+
+// =map-filter-keys( $map, $test, $args... )
+// -----------------------------------------------------------------------------
+/// Removes items in a map with a key that doesn't pass a given test function.
+/// **Note**: to pass the test, the test function must return a truethy value —
+/// not per se the boolean `true`.
+///
+/// @param {map} $map - The map with the item keys to test.
+/// @param {string} $test - The name of the test function to run on each item's key.
+/// @param {arglist} $args... - Additional arguments for `$test`.
+///
+/// @return {map} - `$map` without the items that didn't pass the `$test` function.
+///
+/// @example scss
+///   $foo: map-filter( ('foo': 10, 'bar': 5px, 'baz': 7, 'wiz' 3), 'str-index', 'b');
+///     // => ('bar': 5px, 'baz': 7)
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-filter-keys( $map, $test, $args... )
+{
+  @if not is-map($map) {
+    @return throw-error('map-filter():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  $res: ();
+
+  @each $key, $val in $map {
+    @if call($test, $key, $args...) {
+      $res: map-set($res, $key, $val);
+    }
+  }
+
+  @return $res;
+}

data/stylesheets/aleksi/maps/_map-find.scss

@@ -0,0 +1,95 @@
+// =============================================================================
+// =ALEKSI - MAP-FIND
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =map-find-key( $map, $value )
+// -----------------------------------------------------------------------------
+/// Returns the key under which a given value is stored in a map. If the value
+/// is found multiple times, the first key for it will be returned. Returns
+/// `null` if the value wasn't found.
+///
+/// @param {map} $map - The map to search in.
+/// @param {any} $value - The value to search for.
+///
+/// @return {string} - The first map's key under which `$value` is stored.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-find('a': 10, 'b': 5, 'c': 3, 5);
+///     // => 'b'
+///   $bar: map-find('a': 10, 'b': 5, 'c': 3, 'd': 5, 5);
+///     // => 'b'
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-find-key( $map, $value )
+{
+  @if not is-map($map) {
+    @return throw-error('map-find-key():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  @each $key, $val in $map {
+    @if $val == $value {
+      @return $key;
+    }
+  }
+
+  @return null;
+}
+
+// =map-find( $map, $value )
+// -----------------------------------------------------------------------------
+/// @alias map-find-key
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-find( $map, $value )
+{
+  @return map-find-key($map, $value);
+}
+
+// =map-find-keys( $map, $value )
+// -----------------------------------------------------------------------------
+/// Returns a list with all the keys in a map that hold the given value.
+///
+/// @param {map} $map - The map to search in.
+/// @param {any} $value - The value to search for
+///
+/// @return {list} - The list of keys that hold `$value` in `$map`.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-find-keys( 'a': 'foo', 'b': 'bar', 'c': 'foo', 'd': 'baz', 'foo');
+///     // => 'a' 'b'
+///   $bar: map-find-keys( 'a': 'foo', 'b': 'bar', 'c': 'baz', 'foo');
+///     // => 'a';
+///   $bar-type: type-of($bar);
+///     // => list
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-find-keys( $map, $value )
+{
+  @if not is-map($map) {
+    @return throw-error('map-find-keys():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  $keys: ();
+
+  @each $key, $val in $map {
+    @if $val == $value {
+      $keys: append($keys, $key);
+    }
+  }
+
+  @return $keys;
+}

data/stylesheets/aleksi/maps/_map-get-tuple.scss

@@ -0,0 +1,33 @@
+// =============================================================================
+// =ALEKSI - MAP-GET-TUPLE
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =map-get-tuple( $map, $key )
+// -----------------------------------------------------------------------------
+/// Retrieves a tuple (a key, value formatted as a map item) from a map. Returns
+/// `null` if `$key` was not found in `$map`.
+///
+/// @param {map} $map - The map in which to search for the tuple.
+/// @param {string} $key - The key of the tuple to retreive.
+///
+/// @return {map} - The `(key: value)` pair corresponding to `$key`.
+/// @throw Error if `$map`is not a map.
+///
+/// @example scss
+///   $foo: map-get-tuple('a': 'foo', 'b': 'bar', 'a');
+///     // => ('a': 'foo')
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-get-tuple( $map, $key )
+{
+  @if not is-map($map) {
+    @return throw-error('map-get-tuple():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  @return (#{$key}: map-get($map, $key));
+}

data/stylesheets/aleksi/maps/_map-has-keys.scss

@@ -0,0 +1,92 @@
+// =============================================================================
+// =ALEKSI - MAP-HAS-KEYS
+// =============================================================================
+////
+//// @group aleksi-maps
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =map-has-keys( $map, $keys )
+// -----------------------------------------------------------------------------
+/// Tests if a map has all the given keys at first level.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {map} $map - The map to search in for `$keys...`.
+/// @param {list} $keys - The keys to search for.
+///
+/// @return {bool} - Whether all keys were found in first level of `$map`.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-has-keys( ('a': 'foo', 'b': 'bar', 'c': 'baz'), 'a', 'd');
+///     // => false
+///   $bar: map-has-keys( ('a': 'foo', 'b': 'bar', 'c': 'baz'), 'a', 'b');
+///     // => true
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-has-keys($map, $keys)
+{
+  @if not is-map($map) {
+    @return throw-error('map-has-keys():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  @each $key in $keys {
+    @if not map-has-key($map, $key) {
+      @return false;
+    }
+  }
+
+  @return true;
+}
+
+// =map-has-deep-key($map, $keys...)
+// -----------------------------------------------------------------------------
+/// Tests if a map has all given keys nested within each other.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {map} $map - The map to search in for `$keys...`.
+/// @param {arglist} $keys - The keys to search for.
+///
+/// @return {bool} - Whether `$map` has all `$keys` nested within each other.
+/// @throw Error if `$map` is not a map.
+///
+/// @example scss
+///   $foo: map-has-deep-keys( ('a': 'foo', 'b': ('ba': 'bar', 'bb': 'baz')), 'a', 'b');
+///     // => true
+///   $bar: map-has-deep-keys( 'a': 'foo', 'b': 'bar', 'a', 'b')
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-has-deep-key($map, $keys...)
+{
+  @if not is-map($map) {
+    @return throw-error('map-has-deep-key():: $map must be a map, was #{inspect($map)}.');
+  }
+
+  @each $key in $keys {
+    @if not map-has-key($map, $key) {
+      @return false;
+    }
+
+    $map: map-get($map, $key);
+  }
+
+  @return true;
+}
+
+// =map-has-nested-key( $map, $keys... )
+// -----------------------------------------------------------------------------
+/// @alias map-has-deep-key
+///
+/// @access public
+/// @since 0.1.0
+
+@function map-has-nested-key( $map, $keys... )
+{
+  @return map-has-deep-key($map, $keys...);
+}