@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/data-migration.md

@@ -0,0 +1,269 @@
+---
+id: data-migration
+title: "SQL Data Migration"
+---
+
+The `zio.blocks.data.migration` module provides three execution models for evolving database schemas online. It builds on [`Migration[A, B]`](./schema/migration.md) for the typed row transformation and [`Repo[E, ID]`](./sql/index.md) for database access. No hand-written SQL, no XML, no Liquibase-style migration files.
+
+## Overview
+
+Data migration in ZIO Blocks is split into three execution tiers, each suited to a different scale of change:
+
+| Model | Class | When to use |
+|---|---|---|
+| **A-Tiny** | `TinyMigrator` | DDL-only changes at startup (add column, rename table) |
+| **A-Small** | `SmallMigrator` | Queue-based batch backfill for moderate tables |
+| **B-Large** | `LargeMigrator` | Incremental worker with pause/resume and safe cutover for large tables |
+
+All three share the same building blocks:
+
+- `Migration[A, B]` from `zio.blocks.schema.migration` defines the typed transformation
+- `Repo[E, ID]` from `zio.blocks.sql` provides database access for source and target
+- `TargetStrategy` controls whether rows are updated in place or written to a shadow table
+- `QueueTable` tracks dirty keys that need processing
+
+The module is Scala 3 only.
+
+## Execution Models
+
+### A-Tiny: `TinyMigrator`
+
+`TinyMigrator` runs DDL migrations at application startup through `Transactor.transact`. Extend it and override `run()` to issue schema changes:
+
+```scala
+import zio.blocks.data.migration._
+import zio.blocks.sql._
+
+class AddAgeColumn(transactor: Transactor) extends TinyMigrator(transactor) {
+  def run()(using tx: DbTx): Unit =
+    // DDL statements executed at startup
+    ???
+}
+
+new AddAgeColumn(transactor).migrate()
+```
+
+Tiny migrations are appropriate when the schema change is fast, non-blocking, and can run before the application starts serving requests.
+
+### A-Small: `SmallMigrator`
+
+`SmallMigrator` is a queue-based batch worker for moderate-sized tables. It reads dirty keys from a `QueueTable`, fetches the source row, applies the `Migration[A, B]`, and writes the result to the target.
+
+The lifecycle has three steps:
+
+1. `init()` prepares the target table (creates a shadow table for `ShadowTable` strategy)
+2. `processBatch()` claims and processes a batch of dirty keys
+3. `complete()` finalizes the migration (swaps shadow table if applicable)
+
+Call `processBatch()` in a loop until the queue is empty, then call `complete()` (`complete()` refuses to run while items are still pending):
+
+```scala
+import zio.blocks.data.migration._
+
+// Assuming smallMigrator is already constructed (see full example below)
+smallMigrator.init()
+
+// Process batches until the queue drains
+var pending = true
+while (pending) {
+  val count = smallMigrator.processBatch()
+  pending = count > 0
+}
+
+smallMigrator.complete()
+```
+
+`SmallMigrator` supports both `TargetStrategy.InPlace` and `TargetStrategy.ShadowTable`.
+
+### B-Large: `LargeMigrator`
+
+`LargeMigrator` is an incremental worker designed for large tables where a full backfill would take too long. It adds pause/resume capability, concurrent worker support on PostgreSQL via `SKIP LOCKED`, and a safe completion protocol that guarantees no data is lost during cutover.
+
+The lifecycle has four steps:
+
+1. `init()` prepares the target table (creates a shadow table for `ShadowTable` strategy)
+2. `fence()` signals cutover and stops new producers from writing to the old table
+3. `drain()` processes all remaining queue items until the queue is empty
+4. `complete()` swaps the shadow table and finalizes the migration
+
+```scala
+import zio.blocks.data.migration._
+
+// Assuming largeMigrator is already constructed (see full example below)
+largeMigrator.init()
+
+// ... application runs, dirty keys accumulate ...
+
+// Cutover: stop writers, drain remaining, swap
+largeMigrator.fence()
+val totalDrained = largeMigrator.drain()
+largeMigrator.complete()
+```
+
+`LargeMigrator` is typically used with `TargetStrategy.ShadowTable` for safe cutover. The completion protocol ensures every dirty key is processed before the shadow table replaces the source.
+
+## Target Strategies
+
+`TargetStrategy` controls where migrated rows are written:
+
+- **`TargetStrategy.InPlace`** updates rows directly in the source table. Suitable when the schema change is backward compatible and the table structure does not change.
+- **`TargetStrategy.ShadowTable(suffix)`** creates a shadow table with the target schema, writes migrated rows there, and swaps the shadow table in at completion. The suffix is appended to the source table name to derive the shadow table name. Suitable when the schema change is not backward compatible or when you need a clean cutover.
+
+```scala
+TargetStrategy.InPlace
+TargetStrategy.ShadowTable("v2")   // shadow table will be named: users_v2
+```
+
+## Safe Completion Protocol (B-Large)
+
+`LargeMigrator` follows a stateful protocol to guarantee zero data loss during cutover. The protocol moves through four states:
+
+```
+Initialized → Fenced → Drained → Completed
+```
+
+### `init()` (Initialized)
+
+Prepares the target table. For `TargetStrategy.ShadowTable`, creates the shadow table. The source table continues to accept writes normally — producers are not interrupted. Workers call `init()` once before processing any batches.
+
+### `fence()` (Fenced)
+
+Signals that cutover is starting. The application **must** stop writing to the source table before calling `fence()`. After fencing, `drain()` will process all remaining queue entries until the queue is confirmed empty. Writes arriving after `fence()` may not be migrated.
+
+### `drain()` (Drained)
+
+Processes all remaining dirty keys until the queue is empty. Returns the total number of rows processed. Because fencing stopped new writes, the queue is guaranteed to reach zero.
+
+### `complete()` (Completed)
+
+Swaps the shadow table to replace the source table. After completion, the migration is done and the target table is live. Trigger cleanup and queue table removal are not performed automatically — callers are responsible for dropping these after verifying the migration is complete.
+
+The protocol ensures that every row modified between `init()` and `complete()` is migrated, even if the application crashes and restarts mid-migration. The queue table persists across restarts.
+
+## ID Type Flexibility
+
+`LargeMigrator` and `SmallMigrator` accept separate `ID1` and `ID2` type parameters for the source and target repos, but construction requires evidence that they are the same type (`ID1 =:= ID2`):
+
+```scala
+SmallMigrator[UserV1, UserV2, Long, Long](...)
+LargeMigrator[UserV1, UserV2, Long, Long](...)
+```
+
+The queue table stores V1 IDs (`ID1`). The `ID1` type must have a `DbCodec` instance available as a given. The equality constraint keeps delete propagation type-safe: when a source row disappears between dequeue and read, the same key is reinterpreted for the target repo via the type evidence rather than a cast. Migrations that change the primary key type are out of scope for the built-in migrators.
+
+## Queue Primitives
+
+`QueueTable` is the dirty-key tracking mechanism shared by `SmallMigrator` and `LargeMigrator`. The queue table has three columns:
+
+| Column | Type | Description |
+|---|---|---|
+| `id` | `TEXT NOT NULL PRIMARY KEY` | The primary key of the affected source row |
+| `op` | `TEXT NOT NULL DEFAULT 'I'` | The operation type: `'I'` (insert), `'U'` (update), or `'D'` (delete) |
+| `payload` | `TEXT` | JSON-serialized V1 row data, captured only for `'D'` operations on PostgreSQL |
+
+Queue entries are coalesced by primary key. There are two ways keys enter the queue:
+
+1. **Manual enqueue** — the application calls `QueueTable.enqueue` for every row it writes (or for a batch of rows to backfill).
+2. **Capture triggers** — pass `captureTriggers = true` when constructing `SmallMigrator` or `LargeMigrator`; `init()` then installs triggers via `QueueTable.installTriggers` so every source INSERT/UPDATE/DELETE upserts the affected key in the writer's own transaction. Trigger installation is idempotent (PostgreSQL requires PG 14+ for `CREATE OR REPLACE TRIGGER`). Do not enable capture triggers when the migrator writes to the same physical table it captures from: the worker's own writes would re-enqueue processed keys forever.
+
+For `INSERT` and `UPDATE`, only the key and operation type are stored. For `DELETE`, PostgreSQL additionally captures the full row as JSON via `row_to_json(OLD)::text` into the `payload` column; the payload is reserved for future delete-recovery and is not read by the current workers. SQLite does not support `row_to_json`, so its delete entries carry no payload.
+
+| Operation | Description |
+|---|---|
+| `QueueTable.create` | Creates the queue table (id, op, payload columns) |
+| `enqueue` | Inserts the ID into the queue |
+| `dequeue` | Claims and removes a batch of IDs, returning `List[ID]` |
+| `pending` | Returns the number of unprocessed keys |
+| `installTriggers` | Installs capture triggers on the source table |
+
+PostgreSQL uses `FOR UPDATE SKIP LOCKED` for concurrent worker claims. SQLite uses a single consumer with `BEGIN IMMEDIATE` and a busy timeout. Queue IDs are stored as TEXT, so batches are claimed in lexicographic order (`'10'` before `'9'`); this affects claim order only, never correctness.
+
+A worker claims the dirty key and, in one transaction, looks up the source row by ID, applies the `Migration[A, B]`, and writes the result to the target. If the source row is missing at processing time (deleted between enqueue and dequeue), the corresponding target row is deleted — `findAll` returns only rows that still exist.
+
+## Database Support
+
+| Feature | PostgreSQL | SQLite |
+|---|---|---|
+| `TinyMigrator` | Yes | Yes |
+| `SmallMigrator` | Yes | Yes |
+| `LargeMigrator` | Yes (multi-worker) | Yes (single-worker) |
+| `SKIP LOCKED` | Yes | No |
+| `ShadowTable` (CREATE TABLE LIKE, atomic swap) | Yes | No |
+| `InPlace` updates | Yes | Yes |
+
+PostgreSQL supports the full feature set including concurrent workers, shadow table creation via `CREATE TABLE LIKE`, and atomic DDL swap. SQLite supports queue primitives and in-place updates but does not support shadow tables or concurrent workers.
+
+## Contextual Requirements
+
+`TinyMigrator`, `SmallMigrator`, and `LargeMigrator` require a `Transactor` as an implicit constructor parameter. `SmallMigrator` and `LargeMigrator` also require a `DbCodec[ID1]` given for the queue table's primary key column.
+
+## Full Example
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.migration.Migration
+import zio.blocks.sql.{DbCodec, DbCodecDeriver, Repo, Table, Transactor}
+import zio.blocks.data.migration._
+
+case class UserV1(id: Int, name: String)
+case class UserV2(id: Int, name: String, age: Int)
+
+object UserV1 { implicit val schema: Schema[UserV1] = Schema.derived }
+object UserV2 { implicit val schema: Schema[UserV2] = Schema.derived }
+
+val v1Table = Table.derived[UserV1]
+val v2Table = Table.derived[UserV2]
+
+implicit val codecInt: DbCodec[Int] = implicitly[Schema[Int]].deriving(DbCodecDeriver).derive
+implicit val codecV1: DbCodec[UserV1] = UserV1.schema.deriving(DbCodecDeriver).derive
+implicit val codecV2: DbCodec[UserV2] = UserV2.schema.deriving(DbCodecDeriver).derive
+
+val v1Repo = Repo(v1Table, "id", summon[DbCodec[Int]], (_: UserV1).id)
+val v2Repo = Repo(v2Table, "id", summon[DbCodec[Int]], (_: UserV2).id)
+
+// Migration that transforms UserV1 to UserV2
+val migration: Migration[UserV1, UserV2] = Migration
+  .newBuilder[UserV1, UserV2]
+  .addField(_.age, SchemaExpr.literal(0))
+  .build
+
+// SmallMigrator: queue-based batch processing
+val smallMigrator = SmallMigrator[UserV1, UserV2, Int, Int](
+  repoV1 = v1Repo,
+  repoV2 = v2Repo,
+  migration = migration,
+  queueTable = "user_migration_q",
+  batchSize = 100,
+  target = TargetStrategy.ShadowTable("v2")
+)(using transactor, summon[DbCodec[Int]], Dialect.Postgres)
+
+// Lifecycle: init, process batches, complete
+smallMigrator.init()
+// ... loop processBatch() ...
+smallMigrator.complete()
+
+// LargeMigrator: incremental worker with safe completion protocol
+val largeMigrator = LargeMigrator[UserV1, UserV2, Int, Int](
+  repoV1 = v1Repo,
+  repoV2 = v2Repo,
+  migration = migration,
+  queueTable = "user_migration_q",
+  batchSize = 100,
+  target = TargetStrategy.ShadowTable("v2"),
+  captureTriggers = true
+)(using transactor, summon[DbCodec[Int]], Dialect.Postgres)
+
+// Safe lifecycle: init, fence, drain, complete
+largeMigrator.init()
+largeMigrator.fence()
+val total = largeMigrator.drain()
+largeMigrator.complete()
+```
+
+## Failure Policy
+
+When a worker transaction fails, the transaction is rolled back and the dirty key is retained in the queue table. The failure is returned to the caller. No data is silently lost, and no automatic retry or dead-letter configuration is applied. The caller decides how to handle the failure.
+
+## Architecture Decisions
+
+For a detailed record of architecture decisions, see the [ADR](../adr/2026-07-18-data-migration.md).

package/reference/datastar/attributes.md

@@ -0,0 +1,302 @@
+---
+id: attributes
+title: "Datastar Attributes"
+sidebar_label: "Attributes"
+---
+
+`DatastarAttributes` supplies 27 `data*` helpers that make rendered HTML reactive. Each returns either a finished `Dom.Attribute` or a `DatastarAttrKey` awaiting a value, and `ToDatastarExpr` decides what may be assigned — rejecting raw `String` at compile time. The package object extends this trait, so one wildcard import brings every helper into scope. The two types every helper funnels through:
+
+```scala
+final class DatastarAttrKey(val name: String) {
+  def :=[T](value: T)(implicit toDatastarExpr: ToDatastarExpr[T]): Dom.Attribute
+}
+
+trait ToDatastarExpr[-A] {
+  def toDatastarExpr(a: A): String
+}
+```
+
+## Motivation
+
+Datastar's whole interface is attribute names and expression strings. `data-text="$count"` displays a signal; `data-show="$count > 0"` conditionally renders; `data-class:active="$selected"` toggles a class. Getting one character wrong produces an attribute the framework ignores, with no error anywhere.
+
+The failure that costs the most time is subtler than a typo. Attribute values are *expressions*, evaluated in the browser — `"$count"` reads a signal, but `"count"` is a string literal that happens to look right. Interpolating a Scala `String` into an expression position produces exactly that: valid HTML, ignored semantics, a blank element.
+
+These helpers make the attribute name a method call and the value type-checked. There is no attribute name to misspell, and `ToDatastarExpr` is deliberately unavailable for `String`, so the one mistake that fails silently in the browser fails loudly at compile time instead.
+
+## Quick Showcase
+
+Attributes compose with the HTML DSL like any other:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val open = Signal[Boolean]("open")
+
+val panel = div(
+  dataSignals(open := false),
+  button(dataOn.click := js"$open = !$open", "toggle"),
+  div(dataShow := open, dataClass("visible") := open, "panel contents")
+)
+```
+
+Rendering produces the attribute names and expressions Datastar expects:
+
+```scala
+panel.renderMinified
+// res0: String = "<div data-signals=\"{&quot;open&quot;: false}\"><button data-on:click=\"$open = !$open\">toggle</button><div data-show=\"$open\" data-class:visible=\"$open\">panel contents</div></div>"
+```
+
+## Attribute Naming
+
+Two shapes appear in the rendered output, and which one a helper produces tells you whether it takes a key.
+
+| Helper form | Renders as | Example |
+| ----------- | ---------- | ------- |
+| No key | `data-<name>` | `dataText` → `data-text` |
+| Keyed | `data-<name>:<key>` | `dataClass("active")` → `data-class:active` |
+| Own attribute | `data-<multi-word-name>` | `dataOnIntersect` → `data-on-intersect` |
+| Modified | `…__<modifier>` | `dataOn.click.once` → `data-on:click__once` |
+
+Keys derived from signal names are kebab-cased, so a `Signal[Int]("itemCount")` used as a `dataComputed` key becomes `data-computed:item-count`.
+
+The third row is the one that breaks the pattern. A DOM event is a *key* on `data-on`, giving `data-on:click`, but the non-DOM triggers are attribute names in their own right — `data-on-intersect`, `data-on-interval`, `data-on-signal-patch` — with hyphens and no key. Their modifiers still attach with `__`.
+
+## Declaring State
+
+Two helpers put signals on the page.
+
+### `dataSignals` — initial values
+
+`dataSignals` has three forms. Given one or more `SignalUpdate`s it renders the whole object as the attribute value:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val price    = Signal[Double]("price")
+val quantity = Signal[Int]("quantity")
+```
+
+Several updates become a single `data-signals` attribute:
+
+```scala
+div(dataSignals(price := 9.99, quantity := 1)).renderMinified
+// res2: String = "<div data-signals=\"{&quot;price&quot;: 9.99, &quot;quantity&quot;: 1}\"></div>"
+```
+
+Given a single `Signal`, it returns a `DataSignalsBuilder` for the keyed form — `data-signals:<name>` — which sets one signal rather than an object:
+
+```scala
+div(dataSignals(price) := js"42.0").renderMinified
+// res3: String = "<div data-signals:price=\"42.0\"></div>"
+```
+
+The builder also carries the case modifiers described below. The third form, bare `dataSignals`, is a `DatastarAttrKey` for assigning a raw expression.
+
+### `dataComputed` — derived signals
+
+`dataComputed(signal)` declares a signal whose value is an expression over others, recomputed by the browser whenever an input changes:
+
+```scala
+div(dataComputed(Signal[Double]("total")) := js"$price * $quantity").renderMinified
+// res4: String = "<div data-computed:total=\"$price * $quantity\"></div>"
+```
+
+The signal name becomes the attribute key, kebab-cased.
+
+## Displaying and Binding
+
+Three helpers read a signal and change what the element shows, without any handler being involved.
+
+### `dataText` and `dataShow`
+
+`dataText` sets an element's text content from an expression, and `dataShow` controls its visibility:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count = Signal[Int]("count")
+```
+
+Both take an expression, so a signal or a `js"..."` both work:
+
+```scala
+span(dataText := count).renderMinified
+// res6: String = "<span data-text=\"$count\"></span>"
+div(dataShow := js"$count > 0", "non-empty").renderMinified
+// res7: String = "<div data-show=\"$count &gt; 0\">non-empty</div>"
+```
+
+### `dataBind` — two-way input binding
+
+`dataBind(signal)` binds a form control to a signal in both directions, and needs no value:
+
+```scala
+input(dataBind(count)).renderMinified
+// res8: String = "<input data-bind:count/>"
+```
+
+The rendered attribute is `data-bind:<name>` with no value, which is how Datastar recognizes the binding form.
+
+## Styling
+
+Three helpers follow the same keyed-or-bare pattern: a key selects what to modify, and the expression decides when.
+
+| Helper | Keyed form | Purpose |
+| ------ | ---------- | ------- |
+| `dataClass(name)` | `data-class:<name>` | Toggle one class |
+| `dataClass` | `data-class` | Object of class names to conditions |
+| `dataStyle(name)` | `data-style:<name>` | Set one CSS property |
+| `dataStyle` | `data-style` | Object of properties to values |
+| `dataAttr(name)` | `data-attr:<name>` | Set one HTML attribute |
+| `dataAttr` | `data-attr` | Object of attributes to values |
+
+The keyed form is the common one, toggling a single class from a condition:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val selected = Signal[Boolean]("selected")
+```
+
+Keyed and bare forms render differently, and the bare form takes an object expression:
+
+```scala
+div(dataClass("active") := selected).renderMinified
+// res10: String = "<div data-class:active=\"$selected\"></div>"
+div(dataStyle("color") := js"$selected ? 'red' : 'gray'").renderMinified
+// res11: String = "<div data-style:color=\"$selected ? &#x27;red&#x27; : &#x27;gray&#x27;\"></div>"
+```
+
+## Effects and References
+
+`dataEffect` runs an expression whenever its dependencies change, `dataIndicator(signal)` sets a signal while a request is in flight, and `dataRef(name)` exposes the element to expressions by name:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val loading = Signal[Boolean]("loading")
+```
+
+`dataIndicator` and `dataRef` are complete attributes rather than keys, since their argument is the whole content:
+
+```scala
+button(dataIndicator(loading), "save").renderMinified
+// res13: String = "<button data-indicator:loading>save</button>"
+div(dataRef("panel")).renderMinified
+// res14: String = "<div data-ref:panel></div>"
+```
+
+## Morph Control
+
+When the server patches elements, Datastar morphs the existing DOM rather than replacing it. Four helpers control what that morph may touch — all of them complete attributes taking no expression:
+
+| Helper | Effect |
+| ------ | ------ |
+| `dataIgnore` | Datastar ignores this element and its subtree entirely |
+| `dataIgnoreSelf` | Ignores this element but still processes its children |
+| `dataIgnoreMorph` | Preserves this element across morphs |
+| `dataPreserveAttr(attrs*)` | Preserves the named attributes across morphs |
+
+Preserving an attribute matters for state the server does not know about — a scroll position, an open `details`, a user-resized width:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+```
+
+The first three are boolean attributes; the fourth names what to keep:
+
+```scala
+div(dataIgnore).renderMinified
+// res16: String = "<div data-ignore></div>"
+div(dataPreserveAttr("open", "style")).renderMinified
+// res17: String = "<div data-preserve-attr=\"open style\"></div>"
+```
+
+## Other Attributes
+
+`dataJsonSignals` renders the full signal state as JSON, which is useful for debugging a page's reactive state, and `dataOnSignalPatchFilter` narrows which signal patches a `data-on-signal-patch` handler responds to. Both are `DatastarAttrKey`s taking an expression.
+
+The trigger helpers — `dataOn`, `dataInit`, `dataOnIntersect`, `dataOnInterval`, `dataOnSignalPatch` — are covered in [Event Handlers](./events.md).
+
+## ToDatastarExpr
+
+`ToDatastarExpr[A]` is the type class deciding what may be assigned with `:=`. It is contravariant, and instances derive from `ToJs[A]`, so anything the HTML module can render as JavaScript works here.
+
+### What Is Accepted
+
+An instance exists for any `A` with a `ToJs[A]` — which covers `Js` values from the `js"..."` interpolator, `Signal[A]`, `SignalUpdate[A]`, and `DatastarRef`:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count = Signal[Int]("count")
+```
+
+Each renders to its expression form:
+
+```scala
+span(dataText := count).renderMinified
+// res19: String = "<span data-text=\"$count\"></span>"
+span(dataText := js"$count + 1").renderMinified
+// res20: String = "<span data-text=\"$count + 1\"></span>"
+```
+
+### Why `String` Is Rejected
+
+There is deliberately **no** usable instance for `String`. The mechanism is a private `NotString` witness with two conflicting instances for `String`, which makes the implicit search ambiguous, plus an `@implicitAmbiguous` annotation supplying the message:
+
+```scala
+@implicitAmbiguous(
+  "Raw String values are not allowed in Datastar expression positions. " +
+  "Use js\"...\" for Datastar expressions or typed Signal/SignalUpdate values."
+)
+private sealed trait NotString[A]
+```
+
+The result is that `dataText := "count"` does not compile, and the error tells you to use `js"..."` instead.
+
+:::tip[This is the module's most valuable guard]
+Assigning a raw `String` is the one Datastar mistake that produces valid HTML and no error at runtime — the attribute renders, the browser reads it as a literal, and the element silently shows nothing useful. Making it a compile error is worth the unusual implicit machinery.
+:::
+
+`@implicitNotFound` covers the other case: a type with no `ToJs` instance at all gets a message naming the type and pointing at the same two options.
+
+## DatastarAttrKey
+
+`DatastarAttrKey` is the low-level escape hatch — a raw attribute name plus `:=`. Every keyed helper returns one, and you can construct one for an attribute the module has no helper for yet.
+
+Since the constructor is `private[datastar]`, reach it through a helper that returns a bare key. `dataAttr`, `dataClass`, `dataStyle`, `dataText`, `dataShow`, `dataEffect`, `dataSignals`, `dataJsonSignals`, and `dataOnSignalPatchFilter` all have bare forms:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val theme = Signal[String]("theme")
+```
+
+The bare form takes an object expression covering several keys at once:
+
+```scala
+div(dataStyle := js"{color: $theme}").renderMinified
+// res22: String = "<div data-style=\"{color: $theme}\"></div>"
+```
+
+:::warning[`dataAttr` collides with the HTML module]
+`zio.blocks.html` also defines `dataAttr`, for plain static `data-*` attributes — `dataAttr("id") := "42"` renders `data-id="42"`. Datastar's renders `data-attr:id="<expression>"`, a reactive binding. With both packages wildcard-imported, the bare name is ambiguous and will not compile.
+
+Qualify the one you mean, `zio.http.datastar.dataAttr` for the reactive form, or import selectively. The ambiguity error is the good case: it stops you silently getting a static attribute where you wanted a binding.
+:::
+
+## Integration Points
+
+Every helper returns a `Dom.Attribute` from [HTML](../html.md), so Datastar attributes are indistinguishable from `id` or `class` at the point of use and compose in the same element constructors. `ToDatastarExpr` derives from that module's `ToJs`, and the `js"..."` interpolator producing most expression values is also its.
+
+Values assigned here are usually [Signals](./signals.md), and the triggers that pair with these attributes are in [Event Handlers](./events.md). What the server sends back to change them is in [Server-Sent Events](./sse.md).