docs for components sharing state

docs/source/adding-interactivity/components-sharing-state/_examples/filterable_list/app.py

@@ -0,0 +1,45 @@
+import json
+from pathlib import Path
+
+from idom import component, hooks, html, run
+
+
+HERE = Path(__file__)
+DATA_PATH = HERE.parent / "data.json"
+sculpture_data = json.loads(DATA_PATH.read_text())
+
+
+@component
+def FilterableList():
+    value, set_value = hooks.use_state("")
+    return html.p(Search(value, set_value), html.hr(), Table(value, set_value))
+
+
+@component
+def Search(value, set_value):
+    def handle_change(event):
+        set_value(event["target"]["value"])
+
+    return html.label(
+        "Search by Food Name: ", html.input({"value": value, "onChange": handle_change})
+    )
+
+
+@component
+def Table(value, set_value):
+    rows = []
+    for row in data:
+        name = html.td(row["name"])
+        descr = html.td(row["description"])
+        tr = html.tr(name, descr, value)
+        if value == "":
+            rows.append(tr)
+        else:
+            if value.lower() in row["name"].lower():
+                rows.append(tr)
+        headers = html.tr(html.td(html.b("name")), html.td(html.b("description")))
+    table = html.table(html.thead(headers), html.tbody(rows))
+    return table
+
+
+run(FilterableList)

docs/source/adding-interactivity/components-sharing-state/_examples/filterable_list/data.json

@@ -0,0 +1,22 @@
+[
+  {
+    "name": "Sushi",
+    "description": "Sushi is a traditional Japanese dish of prepared vinegared rice",
+  },
+  {
+    "name": "Dal",
+    "description": "The most common way of preparing dal is in the form of a soup to which onions, tomatoes and various spices may be added",
+  },
+  {
+    "name": "Pierogi",
+    "description": "Pierogi are filled dumplings made by wrapping unleavened dough around a savoury or sweet filling and cooking in boiling water",
+  },
+  {
+    "name": "Shish Kebab",
+    "description": "Shish kebab is a popular meal of skewered and grilled cubes of meat",
+  },
+  {
+    "name": "Dim sum",
+    "description": "Dim sum is a large range of small dishes that Cantonese people traditionally enjoy in restaurants for breakfast and lunch",
+  }
+]

docs/source/adding-interactivity/components-sharing-state/index.rst

@@ -0,0 +1,59 @@
+Components Sharing State
+========================
+
+Sometimes you want the state of two components to always change together. To do it, you
+need to be able to share state between those two components, to share state between 
+componets move state to the nearest parent. In React world this is known as "lifting
+state up" and it is a very common thing to do. Let's look at 2 examples, also from 
+`React <https://beta.reactjs.org/learn/sharing-state-between-components>`__, 
+but translated to IDOM.
+
+Sycned Inputs
+-------------
+
+In the code below the two input boxes are syncronized, this happens because they share
+state. The state is shared via the parent component ``SyncedInputs``. Check the ``value``
+and ``set_value`` variables.
+
+.. code-block::
+    :linenos:
+    :lineno-start: 14
+
+    from idom import component, html, run, hooks
+
+    @component
+    def SyncedInputs():
+        value, set_value = hooks.use_state("")
+        return html.p(
+            Input("First input", value, set_value),
+            Input("Second input", value, set_value),
+        )
+
+
+    @component
+    def Input(label, value, set_value):
+        def handle_change(event):
+            set_value(event["target"]["value"])
+
+        return html.label(
+            label + " ", html.input({"value": value, "onChange": handle_change})
+        )
+
+    run(SyncedInputs)
+
+
+Filterable  List
+----------------
+
+In the example below the search input and the list of elements below share the
+same state, the state represents the food name.
+
+Note how the component ``Table`` gets called at each change of state. The
+component is observing the state and reacting to state changes automatically, 
+just like it would do in React.
+
+.. idom:: _examples/filterable_list
+
+.. note::
+
+    Try typing a food name in the search bar.

docs/source/adding-interactivity/index.rst

@@ -6,6 +6,7 @@ Adding Interactivity
 
     responding-to-events/index
     components-with-state/index
+    components-sharing-state/index
     state-as-a-snapshot/index
     multiple-state-updates/index
     dangers-of-mutability/index
@@ -107,7 +108,20 @@ other :ref:`later <managing state>`).
     Allow components to change what they display by saving and updating their state.
 
 
-Section 3: State as a Snapshot
+Section 3: Components Sharing State
+-----------------------------------
+
+Sometimes you want the state of two components to always change together. To do it, you
+need to be able to share state between those two components, to share state between 
+componets move state to the nearest parent. In React world this is known as "lifting
+state up" and it is a very common thing to do. Let's look at 2 examples, also from 
+`React <https://beta.reactjs.org/learn/sharing-state-between-components>`__, 
+but translated to IDOM.
+
+.. idom:: components-sharing-state/_examples/filterable_list
+
+
+Section 4: State as a Snapshot
 ------------------------------
 
 As we :ref:`learned earlier <Components with State>`, state setters behave a little
@@ -151,7 +165,7 @@ snapshot.
     Learn why state updates schedules a re-render, instead of being applied immediately.
 
 
-Section 4: Multiple State Updates
+Section 5: Multiple State Updates
 ---------------------------------
 
 As we saw in an earlier example, :ref:`setting state triggers renders`. In other words,
@@ -184,7 +198,7 @@ To accomplish this, instead of passing the next state value directly (e.g.
     Learn how updates to a components state can be batched, or applied incrementally.
 
 
-Section 5: Dangers of Mutability
+Section 6: Dangers of Mutability
 --------------------------------
 
 While state can hold any type of value, you should be careful to avoid directly