@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/datastar/signals.md

@@ -0,0 +1,230 @@
+---
+id: signals
+title: "Signal"
+sidebar_label: "Signals"
+---
+
+`Signal[A]` is a named, typed handle on a piece of state that lives in the browser. `Signal#:=` pairs it with a value to produce a `SignalUpdate[A]`, serialized through the type's JSON codec, and `Signal#ref` produces the `$name` reference form used inside Datastar expressions. Names are validated — literals during compilation. The three types:
+
+```scala
+final class Signal[A] private (val name: String) {
+  def :=(value: A)(implicit schema: Schema[A]): SignalUpdate[A]
+  def ref: DatastarRef
+}
+
+final class SignalUpdate[A] private (val name: String, val serialized: String)
+
+final class DatastarRef private (val signalName: String) {
+  val value: String   // "$" + signalName
+}
+```
+
+## Motivation
+
+Datastar identifies state by name, as a string, on both sides of the wire. The browser reads `data-signals="{count: 0}"`, an expression refers to `$count`, and the server patches it with `signals {"count": 42}`. Three places, one name, and nothing checks that they agree.
+
+They disagree in ways that produce no error. A signal referenced as `$cont` is simply undefined, so the expression evaluates to nothing and the element renders blank. A patch sent for `"counter"` when the page declared `"count"` creates a second signal nobody reads. Both look like the feature is broken rather than the name being wrong.
+
+`Signal[A]` makes the name a value declared once, so all three uses are the same Scala identifier. Declaring it also validates it — and the type parameter decides how values serialize, so a `Signal[Int]` cannot be patched with a string.
+
+## Quick Showcase
+
+Declare a signal, then use the same value for the attribute, the expression, and the patch:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count = Signal[Int]("count")
+```
+
+The three forms it produces — an initial value, a reference, and a patch:
+
+```scala
+(count := 0).serialized
+// res0: String = "0"
+count.ref.value
+// res1: String = "$count"
+DatastarEvent.patchSignals(count := 42).renderSSE
+// res2: String = """event: datastar-patch-signals
+// data: signals {"count":42}
+// 
+// """
+```
+
+## Construction
+
+Two constructors. They differ in when a *literal* name is checked; for a computed name both check at runtime.
+
+### `Signal.apply` — checked at compile time
+
+`Signal[A]("name")` validates a literal name during compilation, so a malformed name is a build failure rather than a silently dead expression:
+
+```scala
+import zio.http.datastar._
+
+val count   = Signal[Int]("count")
+val nested  = Signal[String]("user.profile.name")
+```
+
+Dotted names are how Datastar expresses nested signal namespaces, and each segment is validated separately:
+
+```scala
+count.name
+// res4: String = "count"
+nested.name
+// res5: String = "user.profile.name"
+```
+
+### `Signal.dynamic` — checked at runtime
+
+`Signal.apply` also accepts a computed name — its macro falls back to a runtime check when the argument is not a literal — so `Signal.dynamic` is not strictly required. Prefer it anyway for computed names, because it states that intent at the call site. Either way the check throws `IllegalArgumentException`:
+
+```scala
+object Signal {
+  def dynamic[A](name: String): Signal[A]
+}
+```
+
+Use it for names derived from data — a row id, a tenant prefix — and validate before constructing if the source is untrusted:
+
+```scala
+import zio.http.datastar._
+
+def rowSignal(id: Long): Signal[Boolean] = Signal.dynamic[Boolean](s"row$id.selected")
+```
+
+A well-formed computed name behaves exactly like a literal one:
+
+```scala
+rowSignal(17).name
+// res7: String = "row17.selected"
+rowSignal(17).ref.value
+// res8: String = "$row17.selected"
+```
+
+A malformed one fails at the point of construction rather than in the browser:
+
+```scala
+scala.util.Try(Signal.dynamic[Int]("has spaces")).failed.map(_.getMessage)
+// res9: Try[String] = Success(
+//   "Invalid Datastar signal name 'has spaces'. Signal names must be dot-separated JavaScript identifiers and must not contain '__'."
+// )
+```
+
+### Name Rules
+
+A valid name is one or more dot-separated segments, each a Java identifier, and must not contain `__`:
+
+| Name | Valid | Why |
+| ---- | ----- | --- |
+| `count` | yes | single identifier |
+| `user.profile.name` | yes | dot-separated identifiers |
+| `row17.selected` | yes | digits are identifier parts, just not the first character |
+| `row.17.selected` | **no** | the segment `17` starts with a digit |
+| `has spaces` | no | space is not an identifier character |
+| `count__case` | no | `__` is reserved for Datastar modifier syntax |
+| `` (empty) | no | at least one segment is required |
+| `a..b` | no | empty segment |
+
+Two of these catch people out. The `__` restriction exists because Datastar uses a double underscore to separate an attribute name from its modifiers, so a signal containing one would be parsed as a modifier suffix. And every segment must *start* with an identifier-start character, which rules out a purely numeric segment — the natural `s"row.$id.selected"` for a per-row signal is rejected, and `s"row$id.selected"` is the form that works.
+
+## Producing Values
+
+A signal on its own is just a name. Two methods turn it into something renderable.
+
+### `Signal#:=` — pair a value with the name
+
+`Signal#:=` requires a `Schema[A]` and serializes through that schema's JSON codec, producing a `SignalUpdate[A]`:
+
+```scala
+final class Signal[A] {
+  def :=(value: A)(implicit schema: Schema[A]): SignalUpdate[A]
+}
+```
+
+The update holds the name and the already-serialized JSON:
+
+```scala
+import zio.http.datastar._
+
+final case class Point(x: Int, y: Int)
+
+object Point {
+  implicit val schema: zio.blocks.schema.Schema[Point] = zio.blocks.schema.Schema.derived[Point]
+}
+
+val origin = Signal[Point]("origin")
+```
+
+Because serialization goes through the schema, a case class signal works without extra ceremony:
+
+```scala
+(origin := Point(3, 4)).serialized
+// res11: String = "{\"x\":3,\"y\":4}"
+```
+
+:::warning[`serialized` is inserted verbatim]
+`SignalUpdate#serialized` is spliced directly into the rendered expression or SSE payload. It is produced by the schema codec, so it is valid JSON — but if you construct a payload by other means (`DatastarEvent.patchSignalsRaw`), you are responsible for the JSON being well formed.
+:::
+
+### `Signal#ref` — refer to the signal in an expression
+
+`Signal#ref` returns a `DatastarRef`, whose `value` is the name prefixed with `$` — the form Datastar expressions use to read a signal:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val price    = Signal[Double]("price")
+val quantity = Signal[Int]("quantity")
+```
+
+A reference renders as `$name`, and both `Signal` and `DatastarRef` have `ToJs` instances so either can be interpolated into a `js"..."` expression:
+
+```scala
+price.ref.value
+// res13: String = "$price"
+js"$price * $quantity".value
+// res14: String = "$price * $quantity"
+```
+
+Interpolating the signal itself is equivalent to interpolating its ref, which is why most code never mentions `DatastarRef` explicitly.
+
+## SignalUpdate
+
+`SignalUpdate[A]` carries a name and its serialized value. Beyond being consumed by `DatastarEvent.patchSignals` and the `dataSignals` attribute, it renders as a JavaScript object literal.
+
+### `SignalUpdate.objectExpression`
+
+`SignalUpdate.objectExpression` renders one or more updates as a single object expression, which is what the `data-signals` attribute contains:
+
+```scala
+object SignalUpdate {
+  def objectExpression(update: SignalUpdate[_], updates: SignalUpdate[_]*): String
+}
+```
+
+Several updates become one object, with each key quoted:
+
+```scala
+import zio.http.datastar._
+
+val price    = Signal[Double]("price")
+val quantity = Signal[Int]("quantity")
+```
+
+Keys are escaped, so a dotted signal name stays a single key rather than becoming a nested path:
+
+```scala
+SignalUpdate.objectExpression(price := 9.99, quantity := 2)
+// res16: String = "{\"price\": 9.99, \"quantity\": 2}"
+```
+
+An implicit `ToJs[SignalUpdate[A]]` renders a single update the same way, so an update can be interpolated into an expression directly.
+
+## Integration Points
+
+`Signal` sits at the centre of the module: [Attributes](./attributes.md) accept signals as values and as keys (`dataBind`, `dataComputed`, `dataIndicator`), [Event Handlers](./events.md) reference them inside expressions, and [Server-Sent Events](./sse.md) patch them by name.
+
+Outside the module, `Signal#:=` depends on `Schema[A]` and its JSON codec from [Schema](../schema/index.md), and the `ToJs` instances come from [HTML](../html.md), which is what lets a signal be interpolated into `js"..."`.

package/reference/datastar/sse.md

@@ -0,0 +1,295 @@
+---
+id: sse
+title: "Server-Sent Events"
+sidebar_label: "Server-Sent Events"
+---
+
+`DatastarEvent` builds the events a server sends to patch a live page: replace elements, patch signals, execute a script, or remove elements. Each constructor returns a builder for its event kind, and `DatastarEvent#renderSSE` produces the wire format. `DatastarEvent.executeScript` is the exception noted below: it reuses the element-patch builder, so it offers two options that do not apply to it. Supporting types: `PatchElementsBuilder`, `PatchSignalsBuilder`, `RemoveElementsBuilder`, `ElementPatchMode`, `EventType`. The constructors and the one method they all end in:
+
+```scala
+sealed trait DatastarEvent {
+  def renderSSE: String
+}
+
+object DatastarEvent {
+  def patchElements(elements: Dom): PatchElementsBuilder
+  def patchSignals(first: SignalUpdate[_], rest: SignalUpdate[_]*): PatchSignalsBuilder
+  def patchSignalsRaw(json: String): PatchSignalsBuilder
+  def executeScript(code: Js): PatchElementsBuilder
+  def removeElements(selector: CssSelector): RemoveElementsBuilder
+}
+```
+
+## Motivation
+
+The Datastar response protocol is SSE with structure inside the `data:` field. A patch looks like this on the wire:
+
+```
+event: datastar-patch-elements
+data: selector #results
+data: mode append
+data: elements <li>Widget</li>
+
+```
+
+Three things make that easy to get wrong by hand. The event name must match the protocol exactly. The `data:` lines are a small keyed format, not free text, and the keys differ per event kind. And the terminating blank line is required — omit it and the browser waits indefinitely for an event it already has.
+
+`DatastarEvent` removes all three concerns. Each constructor knows its event name, each builder method maps to one protocol field, and `DatastarEvent#renderSSE` delegates the SSE envelope to `ServerSentEvent`, which supplies the terminator.
+
+## Quick Showcase
+
+Build an event and render it:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count = Signal[Int]("count")
+```
+
+A signal patch is one line of data:
+
+```scala
+DatastarEvent.patchSignals(count := 42).renderSSE
+// res0: String = """event: datastar-patch-signals
+// data: signals {"count":42}
+// 
+// """
+```
+
+An element patch carries its target and mode:
+
+```scala
+DatastarEvent
+  .patchElements(li("Widget"))
+  .selector(CssSelector.id("results"))
+  .mode(ElementPatchMode.Append)
+  .renderSSE
+// res1: String = """event: datastar-patch-elements
+// data: selector #results
+// data: mode append
+// data: elements <li>Widget</li>
+// 
+// """
+```
+
+## Patching Elements
+
+`DatastarEvent.patchElements` takes a `Dom` and returns a `PatchElementsBuilder`. Its options map one-to-one onto protocol fields:
+
+| Method | Field | Default |
+| ------ | ----- | ------- |
+| `selector(CssSelector)` | `selector` | omitted — patch by element id |
+| `mode(ElementPatchMode)` | `mode` | `Outer`, which is omitted |
+| `viewTransition` | `useViewTransition true` | omitted |
+| `namespace(String)` | `namespace` | omitted |
+| `eventId(String)` | SSE `id:` | omitted |
+| `retry(Long)` | SSE `retry:` | omitted |
+
+Every option is omitted when unset, so the minimal event is just the elements:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val row = li("Widget")
+```
+
+With no selector, Datastar matches on the element's own id, and `mode` is absent because `Outer` is the default:
+
+```scala
+DatastarEvent.patchElements(row).renderSSE
+// res3: String = """event: datastar-patch-elements
+// data: elements <li>Widget</li>
+// 
+// """
+```
+
+Adding options adds exactly the corresponding lines:
+
+```scala
+DatastarEvent.patchElements(row).selector(CssSelector.id("list")).viewTransition.eventId("evt-1").renderSSE
+// res4: String = """event: datastar-patch-elements
+// id: evt-1
+// data: selector #list
+// data: useViewTransition true
+// data: elements <li>Widget</li>
+// 
+// """
+```
+
+:::note[`mode` is omitted when it is `Outer`]
+`ElementPatchMode.Outer` is the protocol default, so setting it explicitly produces no `mode` line. That is intentional and keeps the payload minimal; do not read the absence of a `mode` line as "no mode".
+:::
+
+### ElementPatchMode
+
+Eight modes decide where the content lands relative to the target. Each renders as its lowercase name:
+
+| Mode | Effect |
+| ---- | ------ |
+| `Outer` | Replace the target element itself *(default)* |
+| `Inner` | Replace the target's children |
+| `Replace` | Replace using replacement semantics |
+| `Prepend` | Insert before the target's existing children |
+| `Append` | Insert after the target's existing children |
+| `Before` | Insert immediately before the target |
+| `After` | Insert immediately after the target |
+| `Remove` | Remove the target |
+
+`Append` is the one to reach for when adding to a list without re-rendering it:
+
+```scala
+ElementPatchMode.Append.render
+// res5: String = "append"
+ElementPatchMode.Inner.render
+// res6: String = "inner"
+```
+
+## Patching Signals
+
+`DatastarEvent.patchSignals` takes one or more `SignalUpdate`s and renders them as a single JSON object under the `signals` key:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val price    = Signal[Double]("price")
+val quantity = Signal[Int]("quantity")
+```
+
+Multiple updates go in one event rather than one event each:
+
+```scala
+DatastarEvent.patchSignals(price := 19.99, quantity := 3).renderSSE
+// res8: String = """event: datastar-patch-signals
+// data: signals {"price":19.99,"quantity":3}
+// 
+// """
+```
+
+`PatchSignalsBuilder#onlyIfMissing` adds `onlyIfMissing true`, which tells Datastar to set the signal only when it is not already present — the way to supply a default without clobbering client state:
+
+```scala
+DatastarEvent.patchSignals(price := 0.0).onlyIfMissing.renderSSE
+// res9: String = """event: datastar-patch-signals
+// data: onlyIfMissing true
+// data: signals {"price":0.0}
+// 
+// """
+```
+
+### `DatastarEvent.patchSignalsRaw` — pre-serialized JSON
+
+When the JSON already exists — from a cache, or a shape no `Schema` describes — `DatastarEvent.patchSignalsRaw` takes it verbatim:
+
+```scala
+DatastarEvent.patchSignalsRaw("""{"count":7}""").renderSSE
+// res10: String = """event: datastar-patch-signals
+// data: signals {"count":7}
+// 
+// """
+```
+
+:::warning[`patchSignalsRaw` does not validate]
+The string is inserted into the payload unchanged. Malformed JSON produces an event the browser silently discards, and there is no server-side error. Prefer `DatastarEvent.patchSignals` with typed updates, which cannot produce invalid JSON.
+:::
+
+## Executing Scripts
+
+`DatastarEvent.executeScript` takes a `Js` and returns a `PatchElementsBuilder` — because on the wire it *is* an element patch, appending a `<script>` element that the browser executes:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+The rendered event shows the mechanism rather than hiding it:
+
+```scala
+DatastarEvent.executeScript(js"console.log('done')").renderSSE
+// res12: String = """event: datastar-patch-elements
+// data: selector body
+// data: mode append
+// data: elements <script data-effect="el.remove()">console.log('done')</script>
+// 
+// """
+```
+
+The script is appended to `body` and carries `data-effect="el.remove()"`, so it deletes itself after running and leaves no residue in the DOM.
+
+Because the return type is `PatchElementsBuilder`, the element-patch options are all available — including `selector` and `mode`, which would override that targeting and rarely make sense here. Treat the builder as offering `PatchElementsBuilder#eventId` and `PatchElementsBuilder#retry`.
+
+## Removing Elements
+
+`DatastarEvent.removeElements` takes a `CssSelector` and returns a `RemoveElementsBuilder` with a deliberately narrow surface — `viewTransition`, `namespace`, `RemoveElementsBuilder#eventId`, and `RemoveElementsBuilder#retry`:
+
+```scala
+DatastarEvent.removeElements(CssSelector.id("banner")).renderSSE
+// res13: String = """event: datastar-patch-elements
+// data: selector #banner
+// data: mode remove
+// data: elements 
+// 
+// """
+```
+
+There is no `mode` or `selector` method, because the selector is the argument and the mode is fixed to `remove` with an empty element body. That is the builder pattern doing its job: an option that would be meaningless is not offered.
+
+## EventType
+
+`EventType` names the protocol event in the SSE `event:` field. Two values, and you rarely name them directly since each constructor selects the right one:
+
+| Value | Renders |
+| ----- | ------- |
+| `EventType.PatchElements` | `datastar-patch-elements` |
+| `EventType.PatchSignals` | `datastar-patch-signals` |
+
+Both render the protocol string rather than the Scala name:
+
+```scala
+EventType.PatchElements.render
+// res14: String = "datastar-patch-elements"
+EventType.PatchSignals.render
+// res15: String = "datastar-patch-signals"
+```
+
+Both element patches and script execution use `PatchElements`, and removal does too — the distinction between them is in the `data:` body, not the event name.
+
+## Streaming Several Events
+
+`DatastarEvent#renderSSE` produces one complete event including its terminating blank line, so a stream is a concatenation. Nothing in the module manages the stream itself; you write the strings to whatever response body your HTTP layer uses:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val progress = Signal[Int]("progress")
+
+val stream: String =
+  (1 to 3).map(step => DatastarEvent.patchSignals(progress := step * 33).renderSSE).mkString
+```
+
+Each event is self-delimiting, so concatenating what `DatastarEvent#renderSSE` returns is valid SSE:
+
+```scala
+stream
+// res17: String = """event: datastar-patch-signals
+// data: signals {"progress":33}
+// 
+// event: datastar-patch-signals
+// data: signals {"progress":66}
+// 
+// event: datastar-patch-signals
+// data: signals {"progress":99}
+// 
+// """
+```
+
+Set `PatchElementsBuilder#eventId` when the client should be able to resume with `Last-Event-ID`, and `PatchElementsBuilder#retry` to control the reconnection delay — both are ordinary SSE fields handled by `ServerSentEvent`.
+
+## Integration Points
+
+`DatastarEvent#renderSSE` delegates to `ServerSentEvent` from `zio-http-model`, which supplies the SSE envelope, the field ordering, and the terminating blank line — see [ServerSentEvent](../http-model/server-sent-event.md). The Datastar-specific part is the event name and the keyed `data:` body.
+
+Element patches carry `Dom` values and `CssSelector` targets from [HTML](../html.md), and signal patches carry [SignalUpdate](./signals.md) values whose JSON comes from the type's `Schema`. What the patched page does with the result is determined by the [Attributes](./attributes.md) and [Event Handlers](./events.md) rendered into it.