Expanded Tyrian Next examples

Author: davesmith00000

build.sc

@@ -10,16 +10,85 @@ object `tyrian-next-examples` extends mill.Module {
 
   object `getting-started` extends mill.Module {
 
-    object minimal       extends examplemodule.ExampleModule {
-      
+    object minimal extends examplemodule.ExampleModule {
+
       def ivyDeps =
         Agg(
           ivy"io.indigoengine::tyrian-next::$tyrianVersion"
         )
 
     }
+
     object subcomponents extends examplemodule.ExampleModule {
-      
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion"
+        )
+
+    }
+
+    object `html-fragments` extends examplemodule.ExampleModule {
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion"
+        )
+
+    }
+
+  }
+
+  object networking extends mill.Module {
+
+    object http extends examplemodule.ExampleModule {
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion",
+          ivy"io.circe::circe-core::0.14.13",
+          ivy"io.circe::circe-parser::0.14.13"
+        )
+
+    }
+
+    object websockets extends examplemodule.ExampleModule {
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion"
+        )
+
+    }
+
+  }
+
+  object svg extends mill.Module {
+
+    object clock extends examplemodule.ExampleModule {
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion"
+        )
+
+    }
+
+  }
+
+  object ui extends mill.Module {
+
+    object debouncing extends examplemodule.ExampleModule {
+
+      def ivyDeps =
+        Agg(
+          ivy"io.indigoengine::tyrian-next::$tyrianVersion"
+        )
+
+    }
+
+    object field extends examplemodule.ExampleModule {
+
       def ivyDeps =
         Agg(
           ivy"io.indigoengine::tyrian-next::$tyrianVersion"

classic-examples/svg/clock/README.md

@@ -1 +1,3 @@
 # Clock SVG
+
+This example demonstrates how to create an animated SVG clock using Tyrian. The clock displays the current time with a moving second hand that updates every second.

classic-examples/svg/clock/src/Main.scala

@@ -18,10 +18,20 @@ object Main extends TyrianIOApp[Msg, Model]:
   def init(flags: Map[String, String]): (Model, Cmd[IO, Msg]) =
     (new js.Date(), Cmd.None)
 
+  /** The update function handles tick messages by simply updating the model with the new time.
+    */
+//```scala
   def update(model: Model): Msg => (Model, Cmd[IO, Msg]) =
     case Msg.Tick(newTime) => (newTime, Cmd.None)
     case Msg.NoOp          => (model, Cmd.None)
+//```
 
+  /** The view function renders an SVG clock face with a moving second hand.
+    *
+    * We calculate the angle of the second hand based on the current seconds (0-59), then compute
+    * the X and Y coordinates for the tip of the hand using trigonometry.
+    */
+//```scala
   def view(model: Model): Html[Msg] =
     val angle = model.getSeconds() * 2 * math.Pi / 60 - math.Pi / 2
     val handX = 50 + 40 * math.cos(angle)
@@ -42,9 +52,15 @@ object Main extends TyrianIOApp[Msg, Model]:
         stroke := "#023963"
       )
     )
+//```
 
+  /** The subscription sends a tick message every second, providing the current time. This drives
+    * the clock animation by continuously updating the model.
+    */
+//```scala
   def subscriptions(model: Model): Sub[IO, Msg] =
     Sub.every[IO](1.second, "clock-ticks").map(Msg.Tick.apply)
+//```
 
 type Model = js.Date
 

tyrian-next-examples/README.md

@@ -1 +1 @@
-# Classic
+# Tyrian Next Examples

tyrian-next-examples/getting-started/html-fragments/README.md

@@ -0,0 +1,18 @@
+# Html Fragments
+
+This example is about 'Out of order' rendering.
+
+In the classic Elm style, you construct the view HTML in one go, based on the model. That works, but comes with the drawback that you have to - in effect - render everything 'in order'. Or at least, you have to co-ordinate the construction so that everything turns up in the right place. This has the knock on effect of enticing the developer away from the idea of building encapsulated components.
+
+What would be better, is if we could render all our components in any order (or the order that makes sense for the data they need), and then just mechanically glue them together, safe in the knowledge that the right fragment of HTML would turn up in the right part of the final DOM.
+
+This is the function of `HtmlRoot` and `HtmlFragment`.
+
+> `HtmlFragment` borrows from a similar notion in Indigo, called `SceneUpdateFragment`.
+
+Note that using `Marker`s is _not_ the same as HTML templating. In Tyrian, an HTML template (i.e. HTML that needs to be hydrated with data), is just a function, e.g.:
+
+```scala
+def nameInHtml(name: String): Html[GlobalMsg] =
+  p(name)
+```

tyrian-next-examples/getting-started/html-fragments/src/Main.scala

@@ -0,0 +1,108 @@
+package example
+
+import tyrian.Html.*
+import tyrian.*
+import tyrian.next.*
+import tyrian.next.syntax.*
+
+import scala.scalajs.js.annotation.*
+
+/** In order to control the rendering we need to use markers, and markers have IDs. It's a good idea
+  * to keep these as constants somewhere.
+  */
+// ```scala
+object ViewMarkers:
+  val A: MarkerId = MarkerId("a")
+  val B: MarkerId = MarkerId("b")
+  val C: MarkerId = MarkerId("c")
+// ```
+
+/** First we'll need a basic component. Since the component does almost nothing, this setup feels
+  * like overkill in our use case, but later on we'll use it to demonstrate how it makes updates and
+  * rendering easy to wire in.
+  *
+  * Notice that the `view` function is making an `HtmlFragment` using `HtmlFragment.insert`, this
+  * tells the fragment that this HTML will be assigned to a marker somewhere later.
+  */
+// ```scala
+final case class MyComponent(id: MarkerId):
+
+  def update: GlobalMsg => Outcome[MyComponent] =
+    _ => Outcome(this)
+
+  def view: HtmlFragment =
+    HtmlFragment.insert(
+      id,
+      p(s"Component: ${id.value}")
+    )
+// ```
+
+/** The model also follows the component pattern, and mechanically updates and presents the
+  * components. Nice and simple, but this pattern is useful because it allows the Model to manage
+  * the components under it (whatever manage means, could be adding more, removing, finding or
+  * altering, etc.).
+  */
+// ```scala
+final case class Model(components: Batch[MyComponent]):
+  def update: GlobalMsg => Outcome[Model] = e =>
+    components.map(_.update(e)).sequence.map { updated =>
+      this.copy(components = updated)
+    }
+
+  def view: Batch[HtmlFragment] =
+    components.map(_.view)
+// ```
+
+@JSExportTopLevel("TyrianApp")
+object Main extends TyrianNext[Model]:
+
+  def router: Location => GlobalMsg =
+    Routing.none(NoOp)
+
+  /** When we initialise the model we'll add the components purposely out of order, for
+    * demonstration purposes.
+    */
+// ```scala
+  def init(flags: Map[String, String]): Outcome[Model] =
+    Outcome(
+      Model(
+        Batch(
+          MyComponent(ViewMarkers.A),
+          MyComponent(ViewMarkers.C),
+          MyComponent(ViewMarkers.B)
+        )
+      )
+    )
+// ```
+
+  /** The main update function is simple delegation.
+    */
+// ```scala
+  def update(model: Model): GlobalMsg => Outcome[Model] =
+    case e => model.update(e)
+// ```
+
+  /** The main function does two things:
+    *
+    *   1. Sets up markers - these are placeholders for where we want the Html to end up. Notice
+    *      that these are now in order. This is very simple structure, but markers can be deeply
+    *      nested too.
+    *
+    * 2. It combines the fragment containing the markers with the result of calling view on the
+    * model, and the view is constructed for us.
+    */
+// ```scala
+  def view(model: Model): HtmlRoot =
+    HtmlRoot(
+      HtmlFragment(
+        Marker(ViewMarkers.A),
+        Marker(ViewMarkers.B),
+        Marker(ViewMarkers.C)
+      )
+    ).addHtmlFragments(model.view)
+// ```
+
+  def watchers(model: Model): Batch[Watcher] =
+    Batch.empty
+
+case object NoOp extends GlobalMsg

tyrian-next-examples/getting-started/minimal/README.md

@@ -1 +1,3 @@
 # Minimal Setup
+
+A minimal example of how to set up a Tyrian-Next app.

tyrian-next-examples/getting-started/minimal/src/Main.scala

@@ -6,13 +6,24 @@ import tyrian.next.*
 
 import scala.scalajs.js.annotation.*
 
+/** The main thing to note is that the use of `Outcome`, `Batch`, `Action`, and `Watchers`.
+  *
+  *   - `Outcome` replaces `(model, Cmd)`
+  *   - `Batch` is used as a `List` replacement. It isn't quite as friendly as list, but it is more
+  *     performant for our needs.
+  *   - `Action` replaces `Cmd` (to avoid ambiguous terms), but you can convert from one to the
+  *     other, so you can use `Cmd`s in `Action`s.
+  *   - `Watcher` replaces `Sub` (to avoid ambiguous terms), but you can convert from one to the
+  *     other, so you can use `Sub`s in `Watcher`s.
+  */
+// ```scala
 @JSExportTopLevel("TyrianApp")
 object Main extends TyrianNext[Model]:
 
   def router: Location => GlobalMsg =
     Routing.none(NoOp)
 
-  def init(flags: Map[String, String]): Outcome[Model]=
+  def init(flags: Map[String, String]): Outcome[Model] =
     Outcome(Model())
 
   def update(model: Model): GlobalMsg => Outcome[Model] =
@@ -23,14 +34,15 @@ object Main extends TyrianNext[Model]:
       Outcome(model)
 
   def view(model: Model): HtmlRoot =
-    HtmlRoot.div(
+    HtmlRoot(
       HtmlFragment(
         p("Hello, Tyrian!")
       )
     )
 
   def watchers(model: Model): Batch[Watcher] =
     Batch.empty
+// ```
 
 final case class Model()
 

tyrian-next-examples/getting-started/subcomponents/README.md

@@ -1 +1,5 @@
 # Sub-Components
+
+This is the typical Tyrian/Elm sub-component example, written in Tyrian Next style.
+
+The emphasis is on encapsulation of data and logic in 'components'. Components can contain other components and operate on them, but not the other way around. All other communication is done via messages.

tyrian-next-examples/getting-started/subcomponents/src/Counter.scala

@@ -4,6 +4,19 @@ import tyrian.*
 import tyrian.Html.*
 import tyrian.next.*
 
+/** Each individual Counter is handled with a Counter component instance. The isntance is stateful
+  * and lives in the CounterManager.
+  *
+  * The Counter component follows the typical Elm-component architecture of having an `update` and a
+  * `view` method.
+  *
+  * Since the `Counter` `update` takes a `CounterEvent`, we can have exhaustive message checking.
+  * The problem is that it means something higher up needs to pre-extract these message type for the
+  * Counters (CounterManager in this case), which can make message / event wiring fragile.
+  * 
+  * The counters view is simple enough to return normal HTML.
+  */
+// ```scala
 final case class Counter(value: Int):
   def update: CounterEvent => Counter =
     case CounterEvent.Increment =>
@@ -18,12 +31,19 @@ final case class Counter(value: Int):
       div(text(value.toString)),
       button(onClick(CounterEvent.Increment))(text("+"))
     )
+// ```
 
 object Counter:
 
   val initial: Counter =
     Counter(0)
 
+/** In Tyrian-Next, all messages extend the `GlobalMsg` type. This means that you lose absolute
+  * exhaustive message type checking, but the advantage is that it now feels natural to keep the
+  * messages types with the components they're related to.
+  */
+// ```scala
 enum CounterEvent extends GlobalMsg:
   case Increment
   case Decrement
+// ```