Package detail

@bem/sdk.naming.entity

bem117MPL-2.00.2.11

Manage naming of BEM entities

bem, naming, entity, name

readme

naming.entity

The tool for working with BEM entity representations:

parse a string representation;
stringify an object representation.

Introduction

This package combines the capabilities of the following packages:

@bem/sdk.naming.parse — to create a parse() function.
@bem/sdk.naming.stringify — to create a stringify() function.
@bem/sdk.naming.presets — to select a naming convention for these functions.

Various naming conventions are supported, such as origin, two-dashes and react. See the full list of supported presets in the package documentation.

You can also create a custom naming convention and use it for creating the parse() and stringify() functions.

Try naming.entity

An example is available in the RunKit editor.

Quick start

Attention. To use @bem/sdk.naming.entity, you must install Node.js 8.0+.

To run the @bem/sdk.naming.entity package:

Installing the `@bem/sdk.naming.entity` package

To install the @bem/sdk.naming.entity package, run the following command:

$ npm install --save @bem/sdk.naming.entity

Creating a `naming.entity` instance

To create a naming.entity instance, insert the following lines into your code:

const bemNaming = require('@bem/sdk.naming.entity');

By default, the created instance is based on the origin preset that represents the default naming convention for BEM entities. To use another preset, see Using the specified naming convention.

Using the created instance

Now you can use the created instance to parse and stringify BEM entity name representations.

Parse a string representation

bemNaming.parse('my-block__my-element');

This code will return the BemEntityName object with the block name my-block and the element name my-element.

Stringify an object representation

bemNaming.stringify({ block: 'my-block', mod: 'my-modifier' });

This code will return the string my-block_my-modifier.

API Reference

bemNaming()

This function creates a naming.entity instance with the parse() and stringify() functions.

/**
 * @typedef INamingConventionDelims
 * @property {string} elem — Separates an element name from block.
 * @property {string|Object} mod — Separates a modifier name and the value of a modifier.
 * @property {string} mod.name — Separates a modifier name from a block or an element.
 * @property {string|boolean} mod.val — Separates the value of a modifier from the modifier name.
 */

/**
 * @param {(Object|string)} [options] — User options or the name of the preset to return.
 *                                      If not specified, the default preset will be used.
 * @param {string} [options.preset] — Preset name that should be used as the default preset.
 * @param {Object} [options.delims] — Strings to separate names of bem entities.
 *                                    This object has the same structure as `INamingConventionDelims`,
 *                                    but all properties inside are optional.
 * @param {string} [options.wordPattern] — A regular expression that will be used to match an entity name.
 * @returns {Object} — Created instance with the `parse()` and `stringify()` functions.
 */
create(options);

Examples:

const defaultNaming = require('@bem/sdk.naming.entity');
const reactNaming = require('@bem/sdk.naming.entity')('react');
const customNaming = require('@bem/sdk.naming.entity'){ wordPattern: '[a-z]+' };

See more examples in the Parameter tuning section.

parse()

Parses the string with a BEM entity name into an object representation.

/**
 * @typedef BemEntityName
 * @property {string} block — Block name.
 * @property {string} [elem] — Element name.
 * @property {string|Object} [mod] — Modifier name or object with name and value.
 * @property {string} mod.name — Modifier name.
 * @property {string} [mod.val=true] — Modifier value.
 */

/**
 * @param {string} str — String representation of a BEM entity.
 * @returns {(BemEntityName|undefined)}
 */
parse(str);

Example:

const bemNaming = require('@bem/sdk.naming.entity');

bemNaming.parse('my-block__my-element_my-modifier_some-value');
// => BemEntityName {
//     block: 'my-block',
//     elem: 'my-element',
//     mod: { name: 'my-modifier', val: 'some-value' }
// }

For more information about the parse() function, see the @bem/sdk.naming.parse package documentation.

stringify()

Forms a string from the object that specifies a BEM entity name.

/**
 * @typedef BemEntityName
 * @property {string} block — Block name.
 * @property {string} [elem] — Element name.
 * @property {string|Object} [mod] — Modifier name or object with name and value.
 * @property {string} mod.name — Modifier name.
 * @property {string|boolean} [mod.val] — Modifier value.
 */

/**
 * @param {object|BemEntityName} entity — Object representation of a BEM entity.
 * @returns {string} — BEM entity name. This name can be used in class attributes.
 */
stringify(entity);

Example:

const bemNaming = require('@bem/sdk.naming.entity');

const bemEntityName = {
    block: 'my-block',
    elem: 'my-element',
    mod: { name: 'my-modifier', val: 'some-value' }
}

console.log(bemNaming.stringify(bemEntityName));
// => my-block__my-element_my-modifier_some-value

For more information about the stringify() function, see the @bem/sdk.naming.stringify package documentation.

Parameter tuning

Using a specified naming convention

The @bem/sdk.naming.presets package provides presets with various naming conventions.

Specify the name of a preset to use in the bemNaming() function. See the full list of supported presets in the package documentation.

Example:

const createBemNaming = require('@bem/sdk.naming.entity');
const myEntity = {
    block: 'my-block',
    elem: 'my-element',
    mod: {
        name: 'my-modifier',
        val: 'some-value'
    }
};

// Create the new instance from the `two-dashes` preset.
const twoDashes = createBemNaming('two-dashes');
twoDashes.stringify(myEntity);
// => my-block__my-element--my-modifier_some-value

// Create an instance from the `react` preset.
const react = createBemNaming('react');
react.stringify(myEntity);
// => my-block-my-element_my-modifier_some-value

RunKit live example.

Using a custom naming convention

To use a custom naming convention, create an object that will overwrite the default naming convention parameters. Pass this object in the bemNaming() function.

For example, overwrite the modifier value delimiter and use the equal sign (=) as the delimiter.

Example:

const createBemNaming = require('@bem/sdk.naming.entity');
const myNamingOptions = {
    delims: {
        mod: { val: '=' }
    }
};
const myNaming = createBemNaming(myNamingOptions);

// Parse a BEM entity name to test created instance.
myNaming.parse('my-block_my-modifier=some-value');
/**
 * => BemEntityName {
 *  block: 'my-block',
 *  mod: { name: 'my-modifier', val: 'some-value' } }
 */

// Stringify an object representation of the BEM entity name.
const myEntity = {
    block: 'my-block',
    elem: 'my-element',
    mod: {
        name: 'my-modifier',
        val: 'some-value'
    }
};
myNaming.stringify(myEntity);
// => my-block__my-element_my-modifier=some-value

RunKit live example.

Using another preset as default

The default preset is origin, but you can set another preset as default in the options.preset parameter.

For example, set the two-dashes preset as the default and create a naming.entity instance based on it.

Example:

const createBemNaming = require('@bem/sdk.naming.entity');
const myNamingOptions = {
    preset: 'two-dashes',
    delims: {
        mod: { val: '=' }
    }
};

const myNaming = createBemNaming(myNamingOptions);

// Parse a BEM entity name to test created preset.
myNaming.parse('my-block--my-modifier=some-value');
/**
 * => BemEntityName {
 * block: 'my-block',
 * mod: { name: 'my-modifier', val: 'some-value' } }
 */

// Stringify an object representation of the BEM entity name.
const myEntity = {
    block: 'my-block',
    elem: 'my-element',
    mod: {
        name: 'my-modifier',
        val: 'some-value'
    }
};
myNaming.stringify(myEntity);
// => my-block__my-element--my-modifier=some-value

RunKit live example.

Usage examples

Convert a string to the Two Dashes style

In this example, we will convert the string from the origin naming convention to Two Dashes.

Origin: my-block__my-element_my-modifier_some-value

Two Dashes: my-block__my-element--my-modifier_some-value

Example:

const originNaming = require('@bem/sdk.naming.entity');
const twoDashesNaming = require('@bem/sdk.naming.entity')('two-dashes');

const bemEntityNameStr = 'my-block__my-element_my-modifier_some-value'

const bemEntityNameObj = originNaming.parse(bemEntityName);
// => BemEntityName {
//     block: 'my-block',
//     elem: 'my-element',
//     mod: { name: 'my-modifier', val: 'some-value' }
// }

twoDashesNaming.stringify(bemEntityNameObj);
// => my-block__my-element--my-modifier_some-value

RunKit live example.

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.