@bem/entity-name

BemEntityName
=============

BEM entity name representation.

[![NPM Status][npm-img]][npm]
[![Travis Status][test-img]][travis]
[![Coverage Status][coverage-img]][coveralls]
[![Dependency Status][dependency-img]][david]

[npm]: https://www.npmjs.org/package/@bem/entity-name
[npm-img]: https://img.shields.io/npm/v/@bem/entity-name.svg

[travis]: https://travis-ci.org/bem-sdk/bem-entity-name
[test-img]: https://img.shields.io/travis/bem-sdk/bem-entity-name/master.svg

[coveralls]: https://coveralls.io/r/bem-sdk/bem-entity-name
[coverage-img]: https://img.shields.io/coveralls/bem-sdk/bem-entity-name/master.svg

[david]: https://david-dm.org/bem-sdk/bem-entity-name
[dependency-img]: http://img.shields.io/david/bem-sdk/bem-entity-name.svg

Contents
--------

* Install
* Usage
* API
* Serialization
* TypeScript support
* Debuggability
* Deprecation

Install
-------

``
$ npm install --save @bem/entity-name
`

Usage
-----

`js
const BemEntityName = require('@bem/entity-name');

const entityName = new BemEntityName({ block: 'button', elem: 'text' });

entityName.block; // button
entityName.elem; // text
entityName.mod; // undefined

entityName.id; // button__elem
entityName.type; // elem

entityName.isEqual(new BemEntityName({ block: 'button' })); // false
entityName.isEqual(new BemEntityName({ block: 'button', elem: 'text' })); // true
`

API
---

* constructor({ block, elem, mod })
* block
* elem
* mod
* type
* scope
* id
* isSimpleMod()
* isEqual(entityName)
* belongsTo(entityName)
* valueOf()
* toJSON()
* toString()
* static create(obj)
* static isBemEntityName(entityName)

$3

Parameter | Type | Description
----------|----------|------------------------------
block | string | The block name of entity.
elem | string | The element name of entity.
mod | string, object | The modifier of entity.

If specified value is string then it will be equivalent to { name: string, val: true }. Optional.
mod.name| string | The modifier name of entity.
mod.val | string, true | The modifier value of entity. Optional.

BEM entities can be defined with a help of JS object with the following fields:

* block — a block name. The field is required because only a block exists as an independent BEM entity
* elem — an element name.
* mod — a modifier.

The modifier consists of a pair of fields mod.name and mod.val. This means that the field mod.val without mod.name has no meaning.

`js
const BemEntityName = require('@bem/entity-name');

// The modifier of block
new BemEntityName({
block: 'button',
mod: { name: 'view', val: 'action' }
});

// Not valid modifier
new BemEntityName({
block: 'button',
mod: { val: 'action' }
});
// ➜ EntityTypeError: the object { block: 'block', mod: { val: 'action' } } is not valid BEM entity, the field mod.name is undefined
`

To describe a simple modifier the mod.val field must be omitted.

`js
// Simple modifier of a block
new BemEntityName({ block: 'button', mod: 'focused' });

// Is equivalent to simple modifier, if mod.val is true
new BemEntityName({
block: 'button',
mod: { name: 'focused', val: true }
});
`

$3

The name of block to which this entity belongs.

`js
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button' });

name.block; // button
`

$3

The element name of this entity.

If entity is not element or modifier of element then returns empty string.

`js
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', elem: 'text' });

name.elem; // text
`

$3

The modifier of this entity.

Important: If entity is not a modifier then returns undefined.

`js
const BemEntityName = require('@bem/entity-name');

const blockName = new BemEntityName({ block: 'button' });
const modName = new BemEntityName({ block: 'button', mod: 'disabled' });

modName.mod; // { name: 'disabled', val: true }
blockName.mod; // undefined
`

$3

The type for this entity.

Possible values: block, elem, blockMod, elemMod.

`js
const BemEntityName = require('@bem/entity-name');

const elemName = new BemEntityName({ block: 'button', elem: 'text' });
const modName = new BemEntityName({ block: 'menu', elem: 'item', mod: 'current' });

elemName.type; // elem
modName.type; // elemMod
`

$3

The scope of this entity.

Important: block-typed entities has no scope.

`js
const BemEntityName = require('@bem/entity-name');

const buttonName = new BemEntityName({ block: 'button' });
const buttonTextName = new BemEntityName({ block: 'button', elem: 'text' });
const buttonTextBoldName = new BemEntityName({ block: 'button', elem: 'text', mod: 'bold' });

buttonName.scope; // null
buttonTextName.scope; // BemEntityName { block: 'button' }
buttonTextBoldName.scope; // BemEntityName { block: 'button', elem: 'elem' }
`

$3

The id for this entity.

Important: should only be used to determine uniqueness of entity.

If you want to get string representation in accordance with the provisions naming convention you should use @bem/naming package.

`js
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'disabled' });

name.id; // button_disabled
`

$3

Determines whether modifier simple or not.

NOTE: For entity without modifier isSimpleMod() returns null.

`js
const BemEntityName = require('@bem/entity-name');
const modName = new BemEntityName({ block: 'button', mod: { name: 'theme' } });
const modVal = new BemEntityName({ block: 'button', mod: { name: 'theme', val: 'normal' } });
const block = new BemEntityName({ block: 'button' });

modName.isSimpleMod(); // true
modVal.isSimpleMod(); // false
block.isSimpleMod(); // null
`

$3

Parameter | Type | Description
-------------|-----------------|-----------------------
entityName | BemEntityName | The entity to compare.

Determines whether specified entity is the deepEqual entity.

`js
const BemEntityName = require('@bem/entity-name');

const inputName = new BemEntityName({ block: 'input' });
const buttonName = new BemEntityName({ block: 'button' });

inputName.isEqual(buttonName); // false
buttonName.isEqual(buttonName); // true
`

$3

Parameter | Type | Description
-------------|-----------------|-----------------------
entityName | BemEntityName | The entity to compare.

Determines whether specified entity belongs to this.

`js
const BemEntityName = require('@bem/entity-name');

const buttonName = new BemEntityName({ block: 'button' });
const buttonTextName = new BemEntityName({ block: 'button', elem: 'text' });
const buttonTextBoldName = new BemEntityName({ block: 'button', elem: 'text', mod: 'bold' });

buttonTextName.belongsTo(buttonName); // true
buttonName.belongsTo(buttonTextName); // false
buttonTextBoldName.belongsTo(buttonTextName); // true
buttonTextBoldName.belongsTo(buttonName); // false
`

$3

Returns normalized object representing the entity name.

`js
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'focused' });

name.valueOf();

// ➜ { block: 'button', mod: { name: 'focused', value: true } }
`

$3

Returns raw data for JSON.stringify() purposes.

`js
const BemEntityName = require('@bem/entity-name');

const name = new BemEntityName({ block: 'input', mod: 'available' });

JSON.stringify(name); // {"block":"input","mod":{"name":"available","val":true}}
`

$3

Returns string representing the entity name.

Important: if you want to get string representation in accordance with the provisions naming convention
you should use @bem/naming package.

`js
const BemEntityName = require('@bem/entity-name');
const name = new BemEntityName({ block: 'button', mod: 'focused' });

name.toString(); // button_focused
`

$3

Creates BemEntityName instance by any object representation or a string.

Helper for sugar-free simplicity.

Parameter | Type | Description
-------------|--------------------|--------------------------
object | object, string | Representation of entity name.

Passed Object could have the common field names for entities:

Object field | Type | Description
-------------|----------|------------------------------
block | string | The block name of entity.
elem | string | The element name of entity. Optional.
mod | string, object | The modifier of entity.

If specified value is string then it will be equivalent to { name: string, val: true }. Optional.
val | string | The modifier value of entity. Used if mod is a string. Optional.
mod.name | string | The modifier name of entity. Optional.
mod.val | string, true | The modifier value of entity. Optional.
modName | string | The modifier name of entity. Used if mod.name was not specified. Optional.
modVal | string, true | The modifier value of entity. Used if neither mod.val nor val were not specified. Optional.

`js
const BemEntityName = require('@bem/entity-name');

BemEntityName.create('my-button');
BemEntityName.create({ block: 'my-button' });
// ➜ BemEntityName { block: 'my-button' }

BemEntityName.create({ block: 'my-button', mod: 'theme', val: 'red' });
BemEntityName.create({ block: 'my-button', modName: 'theme', modVal: 'red' });
// ➜ BemEntityName { block: 'my-button', mod: { name: 'theme', val: 'red' } }

BemEntityName.create({ block: 'my-button', mod: 'focused' });
// ➜ BemEntityName { block: 'my-button', mod: { name: 'focused', val: true } }
`

$3

Determines whether specified entity is an instance of BemEntityName.

Parameter | Type | Description
-------------|-----------------|-----------------------
entityName | * | The entity to check.

`js
const BemEntityName = require('@bem/entity-name');

const entityName = new BemEntityName({ block: 'input' });

BemEntityName.isBemEntityName(entityName); // true
BemEntityName.isBemEntityName({ block: 'button' }); // false
`

Serialization
-------------

The BemEntityName has toJSON method to support JSON.stringify() behaviour.

Use JSON.stringify to serialize an instance of BemEntityName.

`js
const BemEntityName = require('@bem/entity-name');

const name = new BemEntityName({ block: 'input', mod: 'available' });

JSON.stringify(name); // {"block":"input","mod":{"name":"available","val":true}}
`

Use JSON.parse to deserialize JSON string and create an instance of BemEntityName.

`js
const BemEntityName = require('@bem/entity-name');

const str = '{"block":"input","mod":{"name":"available","val":true}}';

new BemEntityName(JSON.parse(str)); // BemEntityName({ block: 'input', mod: 'available' });
`

TypeScript support
------------------

The package includes typings for TypeScript. You have to set up transpilation yourself. When you set module to commonjs in your tsconfig.json file, TypeScript will automatically find the type definitions for @bem/entity-name.

The interfaces are provided in global namespace BEMSDK.EntityName. It is necessary to use interfaces in JsDoc.

Debuggability
-------------

In Node.js, console.log() calls util.inspect() on each argument without a formatting placeholder.

BemEntityName has inspect() method to get custom string representation of the object.

`js
const BemEntityName = require('@bem/entity-name');

const name = new BemEntityName({ block: 'input', mod: 'available' });

console.log(name);

// ➜ BemEntityName { block: 'input', mod: { name: 'available' } }
`

You can also convert BemEntityName object to string.

`js
const BemEntityName = require('@bem/entity-name');

const name = new BemEntityName({ block: 'input', mod: 'available' });

console.log(name: ${name});

// ➜ name: input_available
`

Deprecation
-----------

Deprecation is performed with depd.

To silencing deprecation warnings from being output use the NO_DEPRECATION environment variable.

`
NO_DEPRECATION=@bem/entity-name node app.js
`

> More details in depd` documentation

License
-------

Code and documentation © 2016 YANDEX LLC. Code released under the Mozilla Public License 2.0.