bem-import-notation

Tool for working with BEM import strings.

Extract BEM entities from import strings.

Installation

npm install --save @bem/import-notation

Usage

import {parse} from '@bem/import-notation';

parse('b:button e:text'); // → [ { block : 'button', elem : 'text' } ]

parse('b:button m:theme=normal|action');

// → [ { block : 'button' },
//     { block : 'button', mod : { name: 'theme' } },
//     { block : 'button', mod : { name: 'theme', val : 'normal' } },
//     { block : 'button', mod : { name: 'theme', val : 'action' } } ]

API

parse
stringify

parse(str, ctx)

Parameter	Type	Description
`str`	`string`	BEM import notation check notation section
`ctx`	`object`	BEM entity name representation.

Parses the string into BEM entities.

Example:

var entity = parse('b:button e:text')[0];
entity.block // → 'button'
entity.elem // → 'text'

ctx

Context allows to extract portion of entities.

var enties = parse('m:theme=normal', { block: 'button' });

// → [ { block: 'button' },
//     { block: 'button', mod: { name: 'theme' } },
//     { block: 'button', mod: { name: 'theme', val: 'normal' } } ]

stringify

Parameter	Type	Description
`entities`	`array`	Array of BEM entities to merge into import string notation

Forms a string from BEM entities. Be aware to merge only one type of entities. The array should contains one block or one elem and optionally it's modifiers.

Notation

This section describes all possible syntax of BEM import strings. Examples are provided in es6 syntax. Note that parse function only works with strings.

Right now order of fields is important, check issue:

b:
e:
m:
t:

block

import 'b:button';
// → [ { block: 'button' } ]

block with simple modifier

import 'b:popup m:autoclosable';
// → [ { block: 'popup', mod: { name: 'autoclosable' } } ]

block with modifier

import 'b:button m:theme=active';
// → [ { block: 'button', mod: { name: 'theme' } }
//     { block: 'button', mod: { name: 'theme', val: 'active' } } ]

block with several modifiers

import 'b:button m:theme=active m:size=m';
// → [ { block: 'button' },
//     { block: 'button', mod: { name: 'theme' } },
//     { block: 'button', mod: { name: 'theme', val: 'active' } },
//     { block: 'button', mod: { name: 'size' } },
//     { block: 'button', mod: { name: 'size', val: 'm' } } ]

block with modifier that has several values

import 'b:button m:theme=normal|active';
// → [ { block: 'button' },
//     { block: 'button', mod: { name: 'theme' } },
//     { block: 'button', mod: { name: 'theme', val: 'normal' } },
//     { block: 'button', mod: { name: 'theme', val: 'active' } } ]

element

import 'b:button e:text';
// → [ { block: 'button', elem: 'text' } ]

element with simple modifier

import 'b:popup e:tail m:autoclosable';
// → [ { block: 'popup', elem: 'tail' },
//     { block: 'popup', elem: 'tail', mod: { name: 'autoclosable' } } ]

element with modifier

import 'b:button e:text m:theme=active';
// → [ { block: 'button', elem: 'text' },
//     { block: 'button', elem: 'text', mod: { name: 'theme' } },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'active' } } ]

element with several modifiers

import 'b:button e:text m:theme=active m:size=m';
// → [ { block: 'button', elem: 'text' },
//     { block: 'button', elem: 'text', mod: { name: 'theme' } },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'active' } },
//     { block: 'button', elem: 'text', mod: { name: 'size' } },
//     { block: 'button', elem: 'text', mod: { name: 'size', val: 'm' } } ]

element with modifier that has several values

import 'b:button e:text m:theme=normal|active';
// → [ { block: 'button', elem: 'text' },
//     { block: 'button', elem: 'text', mod: { name: 'theme' } },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'normal' } },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'active' } } ]

technology

Technology is abstraction for extension on file system. Check docs.

Specify field t: to extract BEM entities with concretele technology.

import 'b:button t:css';
// → [ { block: 'button', tech: 'css' } ]

import 'b:button m:theme=active t:js';
// → [ { block: 'button', tech: 'js' },
//     { block: 'button', mod: { name: 'theme' }, tech: 'js' },
//     { block: 'button', mod: { name: 'theme', val: 'active' }, tech: 'js' } ]

import 'b:button e:text m:theme=normal|active t:css';
// → [ { block: 'button', elem: 'text', tech: 'css' },
//     { block: 'button', elem: 'text', mod: { name: 'theme' }, tech: 'css' },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'normal' }, tech: 'css' },
//     { block: 'button', elem: 'text', mod: { name: 'theme', val: 'active' }, tech: 'css' } ]