sass-aleksi 0.1.2

data/stylesheets/aleksi/lengths/_convert.scss

@@ -0,0 +1,100 @@
+// =============================================================================
+// =ALEKSI - CONVERT-LENGTH
+// =============================================================================
+//// @group aleksi-lengths
+//// @author [Chris Eppstein](http://chriseppstein.github.io/)
+
+// Base font size in pixels, if not already defined.
+// Should be the same as the font-size of the html element.
+$base-font-size: 16px !default;
+
+// =convert-length( $length, $to-unit[, $from-context, $to-context ])
+// -----------------------------------------------------------------------------
+/// Convert any CSS <length> or <percentage> value to any another.
+///
+/// @param {number} $length - A css <length> or <percentage> value
+/// @param {string} $to-unit - A css unit keyword, e.g. 'em', '%', 'px', etc.
+/// @param {number} $from-context [$base-font-size] - The absolute length (in px) to which `$length` refers
+/// @param {number} $to-context [$from-context] - the absolute length in px to which the output value will refer.
+///
+/// @return {type|...} - Description
+/// @throw Description
+///
+/// @access public
+/// @since 0.1.0
+
+@function convert-length(
+  $length,
+  $to-unit,
+  $from-context: $base-font-size,
+  $to-context: $from-context
+) {
+  $from-unit: unit($length);
+
+  // Optimize for cases where `from` and `to` units are accidentally the same.
+  @if $from-unit == $to-unit { @return $length; }
+
+  // Context values must be in px so we can determine a conversion ratio for
+  // relative units.
+  @if unit($from-context) != 'px' { @warn "Paremeter $from-context must resolve to a value in pixel units."; }
+  @if unit($to-context) != 'px' { @warn "Parameter $to-context must resolve to a value in pixel units."; }
+
+  // Convert input length to pixels
+  $px-length: $length;
+
+  @if $from-unit != 'px' {
+    // Convert relative units using the from-context parameter.
+    @if      $from-unit == 'em'  { $px-length: $length * $from-context / 1em }
+    @else if $from-unit == 'rem' { $px-length: $length * $base-font-size / 1rem }
+    @else if $from-unit == '%'   { $px-length: $length * $from-context / 100% }
+    @else if $from-unit == 'ex'  { $px-length: $length * $from-context / 2ex }
+    // Convert absolute units using Sass' conversion table.
+    @else if $from-unit == 'in'  or
+             $from-unit == 'mm'  or
+             $from-unit == 'cm'  or
+             $from-unit == 'pt'  or
+             $from-unit == 'pc'  { $px-length: 0px + $length }
+    // Certain units can't be converted.
+    @else if $from-unit == 'ch'  or
+             $from-unit == 'vw'  or
+             $from-unit == 'vh'  or
+             $from-unit == 'vmin' {
+      @warn "#{$from-unit} units can't be reliably converted; Returning original value.";
+      @return $length;
+    }
+    @else {
+      @warn "#{$from-unit} is an unknown length unit. Returning original value.";
+      @return $length;
+    }
+  }
+
+  // Convert length in pixels to the output unit
+  $output-length: $px-length;
+  @if $to-unit != 'px' {
+    // Relative units
+    @if      $to-unit == 'em'  { $output-length: $px-length * 1em / $to-context }
+    @else if $to-unit == 'rem' { $output-length: $px-length * 1rem / $base-font-size }
+    @else if $to-unit == '%'   { $output-length: $px-length * 100% / $to-context }
+    @else if $to-unit == 'ex'  { $output-length: $px-length * 2ex / $to-context }
+    // Absolute units
+    @else if $to-unit == 'in'  { $output-length: 0in + $px-length }
+    @else if $to-unit == 'mm'  { $output-length: 0mm + $px-length }
+    @else if $to-unit == 'cm'  { $output-length: 0cm + $px-length }
+    @else if $to-unit == 'pt'  { $output-length: 0pt + $px-length }
+    @else if $to-unit == 'pc'  { $output-length: 0pc + $px-length }
+    // Non-convertible units
+    @else if $to-unit == 'ch'  or
+             $to-unit == 'vw'  or
+             $to-unit == 'vh'  or
+             $to-unit == 'vmin' {
+      @warn "#{$to-unit} units can't be reliably converted; Returning original value.";
+      @return $length;
+    }
+    @else {
+      @warn "#{$to-unit} is an unknown length unit. Returning original value.";
+      @return $length;
+    }
+  }
+
+  @return $output-length;
+}

data/stylesheets/aleksi/lengths/_strip-unit.scss

@@ -0,0 +1,37 @@
+// =============================================================================
+// =ALEKSI - STRIP-UNIT
+// =============================================================================
+//// @group aleksi-units
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =strip-unit( $number )
+// -----------------------------------------------------------------------------
+/// Removes the unit of a given number.
+/// @author [Hugo Giraudel](http://hugogiraudel.com)
+///
+/// @param {number} $number - Number from which to strip the unit.
+///
+/// @return {number} - Unitless `$number`.
+/// @throw Error if `$number` is not a number.
+///
+/// @example scss
+///   $foo: strip-unit(10px);
+///     // => 10
+///   $bar: strip-unit(1.5em);
+///     // => 1.5
+///   $baz: strip-unit(50%);
+///     // => 50
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'strip-unit' function
+
+@function strip-unit($number)
+{
+  @if type-of($number) != number {
+    @return throw-error("strip-unit():: $number must be a number. Was #{inspect($number)}.");
+  }
+
+  @return $number / ($number * 0 + 1);
+}

data/stylesheets/aleksi/lists/_contained-in.scss

@@ -0,0 +1,34 @@
+// =============================================================================
+// =ALEKSI - IS-CONTAINED
+// =============================================================================
+
+// =contained-in( $value, $list )
+// -----------------------------------------------------------------------------
+/// Checks if the given value is contained in a list. Behaves like `sl-contain`,
+/// but with the value as first argument. Useful to check for specific values
+/// when walking over a list or map.
+///
+/// @param {type|...} $name [default] - Description
+///
+/// @return {type|...} - Description
+/// @throw Description
+///
+/// @example scss
+///   $foo: contained-in(10px 'foo', 10px);
+///     // => true
+///   $bar: contained-in(10px 'foo', 'bar');
+///     // => false
+///   $baz: sl-every('a' 'b' 'c' 'd', 'contained-in', 'a' 'b' 'c');
+///     // => false
+///   $wiz: sl-every('a' 'b' 'c', 'contained-in', 'a' 'b' 'c');
+///     // => true
+///
+/// @access public
+/// @since version
+///
+/// @todo Test the 'contained-in' function
+
+@function contained-in( $value, $list )
+{
+  @return (index($list, $value) != null);
+}

data/stylesheets/aleksi/lists/_depth.scss

@@ -0,0 +1,46 @@
+// =============================================================================
+// =ALEKSI - DEPTH
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/maps/map-depth";
+
+// =depth( $list )
+// -----------------------------------------------------------------------------
+/// Returns the depth level of a list. If a single value is passed, it will
+/// return 1.
+/// **Note**: also accepts maps, which delegates to `map-depth()`.
+///
+/// @param {list|map} $list - The list to analyze.
+///
+/// @return {number} - The depth of `$list`.
+///
+/// @example scss
+///   $foo: depth(10 true 'foo' ('bar' 'baz') );
+///     // => 2
+///   $bar: depth(10 true 'foo');
+///     // => 1
+///   $baz: depth('foo');
+///     // => 1
+///
+/// @access public
+/// @since 0.1.0
+
+@function depth( $list )
+{
+  @if type-of($list) == 'map' {
+    @return map-depth($list);
+  }
+
+  $lvl: 1;
+
+  @each $item in $list {
+    @if type-of($item) == 'list' {
+      $lvl: max(depth($item) + 1, $lvl);
+    }
+  }
+
+  @return $lvl;
+}

data/stylesheets/aleksi/lists/_get-nth.scss

@@ -0,0 +1,44 @@
+// =============================================================================
+// =ALEKSI - GET-NTH
+// =============================================================================
+
+// =get-nth( $list, $index )
+// -----------------------------------------------------------------------------
+/// Retreives the item at a given index in a list. Differs from Sass's native
+/// `nth` function by returning `null` if the index is out of scope instead of
+/// throwing an error. In this way it behaves more like `map-get()`.
+///
+/// @param {list} $list - The list from which to retreive an item.
+/// @param {number} $index - The index of the item to retreive
+///
+/// @return {any} - The item found at $index in $list, or `null` if none was found.
+///
+/// @example scss
+///   $foo: get-nth(10px 'foo' false, 2);
+///     // => 'foo'
+///   $bar: get-nth(10px 'foo' false, 4);
+///     // => null
+///
+/// @access public
+/// @since 01.0
+
+@function get-nth( $list, $index )
+{
+  @if $index <= length($list) {
+    @return nth($list, $index);
+  }
+
+  @return null;
+}
+
+// =list-get( $list, $index )
+// -----------------------------------------------------------------------------
+/// @alias get-nth
+///
+/// @acces public
+/// @since 0.1.0
+
+@function list-get( $list, $index )
+{
+  @return get-nth($list, $index);
+}

data/stylesheets/aleksi/lists/_is-list.scss

@@ -0,0 +1,35 @@
+// =============================================================================
+// =ALEKSI - IS-LIST
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =is-list( $value )
+// -----------------------------------------------------------------------------
+/// Checks whether the given value is a number. Also accepts argument lists,
+/// contrary to manually testing `type-of($args) == list`.
+///
+/// @param {any} $value - The value to test.
+///
+/// @return {bool} - Whether `$value` is a list.
+///
+/// @example scss
+///   $foo: is-list(10 true 'foo');
+///     // => true
+///
+/// @example scss - Testing an arglist
+///   @function arglist-is-list($args...) {
+///     @return is-list($args);
+///   }
+///   $foo: arglist-is-list(10, true, 'foo');
+///     // => true
+///   $bar: arglist-is-list(10);
+///     // => true
+///
+/// @access public
+/// @since 0.1.0
+
+@function is-list( $value ) {
+  @return (type-of($value) == 'list' or type-of($value) == 'arglist');
+}

data/stylesheets/aleksi/lists/_list-filter.scss

@@ -0,0 +1,48 @@
+// =============================================================================
+// =ALEKSI - FILTER
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/maps/map-filter";
+
+// =list-filter( $list, $test[, $args... ])
+// -----------------------------------------------------------------------------
+/// Removes items in a list that don't pass the given test function. The current
+/// list item will be passed as first argument to the test function.
+/// **Note**: to pass the test, the test function must return a truethy value —
+/// not per se the boolean `true`.
+///
+/// @param {list|map} $list - The list of items to test.
+/// @param {string} $test - The name of the test function to run on each item.
+/// @param {arglist} $args... - Additional arguments for `$test`.
+///
+/// @return {list} - `$list` without the items that didn't pass the `$test` function.
+///
+/// @example scss
+///   $foo: list-filter( 10 5px 7 3, 'unitless');
+///     // => 10 7 3
+///   $bar: list-filter( 10px 2.5 4px 8em, 'comparable', 1px);
+///     // => 10px 2.5 4px
+///
+/// @access public
+/// @since 0.1.0
+
+@function list-filter( $list, $test, $args... )
+{
+  // delegate to 'map-filter' if filtering a map
+  @if type-of($list) == 'map' {
+    @return map-filter($list, $test, $args...);
+  }
+
+  $res: ();
+
+  @each $item in $list {
+    @if call($test, $item, $args...) {
+      $res: append($res, $item);
+    }
+  }
+
+  @return $res;
+}

data/stylesheets/aleksi/lists/_next.scss

@@ -0,0 +1,47 @@
+// =============================================================================
+// =ALEKSI - NEXT
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+
+// =next( $list, $value )
+// -----------------------------------------------------------------------------
+/// Returns the item sitting next to the given value in alist. If the value is
+/// found multiple times, it will use the first one. If the value was not found
+/// or is in last position in the list, it will return `null`.
+///
+/// @param {list} $list - The list in which to search.
+/// @param {list} $value - The value to search in `$list`.
+///
+/// @return {any} - The value sitting previous to `$value` in `$list`.
+/// @throw Warning if `$value` was not found in `$list`.
+/// @throw Warning if `$value` is the last value in `$list`.
+///
+/// @example scss
+///   $foo: next( 'foo' 'bar' 'baz', 'bar');
+///     // => 'baz'
+///   $bar: next( 'foo' 'bar' 'baz', 'baz');
+///     // => null
+///   $baz: next( 'foo' 'bar' 'baz', 'wiz');
+///     // => null
+///
+/// @access public
+/// @since 0.1.0
+
+@function next( $list, $value )
+{
+  $index: index($list, $value);
+
+  @if $index == null {
+    @return throw-warning('next():: #{inspect($value)} could not be found in #{inspect($list)}.');
+  }
+
+  @else if $index == length($list) {
+    @return throw-warning('next():: #{inspect($value)} is the last item in #{inspect($list)}.');
+  }
+
+  @return nth($list, $index + 1);
+}

data/stylesheets/aleksi/lists/_prepend.scss

@@ -0,0 +1,40 @@
+// =============================================================================
+// =ALESKI - PREPEND
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+// =prepend( $list, $value[, $separator ])
+// -----------------------------------------------------------------------------
+/// A simple function to prepend an item to any other value.
+/// **Note**: SassyLists provides a similar 'sl-prepend()' function, but passing
+/// it a list or a map will return a flattened list instead of nested.
+/// Aleksi's `prepend()` function will instead behave like sass's native
+/// `append()` function by nesting lists and maps (unless the $separator
+/// argument suggests otherwise).
+///
+/// @param {list} $list - The list to which $value shoudl be prepended.
+/// @param {list} $value - The value to prepend to $list.
+/// @param {string} $separator (list-separator($list))- The list separator to use when prepending.
+///
+/// @return {list} - A copy of $list, with $value added in first position.
+/// @throw Error if $separator is neither 'space' nor 'comma'.
+///
+/// @example scss
+///   $foo: prepend('bar', 5);
+///     // => 5 'bar'
+///   $bar: prepend( 10 false 'baz', null 'wiz');
+///     // => 'baz' null 'wiz' 10 false;
+///   $baz: prepend( 10 false 'baz', ('en': 'hello', 'es': 'ola'));
+///     // => ('en': 'hello', 'es': 'ola') 10 false 'baz';
+///   $wiz: prepend( (10, false, 'baz'), ('en': 'hello', 'es': 'ola'));
+///     // => ('en': 'hello', 'es': 'ola'), 10, false, 'baz';
+///
+/// @access public
+/// @since 0.1.0
+
+@function prepend( $list, $value, $separator: list-separator($list) )
+{
+  @return append($value, $list, $separator);
+}

data/stylesheets/aleksi/lists/_previous.scss

@@ -0,0 +1,47 @@
+// =============================================================================
+// =ALEKSI - PREVIOUS
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "aleksi/general/throw";
+
+// =previous( $list, $value )
+// -----------------------------------------------------------------------------
+/// Returns the item sitting previous to the given value in alist. If the value
+/// is found multiple times, it will use the first one. If the value was not
+/// found or is in first position in the list, it will return `null`.
+///
+/// @param {list} $list - The list in which to search.
+/// @param {list} $value - The value to search in `$list`.
+///
+/// @return {any} - The value sitting next to `$value` in `$list`.
+/// @throw Warning if `$value` was not found in `$list`.
+/// @throw Warning if `$value` is the first value in `$list`.
+///
+/// @example scss
+///   $foo: next( 'foo' 'bar' 'baz', 'bar');
+///     // => 'foo'
+///   $bar: next( 'foo' 'bar' 'baz', 'foo');
+///     // => null
+///   $baz: next( 'foo' 'bar' 'baz', 'wiz');
+///     // => null
+///
+/// @access public
+/// @since 0.1.0
+
+@function previous( $list, $value )
+{
+  $index: index($list, $value);
+
+  @if $index == null {
+    @return throw-warning('previous():: #{inspect($value)} could not be found in #{inspect($list)}.');
+  }
+
+  @else if $index == 1 {
+    @return throw-warning('previous():: #{inspect($value)} is the first item in #{inspect($list)}.');
+  }
+
+  @return nth($list, $index - 1);
+}

data/stylesheets/aleksi/lists/_set-list-separator.scss

@@ -0,0 +1,173 @@
+// =============================================================================
+// =ALEKSI - SET-LIST-SEPARATOR
+// =============================================================================
+////
+//// @group aleksi-lists
+//// @author [Yoannis Jamar](http://yoannis.me)
+////
+//// @todo Move 'shortcut' functions to separate files ?
+
+@import "aleksi/general/throw";
+@import "aleksi/lists/is-list";
+
+// =set-list-separator( $list, $separator )
+// -----------------------------------------------------------------------------
+/// Converts a list to the given lists separator.
+/// **Note**: Because maps can only use the comma separator a map is passed,
+/// passing a map will throw a warning and return the map as is.
+///
+/// @param {list} $list - The list on which to set the separator.
+/// @param {list} $separator - The separator to set on `$list`
+///
+/// @return {list} - The version of `$list` using the given separator
+///
+/// @example scss
+///   $foo: set-list-separator( 10 true 'foo', 'space');
+///     // => 10 true 'foo'
+///   $bar: set-list-separator( 10 true 'foo', 'comma');
+///     // => 10, true, 'foo'
+///   $baz: set-list-separator( 10, 'comma');
+///     // => (10,)
+///   type-of($baz);
+///     // => 'list'
+///   list-separator($baz)
+///     // => 'comma'
+///
+/// @access public
+/// @since 0.1.0
+
+@function set-list-separator( $list, $separator )
+{
+  // optimization: return list that are already comma-separated as is
+  @if is-list($list) and list-separator($list) == $separator {
+    @return $list;
+  }
+
+  @else if type-of($list) == 'map' {
+    $e: throw-warning('set-list-separator():: Can not change the separator of a map.');
+    @return $list;
+  }
+
+  $res: ();
+
+  @each $item in $list {
+    $res: append($res, $item, $separator);
+  }
+
+  @return $res;
+}
+
+// =to-separator( $list, $separator )
+// -----------------------------------------------------------------------------
+/// @alias set-list-separator
+///
+/// @access public
+/// @since 0.1.0
+
+@function to-separator( $list, $separator )
+{
+  @return set-list-separator( $list, $separator );
+}
+
+// =to-comma-list( $list )
+// -----------------------------------------------------------------------------
+/// Converts a list into a comma-separated list. If the list is already comma-
+/// separated, then it will be returned as is.
+///
+/// @param {list} $list - The list to convert
+///
+/// @return {list} - The modified list with comma separation.
+///
+/// @example scss
+///   $foo: to-comma-list( 10 true 'foo' );
+///     // => 10, true, 'foo'
+///   $bar: to-comma-list( (10, true, 'foo') );
+///     // => 10, true, 'foo'
+///   $baz: to-comma-list(10);
+///     // => (10,)
+///   type-of($baz);
+///     // => 'list'
+///   list-separator($baz)
+///     // => 'comma'
+///
+/// @access public
+/// @since 0.1.0
+
+@function to-comma-list( $list )
+{
+  @return set-list-separator($list, 'comma');
+}
+
+// =to-comma-list( $list )
+// -----------------------------------------------------------------------------
+/// Converts a list into a space-separated list. If the list is already space-
+/// separated, then it will be returned as is.
+///
+/// @param {list} $list - The list to convert
+///
+/// @return {list} - The modified list with space separation.
+///
+/// @example scss
+///   $foo: to-space-list( (10, true, 'foo') );
+///     // => 10 true 'foo'
+///   $bar: to-space-list( (10, true, 'foo') );
+///     // => 10 true 'foo'
+///   $baz: to-space-list(10);
+///     // => (10)
+///   type-of($baz);
+///     // => 'list'
+///   list-separator($baz)
+///     // => 'space'
+///
+/// @access public
+/// @since 0.1.0
+
+@function to-space-list( $list )
+{
+  @return set-list-separator($list, 'space');
+}
+
+// =switch-list-separator( $list )
+// -----------------------------------------------------------------------------
+/// Changes the separator of a given list, from 'space' to 'comma', and from
+/// 'comma' to space.
+/// **Note**: simple values are considered to be space-separated lists, as for
+/// all native sass list functions.
+/// **Note**: map values are considered to be comma-separated lists, as for
+/// all native sass list functions.
+///
+/// @param {list} $list - The list on which to switch separator.
+///
+/// @return {list} - The space-separated version of `$list` if it is comma-separated, and vice-versa.
+///
+/// @example scss
+///   $foo: switch-list-separator(10 true 'foo');
+///     // => 10, true 'foo'
+///   $bar: switch-list-separator((10, true, 'foo'));
+///     // => 10 true 'foo'
+///   $baz: switch-list-separator(false);
+///     // => (false,)
+///   type-of($baz);
+///     // => 'list'
+///   list-separator($baz)
+///     // => 'comma'
+///
+/// @access public
+/// @since 0.1.0
+
+@function switch-list-separator( $list )
+{
+  @return if(list-separator($list) == 'comma', to-space-list($list), to-comma-list($list));
+}
+
+// =switch-separator( $list )
+// -----------------------------------------------------------------------------
+/// @alias switch-list-separator
+///
+/// @access public
+/// @since 0.1.0
+
+@function switch-separator( $list )
+{
+  @return switch-list-separator($list);
+}