@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/htmx/attribute-values.md

@@ -0,0 +1,359 @@
+---
+id: attribute-values
+title: Attribute Values and Infrastructure
+---
+
+This section documents supporting attribute value types and infrastructure for the HTMX DSL. These types handle specialized data encoding, configuration, and type-class infrastructure that enables extensibility.
+
+## Attribute Value Types
+
+These types enable specialized data encoding and configuration:
+
+### HxVals — Custom Values
+
+`HxVals` represents the `hx-vals` attribute, allowing you to send custom data alongside form parameters. It accepts both schema-backed values (automatically JSON-encoded) and raw JSON:
+
+```scala
+import zio.http.htmx._
+import zio.blocks.schema._
+import zio.blocks.schema.json.Json
+
+// From a schema-backed value
+case class Extra(userId: Int, role: String)
+HxVals.from(Extra(123, "admin"))
+
+// From raw JSON
+HxVals.json(Json.Object(Chunk("userId" -> Json.Number(123))))
+```
+
+Use `HxVals.from[T](value)` with an implicit `Schema[T]` to automatically encode any data type to JSON. First, set up a schema for your data type:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import zio.blocks.schema._
+
+case class RequestContext(userId: Int, sessionId: String)
+object RequestContext {
+  implicit val schema: Schema[RequestContext] = Schema.derived
+}
+```
+
+Then use it in your form:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/api/action",
+  hxVals := HxVals.from(RequestContext(42, "abc123")),
+  button("Submit")
+)
+```
+
+Or use `HxVals.json(json)` when you already have JSON. Set up the imports first:
+
+```scala
+import zio.blocks.schema.json.Json
+import zio.blocks.chunk.Chunk
+```
+
+Then construct the JSON:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import zio.blocks.schema.json.Json
+import zio.blocks.chunk.Chunk
+
+form(
+  hxPost := "/api/action",
+  hxVals := HxVals.json(Json.Object(Chunk("priority" -> Json.String("high")))),
+  button("Submit")
+)
+```
+
+### HxHeadersValue — Custom Headers
+
+`HxHeadersValue` represents the `hx-headers` attribute, sending custom HTTP headers with HTMX requests. Like `HxVals`, it accepts schema-backed values or raw JSON:
+
+```scala
+import zio.http.htmx._
+import zio.blocks.schema.json.Json
+import zio.blocks.chunk.Chunk
+
+// From raw JSON object
+val example1 = HxHeadersValue.json(Json.Object(Chunk(
+  "X-Custom-Header" -> Json.String("value"),
+  "X-Request-ID" -> Json.String("12345")
+)))
+
+// From a schema-backed value
+import zio.blocks.schema._
+case class Headers(traceId: String)
+object Headers {
+  implicit val schema: Schema[Headers] = Schema.derived
+}
+val example2 = HxHeadersValue.from(Headers("xyz789"))
+```
+
+Add custom headers to all requests within an element:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import zio.blocks.schema.json.Json
+import zio.blocks.chunk.Chunk
+
+div(
+  hxHeaders := HxHeadersValue.json(Json.Object(Chunk(
+    "X-API-Key" -> Json.String("secret123"),
+    "X-Client-Version" -> Json.String("2.0")
+  ))),
+  button(hxPost := "/action", "Request (with custom headers)")
+)
+```
+
+### HxSwapOob — Out-of-Bounds Swaps
+
+`HxSwapOob` represents the `hx-swap-oob` attribute, enabling out-of-bounds swaps that update content outside the primary request target. This allows a single response to update multiple DOM regions simultaneously.
+
+Use `HxSwapOob(true)` or `HxSwapOob(false)` for boolean flags:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(
+  id := "status-badge",
+  hxSwapOob := HxSwapOob(true),
+  "Ready"
+)
+```
+
+Or use `HxSwapOob.using(swap)` to specify a swap strategy:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(
+  id := "notification",
+  hxSwapOob := HxSwapOob.using(HxSwap.BeforeEnd),
+  span("New notification")
+)
+```
+
+Combine with a target selector:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(
+  hxSwapOob := HxSwapOob.using(
+    HxSwap.InnerHTML,
+    HxTarget.css("#status")
+  ),
+  "Updated Status"
+)
+```
+
+### HxExtensions — HTMX Extensions
+
+`HxExtensions` represents the `hx-ext` attribute, enabling HTMX extensions. Pass extension names as comma-separated values:
+
+```scala
+import zio.http.htmx._
+
+// Enable multiple extensions
+HxExtensions("json-enc", "class-tools")
+```
+
+Use in elements to opt in to extensions:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/api/submit",
+  hxExt := HxExtensions("json-enc", "debug"),
+  button("Submit")
+)
+```
+
+The `hxExt` attribute key provides a convenience builder to construct extensions:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxExt("json-enc", "class-tools"),
+  button("Submit")
+)
+```
+
+### HxAttributeNames — Attribute Disinheritance
+
+`HxAttributeNames` represents the `hx-disinherit` attribute, preventing child elements from inheriting specific HTMX attributes from their ancestors. Pass attribute names as space-separated values:
+
+```scala
+import zio.http.htmx._
+
+// Prevent inheriting these attributes
+HxAttributeNames("hx-trigger", "hx-swap")
+```
+
+Use to override inherited attributes:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(
+  hxPost := "/parent-action",
+  hxTrigger := HxTrigger.click,
+  button(
+    hxDisinherit := HxAttributeNames("hx-post", "hx-trigger"),
+    hxPost := "/child-action",
+    hxTrigger := HxTrigger.submit,
+    "Child (overrides parent)"
+  )
+)
+```
+
+The `hxDisinherit` attribute key provides a convenience builder:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(
+  hxPost := "/parent-action",
+  button(
+    hxDisinherit("hx-post", "hx-trigger"),
+    hxPost := "/child-action",
+    "Child"
+  )
+)
+```
+
+## Infrastructure Types
+
+These types provide the internal machinery for the HTMX DSL:
+
+### HtmxAttrKey — Typed Attribute Keys
+
+`HtmxAttrKey[-A]` is the typed attribute key binding an attribute name to its expected value type. Unlike plain HTML attributes, HTMX attributes carry compile-time type information, preventing type mismatches.
+
+The `HtmxAttributes` mixin provides predefined keys like `hxPost`, `hxSwap`, `hxTarget`, etc.; use these rather than constructing `HtmxAttrKey` directly. Each key enforces the correct value type:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// hxSwap expects HxSwap; this compiles
+div(hxSwap := HxSwap.InnerHTML)
+
+// hxTarget expects HxTarget; this compiles
+div(hxTarget := HxTarget.This)
+
+// hxPost expects UrlLike (String | Path | URL); this compiles
+div(hxPost := "/api/endpoint")
+```
+
+### ToHtmxValue — Type Class for Rendering
+
+`ToHtmxValue[-A]` is the type class that renders HTMX domain values to attribute strings. It's automatically derived for types like `HxSwap`, `HxTarget`, `HxTrigger`, and basic primitives.
+
+The module provides instances for common types out of the box:
+
+- **Primitives:** `String`, `Boolean`, `Int`, `Long`, `Double` render to their string representations
+- **Selectors:** `CssSelector` renders via its `render` method
+- **URLs:** `Path` and `URL` render to encoded strings
+- **HTMX domain types:** `HxSwap`, `HxTarget`, `HxTrigger`, `HxParams`, etc. render via their `render` methods
+- **Schema-backed types:** `Schema[A]` instances enable `HxVals.from()` to encode any data to JSON
+
+#### Extending with Custom Types
+
+Define your own `ToHtmxValue` instance to make custom domain types work in the HTMX DSL:
+
+```scala
+import zio.http.htmx._
+
+sealed trait Priority
+object Priority {
+  case object Low extends Priority
+  case object Medium extends Priority
+  case object High extends Priority
+  
+  implicit val toHtmxValue: ToHtmxValue[Priority] = new ToHtmxValue[Priority] {
+    def toHtmxValue(value: Priority): String = value match {
+      case Low    => "low"
+      case Medium => "medium"
+      case High   => "high"
+    }
+  }
+}
+```
+
+Use `Priority` values directly in HTMX attributes through the `ToHtmxValue` type class:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/api/task",
+  hxOn.click := Js(s"console.log('Priority: ${Priority.High.toString()}')"),
+  "Create High Priority Task"
+)
+```
+
+#### Implicit Resolution
+
+When you assign a value to an HTMX attribute, the type class is summoned implicitly:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// Implicit ToHtmxValue[HxSwap] is summoned
+div(hxSwap := HxSwap.InnerHTML)
+
+// Implicit ToHtmxValue[String] is summoned
+div(hxPost := "/endpoint")
+```
+
+If you get an error like "No `ToHtmxValue` instance found for type X," implement the type class for your custom type as shown above.
+
+## Integration
+
+These types work together to provide a complete, extensible HTMX DSL. For example, a form might use multiple attribute value types:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import zio.blocks.schema.json.Json
+import zio.blocks.chunk.Chunk
+import scala.concurrent.duration._
+
+form(
+  hxPost := "/api/submit",
+  hxTrigger := HxTrigger.submit,
+  hxTarget := HxTarget.closest("form"),
+  hxSwap := HxSwap.InnerHTML.settle(250.millis),
+  hxParams := HxParams.only("name", "email"),
+  hxEncoding := HxEncoding.Multipart,
+  hxHeaders := HxHeadersValue.json(Json.Object(Chunk(
+    "X-Request-ID" -> Json.String("12345")
+  ))),
+  hxVals := HxVals.from(RequestContext(42, "session-abc")),
+  button("Submit")
+)
+```
+
+Each attribute key is type-safe, and the `ToHtmxValue` type class ensures values render correctly to HTMX syntax.

package/reference/htmx/hx-encoding.md

@@ -0,0 +1,111 @@
+---
+id: hx-encoding
+title: HxEncoding
+---
+
+`HxEncoding` represents the `hx-encoding` attribute, controlling how form data is encoded when sent in an HTMX request. The primary use case is file uploads, which require `multipart/form-data` encoding instead of the default URL-encoded form submission.
+
+Use `HxEncoding.Multipart` to enable multipart form data encoding for requests that include file fields. Here is the core pattern:
+
+```scala
+import zio.http.htmx._
+
+// Multipart encoding (for file uploads)
+HxEncoding.Multipart
+```
+
+## Encoding Strategies
+
+**`HxEncoding.Multipart`** sets the `hx-encoding` attribute to `multipart/form-data`, enabling file uploads and other multipart data:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/upload",
+  hxEncoding := HxEncoding.Multipart,
+  input(name := "file", `type` := "file"),
+  input(name := "description"),
+  button("Upload")
+)
+```
+
+When you omit `hxEncoding`, HTMX uses the default encoding (URL-encoded form data), so there is no DSL value for the default case. This keeps the DSL focused on the special cases that deviate from the default.
+
+## Common Patterns
+
+Multipart encoding enables file uploads in HTMX forms. Here are practical usage patterns:
+
+### File Upload with Metadata
+
+Send a file along with additional form fields:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/api/upload-document",
+  hxEncoding := HxEncoding.Multipart,
+  hxTarget := HxTarget.css("#upload-status"),
+  hxSwap := HxSwap.InnerHTML,
+  fieldset(
+    legend("Upload Document"),
+    input(
+      name := "file",
+      `type` := "file",
+      accept := ".pdf,.doc,.docx"
+    ),
+    input(
+      name := "title",
+      placeholder := "Document Title"
+    ),
+    textarea(name := "description", "Description"),
+    button("Upload")
+  )
+)
+```
+
+### Profile Picture Upload
+
+Update a profile picture with multipart encoding:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/api/profile-picture",
+  hxEncoding := HxEncoding.Multipart,
+  hxTarget := HxTarget.css("#profile-pic"),
+  hxSwap := HxSwap.OuterHTML,
+  input(
+    name := "image",
+    `type` := "file",
+    accept := "image/*"
+  ),
+  button("Update Picture")
+)
+```
+
+## Integration with Other Request Control Attributes
+
+`HxEncoding` works alongside `HxParams` to control both how data is encoded and which fields are sent:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/upload",
+  hxEncoding := HxEncoding.Multipart,
+  hxParams := HxParams.only("file", "title"),  // only send these fields
+  input(name := "file", `type` := "file"),
+  input(name := "title"),
+  input(name := "csrf_token"),  // excluded by hxParams
+  button("Upload")
+)
+```
+
+The `ToHtmxValue[HxEncoding]` instance renders automatically, so `HxEncoding` values work seamlessly with the `hxEncoding` attribute key.

package/reference/htmx/hx-params.md

@@ -0,0 +1,204 @@
+---
+id: hx-params
+title: HxParams
+---
+
+`HxParams` represents the `hx-params` attribute, controlling which form parameters are included in the HTMX request. Instead of sending all form fields, you can explicitly allow or forbid specific parameters through compile-safe domain types.
+
+Use `HxParams.All` to include all parameters, `HxParams.None` to include none, or `HxParams.only()` and `HxParams.not()` to allow/forbid specific names. Here are the core patterns:
+
+```scala
+import zio.http.htmx._
+
+// Include all parameters
+HxParams.All
+
+// Include no parameters
+HxParams.None
+
+// Include only specific parameters
+HxParams.only("query", "page")
+
+// Exclude specific parameters
+HxParams.not("csrf_token", "session")
+```
+
+## Strategies
+
+**`HxParams.All`** includes all form parameters in the request (the default HTMX behavior):
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/search",
+  hxParams := HxParams.All
+)
+```
+
+**`HxParams.None`** excludes all form parameters. The request body is empty:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/ping",
+  hxParams := HxParams.None,
+  "Ping Server"
+)
+```
+
+**`HxParams.only(first, rest*)`** includes only the listed parameters by name:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/search",
+  hxParams := HxParams.only("query", "page", "limit"),
+  placeholder := "Search..."
+)
+```
+
+**`HxParams.not(first, rest*)`** excludes the listed parameters, sending all others:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/submit",
+  hxParams := HxParams.not("csrf_token", "_method"),
+  input(name := "username"),
+  input(name := "csrf_token"),
+  button("Submit")
+)
+```
+
+## Rendering & Parsing
+
+**`render: String`** produces the literal `hx-params` attribute value string:
+
+```scala
+import zio.http.htmx._
+
+HxParams.All.render                           // "*"
+HxParams.None.render                          // "none"
+HxParams.only("query", "page").render         // "query,page"
+HxParams.not("csrf_token", "session").render  // "not csrf_token,session"
+```
+
+**`HxParams.parse(value: String): Either[String, HxParams]`** parses a rendered string back into a typed `HxParams`:
+
+```scala
+import zio.http.htmx._
+
+HxParams.parse("*")                    // Right(HxParams.All)
+HxParams.parse("none")                 // Right(HxParams.None)
+HxParams.parse("query,page")           // Right(HxParams.only("query", "page"))
+HxParams.parse("not csrf,session")     // Right(HxParams.not("csrf", "session"))
+```
+
+Parse failures return a descriptive `Left`:
+
+```scala
+import zio.http.htmx._
+
+HxParams.parse("")                     // Left("HTMX params list must be non-empty")
+HxParams.parse("query,,page")          // Left("HTMX params list cannot contain empty names")
+```
+
+## Common Patterns
+
+`HxParams` is useful when you need fine-grained control over which form fields are sent to the server. Here are representative usage patterns:
+
+### Search Without CSRF Token
+
+Include only the search query parameter, excluding the CSRF token typically added by form handlers:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  name := "query",
+  hxPost := "/search",
+  hxParams := HxParams.only("query"),
+  placeholder := "Search..."
+)
+```
+
+### Selective Parameter Submission
+
+When a form has many fields but an HTMX request should only send a few:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  input(name := "firstName"),
+  input(name := "lastName"),
+  input(
+    name := "email",
+    hxPost := "/validate-email",
+    hxParams := HxParams.only("email"),
+    hxTarget := HxTarget.next(".error"),
+    placeholder := "Email"
+  ),
+  div("Error message")
+)
+```
+
+### Exclude Framework Parameters
+
+Prevent sending framework-specific parameters (like Rails' `_method`, CSRF tokens) to the HTMX endpoint:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/api/submit",
+  hxParams := HxParams.not("_method", "authenticity_token", "utf8"),
+  button("Submit")
+)
+```
+
+### No Parameter Request
+
+Send a request without any form data, useful for server-side-only actions:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/logout",
+  hxParams := HxParams.None,
+  "Logout"
+)
+```
+
+## Integration with Request Control
+
+`HxParams` works with other request-control attributes like `hxEncoding` and `hxSync`:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/upload",
+  hxParams := HxParams.only("file", "description"),
+  hxEncoding := HxEncoding.Multipart,
+  input(name := "file", `type` := "file"),
+  input(name := "description"),
+  button("Upload")
+)
+```
+
+The `ToHtmxValue[HxParams]` instance renders automatically, so `HxParams` values work seamlessly with the `hxParams` attribute key.