* Create KuiButton, KuiLinkButton, KuiSubmitButton, and KuiButtonIcon React components in UI Framework. * Add Jest test coverage for UI Framework, generate report in ui_framework/jest/report. * Add UI Framework to linting task. * Update UI Framework README with instructions on creating and testing React components. * Add both React and HTML examples. * Add UI Framework Jest tests to npm test script. Create separate scripts for watching and generating coverage reports. * Fix appearance of kuiButtons with icons throughout Kibana, by adding a flexbox wrapper. * Improve accessibility of kuiButtonIcon. * Remove disabled attribute from KuiLinkButton. * Remove kuiButton-isDisabled class from KuiButton and KuiSubmitButton.
6.4 KiB
Kibana UI Framework
The Kibana UI Framework is a collection of React UI components for quickly building user interfaces for Kibana. Not using React? No problem! You can still use the CSS behind each component.
Using the Framework
Documentation
You can view interactive documentation by running npm run uiFramework:start
and then visiting
http://localhost:8020/
.
React components
Here are the components you can import from the Framnework:
import {
KuiButton,
KuiButtonGroup,
KuiButtonIcon,
} from '../path/to/ui_framework/components';
Creating components
There are four steps to creating a new component:
- Create the SCSS for the component in
ui_framework/components
. - Create the React portion of the component.
- Document it with examples in
ui_framework/doc_site
. - Write tests.
Create component SCSS
- Create a directory for your component in
ui_framework/components
. - In this directory, create
_{component name}.scss
. - Optional: Create any other components that should be logically-grouped in this directory.
- Create an
_index.scss
file in this directory that import all of the new component SCSS files you created. - Import the
_index.scss
file intoui_framework/components/index.scss
.
This makes your styles available to Kibana and the UI Framework documentation.
Create the React component
- Create the React component(s) in the same directory as the related SCSS file(s).
- Export these components from an
index.js
file. - Re-export these components from
ui_framework/components/index.js
.
This makes your React component available for import into Kibana.
Document the component with examples
- Create a directory for your example in
ui_framework/doc_site/src/views
. Name it the name of the component. - Create a
{component name}_example.js
file inside the directory. You'll use this file to define the different examples for your component. - Add the route to this file in
ui_framework/doc_site/src/services/routes/Routes.js
. - In the
{component name}_example.js
file you created, define examples which demonstrate the component and describe its role from a UI perspective.
The complexity of the component should determine how many examples you need to create, and how complex they should be. In general, your examples should demonstrate:
- The most common use-cases for the component.
- How the component handles edge cases, e.g. overflowing content, text-based vs. element-based content.
- The various states of the component, e.g. disabled, selected, empty of content, error state.
Test the component
- Create test files with the name pattern of
{component name}.test.js
. - Create your tests.
- Run tests with
npm run uiFramework:test
.
You can check how well the components have been covered
by the tests by viewing the generated report at ui_framework/jest/report/index.html
.
React component development tips
You can run npm run uiFramework:dev
to watch your files and automatically run the tests when you
make changes. Under this command, the tests will run faster than under uiFramework:test
because
they'll only test the files you've changed -- the code coverage report won't be re-genereated,
however.
Principles
Logically-grouped components
If a component has subcomponents (e.g. ToolBar and ToolBarSearch), tightly-coupled components (e.g. Button and ButtonGroup), or you just want to group some related components together (e.g. TextInput, TextArea, and CheckBox), then they belong in the same logicaly grouping. In this case, you can create additional SCSS files for these components in the same component directory.
Writing CSS
Check out our CSS style guide.
Benefits
Dynamic, interactive documentation
By having a "living style guide", we relieve our designers of the burden of creating and maintaining static style guides. This also makes it easier for our engineers to translate mockups, prototypes, and wireframes into products.
Copy-pasteable UI
Engineers can copy and paste sample code into their projects to quickly get reliable, consistent results.
Remove CSS from the day-to-day
The CSS portion of this framework means engineers don't need to spend mental cycles translating a design into CSS. These cycles can be spent on the things critical to the identity of the specific project they're working on, like architecture and business logic.
If they use the React components, engineers won't even need to see CSS -- it will be encapsulated behind the React components' interfaces.
More UI tests === fewer UI bugs
By covering our UI components with great unit tests and having those tests live within the framework itself, we can rest assured that our UI layer is tested and remove some of that burden from our integration/end-to-end tests.
Why not just use Bootstrap?
In short: we've outgrown it! Third-party CSS frameworks like Bootstrap and Foundation are designed for a general audience, so they offer things we don't need and don't offer things we do need. As a result, we've been forced to override their styles until the original framework is no longer recognizable. When the CSS reaches that point, it's time to take ownership over it and build your own framework.
We also gain the ability to fix some of the common issues with third-party CSS frameworks:
- They have non-semantic markup.
- They deeply nest their selectors.
For a more in-depth analysis of the problems with Bootstrap (and similar frameworks), check out this article and the links it has at the bottom: "Bootstrap Bankruptcy".