About this lab

Focus: Laminar, a reactive UI library fo Scala.js

Agenda

How the exercises work

Fake potion store

Var, Signal, EventStream

val heat: Var[Int] = Var(40)

val colour: Signal[String] =
  heat.signal.map(h =>
    if h > 80 then "crimson" else "violet")

val bubbles: EventStream[Unit] =
  EventStream.periodic(500).mapToUnit

Binding with <-- and -->

def cauldron(heat: Var[Int]): HtmlElement =
  div(
    cls := "cauldron",
    backgroundColor <-- heat.signal.map(colourFor), // data → DOM
    input(
      typ := "range", minAttr := "0", maxAttr := "100",
      controlled(
        value <-- heat.signal.map(_.toString),
        onInput.mapToValue.map(_.toInt) --> heat     // DOM → data
      )
    ),
    child.text <-- heat.signal.map(h => s"$h°"),
    button("Stir", onClick --> (_ => heat.update(_ + 5)))
  )

<-- reads into the element · --> writes out of it

Subscription ownership

div(
  EventStream.periodic(1000) --> (_ => println("tick")), // stops on unmount
  onMountCallback(ctx => println("mounted"))
)

Controlled inputs

case class Potion(name: String, doses: Int, drinkable: Boolean, explosive: Boolean)

val potion = Var(Potion("", 1, drinkable = true, explosive = false))

input(
  controlled(
    value <-- potion.signal.map(_.name),
    onInput.mapToValue --> potion.updater[String]((p, n) => p.copy(name = n))
  )
)

• controlled makes the Var the single source of truth
• Filter input before it lands: onInput.mapToValue.filter(_.forall(_.isDigit))

Lenses over a case-class Var

Simplified updaters for large form-like data (product types).

val form = VarLenses(Potion("", 1, drinkable = true, explosive = false))

input(controlled(
  value <-- form.name.view,
  onInput.mapToValue --> form.name.updater
))

• form.name is a named tuple with two fields: updater: Observer[String] and view: Signal[String].
• Compatible with any case class that supports scala.deriving.Mirror.

Validation is just a Signal

case class Problem(field: String, message: String)

def validate(p: Potion): List[Problem] =
  List(
    Option.when(p.name.isBlank)(Problem("name", "Every potion needs a name")),
    Option.when(p.doses > 12)(Problem("doses", "At most 12 doses per batch")),
    Option.when(p.drinkable && p.explosive)(
      Problem("explosive", "A potion may not be both drinkable and explosive"))
  ).flatten

val problems: Signal[List[Problem]] = potion.signal.map(validate)

A pure function: test it without a browser

Errors after blur or submit

val touched = Var(Set.empty[String])
val submitted = Var(false)

def errorsFor(field: String): Signal[List[Problem]] =
  problems
    .combineWith(touched.signal, submitted.signal)
    .map((ps, t, s) => if s || t(field) then ps.filter(_.field == field) else Nil)

input(onBlur --> (_ => touched.update(_ + "name")), /* ... */)

form(onSubmit.preventDefault --> { _ =>
  submitted.set(true)
  if validate(potion.now()).isEmpty then save(potion.now())
})

The backend: Oracle

trait Oracle:
  def searchIngredients(query: String): Future[List[Ingredient]]
  def inventory(): Future[List[Stock]]
  def save(stock: Stock): Future[Stock]
  def delete(id: StockId): Future[Unit]
  def register(potion: Potion): Future[String]

• Runs in the browser, with random latency (100–1500 ms)
• 10 % of calls fail
• Latency and failure rate are adjustable in each exercise page's oracle panel

Stale responses

val query = Var("")

val results: EventStream[List[Ingredient]] =
  query.signal.changes
    .debounce(300)                                       // wait for a pause
    .flatMapSwitch(q =>                                  // drop stale answers
      EventStream.fromFuture(oracle.searchIngredients(q)))

• flatMapMerge shows whichever response arrives last
• flatMapSwitch only emits the response to the latest request

Modelling remote state

enum Remote[+A]:
  case Loading
  case Ready(value: A)
  case Failed(reason: String)

def consult[A](f: => Future[A]): Signal[Remote[A]] =
  EventStream
    .fromFuture(f.map(Remote.Ready(_)).recover(e => Remote.Failed(e.getMessage)))
    .startWith(Remote.Loading)

child <-- consult(oracle.inventory()).map {
  case Remote.Loading       => p(cls := "loading", "Loading…")
  case Remote.Ready(items)  => ul(items.map(i => li(i.name)))
  case Remote.Failed(why)   => p(cls := "error", why, button("Retry", onClick --> retry))
}

Keyed lists with split

val stock: Var[List[Stock]] = Var(Nil)

ul(
  children <-- stock.signal.split(_.id) { (id, initial, item: Signal[Stock]) =>
    li(
      child.text <-- item.map(_.name),
      child.text <-- item.map(s => s" × ${s.quantity}"),
      button("−", onClick --> (_ => adjust(id, -1)))
    )
  }
)

• One element per id, created once, then fed an updated Signal
• Focus, scroll and CSS transitions survive updates

A component is a function

object DoseInput:
  def apply(value: Signal[Int], onChange: Observer[Int], max: Int = 12): HtmlElement =
    div(
      cls := "dose-input",
      button("−", onClick(_.sample(value).map(v => (v - 1) max 1)) --> onChange),
      child.text <-- value,
      button("+", onClick(_.sample(value).map(v => (v + 1) min max)) --> onChange)
    )

• In: Signals. Out: Observers. Return: an element
• State lives where it is needed, usually in the page, not the component
• To expose more, return a small class: .element plus extra signals

Error handling

AirstreamError.registerUnhandledErrorCallback(e => notices.emit(Notice.Bug(e)))

JavaScript interop

object Confetti:
  @js.native @JSImport("https://esm.sh/canvas-confetti@1.9.3", JSImport.Default)
  def fire(options: js.Object): js.Promise[Unit] = js.native

button(
  "Brew!",
  onClick --> (_ => Confetti.fire(js.Dynamic.literal(particleCount = 150, spread = 70)))
)

Libraries that own DOM nodes: create on mount, destroy on unmount

div(onMountUnmountCallback(
  mount = ctx => chart = Chart(ctx.thisNode.ref, config),
  unmount = _ => chart.destroy()
))

notebook.sc

// cell: a slider widget
val heatH =
  Widgets.slider("heat", 0, 100, 40)

// cell: re-runs when heat changes
if heat > 80 then "high" else "normal"

The plugin contract

case class Rgb(r: Int, g: Int, b: Int) derives Json.ReadWriter   // upickle

object Main extends LaminarPlugin:                                // notebook-plugin-api
  def view(payload: Signal[String], ctx: PluginContext): HtmlElement =
    val widget = ctx.widgetOpt.get.as[Rgb](Rgb(0, 0, 0))          // value, set, signal
    val colour = Var(widget.value)
    div(widget.signal --> colour, sliders(colour, onChange = widget.writer))

// a notebook cell
case class Rgb(r: Int, g: Int, b: Int)
  derives ConfiguredJsonValueCodec
val mixH = Widgets.custom[Rgb](
  "mix", "potions/mixer",
  config = "{}", Rgb(180, 40, 120))

Capstone options

./sake widget recipe WATCH=1 · ./sake notebook

Summary