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:

docs/source/adding-interactivity/state-as-a-snapshot.rst

@@ -39,9 +39,9 @@ IDOM is also ecosystem independent. It can be added to existing applications bui
 variety of sync and async web servers, as well as integrated with other frameworks like
 Django, Jupyter, and Plotly Dash. Not only does this mean you're free to choose what
 technology stack to run on, but on top of that, you can run the exact same components
-wherever you need them. For example, you can take a component originally developed in a
-Jupyter Notebook and embed it in your production application without changing anything
-about the component itself.
+wherever you need them. Consider the case where, you can take a component originally
+developed in a Jupyter Notebook and embed it in your production application without
+changing anything about the component itself.
 
 
 At a Glance

docs/source/creating-interfaces/your-first-components.rst

@@ -253,6 +253,12 @@ def update_version(session: Session) -> None:
     session.install("-e", ".")
 
 
+@nox.session
+def build_js(session: Session) -> None:
+    session.chdir(ROOT / "src" / "client")
+    session.run("npm", "run", "build", external=True)
+
+
 @nox.session(reuse_venv=True)
 def latest_pull_requests(session: Session) -> None:
     """A basic script for outputing changelog info"""

docs/source/index.rst

@@ -39,7 +39,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"],
 };

noxfile.py

@@ -66,7 +66,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++;

src/client/packages/idom-client-react/src/event-to-object.js

@@ -100,14 +100,18 @@
 Forms
 -----
 
-- :func:`meter`
-- :func:`output`
-- :func:`progress`
-- :func:`input`
 - :func:`button`
-- :func:`label`
 - :func:`fieldset`
+- :func:`form`
+- :func:`input`
+- :func:`label`
 - :func:`legend`
+- :func:`meter`
+- :func:`option`
+- :func:`output`
+- :func:`progress`
+- :func:`select`
+- :func:`textarea`
 
 
 Interactive Elements
@@ -201,14 +205,18 @@
 tr = make_vdom_constructor("tr")
 
 # Forms
-meter = make_vdom_constructor("meter")
-output = make_vdom_constructor("output")
-progress = make_vdom_constructor("progress")
-input = make_vdom_constructor("input", allow_children=False)
 button = make_vdom_constructor("button")
-label = make_vdom_constructor("label")
 fieldset = make_vdom_constructor("fieldset")
+form = make_vdom_constructor("form")
+input = make_vdom_constructor("input", allow_children=False)
+label = make_vdom_constructor("label")
 legend = make_vdom_constructor("legend")
+meter = make_vdom_constructor("meter")
+option = make_vdom_constructor("option")
+output = make_vdom_constructor("output")
+progress = make_vdom_constructor("progress")
+select = make_vdom_constructor("select")
+textarea = make_vdom_constructor("textarea")
 
 # Interactive elements
 details = make_vdom_constructor("details")