Kibana UI componentization

[cjcenizal]

Overview

• We're going to componentize as much of Kibana's UI as possible.
• The UI Framework will be our single source of truth for our UI and our components.
• Currently these are CSS components, but very soon they'll be React components.

We'll also build UI systems, e.g. sidebars, header / top nav, timepicker, search bar, modals, alerts / notifications.

To see where our UI Framework is headed in the long-term, check out:

• React Button components: This is our first PR which introduces React components into our UI Framework
• Smaato UI Framework: this is a React UI framework I built at my last job.

Roadmap

Componentization and the UI Framework

What's componentization?

Componentization is the process of breaking apart bespoke user interfaces into generalized UI components.

How do we use components?

Components will live in the UI Framework, but they'll be available to anyone working in the Kibana codebase.

Engineers will refer to the UI Framework documentation, find the components they need, and use them to develop user interfaces in Kibana.

The componentization process

The process of componentization will consist of a few overlapping phases.

CSS-only components

At first, the UI Framework will only contain CSS components.

1. Engineers and designers identify a component.
2. If the component doesn't exist yet, we write its CSS in the UI Framework. If it already exists, we migrate its CSS into the UI Framework.
3. We document the component with examples in the UI Framework.
4. Engineers migrate existing markup to use the new component CSS. Engineers write new markup to use the new component CSS.

React components

Eventually the primary mechanism for consuming the UI Framework will be through its React components:

1. Engineers will build user interfaces with React components. These components will emphasize composability, granularity, and statelessness. Engineers will also migrate existing JS components into the UI Framework.
2. We export React components from a module within the UI Framework.
3. We document these React components with interactive examples alongside the basic CSS examples. We cover all of these components with unit tests and keep the tests in the UI Framework.

Who can add components?

Anybody can! Just open a PR like you normally would. Feel free to enlist the help of the Design team when defining and building the component. CJ is the steward of the UI Framework, so he can guide you through the process. Refer to the UI Framework README.

End goal

The end goal is to completely componentize our UI, i.e. the UI Framework will drive Kibana's UI.
Once our UI is completely componentized, Kibana's UI will appear and behave more consistently, and it will be easier to apply UI improvements in a global manner:

• Design tweaks and redesigns
• Accessibility enhancements
• Color-blind mode everywhere
• Dark theme everywhere
• Themeable and customizable UI

Immediate steps for componentization

Migrate all CSS to use components in the UI Framework

We already have several new components in the UI Framework (in CSS form). These include ToolBar, Button, Form, and Table components. Wherever possible, each functional team should migrate parts of the UI under its purview to these new components.

Fire up the documentation by running npm run uiFramework:start and visiting localhost:8080. Find the components you need and copy/paste the code examples to get started.

For reference, here are some related PRs and Issues:

• Add landing page with table to Visualize app. #9605
• Refer to other cross-referenced PRs below
• Table Component #9143

Designing React components

Refer to #9933 for concrete examples of how to write Angular directives as components.

React components can be composed by treating each component as a dumb container into which other components can be injected. Composable components offer several benefits:

• Substitutability. If part of a UI needs to be updated, a new component can be substituted in place of a pre-existing one. By writing a new component instead of modifying an existing one, we can avoid introducing bugs as side effects elsewhere in the UI, and we can avoid the possibility of introducing code bloat.
• Readability. When a UI is built out of composed components, the UI becomes clear just by reading the code.
• Malleability. It also becomes easier to change positioning and layout by shuffling components around.

We can make components more composable by embracing a few concepts:

• Single responsibility. This means making components as small and fine-grained as possible. When a component has only a single responsibility, we can use it in more contexts. Taken to its extreme, this means a component can be as simple and fine-grained as a single div with a class applied to it. As a side-benefit, embracing SRP also makes components more testable.
• Inversion of control. By extracting business logic out of components into services, and then providing these services as dependencies, we not only adhere to SRP but we also make it easier to customize the way our components behave. When we have this level of control over components on an instance-by-instance basis, we can use these components in almost any situation.
• Statelessness. Similar to IoC, we can treat state as an external dependency. This makes components more testable, and also allows for the possibility of a Flux-like application design (with the associated benefits of a single-directional data flow, and the ability to treat the UI state as a projection of the application state). In terms of composability, it means we can compose components together without having to worry about how the internal state of one component will interact with the internal state of another component.

UI systems

There are several global UI systems which we also want to build. Each of these is a major initiative. In no particular order:

• Notifications
• Undo/redo
• Fixed layouts
• Header / top nav
• Timerpicker
• Search bar
• Filter bar
• Modals

[Bargs]

Please loop in the Discovery team if/when you start to think about timepicker, search bar, and filter bar. These are areas we're actively working in.

[cjcenizal]

Meeting notes

Stuff to do right now

• Our immediate goal is to migrate existing markup to use the components in the UI Framework.
• Run the UI Framework locally with npm run uiFramework:start and visit localhost:8080 (see UI Framework README.
• Each functional team will audit the apps under their jurisdiction and create an issue enumerating the areas in the UI which need to be updated with UI Framework components.
• Note: If your UI has needs that aren't met by the UI Framework (e.g. your UI needs a 100% width button but the UI Framework doesn't support this), document these unmet requirements in your audit issue with a screenshot. We'll update the UI Framework and/or the UI so that the two will be compatible.
• Ping CJ with this list. He'll cross-reference them here, look for missing gaps, and determine the scope of the total migration task.
• We'll use this scope to decided which release(s) to target with this change.

Stuff to keep in mind

• When writing or re-writing directives, keep the componentization principles in mind.
• Try to apply them and see if they make sense.
• Record anything you learn or any problems you encounter here so we can refine our team-wide componentization approach.

[Bargs]

When writing or re-writing directives, keep the componentization principles in mind.

Do we have concrete recommendations for how to achieve this in Angular? If not, this is probably something we should experiment with outside of regular work first. Otherwise that statement is going to be interpreted in a lot of different ways and we'll end up with inconsistent components.

[w33ble]

Some of that should be encapsulated as part of #9049, but setting out specific guidelines for components is a good idea. For example, keeping things as stateless as possible, keep things small, passing around handler functions, etc. All good stuff to define and outline somewhere, maybe as a "component styleguide", or as a set of guidelines in the UI Framework.

[cjcenizal]

Closing this in favor of its spiritual successor: #15282