:construction: Start replacing old test examples with structured examples.

4 files changed, 212 insertions, 0 deletions

diff --git a/examples/02-interactivity/README.md b/examples/02-interactivity/README.md
new file mode 100644
index 0000000..d97f618
--- /dev/null
+++ b/examples/02-interactivity/README.md
@@ -0,0 +1,111 @@
+# 02 Interactivity
+
+In this example we show the basic structure of all Lustre applications with a
+classic counter example.
+
+## The Model-View-Update architecture
+
+All Lustre applications are built around the Model-View-Update (MVU) architecture.
+This is a pattern that's been popularised by the Elm programming language and
+has since been adopted by many other frameworks and languages.
+
+MVU applications are built around three main concepts:
+
+- A `Model` and a function to initialise it.
+- A `Msg` type and a function to update the model based on messages.
+- A `View` function to render the model as a Lustre `Element`.
+
+These three pieces come together to form a self-contained update loop. You produce
+an initial model, render it as HTML, and convert any user interactions into
+messages to handle in the update function.
+
+ ```text
+                                        +--------+
+                                        |        |
+                                        | update |
+                                        |        |
+                                        +--------+
+                                          ^    |
+                                          |    |
+                                      Msg |    | Model
+                                          |    |
+                                          |    v
++------+                         +------------------------+
+|      |          Model          |                        |
+| init |------------------------>|     Lustre Runtime     |
+|      |                         |                        |
++------+                         +------------------------+
+                                          ^    |
+                                          |    |
+                                      Msg |    | Model
+                                          |    |
+                                          |    v
+                                        +--------+
+                                        |        |
+                                        |  view  |
+                                        |        |
+                                        +--------+
+```
+
+### Model
+
+The model represents the entire state of your application. For most Lustre
+applications this will be a record, but for this example we're aliasing `Int` to
+our `Model` type to keep things simple.
+
+We also need to write an `init` function that returns the initial state of our
+application. It takes one argument, known as "flags" which is provided when the
+application is first started.
+
+```gleam
+fn init(initial_count: Int) -> Model {
+  case initial_count < 0 {
+    True -> 0
+    False -> initial_count
+  }
+}
+```
+
+Our `init` function takes a starting count, but ensures it cannot be below `0`.
+
+### Update
+
+In many other frameworks, it's common to update state directly in an event handler.
+MVU applications take a different approach: instead of state updates being scattered
+around your codebase, they are handled in a single `update` function.
+
+To achieve this, we define a `Msg` type that represents all the different kinds of
+messages our application can receive. If you're familiar with Erlang this approach
+to state management will be familiar to you. If you're coming from a JavaScript
+background, this approach is most-similar to state management solutions like Redux
+or Vuex.
+
+```gleam
+pub opaque type Msg {
+  Incr
+  Decr
+}
+```
+
+This approach means it is easy to quickly get an idea of all the ways your app
+can change state, and makes it easy to add new state changes over time. By pattern
+matching on an incoming message in our `update` function, we can lean on Gleam's
+_exhaustiveness checking_ to ensure we handle all possible messages.
+
+### View
+
+
+
+```gleam
+fn view(model: Model) -> Element(Msg) {
+  ...
+}
+```
+
+
+## Creating a dynamic Lustre application
+
+In the previous example we used the `lustre.element` function to construct a
+static Lustre app. To construct a simple interactive app we can use `lustre.simple`
+instead. From now on we'll see that all the different ways to construct a Lustre
+application all take the same three `init`, `update`, and `view` functions.
diff --git a/examples/02-interactivity/gleam.toml b/examples/02-interactivity/gleam.toml
new file mode 100644
index 0000000..4368c0c
--- /dev/null
+++ b/examples/02-interactivity/gleam.toml
@@ -0,0 +1,11 @@
+name = "app"
+version = "1.0.0"
+target = "javascript"
+
+[dependencies]
+gleam_stdlib = "~> 0.34 or ~> 1.0"
+lustre = { path = "../../" }
+lustre_ui = "~> 0.3"
+
+[dev-dependencies]
+gleeunit = "~> 1.0"
diff --git a/examples/02-interactivity/manifest.toml b/examples/02-interactivity/manifest.toml
new file mode 100644
index 0000000..4033048
--- /dev/null
+++ b/examples/02-interactivity/manifest.toml
@@ -0,0 +1,24 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "argv", version = "1.0.1", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "A6E9009E50BBE863EB37D963E4315398D41A3D87D0075480FC244125808F964A" },
+  { name = "gleam_community_ansi", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "gleam_community_colour"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "FE79E08BF97009729259B6357EC058315B6FBB916FAD1C2FF9355115FEB0D3A4" },
+  { name = "gleam_community_colour", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "A49A5E3AE8B637A5ACBA80ECB9B1AFE89FD3D5351FF6410A42B84F666D40D7D5" },
+  { name = "gleam_erlang", version = "0.24.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "26BDB52E61889F56A291CB34167315780EE4AA20961917314446542C90D1C1A0" },
+  { name = "gleam_json", version = "0.7.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "thoas"], otp_app = "gleam_json", source = "hex", outer_checksum = "CB405BD93A8828BCD870463DE29375E7B2D252D9D124C109E5B618AAC00B86FC" },
+  { name = "gleam_otp", version = "0.9.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "5FADBBEC5ECF3F8B6BE91101D432758503192AE2ADBAD5602158977341489F71" },
+  { name = "gleam_stdlib", version = "0.34.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "1FB8454D2991E9B4C0C804544D8A9AD0F6184725E20D63C3155F0AEB4230B016" },
+  { name = "gleeunit", version = "1.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "D364C87AFEB26BDB4FB8A5ABDE67D635DC9FA52D6AB68416044C35B096C6882D" },
+  { name = "glint", version = "0.14.0", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_stdlib", "snag", "gleam_community_colour"], otp_app = "glint", source = "hex", outer_checksum = "21AB16D5A50D4EF34DF935915FDBEE06B2DAEDEE3FCC8584C6E635A866566B38" },
+  { name = "lustre", version = "3.1.3", build_tools = ["gleam"], requirements = ["argv", "gleam_community_ansi", "gleam_erlang", "gleam_json", "gleam_otp", "gleam_stdlib", "glint"], source = "local", path = "../.." },
+  { name = "lustre_ui", version = "0.3.0", build_tools = ["gleam"], requirements = ["gleam_community_colour", "lustre", "gleam_stdlib"], otp_app = "lustre_ui", source = "hex", outer_checksum = "F81BE5D20153CFFC717C2C4687A19375A8613528908AF7069DDA1B929C8398B1" },
+  { name = "snag", version = "0.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "snag", source = "hex", outer_checksum = "54D32E16E33655346AA3E66CBA7E191DE0A8793D2C05284E3EFB90AD2CE92BCC" },
+  { name = "thoas", version = "0.4.1", build_tools = ["rebar3"], requirements = [], otp_app = "thoas", source = "hex", outer_checksum = "4918D50026C073C4AB1388437132C77A6F6F7C8AC43C60C13758CC0ADCE2134E" },
+]
+
+[requirements]
+gleam_stdlib = { version = "~> 0.34 or ~> 1.0" }
+gleeunit = { version = "~> 1.0" }
+lustre = { path = "../../" }
+lustre_ui = { version = "~> 0.3"}
diff --git a/examples/02-interactivity/src/app.gleam b/examples/02-interactivity/src/app.gleam
new file mode 100644
index 0000000..e47b7a4
--- /dev/null
+++ b/examples/02-interactivity/src/app.gleam
@@ -0,0 +1,66 @@
+import gleam/int
+import lustre
+import lustre/attribute
+import lustre/element.{type Element}
+import lustre/element/html
+import lustre/event
+// These examples are written with lustre_ui in mind. They'll work regardless,
+// but to see what lustre_ui can do make sure to run each of these examples with
+// the `--include-styles` flag:
+//
+//   $ gleam run -m lustre/try -- --include-styles
+//
+// In your own apps, make sure to add the `lustre_ui` dependency and include the
+// stylesheet somewhere.
+import lustre/ui
+
+// MAIN ------------------------------------------------------------------------
+
+pub fn main() {
+  let app = lustre.simple(init, update, view)
+  let assert Ok(_) = lustre.start(app, "#app", 0)
+}
+
+// MODEL -----------------------------------------------------------------------
+
+type Model =
+  Int
+
+fn init(initial_count: Int) -> Model {
+  case initial_count < 0 {
+    True -> 0
+    False -> initial_count
+  }
+}
+
+// UPDATE ----------------------------------------------------------------------
+
+pub opaque type Msg {
+  Incr
+  Decr
+}
+
+fn update(model: Model, msg: Msg) -> Model {
+  case msg {
+    Incr -> model + 1
+    Decr -> model - 1
+  }
+}
+
+// VIEW ------------------------------------------------------------------------
+
+fn view(model: Model) -> Element(Msg) {
+  let count = int.to_string(model)
+  let styles = [#("width", "100vw"), #("height", "100vh")]
+
+  ui.centre(
+    [attribute.style(styles)],
+    ui.stack([], [
+      ui.button([event.on_click(Incr)], [element.text("+")]),
+      html.p([attribute.style([#("text-align", "center")])], [
+        element.text(count),
+      ]),
+      ui.button([event.on_click(Decr)], [element.text("-")]),
+    ]),
+  )
+}