Jigsass-tools-selectors - 0.9.2
JigSass Tools Selectors
Create predictable, manageable and composable CSS with zero bloat and scalability in mind
Report an issue in Github
Installation
Using npm:
npm i -S jigsass-tools-selectors
Usage
@import 'path/to/jigsass-tools-selectors';
Managing CSS at scale is hard, even very hard. Code bases easily grow out of control, and dead code elimination is an onerous task.
JigSass borrows much of its architecture from inuit and ideas on CSS structure expressed elsewhere by Harry Roberts, and as such is, at its core, based on two main pillars:
- Objects: Abstract design pattern, such as the media object meant for reuse in many unrelated contexts. Can be extended, with modifer classes, but directly mutating an object will have rippling effects. Should consist of minimal styling, to later be expanded with modifiers, utiliies and within components themselves.
- Components: An implementation-specific piece of UI. Should not be reused outside the context of the specific component. Will often consist mostly of including objects and utils within the ruleset.
- Utilities: Low-level, single-purpose immutable units of style, often only declaring a single declaration. These are not bound to any spcific ui or design abstruction, and can be used to change, adjust or augment
JigSass Selectors is an attempt to provide tools for better tackling these tasks, and assisting with defining and generating clean and easy to maintain CSS based on responsive-enabled, reusable object and utility classes.
In order to keep a CSS footprint to a minimum, not even a single line of the defined CSS is generated unless it is explicitly included for use.
Objects
CSS rulsets of objects and object modifiers are generated based on settings in its configuration map (passed as a parameter to the jigsass-object
mixin), where classes must be explicitly enabled in the associated configuration map (passed to the mixin as the $config
param) BEFORE the object is @include
d.
By default, CSS rulsets of objects and object modifiers are not automatically generated generated by including the jigsass-object
mixin. For any output to be generated, classes must be explicitly enabled in the Object's associated configuration map (passed to the mixin as the $config
param) BEFORE the object is @include
d.
The structure of configuration maps is:
// _objects.foo.scss
$foo-map: (
no-breakpoint: (
no-modifier: true, // Enables generation of the `.o-foo`
// class outside of any media query.
bar: true, // Enables generation of the `.o-foo--bar`
// modifier class outside of any media query.
),
from-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--from-<bp-name>`
// class inside a min-width media query
// defined ins `$jigsass-breakpoints.length`.
bar: true, // Enables generation of the `.o-foo--bar--from-<bp-name>`
// class inside a min-width media query
// defined ins `$jigsass-breakpoints.length`.
),
until-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--until-<bp-name>`
// class inside a max-width media query
// defined ins `$jigsass-breakpoints.length`.
bar: true, // Enables generation of the `.o-foo--bar--until-<bp-name>`
// class inside a max-width media query
// defined ins `$jigsass-breakpoints.length`.
),
when-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--when-<bp-name>`
// class inside a misc media query
// defined ins `$jigsass-breakpoints.features`.
bar: true, // Enables generation of the `.o-foo--bar--when-<bp-name>`
// class inside a misc media query
// defined ins `$jigsass-breakpoints.features`.
),
from-<bp-name>-until-<bp-name>: (...);
from-<bp-name>-when-<bp-name>: (...);
until-<bp-name>-when-<bp-name>: (...);
from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
);
Utilities
Instead of using configuration maps or variables, which eventually become difficult to maintain and keep track of for utility classes, JigSass offers the jigsass-define-util
and jigsass-util
mixins, used to define utils and dynamically CSS output for them without creating duplication or changing the cascade.
Let's take a look at a simplified example:
/* _object.media.scss */
$media-conf: (
from-large: (
no-modifier: true,
middle: true,
),
);
$media-item-conf: (
from-large: (
bottom: true,
),
);
@jigsass-object(o-media, $media-conf) {
@include jigsass-classname {
display: flex;
}
@include jigsass-classname($modifer: middle) {
align-items: center;
}
@include jigsass-classname($modifer: reverse) {
flex-direction: row-reverse;
}
}
@jigsass-object(o-media__item, $media-item-conf) {
@include jigsass-classname($modifier: bottom) {
align-self: flex-end;
}
}
/* _component.foo.scss */
.c-foo {
// Styles unique for `.c-foo`:
mix-blend-mode: multiply;
}
.c-foo__fig {
@include jigsass-util(u-ml, $from: large, $modifier: 1);
@include jigsass-util(u-mr, $from: large, $modifier: 1);
// Styles unique for `.c-foo__fig`:
filter: blur(3px);
}
// `.foo__fig--bottom` will not actually be generated,
// as it has no styles of its own.
.c-foo__fig--bottom {
@include jigsass-util(u-ml, $from: large, $modifier: 1);
}
// `.foo__body` will not actually be generated,
// as it has no styles of its own.
.c-foo__body {
@include jigsass-util(u-mr, $from: large, $modifier: 1);
}
/* _util.margin.scss */
@include jigsass-define-util(u-mr) {
$modifier: $jigsass-util-modifier or 0;
margin-right: $jigsass-util-modifier * 12px;
}
@include jigsass-define-util(u-ml) {
$modifier: $jigsass-util-modifier or 0;
margin-left: $jigsass-util-modifier * 12px;
}
// style.scss
@import 'object.media'; // `.o-media` will be generated here
@import 'component.foo'; // `.c-foo` and `.c-foo__fig` will be generated here.
@import 'util.margin'; // `.u-ml` and `.u-mr` will be generated here.
Will generate:
/* style.css */
@media (min-width: 65em) {
.o-media--from-large {
display: flex;
}
.o-media--middle--from-large {
align-items: center;
}
}
@media (min-width: 65em) {
.o-media__item--bottom--from-large {
align-self: bottom;
}
}
.c-foo {
mix-blend-mode: multiply;
}
.c-foo__fig {
filter: blur(3px);
}
@media (min-width: 65em) {
.u-mr--1--from-large {
margin-right: 12px;
}
}
@media (min-width: 65em) {
.u-ml--1--from-large {
margin-left: 12px;
}
}
Notice how only the styles we actually used ended up in our CSS? How they were generated where they were defined, and only once?
When managing the generation of css utility classes through config files, it eventually becomes damn near impossible to keep track of where each class is used, and when it is safe to remove, often leaving us with codebases that are larger than they need to be.
In contrast, generating the styles by simply including them where they are being used is a lot easier to grasp and manage, while still keeping our CSS stringent and modular.
Now, with the above CSS and following html:
<article class="[ o-media--from-large o-media--middle--from-large ] c-foo">
<figure class="c-foo__fig u-mr--1--from-large">
<!-- img1 here -->
</figure>
<div class="foo__body">
<!-- content here -->
</div>
<figure class="o-media__item--bottom--from-large c-foo__fig u-ml--1--from-large">
<!-- img2 here -->
</figure>
</articel>
We can get something like this:
┌─────────────╥╥─────────────────────────────╥╥─────────────┐
│############ ║║CONTENT HEAD ║║ │
│############ ║║ ║║ │
│############ ║║ minus saepe sequi velit a, ║║ ############│
│## IMG1 ## ║║ sit veniam quia quibusdam ║║ ############│
│############ ║║ odio itaque non! Dolores ║║ ############│
│############ ║║ deserunt atque repudiandae ║║ ## IMG2 ##│
│############ ║║ asperiores rerum velit ║║ ############│
│ ║║ magnam deleniti deleniti ║║ ############│
│ ║║ sed aspernatur commodi? ║║ ############│
└─────────────╨╨─────────────────────────────╨╨─────────────┘
The jigsass-object
and jigsass-util
mixins will generate selectors according to the following logic:
.class-name[--modifier][-[-from-{breakpoint-name}][-until-{breakpoint-name}][-misc-{breakpoint-name}]]
License: MIT
selectors
variables
[private] _jigsass-selectors
$_jigsass-selectors: () !default;
Description
A container to store the names of generated selectors.
Once populated, its structure will be as follows:
$_jigsass-selectors: (
name: (
breakpoint: (
modifier: false, // true: Was included;
// silent: Was in silent mod when first
// included, don't touch even if
// included again.
// false: Wasn't called yet. Set to `true`
// or `silent` if called.
)
)
);
Used by
- [function]
_jigsass-class-was-included
- [mixin]
jigsass-component
- [mixin]
jigsass-object
- [mixin]
jigsass-classname
- [mixin]
jigsass-define-util
- [mixin]
jigsass-block
- [mixin]
jigsass-util
selectors - 01 namespace
functions
jigsass-get-namespace
@function jigsass-get-namespace() { ... }
Description
Get the namespace correctly formatted
Parameters
None.
Returns
String
Requires
- [variable]
jigsass-namespace
Used by
- [function]
_jigsass-gen-class-name
- [mixin]
_jigsass-define-util
mixins
jigsass-set-local-namespace
@mixin jigsass-set-local-namespace($namespace) { ... }
Description
Set a local namespace to prefix all classes generated withing the context of the mixin with.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$namespace | The namespace to prepend. | String | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [variable]
jigsass-namespace
variables
jigsass-namespace
$jigsass-namespace: '' !default;
Description
A prefix to prepend all jigsass classes with
Do not directly override. To redefine, use the jigsass-set-namespace
and jigsass-set-local-namespace
mixins.
Type
{string}
Used by
- [function]
jigsass-get-namespace
- [mixin]
jigsass-set-local-namespace
See
- [mixin]
jigsass-set-local-namespace
selectors - 02 silent
mixins
jigsass-mute
@mixin jigsass-mute() { ... }
Description
Disable CSS output.
Parameters
None.
Requires
- [variable]
jigsass-silent
jigsass-if-not-silent
@mixin jigsass-if-not-silent() { ... }
Description
Process @content
if not in silent mode
Parameters
None.
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [variable]
jigsass-silent
jigsass-unmute
@mixin jigsass-unmute() { ... }
Description
Enable CSS output.
Parameters
None.
Requires
- [variable]
jigsass-silent
variables
jigsass-silent
$jigsass-silent: false !default;
Description
Determines if JigSass should output CSS.
Type
{boolean}
Used by
- [mixin]
jigsass-mute
- [mixin]
jigsass-unmute
- [mixin]
jigsass-if-not-silent
- [mixin]
jigsass-component
- [mixin]
jigsass-classname
- [mixin]
jigsass-block
- [mixin]
jigsass-util
selectors - 03 helpers
functions
jigsass-parse-modifier
Since 0.7.0@function jigsass-parse-modifier() { ... }
Description
Parse a modifier string into a map with modifier
, state
and args
keys, for use inside @content
blocks.
Modifiers should be written in the following format: 'modifier-name(arg1,arg2):state'
Parameters
None.
Returns
Map
—A map of parsed values.
Example
$parsed: jigsass-parse-modifier(mod(tint,1):hover);
// -> (modifier: mod, args: 'tint' 1, state: ':hover');
[private] _jigsass-bp-string
@function _jigsass-bp-string($from, $until, $misc) { ... }
Description
Return a string representing a media query.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$from | The name of breakpoint used as the min-width condition. | String or Boolean | —none |
$until | The name of breakpoint used as the max-width condition. | String or Boolean | —none |
$misc | The name of a miscellaneous media query condition. | String or Boolean | —none |
Returns
String
—string representation of a media-query's conditions
Throws
_jigsass-bp-string: #{$from} is not a named width breakpoint
_jigsass-bp-string: #{$until} is not a named width breakpoint
_jigsass-bp-string: #{$misc} is not a named misc feature breakpoint
Used by
- [function]
_jigsass-gen-class-name
- [function]
_jigsass-class-was-included
- [mixin]
jigsass-object
- [mixin]
jigsass-classname
- [mixin]
jigsass-util
[private] _jigsass-mq-args-parser
@function _jigsass-mq-args-parser() { ... }
Description
Parse a string representing media query conditions into a map with from
, until
and misc
keys.
Parameters
None.
Used by
- [mixin]
_jigsass-define-util
[private] _jigsass-gen-class-name
@function _jigsass-gen-class-name($name, $from, $until, $misc, $modifier) { ... }
Description
Parse arguments into a string for a class name
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the object or util. | String or Boolean | —none |
$from | The name of breakpoint used as the min-width condition. | String or Boolean | —none |
$until | The name of breakpoint used as the max-width condition. | String or Boolean | —none |
$misc | The name of a miscellaneous media query condition. | String or Boolean | —none |
$modifier | A modifier's name | String or Boolean | —none |
Returns
String
—A class name (sans the .
)
Requires
- [function]
_jigsass-bp-string
- [function]
jigsass-get-namespace
Used by
- [mixin]
jigsass-classname
[private] _jigsass-generate-selector-map
@function _jigsass-generate-selector-map($name: $name, $bps: $jigsass-breakpoints) { ... }
Description
Generate a map used for generating a jigsass object or utility class in a correct and predictable order, allowing usage of the cascade to override default classes with modifier ones and non-responsive classes media responsive ones.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the object of helper to generate the map for. When in the context of generating a utility or object class, defaults to the name of that class. | String | $name |
$bps | —none | Map | $jigsass-breakpoints |
Returns
Map
Requires
- [variable]
_jigsass-selector-map
Example
$jigsass-selectors: map-merge(
$jigsass-selectors,
_jigsass-generate-selector-map(class-name)
);
Used by
- [mixin]
jigsass-object
- [mixin]
jigsass-util
[private] _jigsass-class-was-included
@function _jigsass-class-was-included($name, $from, $until, $misc, $modifier) { ... }
Description
Check if a class was already included
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the object or util. | String | —none |
$from | The name of breakpoint used as the min-width condition. | String or Boolean | —none |
$until | The name of breakpoint used as the max-width condition. | String or Boolean | —none |
$misc | The name of a miscellaneous media query condition. | String or Boolean | —none |
$modifier | A modifier's name | String or Boolean | —none |
Returns
Boolean
—Indicates if the class was generated or called in silent mode (true);
Throws
_jigsass-selector-was-inclded()
has a dependency on
Requires
- [function]
_jigsass-bp-string
- [variable]
_jigsass-selectors
Used by
- [mixin]
jigsass-classname
- [mixin]
jigsass-util
variables
[private] _jigsass-selector-map
$_jigsass-selector-map: false;
Description
Selector map cache
Selector maps are always identical, so can be generated once and cached.
For internal use by _jigsass-generate-selector-map
Type
{map}
Used by
- [function]
_jigsass-generate-selector-map
selectors - 04 define
mixins
jigsass-define-block
@mixin jigsass-define-block($name) { ... }
Description
Define a custom css block that can be later enabled and generated once where it was defined.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the CSS block being defined, e.g. | String | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Example
@include jigsass-define-block(normalize-forms) {
form { margin: 0; }
button,
input,
optgroup,
select,
textarea {
color: inherit;
font: inherit;
margin: 0;
}
}
// ...
jigsass-component
@mixin jigsass-component($name) { ... }
Description
A helper for defining single-use CSS components that can be included numerous times, but will only be generated once, where it was first included.
If $jigsass-silent
is set to true
when a component is first included, no CSS will be generated even if it is included a second time when $jigsass-silent
is set to false
.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the CSS component being defined, e.g. | String | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [variable]
_jigsass-selectors
- [variable]
jigsass-silent
Example
@mixin login-area() { // <-- The custom component mixin
@include jigsass-component(login-area) { // <-- Using the helper
@include jigsass-object(o-grid, $modifier: center);
@include jigsass-object(o-grid, $modifier:gutter-8, $from: large);
@include jigsass-util(u-mb, 4);
@include jigsass-util(u-tac);
background-image: url(/images/some-awesome-background.png);
}
}
jigsass-map2styles
@mixin jigsass-map2styles($ruleset-map) { ... }
Description
Convert Sass maps in to CSS rulesets
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$ruleset-map | The map to convert to a ruleset. Supports nested maps for nested selectors | Map | —none |
Throws
jigsass-map2styles
fromjigsass-tools-selectors
has a dependency on
Example
SCSS Input
$foo-styles: (
display: block,
'& > .bar': (
color: red
)
);
.foo {
@inlcude jigsass-map2styles($foo-styles);
}
CSS Output
.foo {
display: block;
}
.foo > .bar {
color: red
}
jigsass-object
@mixin jigsass-object($name, $conf) { ... }
Description
Define a reusable object class and generate it once, if it is enabled in configuration map.
By default, including the jigsass-object
mixin will not generate any css. For any output to be generated, classes must be explicitly enabled in the associated configuration map (passed to the mixin as the $config
param) BEFORE the object is @include
d.
The structure of configuration maps is:
// _objects.foo.scss
$foo-map: (
no-breakpoint: (
no-modifier: true, // Enables generation of the `.o-foo`
// class outside of any media query.
bar: true, // Enables generation of the `.o-foo--bar`
// modifier class outside of any media query.
),
from-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--from-<bp-name>`
// class inside a min-width media query
// defined ins `$jigsass-breakpoints.length`.
bar: true, // Enables generation of the `.o-foo--bar--from-<bp-name>`
// class inside a min-width media query
// defined ins `$jigsass-breakpoints.length`.
),
until-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--until-<bp-name>`
// class inside a max-width media query
// defined ins `$jigsass-breakpoints.length`.
bar: true, // Enables generation of the `.o-foo--bar--until-<bp-name>`
// class inside a max-width media query
// defined ins `$jigsass-breakpoints.length`.
),
when-<bp-name>: (
no-modifier: true, // Enables generation of the `.o-foo--when-<bp-name>`
// class inside a misc media query
// defined ins `$jigsass-breakpoints.features`.
bar: true, // Enables generation of the `.o-foo--bar--when-<bp-name>`
// class inside a misc media query
// defined ins `$jigsass-breakpoints.features`.
),
from-<bp-name>-until-<bp-name>: (...);
from-<bp-name>-when-<bp-name>: (...);
until-<bp-name>-when-<bp-name>: (...);
from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
);
Regardless of how many times the jigsass-object
mixin is included, each selector will only be generated once.
If $jigsass-silent
is set to true
when the mixin is first included for a certain selector, the selector will not be generated, even if the mixin is later included again for that selector when $jigsass-silent
is set to false.
Use the jigsass-classname
mixin inside this mixin's body to define the base object and each of it's modifiers (See example below).
When calling the jigsass-get-obj-mq
function without arguments inside the @contnet
block, it will return a map with from
, until
and misc
keys, holding the arguments passed to the media query in the current context of @content
.
When called with an argument of from
, until
or misc
, the jigsass-get-obj-mq
will return the value of of that key from the above map.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the object class being defined, sans modifiers. A modifier's name | String | —none |
$conf | The configuration map in which the generation of the object's class and modifier classes are enabled. | Map | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [function]
_jigsass-generate-selector-map
- [function]
_jigsass-bp-string
- [variable]
jigsass-obj-mq-args
- [variable]
jigsass-obj-name
- [variable]
jigsass-obj-config
- [variable]
_jigsass-selectors
Example
@include jigsass-object(o-box, $box-config) {
// Defines rules for `.o-box`
@include jigsass-classname() {
padding: if(jigsass-get-obj-mq(misc) == landscape, 24px 48px, 24px));
}
// Defines rules for `.box--cramped`
@include jigsass-classname(box, $modifier: cramped) {
padding: 12px;
}
}
jigsass-classname
@mixin jigsass-classname($modifier: false, $name: $jigsass-obj-name) { ... }
Description
Generate an object or object-modifier class name inside jigsass-object
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$modifier | A modifier's name | String or Number or False | false |
$name | The object's base name. defaults to the name that was passed in the calling | String | $jigsass-obj-name |
Content
This mixin allows extra content to be passed (through the @content
directive).
Throws
jigsass-classname: A
$name
is required for generating a selector.jigsass-classname: A jigsass class modifier cannot be called
Requires
- [function]
jigsass-get-obj-mq
- [function]
_jigsass-bp-string
- [function]
_jigsass-gen-class-name
- [function]
_jigsass-class-was-included
- [variable]
jigsass-obj-config
- [variable]
jigsass-obj-modifier
- [variable]
jigsass-obj-name
- [variable]
jigsass-silent
- [variable]
_jigsass-selectors
Example
@include jigsass-object(box) {
// Defines rules from `.box`
@include jigsass-classname() {
padding: if(jigsass-get-obj-mq(misc) == landscape, 24px 48px, 24px));
}
// Defines rules for `.box--cramped`
@include jigsass-classname() {
@include jigsass-classname(box, $modifier: cramped) {
padding: 12px;
}
}
See
- [mixin]
jigsass-object
jigsass-define-util
@mixin jigsass-define-util($name) { ... }
Description
Define a utility class
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the utility class being defined, sans modifiers. | String | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [mixin]
jigsass-util
- [mixin]
_jigsass-define-util
- [variable]
_jigsass-selectors
- [variable]
jigsass-util-name
- [variable]
jigsass-util-modifier
[private] _jigsass-define-util
@mixin _jigsass-define-util($name, $bp-str) { ... }
Description
Private util used to abstract away selector generation
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the utility class being defined, sans modifiers. | String | —none |
$bp-str | A string representing media query conditions in the following format: | String | —none |
Content
This mixin allows extra content to be passed (through the @content
directive).
Requires
- [function]
_jigsass-mq-args-parser
- [function]
jigsass-get-namespace
- [variable]
jigsass-util-modifier
- [variable]
jigsass-util-mq-args
Used by
- [mixin]
jigsass-define-util
functions
jigsass-get-obj-mq
@function jigsass-get-obj-mq($type: false) { ... }
Description
Get media query arguments of current context. For use inside jigsass-object
.
When called inside the @contnet
block without arguments, it will return a map with from
, until
and misc
keys, holding the arguments passed to the media query in the current context of @content
.
When called with an argument of from
, until
or misc
, it will return the value of of that key from the above map.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$type | The type of media-query argument to check. May be | String or Boolean | false |
Returns
String
or Map
—The value attached to the queried $type
, or a map of all three types.
Requires
- [variable]
jigsass-obj-mq-args
Used by
- [mixin]
jigsass-classname
variables
jigsass-util-name
$jigsass-util-name: null;
Description
The current context's utility name. For use inside @content
blocks
Type
{null
or String}
Used by
- [mixin]
jigsass-define-util
jigsass-util-modifier
$jigsass-util-modifier: null;
Description
The current context's utility modifier. For use inside @content
blocks
Type
{null
or String}
Used by
- [mixin]
jigsass-define-util
- [mixin]
_jigsass-define-util
jigsass-util-mq-args
$jigsass-util-mq-args: (from: false, until: false, misc: false);
Description
The current context's media query arguments. For use inside @content
blocks.
Type
Map
Map structure
Map keyName | Map keyDescription | Map keyType | Map keyValue |
---|---|---|---|
from | The min-width condition of the current context. | Boolean or Number | false |
until | The max-width condition of the current context. | Boolean or Number | false |
misc | The miscellaneous media-query conditions of the current context. | Boolean or String or List | false |
Used by
- [mixin]
_jigsass-define-util
selectors - 05 require
mixins
jigsass-block
@mixin jigsass-block($name, $scope: false) { ... }
Description
Generate CSS of a defined block
Regardless of how many times the mixin is called with a certain set of argument, the rules defined in the block will only be generated once.
The generated styles will be created where they was defined, not where it was included.
If $jigsass-silent
is set to true
when a block is first included with a certain set of argument, no CSS will be generated for that argument set.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The name of the block to generate, as previously defined by calling jigsass-define-block | String | —none |
$scope | A selector to use for scoping the defined styles, Must be quoted | String or Boolean | false |
Requires
- [variable]
_jigsass-selectors
- [variable]
jigsass-silent
jigsass-util
@mixin jigsass-util($name, $from, $until, $misc, $modifier) { ... }
Description
Generate CSS of a utility class
jigsass-util
must be @include
d before the util class it calls is defined.
No matter how many times the mixin is called with a certain set of argument, only a single selector will be created in the generated CSS.
The generated class will be created where it was defined, not where it was called.
If $jigsass-silent
is set to true
when the jigsass-util
is first called with a certain set of argument, no class will be generated for that argument set.
Parameters
parameterName | parameterDescription | parameterType | parameterDefault value |
---|---|---|---|
$name | The base-name of the util class to generate | String | —none |
$from | The name of breakpoint used as the min-width condition. | String or Boolean | —none |
$until | The name of breakpoint used as the max-width condition. | String or Boolean | —none |
$misc | The name of a miscellaneous media query condition. | String or Boolean | —none |
$modifier | A modifier's name | String or Boolean | —none |
Throws
jigsass-util: A jigsass util class modifier cannot be called
Requires
- [function]
_jigsass-generate-selector-map
- [function]
_jigsass-class-was-included
- [function]
_jigsass-bp-string
- [variable]
_jigsass-selectors
- [variable]
jigsass-silent
Used by
- [mixin]
jigsass-define-util
variables
jigsass-obj-modifier
$jigsass-obj-modifier: null;
Description
The current $modifier
argument in the running context of the jigsass-classname
mixin to be used inside its @content
block.
Type
Null
or String
Used by
- [mixin]
jigsass-classname
jigsass-obj-mq-args
$jigsass-obj-mq-args: (from: false, until: false, misc: false);
Description
The current media query arguments in the running context of the jigsass-object
mixin to be used inside its @content
block.
Type
Map
Map structure
Map keyName | Map keyDescription | Map keyType | Map keyValue |
---|---|---|---|
from | The min-width condition of the current context. | Boolean or Number | false |
until | The max-width condition of the current context. | Boolean or Number | false |
misc | The miscellaneous media-query conditions of the current context. | Boolean or String or List | false |
Used by
- [function]
jigsass-get-obj-mq
- [mixin]
jigsass-object
jigsass-obj-name
$jigsass-obj-name: null;
Description
The name of the object in the current running context of the jigsass-classname
mixin to be used inside its @content
block.
Type
Null
or String
Used by
- [mixin]
jigsass-object
- [mixin]
jigsass-classname
jigsass-obj-config
$jigsass-obj-config: null;
Type
Null
or Map
Used by
- [mixin]
jigsass-object
- [mixin]
jigsass-classname
General
csss
// for be use inside `jigsass-classname` mixin. /// --- /// @type Null | Map /// --- /// @group Selectors - 05 Require /// --- $jigsass-obj-config: null; // ------------------------------------- // Mixins // ------------------------------------- /// Define a reusable object class and generate it once, /// if it is enabled in configuration map. /// /// By default, including the `jigsass-object` mixin will not generate /// any css. For any output to be generated, classes must be /// explicitly enabled in the associated configuration map (passed /// to the mixin as the `$config` param) _BEFORE_ the object is /// `@include`d. /// /// The structure of configuration maps is: /// ```scss /// // _objects.foo.scss /// $foo-map: ( /// no-breakpoint: ( /// no-modifier: true, // Enables generation of the `.o-foo` /// // class outside of any media query. /// bar: true, // Enables generation of the `.o-foo--bar` /// // modifier class outside of any media query. /// ), /// from-<bp-name>: ( /// no-modifier: true, // Enables generation of the `.o-foo--from-<bp-name>` /// // class inside a min-width media query /// // defined ins `$jigsass-breakpoints.length`. /// bar: true, // Enables generation of the `.o-foo--bar--from-<bp-name>` /// // class inside a min-width media query /// // defined ins `$jigsass-breakpoints.length`. /// ), /// until-<bp-name>: ( /// no-modifier: true, // Enables generation of the `.o-foo--until-<bp-name>` /// // class inside a max-width media query /// // defined ins `$jigsass-breakpoints.length`. /// bar: true, // Enables generation of the `.o-foo--bar--until-<bp-name>` /// // class inside a max-width media query /// // defined ins `$jigsass-breakpoints.length`. /// ), /// when-<bp-name>: ( /// no-modifier: true, // Enables generation of the `.o-foo--when-<bp-name>` /// // class inside a misc media query /// // defined ins `$jigsass-breakpoints.features`. /// bar: true, // Enables generation of the `.o-foo--bar--when-<bp-name>` /// // class inside a misc media query /// // defined ins `$jigsass-breakpoints.features`. /// ), /// from-<bp-name>-until-<bp-name>: (...); /// from-<bp-name>-when-<bp-name>: (...); /// until-<bp-name>-when-<bp-name>: (...); /// from-<bp-name>-until-<bp-name>-when-<bp-name>: (...); /// ); /// ``` /// /// Regardless of how many times the `jigsass-object` mixin is /// included, each selector will only be generated once. /// /// If `$jigsass-silent` is set to `true` when the mixin /// is first included for a certain selector, the selector /// will not be generated, even if the mixin is later included /// again for that selector when `$jigsass-silent` is set to false. /// /// /// Use the `jigsass-classname` mixin inside this mixin's /// body to define the base object and each of it's modifiers /// **(See example below)**. /// /// When calling the `jigsass-get-obj-mq` function without arguments /// inside the `@contnet` block, it will return a map with `from`, /// `until` and `misc` keys, holding the arguments passed to the /// media query in the current context of `@content`. /// /// When called with an argument of `from`, `until` or `misc`, the /// `jigsass-get-obj-mq` will return the value of of that key from /// the above map. /// --- /// @param
@css // for be use inside `jigsass-classname` mixin.
/// ---
/// @type Null | Map
/// ---
/// @group Selectors - 05 Require
/// ---
$jigsass-obj-config: null;
// -------------------------------------
// Mixins
// -------------------------------------
/// Define a reusable object class and generate it once,
/// if it is enabled in configuration map.
///
/// By default, including the `jigsass-object` mixin will not generate
/// any css. For any output to be generated, classes must be
/// explicitly enabled in the associated configuration map (passed
/// to the mixin as the `$config` param) _BEFORE_ the object is
/// `@include`d.
///
/// The structure of configuration maps is:
/// ```scss
/// // _objects.foo.scss
/// $foo-map: (
/// no-breakpoint: (
/// no-modifier: true, // Enables generation of the `.o-foo`
/// // class outside of any media query.
/// bar: true, // Enables generation of the `.o-foo--bar`
/// // modifier class outside of any media query.
/// ),
/// from-<bp-name>: (
/// no-modifier: true, // Enables generation of the `.o-foo--from-<bp-name>`
/// // class inside a min-width media query
/// // defined ins `$jigsass-breakpoints.length`.
/// bar: true, // Enables generation of the `.o-foo--bar--from-<bp-name>`
/// // class inside a min-width media query
/// // defined ins `$jigsass-breakpoints.length`.
/// ),
/// until-<bp-name>: (
/// no-modifier: true, // Enables generation of the `.o-foo--until-<bp-name>`
/// // class inside a max-width media query
/// // defined ins `$jigsass-breakpoints.length`.
/// bar: true, // Enables generation of the `.o-foo--bar--until-<bp-name>`
/// // class inside a max-width media query
/// // defined ins `$jigsass-breakpoints.length`.
/// ),
/// when-<bp-name>: (
/// no-modifier: true, // Enables generation of the `.o-foo--when-<bp-name>`
/// // class inside a misc media query
/// // defined ins `$jigsass-breakpoints.features`.
/// bar: true, // Enables generation of the `.o-foo--bar--when-<bp-name>`
/// // class inside a misc media query
/// // defined ins `$jigsass-breakpoints.features`.
/// ),
/// from-<bp-name>-until-<bp-name>: (...);
/// from-<bp-name>-when-<bp-name>: (...);
/// until-<bp-name>-when-<bp-name>: (...);
/// from-<bp-name>-until-<bp-name>-when-<bp-name>: (...);
/// );
/// ```
///
/// Regardless of how many times the `jigsass-object` mixin is
/// included, each selector will only be generated once.
///
/// If `$jigsass-silent` is set to `true` when the mixin
/// is first included for a certain selector, the selector
/// will not be generated, even if the mixin is later included
/// again for that selector when `$jigsass-silent` is set to false.
///
///
/// Use the `jigsass-classname` mixin inside this mixin's
/// body to define the base object and each of it's modifiers
/// **(See example below)**.
///
/// When calling the `jigsass-get-obj-mq` function without arguments
/// inside the `@contnet` block, it will return a map with `from`,
/// `until` and `misc` keys, holding the arguments passed to the
/// media query in the current context of `@content`.
///
/// When called with an argument of `from`, `until` or `misc`, the
/// `jigsass-get-obj-mq` will return the value of of that key from
/// the above map.
/// ---
/// @param() { ... }