BEM Components Library

What is this?

bem-components is a library of blocks providing ready-made form controls and some other blocks. It contains base realizations of blocks that are abstracted from the design. Few optional design themes are available.

Usage

You can use any way you are familiar with to include this library into your project. E.g. you can use bem-tools or ENB.

Supported browsers

• Desktop:
  • Firefox 30+
  • Chrome last 2 versions
  • Safari 6.0+
  • Opera 12.1+
  • Internet Explorer 9+
• Touch-pad:
  • Android 4+
  • iOS 5+
• Touch-phone:
  • Android 4+
  • iOS 6+
  • Windows Phone 8+ (Internet Explorer 10+)

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

• attach
• button
• checkbox
• checkbox-group
• control
• control-group
• dropdown
• icon
• image
• input
• link
• menu
• menu-item
• popup
• radio
• radio-group
• select
• spin
• textarea
• z-index-group

Technologies

• JS
• YModules
• BEMHTML
• BH
• BEMTREE
• Stylus

Changelog

You can check the changelog at the changelog page.

Migration

Migartion guide is here.

Maintainers

• veged
• dfilatov
• mishanga

Development

Working copy

1. Get the source code:

$ git clone git://github.com/bem/bem-components.git
$ cd bem-components

1. Install the dependencies:

$ npm install

You need export PATH=./node_modules/.bin:$PATH or any alternative way to run locally-installed ENB.

Install all necessary libraries:

$ bower install

Build and run tests and examples:

$ npm run build-all

Run development server:

$ enb server

Check the code-style:

$ npm run lint

How to contribute

1. Create an issue with a proper description.
2. Decide which version needs your changes.
3. Create a feature branch with an issue number and a version (issues/<issue_number>@v<version_number>) based on a version branch. For example, for an issue #42 and a version 2: git checkout -b issues/42@v2. If you need changes for several versions, each of them has to have a feature branch.
4. Commit changes (you can test your changes running npm test) and push. Rebase your branch on a corresponding version branch if needed.
5. Create a pull request from your feature branch; or several pull requests if you changed several versions.
6. Link your pull request with an issue number any way you like. For example, leave a comment with the issue number.
7. Wait for your pull request and the issue to be closed ;-)

Modular testing

JavaScript unit tests

To run JS unit tests use npm run test-specs command. You may also specify the target, e.g. enb make specs desktop.specs/input to run just input tests.

All tests will be run automatically using Travis on each pull request.

Regrassion tests of layout

We use gemini for layout testing.

Tests for each block are stored in a separate file block-name.gemini.js in a directory gemini/. All tests could be executed manually or automatically using Travis. We use SauceLabs service as a Selenium Grid.

Use OpenSauce account in SauceLabs and Sauce Connect utility to run tests locally.

Developers of BEM team could use bem-components account (we do not publish login and password because of the limit for three concurrent browsers launch; it is much more efficiently to use different free accounts for manual testing).

For tests execution you need the following:

1. Set up environment variables (SAUCE_USERNAME and SAUCE_ACCESS_KEY).
2. Run sc utility (SauceConnect) and wait for a tunnel initialization.
3. Run the tests using npm run gemini.
4. To collect new versions of the screenshots use npm run gemini-gather.

In case you write new tests for local usage, you can run your own Selenium Server or PhantomJS with WebDriver server. For this:

1. Install and run selenium-server or phantomjs.
2. Correct gridUrl option to http://localhost:4444/ in .gemini.yml file.
3. Run tests (see above).

Detailed description of gemini work with different types of backends find here.

NB You have to commit screenshots to the repository from SauceLabs to avoid minor differencies in fonts rendering.

Befor commit some new or modified pattern you have to:

1. Check the validity. If in doubt, use Araxis Merge utility or something like this to see the difference between two versions of the pattern.
2. Compress them using ImageOptim utility (this is the most effective tool for images compression for May 2014).

Tests for templates

Build tools for the library allow you to build and run tests on BEMHTML and BH block templates.

To add a test for a block, you need to add a directory named [block name].tmpl-specs on your definition level. All test files will be stored in it.

Each test consists of a pair of files implemented in following technologies: BEMJSON and HTML. Each block could have more then one pair of such files. You could give any name to the file. But the file names (without extensions) within the one pair for one test must coincide. For example, 10-default.bemjson.js and 10-default.html.

For each block:

• BEMJSON file contains an example for a block;
• HTML file contains standard HTML-code – a block sample.

Block sample in HTML is a block implementation result that becomes available after applying a template to the BEMJSON example.

desktop.blocks
    └── myblocks
        ├── myblock.bemhtml.js
        ├── myblock.bh.js
        ├── ...
        └── myblock.tmpl-specs
            ├── 10-default.bemjson.js
            ├── 10-default.html
            ├── 20-advanced.bemjson.js
            └── 20-advanced.html

To run tests for templates use:

enb make tmpl-specs or npm run test-tmpls

To run tests for required definition level use:

enb make tmpl-specs desktop.tmpl-specs

To run tests for a specific block use:

enb make tmpl-specs desktop.tmpl-specs/button

If build procedure is successful, tests will be run automatically. After that you will see all test results.

If the result of applying the template does not match with the block sample in HTML, then you will see errors in the log with description of the difference from the block sample.

All tests will be run automatically using Travis for each pull request.