Skip to content

Commit

Permalink
[UI Framework] Reorganize UI Framework and add Yeoman generator (elas…
Browse files Browse the repository at this point in the history
…tic#13172)

* Reorganize documentation styles so they all live in doc_site/components directory. (elastic#12809)
  - Remove global styles, e.g. body and html element selectors.
* Create global_styles dir with sub-directories. (elastic#12833)
* Add SCSS style guide. (elastic#12850)
* Refactor UI Framework directory structure to house everything in a src directory. (elastic#12880)
  - Add components/index.js and services/index.js files to continue to export JS modules from the root.
* Add KUI Yeoman generator.
* Support creation of components.
* Add documentation generator for main page, demo, and sandbox.
  - Add additional documentation snippets to KUI generator. (elastic#13076)
  - Fix incorrect use of double quotes in KUI generator snippet. (elastic#13086)
  - Remove infrequently used imports from the KUI generator test template. (elastic#13110)
* Mock assets files for Jest. (elastic#13060)
* Fix broken coverage report paths in Jest config. (elastic#13082)
* Update eslint config to lint the new UI Framework directory structure. (elastic#13102)
* Fix positioning of doc site pagination buttons. (elastic#13203)
* Support hasReact prop for sandboxes. (elastic#13270)
* Remove deprecated used of component mixin from KUI generator's SCSS template. (elastic#13377)
* Fix rebasing errors.
  - Add dashboard back to Jest config.
  - Add missing form and tool_bar variables.
* Rename tasks to createComponent and documentComponent.
* Reference correct src paths in README.
* Add children and className to templates' propTypes.
* Add default folder name for page demo.
* Add suffix to sandbox routes.
* Specify testPathIgnorePatterns more clearly.
* Rename component.test.js to test.js so that Jenkins won't try to run it.
* Update npm scripts to depend on local yo dependency, not global.
* Add ui_framework/src to copy task.
* Simplify npm scripts and remove requirement for installing Yeoman from README.
* Add services to moduleNameMapper in jest config.
* Clean up Button and Gallery examples.
  • Loading branch information
cjcenizal committed Aug 11, 2017
1 parent 84e74f5 commit bb065f5
Show file tree
Hide file tree
Showing 429 changed files with 1,356 additions and 578 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,4 @@ selenium
ui_framework/doc_site/build
!ui_framework/doc_site/build/index.html
yarn.lock
.yo-rc.json
1 change: 1 addition & 0 deletions STYLEGUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ recommended for the development of all Kibana plugins.
- [Angular](style_guides/angular_style_guide.md)
- [React](style_guides/react_style_guide.md)
- [CSS](style_guides/css_style_guide.md)
- [SCSS](style_guides/scss_style_guide.md)
- [HTML](style_guides/html_style_guide.md)
- [API](style_guides/api_style_guide.md)
- [Architecture](style_guides/architecture_style_guide.md)
Expand Down
9 changes: 7 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,9 @@
"mocha": "echo 'use `node scripts/mocha`' && false",
"sterilize": "grunt sterilize",
"uiFramework:start": "grunt uiFramework:start",
"uiFramework:build": "grunt uiFramework:build"
"uiFramework:build": "grunt uiFramework:build",
"uiFramework:createComponent": "yo ./ui_framework/generator-kui/app/component.js",
"uiFramework:documentComponent": "yo ./ui_framework/generator-kui/app/documentation.js"
},
"repository": {
"type": "git",
Expand Down Expand Up @@ -208,6 +210,7 @@
"angular-mocks": "1.4.7",
"babel-eslint": "7.2.3",
"chai": "3.5.0",
"chalk": "2.0.1",
"chance": "1.0.6",
"cheerio": "0.22.0",
"chokidar": "1.6.0",
Expand Down Expand Up @@ -275,7 +278,9 @@
"supertest": "3.0.0",
"supertest-as-promised": "2.0.2",
"tree-kill": "1.1.0",
"webpack-dev-server": "1.14.1"
"webpack-dev-server": "1.14.1",
"yeoman-generator": "1.1.1",
"yo": "2.0.0"
},
"engines": {
"node": "6.11.1",
Expand Down
17 changes: 10 additions & 7 deletions src/jest/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,16 @@
"<rootDir>/ui_framework/"
],
"collectCoverageFrom": [
"ui_framework/services/**/*.js",
"!ui_framework/services/index.js",
"!ui_framework/services/**/*/index.js",
"ui_framework/components/**/*.js",
"!ui_framework/components/index.js",
"!ui_framework/components/**/*/index.js"
"ui_framework/src/components/**/*.js",
"!ui_framework/src/components/index.js",
"!ui_framework/src/components/**/*/index.js",
"ui_framework/src/services/**/*.js",
"!ui_framework/src/services/index.js",
"!ui_framework/src/services/**/*/index.js"
],
"moduleNameMapper": {
"^ui_framework/components": "<rootDir>/ui_framework/components",
"^ui_framework/services": "<rootDir>/ui_framework/services",
"\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": "<rootDir>/src/jest/file_mock.js",
"\\.(css|less|scss)$": "<rootDir>/src/jest/style_mock.js"
},
Expand All @@ -29,7 +30,9 @@
"**/*.test.js"
],
"testPathIgnorePatterns": [
"<rootDir>[/\\\\]ui_framework[/\\\\](dist|doc_site|jest)[/\\\\]"
"<rootDir>/ui_framework/dist/",
"<rootDir>/ui_framework/doc_site/",
"<rootDir>/ui_framework/generator-kui/"
],
"transform": {
"^.+\\.js$": "<rootDir>/src/jest/babelTransform.js"
Expand Down
5 changes: 4 additions & 1 deletion src/ui/public/modals/confirm_modal.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@ import { ModalOverlay } from './modal_overlay';

const module = uiModules.get('kibana');

import { CONFIRM_BUTTON, CANCEL_BUTTON } from 'ui_framework/components/modal/confirm_modal';
import {
KUI_MODAL_CONFIRM_BUTTON as CONFIRM_BUTTON,
KUI_MODAL_CANCEL_BUTTON as CANCEL_BUTTON,
} from 'ui_framework/components';

export const ConfirmationButtonTypes = {
CONFIRM: CONFIRM_BUTTON,
Expand Down
16 changes: 16 additions & 0 deletions style_guides/css_style_guide.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,22 @@

# CSS Style Guide

## Original style guide

Our style guide is an extension of [CSS Guidelines by Harry Roberts](https://cssguidelin.es/). The rules we especially focus on are:

* [Multiple files](https://cssguidelin.es/#multiple-files)
* [Indenting](https://cssguidelin.es/#indenting)
* [Commenting](https://cssguidelin.es/#commenting)
* [Naming conventions](https://cssguidelin.es/#naming-conventions) (see "Naming convention", below, for exceptions)
* [CSS selectors](https://cssguidelin.es/#css-selectors)
* [Specificity](https://cssguidelin.es/#specificity)
* [Architectural principles](https://cssguidelin.es/#architectural-principles)

Please see the [SCSS Style Guide](scss_style_guide.md) for additional rules pertaining to SCSS.

## Contents

- [CSS Style Guide](#css-style-guide)
- [Selecting elements](#selecting-elements)
- [Using the preprocessor](#using-the-preprocessor)
Expand Down
16 changes: 16 additions & 0 deletions style_guides/scss_style_guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@

# SCSS Style Guide

## Original style guide

Our style guide is an extension of [Sass Guidelines by Hugo Giraudel](https://sass-guidelin.es/). The rules we especially focus on are:

* [Syntax & formatting](https://sass-guidelin.es/#syntax--formatting) (exceptions below)
* [Naming conventions](https://sass-guidelin.es/#naming-conventions) (see the [CSS Style Guide](css_style_guide.md) for infomation on exceptions)
* [Variables](https://sass-guidelin.es/#variables)
* [Mixins](https://sass-guidelin.es/#mixins)

## Syntax and formatting

The Sass Guidelines site recommends using RBG and HSL values to format colors, but we're using
hex values.
1 change: 1 addition & 0 deletions tasks/config/copy.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ module.exports = function () {
'ui_framework/components/**',
'ui_framework/services/**',
'ui_framework/dist/**',
'ui_framework/src/**',
'webpackShims/**',
'config/kibana.yml',
],
Expand Down
5 changes: 3 additions & 2 deletions tasks/config/eslint.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ export default grunt => ({
'scripts',
'tasks',
'test',
'ui_framework/components',
'ui_framework/doc_site',
'ui_framework/src',
'ui_framework/doc_site/src',
'ui_framework/generator_kui',
'utilities',
'webpackShims',
],
Expand Down
4 changes: 2 additions & 2 deletions tasks/ui_framework.js
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ module.exports = function (grunt) {
}

function uiFrameworkCompile() {
const src = 'ui_framework/components/index.scss';
const src = 'ui_framework/src/index.scss';
const dest = 'ui_framework/dist/ui_framework.css';

return new Promise(resolve => {
Expand Down Expand Up @@ -130,7 +130,7 @@ module.exports = function (grunt) {
return new Promise(() => {
debouncedCompile();

chokidar.watch('ui_framework/components', { ignoreInitial: true }).on('all', (event, path) => {
chokidar.watch('ui_framework/src', { ignoreInitial: true }).on('all', (event, path) => {
grunt.log.writeln(event, path);
debouncedCompile();
});
Expand Down
109 changes: 80 additions & 29 deletions ui_framework/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,48 +21,91 @@ fully-tested the code is.

See the documentation in [`scripts/jest.js`](../scripts/jest.js) for more options.

### React components

Here are the components you can import from the Framework:

```javascript
import {
KuiButton,
KuiButtonGroup,
KuiButtonIcon,
} from '../path/to/ui_framework/components';
```

## Creating components

There are four steps to creating a new component:

1. Create the SCSS for the component in `ui_framework/components`.
1. Create the SCSS for the component in `ui_framework/src/components`.
2. Create the React portion of the component.
3. Document it with examples in `ui_framework/doc_site`.
4. Write tests.
3. Write tests.
4. Document it with examples in `ui_framework/doc_site`.

You can do this using Yeoman (the easy way), or you can do it manually (the hard way).

### Using Yeoman

#### Create a new component

From the command line, run `npm run uiFramework:createComponent`.

First, you'll be prompted for what kind of component to create:

| Choice | Description |
|---|---|
| Stateless function | A stateless functional React component |
| Component class | A class-based React component |

Next, you'll enter a series of prompts.

#### "What's the name of this component?"

Yeoman will ask you what to name the file. It expects you to provide the name
in snake case. Yeoman will automatically add file extensions and a "kui" prefix so you should leave those out.

#### "Where do you want to create this component's files?"

This defaults to the last directory you specified for this prompt, or to the UI Framework's
components directory if you haven't specified one. To change this location, type in the path to the
directory where the files should live.

If you want Yeoman to automatically generate a directory to organize the files,
that directory will be created inside of the location you specify (see next prompt).

#### "Does it need its own directory?""

This defaults to `YES`. This will automatically generate a directory with the
same name as the file, but without a "kui" prefix.

#### Done!

Yeoman will generate the files you need in your project's folder system.

For your convenience, it will also output some snippets you can tweak to import
and re-export the generated JS and SCSS files.

### Create component SCSS
### Manually

1. Create a directory for your component in `ui_framework/components`.
#### Create component SCSS

1. Create a directory for your component in `ui_framework/src/components`.
2. In this directory, create `_{component name}.scss`.
3. _Optional:_ Create any other components that should be [logically-grouped](#logically-grouped-components)
in this directory.
4. Create an `_index.scss` file in this directory that import all of the new component SCSS files
you created.
5. Import the `_index.scss` file into `ui_framework/components/index.scss`.
5. Import the `_index.scss` file into `ui_framework/src/components/index.scss`.

This makes your styles available to Kibana and the UI Framework documentation.

### Create the React component
#### Create the React component

1. Create the React component(s) in the same directory as the related SCSS file(s).
2. Export these components from an `index.js` file.
3. Re-export these components from `ui_framework/components/index.js`.
3. Re-export these components from `ui_framework/src/components/index.js`.

This makes your React component available for import into Kibana.

### Document the component with examples
#### Test the component

1. Start Jest in watch mode by running `node scripts/jest --watch`.
2. Create test files with the name pattern of `{component name}.test.js`.
3. Write your tests and see them fail or succeed.

To see how well the components have been covered by tests, you can run
`node scripts/jest --coverage` and check the generated report in
`target/jest-coverage/index.html`.

#### Document the component with examples

1. Create a directory for your example in `ui_framework/doc_site/src/views`. Name it the name of the
component.
Expand All @@ -80,15 +123,22 @@ complex they should be. In general, your examples should demonstrate:
content.
* The various states of the component, e.g. disabled, selected, empty of content, error state.

### Test the component
## Creating documentation

1. Start Jest in watch mode by running `node scripts/jest --watch`.
2. Create test files with the name pattern of `{component name}.test.js`.
3. Write your tests and see them fail or succeed.
You can use the same Yeoman generator referenced above to create documentation.

To see how well the components have been covered by tests, you can run
`node scripts/jest --coverage` and check the generated report in
`target/jest-coverage/index.html`.
From the command line, run `npm run uiFramework:documentComponent`.

First, you'll be prompted for what kind of documentation to create:

| Choice | Description |
|---|---|
| Page | A page for documenting a component(s) with multiple demos |
| Page demo | An individual demo of a particular component use case |
| Sandbox | An empty document where you can do pretty much anything |

Just follow the prompts and your documentation files will be created.
You can use the snippets that are printed to the terminal to integrate these files into the UI Framework documentation site.

## Principles

Expand All @@ -101,7 +151,8 @@ additional SCSS files for these components in the same component directory.

### Writing CSS

Check out our [CSS style guide](https://github.com/elastic/kibana/blob/master/style_guides/css_style_guide.md).
Check out our [CSS style guide](https://github.com/elastic/kibana/blob/master/style_guides/css_style_guide.md)
and [SCSS style guide](https://github.com/elastic/kibana/blob/master/style_guides/scss_style_guide.md).

## Benefits

Expand Down
Loading

0 comments on commit bb065f5

Please sign in to comment.