Improving examples and docs

.github/workflows/ci.yml

@@ -4,10 +4,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
     - uses: coursier/cache-action@v6
-    - uses: olafurpg/setup-scala@v11
+    - uses: coursier/setup-action@v1
       with:
         java-version: [email protected]
-    - name: Indigo Compile & Test
-      run: ./mill __.compile
+    - name: Compile & Test
+      run: bash ci.sh

ci.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# This script is used to everything basically builds correctly in a CI environment.
+
+set -e
+
+./mill __.compile
+./mill __.fastLinkJS
+
+cd integration-examples
+bash ci.sh
+cd ..

examples/effects/cats-effect/README.md

@@ -0,0 +1 @@
+# Cats Effect

examples/effects/cats-effect/src/Main.scala

@@ -6,18 +6,33 @@ import tyrian.*
 
 import scala.scalajs.js.annotation.*
 
+/** To use Tyrian with Cats Effect, we need to bring in the tyrian-io library.
+  *
+  * ```
+  * ivy"io.indigoengine::tyrian-io::x.y.z" // Mill
+  * libraryDependencies += "io.indigoengine" %%% "tyrian-io" % "x.y.z" // SBT
+  * ```
+  *
+  * Then we can bring in the `TyrianIOApp` trait to create our application.
+  */
+//```scala
 @JSExportTopLevel("TyrianApp")
 object Counter extends TyrianIOApp[Msg, Model]:
+//```
 
   def router: Location => Msg = Routing.none(Msg.NoOp)
 
   def init(flags: Map[String, String]): (Model, Cmd[IO, Msg]) =
     (Model.init, Cmd.None)
 
+  /** `Cmd`s and `Sub`s then make use of the `IO` type to perform side effects.
+    */
+  // ```scala
   def update(model: Model): Msg => (Model, Cmd[IO, Msg]) =
     case Msg.Increment => (model + 1, Cmd.None)
     case Msg.Decrement => (model - 1, Cmd.None)
     case Msg.NoOp      => (model, Cmd.None)
+  // ```
 
   def view(model: Model): Html[Msg] =
     div(
@@ -26,8 +41,10 @@ object Counter extends TyrianIOApp[Msg, Model]:
       button(onClick(Msg.Increment))("+")
     )
 
+  // ```scala
   def subscriptions(model: Model): Sub[IO, Msg] =
     Sub.None
+  // ```
 
 opaque type Model = Int
 object Model:
@@ -38,4 +55,4 @@ object Model:
     def -(other: Int): Model = i - other
 
 enum Msg:
-  case Increment, Decrement, NoOp
+  case Increment, Decrement, NoOp

examples/effects/fs2/README.md

@@ -0,0 +1 @@
+# FS2

examples/effects/zio/README.md

@@ -0,0 +1 @@
+# ZIO

examples/effects/zio/src/Main.scala

@@ -7,18 +7,33 @@ import zio.interop.catz.*
 
 import scala.scalajs.js.annotation.*
 
+/** To use Tyrian with ZIO, we need to bring in the tyrian-zio library.
+  *
+  * ```
+  * ivy"io.indigoengine::tyrian-zio::x.y.z" // Mill
+  * libraryDependencies += "io.indigoengine" %%% "tyrian-zio" % "x.y.z" // SBT
+  * ```
+  *
+  * Then we can bring in the `TyrianZIOApp` trait to create our application.
+  */
+//```scala
 @JSExportTopLevel("TyrianApp")
 object Main extends TyrianZIOApp[Msg, Model]:
+//```
 
   def router: Location => Msg = Routing.none(Msg.NoOp)
 
   def init(flags: Map[String, String]): (Model, Cmd[Task, Msg]) =
     (Model.init, Cmd.None)
 
+  /** `Cmd`s and `Sub`s then make use of ZIO's `Task` type to perform side effects.
+    */
+  // ```scala
   def update(model: Model): Msg => (Model, Cmd[Task, Msg]) =
     case Msg.Increment => (model + 1, Cmd.None)
     case Msg.Decrement => (model - 1, Cmd.None)
     case Msg.NoOp      => (model, Cmd.None)
+  // ```
 
   def view(model: Model): Html[Msg] =
     div(
@@ -27,8 +42,10 @@ object Main extends TyrianZIOApp[Msg, Model]:
       button(onClick(Msg.Increment))("+")
     )
 
+  // ```scala
   def subscriptions(model: Model): Sub[Task, Msg] =
     Sub.None
+  // ```
 
 opaque type Model = Int
 object Model:

examples/getting-started/minimal/README.md

@@ -0,0 +1 @@
+# Minimal Setup

examples/getting-started/subcomponents/README.md

@@ -0,0 +1 @@
+# Sub-Components

examples/networking/http/README.md

@@ -0,0 +1 @@
+# Http

examples/networking/http4s-dom/README.md

@@ -0,0 +1 @@
+# Http4s-Dom

examples/networking/websockets/README.md

@@ -0,0 +1 @@
+# WebSockets

examples/networking/websockets/src/Main.scala

@@ -76,9 +76,6 @@ object Model:
   val init: Model =
     Model(EchoSocket.init, Nil)
 
-/** Encapsulates and manages our socket connection, cleanly proxies methods, and knows how to draw the right
-  * connnect/disconnect button.
-  */
 final case class EchoSocket(socketUrl: String, socket: Option[WebSocket[IO]]):
 
   def connectDisconnectButton =

examples/svg/clock/README.md

@@ -0,0 +1 @@
+# Clock SVG

examples/ui/debouncing/README.md

@@ -0,0 +1 @@
+# Debouncing

examples/ui/field/README.md

@@ -0,0 +1 @@
+# Input Field

website/CNAME

@@ -0,0 +1 @@
+tyrian.indigoengine.io

website/documentation/directory.conf

@@ -5,4 +5,5 @@ laika.navigationOrder = [
   architecture
   information
   guides
+  integration-examples.md
 ]

website/documentation/integration-examples.md

@@ -0,0 +1,7 @@
+# Integration-Examples
+
+The 'feature examples' available on this website try to cover how to use Tyrian, but not the various ways that it can be setup and integrated with different build tools, services, networking protocols, and css frameworks.
+
+Some examples of those kinds of integrations can be found in the [integrated-examples](https://github.com/PurpleKingdomGames/tyrian-docs/tree/main/integrated-examples) folder of the tyrian-docs repo.
+
+> Note: The networking examples are duplicated in both example areas. In the feature examples they compile and are viewable, but may not work. In the integrated examples, if run correctly, they should work.

website/examples/directory.conf

@@ -1 +1 @@
-laika.title = "Examples"
+laika.title = "Feature Examples"