sass-aleksi 0.1.2

data/stylesheets/aleksi/math/_subtract.scss

@@ -0,0 +1,66 @@
+// =============================================================================
+// =ALEKSI - SUBTRACT
+// =============================================================================
+////
+//// @group aleksi-math
+//// @author [Yoannis Jamar](http://yoannis.me)
+
+@import "SassyLists";
+@import "aleksi/general/throw";
+@import "aleksi/general/is-of-type";
+
+// =subtract( $terms... )
+// -----------------------------------------------------------------------------
+/// Calculates the difference between two or more numbers. Usefull when relying
+/// on `call()`, `walk()` or `apply()` for mathematical operations.
+/// **Note**: passing more then 2 arguments will subtract them successively.
+/// **Note**: if one of the terms is not a number, it will return `null`.
+///
+/// @param {arglist} $terms... - The operators in the subtraction.
+///
+/// @return {number|null} - The difference resulting from subtracting `$terms`.
+/// @throw Warning if one of the terms is not a number.
+///
+/// @example scss
+///   $foo: subtract(10, 5);
+///     // => 5
+///   $bar: subtract(10, 'hello')
+///     // => null
+///   $baz: subtract(10 5, 3)
+///     // => null
+///   $wiz: subtract(10, 5, 3)
+///     // => 2
+///
+/// @access public
+/// @since 0.1.0
+
+@function subtract( $terms... )
+{
+  @if not sl-every($terms, 'is-of-type', 'number') {
+    @return throw-warning('subtract():: all $terms must be numbers — returning null.');
+  }
+
+  @if length($terms) < 2 {
+    @return thow-error('subtract():: wrong number of arguments, 1 instead of 2 or more.');
+  }
+
+  $diff: nth($terms, 1);
+
+  @each $term in sl-slice($terms, 2) {
+    $diff: $diff - $term;
+  }
+
+  @return $diff;
+}
+
+// =diff( $terms... )
+// -----------------------------------------------------------------------------
+/// @alias subtract
+///
+/// @access public
+/// @since 0.1.0
+
+@function diff( $terms... )
+{
+  @return subtract($terms...);
+}

data/stylesheets/aleksi/sides/_output-sides.scss

@@ -0,0 +1,71 @@
+// =============================================================================
+// =ALEKSI - SIDE-PROPERTY
+// =============================================================================
+
+@import "aleksi/config";
+@import "aleksi/general/css-rule";
+@import "aleksi/sides/side-value";
+@import "aleksi/sides/reduce-sides";
+
+// =output-sides( $property, $values[, $important ])
+// -----------------------------------------------------------------------------
+/// Output a CSS property for a side-list value. The keyword 'offset' is
+/// accepted to output the 'top', 'right', 'bottom' and 'left'.
+///
+/// @param {property} $name - The CSS property name to output.
+/// @param {list} $values - The sides-list describing the property's values.
+/// @param {bool} $important [false] - Whether to add the '!imporant' flag.
+///
+/// @example scss - SCSS stylesheet
+///   .foo {
+///     position: absolute;
+///     @include output-sides('offset', 10px null null 10px);
+///     @include output-sides('margin', 10px null 1em);
+///     @include output-sides('padding', 0.5em 5%);
+///   }
+///
+/// @example css - CSS output
+///   .foo {
+///     position: absolute;
+///     top: 10px;
+///     left: 10px;
+///     margin-top: 10px;
+///     margin-bottom: 1em;
+///     padding: 0.5em 5%;
+///   }
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin output-sides( $property, $values, $important: false )
+{
+  // output separate property if setting offset or if one side
+  // should be omitted
+  @if $property == 'offset' or sl-contain($values, null) {
+    @each $side in const('CSS_SIDES') {
+      // append the side to the property name, or use the side only for offsets
+      $prop: if($property == 'offset', $side, '#{$property}-#{$side}');
+      // select the side's value from the list of values
+      $val: side-value($values, $side);
+
+      @include css-rule($prop, $val, $important);
+    }
+  }
+
+  // output shorthand otherwise
+  @else {
+    @include css-rule($property, reduce-sides($values), $important);
+  }
+}
+
+// =sides( $property, $values[, $important ])
+// -----------------------------------------------------------------------------
+/// @alias output-sides
+///
+/// @access public
+/// @since 0.1.0
+
+@mixin sides( $property, $values, $important: false )
+{
+  @include output-sides($property, $values, $important);
+}

data/stylesheets/aleksi/sides/_reduce-sides.scss

@@ -0,0 +1,74 @@
+// =============================================================================
+// =ALEKSI - REDUCE-SIDES-LIST
+// =============================================================================
+
+@import "SassyLists";
+@import "aleksi/general/throw";
+@import "aleksi/lists/get-nth";
+
+// =reduce-sides-list( $list )
+// -----------------------------------------------------------------------------
+/// Reduces a sides-list to its most compact form.
+///
+/// @param {list} $list - The sides-list to reduce.
+///
+/// @return {list} - The reduced version of $list.
+/// @throw Error if $list has more then 4 items.
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'reduce-sides-list' function
+
+@function reduce-sides-list( $list )
+{
+  $l: length($list);
+
+  @if $l > 4 {
+    @return throw-error("reduce-sides-list():: $list #{inspect($list)} is not a valid sides-list. Sides-lists can only have 1 to 4 items.");
+  }
+
+  // OPTIMIZATION: single-items can't be reduces
+  @if $l == 1 {
+    @return $list;
+  }
+
+  // CAUTION: don't remove 3rd unless 4th can be removed as well,
+  // and don't remove 3rd unless 2nd can be removed as well otherwise
+  // values would be attributed to wrong sides.
+  $first: nth($list, 1);
+  $second: get-nth($list, 2);
+  $third: get-nth($list, 3);
+  $fourth: get-nth($list, 4);
+
+  @if $l == 4 {
+    @if $fourth == $second {
+      @return reduce-sides-list(sl-without($list, 4));
+    }
+  }
+
+  @else if $l == 3 {
+    @if $third == $first {
+      @return reduce-sides-list(sl-without($list, 3));
+    }
+  }
+
+  @else if $l == 2 {
+    @return if($second == $first, $first, $list);
+  }
+
+  // no items to remove
+  @return $list;
+}
+
+// =reduce-sides( $list )
+// -----------------------------------------------------------------------------
+/// @alias reduce-sides-list
+///
+/// @access public
+/// @since 0.1.0
+
+@function reduce-sides( $list )
+{
+  @return reduce-sides-list( $list );
+}

data/stylesheets/aleksi/sides/_side-name.scss

@@ -0,0 +1,48 @@
+// =============================================================================
+// =ALEKSI - SIDE-NAME
+// =============================================================================
+
+@import "aleksi/config";
+@import "aleksi/config/constants";
+@import "aleksi/general/throw";
+
+// =side-name( $index )
+// -----------------------------------------------------------------------------
+/// Retreives the name of side corresponding to a given index in the ordered
+/// list of CSS sides.
+///
+/// @param {number} $index - The index of the side to retreive.
+///
+/// @return {string} - The name of the CSS side corresponding to $index.
+/// @throw Error if $index is not an integer
+/// @throw Error if $index is out of scope.
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'side-name' function
+
+@function side-name( $index )
+{
+  @if not is-int($index) {
+    @return throw-error('side-for-index():: $index must be an integer. Was #{inspect($index)}.');
+  }
+
+  @if $i > 4 {
+    @return throw-error('side-for-index():: $index #{inspect($index)} out of scope. Should be between 1 and 4.');
+  }
+
+  @return nth(const('CSS_SIDES'), $index);
+}
+
+// =nth-side( $index )
+// -----------------------------------------------------------------------------
+/// @alias side-name
+///
+/// @access public
+/// @since 0.1.0
+
+@function nth-side( $index )
+{
+  @return side-name($index);
+}

data/stylesheets/aleksi/sides/_side-value.scss

@@ -0,0 +1,83 @@
+// =============================================================================
+// =ALEKSI - SIDES-LIST
+// =============================================================================
+
+@import "SassyLists";
+@import "aleksi/config";
+@import "aleksi/config/constants";
+@import "aleksi/general/throw";
+@import "aleksi/maps/is-map";
+
+// =get-side-value( $list, $side )
+// -----------------------------------------------------------------------------
+/// Retreives the value for the given side in a side-list.
+/// **Note**: Caution, if passed a map, it will be considered a single value
+/// inside a single item sides-list.
+///
+/// @param {list} $list - The side-list from which to fetch the value
+/// @param {string} $side - The name of the side to retreive in $list
+///
+/// @return {any} - The value corresponding to the asked in $list
+/// @throw Error if $side is not a valid side name.
+///
+/// @example scss
+///   $foo: get-side-value(10px 2em, 'left');
+///     // => 2em
+///   $bar: get-side-value(10px 2em, 'top');
+///     // => 10px
+///   $baz: get-side-value(10px 2em 20%, 'bottom');
+///     // => 20%
+///   $wiz: get-side-value(10px, 'right');
+///     // => 10px
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'get-side-value' function.
+
+@function get-side-value( $list, $side )
+{
+  @if type-of($side) != string or (not sl-contain(const('CSS_SIDES'), $side)) {
+    @return throw-error("side-list-value():: $side must be either 'top', 'right', 'bottom' or 'left'. Was #{inspect($side)}.");
+  }
+
+  // consider maps as single values inside a single item sides-list
+  @if is-map($list) {
+    @return $list;
+  }
+
+  $l: length($list);
+  $first: nth($list, 1);
+
+  @if $side == 'top' {
+    @return $first;
+  }
+
+  @else if $side == 'right' {
+    @return if($l >= 2, nth($list, 2), $first);
+  }
+
+  @else if $side == 'bottom' {
+    @return if($l >= 3, nth($list, 3), $first);
+  }
+
+  @else if $side == 'left' {
+    @return if($l >= 4, nth($list, 4), if($l >= 2, nth($list, 2), $first));
+  }
+
+  @else {
+    @return throw-error('side-list-value():: $side is must be either');
+  }
+}
+
+// =side-value( $list, $side )
+// -----------------------------------------------------------------------------
+/// @alias get-side-value
+///
+/// @access public
+/// @since 0.1.0
+
+@function side-value( $list, $side )
+{
+  @return get-side-value($list, $side);
+}

data/stylesheets/aleksi/sides/_sides-shorthand.scss

@@ -0,0 +1,64 @@
+// =============================================================================
+// =ALEKSI - SIDES-FOR-KEYWORD
+// =============================================================================
+
+// =sides-shorthand( $side, $value )
+// -----------------------------------------------------------------------------
+/// Converts a value into a shorthan sides-list based on a given keyword.
+/// Recognized keywords are 'all', 'ends', 'sides', 'top', 'right', 'bottom' and
+/// 'left'.
+///
+/// @param {string} $side - Keyword to use to create the shorthand sides-list
+/// @param {any} $value - The value to set in the resulting shortand sides-list
+///
+/// @return {list} - Shorthand sides-list containing $value.
+/// @throw Warning if $side is not a recognized sides-list keyword.
+///
+/// @example scss
+///   $foo: sides-for-keyword('left', 10px);
+///     // => null null null 10px
+///   $bar: sides-for-keyword('all', 10px);
+///     // => 10px
+///   $baz: sides-for-keyword('ends', 10px);
+///     // => 10px null
+///   $wiz: sides-for-keyword('sides', 10px);
+///     // => null 10px
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'sides-shorthand' function
+
+@function sides-shorthand( $side, $value )
+{
+  @if $side == 'all' {
+    @return $value;
+  }
+
+  @else if $side == 'ends' {
+    @return $value null;
+  }
+
+  @else if $side == 'sides' {
+    @return null $value;
+  }
+
+  @else if $side == 'top' {
+    @return $value null null;
+  }
+
+  @else if $side == 'right' {
+    @return null $value null null;
+  }
+
+  @else if $side == 'bottom' {
+    @return null null $value;
+  }
+
+  @else if $side == 'left' {
+    @return null null null $value;
+  }
+
+  @return throw-error("sides-for-keyword():: keyword #{inspect($side)} is"
+    + " not a recognized keyword for sides-lists. Returning `null`.");
+}

data/stylesheets/aleksi/sides/_to-sides-list.scss

@@ -0,0 +1,63 @@
+// =============================================================================
+// =ALEKSI - TO-SIDES-LIST
+// =============================================================================
+
+@import "SassyLists";
+@import "aleksi/config";
+@import "aleksi/config/constants";
+@import "aleksi/general/is-of-type";
+@import "aleksi/general/throw";
+@import "aleksi/lists/contained-in";
+@import "aleksi/sides/reduce-sides";
+
+// =sides-map-to-list( $map[, $reduce ])
+// -----------------------------------------------------------------------------
+/// Converts a map of side, value pairs into a sides-list, and optionally
+/// reduces the result.
+///
+/// @param {map} $map - The map to convert into a sides-list
+/// @param {bool} $reduce [false] - Whether to reduce the resulting sides-list
+///
+/// @return {list} - The sides-list with values found in $map, in correct order.
+/// @throw Error if $map is not a map.
+/// @throw Warning if $map does not define a key, value pair for every CSS side.
+///
+/// @example scss
+///   $bar: sides-map-to-list('left': 2em, 'right': 2em, 'top': 10px, 'bottom': 5%);
+///     // => 10px 2em 5% 2em
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'sides-map-to-list' function.
+
+@function sides-map-to-list( $map, $reduce: false )
+{
+  $list: ();
+
+  @if not is-of-type($map, 'map') {
+    @return throw-error('sides-map-to-sides-list():: $map must be a map. Was #{inspect($map)}.');
+  }
+
+  @if not sl-some(map-keys($map), 'contained-in', const('CSS_SIDES')) {
+    @return throw-warnig('sides-map-to-sides-list():: $map does not contain any CSS side, value pair.');
+  }
+
+  @each $side in const('CSS_SIDES') {
+    $list: append($list, map-get($map, $side));
+  }
+
+  @return if($reduce, reduce-sides-list($list), $list);
+}
+
+// =to-sides-list( $map )
+// -----------------------------------------------------------------------------
+/// @alias sides-map-to-list
+///
+/// @access public
+/// @since 0.1.0
+
+@function to-sides-list( $map )
+{
+  @return sides-map-to-list($map);
+}

data/stylesheets/aleksi/sides/_to-sides-map.scss

@@ -0,0 +1,57 @@
+// =============================================================================
+// =ALEKSI - TO-SIDES-MAP
+// =============================================================================
+
+@import "sassy-maps";
+@import "aleksi/config";
+@import "aleksi/config/constants";
+@import "aleksi/general/throw";
+
+// =sides-list-to-map( $list )
+// -----------------------------------------------------------------------------
+/// Converts a given side-list to a map pairing each side with its corresponding
+/// value. If the list has more then 4 items, it will ignore additional items.
+/// **Note**: sides-maps can not be reduced, otherwise a `null` value could
+/// falsely get attributed to a side by using `map-get()`.
+///
+/// @param {list} $name - The side-list to convert.
+///
+/// @return {map} - A map pairing each CSS side with the value found in $list.
+/// @throw Warning If $list has more then 4 items.
+///
+/// @example scss
+///   $foo: sides-list-to-map(10px 2em 5%);
+///     // => ('top': 10px, 'right': 2em, 'bottom': 5%, 'left': 2em)
+///
+/// @access public
+/// @since 0.1.0
+///
+/// @todo Unit test the 'sides-list-to-map' function.
+
+@function sides-list-to-map( $list )
+{
+  $l: length($list);
+  $map: ();
+
+  @if $l >= 4 {
+    $w: throw-warning('sides-list-to-map():: $list has more then 4 items. Items 5 and up are being ignored.');
+  }
+
+  @each $side in const('CSS_SIDES') {
+    $map: map-set($map, $side, side-value($list, $side));
+  }
+
+  @return $map;
+}
+
+// =to-sides-map( $list )
+// -----------------------------------------------------------------------------
+/// @alias sides-list-to-map
+///
+/// @access public
+/// @since 0.1.0
+
+@function to-sides-map( $list )
+{
+  @return sides-list-to-map( $list );
+}