From 03a8e70b4dda39776fed4f4e435b551a261a07d5 Mon Sep 17 00:00:00 2001
From: Zainab Ali <zainab.ali.london@gmail.com>
Date: Sat, 17 Aug 2024 20:18:36 +0100
Subject: [PATCH] Support a single input element. (#58)

---
 build.sbt                                |   2 +-
 docs/aquascape.js                        |  55 +++++++++++
 docs/basic/take.md                       |  26 +++--
 docs/highlightWrapper.js                 |  23 -----
 docs/main.css                            |  14 +++
 examples/src/main/scala/Example.scala    |  89 +++++++++++++++--
 examples/src/main/scala/Examples.scala   |  53 +++++-----
 examples/src/main/scala/formCodecs.scala |  30 ++++++
 project/AquascapeDirectives.scala        | 117 +++++++++++++++--------
 9 files changed, 305 insertions(+), 104 deletions(-)
 create mode 100644 docs/aquascape.js
 delete mode 100644 docs/highlightWrapper.js
 create mode 100644 examples/src/main/scala/formCodecs.scala

diff --git a/build.sbt b/build.sbt
index 521b0d1..f0a9039 100644
--- a/build.sbt
+++ b/build.sbt
@@ -99,7 +99,7 @@ lazy val docs = project
       // Add highlight.js for code examples
       .internalJS(Root / "highlight.min.js")
       .site
-      .internalJS(Root / "highlightWrapper.js")
+      .internalJS(Root / "aquascape.js")
       .site
       .internalCSS(Root / "a11y-dark.min.css"),
     laikaExtensions += AquascapeDirectives,
diff --git a/docs/aquascape.js b/docs/aquascape.js
new file mode 100644
index 0000000..0ebccd1
--- /dev/null
+++ b/docs/aquascape.js
@@ -0,0 +1,55 @@
+var aquascape = (function () {
+
+    /** Draws an aquascape svg in-browser.
+     *
+     * @param exampleObject An instance of `aquascape.examples.Example`.
+     * @param codeId        The html id of the <code> element that should be populated.
+     * @param frameIds      An instance of `aquascape.examples.FrameIds`
+     */
+    function example(exampleObject, codeId, frameIds) {
+	highlightExampleCode(codeId);
+	exampleObject.draw(codeId, frameIds);
+    };
+
+    /** Draws an aquascape svg in-browser with a single user input.
+     *
+     * The user-input is provided through an <input> element.
+     *
+     * @param exampleObject An instance of `aquascape.examples.Example`.
+     * @param codeId        The html id of the <code> element that should be populated.
+     * @param frameIds      An instance of `aquascape.examples.FrameIds`
+     * @param labelId       The html id of the <label> element for the input.
+     * @param inputId       The html id of the <input> element.
+     */
+    function exampleWithInput(exampleObject, codeId, frameIds, labelId, inputId) {
+	highlightExampleCode(codeId);
+	document.getElementById(inputId).addEventListener("input", function (e) {
+	    exampleObject.draw(codeId, frameIds, this.value);
+	});
+	exampleObject.setup(labelId, inputId, codeId, frameIds);
+    };
+
+    /** Highlight Scala code examples.
+     *
+     * The @:example directive fills in <code> blocks
+     * asynchronously. This function adds an observer to highlight the
+     * <code> block after its text content has been set.
+     */
+    function highlightExampleCode(codeId) {
+        const targetNode = document.getElementById(codeId);
+        const config = { attributes: true, childList: true, subtree: false };
+
+        const callback = (mutationList, observer) => {
+            hljs.highlightElement(targetNode);
+            observer.disconnect();
+        };
+
+        const observer = new MutationObserver(callback);
+        observer.observe(targetNode, config);
+    };
+
+    return {
+	example: example,
+	exampleWithInput: exampleWithInput
+    };
+})();
diff --git a/docs/basic/take.md b/docs/basic/take.md
index 5db54ea..3d7d600 100644
--- a/docs/basic/take.md
+++ b/docs/basic/take.md
@@ -1,16 +1,26 @@
 # take
-## fewer
 
-@:example(TakeFewer)
+Experiment with taking a number of elements from an infinite stream.
 
-## more
+Note that the resulting stream is finite because a fixed number of elements are pulled.
 
-@:example(TakeMore)
+@:exampleWithInput(TakeFromAnInfiniteStream) {
+  drawChunked = false
+}
 
-## from an infinite stream
 
-@:example(TakeFromAnInfiniteStream)
+## `take` from finite streams
 
-## from a drained stream
+Experiment with taking a number of elements from a finite stream.
 
-@:example(TakeFromADrainedStream)
+@:exampleWithInput(TakeFromAFiniteStream) {
+  drawChunked = false
+}
+
+## Drained streams
+
+Drained streams output no elements, but may still capture side-effects.
+
+@:example(TakeFromADrainedStream) {
+  drawChunked = false
+}
diff --git a/docs/highlightWrapper.js b/docs/highlightWrapper.js
deleted file mode 100644
index 8e9a809..0000000
--- a/docs/highlightWrapper.js
+++ /dev/null
@@ -1,23 +0,0 @@
-var hljsWrapper = (function () {
-    /** Highlight Scala code examples.
-     *
-     * The @:example directive fills in <code> blocks
-     * asynchronously. This function adds an observer to highlight the
-     * <code> block after its text content has been set.
-     */
-    function highlightExampleCode(codeId) {
-        const targetNode = document.getElementById(codeId);
-        const config = { attributes: true, childList: true, subtree: false };
-
-        const callback = (mutationList, observer) => {
-            hljs.highlightElement(targetNode);
-            observer.disconnect();
-        };
-
-        const observer = new MutationObserver(callback);
-        observer.observe(targetNode, config);
-    };
-    return {
-	highlightExampleCode: highlightExampleCode
-    };
-})();
diff --git a/docs/main.css b/docs/main.css
index 774ef76..6b38375 100644
--- a/docs/main.css
+++ b/docs/main.css
@@ -13,3 +13,17 @@ div.example-frame svg {
 pre.example-code {
     padding: 0;
 }
+
+div.example-input {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+}
+
+div.example-input > label {
+    font-size: var(--header3-font-size);
+    
+}    
+
+div.example-input > input {
+    padding: 12px;
+}
diff --git a/examples/src/main/scala/Example.scala b/examples/src/main/scala/Example.scala
index a21e7f2..6c9236c 100644
--- a/examples/src/main/scala/Example.scala
+++ b/examples/src/main/scala/Example.scala
@@ -24,6 +24,7 @@ import cats.effect.unsafe.implicits.global
 import doodle.svg.*
 import doodle.syntax.all.*
 import org.scalajs.dom
+import cats.syntax.all.*
 
 import scala.scalajs.js.annotation.JSExport
 import scala.scalajs.js.annotation.JSExportTopLevel
@@ -48,17 +49,71 @@ object FrameIds {
 trait Example {
   @JSExport
   final def draw(codeId: String, frameIds: FrameIds): Unit = {
-    drawFrames(codeId, frameIds)(apply)
+    drawFrames(codeId, frameIds)(apply).unsafeRunAsync {
+      case Left(err) => throw err
+      case Right(_)  => ()
+    }
   }
 
   def apply(using Scape[IO]): StreamCode
 }
 
+/** Describes how a value encodes to and from an <input> element.
+  *
+  * In practice, this only works for numbers. More work is needed to support
+  * coproducts (e.g. with radio buttons).
+  */
+trait FormCodec[A] {
+
+  def attributes: Map[String, String]
+  def inputType: String
+
+  def decode(text: String): Option[A]
+  def encode(a: A): String
+}
+
+trait ExampleWithInput[A: FormCodec] {
+
+  def label: String
+  def default: A
+
+  @JSExport
+  final def setup(
+      labelId: String,
+      inputId: String,
+      codeId: String,
+      frameIds: FrameIds
+  ): Unit = {
+    val program = for {
+      _ <- drawFrames(codeId, frameIds)(apply(default))
+      _ <- drawLabel(labelId, label)
+      _ <- setValue(inputId, default)
+    } yield ()
+    program.unsafeRunAsync {
+      case Left(err) => throw err
+      case Right(_)  => ()
+    }
+  }
+
+  @JSExport
+  final def draw(codeId: String, frameIds: FrameIds, param: String): Unit = {
+    summon[FormCodec[A]]
+      .decode(param)
+      .traverse_ { a => drawFrames(codeId, frameIds)(apply(a)) }
+      .unsafeRunAsync {
+        case Left(err) => throw err
+        case Right(_)  => ()
+      }
+  }
+
+  def apply(a: A)(using Scape[IO]): StreamCode
+}
+
 private def drawFrames(
     codeId: String,
     frameIds: FrameIds
-)(stream: Scape[IO] ?=> StreamCode): Unit = {
-  val program = for {
+)(stream: Scape[IO] ?=> StreamCode): IO[Unit] = {
+  for {
     code <- {
       frameIds match {
         case FrameIds.Unchunked(id) => drawFrame(id, false)(stream)
@@ -71,11 +126,8 @@ private def drawFrames(
     }
     codeEl <- IO(dom.document.getElementById(codeId))
     _ <- IO(codeEl.textContent = code.code)
+      .whenA(codeEl.textContent.trim.isEmpty)
   } yield ()
-  program.unsafeRunAsync {
-    case Left(err) => throw err
-    case Right(_)  => ()
-  }
 }
 
 private def drawFrame(frameId: String, chunked: Boolean)(
@@ -90,6 +142,29 @@ private def drawFrame(frameId: String, chunked: Boolean)(
       streamCode.stream.attempt.void.draw(),
       seed = Some("MTIzNDU=")
     )
+    frameEl <- IO(dom.document.getElementById(frameId))
+    // If there is already an image, remove it.
+    _ <- IO(
+      Option(frameEl.firstChild).foreach(child => frameEl.removeChild(child))
+    )
     _ <- picture.drawWithFrameToIO(frame)
   } yield streamCode
 }
+
+private def drawLabel(labelId: String, label: String): IO[Unit] = {
+  for {
+    labelEl <- IO(dom.document.getElementById(labelId))
+    _ <- IO(labelEl.textContent = label)
+  } yield ()
+}
+private def setValue[A: FormCodec](inputId: String, default: A): IO[Unit] = {
+  for {
+    inputEl <- IO(dom.document.getElementById(inputId))
+    codec = summon[FormCodec[A]]
+    _ <- IO(inputEl.setAttribute("type", codec.inputType))
+    _ <- IO(inputEl.setAttribute("value", codec.encode(default)))
+    _ <- codec.attributes.toList.traverse_ { case (k, v) =>
+      IO(inputEl.setAttribute(k, v))
+    }
+  } yield ()
+}
diff --git a/examples/src/main/scala/Examples.scala b/examples/src/main/scala/Examples.scala
index e277987..700cce2 100644
--- a/examples/src/main/scala/Examples.scala
+++ b/examples/src/main/scala/Examples.scala
@@ -103,46 +103,47 @@ object BasicCompileOnlyOrError extends Example {
     )
 }
 
-@JSExportTopLevel("TakeFewer")
-object TakeFewer extends Example {
-  def apply(using Scape[IO]): StreamCode =
+import formCodecs.given
+
+@JSExportTopLevel("TakeFromAnInfiniteStream")
+object TakeFromAnInfiniteStream extends ExampleWithInput[Int] {
+
+  def label: String = "n (number of elements to take)"
+
+  def default: Int = 3
+
+  def apply(n: Int)(using Scape[IO]): StreamCode =
     code(
-      Stream('a', 'b', 'c')
-        .stage("Stream('a','b','c')")
-        .take(2)
-        .stage("take(2)")
+      Stream('a').repeat
+        .stage("Stream('a').repeat")
+        .take(n)
+        .stage(s"take($n)")
         .compile
         .toList
         .compileStage("compile.toList")
     )
 }
 
-@JSExportTopLevel("TakeMore")
-object TakeMore extends Example {
-  def apply(using Scape[IO]): StreamCode =
+@JSExportTopLevel("TakeFromAFiniteStream")
+object TakeFromAFiniteStream extends ExampleWithInput[Int] {
+
+  def label: String = "n (number of elements to take)"
+
+  def default: Int = 2
+
+  def apply(n: Int)(using Scape[IO]): StreamCode =
     code(
       Stream('a', 'b', 'c')
         .stage("Stream('a','b','c')")
-        .take(5)
-        .stage("take(5)")
-        .compile
-        .toList
-        .compileStage("compile.toList")
-    )
-}
-@JSExportTopLevel("TakeFromAnInfiniteStream")
-object TakeFromAnInfiniteStream extends Example {
-  def apply(using Scape[IO]): StreamCode =
-    code(
-      Stream('a').repeat
-        .stage("Stream('a').repeat")
-        .take(2)
-        .stage("take(2)")
+        .take(n)
+        .stage(s"take($n)")
         .compile
         .toList
         .compileStage("compile.toList")
     )
 }
+
+
 @JSExportTopLevel("TakeFromADrainedStream")
 object TakeFromADrainedStream extends Example {
   import NothingShow.given
@@ -912,3 +913,5 @@ object TimeDebounceAwake extends Example {
         .compileStage("compile.toList")
     )
 }
+
+
diff --git a/examples/src/main/scala/formCodecs.scala b/examples/src/main/scala/formCodecs.scala
new file mode 100644
index 0000000..e67e736
--- /dev/null
+++ b/examples/src/main/scala/formCodecs.scala
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2023 Zainab Ali
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package aquascape.examples
+
+object formCodecs {
+  given FormCodec[Int] = new FormCodec[Int] {
+    def attributes: Map[String, String] = Map(
+      "min" -> "0",
+      "max" -> "10"
+    )
+    def inputType: String = "number"
+    def encode(i: Int): String = i.toString
+    def decode(text: String): Option[Int] =
+      scala.util.Try(Integer.parseInt(text)).toOption
+  }
+}
diff --git a/project/AquascapeDirectives.scala b/project/AquascapeDirectives.scala
index 37df1ab..b9a761f 100644
--- a/project/AquascapeDirectives.scala
+++ b/project/AquascapeDirectives.scala
@@ -32,59 +32,96 @@ object AquascapeDirectives extends DirectiveRegistry {
   // Parameter is the name of the JS instance of aquascape.example.Example
   val example: BlockDirectives.Directive =
     BlockDirectives.create("example") {
-      import BlockDirectives.dsl.*
-      (attribute(0).as[String], attribute("drawChunked").as[Boolean].optional)
+      exampleAttributes
         .mapN { case (example, drawChunked) =>
           val codeId = s"${example}Code"
 
-          val (svgEls, frameIds) = {
-            val unchunkedFrameId = example
-            val chunkedFrameId = s"${example}Chunked"
-            val unchunkedSnippet = Seq(
-              html(
-                s"""<div id="$unchunkedFrameId" class="example-frame"></div>"""
-              )
-            )
-            val chunkedSnippet = Seq(
-              html("<h3>chunked</h3>"),
-              html(
-                s"""<div id="$chunkedFrameId" class="example-frame"></div>"""
-              )
-            )
-            drawChunked match {
-              case None =>
-                (
-                  unchunkedSnippet ++ chunkedSnippet,
-                  s"""ExampleFrameIds.both("$unchunkedFrameId", "$chunkedFrameId")"""
-                )
-              case Some(true) =>
-                (
-                  chunkedSnippet,
-                  s"""ExampleFrameIds.chunked("$chunkedFrameId")"""
-                )
-              case Some(false) =>
-                (
-                  unchunkedSnippet,
-                  s"""ExampleFrameIds.chunked("$chunkedFrameId")"""
-                )
-            }
-          }
-          val codeEl = html(
-            s"""<pre class="example-code"><code id="$codeId" class="language-scala"></code></pre>"""
+          val (svgEls, frameIds) = frameElsAndIds(example, drawChunked)
+
+          val scriptEl = html(
+            s"""<script>
+                   | aquascape.example($example, "$codeId", $frameIds);
+                   |</script>""".stripMargin
+          )
+          BlockSequence(codeEl(codeId) +: svgEls :+ scriptEl)
+        }
+    }
+  val exampleWithInput: BlockDirectives.Directive =
+    BlockDirectives.create("exampleWithInput") {
+      exampleAttributes
+        .mapN { case (example, drawChunked) =>
+          val codeId = s"${example}Code"
+          val (svgEls, frameIds) = frameElsAndIds(example, drawChunked)
+
+          val labelId = s"${example}Label"
+          val inputId = s"${example}Input"
+          val inputEls = BlockSequence(
+            Seq(
+              html(s"""<label id="$labelId" for="$inputId"></label>"""),
+              html(s"""<input id="$inputId"></input>""")
+            ),
+            Options(styles = Set("example-input"))
           )
 
           val scriptEl = html(
             s"""<script>
-                   | hljsWrapper.highlightExampleCode("$codeId");
-                   | ${example}.draw("$codeId", $frameIds);
+                   | aquascape.exampleWithInput($example, "$codeId", $frameIds, "$labelId", "$inputId");
                    |</script>""".stripMargin
           )
-          BlockSequence(codeEl +: svgEls :+ scriptEl)
+          BlockSequence(inputEls +: (codeEl(codeId) +: svgEls :+ scriptEl))
         }
     }
 
+  private def exampleAttributes: (
+      BlockDirectives.DirectivePart[String],
+      BlockDirectives.DirectivePart[Option[Boolean]]
+  ) = {
+    import BlockDirectives.dsl.*
+    (attribute(0).as[String], attribute("drawChunked").as[Boolean].optional)
+  }
+  private def codeEl(codeId: String): RawContent = {
+    html(
+      s"""<pre class="example-code"><code id="$codeId" class="language-scala"></code></pre>"""
+    )
+  }
+
+  private def frameElsAndIds(
+      example: String,
+      drawChunked: Option[Boolean]
+  ): (Seq[RawContent], String) = {
+    val unchunkedFrameId = example
+    val chunkedFrameId = s"${example}Chunked"
+    val unchunkedSnippet = Seq(
+      html(
+        s"""<div id="$unchunkedFrameId" class="example-frame"></div>"""
+      )
+    )
+    val chunkedSnippet = Seq(
+      html("<h3>chunked</h3>"),
+      html(
+        s"""<div id="$chunkedFrameId" class="example-frame"></div>"""
+      )
+    )
+    drawChunked match {
+      case None =>
+        (
+          unchunkedSnippet ++ chunkedSnippet,
+          s"""ExampleFrameIds.both("$unchunkedFrameId", "$chunkedFrameId")"""
+        )
+      case Some(true) =>
+        (
+          chunkedSnippet,
+          s"""ExampleFrameIds.chunked("$chunkedFrameId")"""
+        )
+      case Some(false) =>
+        (
+          unchunkedSnippet,
+          s"""ExampleFrameIds.unchunked("$unchunkedFrameId")"""
+        )
+    }
+  }
   val spanDirectives = Seq.empty
-  val blockDirectives = Seq(example)
+  val blockDirectives = Seq(example, exampleWithInput)
   val templateDirectives = Seq.empty
   val linkDirectives = Seq.empty
 }