@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/config.md

@@ -0,0 +1,158 @@
+---
+id: config
+title: "Config"
+sidebar_label: "Config"
+---
+
+`zio.blocks.config` provides typed configuration loading, feature flags, provenance tracking, rollout selection, and source adapters for YAML, JSON, and HOCON. The module is synchronous and zero-dependency: configuration is loaded from `ConfigSource`, flags are read through `FlagSource`, and typed decoding is derived from `Schema[A]`.
+
+## Installation
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-config-yaml" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-config-json" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-config-hocon" % "0.0.51"
+```
+
+For Scala.js:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-config" % "0.0.51"
+```
+
+Supported Scala versions: 2.13.x and 3.x.
+
+## Core Types
+
+At the center of the module are two source abstractions:
+
+```scala
+import zio.blocks.maybe.Maybe
+
+trait FlagSource {
+  def sourceId: String
+  def get(name: String): Maybe[SourceValue[String]]
+}
+
+trait ConfigSource extends FlagSource {
+  def get(key: String): Maybe[SourceValue[String]]
+  def all(prefix: String): Map[String, SourceValue[String]]
+}
+```
+
+`ConfigSource` extends `FlagSource`, so the same source can power both typed config loading and simple scalar flags.
+
+## Loading Typed Configuration
+
+Use `Config.load[A]` when you want a typed result and explicit errors:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.scope.Unscoped
+
+final case class AppConfig(host: String, port: Int) derives Schema, Unscoped
+
+val source = ConfigSource.fromMap(
+  Map("app.host" -> "localhost", "app.port" -> "8080"),
+  "example"
+)
+
+val loaded = Config.load[AppConfig](source.prefix("app"))
+```
+
+The main entry points are:
+
+```scala
+Config.load[A](source)
+Config.loadOrThrow[A](source)
+Config.loadWithProvenance[A](source)
+```
+
+`Config.loadWithProvenance` returns a `ProvenanceMap[A]`, which lets you inspect where resolved values came from.
+
+## Wiring Config into Dependency Graphs
+
+For application wiring, prefer `Config.wire[A]` or `Config.wire[A](prefix)` so decoding stays inside the dependency graph instead of being done manually at startup:
+
+```scala
+Config.wire[AppConfig]
+Config.wire[AppConfig]("app")
+```
+
+That keeps `ConfigSource` as the injected input and the typed config as the derived output.
+
+## Working with Sources
+
+`ConfigSource` supports composition and key transformation:
+
+```scala
+val defaults = ConfigSource.fromMap(Map("db.host" -> "localhost"), "defaults")
+val env      = ConfigSource.fromMap(Map("db.port" -> "5432"), "env")
+
+val combined = env.orElse(defaults)
+val scoped   = combined.prefix("db")
+```
+
+Common adapters:
+
+- `ConfigSource.fromMap(...)`
+- `ConfigSource.fromYaml(...)`  (requires `config-yaml` dependency)
+- `ConfigSource.fromJson(...)`  (requires `config-json` dependency)
+- `ConfigSource.fromHocon(...)` (requires `config-hocon` dependency)
+
+## Static and Dynamic Flags
+
+`StaticFlag[A]` resolves once, during object initialization:
+
+```scala
+import zio.blocks.config._
+
+object poolSize extends StaticFlag[Int](10)
+
+val size: Int = poolSize()
+```
+
+`DynamicFlag[A]` keeps an updatable rollout expression and evaluates it on demand.
+
+`StaticFlag` names are derived from the Scala object's fully qualified name, so custom `FlagSource` registrations must use that exact key.
+
+`FlagSource.Registry` is consulted in registration order, so the first registered source wins when multiple sources provide the same flag.
+
+:::note
+Register `FlagSource`s before the first reference to a `StaticFlag` object. Once a static flag object is initialized, later registrations do not retroactively change its resolved value.
+:::
+
+## Rollout DSL
+
+`Rollout` selects values based on a path and an optional percentage bucket:
+
+```scala
+import zio.blocks.config._
+
+val bucket = Rollout.bucketFor("user-123")
+val choice = Rollout.select("true@prod/50%;false", "prod", bucket)
+```
+
+The percentage uses slash-separated syntax (`prod/50%`). For the example above, `choice` is `Maybe.present("true")` for roughly half of the `prod` buckets and `Maybe.present("false")` otherwise. Bare values act as catch-all fallbacks and should come last.
+
+## Provenance
+
+Every resolved value carries provenance information through `SourceValue` and `Provenance`:
+
+```scala
+val source = ConfigSource.fromMap(Map("db.host" -> "localhost"), "defaults")
+val host   = source.get("db.host")
+```
+
+`host` contains both the raw value and a `Provenance.Resolved` entry that records the source id and key.
+
+## Format Adapters
+
+The format modules flatten structured documents into dot-separated keys:
+
+- YAML: nested mappings become `a.b.c`
+- JSON: arrays are indexed as `items.0`, `items.1`, ...
+- HOCON: substitutions are resolved before flattening
+
+Use these adapters when you want the convenience of file formats but still want a single `ConfigSource` API for decoding, composition, and provenance.

package/reference/context.md

@@ -116,7 +116,7 @@ val config = ctx.get[Config]  // Compile-time proof it exists
 Add the ZIO Blocks Context module to your `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.33"
+libraryDependencies += "dev.zio" %% "zio-blocks-context" % "0.0.51"
 ```
 
 ## Construction
@@ -544,7 +544,7 @@ cd zio-blocks
 package context
 
 import zio.blocks.context._
-import util.ShowExpr.show
+import zio.sbt.ExprEval.show
 
 // Context.empty creates an empty, type-safe dependency container.
 // Use Context.apply(...) to construct contexts with 1–10 values.
@@ -621,7 +621,7 @@ sbt "schema-examples/runMain context.ContextConstructionExample"
 package context
 
 import zio.blocks.context._
-import util.ShowExpr.show
+import zio.sbt.ExprEval.show
 
 // Context#get[A] retrieves a value by type with compile-time proof of existence.
 // Context#getOption[A] retrieves a value if present, returning None if missing.
@@ -706,7 +706,7 @@ sbt "schema-examples/runMain context.ContextRetrievalExample"
 package context
 
 import zio.blocks.context._
-import util.ShowExpr.show
+import zio.sbt.ExprEval.show
 
 // Context is immutable; modification methods return new contexts.
 // Context#add expands the context with a new value (or replaces if type exists).

package/reference/datastar.md

@@ -0,0 +1,346 @@
+---
+id: datastar
+title: "Datastar"
+---
+
+`zio-blocks-datastar` provides a type-safe Scala SDK for [Datastar](https://data-star.dev/), the hypermedia framework that brings reactive UIs via server-sent events (SSE). It builds on `zio-blocks-html` for DOM construction and `zio-blocks-schema` for JSON serialization.
+
+## Installation
+
+```scala
+// JVM
+libraryDependencies += "dev.zio" %% "zio-blocks-datastar" % "0.0.51"
+
+// Scala.js
+libraryDependencies += "dev.zio" %%% "zio-blocks-datastar" % "0.0.51"
+```
+
+## Signals
+
+A `Signal[A]` represents a named reactive signal on the client. Use `:=` to pair it with a value, producing a `SignalUpdate` ready for SSE transmission:
+
+```scala
+import zio.http.datastar._
+import zio.blocks.schema.Schema
+
+case class User(name: String, age: Int)
+object User {
+  implicit val schema: Schema[User] = Schema.derived
+}
+
+val count    = Signal[Int]("count")
+val username = Signal[String]("username")
+
+// Create signal updates (serializes via Schema's cached JSON codec)
+val update1 = count := 0
+val update2 = username := "Alice"
+```
+
+## SSE Events
+
+`DatastarEvent` is the sealed trait representing events sent to the browser. Use the companion object's builder methods:
+
+### patchSignals
+
+Send signal updates to the client:
+
+```scala
+val sse = DatastarEvent
+  .patchSignals(count := 42, username := "Bob")
+  .renderSSE
+
+// With options:
+val sseWithOptions = DatastarEvent
+  .patchSignals(count := 1)
+  .withOnlyIfMissing
+  .withEventId("evt-1")
+  .withRetry(5000)
+  .renderSSE
+```
+
+### patchElements
+
+Send DOM fragments to the client:
+
+```scala
+import zio.blocks.html._
+
+val sse = DatastarEvent
+  .patchElements(div(id := "status")("Online"))
+  .withSelector(CssSelector.id("status"))
+  .withMode(ElementPatchMode.Inner)
+  .withViewTransition
+  .renderSSE
+```
+
+### executeScript
+
+Run JavaScript on the client:
+
+```scala
+val sse = DatastarEvent
+  .executeScript(js"console.log('hello')")
+  .renderSSE
+```
+
+### removeElements
+
+Remove elements matching a CSS selector:
+
+```scala
+val sse = DatastarEvent
+  .removeElements(CssSelector.id("old-item"))
+  .renderSSE
+```
+
+## Attribute DSL
+
+Import `zio.http.datastar._` to get all `data-*` attribute constructors. These integrate with the `zio-blocks-html` DSL:
+
+```scala
+import zio.blocks.html._
+import zio.http.datastar._
+
+val count    = Signal[Int]("count")
+val username = Signal[String]("username")
+
+div(
+  dataSignals(count := 0),
+  dataText := count
+)(
+  span()("Count: "),
+  button(dataOn.click := js"$count++")("Increment")
+)
+```
+
+Datastar expression positions are intentionally stricter than generic HTML/JS templating.
+Raw `String` values are rejected in Datastar expression attributes; use `js"..."`
+for expressions, or typed values like `Signal`, `SignalUpdate`, and `DatastarRef`.
+
+```scala
+dataText := count
+dataText := count.ref
+dataOn.click := js"$count++"
+
+// does not compile:
+// dataOn.click := "$count++"
+```
+
+### Available Attributes
+
+| Method | Datastar Attribute | Description |
+|--------|-------------------|-------------|
+| `dataSignals(signal)` | `data-signals:name` | Declare one keyed signal with an initial value |
+| `dataSignals(update, updates...)` | `data-signals` | Patch multiple signals with one object expression |
+| `dataBind(signal)` | `data-bind:name` | Two-way bind an input to a signal |
+| `dataText` | `data-text` | Set element text content |
+| `dataShow` | `data-show` | Conditionally show/hide element |
+| `dataClass("name")` | `data-class:name` | Toggle CSS class |
+| `dataOn.click` | `data-on:click` | Event handler |
+| `dataComputed(signal)` | `data-computed:name` | Computed signal |
+| `dataEffect` | `data-effect` | Side-effect expression |
+| `dataIndicator(signal)` | `data-indicator:name` | Loading indicator signal |
+| `dataRef("name")` | `data-ref:name` | Element reference |
+| `dataInit` | `data-init` | Initialization expression |
+
+### Event Modifiers
+
+Chain modifiers on `dataOn` before assigning a handler:
+
+```scala
+// Debounce input by 300ms
+dataOn.input.debounce(300) := username
+
+// Click with prevent default, only once
+dataOn.click.prevent.once := js"handleSubmit()"
+
+// Throttle scroll, listen on window
+dataOn.scroll.throttle(100).window := js"onScroll()"
+```
+
+Available modifiers: `debounce`, `debounceLeading`, `throttle`, `throttleLeading`, `delay`, `once`, `passive`, `capture`, `stop`, `prevent`, `outside`, `window`, `document`, `viewTransition`.
+
+### Case Modifiers
+
+`dataOn` and `dataSignals(signal)` builders expose `.camel`, `.kebab`, `.snake`, and `.pascal` to control how the attribute key is cased. The default for `dataOn` is kebab; for `dataSignals(signal)` it is camel.
+
+```scala
+// Renders data-on:myCustomEvent (camel, explicit)
+dataOn("myCustomEvent").camel := js"handleIt()"
+
+// Renders data-signals:my-signal__case.kebab (kebab override)
+dataSignals(count := 0).kebab
+```
+
+The suffix `__case.<modifier>` is appended to the attribute name only when the chosen case differs from the builder's default.
+
+### Advanced Triggers
+
+#### dataOnIntersect
+
+Fires when the element enters (or exits) the viewport. Modifiers map directly to Datastar's intersection observer options:
+
+```scala
+// Fire once when 50% of the element is visible
+div(dataOnIntersect.half.once := js"loadContent()")()
+
+// Fire when element exits the viewport, debounced
+div(dataOnIntersect.exit.debounce(200) := js"cleanup()")()
+```
+
+Available modifiers: `once`, `half`, `full`, `exit`, `threshold(pct: Double)`, `delay(millis)`, `debounce(millis)`, `throttle(millis)`, `viewTransition`.
+
+#### dataOnInterval
+
+Runs an expression on a repeating timer:
+
+```scala
+// Poll every second
+div(dataOnInterval.duration(1000) := js"$count++")(count.ref.text)
+
+// Leading-edge interval with view transitions
+div(dataOnInterval.durationLeading(500).viewTransition := js"refresh()")()
+```
+
+#### dataOnSignalPatch / dataOnSignalPatchFilter
+
+`dataOnSignalPatch` runs whenever the server patches signals. Use `dataOnSignalPatchFilter` to restrict which patches trigger the handler:
+
+```scala
+div(
+  dataOnSignalPatch.debounce(100) := js"onPatch()",
+  dataOnSignalPatchFilter         := js"$count > 0"
+)()
+```
+
+Available modifiers on `dataOnSignalPatch`: `delay(millis)`, `debounce(millis)`, `throttle(millis)`.
+
+### Style and Attribute Binding
+
+#### dataStyle
+
+Bind inline styles, either as a whole-object expression or per-property:
+
+```scala
+// Keyed: sets a single CSS property
+div(dataStyle("color") := js"$isDark ? 'white' : 'black'")()
+
+// Unkeyed: bind an entire style object
+div(dataStyle := js"{color: $color, fontSize: $size + 'px'}")()
+```
+
+#### dataAttr
+
+Bind arbitrary HTML attributes:
+
+```scala
+div(dataAttr("aria-label") := js"$label")()
+div(dataAttr("tabindex")   := js"$isActive ? 0 : -1")()
+```
+
+### Morph Control
+
+Mark elements so Datastar's morphing algorithm treats them specially:
+
+```scala
+// Exclude element and its children from morphing
+div(dataIgnore)()
+
+// Exclude only the element itself, not its children
+div(dataIgnoreSelf)()
+
+// Prevent the element from being morphed (keep existing DOM node)
+div(dataIgnoreMorph)()
+
+// Preserve a specific attribute across morphs
+input(dataPreserveAttr("value"))()
+```
+
+### JSON Signals
+
+`dataJsonSignals` passes a raw JSON string as the signals expression, useful when signals are serialized server-side:
+
+```scala
+div(dataJsonSignals := js"""{"count":0,"username":""}""")()
+```
+
+## ElementPatchMode
+
+Controls how `patchElements` applies DOM content to the target:
+
+| Mode | Description |
+|------|-------------|
+| `Outer` | Morphs the target element in place (default, omitted from SSE) |
+| `Inner` | Replaces the target's children |
+| `Replace` | Replaces the target element |
+| `Prepend` | Inserts before the first child |
+| `Append` | Inserts after the last child |
+| `Before` | Inserts before the target element |
+| `After` | Inserts after the target element |
+| `Remove` | Removes the target element |
+
+```scala
+DatastarEvent
+  .patchElements(li(id := "new")("item"))
+  .withSelector(CssSelector.id("list"))
+  .withMode(ElementPatchMode.Append)
+  .renderSSE
+```
+
+## CssSelector
+
+`CssSelector` (from `zio.blocks.html`) constructs CSS selectors with type-safe combinators:
+
+```scala
+import zio.blocks.html._
+
+CssSelector.id("main")          // #main
+CssSelector.`class`("active")   // .active
+CssSelector.element("div")      // div
+CssSelector.raw(".foo > .bar")  // .foo > .bar
+CssSelector.universal           // *
+```
+
+Selectors compose with operators:
+
+```scala
+val sel = CssSelector.element("ul") > CssSelector.element("li")  // ul > li
+val grouped = CssSelector.id("a") | CssSelector.id("b")          // #a, #b
+```
+
+## Signal.dynamic
+
+`Signal[A]("name")` validates the signal name at compile time for string literals. Use `Signal.dynamic[A](name)` when the name is only known at runtime:
+
+```scala
+val fieldName = computeFieldName()               // runtime string
+val sig       = Signal.dynamic[String](fieldName) // validated at runtime
+
+sig := "hello"  // works like any other Signal
+```
+
+`dynamic` throws `IllegalArgumentException` if the name is invalid. The same validation rules apply: dot-separated JavaScript identifiers, no `__`.
+
+## SSE Streaming
+
+`DatastarEvent` has no ZIO or HTTP framework dependency. It just produces strings. To stream events, set the response content-type to `text/event-stream` and write each `renderSSE` result to the response body:
+
+```scala
+// Framework-agnostic pseudocode
+response.setHeader("Content-Type", "text/event-stream")
+response.setHeader("Cache-Control", "no-cache")
+
+// Send an initial signal patch
+response.write(DatastarEvent.patchSignals(count := 0).renderSSE)
+
+// Stream DOM updates as data changes
+val fragment = div(id := "result")(computedContent)
+response.write(
+  DatastarEvent
+    .patchElements(fragment)
+    .withSelector(CssSelector.id("result"))
+    .renderSSE
+)
+```
+
+Each `renderSSE` call returns a self-contained SSE block — multiple events can be written sequentially to the same stream.