From 19c151575dfdcc969b55a3cb92896885d56e2881 Mon Sep 17 00:00:00 2001
From: Anton Dosov <anton.dosov@elastic.co>
Date: Mon, 8 Jun 2020 18:20:12 +0200
Subject: [PATCH] add readme

---
 src/plugins/embeddable/README.md              |  4 +++
 src/plugins/embeddable/docs/README.md         |  5 +++
 .../docs/containers_and_inherited_state.md    | 33 +++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 src/plugins/embeddable/docs/README.md
 create mode 100644 src/plugins/embeddable/docs/containers_and_inherited_state.md

diff --git a/src/plugins/embeddable/README.md b/src/plugins/embeddable/README.md
index 226b359e1ed5f..55abe8606159c 100644
--- a/src/plugins/embeddable/README.md
+++ b/src/plugins/embeddable/README.md
@@ -18,6 +18,10 @@ and navigate to the Embeddable explorer app.
 
 There is also an example of rendering dashboard container outside of dashboard app [here](https://github.com/elastic/kibana/tree/master/examples/dashboard_embeddable_examples).
 
+## Docs
+
+[Embeddable docs, guides & caveats](./docs/README.md)
+
 ## Testing
 
 Run unit tests
diff --git a/src/plugins/embeddable/docs/README.md b/src/plugins/embeddable/docs/README.md
new file mode 100644
index 0000000000000..1b6c7be13b1d4
--- /dev/null
+++ b/src/plugins/embeddable/docs/README.md
@@ -0,0 +1,5 @@
+# Embeddable Docs, Guides & Caveats
+
+## Reference
+
+- [Embeddable containers and inherited input state](./containers_and_inherited_state.md)
diff --git a/src/plugins/embeddable/docs/containers_and_inherited_state.md b/src/plugins/embeddable/docs/containers_and_inherited_state.md
new file mode 100644
index 0000000000000..c950bef96002a
--- /dev/null
+++ b/src/plugins/embeddable/docs/containers_and_inherited_state.md
@@ -0,0 +1,33 @@
+## Embeddable containers and inherited input state
+
+`updateInput` is typed as `updateInput(input: Partial<EmbeddableInput>)`. Notice it's _partial_. This is to support the use case of inherited state when an embeddable is inside a container.
+
+If you are simply rendering an embeddable, it's no problem to do something like:
+
+```ts
+// Notice this isn't a partial so it'll be the entire state.
+const input: EmbeddableInput = this.state.input
+embeddable.updateInput(input);
+```
+
+However when you are dealing with _containers_, you want to be sure to **only pass into `updateInput` the actual state that changed**. This is because calling `child.updateInput({ foo })` will make `foo` _explicit_ state. It cannot be inherited from it's parent.
+
+For example, on a dashboard, the time range is _inherited_ by all children, _unless_ they had their time range set explicitly. This is how "per panel time range" works. That action calls `embeddable.updateInput({ timeRange })`, and the time range will no longer be inherited from the container.
+
+### Why is this important?
+
+A common mistake is always passing in the full state. If you do this, all of a sudden you will lose the inheritance of the container state.
+
+**Don't do**
+
+```ts
+// Doing this will make it so this embeddable inherits _nothing_ from its container. No more time range updates
+// when the user updates the dashboard time range!
+embeddable.updateInput({ ...embeddable.getInput(), foo: 'bar' });
+```
+
+**Do**
+
+```ts
+embeddable.updateInput({ foo: 'bar' });
+```