From 70fbd652bdf9d07c24e2c1c05ee861865a1af45a Mon Sep 17 00:00:00 2001 From: zgabievi Date: Sat, 12 Mar 2016 18:23:02 +0400 Subject: [PATCH] Well Documented --- .gitignore | 2 - _bem.scss | 59 +---- _config.scss | 113 +++++++++ bower.json | 2 +- functions/_all.scss | 15 ++ functions/_bem-index.scss | 35 ++- functions/_explode.scss | 12 +- functions/_get-block.scss | 17 +- functions/_has-state.scss | 19 +- functions/_implode.scss | 32 +++ functions/_is-block.scss | 15 +- functions/_is-element.scss | 15 +- functions/_is-modifier.scss | 15 +- functions/_math-min.scss | 13 +- functions/_to-string.scss | 21 -- helpers/_all.scss | 18 ++ helpers/_block-selector.scss | 16 +- helpers/_component-selector.scss | 21 +- helpers/_element-selector.scss | 28 ++- helpers/_hack-selector.scss | 25 +- helpers/_modifier-selector.scss | 22 +- helpers/_object-selector.scss | 21 +- helpers/_relations-selector.scss | 53 +++- helpers/_scope-selector.scss | 21 +- helpers/_state-selector.scss | 25 +- helpers/_test-selector.scss | 21 +- helpers/_theme-selector.scss | 21 +- helpers/_utility-selector.scss | 21 +- mixins/_all.scss | 21 ++ mixins/_block.scss | 33 ++- mixins/_component.scss | 51 ++-- mixins/_element.scss | 34 +++ mixins/_hack.scss | 50 ++-- mixins/_modifier.scss | 34 +++ mixins/_object.scss | 50 ++-- mixins/_parse.scss | 24 +- mixins/_pseudo.scss | 86 +++++++ mixins/_relations.scss | 80 ++++++ mixins/_scope.scss | 48 +++- mixins/_state.scss | 49 ++-- mixins/_states.scss | 100 ++++++++ mixins/_test.scss | 50 ++-- mixins/_theme.scss | 48 +++- mixins/_utility.scss | 51 ++-- package.json | 2 +- tests/style.scss | 410 ------------------------------- 46 files changed, 1218 insertions(+), 701 deletions(-) create mode 100644 _config.scss create mode 100644 functions/_all.scss create mode 100644 functions/_implode.scss delete mode 100644 functions/_to-string.scss create mode 100644 helpers/_all.scss create mode 100644 mixins/_all.scss delete mode 100644 tests/style.scss diff --git a/.gitignore b/.gitignore index b928283..29fd686 100644 --- a/.gitignore +++ b/.gitignore @@ -2,8 +2,6 @@ .sass-cache node_modules -gulpfile.js -config.json /style.scss /style.css diff --git a/_bem.scss b/_bem.scss index eaa2877..8a18c37 100644 --- a/_bem.scss +++ b/_bem.scss @@ -1,51 +1,16 @@ -$bem: ( - element: '__', - modifier: '--', - state: '-' -) !default; +// SASS-BEM 2.4.0 +// http://sass-bem.zgabievi.io/ +// Copyright 2016 Zura Gabievi. +// MIT License -$bem-debug: false !default; +// Configuration +@import "config"; -// functions -@import "functions/bem-index"; -@import "functions/get-block"; -@import "functions/has-state"; -@import "functions/is-modifier"; -@import "functions/is-element"; -@import "functions/is-block"; -@import "functions/math-min"; -@import "functions/explode"; -@import "functions/to-string"; +// Functions +@import "functions/all"; -// selectors -@import "helpers/block-selector"; -@import "helpers/element-selector"; -@import "helpers/modifier-selector"; -@import "helpers/relations-selector"; -@import "helpers/object-selector"; -@import "helpers/component-selector"; -@import "helpers/utility-selector"; -@import "helpers/theme-selector"; -@import "helpers/scope-selector"; -@import "helpers/state-selector"; -@import "helpers/hack-selector"; -@import "helpers/test-selector"; +// Helpers +@import "helpers/all"; -// mixins -@import "mixins/block"; -@import "mixins/element"; -@import "mixins/modifier"; -@import "mixins/relations"; -@import "mixins/states"; -@import "mixins/pseudo"; -@import "mixins/parse"; - -// oocss -@import "mixins/object"; -@import "mixins/component"; -@import "mixins/utility"; -@import "mixins/theme"; -@import "mixins/scope"; -@import "mixins/state"; -@import "mixins/hack"; -@import "mixins/test"; \ No newline at end of file +// Mixins +@import "mixins/all"; \ No newline at end of file diff --git a/_config.scss b/_config.scss new file mode 100644 index 0000000..eaa8bda --- /dev/null +++ b/_config.scss @@ -0,0 +1,113 @@ +@charset "UTF-8"; + +/// Default sass-bem configuration settings. +/// +/// @type map +/// +/// @prop {boolean} debug [false] - Turn debug mode on/off. To get outlines on selectors. +/// +/// @prop {boolean} separator.element [__] - Element separator from parent block. +/// +/// @prop {boolean} separator.modifier [--] - Modifier separator from parent block. +/// +/// @prop {boolean} separator.state [-] - States separator from parent block. +/// +/// @prop {boolean} namespace.component [c] - Component selector namespace. +/// +/// @prop {boolean} namespace.hack [_] - Hack selector namespace. +/// +/// @prop {boolean} namespace.object [o] - Object selector namespace. +/// +/// @prop {boolean} namespace.scope [s] - Scope selector namespace. +/// +/// @prop {boolean} namespace.test [qa] - Test selector namespace. +/// +/// @prop {boolean} namespace.theme [t] - Theme selector namespace. +/// +/// @prop {boolean} namespace.utility [u] - Utility selector namespace. +/// +/// @access public + +$bem: ( + 'debug': false, + 'separator': ( + 'element': "__", + 'modifier': "--", + 'state': "-", + ), + 'namespace': ( + 'component': "c", + 'hack': "_", + 'object': "o", + 'scope': "s", + 'test': "qa", + 'theme': "t", + 'utility': "u", + ) +) !default; + +/// Turn debug mode on/off. To get outlines on selectors. +/// +/// @type Bool + +$bem-debug: map-get($bem, 'debug') !default; + +/// Element separator from parent block. +/// +/// @type String + +$bem-element-separator: map-get(map-get($bem, 'separator'), 'element') !default; + +/// Modifier separator from parent block. +/// +/// @type String + +$bem-modifier-separator: map-get(map-get($bem, 'separator'), 'modifier') !default; + +/// States separator from parent block. +/// +/// @type String + +$bem-state-separator: map-get(map-get($bem, 'separator'), 'state') !default; + +/// Component selector namespace. +/// +/// @type String + +$bem-component-namespace: map-get(map-get($bem, 'namespace'), 'component') !default; + +/// Hack selector namespace. +/// +/// @type String + +$bem-hack-namespace: map-get(map-get($bem, 'namespace'), 'hack') !default; + +/// Object selector namespace. +/// +/// @type String + +$bem-object-namespace: map-get(map-get($bem, 'namespace'), 'object') !default; + +/// Scope selector namespace. +/// +/// @type String + +$bem-scope-namespace: map-get(map-get($bem, 'namespace'), 'scope') !default; + +/// Test selector namespace. +/// +/// @type String + +$bem-test-namespace: map-get(map-get($bem, 'namespace'), 'test') !default; + +/// Theme selector namespace. +/// +/// @type String + +$bem-theme-namespace: map-get(map-get($bem, 'namespace'), 'theme') !default; + +/// Utility selector namespace. +/// +/// @type String + +$bem-utility-namespace: map-get(map-get($bem, 'namespace'), 'utility') !default; \ No newline at end of file diff --git a/bower.json b/bower.json index e316d7c..15fe1a6 100644 --- a/bower.json +++ b/bower.json @@ -1,6 +1,6 @@ { "name": "sass-bem", - "version": "2.3.3", + "version": "2.4.0", "main": "_bem.scss", "description": "Collection of BEM Mixins & Helpers", "authors": [ diff --git a/functions/_all.scss b/functions/_all.scss new file mode 100644 index 0000000..6dd7ea7 --- /dev/null +++ b/functions/_all.scss @@ -0,0 +1,15 @@ +//// +/// @group Functions +/// +/// @access private +//// + +@import "bem-index"; +@import "get-block"; +@import "has-state"; +@import "is-modifier"; +@import "is-element"; +@import "is-block"; +@import "math-min"; +@import "explode"; +@import "implode"; \ No newline at end of file diff --git a/functions/_bem-index.scss b/functions/_bem-index.scss index 96d7763..ba3b573 100644 --- a/functions/_bem-index.scss +++ b/functions/_bem-index.scss @@ -1,31 +1,44 @@ -// +@charset "UTF-8"; + +/// Get index of separator. +/// +/// @access private +/// +/// @param {String} $string - Name of selector, where we should find separator +/// +/// @requires math-min +/// @requires $bem-element-separator +/// @requires $bem-modifier-separator +/// +/// @returns {Number} - Index of separators + @function bem-index($string) { $e_index: null; $m_index: null; // - @if (str-index($string, unquote("#{map-get($bem, element)}")) != null) { - $e_index: str-index($string, unquote("#{map-get($bem, element)}")); + @if (str-index($string, unquote("#{$bem-element-separator}")) != null) { + $e_index: str-index($string, unquote("#{$bem-element-separator}")); } // - @if (str-index($string, unquote("#{map-get($bem, modifier)}")) != null) { - $m_index: str-index($string, unquote("#{map-get($bem, modifier)}")); + @if (str-index($string, unquote("#{$bem-modifier-separator}")) != null) { + $m_index: str-index($string, unquote("#{$bem-modifier-separator}")); } // - @if (str-index($string, unquote(".is#{map-get($bem, state)}")) != null) { - $m_index: str-index($string, unquote(".is#{map-get($bem, state)}")); + @if (str-index($string, unquote(".is#{$bem-modifier-separator}")) != null) { + $m_index: str-index($string, unquote(".is#{$bem-state-separator}")); } // - @if (str-index($string, unquote(".js#{map-get($bem, state)}")) != null) { - $m_index: str-index($string, unquote(".js#{map-get($bem, state)}")); + @if (str-index($string, unquote(".js#{$bem-modifier-separator}")) != null) { + $m_index: str-index($string, unquote(".js#{$bem-state-separator}")); } // - @if (str-index($string, unquote(".has#{map-get($bem, state)}")) != null) { - $m_index: str-index($string, unquote(".has#{map-get($bem, state)}")); + @if (str-index($string, unquote(".has#{$bem-modifier-separator}")) != null) { + $m_index: str-index($string, unquote(".has#{$bem-state-separator}")); } // diff --git a/functions/_explode.scss b/functions/_explode.scss index 7662be1..76e740f 100644 --- a/functions/_explode.scss +++ b/functions/_explode.scss @@ -1,4 +1,14 @@ -// +@charset "UTF-8"; + +/// Explode string to get list of strings. +/// +/// @access private +/// +/// @param {String} $string - String which should be exploded +/// @param {String} $separator - Separator which will explode string to pieces +/// +/// @returns {List} - List of exploded string + @function explode($string, $separator) { $list: (); $length: str-length($string); diff --git a/functions/_get-block.scss b/functions/_get-block.scss index ce521ff..c29d0cb 100644 --- a/functions/_get-block.scss +++ b/functions/_get-block.scss @@ -1,4 +1,15 @@ -// -@function get-block($element) { - @return str-slice($element, 2, bem-index($element) - 1); +@charset "UTF-8"; + +/// Get block element from selector. +/// +/// @access private +/// +/// @param {String} $selector - Selector, from where we will take block +/// +/// @requires bem-index +/// +/// @returns {String} - Block element + +@function get-block($selector) { + @return str-slice($selector, 2, bem-index($selector) - 1); } \ No newline at end of file diff --git a/functions/_has-state.scss b/functions/_has-state.scss index 2eb231b..be71804 100644 --- a/functions/_has-state.scss +++ b/functions/_has-state.scss @@ -1,8 +1,19 @@ -// +@charset "UTF-8"; + +/// Check if selector contains state. +/// +/// @access private +/// +/// @param {String} $selector - Selector, which we will check for state +/// +/// @requires $bem-state-separator +/// +/// @returns {Bool} + @function has-state($selector) { - $separator_is: unquote(".is#{map-get($bem, state)}"); - $separator_js: unquote(".js#{map-get($bem, state)}"); - $separator_has: unquote(".has#{map-get($bem, state)}"); + $separator_is: unquote(".is#{$bem-state-separator}"); + $separator_js: unquote(".js#{$bem-state-separator}"); + $separator_has: unquote(".has#{$bem-state-separator}"); @return str-index($selector, $separator_is) != null and str-index($selector, $separator_js) != null and str-index($selector, $separator_has) != null; } \ No newline at end of file diff --git a/functions/_implode.scss b/functions/_implode.scss new file mode 100644 index 0000000..b66034e --- /dev/null +++ b/functions/_implode.scss @@ -0,0 +1,32 @@ +@charset "UTF-8"; + +/// Implode list to get string. +/// +/// @access private +/// +/// @param {List} $list - List which will be imploded +/// @param {String} $glue [''] - Separator which will glue list +/// @param {Bool} $is-nested - List is nested or not +/// +/// @returns {String} - Imploded list + +@function implode($list, $glue: '', $is-nested: false) { + $result: null; + + // + @for $i from 1 through length($list) { + $e: nth($list, $i); + + // + @if type-of($e) == list { + $result: unquote("#{$result}#{implode($e, $glue, true)}"); + } + + // + @else { + $result: if($i != length($list) or $is-nested, unquote("#{$result}#{$e}#{$glue}"), unquote("#{$result}#{$e}")); + } + } + + @return $result; +} \ No newline at end of file diff --git a/functions/_is-block.scss b/functions/_is-block.scss index 5719557..ef12c8f 100644 --- a/functions/_is-block.scss +++ b/functions/_is-block.scss @@ -1,4 +1,17 @@ -// +@charset "UTF-8"; + +/// Check if selector is block. +/// +/// @access private +/// +/// @param {String} $selector - Selector, which we will check for block +/// +/// @requires is-element +/// @requires is-modifier +/// @requires has-state +/// +/// @returns {Bool} + @function is-block($selector) { @return (not is-element($selector) and not is-modifier($selector) and not has-state($selector)); } \ No newline at end of file diff --git a/functions/_is-element.scss b/functions/_is-element.scss index b2257d0..f97eca1 100644 --- a/functions/_is-element.scss +++ b/functions/_is-element.scss @@ -1,5 +1,16 @@ -// +@charset "UTF-8"; + +/// Check if selector is element. +/// +/// @access private +/// +/// @param {String} $selector - Selector, which we will check for element +/// +/// @requires $bem-element-separator +/// +/// @returns {Bool} + @function is-element($selector) { - $separator: unquote("#{map-get($bem, element)}"); + $separator: unquote("#{$bem-element-separator}"); @return str-index($selector, $separator) != null; } \ No newline at end of file diff --git a/functions/_is-modifier.scss b/functions/_is-modifier.scss index 95782b7..3138d3f 100644 --- a/functions/_is-modifier.scss +++ b/functions/_is-modifier.scss @@ -1,5 +1,16 @@ -// +@charset "UTF-8"; + +/// Check if selector is modifier. +/// +/// @access private +/// +/// @param {String} $selector - Selector, which we will check for modifier +/// +/// @requires $bem-modifier-separator +/// +/// @returns {Bool} + @function is-modifier($selector) { - $separator: unquote("#{map-get($bem, modifier)}"); + $separator: unquote("#{$bem-modifier-separator}"); @return str-index($selector, $separator) != null; } \ No newline at end of file diff --git a/functions/_math-min.scss b/functions/_math-min.scss index a33d1fe..8ffc482 100644 --- a/functions/_math-min.scss +++ b/functions/_math-min.scss @@ -1,4 +1,15 @@ -// +@charset "UTF-8"; + +/// Get minimum number from two of them, or get default. +/// +/// @access private +/// +/// @param {String} $a - First number to be checked +/// @param {String} $n - Second number to be checked +/// @param {String} $default - Default number to be returned if min wasn't found +/// +/// @returns {Number} - Minimum number from two of them + @function math-min($a, $b, $default) { $min: $default; diff --git a/functions/_to-string.scss b/functions/_to-string.scss deleted file mode 100644 index c7400fd..0000000 --- a/functions/_to-string.scss +++ /dev/null @@ -1,21 +0,0 @@ -// -@function to-string($list, $glue: '', $is-nested: false) { - $result: null; - - // - @for $i from 1 through length($list) { - $e: nth($list, $i); - - // - @if type-of($e) == list { - $result: unquote("#{$result}#{to-string($e, $glue, true)}"); - } - - // - @else { - $result: if($i != length($list) or $is-nested, unquote("#{$result}#{$e}#{$glue}"), unquote("#{$result}#{$e}")); - } - } - - @return $result; -} \ No newline at end of file diff --git a/helpers/_all.scss b/helpers/_all.scss new file mode 100644 index 0000000..61adff9 --- /dev/null +++ b/helpers/_all.scss @@ -0,0 +1,18 @@ +//// +/// @group Helpers +/// +/// @access private +//// + +@import "block-selector"; +@import "element-selector"; +@import "modifier-selector"; +@import "relations-selector"; +@import "object-selector"; +@import "component-selector"; +@import "utility-selector"; +@import "theme-selector"; +@import "scope-selector"; +@import "state-selector"; +@import "hack-selector"; +@import "test-selector"; \ No newline at end of file diff --git a/helpers/_block-selector.scss b/helpers/_block-selector.scss index 1df7ac5..a1dbcf2 100644 --- a/helpers/_block-selector.scss +++ b/helpers/_block-selector.scss @@ -1,9 +1,21 @@ -// +@charset "UTF-8"; + +/// Selector of block. +/// +/// @access private +/// +/// @param {String} $block - Name of block that will come after "." +/// +/// @returns {String} - .{block} +/// +/// @see {mixin} block + @function block-selector($block) { @return unquote(".#{$block}"); } -// +/// @alias block-selector + @function b-selector($block) { @return block-selector($block); } \ No newline at end of file diff --git a/helpers/_component-selector.scss b/helpers/_component-selector.scss index 01506e4..9d371a6 100644 --- a/helpers/_component-selector.scss +++ b/helpers/_component-selector.scss @@ -1,11 +1,22 @@ -$bem-component-namespace: c !default; +@charset "UTF-8"; -// -@function component-selector($component) { - @return unquote(".#{$bem-component-namespace}-#{$component}"); +/// Selector of component. +/// +/// @access private +/// +/// @param {String} $component - Name of component that will come after ".c-" +/// @param {String} $namespace - Namespace of component. +/// +/// @returns {String} - .c-{component} +/// +/// @see {mixin} component + +@function component-selector($component, $namespace) { + @return unquote(".#{$namespace}-#{$component}"); } -// +/// @alias component-selector + @function c-selector($component) { @return component-selector($component); } \ No newline at end of file diff --git a/helpers/_element-selector.scss b/helpers/_element-selector.scss index 0f663ad..f66722b 100644 --- a/helpers/_element-selector.scss +++ b/helpers/_element-selector.scss @@ -1,14 +1,29 @@ -// +@charset "UTF-8"; + +/// Selector of element. +/// +/// @access private +/// +/// @param {String} $element - Name of element that will come after ".{block}__" +/// +/// @requires get-block +/// @requires is-block +/// @requires $bem-element-separator +/// +/// @returns {String} - .{block}__{element} +/// +/// @see {mixin} element + @function element-selector($element) { $selector: ''; $parent: unquote("#{&}"); // @if (is-block($parent)) { - $selector: unquote("&#{map-get($bem, 'element')}#{$element}"); + $selector: unquote("&#{$bem-element-separator}#{$element}"); } @else { $block: get-block($parent); - $selector: unquote("& .#{$block}#{map-get($bem, 'element')}#{$element}"); + $selector: unquote("& .#{$block}#{$bem-element-separator}#{$element}"); } // @@ -21,10 +36,10 @@ // @if (is-block($parent)) { - $current: unquote("&#{map-get($bem, 'element')}#{$value}"); + $current: unquote("&#{$bem-element-separator}#{$value}"); } @else { $block: get-block($parent); - $current: unquote("& .#{$block}#{map-get($bem, 'element')}#{$value}"); + $current: unquote("& .#{$block}#{$bem-element-separator}#{$value}"); } // @@ -35,7 +50,8 @@ @return $selector; } -// +/// @alias element-selector + @function e-selector($element) { @return element-selector($element); } \ No newline at end of file diff --git a/helpers/_hack-selector.scss b/helpers/_hack-selector.scss index 140a950..696f44d 100644 --- a/helpers/_hack-selector.scss +++ b/helpers/_hack-selector.scss @@ -1,17 +1,22 @@ -$bem-hack-namespace: _ !default; +@charset "UTF-8"; -// -@function hack-selector($hack, $namespace: null) { - $selector: unquote(".#{$bem-hack-namespace}#{$hack}"); +/// Selector of hack. +/// +/// @access private +/// +/// @param {String} $hack - Name of hack that will come after "._" +/// @param {String} $namespace - Namespace of hack. +/// +/// @returns {String} - ._{hack} +/// +/// @see {mixin} hack - @if $namespace != null { - $selector: unquote(".#{$bem-hack-namespace}#{$namespace}-#{$hack}"); - } - - @return $selector; +@function hack-selector($hack, $namespace) { + @return unquote(".#{$namespace}#{$hack}"); } -// +/// @alias hack-selector + @function _-selector($hack) { @return hack-selector($hack, '_'); } \ No newline at end of file diff --git a/helpers/_modifier-selector.scss b/helpers/_modifier-selector.scss index df2dfb8..af0247c 100644 --- a/helpers/_modifier-selector.scss +++ b/helpers/_modifier-selector.scss @@ -1,6 +1,19 @@ -// +@charset "UTF-8"; + +/// Selector of modifier. +/// +/// @access private +/// +/// @param {String} $modifier - Name of modifier that will come after ".{block}--" +/// +/// @requires $bem-modifier-separator +/// +/// @returns {String} - .{block}--{modifier} +/// +/// @see {mixin} modifier + @function modifier-selector($modifier) { - $selector: unquote("&#{map-get($bem, "modifier")}#{$modifier}"); + $selector: unquote("&#{$bem-modifier-separator}#{$modifier}"); // @if (type-of($modifier) == 'list') { @@ -8,7 +21,7 @@ // @each $value in $modifier { - $current: unquote("&#{map-get($bem, 'modifier')}#{$value}"); + $current: unquote("&#{$bem-modifier-separator}#{$value}"); $selector: append($selector, $current, comma); } } @@ -16,7 +29,8 @@ @return $selector; } -// +/// @alias modifier-selector + @function m-selector($modifier) { @return modifier-selector($modifier); } \ No newline at end of file diff --git a/helpers/_object-selector.scss b/helpers/_object-selector.scss index efe7903..f0b737b 100644 --- a/helpers/_object-selector.scss +++ b/helpers/_object-selector.scss @@ -1,11 +1,22 @@ -$bem-object-namespace: o !default; +@charset "UTF-8"; -// -@function object-selector($object) { - @return unquote(".#{$bem-object-namespace}-#{$object}"); +/// Selector of object. +/// +/// @access private +/// +/// @param {String} $object - Name of object that will come after ".o-" +/// @param {String} $namespace - Namespace of object. +/// +/// @returns {String} - .o-{object} +/// +/// @see {mixin} object + +@function object-selector($object, $namespace) { + @return unquote(".#{$namespace}-#{$object}"); } -// +/// @alias object-selector + @function o-selector($object) { @return object-selector($object); } \ No newline at end of file diff --git a/helpers/_relations-selector.scss b/helpers/_relations-selector.scss index e8eba67..4cbee21 100644 --- a/helpers/_relations-selector.scss +++ b/helpers/_relations-selector.scss @@ -1,18 +1,47 @@ -// +@charset "UTF-8"; + +/// Selector of at relationship. +/// +/// @param {String} $modifier - Name of modifier that will come after ".{block}--" +/// +/// @requires get-block +/// @requires $bem-modifier-separator +/// +/// @returns {String} - .{block}--{modifier} +/// +/// @see {mixin} at + @function at-selector($modifier) { $block: get-block(unquote("#{&}")); - @return unquote(".#{$block}#{map-get($bem, 'modifier')}#{$modifier} &"); + @return unquote(".#{$block}#{$bem-modifier-separator}#{$modifier} &"); } -// +/// Selector of with relationship. +/// +/// @param {String} $element - Name of element that will come after ".{block}__" +/// +/// @requires get-block +/// @requires $bem-element-separator +/// +/// @returns {String} - & + .{block}__{element} +/// +/// @see {mixin} with + @function with-selector($element) { $block: get-block(unquote("#{&}")); - @return unquote("& + .#{$block}#{map-get($bem, 'element')}#{$element}"); + @return unquote("& + .#{$block}#{$bem-element-separator}#{$element}"); } -// +/// Selector of duo relationship. +/// +/// @requires explode +/// +/// @returns {String} - & + & +/// +/// @see {mixin} duo + @function duo-selector() { $list: explode(unquote("#{&}"), ' '); $last: nth($list, length($list)); @@ -20,9 +49,19 @@ @return unquote("& + #{$last}"); } -// +/// Selector of while relationship. +/// +/// @param {String} $modifier - Name of modifier that will come after ".{block}--" +/// +/// @requires get-block +/// @requires $bem-element-separator +/// +/// @returns {String} - .{block}--{modifier} +/// +/// @see {mixin} while + @function while-selector($modifier) { $block: get-block(unquote("#{&}")); - @return unquote("&.#{$block}#{map-get($bem, 'modifier')}#{$modifier}"); + @return unquote("&.#{$block}#{$bem-modifier-separator}#{$modifier}"); } \ No newline at end of file diff --git a/helpers/_scope-selector.scss b/helpers/_scope-selector.scss index f763453..67226b6 100644 --- a/helpers/_scope-selector.scss +++ b/helpers/_scope-selector.scss @@ -1,11 +1,22 @@ -$bem-scope-namespace: s !default; +@charset "UTF-8"; -// -@function scope-selector($scope) { - @return unquote(".#{$bem-scope-namespace}-#{$scope}"); +/// Selector of scope. +/// +/// @access private +/// +/// @param {String} $scope - Name of scope that will come after ".s-" +/// @param {String} $namespace - Namespace of scope. +/// +/// @returns {String} - .s-{scope} +/// +/// @see {mixin} scope + +@function scope-selector($scope, $namespace) { + @return unquote(".#{$namespace}-#{$scope}"); } -// +/// @alias scope-selector + @function s-selector($scope) { @return scope-selector($scope); } \ No newline at end of file diff --git a/helpers/_state-selector.scss b/helpers/_state-selector.scss index 03ae3e6..c53eaec 100644 --- a/helpers/_state-selector.scss +++ b/helpers/_state-selector.scss @@ -1,8 +1,18 @@ -$bem-state-namespace: is !default; +@charset "UTF-8"; + +/// Selector of state. +/// +/// @access private +/// +/// @param {String} $state - Name of state that will come after ".[is|has|js]-" +/// @param {String} $namespace [null] - Namespace of state. [is|has|js] +/// +/// @returns {String} - .[is|has|js]-{state} +/// +/// @see {mixin} state -// @function state-selector($state, $namespace: null) { - $selector: unquote("&.#{$bem-state-namespace}#{$state}"); + $selector: unquote("&.#{$state}"); // @if $namespace != null { @@ -12,17 +22,20 @@ $bem-state-namespace: is !default; @return $selector; } -// +/// @alias state-selector + @function is-selector($state) { @return state-selector($state, 'is'); } -// +/// @alias state-selector + @function has-selector($state) { @return state-selector($state, 'has'); } -// +/// @alias state-selector + @function js-selector($state) { @return state-selector($state, 'js'); } \ No newline at end of file diff --git a/helpers/_test-selector.scss b/helpers/_test-selector.scss index 918f4c2..3d7ebdf 100644 --- a/helpers/_test-selector.scss +++ b/helpers/_test-selector.scss @@ -1,11 +1,22 @@ -$bem-test-namespace: qa !default; +@charset "UTF-8"; -// -@function test-selector($test) { - @return unquote(".#{$bem-test-namespace}-#{$test}"); +/// Selector of test. +/// +/// @access private +/// +/// @param {String} $test - Name of test that will come after ".qa-" +/// @param {String} $namespace - Namespace of test. +/// +/// @returns {String} - .qa-{test} +/// +/// @see {mixin} test + +@function test-selector($test, $namespace) { + @return unquote(".#{$namespace}-#{$test}"); } -// +/// @alias test-selector + @function qa-selector($test) { @return test-selector($test); } \ No newline at end of file diff --git a/helpers/_theme-selector.scss b/helpers/_theme-selector.scss index 8a55a14..2a59579 100644 --- a/helpers/_theme-selector.scss +++ b/helpers/_theme-selector.scss @@ -1,11 +1,22 @@ -$bem-theme-namespace: t !default; +@charset "UTF-8"; -// -@function theme-selector($theme) { - @return unquote(".#{$bem-theme-namespace}-#{$theme}"); +/// Selector of theme. +/// +/// @access private +/// +/// @param {String} $theme - Name of theme that will come after ".t-" +/// @param {String} $namespace - Namespace of theme. +/// +/// @returns {String} - .t-{theme} +/// +/// @see {mixin} theme + +@function theme-selector($theme, $namespace) { + @return unquote(".#{$namespace}-#{$theme}"); } -// +/// @alias theme-selector + @function t-selector($theme) { @return theme-selector($theme); } \ No newline at end of file diff --git a/helpers/_utility-selector.scss b/helpers/_utility-selector.scss index 456e7ae..d7d10b8 100644 --- a/helpers/_utility-selector.scss +++ b/helpers/_utility-selector.scss @@ -1,11 +1,22 @@ -$bem-utility-namespace: u !default; +@charset "UTF-8"; -// -@function utility-selector($utility) { - @return unquote(".#{$bem-utility-namespace}-#{$utility}"); +/// Selector of utility. +/// +/// @access private +/// +/// @param {String} $utility - Name of utility that will come after ".u-" +/// @param {String} $namespace - Namespace of utility. +/// +/// @returns {String} - .u-{utility} +/// +/// @see {mixin} utility + +@function utility-selector($utility, $namespace) { + @return unquote(".#{$namespace}-#{$utility}"); } -// +/// @alias utility-selector + @function u-selector($utility) { @return utility-selector($utility); } \ No newline at end of file diff --git a/mixins/_all.scss b/mixins/_all.scss new file mode 100644 index 0000000..0cf4bd0 --- /dev/null +++ b/mixins/_all.scss @@ -0,0 +1,21 @@ +//// +/// @group Mixins +/// +/// @access public +//// + +@import "block"; +@import "element"; +@import "modifier"; +@import "relations"; +@import "states"; +@import "pseudo"; +@import "parse"; +@import "object"; +@import "component"; +@import "utility"; +@import "theme"; +@import "scope"; +@import "state"; +@import "hack"; +@import "test"; \ No newline at end of file diff --git a/mixins/_block.scss b/mixins/_block.scss index 2cace41..4a4b74f 100644 --- a/mixins/_block.scss +++ b/mixins/_block.scss @@ -1,6 +1,31 @@ -/** - * Format: .block[|] {} - */ +@charset "UTF-8"; + +/// Block selector that will be parent of some elements, modifiers, states... +/// +/// @param {String} $block - Name of block that will come after "." +/// +/// @example scss - Usage +/// @include block('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .list { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include b('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .list { +/// color: black; +/// } +/// +/// @requires {function} block-selector + @mixin block($block) { #{block-selector($block)} { @if $bem-debug == true { @@ -11,6 +36,8 @@ } } +/// @alias block + @mixin b($block) { @include block($block) { @content; diff --git a/mixins/_component.scss b/mixins/_component.scss index 21a1005..a11a189 100644 --- a/mixins/_component.scss +++ b/mixins/_component.scss @@ -1,16 +1,34 @@ -/** - * Signify that something is a Component. This - * is a concrete, implementation-specific piece - * of UI. All of the changes you make to its - * styles should be detectable in the context - * you’re currently looking at. Modifying - * these styles should be safe and have - * no side effects. - * - * Format: .c-component[|] {} - */ -@mixin component($component) { - #{component-selector($component)} { +@charset "UTF-8"; + +/// Signify that something is a Component. This is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you’re currently looking at. Modifying these styles should be safe and have no side effects. +/// +/// @param {String} $component - Name of component that will come after ".c-" +/// @param {String} $namespace [null] - Component element namespace. +/// +/// @example scss - Usage +/// @include component('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .c-list { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include c('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .c-list { +/// color: black; +/// } +/// +/// @requires {function} component-selector + +@mixin component($component, $namespace: $bem-component-namespace) { + #{component-selector($component, $namespace)} { @if $bem-debug == true { outline: 5px solid #00b8a9; } @@ -19,9 +37,10 @@ } } -// Shorthand -@mixin c($component) { - @include component($component) { +/// @alias component + +@mixin c($component, $namespace: $bem-component-namespace) { + @include component($component, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_element.scss b/mixins/_element.scss index 45e8479..a9494b1 100644 --- a/mixins/_element.scss +++ b/mixins/_element.scss @@ -1,3 +1,35 @@ +@charset "UTF-8"; + +/// Element selector, that is generated from parent block +/// +/// @param {String} $element - Name of element that will come after ".{block}__" +/// +/// @example scss - Usage +/// @include block('list') { +/// @include element('item') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list__item { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include b('list') { +/// @include e('item') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list__item { +/// color: black; +/// } +/// +/// @requires {function} element-selector + @mixin element($element) { @at-root { #{element-selector($element)} { @@ -10,6 +42,8 @@ } } +/// @alias element + @mixin e($element) { @include element($element) { @content; diff --git a/mixins/_hack.scss b/mixins/_hack.scss index 59886ea..ef1cdce 100644 --- a/mixins/_hack.scss +++ b/mixins/_hack.scss @@ -1,16 +1,33 @@ -/** - * Signify that this class is the worst of - * the worst—a hack! Sometimes, although - * incredibly rarely, we need to add a - * class in our markup in order to force - * something to work. If we do this, we - * need to let others know that this class - * is less than ideal, and hopefully temporary - * (i.e. do not bind onto this). - * - * Format: ._hack {} - */ -@mixin hack($hack, $namespace: null) { +@charset "UTF-8"; + +/// Signify that this class is the worst of the worst—a hack! Sometimes, although incredibly rarely, we need to add a class in our markup in order to force something to work. If we do this, we need to let others know that this class is less than ideal, and hopefully temporary (i.e. do not bind onto this). +/// +/// @param {String} $hack - Name of hack that will come after "._" +/// @param {String} $namespace [null] - Hack element namespace. +/// +/// @example scss - Usage +/// @include hack('clearfix') { +/// color: black; +/// } +/// +/// @example css - Output +/// ._clearfix { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include _('clearfix') { +/// color: black; +/// } +/// +/// @example css - Output +/// ._clearfix { +/// color: black; +/// } +/// +/// @requires {function} hack-selector + +@mixin hack($hack, $namespace: $bem-hack-namespace) { #{hack-selector($hack, $namespace)} { @if $bem-debug == true { outline: 5px solid #f33535; @@ -20,9 +37,10 @@ } } -// Shorthand -@mixin _($hack, $namespace: null) { - @include hack($hack, $namespace: null) { +/// @alias hack + +@mixin _($hack, $namespace: $bem-hack-namespace) { + @include hack($hack, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_modifier.scss b/mixins/_modifier.scss index 382fb7f..8adca8b 100644 --- a/mixins/_modifier.scss +++ b/mixins/_modifier.scss @@ -1,3 +1,35 @@ +@charset "UTF-8"; + +/// Modifier selector, that is generated from parent block +/// +/// @param {String} $modifier - Name of modifier that will come after ".{block}--" +/// +/// @example scss - Usage +/// @include block('list') { +/// @include modifier('inline') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list--inline { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include b('list') { +/// @include m('inline') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list--inline { +/// color: black; +/// } +/// +/// @requires {function} modifier-selector + @mixin modifier($modifier) { @at-root { #{modifier-selector($modifier)} { @@ -10,6 +42,8 @@ } } +/// @alias modifier + @mixin m($modifier) { @include modifier($modifier) { @content; diff --git a/mixins/_object.scss b/mixins/_object.scss index 4be0706..7f900ae 100644 --- a/mixins/_object.scss +++ b/mixins/_object.scss @@ -1,15 +1,34 @@ -/** - * Signify that something is an Object, and that it may - * be used in any number of unrelated contexts to the one - * you can currently see it in. Making modifications to - * these types of class could potentially have knock-on - * effects in a lot of other unrelated places. - * Tread carefully. - * - * Format: .o-object[|] {} - */ -@mixin object($object) { - #{object-selector($object)} { +@charset "UTF-8"; + +/// Signify that something is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in. Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places. Tread carefully. +/// +/// @param {String} $object - Name of object that will come after ".o-" +/// @param {String} $namespace [null] - Object element namespace. +/// +/// @example scss - Usage +/// @include object('button') { +/// color: black; +/// } +/// +/// @example css - Output +/// .o-button { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include o('button') { +/// color: black; +/// } +/// +/// @example css - Output +/// .o-button { +/// color: black; +/// } +/// +/// @requires {function} object-selector + +@mixin object($object, $namespace: $bem-object-namespace) { + #{object-selector($object, $namespace)} { @if $bem-debug == true { outline: 5px solid #9bcb3c; } @@ -18,9 +37,10 @@ } } -// Shorthand -@mixin o($object) { - @include object($object) { +/// @alias object + +@mixin o($object, $namespace: $bem-object-namespace) { + @include object($object, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_parse.scss b/mixins/_parse.scss index ebbaa64..fed5076 100644 --- a/mixins/_parse.scss +++ b/mixins/_parse.scss @@ -1,4 +1,24 @@ -// +@charset "UTF-8"; + +/// Parse multiple mixins, pseudo elements and other states. +/// +/// @param {String | List} $selectors - List or String of arguments, to generate selector. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include parse('&', 'm:inline', ':hover', '[disabled]') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list, .list--inline, .list:hover, .list[disabled] { +/// color: black; +/// } +/// +/// @requires {function} explode +/// @requires {function} implode + @mixin parse($selectors...) { $parent: unquote("#{&}"); $collection: (); @@ -47,7 +67,7 @@ // @at-root { - #{to-string($collection, ', ')} { + #{implode($collection, ', ')} { @content; } } diff --git a/mixins/_pseudo.scss b/mixins/_pseudo.scss index 7300c8e..4bb01e9 100644 --- a/mixins/_pseudo.scss +++ b/mixins/_pseudo.scss @@ -1,33 +1,119 @@ +@charset "UTF-8"; + +/// Pseudo selector with end of first-of-type. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include first { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:first-of-type { +/// color: black; +/// } + @mixin first { &:first-of-type { @content; } } +/// Pseudo selector with end of last-of-type. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include last { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:last-of-type { +/// color: black; +/// } + @mixin last { &:last-of-type { @content; } } +/// Pseudo selector with end of nth-child(even). +/// +/// @example scss - Usage +/// @include b('list') { +/// @include even { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:nth-child(even) { +/// color: black; +/// } + @mixin even { &:nth-child(even) { @content; } } +/// Pseudo selector with end of nth-child(odd). +/// +/// @example scss - Usage +/// @include b('list') { +/// @include odd { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:nth-child(odd) { +/// color: black; +/// } + @mixin odd { &:nth-child(odd) { @content; } } +/// Pseudo selector with end of before. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include before { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:before { +/// color: black; +/// } + @mixin before { &:before { @content; } } +/// Pseudo selector with end of after. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include after { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:after { +/// color: black; +/// } + @mixin after { &:after { @content; diff --git a/mixins/_relations.scss b/mixins/_relations.scss index 545832e..3d4ab22 100644 --- a/mixins/_relations.scss +++ b/mixins/_relations.scss @@ -1,21 +1,101 @@ +@charset "UTF-8"; + +/// Relationship of parent element with current modifier +/// +/// @param {String} $modifier - Name of modifier that will make parent element child. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include e('item') { +/// @include m('inline') { +/// color: black; +/// } +/// } +/// } +/// +/// @example css - Output +/// .list--inline .list__item { +/// color: black; +/// } +/// +/// @requires {function} at-selector + @mixin at($modifier) { #{at-selector($modifier)} { @content; } } +/// Element with another element separated by plus sign +/// +/// @param {String} $element - Name of element that will be styled with parent element. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include e('item') { +/// @include with('title') { +/// color: black; +/// } +/// } +/// } +/// +/// @example css - Output +/// .list__item .list__title { +/// color: black; +/// } +/// +/// @requires {function} with-selector + @mixin with($element) { #{with-selector($element)} { @content; } } +/// Element with same element separated by plus sign +/// +/// @example scss - Usage +/// @include b('list') { +/// @include e('item') { +/// @include duo { +/// color: black; +/// } +/// } +/// } +/// +/// @example css - Output +/// .list__item + .list__item { +/// color: black; +/// } +/// +/// @requires {function} duo-selector + @mixin duo { #{duo-selector()} { @content; } } +/// While two selectors are on same element +/// +/// @param {String} $modifier - Name of modifier that will follow parent modifier. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include m('inline') { +/// @include while('ordered') { +/// color: black; +/// } +/// } +/// } +/// +/// @example css - Output +/// .list--inline.list--ordered { +/// color: black; +/// } +/// +/// @requires {function} while-selector + @mixin while($modifier) { #{while-selector($modifier)} { @content; diff --git a/mixins/_scope.scss b/mixins/_scope.scss index faa9315..3836681 100644 --- a/mixins/_scope.scss +++ b/mixins/_scope.scss @@ -1,13 +1,34 @@ -/** - * Signify that a class is responsible for adding a - * Theme to a view. It lets us know that UI Components’ - * current cosmetic appearance may be due - * to the presence of a theme. - * - * Format: .s-scope {} - */ -@mixin scope($scope) { - #{scope-selector($scope)} { +@charset "UTF-8"; + +/// Signify that a class creates a new styling context or Scope. Similar to a Theme, but not necessarily cosmetic, these should be used sparingly—they can be open to abuse and lead to poor CSS if not used wisely. +/// +/// @param {String} $scope - Name of scope that will come after ".s-" +/// @param {String} $namespace [null] - Scope element namespace. +/// +/// @example scss - Usage +/// @include scope('paper') { +/// color: black; +/// } +/// +/// @example css - Output +/// .s-paper { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include s('paper') { +/// color: black; +/// } +/// +/// @example css - Output +/// .s-paper { +/// color: black; +/// } +/// +/// @requires {function} scope-selector + +@mixin scope($scope, $namespace: $bem-scope-namespace) { + #{scope-selector($scope, $namespace)} { @if $bem-debug == true { outline: 5px solid #a2453d; } @@ -16,9 +37,10 @@ } } -// Shorthand -@mixin s($scope) { - @include scope($scope) { +/// @alias scope + +@mixin s($scope, $namespace: $bem-scope-namespace) { + @include scope($scope, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_state.scss b/mixins/_state.scss index c8a059a..2fe8633 100644 --- a/mixins/_state.scss +++ b/mixins/_state.scss @@ -1,22 +1,24 @@ -/** - * Signify that the piece of UI in question - * is currently styled a certain way because - * of a state or condition. This stateful - * namespace is gorgeous, and comes from SMACSS. - * It tells us that the DOM currently has a - * temporary, optional, or short-lived style - * applied to it due to a certain state being invoked. - * - * ----- - * - * Signify that this piece of the DOM has some - * behaviour acting upon it, and that JavaScript - * binds onto it to provide that behaviour. - * If you’re not a developer working with - * JavaScript, leave these well alone. - * - * Format: .[is|has|js]-state {} - */ +@charset "UTF-8"; + +/// Signify that the piece of UI in question is currently styled a certain way because of a state or condition. This stateful namespace is gorgeous, and comes from SMACSS. It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked. +/// +/// @param {String} $state - Name of state that will come after ".[is|has|js]-" +/// @param {String} $namespace [null] - State element namespace. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include state('active', 'is') { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list.is-active { +/// color: black; +/// } +/// +/// @requires {function} state-selector + @mixin state($state, $namespace: null) { @at-root { #{state-selector($state, $namespace)} { @@ -29,19 +31,26 @@ } } -// Shorthands +/// @alias state + @mixin is($state) { @include state($state, 'is') { @content; } } +/// @alias state + @mixin has($state) { @include state($state, 'has') { @content; } } +/// Signify that this piece of the DOM has some behaviour acting upon it, and that JavaScript binds onto it to provide that behaviour. If you’re not a developer working with JavaScript, leave these well alone. +/// +/// @alias state + @mixin js($state) { @include state($state, 'js') { @content; diff --git a/mixins/_states.scss b/mixins/_states.scss index 3f7940e..15aae06 100644 --- a/mixins/_states.scss +++ b/mixins/_states.scss @@ -1,45 +1,145 @@ +/// Pseudo selector with end of hover. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include hover { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:hover { +/// color: black; +/// } + @mixin hover { &:hover { @content; } } +/// Pseudo selector with end of focus. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include focus { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:focus { +/// color: black; +/// } + @mixin focus { &:focus { @content; } } +/// Pseudo selector with end of active. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include active { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:active { +/// color: black; +/// } + @mixin active { &:active { @content; } } +/// Pseudo selector with end of checked. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include checked { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list:checked { +/// color: black; +/// } + @mixin checked { &:checked { @content; } } +/// Selector with state of disabled. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include disabled { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list[disabled] { +/// color: black; +/// } + @mixin disabled { &[disabled] { @content; } } +/// Selector with state of readonly. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include readonly { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list[readonly] { +/// color: black; +/// } + @mixin readonly { &[readonly] { @content; } } +/// Selector with state of contenteditable. +/// +/// @example scss - Usage +/// @include b('list') { +/// @include contenteditable { +/// color: black; +/// } +/// } +/// +/// @example css - Output +/// .list[contenteditable="true"] { +/// color: black; +/// } + @mixin contenteditable { &[contenteditable="true"] { @content; } } +/// @alias contenteditable + @mixin editable { @include contenteditable { @content; diff --git a/mixins/_test.scss b/mixins/_test.scss index 8c2917f..d4a5bdc 100644 --- a/mixins/_test.scss +++ b/mixins/_test.scss @@ -1,15 +1,34 @@ -/** - * Signify that a QA or Test Engineering team - * is running an automated UI test which needs - * to find or bind onto these parts of the DOM. - * Like the JavaScript namespace, this basically - * just reserves hooks in the - * DOM for non-CSS purposes. - * - * Format: .qa-node {} - */ -@mixin test($test) { - #{test-selector($test)} { +@charset "UTF-8"; + +/// Signify that a QA or Test Engineering team is running an automated UI test which needs to find or bind onto these parts of the DOM. Like the JavaScript namespace, this basically just reserves hooks in the DOM for non-CSS purposes. +/// +/// @param {String} $test - Name of state that will come after ".[is|has|js]-" +/// @param {String} $namespace [null] - State element namespace. +/// +/// @example scss - Usage +/// @include test('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .list.is-active { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include qa('list') { +/// color: black; +/// } +/// +/// @example css - Output +/// .list.is-active { +/// color: black; +/// } +/// +/// @requires {function} test-selector + +@mixin test($test, $namespace: $bem-test-namespace) { + #{test-selector($test, $namespace)} { @if $bem-debug == true { outline: 5px solid #f8e796; } @@ -18,9 +37,10 @@ } } -// Shorthand -@mixin qa($test) { - @include test($test) { +/// @alias test + +@mixin qa($test, $namespace: $bem-test-namespace) { + @include test($test, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_theme.scss b/mixins/_theme.scss index 1a25245..be97ef0 100644 --- a/mixins/_theme.scss +++ b/mixins/_theme.scss @@ -1,13 +1,34 @@ -/** - * Signify that a class is responsible for adding a - * Theme to a view. It lets us know that UI Components’ - * current cosmetic appearance may be due - * to the presence of a theme. - * - * Format: .t-theme {} - */ -@mixin theme($theme) { - #{theme-selector($theme)} { +@charset "UTF-8"; + +/// Signify that a class is responsible for adding a Theme to a view. It lets us know that UI Components’ current cosmetic appearance may be due to the presence of a theme. +/// +/// @param {String} $theme - Name of theme that will come after ".t-" +/// @param {String} $namespace [null] - Theme element namespace. +/// +/// @example scss - Usage +/// @include theme('dark') { +/// color: black; +/// } +/// +/// @example css - Output +/// .t-dark { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include t('dark') { +/// color: black; +/// } +/// +/// @example css - Output +/// .t-dark { +/// color: black; +/// } +/// +/// @requires {function} test-selector + +@mixin theme($theme, $namespace: $bem-theme-namespace) { + #{theme-selector($theme, $namespace)} { @if $bem-debug == true { outline: 5px solid #60316e; } @@ -16,9 +37,10 @@ } } -// Shorthand -@mixin t($theme) { - @include theme($theme) { +/// @alias theme + +@mixin t($theme, $namespace: $bem-theme-namespace) { + @include theme($theme, $namespace) { @content; } } \ No newline at end of file diff --git a/mixins/_utility.scss b/mixins/_utility.scss index 146e1ee..fb9a573 100644 --- a/mixins/_utility.scss +++ b/mixins/_utility.scss @@ -1,16 +1,34 @@ -/** - * Signify that this class is a Utility class. - * It has a very specific role (often providing - * only one declaration) and should not be bound - * onto or changed. It can be reused and is not - * tied to any specific piece of UI. You will - * probably recognise this namespace from - * libraries and methodologies like SUIT. - * - * Format: .u-utility {} - */ -@mixin utility($utility) { - #{utility-selector($utility)} { +@charset "UTF-8"; + +/// Signify that this class is a Utility class. It has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI. You will probably recognise this namespace from libraries and methodologies like SUIT. +/// +/// @param {String} $utility - Name of utility that will come after ".u-" +/// @param {String} $namespace [null] - Utility element namespace. +/// +/// @example scss - Usage +/// @include utility('uppercase') { +/// color: black; +/// } +/// +/// @example css - Output +/// .u-uppercase { +/// color: black; +/// } +/// +/// @example scss - Usage +/// @include u('uppercase') { +/// color: black; +/// } +/// +/// @example css - Output +/// .u-uppercase { +/// color: black; +/// } +/// +/// @requires {function} utility-selector + +@mixin utility($utility, $namespace: $bem-utility-namespace) { + #{utility-selector($utility, $namespace)} { @if $bem-debug == true { outline: 5px solid #635270; } @@ -19,9 +37,10 @@ } } -// Shorthand -@mixin u($utility) { - @include utility($utility) { +/// @alias utility + +@mixin u($utility, $namespace: $bem-utility-namespace) { + @include utility($utility, $namespace) { @content; } } \ No newline at end of file diff --git a/package.json b/package.json index 0464e8c..c8f32b1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sass-bem", - "version": "2.3.3", + "version": "2.4.0", "description": "Collection of BEM Mixins & Helpers", "main": "_bem.scss", "repository": { diff --git a/tests/style.scss b/tests/style.scss deleted file mode 100644 index a97bf90..0000000 --- a/tests/style.scss +++ /dev/null @@ -1,410 +0,0 @@ -@import "../scss/bem"; -@import "../node_modules/sass-true/sass/true"; - -@include test-module('BEM') { - // Functions - @include test('bem-index [function]') { - @include assert-equal(bem-index('.list__item'), 6, 'Returns first index of bem separator'); - @include assert-equal(bem-index('.list--inline'), 6, 'Returns first index of bem separator'); - @include assert-equal(bem-index('.list'), 0, 'Returns first index of bem separator'); - } - - @include test('get-block [function]') { - @include assert-equal(get-block('.list__item'), 'list', 'Returns bem block from string'); - @include assert-equal(get-block('.list--inline'), 'list', 'Returns bem block from string'); - @include assert-equal(get-block('.list'), 'list', 'Returns bem block from string'); - } - - @include test('is-block [function]') { - @include assert-equal(is-block('.list__item'), false, 'Checks if given string is block'); - @include assert-equal(is-block('.list--inline'), false, 'Checks if given string is block'); - @include assert-equal(is-block('.list'), true, 'Checks if given string is block'); - } - - @include test('is-element [function]') { - @include assert-equal(is-element('.list__item'), true, 'Checks if given string is element'); - @include assert-equal(is-element('.list--inline'), false, 'Checks if given string is element'); - @include assert-equal(is-element('.list'), false, 'Checks if given string is element'); - } - - @include test('is-modifier [function]') { - @include assert-equal(is-modifier('.list__item'), false, 'Checks if given string is modifier'); - @include assert-equal(is-modifier('.list--inline'), true, 'Checks if given string is modifier'); - @include assert-equal(is-modifier('.list'), false, 'Checks if given string is modifier'); - } - - @include test('math-min [function]') { - @include assert-equal(math-min(7, 15, 0), 7, 'Returns smallest number from 2 numbers, or default'); - @include assert-equal(math-min(10, 10, 0), 10, 'Returns smallest number from 2 numbers, or default'); - @include assert-equal(math-min(7, null, 0), 7, 'Returns smallest number from 2 numbers, or default'); - @include assert-equal(math-min(null, 5, 0), 5, 'Returns smallest number from 2 numbers, or default'); - @include assert-equal(math-min(null, null, 0), 0, 'Returns smallest number from 2 numbers, or default'); - } - - @include test('explode [function]') { - @include assert-equal(explode('one-two-three', '-'), 'one' 'two' 'three', 'Returns list from string'); - } - - // Mixins - @include test('block [mixin]') { - @include assert('Creates block type selector') { - @include input { - @include b(list) { - background-color: orange; - } - } - - @include expect { - .list { - background-color: orange; - } - } - } - } - - @include test('element [mixin]') { - @include assert('Creates element type selector') { - @include input { - @include b(list) { - @include e(item) { - background-color: red; - } - } - } - - @include expect { - .list__item { - background-color: red; - } - } - } - } - - @include test('modifier [mixin]') { - @include assert('Creates modifier type selector') { - @include input { - @include b(list) { - @include m(inline) { - background-color: green; - } - } - } - - @include expect { - .list--inline { - background-color: green; - } - } - } - } - - @include test('duo [mixin]') { - @include assert('Relates same classed neighbour elements') { - @include input { - @include b(list) { - @include e(item) { - @include duo { - margin-left: 10px; - } - } - } - } - - @include expect { - .list__item + .list__item { - margin-left: 10px; - } - } - } - } - - @include test('is [mixin]') { - @include assert('Addes state to selector') { - @include input { - a { - @include is(active) { - font-weight: bold; - } - } - } - - @include expect { - a.is-active { - font-weight: bold; - } - } - } - } - - @include test('has [mixin]') { - @include assert('Addes state to selector') { - @include input { - a { - @include has(child) { - font-weight: bold; - } - } - } - - @include expect { - a.has-child { - font-weight: bold; - } - } - } - } - - @include test('js [mixin]') { - @include assert('Addes state to selector') { - @include input { - div { - @include js(target) { - font-weight: bold; - } - } - } - - @include expect { - div.js-target { - font-weight: bold; - } - } - } - } - - @include test('hover [mixin]') { - @include assert('Addes hover state to selector') { - @include input { - a { - @include hover { - color: red; - } - } - } - - @include expect { - a:hover { - color: red; - } - } - } - } - - @include test('focus [mixin]') { - @include assert('Addes focus state to selector') { - @include input { - a { - @include focus { - color: blue; - } - } - } - - @include expect { - a:focus { - color: blue; - } - } - } - } - - @include test('active [mixin]') { - @include assert('Addes active state to selector') { - @include input { - a { - @include active { - color: green; - } - } - } - - @include expect { - a:active { - color: green; - } - } - } - } - - @include test('checked [mixin]') { - @include assert('Addes checked state to selector') { - @include input { - input { - @include checked { - display: block; - } - } - } - - @include expect { - input:checked { - display: block; - } - } - } - } - - @include test('disabled [mixin]') { - @include assert('Addes disabled state to selector') { - @include input { - button { - @include disabled { - opacity: 0.8; - } - } - } - - @include expect { - button[disabled] { - opacity: 0.8; - } - } - } - } - - @include test('readonly [mixin]') { - @include assert('Addes readonly state to selector') { - @include input { - input { - @include readonly { - cursor: default; - } - } - } - - @include expect { - input[readonly] { - cursor: default; - } - } - } - } - - @include test('contenteditable [mixin]') { - @include assert('Addes contenteditable state to selector') { - @include input { - .box { - @include contenteditable { - border-color: orange; - } - } - } - - @include expect { - .box[contenteditable="true"] { - border-color: orange; - } - } - } - } - - @include test('first [mixin]') { - @include assert('Takes pseudo element of selector') { - @include input { - a { - @include first { - color: orange; - } - } - } - - @include expect { - a:first-of-type { - color: orange; - } - } - } - } - - @include test('last [mixin]') { - @include assert('Takes pseudo element of selector') { - @include input { - a { - @include last { - color: blue; - } - } - } - - @include expect { - a:last-of-type { - color: blue; - } - } - } - } - - @include test('even [mixin]') { - @include assert('Takes pseudo element of selector') { - @include input { - a { - @include even { - color: green; - } - } - } - - @include expect { - a:nth-child(even) { - color: green; - } - } - } - } - - @include test('odd [mixin]') { - @include assert('Takes pseudo element of selector') { - @include input { - a { - @include odd { - color: aqua; - } - } - } - - @include expect { - a:nth-child(odd) { - color: aqua; - } - } - } - } - - @include test('before [mixin]') { - @include assert('Creates pseudo element of selector') { - @include input { - a { - @include before { - color: orange; - } - } - } - - @include expect { - a:before { - color: orange; - } - } - } - } - - @include test('after [mixin]') { - @include assert('Creates pseudo element of selector') { - @include input { - a { - @include after { - color: red; - } - } - } - - @include expect { - a:after { - color: red; - } - } - } - } -} - -@include report; \ No newline at end of file