state management docs draft

rudolf · May 26, 2020 · May 28, 2020 · May 28, 2020 · Jun 18, 2020 · Jun 18, 2020
commit e96236871a5bda4ef05c3bd2c6c961f8ff125502
diff --git a/docs/development/plugins/kibana_utils/common/state_containers/index.md b/docs/development/plugins/kibana_utils/common/state_containers/index.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+|  Package | Description |
+|  --- | --- |
+|  [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) | State containers are Redux-store-like objects meant to help you manage state in your services or apps. Refer to [https://github.com/elastic/kibana/tree/master/src/plugins/kibana\_utils/docs/state\_containers](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_containers) for guide and examples |
+
diff --git a/...tainers/kibana-plugin-plugins-kibana_utils-common-state_containers.basestate.md b/...tainers/kibana-plugin-plugins-kibana_utils-common-state_containers.basestate.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [BaseState](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestate.md)
+
+## BaseState type
+
+Base state shape valid for state container
+
+<b>Signature:</b>
+
+```typescript
+export declare type BaseState = object;
+```
diff --git a/...a-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.get.md b/...a-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.get.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) &gt; [get](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.get.md)
+
+## BaseStateContainer.get property
+
+<b>Signature:</b>
+
+```typescript
+get: () => State;
+```
diff --git a/...ibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md b/...ibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md)
+
+## BaseStateContainer interface
+
+Base state container shape without transitions or selectors
+
+<b>Signature:</b>
+
+```typescript
+export interface BaseStateContainer<State extends BaseState> 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [get](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.get.md) | <code>() =&gt; State</code> |  |
+|  [set](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.set.md) | <code>(state: State) =&gt; void</code> |  |
+|  [state$](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.state_.md) | <code>Observable&lt;State&gt;</code> |  |
+
diff --git a/...a-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.set.md b/...a-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.set.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) &gt; [set](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.set.md)
+
+## BaseStateContainer.set property
+
+<b>Signature:</b>
+
+```typescript
+set: (state: State) => void;
+```
diff --git a/...lugin-plugins-kibana_utils-common-state_containers.basestatecontainer.state_.md b/...lugin-plugins-kibana_utils-common-state_containers.basestatecontainer.state_.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) &gt; [state$](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.state_.md)
+
+## BaseStateContainer.state$ property
+
+<b>Signature:</b>
+
+```typescript
+state$: Observable<State>;
+```
diff --git a/...ainers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md b/...ainers/kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [Comparator](./kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md)
+
+## Comparator type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type Comparator<Result> = (previous: Result, current: Result) => boolean;
+```
diff --git a/...ontainers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md b/...ontainers/kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [Connect](./kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md)
+
+## Connect type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type Connect<State extends BaseState> = <Props extends object, StatePropKeys extends keyof Props>(mapStateToProp: MapStateToProps<State, Pick<Props, StatePropKeys>>) => (component: ComponentType<Props>) => FC<Omit<Props, StatePropKeys>>;
+```
diff --git a/...ana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer.md b/...ana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [createStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer.md)
+
+## createStateContainer() function
+
+Creates a state container without transitions and without selectors.
+
+<b>Signature:</b>
+
+```typescript
+export declare function createStateContainer<State extends BaseState>(defaultState: State): ReduxLikeStateContainer<State>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  defaultState | <code>State</code> | initial state |
+
+<b>Returns:</b>
+
+`ReduxLikeStateContainer<State>`
+
diff --git a/...a-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md b/...a-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md
@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [createStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md)
+
+## createStateContainer() function
+
+Creates a state container with transitions, but without selectors
+
+<b>Signature:</b>
+
+```typescript
+export declare function createStateContainer<State extends BaseState, PureTransitions extends object>(defaultState: State, pureTransitions: PureTransitions): ReduxLikeStateContainer<State, PureTransitions>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  defaultState | <code>State</code> | initial state |
+|  pureTransitions | <code>PureTransitions</code> | state transitions configuration object |
+
+<b>Returns:</b>
+
+`ReduxLikeStateContainer<State, PureTransitions>`
+
diff --git a/...a-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md b/...a-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md
@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [createStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md)
+
+## createStateContainer() function
+
+Creates a state container with transitions and selectors
+
+<b>Signature:</b>
+
+```typescript
+export declare function createStateContainer<State extends BaseState, PureTransitions extends object, PureSelectors extends object>(defaultState: State, pureTransitions: PureTransitions, pureSelectors: PureSelectors, options?: CreateStateContainerOptions): ReduxLikeStateContainer<State, PureTransitions, PureSelectors>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  defaultState | <code>State</code> | initial state |
+|  pureTransitions | <code>PureTransitions</code> | state transitions configuration object |
+|  pureSelectors | <code>PureSelectors</code> | state selectors configuration object |
+|  options | <code>CreateStateContainerOptions</code> |  |
+
+<b>Returns:</b>
+
+`ReduxLikeStateContainer<State, PureTransitions, PureSelectors>`
+
diff --git a/...gins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md b/...gins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md
@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [CreateStateContainerOptions](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md) &gt; [freeze](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md)
+
+## CreateStateContainerOptions.freeze property
+
+Function to use when freezing state. Supply identity function
+
+```ts
+{
+  freeze: state => state,
+}
+
+```
+if you expect that your state will be mutated externally an you cannot prevent that.
+
+<b>Signature:</b>
+
+```typescript
+freeze?: <T>(state: T) => T;
+```
diff --git a/...gin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md b/...gin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md
@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [CreateStateContainerOptions](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md)
+
+## CreateStateContainerOptions interface
+
+State container options
+
+<b>Signature:</b>
+
+```typescript
+export interface CreateStateContainerOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [freeze](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.freeze.md) | <code>&lt;T&gt;(state: T) =&gt; T</code> | Function to use when freezing state. Supply identity function
+```ts
+{
+  freeze: state => state,
+}
+
+```
+if you expect that your state will be mutated externally an you cannot prevent that. |
+
diff --git a/...lugins-kibana_utils-common-state_containers.createstatecontainerreacthelpers.md b/...lugins-kibana_utils-common-state_containers.createstatecontainerreacthelpers.md
@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [createStateContainerReactHelpers](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainerreacthelpers.md)
+
+## createStateContainerReactHelpers variable
+
+Creates helpers for using [State Containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) with react
+
+<b>Signature:</b>
+
+```typescript
+createStateContainerReactHelpers: <Container extends StateContainer<any, any, {}>>() => {
+    Provider: React.Provider<Container>;
+    Consumer: React.Consumer<Container>;
+    context: React.Context<Container>;
+    useContainer: () => Container;
+    useState: () => UnboxState<Container>;
+    useTransitions: () => Container["transitions"];
+    useSelector: <Result>(selector: (state: UnboxState<Container>) => Result, comparator?: Comparator<Result>) => Result;
+    connect: Connect<UnboxState<Container>>;
+}
+```
diff --git a/...ntainers/kibana-plugin-plugins-kibana_utils-common-state_containers.dispatch.md b/...ntainers/kibana-plugin-plugins-kibana_utils-common-state_containers.dispatch.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [Dispatch](./kibana-plugin-plugins-kibana_utils-common-state_containers.dispatch.md)
+
+## Dispatch type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type Dispatch<T> = (action: T) => void;
+```
diff --git a/...s/kibana-plugin-plugins-kibana_utils-common-state_containers.mapstatetoprops.md b/...s/kibana-plugin-plugins-kibana_utils-common-state_containers.mapstatetoprops.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [MapStateToProps](./kibana-plugin-plugins-kibana_utils-common-state_containers.mapstatetoprops.md)
+
+## MapStateToProps type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type MapStateToProps<State extends BaseState, StateProps extends object> = (state: State) => StateProps;
+```
diff --git a/.../state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md b/.../state_containers/kibana-plugin-plugins-kibana_utils-common-state_containers.md
@@ -0,0 +1,47 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md)
+
+## kibana-plugin-plugins-kibana\_utils-common-state\_containers package
+
+State containers are Redux-store-like objects meant to help you manage state in your services or apps. Refer to [https://github.com/elastic/kibana/tree/master/src/plugins/kibana\_utils/docs/state\_containers](https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_containers) for guide and examples
+
+## Functions
+
+|  Function | Description |
+|  --- | --- |
+|  [createStateContainer(defaultState)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer.md) | Creates a state container without transitions and without selectors. |
+|  [createStateContainer(defaultState, pureTransitions)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_1.md) | Creates a state container with transitions, but without selectors |
+|  [createStateContainer(defaultState, pureTransitions, pureSelectors, options)](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainer_2.md) | Creates a state container with transitions and selectors |
+
+## Interfaces
+
+|  Interface | Description |
+|  --- | --- |
+|  [BaseStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestatecontainer.md) | Base state container shape without transitions or selectors |
+|  [CreateStateContainerOptions](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontaineroptions.md) | State container options |
+|  [ReduxLikeStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md) | Fully featured state container which matches Redux store interface |
+|  [StateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) | Fully featured state container with selectors and transitions |
+|  [TransitionDescription](./kibana-plugin-plugins-kibana_utils-common-state_containers.transitiondescription.md) |  |
+
+## Variables
+
+|  Variable | Description |
+|  --- | --- |
+|  [createStateContainerReactHelpers](./kibana-plugin-plugins-kibana_utils-common-state_containers.createstatecontainerreacthelpers.md) | Creates helpers for using [State Containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.statecontainer.md) with react |
+|  [useContainerSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerselector.md) | Apply selector to state container to extract only needed information. Will re-render your component only when the section changes. |
+|  [useContainerState](./kibana-plugin-plugins-kibana_utils-common-state_containers.usecontainerstate.md) | Returns the latest state of a state container. |
+
+## Type Aliases
+
+|  Type Alias | Description |
+|  --- | --- |
+|  [BaseState](./kibana-plugin-plugins-kibana_utils-common-state_containers.basestate.md) | Base state shape valid for state container |
+|  [Comparator](./kibana-plugin-plugins-kibana_utils-common-state_containers.comparator.md) |  |
+|  [Connect](./kibana-plugin-plugins-kibana_utils-common-state_containers.connect.md) |  |
+|  [Dispatch](./kibana-plugin-plugins-kibana_utils-common-state_containers.dispatch.md) |  |
+|  [MapStateToProps](./kibana-plugin-plugins-kibana_utils-common-state_containers.mapstatetoprops.md) |  |
+|  [Middleware](./kibana-plugin-plugins-kibana_utils-common-state_containers.middleware.md) |  |
+|  [PureSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.pureselector.md) |  |
+|  [Reducer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reducer.md) |  |
+
diff --git a/...ainers/kibana-plugin-plugins-kibana_utils-common-state_containers.middleware.md b/...ainers/kibana-plugin-plugins-kibana_utils-common-state_containers.middleware.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [Middleware](./kibana-plugin-plugins-kibana_utils-common-state_containers.middleware.md)
+
+## Middleware type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type Middleware<State extends BaseState = BaseState> = (store: Pick<ReduxLikeStateContainer<State, any>, 'getState' | 'dispatch'>) => (next: (action: TransitionDescription) => TransitionDescription | any) => Dispatch<TransitionDescription>;
+```
diff --git a/...ners/kibana-plugin-plugins-kibana_utils-common-state_containers.pureselector.md b/...ners/kibana-plugin-plugins-kibana_utils-common-state_containers.pureselector.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [PureSelector](./kibana-plugin-plugins-kibana_utils-common-state_containers.pureselector.md)
+
+## PureSelector type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type PureSelector<State extends BaseState, Result, Args extends any[] = []> = (state: State) => Selector<Result, Args>;
+```
diff --git a/...ontainers/kibana-plugin-plugins-kibana_utils-common-state_containers.reducer.md b/...ontainers/kibana-plugin-plugins-kibana_utils-common-state_containers.reducer.md
@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [Reducer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reducer.md)
+
+## Reducer type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type Reducer<State extends BaseState> = (state: State, action: TransitionDescription) => State;
+```
diff --git a/...s-kibana_utils-common-state_containers.reduxlikestatecontainer.addmiddleware.md b/...s-kibana_utils-common-state_containers.reduxlikestatecontainer.addmiddleware.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-kibana\_utils-common-state\_containers](./kibana-plugin-plugins-kibana_utils-common-state_containers.md) &gt; [ReduxLikeStateContainer](./kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.md) &gt; [addMiddleware](./kibana-plugin-plugins-kibana_utils-common-state_containers.reduxlikestatecontainer.addmiddleware.md)
+
+## ReduxLikeStateContainer.addMiddleware property
+
+<b>Signature:</b>
+
+```typescript
+addMiddleware: (middleware: Middleware<State>) => void;
+```