docs(examples): make every documented handler a coroutine

Handlers must be coroutines now, so each example hoists its one-liner into a
named 'async def' (or a factory), reads event data with 'await event.<path>',
and batches sibling reads through 'event.read(...)' or asyncio.gather so the
round trip is paid once.

Author: Archmonger

docs/examples/choosing_the_state_structure/coordinates_grouped/app.py

@@ -19,11 +19,11 @@
 def marker():
     position, set_position = use_state({"x": 20, "y": 20})
 
-    def move_diagonally(event):
+    async def move_diagonally(event):
         # One setter, one object: there is no second call left to forget.
         set_position({"x": position["x"] + STEP, "y": position["y"] + STEP})
 
-    def reset(event):
+    async def reset(event):
         set_position({"x": 20, "y": 20})
 
     return html.div(

docs/examples/choosing_the_state_structure/coordinates_separate/app.py

@@ -20,15 +20,15 @@ def marker():
     x, set_x = use_state(20)
     y, set_y = use_state(20)
 
-    def move_diagonally(event):
+    async def move_diagonally(event):
         # The classic mistake: this handler remembers x and forgets y.
         set_x(x + STEP)
 
-    def move_correctly(event):
+    async def move_correctly(event):
         set_x(x + STEP)
         set_y(y + STEP)
 
-    def reset(event):
+    async def reset(event):
         set_x(20)
         set_y(20)
 

docs/examples/choosing_the_state_structure/feedback_flags/app.py

@@ -36,12 +36,15 @@ async def submit_with_bug(event):
             html.p({"id": "flags"}, f"is_sending={is_sending}  is_sent={is_sent}"),
         )
 
+    async def handle_text_change(event):
+        set_text(await event.target.value)
+
     return html.div(
         html.p("How was your stay at The Prancing Pony?"),
         html.textarea(
             {
                 "value": text,
-                "onChange": lambda event: set_text(event["target"]["value"]),
+                "onChange": handle_text_change,
                 "disabled": is_sending,
             }
         ),

docs/examples/choosing_the_state_structure/feedback_status/app.py

@@ -25,12 +25,15 @@ async def submit(event):
     if is_sent:
         return html.div(html.h3("Thanks for your feedback!"))
 
+    async def handle_text_change(event):
+        set_text(await event.target.value)
+
     return html.div(
         html.p("How was your stay at The Prancing Pony?"),
         html.textarea(
             {
                 "value": text,
-                "onChange": lambda event: set_text(event["target"]["value"]),
+                "onChange": handle_text_change,
                 "disabled": is_sending,
             }
         ),

docs/examples/choosing_the_state_structure/full_name_derived/app.py

@@ -12,20 +12,26 @@ def check_in():
     # Not state. Every render recomputes it from whatever the two fields hold.
     full_name = f"{first_name} {last_name}"
 
-    def rename_only_first(event):
+    async def rename_only_first(event):
         set_first_name("Grace")
 
-    def rename_only_last(event):
+    async def rename_only_last(event):
         set_last_name("Hopper")
 
+    async def handle_first_name_change(event):
+        set_first_name(await event.target.value)
+
+    async def handle_last_name_change(event):
+        set_last_name(await event.target.value)
+
     return html.div(
         html.h2("Let's check you in"),
         html.label(
             "First name: ",
             html.input(
                 {
                     "value": first_name,
-                    "onChange": lambda event: set_first_name(event["target"]["value"]),
+                    "onChange": handle_first_name_change,
                 }
             ),
         ),
@@ -35,7 +41,7 @@ def rename_only_last(event):
             html.input(
                 {
                     "value": last_name,
-                    "onChange": lambda event: set_last_name(event["target"]["value"]),
+                    "onChange": handle_last_name_change,
                 }
             ),
         ),

docs/examples/choosing_the_state_structure/full_name_stored/app.py

@@ -10,19 +10,19 @@ def check_in():
     last_name, set_last_name = use_state("Lovelace")
     full_name, set_full_name = use_state("Ada Lovelace")
 
-    def handle_first_name_change(event):
-        set_first_name(event["target"]["value"])
-        set_full_name(event["target"]["value"] + " " + last_name)
+    async def handle_first_name_change(event):
+        set_first_name(await event.target.value)
+        set_full_name(await event.target.value + " " + last_name)
 
-    def handle_last_name_change(event):
-        set_last_name(event["target"]["value"])
-        set_full_name(first_name + " " + event["target"]["value"])
+    async def handle_last_name_change(event):
+        set_last_name(await event.target.value)
+        set_full_name(first_name + " " + await event.target.value)
 
-    def rename_only_first(event):
+    async def rename_only_first(event):
         # The bug the extra state variable invites: one writer, one update.
         set_first_name("Grace")
 
-    def rename_only_last(event):
+    async def rename_only_last(event):
         # This one does not touch full_name either.
         set_last_name("Hopper")
 

docs/examples/choosing_the_state_structure/places_flat/app.py

@@ -6,6 +6,17 @@
 
 
 # start
+def bind_visit(on_visit, place_id):
+    # Handlers are called with the event alone, so the id is bound by a closure
+    # rather than a lambda default — a handler has to be a coroutine, and a
+    # coroutine cannot be a lambda. The default stays overridable so a parent's
+    # bound handler can be re-bound for a deeper child.
+    async def visit(event, target_id=place_id):
+        await on_visit(event, target_id)
+
+    return visit
+
+
 @component
 def place_tree(place_id, on_visit, visited):
     place = PLACES[place_id]
@@ -19,11 +30,7 @@ def place_tree(place_id, on_visit, visited):
         (
             html.ol(
                 [
-                    place_tree(
-                        child_id,
-                        lambda event, cid=child_id: on_visit(event, cid),
-                        visited,
-                    )
+                    place_tree(child_id, bind_visit(on_visit, child_id), visited)
                     for child_id in children
                 ]
             )
@@ -39,19 +46,15 @@ def travel_plan():
     # touches exactly one entry — there is no enclosing object to rebuild.
     visited, set_visited = use_state(set())
 
-    def toggle(event, place_id=0):
+    async def toggle(event, place_id=0):
         if place_id not in visited:
             set_visited({*visited, place_id})
 
     return html.div(
         html.h2("Places to visit"),
         html.ol(
             [
-                place_tree(
-                    place_id,
-                    lambda event, pid=place_id: toggle(event, pid),
-                    visited,
-                )
+                place_tree(place_id, bind_visit(toggle, place_id), visited)
                 for place_id in PLACES[0]["childIds"]
             ]
         ),

docs/examples/choosing_the_state_structure/places_nested/app.py

@@ -27,24 +27,31 @@ def place_tree(place, on_visit):
         html.button(
             {"onClick": on_visit}, "Visited" if place.get("visited") else "Visit"
         ),
-        html.ol([place_tree(child, on_visit) for child in children])
-        if children
-        else None,
+        (
+            html.ol([place_tree(child, on_visit) for child in children])
+            if children
+            else None
+        ),
     )
 
 
 @component
 def travel_plan():
     plan, set_plan = use_state(INITIAL_PLAN)
 
+    def make_visit(place_id):
+        # A factory, because a handler has to be a coroutine and a coroutine
+        # cannot be a lambda — this is how the id gets bound instead.
+        async def visit(event):
+            set_plan(mark_visited(plan, place_id))
+
+        return visit
+
     return html.div(
         html.h2("Places to visit"),
         html.ol(
             [
-                place_tree(
-                    place,
-                    lambda event, pid=place["id"]: set_plan(mark_visited(plan, pid)),
-                )
+                place_tree(place, make_visit(place["id"]))
                 for place in plan["childPlaces"]
             ]
         ),

docs/examples/choosing_the_state_structure/snacks_duplicated/app.py

@@ -15,15 +15,27 @@ def menu():
     items, set_items = use_state(INITIAL_ITEMS)
     selected_item, set_selected_item = use_state(INITIAL_ITEMS[0])
 
-    def handle_item_change(item_id, event):
-        new_title = event["target"]["value"]
+    async def handle_item_change(item_id, event):
+        new_title = await event.target.value
         set_items(
             [
                 {**item, "title": new_title} if item["id"] == item_id else item
                 for item in items
             ]
         )
 
+    def make_change(item):
+        async def change(event):
+            await handle_item_change(item["id"], event)
+
+        return change
+
+    def make_choose(item):
+        async def choose(event):
+            set_selected_item(item)
+
+        return choose
+
     return html.div(
         html.h2("What's your travel snack?"),
         html.ul(
@@ -33,13 +45,11 @@ def handle_item_change(item_id, event):
                     html.input(
                         {
                             "value": item["title"],
-                            "onChange": lambda event, i=item: handle_item_change(
-                                i["id"], event
-                            ),
+                            "onChange": make_change(item),
                         }
                     ),
                     html.button(
-                        {"onClick": lambda event, i=item: set_selected_item(i)},
+                        {"onClick": make_choose(item)},
                         "Choose",
                     ),
                 )

docs/examples/choosing_the_state_structure/snacks_normalized/app.py

@@ -18,15 +18,27 @@ def menu():
     # Derived: there is exactly one copy of the title, and it lives in items.
     selected_item = next(item for item in items if item["id"] == selected_id)
 
-    def handle_item_change(item_id, event):
-        new_title = event["target"]["value"]
+    async def handle_item_change(item_id, event):
+        new_title = await event.target.value
         set_items(
             [
                 {**item, "title": new_title} if item["id"] == item_id else item
                 for item in items
             ]
         )
 
+    def make_change(item_id):
+        async def change(event):
+            await handle_item_change(item_id, event)
+
+        return change
+
+    def make_choose(item_id):
+        async def choose(event):
+            set_selected_id(item_id)
+
+        return choose
+
     return html.div(
         html.h2("What's your travel snack?"),
         html.ul(
@@ -36,13 +48,11 @@ def handle_item_change(item_id, event):
                     html.input(
                         {
                             "value": item["title"],
-                            "onChange": lambda event, i=item: handle_item_change(
-                                i["id"], event
-                            ),
+                            "onChange": make_change(item["id"]),
                         }
                     ),
                     html.button(
-                        {"onClick": lambda event, i=item: set_selected_id(i["id"])},
+                        {"onClick": make_choose(item["id"])},
                         "Choose",
                     ),
                 )