final touches

Author: rmorshea

docs/source/adding-interactivity/_examples/delay_before_count_updater.py

@@ -0,0 +1,20 @@
+import asyncio
+
+from idom import component, html, run, use_state
+
+
+@component
+def Counter():
+    number, set_number = use_state(0)
+
+    async def handle_click(event):
+        await asyncio.sleep(3)
+        set_number(lambda old_number: old_number + 1)
+
+    return html.div(
+        html.h1(number),
+        html.button({"onClick": handle_click}, "Increment"),
+    )
+
+
+run(Counter)

docs/source/adding-interactivity/_examples/delay_before_set_count.py

@@ -0,0 +1,20 @@
+import asyncio
+
+from idom import component, html, run, use_state
+
+
+@component
+def Counter():
+    number, set_number = use_state(0)
+
+    async def handle_click(event):
+        await asyncio.sleep(3)
+        set_number(number + 1)
+
+    return html.div(
+        html.h1(number),
+        html.button({"onClick": handle_click}, "Increment"),
+    )
+
+
+run(Counter)

docs/source/adding-interactivity/_examples/set_color_3_times.py

@@ -10,8 +10,16 @@ def handle_click(event):
         set_color("pink")
         set_color("blue")
 
-    return html.button(
-        {"onClick": handle_click, "style": {"backgroundColor": color}}, "Set Color"
+    def handle_reset(event):
+        set_color("gray")
+
+    return html.div(
+        html.button(
+            {"onClick": handle_click, "style": {"backgroundColor": color}}, "Set Color"
+        ),
+        html.button(
+            {"onClick": handle_reset, "style": {"backgroundColor": color}}, "Reset"
+        ),
     )
 
 

docs/source/adding-interactivity/index.rst

@@ -36,14 +36,15 @@ Adding Interactivity
             :link: state-as-a-snapshot
             :link-type: doc
 
-            Learn why IDOM does not change component state the moment it is set, but
-            instead schedules a re-render.
+            Learn why state updates schedules a re-render, instead of being applied
+            immediately.
 
         .. grid-item-card:: :octicon:`versions` Multiple State Updates
             :link: multiple-state-updates
             :link-type: doc
 
-            Under construction 🚧
+            Learn how updates to a components state can be batched, or applied
+            incrementally.
 
         .. grid-item-card:: :octicon:`issue-opened` Dangers of Mutability
             :link: dangers-of-mutability
@@ -147,12 +148,31 @@ snapshot.
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    Learn why IDOM does not change component state the moment it is set, but instead
-    schedules a re-render.
+    Learn why state updates schedules a re-render, instead of being applied immediately.
 
 
 Section 4: Multiple State Updates
-------------------------------------
+---------------------------------
+
+As we saw in an earlier example, :ref:`setting state triggers renders`. In other words,
+changes to state only take effect in the next render, not in the current one. Further,
+changes to state are batched, calling a particular state setter 3 times won't trigger 3
+renders, it will only trigger 1. This means that multiple state assignments are batched
+- so long as the event handler is synchronous (i.e. the event handler is not an
+``async`` function), IDOM waits until all the code in an event handler has run before
+processing state and starting the next render:
+
+.. idom:: _examples/set_color_3_times
+
+Sometimes though, you need to update a state variable more than once before the next
+render. In these cases, instead of having updates batched, you instead want them to be
+applied incrementally. That is, the next update can be made to depend on the prior one.
+To accomplish this, instead of passing the next state value directly (e.g.
+``set_state(new_state)``), we may pass an **"updater function"** of the form
+``compute_new_state(old_state)`` to the state setter (e.g.
+``set_state(compute_new_state)``):
+
+.. idom:: _examples/set_state_function
 
 .. card::
     :link: multiple-state-updates
@@ -161,7 +181,7 @@ Section 4: Multiple State Updates
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    ...
+    Learn how updates to a components state can be batched, or applied incrementally.
 
 
 Section 5: Dangers of Mutability

docs/source/adding-interactivity/multiple-state-updates.rst

@@ -88,29 +88,22 @@ this is functionally equivalent to the following:
 
     set_number(increment(increment(increment(number))))
 
-So why might you want to do this? Well, in this case, we're using the same function on
-each call to ``set_number``, but what if you had more function. Perhaps you might want
-to do introduce ``squared`` or ``decrement`` functions:
+So why might you want to do this? Why not just compute ``set_number(number + 3)`` from
+the start? The easiest way to explain the use case is with an example. Imagine that we
+introduced a delay before ``set_number(number + 1)``. What would happen if we clicked
+the "Increment" button more than once before the delay in the first triggered event
+completed?
 
-.. code-block::
-
-    set_number(increment)
-    set_number(squared)
-    set_number(decrement)
-
-Which would equate to:
-
-.. code-block::
+.. idom:: _examples/delay_before_set_count
 
-    set_number(decrement(squared(increment(number))))
+From an :ref:`earlier lesson <State And Delayed Reactions>`, we learned that introducing
+delays do not change the fact that state variables do not change until the next render.
+As a result, despite clicking many times before the delay completes, the ``number`` only
+increments by one. To solve this we can use updater functions:
 
-This example also presents a scenario with much simpler state. Consider an example where
-the state is more complex. In the scenario below, we need to represent and manipulate
-state that represents the position of a character in a scene. Then imagine that we want
-to allow the user to queue their actions and then apply them all at once. The simplest
-way to do this is to factor out the functions which manualuate this state into
-functions, add them to an ``actions`` queue when the user requests, and finally, once
-the user clicks "Apply Actions", iterator over the ``actions`` and call ``set_position``
-with each action function:
+.. idom:: _examples/delay_before_count_updater
 
-.. idom:: _examples/character_movement
+Now when you click the "Increment" button, each click, though delayed, corresponds to
+``number`` being increased. This is because the ``old_number`` in the updater function
+uses the value which was assigned by the last call to ``set_number`` rather than relying
+in the static ``number`` state variable.

docs/source/conf.py

@@ -48,7 +48,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
+    # "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
@@ -65,7 +65,7 @@
     "idom_view",
     "patched_html_translator",
     "idom_example",
-    "build_custom_js",
+    # "build_custom_js",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/escape-hatches/class-components.rst

@@ -3,6 +3,11 @@
 Class Components 🚧
 ===================
 
+.. warning::
+
+    This feature has not been implemented `yet
+    <https://github.com/idom-team/idom/pull/518>`__.
+
 .. note::
 
     Under construction 🚧

docs/source/escape-hatches/index.rst

@@ -1,7 +1,7 @@
 .. _Escape Hatches:
 
-Escape Hatches 🚧
-=================
+Escape Hatches
+==============
 
 .. toctree::
     :hidden:

docs/source/index.rst

@@ -1,3 +1,9 @@
+.. note::
+
+    This documentation is still under construction 🚧. We welcome your `feedback
+    <https://github.com/idom-team/idom/discussions>`__!
+
+
 IDOM
 ====
 
@@ -156,8 +162,7 @@ other :ref:`later <managing state>`).
     :octicon:`book` Read More
     ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    Under construction 🚧
-
+    Learn how user interfaces can be made to respond to user interaction in real-time.
 
 
 Chapter 4 - :ref:`Managing State`

docs/source/managing-state/index.rst

@@ -1,7 +1,7 @@
 .. _Managing State:
 
-Managing State 🚧
-=================
+Managing State
+==============
 
 .. toctree::
     :hidden: