add some diagrams for state as snapshot

Author: rmorshea

docs/examples.py

@@ -35,6 +35,13 @@ def all_example_names() -> set[str]:
 
 
 def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
+    return lambda: (
+        # we do this to ensure each instance is fresh
+        _load_one_example(file_or_name)
+    )
+
+
+def _load_one_example(file_or_name: Path | str) -> ComponentType:
     if isinstance(file_or_name, str):
         file = get_main_example_file_by_name(file_or_name)
     else:
@@ -43,8 +50,14 @@ def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
     if not file.exists():
         raise FileNotFoundError(str(file))
 
+    print_buffer = _PrintBuffer()
+
+    def capture_print(*args, **kwargs):
+        buffer = StringIO()
+        print(*args, file=buffer, **kwargs)
+        print_buffer.write(buffer.getvalue())
+
     captured_component_constructor = None
-    capture_print, ShowPrint = _printout_viewer()
 
     def capture_component(component_constructor):
         nonlocal captured_component_constructor
@@ -68,13 +81,18 @@ def capture_component(component_constructor):
 
     if captured_component_constructor is None:
         return _make_example_did_not_run(str(file))
-    else:
 
-        @idom.component
-        def Wrapper():
-            return idom.html.div(captured_component_constructor(), ShowPrint())
+    @idom.component
+    def Wrapper():
+        return idom.html.div(captured_component_constructor(), PrintView())
 
-        return Wrapper
+    @idom.component
+    def PrintView():
+        text, set_text = idom.hooks.use_state(print_buffer.getvalue())
+        print_buffer.set_callback(set_text)
+        return idom.html.pre({"class": "printout"}, text) if text else idom.html.div()
+
+    return Wrapper()
 
 
 def get_main_example_file_by_name(name: str) -> Path:
@@ -98,44 +116,26 @@ def _get_root_example_path_by_name(name: str) -> Path:
     return EXAMPLES_DIR.joinpath(*name.split("/"))
 
 
-def _printout_viewer():
-    print_callbacks: set[Callable[[str], None]] = set()
+class _PrintBuffer:
+    def __init__(self, max_lines: int = 10):
+        self._callback = None
+        self._lines = ()
+        self._max_lines = max_lines
 
-    @idom.component
-    def ShowPrint():
-        lines, set_lines = idom.hooks.use_state(())
-
-        def set_buffer(text: str):
-            if len(lines) > 10:
-                # limit printout size - protects against malicious actors
-                # plus it gives you some nice scrolling printout
-                set_lines(lines[1:] + (text,))
-            else:
-                set_lines(lines + (text,))
-
-        @idom.hooks.use_effect(args=[set_buffer])
-        def add_set_buffer_callback():
-            print_callbacks.add(set_buffer)
-            return lambda: print_callbacks.remove(set_buffer)
-
-        if not lines:
-            return idom.html.div()
-        else:
-            return idom.html.pre({"class": "printout"}, "".join(lines))
+    def set_callback(self, function: Callable[[str], None]) -> None:
+        self._callback = function
+        return None
 
-    def capture_print(*args, **kwargs):
-        buffer = StringIO()
-        print(*args, file=buffer, **kwargs)
-        value = buffer.getvalue()
-        for cb in print_callbacks:
-            cb(value)
-
-    return capture_print, ShowPrint
+    def getvalue(self) -> str:
+        return "".join(self._lines)
 
-
-def _use_force_update():
-    toggle, set_toggle = idom.hooks.use_state(False)
-    return lambda: set_toggle(not toggle)
+    def write(self, text: str) -> None:
+        if len(self._lines) == self._max_lines:
+            self._lines = self._lines[1:] + (text,)
+        else:
+            self._lines += (text,)
+        if self._callback is not None:
+            self._callback(self.getvalue())
 
 
 def _make_example_did_not_run(example_name):

docs/source/_examples/adding_interactivity/print_chat_message.py

@@ -0,0 +1,43 @@
+import asyncio
+
+from idom import component, event, html, run, use_state
+
+
+@component
+def App():
+    recipient, set_recipient = use_state("Alice")
+    message, set_message = use_state("")
+
+    @event(prevent_default=True)
+    async def handle_submit(event):
+        set_message("")
+        print("About to send message...")
+        await asyncio.sleep(5)
+        print(f"Sent '{message}' to {recipient}")
+
+    return html.form(
+        {"onSubmit": handle_submit, "style": {"display": "inline-grid"}},
+        html.label(
+            "To: ",
+            html.select(
+                {
+                    "value": recipient,
+                    "onChange": lambda event: set_recipient(event["value"]),
+                },
+                html.option({"value": "Alice"}, "Alice"),
+                html.option({"value": "Bob"}, "Bob"),
+            ),
+        ),
+        html.input(
+            {
+                "type": "text",
+                "placeholder": "Your message...",
+                "value": message,
+                "onChange": lambda event: set_message(event["value"]),
+            }
+        ),
+        html.button({"type": "submit"}, "Send"),
+    )
+
+
+run(App)

docs/source/_exts/widget_example.py

@@ -25,6 +25,7 @@ class WidgetExample(SphinxDirective):
     }
 
     def run(self):
+        print(self.get_source_info())
         example_name = self.arguments[0]
         show_linenos = "linenos" in self.options
         live_example_is_default_tab = "result-is-default-tab" in self.options

docs/source/_static/custom.js

@@ -1483,7 +1483,17 @@ const targetTransformCategories = {
 };
 
 const targetTagCategories = {
-  hasValue: ["BUTTON", "INPUT", "OPTION", "LI", "METER", "PROGRESS", "PARAM"],
+  hasValue: [
+    "BUTTON",
+    "INPUT",
+    "OPTION",
+    "LI",
+    "METER",
+    "PROGRESS",
+    "PARAM",
+    "SELECT",
+    "TEXTAREA",
+  ],
   hasCurrentTime: ["AUDIO", "VIDEO"],
   hasFiles: ["INPUT"],
 };
@@ -1941,7 +1951,9 @@ function mountLayoutWithReconnectingWebSocket(
       mountState
     );
 
-    console.info(`IDOM WebSocket connection lost. Reconnecting in ${reconnectTimeout} seconds...`);
+    console.info(
+      `IDOM WebSocket connection lost. Reconnecting in ${reconnectTimeout} seconds...`
+    );
 
     setTimeout(function () {
       mountState.reconnectAttempts++;

docs/source/adding-interactivity/_static/direct-state-change.png

@@ -224,7 +224,7 @@ below highlights a line of code where something of interest occurs:
 
         .. raw:: html
 
-            <h2>Event handler triggers</h2>
+            <h2>New state is set</h2>
 
         .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
             :lines: 12-33

docs/source/adding-interactivity/_static/idom-state-change.png

@@ -36,7 +36,8 @@ Adding Interactivity
             :link: state-as-a-snapshot
             :link-type: doc
 
-            Under construction 🚧
+            Learn why IDOM does not change component state the moment it is set, but
+            instead schedules a re-render.
 
         .. grid-item-card:: :octicon:`issue-opened` Dangers of Mutability
             :link: dangers-of-mutability
@@ -112,14 +113,32 @@ Section 3: State as a Snapshot
 
 As we :ref:`learned earlier <Components with State>`, state setters behave a little
 differently than you might exepct at first glance. Instead of updating your current
-handle on the corresponding state variable it schedules a re-render of the component
-which owns the state:
+handle on the setter's corresponding variable, it schedules a re-render of the component
+which owns the state.
 
 .. code-block::
 
-    print(count)
-    set_count(count + 1)
-    print(count)
+    count, set_count = use_state(0)
+    print(count)  # prints: 0
+    set_count(count + 1)  # schedule a re-render where count is 1
+    print(count)  # still prints: 0
+
+This behavior of IDOM means that each render of a component is like taking a snapshot of
+the UI based on the component's state at that time. Treating state in this way can help
+reduce subtle bugs. For example, in the code below there's a simple chat app with a
+message input and recipient selector. The catch is that the message actually gets sent 5
+seconds after the "Send" button is clicked. So what would happen if we changed the
+recipient between the time the "Send" button was clicked and the moment the message is
+actually sent?
+
+.. example:: adding_interactivity/print_chat_message
+    :activate-result:
+
+As it turns out, changing the message recipient after pressing send does not change
+where the message ulitmately goes. However, one could imagine a bug where the recipient
+of a message is determined at the time the message is sent rather than at the time the
+"Send" button it clicked. In many cases, IDOM avoids this class of bug entirely because
+it treats state as a snapshot.
 
 .. card::
     :link: state-as-a-snapshot

docs/source/adding-interactivity/components-with-state.rst

@@ -1,8 +1,14 @@
 State as a Snapshot
 ===================
 
-While you can read state variables like you might normally in Python, as we
-:ref:`learned earlier <Components with State>`, assigning to them is somewhat different.
-When you use a state setter to update a component, instead of modifying your handle to
-its corresponding state variable, a re-render is triggered. Only after that next render
-begins will things change.
+When you watch the user interfaces you build change as you interact with them, it's easy
+to imagining that they do so because there's some bit of code that modifies the relevant
+parts of the view directly. For example, you may think that when a user clicks a "Send"
+button, there's code which reaches into the view and adds some text saying "Message
+sent!":
+
+.. image:: _static/direct-state-change.png
+
+
+
+.. image:: _static/idom-state-change.png

docs/source/adding-interactivity/index.rst

@@ -15,8 +15,8 @@ At their core, components are just normal Python functions that return HTML. To
 component you just need to add a ``@component`` `decorator
 <https://realpython.com/primer-on-python-decorators/>`__ to a function. Functions
 decorator in this way are known as **render function** and, by convention, we name them
-like classes - with ``CamelCase``. So for example, if we wanted to write, and then
-:ref:`display <Running IDOM>` a ``Photo`` component, we might write:
+like classes - with ``CamelCase``. So consider what we would do if we wanted to write,
+and then :ref:`display <Running IDOM>` a ``Photo`` component:
 
 .. example:: creating_interfaces/simple_photo
     :activate-result: