@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/datastar/events.md

@@ -0,0 +1,234 @@
+---
+id: events
+title: "Event Handlers"
+sidebar_label: "Event Handlers"
+---
+
+`dataOn` opens the event side of the attribute DSL: sixteen predefined DOM events, fourteen chainable modifiers, and four case modifiers, all rendering into a single `data-on:<event>__<modifiers>` attribute. Four sibling builders cover triggers that are not DOM events — intersection, interval, signal patches, and initialization. Core types: `DataOn`, `PartialDataOn`, `EventModifier`, `CaseModifier`, `DataOnIntersect`, `DataOnInterval`, `DataOnSignalPatch`, `DataInit`. The shape of the builder:
+
+```scala
+final class DataOn private (name: String, modifiers: Maybe[EventModifier], caseModifier: CaseModifier) {
+  def debounce(millis: Long): DataOn
+  def once: DataOn
+  def :=[T](value: T)(implicit toDatastarExpr: ToDatastarExpr[T]): Dom.Attribute
+}
+```
+
+## Motivation
+
+An event handler in Datastar is an attribute whose name encodes both the event and its options. `data-on:input__debounce.300ms` debounces; `data-on:click__once__prevent` fires once and calls `preventDefault`. The name is structured, order-insensitive between modifiers, and entirely stringly-typed on the wire.
+
+Written by hand that is a lot of punctuation to get right, and a modifier that Datastar does not recognize is silently ignored — the handler still fires, just without the debouncing you thought you had. A search box that issues a request per keystroke looks like it works, right up until it doesn't.
+
+`dataOn` turns the whole name into a method chain. The event is a method, each modifier is a method, and the attribute name is assembled for you. A modifier that does not exist is a compile error, and the rendered name is correct by construction.
+
+## Quick Showcase
+
+Chain modifiers before assigning the handler:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val term = Signal[String]("term")
+
+val box = input(
+  dataBind(term),
+  dataOn.input.debounce(300) := js"@get('/search')"
+)
+```
+
+The modifier becomes part of the attribute name:
+
+```scala
+box.renderMinified
+// res0: String = "<input data-bind:term data-on:input__debounce.300ms=\"@get(&#x27;/search&#x27;)\"/>"
+```
+
+## Predefined Events
+
+Sixteen events have dedicated methods, each returning a `DataOn` ready for modifiers or assignment:
+
+| Category | Methods |
+| -------- | ------- |
+| Pointer | `dataOn.click`, `dataOn.mouseover`, `dataOn.mouseout`, `dataOn.mouseenter`, `dataOn.mouseleave` |
+| Keyboard | `dataOn.keydown`, `dataOn.keyup`, `dataOn.keypress` |
+| Form | `dataOn.submit`, `dataOn.input`, `dataOn.change`, `dataOn.focus`, `dataOn.blur` |
+| Window | `dataOn.scroll`, `dataOn.resize`, `dataOn.load` |
+
+Each renders as `data-on:<event>`:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+The method name is the event name — `dataOn.click`, `dataOn.submit`, `dataOn.input` — so nothing needs looking up:
+
+```scala
+button(dataOn.click := js"@post('/save')").renderMinified
+// res2: String = "<button data-on:click=\"@post(&#x27;/save&#x27;)\"></button>"
+form(dataOn.submit := js"@post('/submit')").renderMinified
+// res3: String = "<form data-on:submit=\"@post(&#x27;/submit&#x27;)\"></form>"
+```
+
+### `dataOn.apply` — any other event
+
+For an event without a dedicated method, `dataOn(name)` takes it as a string. The name is validated, so a structurally invalid event name fails rather than rendering a broken attribute:
+
+```scala
+div(dataOn("animationend") := js"@get('/done')").renderMinified
+// res4: String = "<div data-on:animationend=\"@get(&#x27;/done&#x27;)\"></div>"
+```
+
+`dataOn` on its own is a `PartialDataOn` — the builder that the event methods live on — so `dataOn` alone is not a complete attribute.
+
+## Event Modifiers
+
+Fourteen modifiers chain before `:=`, each contributing a `__` suffix.
+
+| Method | Renders | Effect |
+| ------ | ------- | ------ |
+| `debounce(ms)` | `__debounce.<ms>ms` | Fire after quiet period |
+| `debounceLeading(ms)` | `__debounce.<ms>ms.leading` | Fire immediately, then suppress |
+| `throttle(ms)` | `__throttle.<ms>ms` | At most once per interval |
+| `throttleLeading(ms)` | `__throttle.<ms>ms.leading` | Leading-edge throttle |
+| `delay(ms)` | `__delay.<ms>ms` | Wait before firing |
+| `DataOn#once` | `__once` | Fire at most once |
+| `DataOn#passive` | `__passive` | Passive listener |
+| `DataOn#capture` | `__capture` | Capture phase |
+| `DataOn#stop` | `__stop` | `stopPropagation` |
+| `DataOn#prevent` | `__prevent` | `preventDefault` |
+| `DataOn#outside` | `__outside` | Fire on events outside the element |
+| `DataOn#window` | `__window` | Listen on the window object |
+| `DataOn#document` | `__document` | Listen on the document object |
+| `DataOn#viewTransition` | `__viewTransition` | Wrap the resulting patch in a view transition |
+
+Modifiers combine, and the rendered name carries each one:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+A click that fires once and suppresses the default action needs two, `DataOn#once` and `DataOn#prevent`:
+
+```scala
+button(dataOn.click.once.prevent := js"@post('/subscribe')").renderMinified
+// res6: String = "<button data-on:click__once__prevent=\"@post(&#x27;/subscribe&#x27;)\"></button>"
+```
+
+`DataOn#outside` is the one worth knowing about: it inverts the target, firing when the event happens anywhere *but* this element — which is how a dropdown closes when you click away:
+
+```scala
+div(dataOn.click.outside := js"$$open = false").renderMinified
+// res7: String = "<div data-on:click__outside=\"$open = false\"></div>"
+```
+
+Repeating a timing or target modifier does not stack: the chain is normalized to the last effective value before the name is rendered, so chaining `DataOn#debounce` twice keeps only the second value.
+
+Modifiers are represented by the `EventModifier` ADT — `Debounce`, `Throttle`, `Delay`, `Once`, `Passive`, `Capture`, `Stop`, `Prevent`, `Outside`, `Window`, `Document`, `ViewTransition`, and `And` for combination — but the builder methods are the intended interface.
+
+Each trigger has its own modifier ADT, and they are not interchangeable: `EventModifier` for `dataOn`, `IntersectModifier` for `dataOnIntersect` (which adds `Half`, `Full`, `Exit`, and `Threshold`), `OnIntervalModifier` for `dataOnInterval` (`Duration`, `ViewTransition`), `OnSignalPatchModifier` for `dataOnSignalPatch` (`Delay`, `Debounce`, `Throttle`), and `InitModifier` for `dataInit` (`Delay`, `ViewTransition`). Every one of them has an `And` variant, which is how a chain of builder calls accumulates. You never need to construct these directly — the builder methods do it — but they are what a modifier chain is made of.
+
+## Case Modifiers
+
+`CaseModifier` controls how the event name is cased in the rendered attribute. Its four variants — `Camel`, `Kebab`, `Snake`, and `Pascal` — are selected by the same-named builder methods `DataOn#camel`, `DataOn#kebab`, `DataOn#snake`, and `DataOn#pascal`. The suffix appears only when the requested case differs from the builder's default, which for `dataOn` is kebab:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+A custom event whose real name is camelCase needs the modifier. Note what it actually does: the attribute key stays kebab-cased either way, and the modifier is what tells Datastar to convert it back:
+
+```scala
+div(dataOn("myCustomEvent").camel := js"@get('/handle')").renderMinified
+// res9: String = "<div data-on:my-custom-event__case.camel=\"@get(&#x27;/handle&#x27;)\"></div>"
+div(dataOn("myCustomEvent") := js"@get('/handle')").renderMinified
+// res10: String = "<div data-on:my-custom-event=\"@get(&#x27;/handle&#x27;)\"></div>"
+```
+
+So `DataOn#camel` does not change the rendered key — it appends `__case.camel` alongside it. The default differs per builder: `dataOn` defaults to kebab, while `dataSignals(signal)` defaults to camel, and a modifier matching the default is omitted. That is why the same case call is a no-op on one and meaningful on the other.
+
+Note also that the non-DOM triggers render as their own hyphenated attribute names — `data-on-intersect`, not `data-on:intersect` — since the trigger is the attribute rather than a key on it.
+
+## Non-DOM Triggers
+
+Four builders fire on something other than a DOM event. Each has its own modifier set and its own `:=`.
+
+### `dataOnIntersect` — element enters the viewport
+
+Fires when the element becomes visible, which is the basis for infinite scroll and lazy loading:
+
+| Modifier | Effect |
+| -------- | ------ |
+| `DataOnIntersect#once` | Fire only the first time |
+| `half` | Require 50% visibility |
+| `full` | Require 100% visibility |
+| `exit` | Fire on leaving rather than entering |
+| `threshold(pct)` | Require an explicit visibility fraction |
+| `delay(ms)`, `debounce(ms)`, `throttle(ms)` | Timing control |
+| `DataOnIntersect#viewTransition` | Wrap the patch in a view transition |
+
+A sentinel element at the end of a list is the canonical use:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+Loading the next page once, when the sentinel is fully visible:
+
+```scala
+div(dataOnIntersect.once.full := js"@get('/page/2')").renderMinified
+// res12: String = "<div data-on-intersect__once__full=\"@get(&#x27;/page/2&#x27;)\"></div>"
+```
+
+### `dataOnInterval` — fire on a timer
+
+Polls on an interval, with `DataOnInterval#duration` setting the period, `DataOnInterval#durationLeading` firing immediately as well, and `DataOnInterval#viewTransition` wrapping the resulting patch:
+
+```scala
+div(dataOnInterval.duration(5000) := js"@get('/status')").renderMinified
+// res13: String = "<div data-on-interval__duration.5000ms=\"@get(&#x27;/status&#x27;)\"></div>"
+```
+
+Without a `DataOnInterval#duration`, the attribute renders bare and Datastar applies its default interval.
+
+### `dataOnSignalPatch` — react to signal changes
+
+Fires when signals are patched, with `DataOnSignalPatch#delay`, `DataOnSignalPatch#debounce`, and `DataOnSignalPatch#throttle` for timing. Pair it with `dataOnSignalPatchFilter` to narrow which signals count:
+
+```scala
+div(dataOnSignalPatch.debounce(200) := js"@get('/recalculate')").renderMinified
+// res14: String = "<div data-on-signal-patch__debounce.200ms=\"@get(&#x27;/recalculate&#x27;)\"></div>"
+```
+
+### `dataInit` — fire once on load
+
+Runs when Datastar first processes the element, with `DataInit#delay` and `DataInit#viewTransition`:
+
+```scala
+div(dataInit := js"@get('/bootstrap')").renderMinified
+// res15: String = "<div data-init=\"@get(&#x27;/bootstrap&#x27;)\"></div>"
+```
+
+This is the hook for fetching initial content that is too expensive to render server-side on first paint.
+
+## Choosing a Trigger
+
+| You want to react to | Use |
+| -------------------- | --- |
+| A user interaction | `dataOn.<event>` |
+| An event with no dedicated method | `dataOn("name")` |
+| The element scrolling into view | `dataOnIntersect` |
+| The passage of time | `dataOnInterval` |
+| Signal state changing | `dataOnSignalPatch` |
+| The page loading | `dataInit` |
+
+## Integration Points
+
+Every builder here ends in `:=`, which goes through `ToDatastarExpr` and returns a `Dom.Attribute` — see [Attributes](./attributes.md) for that type class and why raw `String` values are rejected. Handler expressions typically read and write [Signals](./signals.md) and call Datastar's `@get`/`@post` actions, which the server answers with [Server-Sent Events](./sse.md).
+
+The `js"..."` interpolator producing those expressions, and the `Dom` types the attributes attach to, come from [HTML](../html.md).

package/reference/datastar/index.md

@@ -0,0 +1,256 @@
+---
+id: index
+title: "Datastar"
+sidebar_label: "Datastar"
+---
+
+`zio.http.datastar` builds [Datastar](https://data-star.dev) hypermedia applications: it renders the `data-*` attributes that make a page reactive, and it produces the SSE events that patch that page from the server. Core types: `Signal`, `SignalUpdate`, `DatastarEvent`, `DataOn`, `DatastarAttrKey`, `ToDatastarExpr`, `ElementPatchMode`. The two halves of the module:
+
+```scala
+final class Signal[A] private (val name: String) {
+  def :=(value: A)(implicit schema: Schema[A]): SignalUpdate[A]
+  def ref: DatastarRef
+}
+
+sealed trait DatastarEvent {
+  def renderSSE: String
+}
+```
+
+## Introduction
+
+Datastar puts application state in the browser as named *signals*, and drives changes to it declaratively. A page says what it reacts to — "when this button is clicked, POST to `/increment`" — using `data-*` attributes, and the server replies with events that patch elements or signals in place. No client-side framework code, no JSON API to design, no separate view model.
+
+This module is the Scala side of that contract. It gives you a typed way to write the attributes, a typed way to name and update signals, and a builder for each kind of SSE event, so both directions of the exchange are checked by the compiler rather than assembled from strings.
+
+Two things it deliberately does not do: it does not ship a server, and it does not ship the Datastar JavaScript. It produces `Dom` attributes and SSE payload strings, which you serve with whatever HTTP layer you already have.
+
+## Motivation
+
+The natural way to write Datastar from a server language is string interpolation — `s"data-on-click=\"@post('/increment')\""` — and it goes wrong in the usual ways. A misspelled signal name fails silently in the browser. An attribute name typo produces an attribute Datastar ignores. A value that should be a Datastar expression gets a Scala `String`, which renders as a literal instead of an expression, and the page just does nothing.
+
+This module closes each of those:
+
+- **Signal names are validated, literals at compile time.** `Signal[Int]("count")` checks the name during compilation; `Signal.dynamic` defers the same check to runtime for names you compute.
+- **Raw strings are rejected in expression positions.** `ToDatastarExpr` is deliberately ambiguous for `String`, so passing one is a compile error that names the fix. Expressions come from the `js"..."` interpolator or from typed signals.
+- **Attributes are `Dom.Attribute` values**, so they compose with the rest of the HTML DSL and cannot be misplaced into text content. The helpers also settle the naming convention for you: plain attributes render with a hyphen (`data-text`), and keyed ones with a colon (`data-on:click`, `data-class:active`, `data-computed:total`).
+- **SSE events are builders**, so each event kind offers the options it accepts and rendering emits the exact protocol field names. The one exception is `executeScript`, which returns an element-patch builder and so exposes `selector` and `mode` that do not apply to it.
+
+## Installation
+
+Add the module to your build:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-datastar" % "0.0.56"
+```
+
+For Scala.js, use `%%%` instead of `%%`:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-datastar" % "0.0.56"
+```
+
+Supported Scala versions: 2.13.x and 3.x.
+
+:::note[The package is `zio.http.datastar`]
+Despite living under `zio/blocks/datastar` in the source tree, the package is `zio.http.datastar`. The package object extends `DatastarAttributes`, so a single wildcard import brings every `data*` helper into scope.
+:::
+
+## Overview
+
+The module divides along the direction data flows.
+
+### Signals — state that lives in the browser
+
+`Signal[A]` is a named, typed handle on a client-side signal. `Signal#:=` pairs it with a value to produce a `SignalUpdate[A]`, serialized through the type's JSON codec. `Signal#ref` produces a `DatastarRef`, the `$name` form used inside expressions. See [Signals](./signals.md).
+
+### Attributes — declaring reactivity on the page
+
+`DatastarAttributes` supplies 27 `data*` helpers — `dataText`, `dataShow`, `dataBind`, `dataClass`, `dataComputed`, and the rest — each returning either a `Dom.Attribute` or a `DatastarAttrKey` awaiting a value. `ToDatastarExpr` governs what may be assigned. See [Attributes](./attributes.md).
+
+### Events — reacting to the user
+
+`dataOn` opens the event side: sixteen predefined events, fourteen chainable modifiers for debouncing, throttling, and propagation control, and four specialized triggers for intersection, interval, signal-patch, and init. See [Event Handlers](./events.md).
+
+### SSE — patching the page from the server
+
+`DatastarEvent` builds the four server-to-browser events: patch elements, patch signals, execute a script, and remove elements. `ElementPatchMode` chooses where content lands, and `EventType` names the protocol event. See [Server-Sent Events](./sse.md).
+
+## How They Work Together
+
+A Datastar interaction is a loop, and the module sits on both ends of it:
+
+```
+1. Server renders HTML          html DSL + data* attributes
+2. Browser becomes reactive     Datastar reads data-* and wires up signals
+3. User acts                    an event matching a data-on:* fires
+4. Browser issues a request     @post('/increment') from the expression
+5. Server responds with SSE     DatastarEvent.patchSignals / patchElements
+6. Browser applies the patch    signals update, elements morph in place
+                                └─> back to 3
+```
+
+The types involved at each end:
+
+```
+BROWSER SIDE (rendered into HTML)
+
+  Signal[A] ──ref──> DatastarRef ──> "$count"   used inside js"..." expressions
+      │
+      └─:=─> SignalUpdate[A] ──> {"count": 42}  JSON via Schema[A].jsonCodec
+
+  dataOn.click ──> DataOn ──modifiers──> DataOn ──:=──> Dom.Attribute
+                              │                          data-on:click__debounce.300ms
+                              ├─ EventModifier            (14: debounce, throttle,
+                              │                            once, passive, stop, …)
+                              └─ CaseModifier             (__case.camel | kebab | snake | pascal)
+
+  dataText / dataShow / dataClass(…) ──> DatastarAttrKey ──:=──> Dom.Attribute
+                                                    ▲
+                                          ToDatastarExpr guards the value:
+                                          js"…" and Signal ok, raw String rejected
+
+SERVER SIDE (rendered into an SSE stream)
+
+  DatastarEvent.patchElements(dom) ──> PatchElementsBuilder ──renderSSE──> String
+        │                                    ├─ selector(CssSelector)
+        │                                    ├─ mode(ElementPatchMode)
+        │                                    ├─ viewTransition / namespace
+        │                                    └─ eventId / retry
+        ├─ patchSignals(updates*) ──> PatchSignalsBuilder    ├─ onlyIfMissing
+        ├─ executeScript(js) ──────> PatchElementsBuilder
+        └─ removeElements(sel) ────> RemoveElementsBuilder
+
+  renderSSE delegates to zio.http.ServerSentEvent, so the result is
+  standard SSE with a Datastar-specific event name and data body.
+```
+
+## Common Patterns
+
+Four shapes cover most Datastar work.
+
+### A Counter, End to End
+
+The smallest complete loop: a signal, an attribute that displays it, a button that asks the server to change it, and an SSE event that does:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count = Signal[Int]("count")
+
+val page = div(
+  dataSignals(count := 0),
+  span(dataText := count),
+  button(dataOn.click := js"@post('/increment')", "increment")
+)
+```
+
+Rendering gives ordinary HTML that Datastar can read:
+
+```scala
+page.renderMinified
+// res0: String = "<div data-signals=\"{&quot;count&quot;: 0}\"><span data-text=\"$count\"></span><button data-on:click=\"@post(&#x27;/increment&#x27;)\">increment</button></div>"
+```
+
+The handler for `/increment` replies with a signal patch rather than a JSON body:
+
+```scala
+DatastarEvent.patchSignals(count := 1).renderSSE
+// res1: String = """event: datastar-patch-signals
+// data: signals {"count":1}
+// 
+// """
+```
+
+### Deriving State Instead of Storing It
+
+`dataComputed` defines a signal whose value is an expression over other signals, so the derived value never has to be kept in sync:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val price    = Signal[Double]("price")
+val quantity = Signal[Int]("quantity")
+val total    = Signal[Double]("total")
+
+val form = div(
+  dataSignals(price := 9.99, quantity := 1),
+  dataComputed(total) := js"$$price * $$quantity",
+  span(dataText := total)
+)
+```
+
+The computed attribute carries the expression, and the browser recomputes it whenever either input changes:
+
+```scala
+form.renderMinified
+// res3: String = "<div data-signals=\"{&quot;price&quot;: 9.99, &quot;quantity&quot;: 1}\" data-computed:total=\"$price * $quantity\"><span data-text=\"$total\"></span></div>"
+```
+
+### Rate-Limiting a Chatty Event
+
+Modifiers chain on `dataOn` before the handler is assigned, which is how a keystroke-driven search avoids one request per character:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val term = Signal[String]("term")
+
+val search = input(
+  dataBind(term),
+  dataOn.input.debounce(300) := js"@get('/search')"
+)
+```
+
+The modifier becomes part of the attribute name, so the browser applies it without any JavaScript of yours:
+
+```scala
+search.renderMinified
+// res5: String = "<input data-bind:term data-on:input__debounce.300ms=\"@get(&#x27;/search&#x27;)\"/>"
+```
+
+### Patching a Fragment Rather Than the Page
+
+`DatastarEvent.patchElements` with a selector and a mode replaces part of the page, leaving the rest — and its signal state — untouched:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val row = tr(td("Widget"), td("in stock"))
+
+val event = DatastarEvent
+  .patchElements(row)
+  .selector(CssSelector.id("inventory"))
+  .mode(ElementPatchMode.Append)
+  .renderSSE
+```
+
+The rendered event names the selector and mode as protocol fields:
+
+```scala
+event
+// res7: String = """event: datastar-patch-elements
+// data: selector #inventory
+// data: mode append
+// data: elements <tr><td>Widget</td><td>in stock</td></tr>
+// 
+// """
+```
+
+## Integration Points
+
+The module is a thin typed layer over three other blocks, and adds no dependency of its own:
+
+- **`zio-blocks-html`** supplies `Dom`, `Dom.Attribute`, `Js`, `CssSelector`, and the `ToJs` type class. Every attribute helper returns a `Dom.Attribute`, so Datastar attributes compose with the HTML DSL exactly like `id` or `class` — see [HTML](../html.md).
+- **`zio-blocks-schema`** supplies the JSON codec behind `Signal#:=`. A signal of type `A` needs a `Schema[A]`, and the serialized form is whatever that schema's JSON codec produces — see [Schema](../schema/index.md).
+- **`zio-http-model`** supplies `ServerSentEvent`, which `DatastarEvent#renderSSE` delegates to for the wire format. The Datastar-specific part is the event name and the structured `data:` body — see [ServerSentEvent](../http-model/server-sent-event.md).
+
+Within the module, the dependency direction is one-way: attributes and events both consume `Signal`, and neither knows about the other. Nothing in the SSE layer reads the attribute DSL.
+
+## Next Steps
+
+Start with [Signals](./signals.md), which every other page builds on, then [Attributes](./attributes.md) for the declarative surface and [Event Handlers](./events.md) for triggers. [Server-Sent Events](./sse.md) covers the server half.