[UI Framework] Reorganize UI Framework and add Yeoman generator (elas…

…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.

.gitignore

@@ -36,3 +36,4 @@ selenium
 ui_framework/doc_site/build
 !ui_framework/doc_site/build/index.html
 yarn.lock
+.yo-rc.json

STYLEGUIDE.md

@@ -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)

package.json

@@ -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",
@@ -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",
@@ -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",

src/jest/config.json

@@ -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"
   },
@@ -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"

src/ui/public/modals/confirm_modal.js

@@ -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,

style_guides/css_style_guide.md

@@ -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)

style_guides/scss_style_guide.md

@@ -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.

tasks/config/copy.js

@@ -18,6 +18,7 @@ module.exports = function () {
         'ui_framework/components/**',
         'ui_framework/services/**',
         'ui_framework/dist/**',
+        'ui_framework/src/**',
         'webpackShims/**',
         'config/kibana.yml',
       ],

tasks/config/eslint.js

@@ -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',
     ],

tasks/ui_framework.js

@@ -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 => {
@@ -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();
       });

ui_framework/README.md

@@ -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.
@@ -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
 
@@ -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