Merge pull request #110 from bem-sdk/issue-100

Scope field

Author: blond

README.md

@@ -64,6 +64,7 @@ API
 * [elem](#elem)
 * [mod](#mod)
 * [type](#type)
+* [scope](#scope)
 * [id](#id)
 * [isSimpleMod()](#issimplemod)
 * [isEqual(entityName)](#isequalentityname)
@@ -178,6 +179,24 @@ elemName.type; // elem
 modName.type;  // elemMod
 ```
 
+### scope
+
+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' }
+```
+
 ### id
 
 The id for this entity.

index.d.ts

@@ -9,6 +9,7 @@ declare class BemEntityName {
     readonly modName: string | undefined;
     readonly modVal: string | true | undefined;
     readonly type: BemSDK.EntityName.TYPE;
+    readonly scope: BemEntityName | null;
     readonly id: string;
 
     isSimpleMod(): boolean | null;

lib/entity-name.js

@@ -156,6 +156,36 @@ class BemEntityName {
         return this._type;
     }
 
+    /**
+     * Returns scope of this entity.
+     *
+     * Important: block-typed entities has no scope.
+     *
+     * @example
+     * 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' }
+     *
+     * @returns {BemEntityName} - scope entity name.
+     */
+    get scope() {
+        if (this.type === TYPES.BLOCK) { return null; }
+        if (this._scope) { return this._scope; }
+
+        this._scope = new BemEntityName({
+            block: this.block,
+            elem: this.type === TYPES.ELEM_MOD && this.elem
+        });
+
+        return this._scope;
+    }
+
     /**
      * Returns id for this entity.
      *
@@ -238,6 +268,7 @@ class BemEntityName {
      *
      * buttonTextName.belongsTo(buttonName); // true
      * buttonName.belongsTo(buttonTextName); // false
+     *
      * buttonTextBoldName.belongsTo(buttonTextName); // true
      * buttonTextBoldName.belongsTo(buttonName); // false
      *

test/scope.test.js

@@ -0,0 +1,50 @@
+import test from 'ava';
+
+import BemEntityName from '../lib/entity-name';
+
+test('should return scope of block', t => {
+    const entityName = new BemEntityName({ block: 'block' });
+
+    t.is(entityName.scope, null);
+});
+
+test('should return scope of block modifier', t => {
+    const entityName = new BemEntityName({ block: 'block', mod: 'mod' });
+
+    t.deepEqual(entityName.scope.valueOf(), { block: 'block' });
+});
+
+test('should return same scope for simple and complex mod', t => {
+    const simpleModName = new BemEntityName({ block: 'block', mod: 'mod' });
+    const complexModName = new BemEntityName({ block: 'block', mod: { name: 'mod', val: 'val' } });
+
+    t.deepEqual(simpleModName.scope, complexModName.scope);
+});
+
+test('should return scope of element', t => {
+    const entityName = new BemEntityName({ block: 'block', elem: 'elem' });
+
+    t.deepEqual(entityName.scope.valueOf(), { block: 'block' });
+});
+
+test('should return scope of element modifier', t => {
+    const entityName = new BemEntityName({ block: 'block', elem: 'elem', mod: 'mod' });
+
+    t.deepEqual(entityName.scope.valueOf(), { block: 'block', elem: 'elem' });
+});
+
+test('should cache scope value', t => {
+    const entity = new BemEntityName({ block: 'block', elem: 'elem' });
+
+    entity.scope; // eslint-disable-line no-unused-expressions
+
+    t.deepEqual(entity._scope.valueOf(), { block: 'block' });
+});
+
+test('should get scope from cache', t => {
+    const entity = new BemEntityName({ block: 'block', elem: 'elem' });
+
+    entity._scope = 'fake';
+
+    t.is(entity.scope, 'fake');
+});