Example apps refinement.

Author: ntoll

docs/example-apps/bouncing-ball/game.py

@@ -2,6 +2,9 @@
 Bouncing Ball - PyGame-CE demo for PyScript.
 
 Based on the PyGame-CE quickstart tutorial.
+
+Note the use of `await asyncio.sleep()` in place of `pygame.time.Clock()`
+to yield to the event loop and keep the browser responsive.
 """
 import asyncio
 import sys
@@ -21,14 +24,13 @@
     for event in pygame.event.get():
         if event.type == pygame.QUIT:
             sys.exit()
-
     ballrect = ballrect.move(speed)
     if ballrect.left < 0 or ballrect.right > width:
         speed[0] = -speed[0]
     if ballrect.top < 0 or ballrect.bottom > height:
         speed[1] = -speed[1]
-
     screen.fill(black)
     screen.blit(ball, ballrect)
     pygame.display.flip()
+    # Needed to yield to the event loop to keep the browser responsive.
     await asyncio.sleep(1/60)

docs/example-apps/bouncing-ball/info.md

@@ -1,10 +1,13 @@
 # Bouncing Ball
 
+[Run the app](index.html) | 
+[View the code on GitHub](https://github.com/pyscript/docs/tree/main/docs/example-apps/bouncing-ball)
+
 A simple PyGame-CE demonstration running in the browser with PyScript.
 Based on the
 [PyGame-CE quickstart tutorial](https://pyga.me/docs/tutorials/en/intro-to-pygame.html).
 
-## What it shows
+## What it demonstrates
 
 - Running PyGame-CE in the browser with the `py-game` script type.
 - Using `await asyncio.sleep()` for frame timing in the browser.
@@ -20,21 +23,4 @@ yields control to the browser with `await asyncio.sleep(1/60)`.
 
 The `await` at the top level works because PyScript provides an async
 context. This wouldn't run in standard Python without wrapping in an
-async function.
-
-## Required files
-
-You'll need to download `intro_ball.webp` from the PyGame-CE repository:
-https://raw.githubusercontent.com/pygame-community/pygame-ce/80fe4cb9f89aef96f586f68d269687572e7843f6/docs/reST/tutorials/assets/intro_ball.gif
-
-Place it in the same directory as the other files.
-
-## Running locally
-
-Serve the files with any web server:
-
-```sh
-python -m http.server 8000
-```
-
-Then visit `http://localhost:8000/` in your browser.
+async function.

docs/example-apps/colour-picker/info.md

@@ -1,33 +1,28 @@
 # Interactive Colour Picker
 
+[Run the app](index.html) | 
+[View the code on GitHub](https://github.com/pyscript/docs/tree/main/docs/example-apps/colour-picker) 
+
 A colour picker application demonstrating various event handling
 patterns in PyScript.
 
 ## What it demonstrates
 
-**Multiple event types:**
-- `input` events - RGB sliders update in real-time.
-- `change` events - Number inputs and hex input.
-- `click` events - Preset buttons and history colours.
-
-**Stacked decorators:**
-- Single function handling multiple sliders with `@when` stacked three
-  times.
-
-**Custom events:**
-- `colour_changed` Event for decoupling colour updates from history
-  management.
-- Shows how to separate concerns in your application.
-
-**Working with form inputs:**
-- Range sliders, number inputs, text inputs.
-- Synchronising values across different input types.
-- Validating and clamping values.
-
-**Dynamic UI updates:**
-- Updating display colour.
-- Maintaining colour history.
-- Creating history elements dynamically.
+* Multiple event types with `input` events (RGB sliders update in real-time), 
+`change` events (number inputs and hex input) and `click` events (preset
+buttons and history colours).
+* Stacked decorators with a single function handling multiple sliders with
+  `@when` stacked three times.
+* Custom events via the `colour_changed` Event for decoupling colour updates
+  from app history and to show how to separate concerns in your application.
+* Working with form inputs of different types:
+    - Range sliders, number inputs, text inputs.
+    - Synchronising values across different input types.
+    - Validating and clamping values.
+* Dynamic UI updates:
+    - Updating display colour.
+    - Maintaining colour history.
+    - Creating history elements dynamically.
 
 ## Features
 
@@ -44,7 +39,7 @@ patterns in PyScript.
 - `index.html` - Page structure and styling.
 - `main.py` - Event handling logic demonstrating various patterns.
 
-## Key patterns demonstrated
+## How it works
 
 ### Stacking decorators
 
@@ -82,13 +77,3 @@ def handle_slider_change(event):
     # Update display.
     update_display(value)
 ```
-
-## Running locally
-
-Serve these files from a web server:
-
-```bash
-python3 -m http.server
-```
-
-Then open http://localhost:8000 in your browser.

docs/example-apps/colour-picker/main.py

@@ -2,32 +2,32 @@
 Interactive Colour Picker - demonstrating event handling in PyScript.
 
 Shows:
+
 - Multiple event types (input, click, change)
 - Custom events for decoupled logic
 - Working with form inputs
 - Dynamic UI updates
 """
 from pyscript import when, Event
-from pyscript.web import page
+from pyscript.web import page, div
 
 
 # Custom event for when colour changes.
-colour_changed = Event()
-
+_colour_has_changed = Event()
 # Colour history (limited to 10).
-history = []
+_HISTORY = []
 
 
 def rgb_to_hex(r, g, b):
     """
-    Convert RGB values to hex colour string.
+    Convert RGB values to a hex colour string.
     """
     return f"#{r:02X}{g:02X}{b:02X}"
 
 
 def hex_to_rgb(hex_colour):
     """
-    Convert hex colour string to RGB tuple.
+    Convert a hex colour string to an RGB tuple.
     """
     hex_colour = hex_colour.lstrip("#")
     return tuple(int(hex_colour[i:i+2], 16) for i in (0, 2, 4))
@@ -60,34 +60,28 @@ def update_controls(r, g, b):
     page["#red-slider"].value = r
     page["#green-slider"].value = g
     page["#blue-slider"].value = b
-    
     # Update number inputs.
     page["#red-value"].value = r
     page["#green-value"].value = g
     page["#blue-value"].value = b
-    
     # Update hex input.
     hex_colour = rgb_to_hex(r, g, b)
     page["#hex-input"].value = hex_colour
-    
     # Update display.
     update_display(hex_colour)
-    
     # Trigger custom event.
-    colour_changed.trigger(hex_colour)
+    _colour_has_changed.trigger(hex_colour)
 
 
 def add_to_history(hex_colour):
     """
     Add colour to history, maintaining max of 10 items.
     """
-    if hex_colour in history:
+    if hex_colour in _HISTORY:
         return
-    
-    history.insert(0, hex_colour)
-    if len(history) > 10:
-        history.pop()
-    
+    _HISTORY.insert(0, hex_colour)
+    if len(_HISTORY) > 10:
+        _HISTORY.pop()
     # Update history display.
     render_history()
 
@@ -96,14 +90,11 @@ def render_history():
     """
     Render colour history.
     """
-    from pyscript.web import div
-    
     container = page["#history-colours"]
     container.clear()
-    
-    for colour in history:
+    for colour in _HISTORY:
         colour_div = div(Class="history-colour", title=colour)
-        colour_div.style.backgroundColor = colour
+        colour_div.style["backgroundColor"] = colour
         colour_div.dataset.colour = colour
         container.append(colour_div)
 
@@ -129,12 +120,10 @@ def handle_number_change(event):
     r = int(page["#red-value"].value)
     g = int(page["#green-value"].value)
     b = int(page["#blue-value"].value)
-    
     # Clamp values.
     r = max(0, min(255, r))
     g = max(0, min(255, g))
     b = max(0, min(255, b))
-    
     update_controls(r, g, b)
 
 
@@ -144,11 +133,9 @@ def handle_hex_change(event):
     Handle hex input changes.
     """
     hex_colour = event.target.value.strip()
-    
     # Validate hex colour.
     if not hex_colour.startswith("#"):
         hex_colour = "#" + hex_colour
-    
     try:
         r, g, b = hex_to_rgb(hex_colour)
         update_controls(r, g, b)
@@ -177,7 +164,7 @@ def handle_history_click(event):
     update_controls(r, g, b)
 
 
-@when(colour_changed)
+@when(_colour_has_changed)
 def handle_colour_changed(hex_colour):
     """
     Handle custom colour changed event.

docs/example-apps/display-demo/index.html

@@ -4,8 +4,10 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
     <title>Display Demo</title>
-    <link rel="stylesheet" href="https://pyscript.net/releases/2025.11.2/core.css">
-    <script type="module" src="https://pyscript.net/releases/2025.11.2/core.js"></script>
+    <link rel="stylesheet" 
+      href="https://pyscript.net/releases/2025.11.2/core.css">
+    <script type="module" 
+      src="https://pyscript.net/releases/2025.11.2/core.js"></script>
     <style>
       body {
         font-family: system-ui, -apple-system, sans-serif;
@@ -42,6 +44,12 @@
         border-radius: 4px;
         border: 1px solid #dee2e6;
         min-height: 100px;
+        overflow: hidden;
+      }
+      .output img {
+        max-width: 100%;
+        height: auto;
+        display: block;
       }
       button {
         background: #3498db;
@@ -72,6 +80,23 @@
         opacity: 0.9;
         font-size: 0.9rem;
       }
+      .loading {
+        text-align: center;
+        color: #666;
+      }
+      .spinner {
+        border: 3px solid #f3f3f3;
+        border-top: 3px solid #3498db;
+        border-radius: 50%;
+        width: 40px;
+        height: 40px;
+        animation: spin 1s linear infinite;
+        margin: 1rem auto;
+      }
+      @keyframes spin {
+        0% { transform: rotate(0deg); }
+        100% { transform: rotate(360deg); }
+      }
     </style>
   </head>
   <body>
@@ -80,7 +105,12 @@ <h1>Display Capabilities Demo</h1>
     <div class="grid">
       <div class="panel">
         <h2>Basic Types</h2>
-        <div id="basic-output" class="output"></div>
+        <div id="basic-output" class="output">
+          <div class="loading">
+            <div class="spinner"></div>
+            <p>Loading PyScript...</p>
+          </div>
+        </div>
         <button id="btn-basic">Show Basic Types</button>
       </div>
 
@@ -113,8 +143,25 @@ <h2>Incremental Updates</h2>
         <div id="incremental-output" class="output"></div>
         <button id="btn-incremental">Start Updates</button>
       </div>
+      
+      <div class="panel">
+        <h2>Pandas DataFrame</h2>
+        <div id="dataframe-output" class="output"></div>
+        <button id="btn-dataframe">Show DataFrame</button>
+      </div>
+      
+      <div class="panel">
+        <h2>Matplotlib Plot</h2>
+        <div id="plot-output" class="output"></div>
+        <button id="btn-plot">Generate Plot</button>
+      </div>
+      
+      <div class="panel">
+        <h2>Multiple Plots</h2>
+        <div id="multiplot-output" class="output"></div>
+        <button id="btn-multiplot">Show Subplots</button>
+      </div>
     </div>
-
-    <script type="mpy" src="./main.py"></script>
+    <script type="py" src="./main.py" config="./pyscript.json"></script>
   </body>
 </html>