From 5c2461ab11db767a32bc157e7b5d6f0d082882a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Katariina=20J=C3=A4rvenm=C3=A4ki?=
 <katariina.jarvenmaki@proton.me>
Date: Sat, 4 Apr 2026 22:01:24 +0300
Subject: [PATCH] Add async event handling example with mutable state

---
 README.md                 | 22 ++++++++++++++--------
 examples/async/nappi.itp  | 29 +++++++++++++++++++++++++++++
 examples/basics/index.itp | 39 +++++++++++++++++++++++++++++++++++++--
 3 files changed, 80 insertions(+), 10 deletions(-)
 create mode 100644 examples/async/nappi.itp

diff --git a/README.md b/README.md
index 3af90a8..6e832fb 100644
--- a/README.md
+++ b/README.md
@@ -17,14 +17,20 @@ make
 Then serve locally and open in your browser:
 
 ```sh
-python3 -m http.server 9994 --directory examples/basics
+python3 -m http.server 9994 --directory examples
 ```
 
+Open `http://localhost:9994/basics/index.html` for the full example index, or go directly:
+
 | URL | What it does |
 |-----|-------------|
-| `http://localhost:9994/hello.html` | Alerts "Hei maailma!" on load |
-| `http://localhost:9994/factorial.html` | Prompts for n, displays n! |
-| `http://localhost:9994/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/basics/hello.html` | Alerts "Hei maailma!" on load |
+| `http://localhost:9994/basics/factorial.html` | Prompts for n, displays n! |
+| `http://localhost:9994/basics/fibonacci.html` | Prompts for n, displays fib(n) |
+| `http://localhost:9994/data-structures/lista.html` | List sorted ascending and descending |
+| `http://localhost:9994/data-structures/vektori.html` | Custom class, Euclidean length of [3,4] = 5 |
+| `http://localhost:9994/strings/merkkijono.html` | String length, concat, trim, split |
+| `http://localhost:9994/async/nappi.html` | Click handlers, mutable counter |
 
 ## What is Tampio?
 
@@ -46,10 +52,10 @@ See [`docs/cheatsheet.md`](docs/cheatsheet.md) for a map of Finnish grammatical
 | Directory | Contents |
 |-----------|----------|
 | `examples/basics/` | Hello world, factorial, Fibonacci |
-| `examples/data-structures/` | Lists, maps |
-| `examples/strings/` | String manipulation |
-| `examples/async/` | Promise / async usage |
-| `examples/program/` | A small complete program |
+| `examples/data-structures/` | Built-in list operations, custom class |
+| `examples/strings/` | String length, concat, trim, split |
+| `examples/async/` | DOM click handlers, mutable state |
+| `examples/program/` | A small complete program (coming soon) |
 
 ## Local Setup (without Docker)
 
diff --git a/examples/async/nappi.itp b/examples/async/nappi.itp
new file mode 100644
index 0000000..ce3c536
--- /dev/null
+++ b/examples/async/nappi.itp
@@ -0,0 +1,29 @@
+# Nappi — DOM Events and State in Tampio
+#
+# Tampio handles async interactions through DOM event handlers.
+# The key pattern is "X:tä painettaessa käyköön niin, että ..."
+# which attaches a click handler to a button element.
+#
+# State is stored in a "muuttuja" (variable object with an "arvo" field).
+# "kasvatetaan yhdellä" increments the stored value in place.
+# "näytetään käyttäjälle" writes the current value to the page output.
+#
+# DOM utilities:
+#   etsii elementin nimellä "id" tuloksenaan X  = document.getElementById
+#   kirjoitetaan koodi "html"                    = element.innerHTML =
+#   pyyhitään                                    = element.innerHTML = ""
+
+# Global counter — persists across button clicks
+Olkoon kiva laskuri uusi muuttuja, jonka arvo on nolla.
+
+Kun nykyinen sivu avautuu,
+	nykyinen sivu etsii elementin nimellä "output" tuloksenaan kiva alue,
+	kivalle alueelle kirjoitetaan koodi "<p><button id='natti'>+1</button> <button id='hieno'>+10</button></p>",
+	nykyinen sivu etsii elementin nimellä "natti" tuloksenaan nätti nappi,
+	nykyinen sivu etsii elementin nimellä "hieno" tuloksenaan hieno nappi,
+	nättiä nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan yhdellä
+		ja	kivan laskurin arvo näytetään käyttäjälle
+ja	hienoa nappia painettaessa käyköön niin, että
+			kivan laskurin arvoa kasvatetaan kymmenellä
+		ja	kivan laskurin arvo näytetään käyttäjälle.
diff --git a/examples/basics/index.itp b/examples/basics/index.itp
index 1c05bab..eb60002 100644
--- a/examples/basics/index.itp
+++ b/examples/basics/index.itp
@@ -26,9 +26,29 @@
 # Addition uses illative case: lisättynä kaniin
 # n-2 computed by chaining: edeltäjän edeltäjä
 
+# Lista — List Operations
+#
+# Built-in lista type: size, first element, iteration,
+# ascending and descending sort.
+
+# Vektori — Custom Class
+#
+# User-defined class with fields and recursive methods.
+# Euclidean length of vector [3,4] = 5.
+
+# Merkkijono — Strings
+#
+# Length, concatenation, trim, and comma-split.
+
+# Nappi — DOM Events
+#
+# Click handlers with "X:tä painettaessa käyköön niin, että".
+# Mutable counter state persists across button clicks.
+
 Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<h1>Tampiorama</h1>",
 	nykyinen sivu näyttää tekstin "<p>Annotated examples for <a href='https://github.com/fergusq/tampio'>Tampio</a>, a natural-language OOP language using Finnish grammar that compiles to JavaScript.</p>",
+	nykyinen sivu näyttää tekstin "<h2>Basics</h2>",
 	nykyinen sivu näyttää tekstin "<h3><a href='hello.html'>Hei maailma →</a></h3>",
 	nykyinen sivu näyttää tekstin "<p>Hello world. Page-load entry point, browser alert.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — it will alert 'Hei maailma!' immediately.</em></p>",
@@ -36,5 +56,20 @@ Kun nykyinen sivu avautuu,
 	nykyinen sivu näyttää tekstin "<p>Recursive factorial. Ternary branching, adessive multiplication.</p>",
 	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 5, and see 120.</em></p>",
 	nykyinen sivu näyttää tekstin "<h3><a href='fibonacci.html'>Fibonacci-kani →</a></h3>",
-	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>"
-ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>".
+	nykyinen sivu näyttää tekstin "<p>Recursive Fibonacci. Illative addition, predecessor chaining.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — enter a number when prompted, e.g. 10, and see 55.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Data Structures</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/lista.html'>Lista →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Built-in list: size, first element, ascending and descending sort.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see the list [3,1,4,1,5] sorted both ways.</em></p>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../data-structures/vektori.html'>Vektori →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>Custom class with fields and recursive methods. Euclidean length of [3,4] = 5.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see dimension, sum, and Euclidean length of vector [3,4].</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Strings</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../strings/merkkijono.html'>Merkkijono →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>String length, concatenation, trim, and comma-split iteration.</p>",
+	nykyinen sivu näyttää tekstin "<p><em>Open the page — see string ops applied to 'Hei, Tampio!'.</em></p>",
+	nykyinen sivu näyttää tekstin "<h2>Async / Events</h2>",
+	nykyinen sivu näyttää tekstin "<h3><a href='../async/nappi.html'>Nappi →</a></h3>",
+	nykyinen sivu näyttää tekstin "<p>DOM click handlers. Mutable counter state persists across button clicks.</p>"
+ja	nykyinen sivu näyttää tekstin "<p><em>Open the page — click +1 or +10 and watch the counter update.</em></p>".