bem / bem-core

BEM Core Library

bem-core library

Documentation on bem-core in a much more informative way is also available at bem.info. It is also available in Russian.

What is this?

bem-core is a base library for web interface development. It provides the minimal stack for coding client-side JavaScript and templating.

Use

The easiest way to run a project with bem-core is to use the project-stub.

You can use any other way you are familiar with to include the library into the project.

Inside

Levels

• common.blocks — suited for any devices and browsers
• desktop.blocks — should be used for desktop browsers
• touch.blocks — implement some touch-platforms specifics

Blocks

• i-bem — base block with helpers for JS and HTML
• strings — helpers for JS-strings
• objects — helpers for JS-objects
• functions — helpers for JS-functions
• events — JS-events
• querystring — helpers for work with querystring
• tick — global timer
• idle — IDLE event
• next-tick — polyfill for nextTick/setTimeout(0, ...)
• inherit — OOP helpers
• jquery — jQuery
• clearfix — CSS clearfix trick
• identify — identify JS-objects
• cookie — helpers for work with browser cookies
• vow — Promises/A+ implementation
• dom — helpers for work with DOM
• loader — loader for JS files
• ua — browser features detection
• keyboard — keyboard helpers
• page — html/head/body scaffold

Technologies

• vanilla.js + browser.js
• bemhtml
• bemtree

API

The autogenerated JSDoc API can be found on bem.info. E.g. JSDoc for i-bem is here https://en.bem.info/platform/libs/bem-core/current/desktop/i-bem/#jsdoc

Changelog

You can check the changelog at the Changelog page.

Migration

If you used BEM before, check the migration instructions.

Development

Working copy

1. Get the needed version code (e.g., v4):

   $ git clone -b v4 git://github.com/bem/bem-core.git
   $ cd bem-core

2. Install the dependencies:

   $ npm install

   You need export PATH=./node_modules/.bin:$PATH or an alternative way to run locally-installed npm dependencies.

3. Install all necessary libraries:

   $ npm run deps

4. Build and run tests (specs):

   $ npm test

5. Run development server:

   $ npm start

How to contribute

Please refer to How to contribute guide.

Modular testing

A default test bundle for functions__debounce:

$ magic make desktop.specs/functions__debounce

You can see the results of the tests in the terminal after the building process finishes.

You can also watch them in a browser loading desktop.specs/functions__debounce/spec-js+browser-js+bemhtml/spec-js+browser-js+bemhtml.html.

Run tests for other BEM entities in the same way. This will work for those which are equipped with .spec.js file.

Code coverage

To build code coverage report add ISTANBUL_COVERAGE=yes environment variable to the tests run command:

$ ISTANBUL_COVERAGE=yes magic make desktop.specs && istanbul report html

You can run modular testing with coverage as well by using more concrete build target as was described above.

$ ISTANBUL_COVERAGE=yes magic make desktop.specs/functions__debounce && istanbul report html

After tests finish, you can view coverage HTML report by opening coverage/index.html in your favorite browser.

The whole code coverage statistics can be found on the bem-core profile page on Coveralls.

Tests are built with a enb-bem-specs library. Check the details (available in Russian only).

Supported browsers

Our browser support policy is based on statistics we get from Yandex services.

Browsers with more than 2% users get full compliant support, more than 0.5% — partially compliant (which means that data is accessible but not necessary 100% functional). New features testing is not provided by us for  browsers with less than 0.5% users.

Desktop

Fully compliant

• Google Chrome 29+
• Firefox 24+
• Yandex 1.7+
• Opera 12.16
• MSIE 10.0
• MSIE 9.0
• MSIE 8.0
• Opera 12.15

Partially compliant

• Opera 17.0
• Opera 16.0
• Opera 12.14
• Opera 12.2
• Firefox 23

Touch

Fully compliant

• iOS 6+
• Android 2.3+
• Opera Mobile 12+
• Windows Phone 7+

Partially compliant

• iOS 5
• Android 2.2

License

Code and documentation copyright 2012 YANDEX LLC. Code released under the Mozilla Public License 2.0.

bem-core's Issues

techs-docs infrastructure

• tech-docs tech that creates level
• docs tech that create level

i-bem.test.js: Use new testing infrastructure

Depends on #46.

bem-core roadmap

\cc @veged @arikon

Нужно набросать примерный roadmap на проект (отдельным документом), чтобы было понятно, когда планируется отрывать DEPRECATED-методы и на который потом, можно будет ссылаться для обоснования тех или иных решений.

Add tests for "functions" module

Tests infrastructure

https://github.com/narqo/bem-pr/blob/master/docs/tests.ru.md

Add jshint-groups, jscs and pre-commit hooks

BEM-dependencies should be downloaded to libs folder

We should download bem-dependencies to libs folder so we will type bem make libs to dowload all libraries.

bem-bl: Move `b-link` somewhere

Documentation about `.bemtree.xjst` tech

i-bem: Introduce `BEM.DOM.scope` for use in `_conflicts_no` version

So we can use BEM.DOM.doc for real document interaction and BEM.DOM.scoupe for live-events and so on. In case without _conflicts_no BEM.DOM.doc === BEM.DOM.scoupe.

i-bem: `this.nextTick` for correct unbind on block destruct

Travis CI integration

Actualize tests for i-bem block

i-bem.bemhtml: Check for modification of `Object.prototype` and omit `hasOwnProperty` in `for-in` loops

Replacement for `$.browser`

We need replacement for deprecated $.browser. Variants:

• port $.browser to bem-core as plugin -- The Easiest One
• add all this stuff to ua block -- The Right One

BEMTREE: Possibility to separate browser and private server templates

By analogy with JS (*.browser.js, *.node.js, *.vanilla.js) we can make *.browser.bemtree.xjst, *.node.bemtree.xjst, *.vanilla.bemtree.xjst.

Add sinon-chai plugin to tests infrastructure

https://github.com/domenic/sinon-chai

i-bem API reference

BEMTREE: Drop `.xjst` from `.bemtree.xjst` file extension

i-bem__dom: add elemify method

i-bem: Bind DOM-events in once-mode

Like in jQuery .one().

Recover documentation

Some files from common.docs are missed in v1.

Documentation about js-syntax for BEMHTML

touch.blocks/ua: Provide user agent information through modules API

Check difference between master and v1

It turned out there's difference between code in v1 and in master (before it was removed).

I recovered documentation (#90) but there's at leat some other differencies in .bem folder:

git st
# On branch issues/81@v1
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#   modified:   .bem/lib/bemhtml.js
#   modified:   .bem/lib/bemhtml/api.js
#   modified:   .bem/techs/bemhtml.js
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#   .bem/lib/ometa/
#   .bem/techs/js-i.js
#   .bem/techs/js.js

I don't understand if it's useful or not, please take a look. Also I'm not sure if everything else was synced at the moment you started work on v1.

Блок `Promise` в core

Я думал вносить i-bem.bemtree.xjst из bem-yana-stub в bem-core, но осознал, что результат вызовава BEMTREE.applyAsync() возвращает Vow-промис.

Внимание, вопрос, в bem-core, все это нужно? Или куда это девать?

\cc @veged @arikon @dfilatov

bem-bl: Move `b-icon` somewhere

Configure default techs for blocks on levels `.bem/levels/*`

BEM.I18N: Use modules

Depend on #58.

cc @dfilatov

Технология deps с расширением на основе технологии *js

Модуль data-provider

\cc @dfilatov @veged

Хочу портировать i-request (и соответственно, его _type_ajax) в bem-core. Но меня смущает название. request неоднозначно описывает, зачем этот блок (по крайней мере в технологии node.js).

Предлагаю назвать блок data-provider и реализовать там базовый интерфейс. Потом от него наследовать http-provider (для AJAX и HTTP -запросов в browser.js и node.js соответственно).

Потом можно реализовывать file-provider и пр.

Что скажите?

Move bemhtml docs to i-bem.tech-docs

Use `[email protected]` in `project-stub`

https://github.com/bem/project-stub/tree/bem-core

Because of using ymodules system there is no more need in most of `mustDeps` usage

Use js-techs from bem-tools

See bem-archive/bem-tools#391

Модульная система для js

Для решения проблем:

• Избавление от зависимости от jQuery того кода, который от него в реальности не зависит
• Избавление от глобальных неймспейсов
• Реальная асинхронность деклараций модулей
• Возможность писать одни и те же модули для браузеров и серверных движков
• Возможность додекларации модулей

начинаем использовать модульную систему https://github.com/ymaps/modules.

next-tick: Optional context argument

ua: API for desktop and touch should be consistent

Add tests for extracting mods from html

i-bem: Rethink cancelation of modifiers set and events on modifiers set

Port i18n from `bem-bl`

Add tests for "events" module

Add documentation to README.md

Add documentation (or links) and API reference to README.md

Fix css/js links in `page` examples

Deprecation policy

Add deprecation policy document that will describe how features are maintained, deprecated and deleted.

Start of the discussion #35

Bower package description

We should add bower package description as a part of libraries infrastructure to allow installation of bem libs as a bower packages

BEMTREE: Generate final .bemtree.xjst.js with `modules.define`

Migration guide from `bem-bl` to `[email protected]`

i-bem.bemtree.xjst: Use js-syntax

Review i-bem.bemhtml

cc @veged