@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/htmx/hx-swap.md

@@ -0,0 +1,276 @@
+---
+id: hx-swap
+title: HxSwap
+---
+
+`HxSwap` represents the `hx-swap` attribute, controlling how HTMX replaces DOM content after a successful response. It combines a base strategy (innerHTML, outerHTML, etc.) with optional modifiers that refine timing, animation, scrolling, and focus behavior.
+
+Start from one of the predefined strategies, then call modifier methods to customize timing, animation, and scroll behavior. All modifiers are optional, and calling the same modifier twice replaces the earlier value rather than stacking. Here are the core patterns:
+
+```scala
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+// Base strategy only
+HxSwap.InnerHTML
+
+// With timing modifiers
+HxSwap.OuterHTML.swap(1.second).settle(500.millis)
+
+// With animation and scroll
+HxSwap.BeforeEnd.transition.scroll(HxSwap.ScrollPosition.Top)
+
+// Full pipeline
+HxSwap.InnerHTML
+  .swap(500.millis)
+  .settle(250.millis)
+  .transition
+  .scroll(HxSwap.ScrollPosition.Bottom)
+  .show(HxSwap.ShowPosition.Top)
+  .focusScroll(true)
+```
+
+## Swap Strategies
+
+Core HTMX strategies define where and how content replaces the DOM:
+
+- `HxSwap.InnerHTML` — Replaces the inner content of the target element. This is the default HTMX behavior.
+- `HxSwap.OuterHTML` — Replaces the target element itself, including its opening and closing tags.
+- `HxSwap.TextContent` — Replaces only the text content, leaving the element structure intact.
+- `HxSwap.BeforeBegin` — Inserts the response as a sibling before the target element.
+- `HxSwap.AfterBegin` — Inserts the response as the first child of the target element.
+- `HxSwap.BeforeEnd` — Inserts the response as the last child of the target element.
+- `HxSwap.AfterEnd` — Inserts the response as a sibling after the target element.
+- `HxSwap.Delete` — Removes the target element; response content is discarded.
+- `HxSwap.NoneSwap` — Prevents any content from being swapped into the DOM; the response is ignored.
+
+All strategies are available as immutable `HxSwap` values, ready for modifier chaining:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+div(hxSwap := HxSwap.InnerHTML)
+div(hxSwap := HxSwap.OuterHTML)
+div(hxSwap := HxSwap.BeforeBegin)
+```
+
+## Timing Modifiers
+
+Control when and how long the swap operation takes:
+
+**`swap(duration: FiniteDuration)`** adds a `swap:` delay before the swap begins. Useful for coordinating with request latency or preparing the DOM:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+// Wait 500ms after response before swapping
+div(hxSwap := HxSwap.InnerHTML.swap(500.millis))
+```
+
+**`settle(duration: FiniteDuration)`** adds a `settle:` delay after the swap before settling (CSS transitions, settling messages). This allows animations to run:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+// Swap immediately, but wait 250ms for CSS to settle
+div(hxSwap := HxSwap.InnerHTML.settle(250.millis))
+```
+
+Both `swap()` and `settle()` accept any `FiniteDuration` that renders to a valid HTMX duration (milliseconds: `ms`, seconds: `s`, or bare integers treated as milliseconds). Calling either method twice replaces the first value:
+
+```scala
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+val swap1 = HxSwap.InnerHTML.swap(1.second)
+val swap2 = swap1.swap(500.millis)  // replaces 1.second with 500.millis
+```
+
+## Animation & Transition
+
+**`transition: HxSwap`** enables the `transition:true` modifier, allowing CSS transitions to run during the swap. Useful with timing modifiers to coordinate animation:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+// Enable transitions and give them 300ms to complete
+div(hxSwap := HxSwap.InnerHTML.transition.settle(300.millis))
+```
+
+## Scroll Behavior
+
+Control where the page scrolls after a swap:
+
+**`scroll(position: HxSwap.ScrollPosition)`** adds a `scroll:` modifier. Valid positions are `HxSwap.ScrollPosition.Top` and `HxSwap.ScrollPosition.Bottom`:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// Scroll to top after swapping
+div(hxSwap := HxSwap.InnerHTML.scroll(HxSwap.ScrollPosition.Top))
+
+// Scroll to bottom (useful for chat/log appends)
+div(hxSwap := HxSwap.BeforeEnd.scroll(HxSwap.ScrollPosition.Bottom))
+```
+
+**`show(position: HxSwap.ShowPosition)`** adds a `show:` modifier to control where newly swapped content becomes visible. Valid positions are `HxSwap.ShowPosition.Top` and `HxSwap.ShowPosition.Bottom`:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// Show the top of the newly swapped content
+div(hxSwap := HxSwap.InnerHTML.show(HxSwap.ShowPosition.Top))
+```
+
+## Focus & Title Management
+
+**`focusScroll(enabled: Boolean)`** sets the `focusScroll:` modifier to control whether focus moves during swap. Pass `true` to focus the swapped element, `false` to disable focus movement:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// Enable focus scroll (default HTMX behavior)
+div(hxSwap := HxSwap.InnerHTML.focusScroll(true))
+
+// Disable automatic focus movement
+div(hxSwap := HxSwap.InnerHTML.focusScroll(false))
+```
+
+**`ignoreTitle: HxSwap`** enables the `ignoreTitle:true` modifier, preventing HTMX from updating the document title if the response contains an `<title>` tag:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+// Don't update the page title even if response has one
+div(hxSwap := HxSwap.InnerHTML.ignoreTitle)
+```
+
+## Rendering & Parsing
+
+**`render: String`** produces the literal `hx-swap` attribute value string:
+
+```scala
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+val swap = HxSwap.InnerHTML.swap(1.second).settle(500.millis).transition
+swap.render  // "innerHTML swap:1s settle:500ms transition:true"
+```
+
+**`HxSwap.parse(value: String): Either[String, HxSwap]`** decodes a rendered HTMX swap string into a typed `HxSwap` value. The parser accepts the same format that `render` produces:
+
+```scala
+import zio.http.htmx._
+
+val parsed = HxSwap.parse("outerHTML swap:2s settle:250ms transition:true scroll:bottom")
+// Right(HxSwap.OuterHTML.swap(2 seconds).settle(250 millis).transition.scroll(ScrollPosition.Bottom))
+```
+
+Parse failures return a descriptive `Left` with the error reason:
+
+```scala
+import zio.http.htmx._
+
+HxSwap.parse("")              // Left("Empty HTMX swap value")
+HxSwap.parse("bogus")         // Left("Unknown HTMX swap strategy: bogus")
+HxSwap.parse("innerHTML swap:later")  // Left("Unsupported HTMX duration: later")
+HxSwap.parse("innerHTML scroll:middle")  // Left("Invalid HTMX scroll position: middle")
+```
+
+## Common Patterns
+
+Effective swap strategies enhance user experience through proper timing and animation. Here are practical usage patterns:
+
+### Fade-In New Content
+
+Combine `HxSwap#transition` with `HxSwap#settle` delay to fade in new elements:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+div(
+  hxGet := "/new-items",
+  hxSwap := HxSwap.BeforeEnd.transition.settle(300.millis)
+)
+```
+
+### Scroll New Content Into View
+
+Use `HxSwap#scroll` with `BeforeEnd` or `AfterEnd` to append content and scroll to it:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+div(
+  id := "messages",
+  hxGet := "/new-messages",
+  hxTrigger := HxTrigger.every(2.seconds),
+  hxSwap := HxSwap.BeforeEnd.scroll(HxSwap.ScrollPosition.Bottom)
+)
+```
+
+### Replace and Focus
+
+Use `InnerHTML` or `OuterHTML` with `HxSwap#focusScroll` to replace content and move focus:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  hxPost := "/submit",
+  hxSwap := HxSwap.OuterHTML.focusScroll(true),
+  button("Submit")
+)
+```
+
+### Preserve Animations While Settling
+
+Increase the `HxSwap#settle` delay to let CSS animations complete before HTMX considers the swap done:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+// CSS animations run for 500ms; settle after they complete
+div(
+  hxPost := "/update",
+  hxSwap := HxSwap.InnerHTML.transition.settle(500.millis)
+)
+```
+
+## Integration with Other Module Types
+
+`HxSwap` is most often paired with `HxTrigger` (when to request) and `HxTarget` (where to apply the swap):
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+button(
+  hxPost := "/api/action",
+  hxTrigger := HxTrigger.click.delay(100.millis),
+  hxTarget := HxTarget.closest("form"),
+  hxSwap := HxSwap.InnerHTML.settle(250.millis),
+  "Perform Action"
+)
+```
+
+The `ToHtmxValue[HxSwap]` type class renders automatically, enabling you to assign `HxSwap` values directly using the `:=` operator on the `hxSwap` attribute key.

package/reference/htmx/hx-sync.md

@@ -0,0 +1,251 @@
+---
+id: hx-sync
+title: HxSync
+---
+
+`HxSync` represents the `hx-sync` attribute, coordinating multiple HTMX requests by specifying how new requests interact with pending or running requests on a target element. This prevents race conditions and ensures predictable behavior when multiple events fire in quick succession.
+
+Create an `HxSync` by pairing an `HxTarget` (which element to synchronize) with a `HxSyncStrategy` (how to handle conflicts):
+
+```scala
+import zio.http.htmx._
+
+// Wait for this element's request to finish before starting a new one
+HxSync(HxTarget.This, HxSyncStrategy.Queue)
+
+// Replace a pending request with a new one
+HxSync(HxTarget.closest("form"), HxSyncStrategy.Replace)
+
+// Drop new requests while one is in flight
+HxSync(HxTarget.This, HxSyncStrategy.Drop)
+
+// Abort the current request and start the new one immediately
+HxSync(HxTarget.This, HxSyncStrategy.Abort)
+```
+
+## Sync Strategies
+
+**`HxSyncStrategy.Queue`** queues new requests, executing them after the current request completes. This is the default HTMX behavior when `hx-sync` is not specified. Useful for ensuring requests are processed in order:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/search",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Queue),
+  placeholder := "Search..."
+)
+```
+
+**`HxSyncStrategy.Replace`** cancels any pending request and immediately sends the new one. Useful for searches and filters where the latest value is all that matters:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/search",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Replace),
+  placeholder := "Live Search (only latest request sent)"
+)
+```
+
+**`HxSyncStrategy.Drop`** discards new requests while one is in flight. Only the first request in a burst is sent; others are ignored. Useful for expensive operations that shouldn't be duplicated:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/expensive-operation",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Drop),
+  "Process (only first request sent)"
+)
+```
+
+**`HxSyncStrategy.Abort`** cancels any in-flight request and immediately sends the new one. The old request's response is discarded. Useful for time-sensitive operations:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/time-sensitive-action",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Abort),
+  "Execute (cancels previous)"
+)
+```
+
+## Target Specification
+
+The first parameter of `HxSync` is an `HxTarget` specifying which element to synchronize. This allows coordinating requests across multiple elements:
+
+**Synchronize the current element:**
+
+Use `HxTarget.This` to synchronize the element that initiates the request:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/search",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Replace),
+  placeholder := "Search..."
+)
+```
+
+**Synchronize a parent form:**
+
+Synchronize across all fields in a form using `HxTarget.closest()`:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+input(
+  hxPost := "/validate",
+  hxSync := HxSync(HxTarget.closest("form"), HxSyncStrategy.Queue),
+  placeholder := "Email"
+)
+```
+
+**Synchronize multiple fields at once:**
+
+Apply the same sync strategy to multiple fields within a form:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  input(
+    name := "firstName",
+    hxPost := "/validate",
+    hxSync := HxSync(HxTarget.closest("form"), HxSyncStrategy.Queue)
+  ),
+  input(
+    name := "email",
+    hxPost := "/validate",
+    hxSync := HxSync(HxTarget.closest("form"), HxSyncStrategy.Queue)
+  )
+)
+```
+
+## Rendering & Parsing
+
+**`render: String`** produces the literal `hx-sync` attribute value string:
+
+```scala
+import zio.http.htmx._
+
+HxSync(HxTarget.This, HxSyncStrategy.Queue).render     // "this:queue"
+HxSync(HxTarget.closest("form"), HxSyncStrategy.Replace).render  // "closest form:replace"
+```
+
+**`HxSync.parse(value: String): Either[String, HxSync]`** parses a rendered string back into a typed `HxSync`:
+
+```scala
+import zio.http.htmx._
+
+HxSync.parse("this:queue")             // Right(HxSync(HxTarget.This, HxSyncStrategy.Queue))
+HxSync.parse("closest form:replace")   // Right(HxSync(HxTarget.closest("form"), HxSyncStrategy.Replace))
+```
+
+## Common Patterns
+
+Synchronization strategies prevent race conditions in interactive forms. Here are practical usage patterns:
+
+### Search with Last-Value-Wins
+
+Use `Replace` to ensure only the most recent search is sent when typing quickly:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+input(
+  hxPost := "/search",
+  hxTrigger := HxTrigger.input.delay(300.millis),
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Replace),
+  hxTarget := HxTarget.css("#results"),
+  placeholder := "Search (only latest request sent)"
+)
+```
+
+### Ordered Form Validation
+
+Use `Queue` to validate form fields in the order they were changed, preventing race conditions:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  input(
+    name := "username",
+    hxPost := "/validate/username",
+    hxSync := HxSync(HxTarget.closest("form"), HxSyncStrategy.Queue)
+  ),
+  input(
+    name := "email",
+    hxPost := "/validate/email",
+    hxSync := HxSync(HxTarget.closest("form"), HxSyncStrategy.Queue)
+  )
+)
+```
+
+### Prevent Double-Submit
+
+Use `Drop` to prevent duplicate submissions when users click a button repeatedly:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+form(
+  button(
+    hxPost := "/submit",
+    hxSync := HxSync(HxTarget.This, HxSyncStrategy.Drop),
+    "Submit (first click only)"
+  )
+)
+```
+
+### Abort Slow Requests
+
+Use `Abort` for requests that shouldn't queue up, replacing old requests immediately:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+
+button(
+  hxPost := "/fetch-latest",
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Abort),
+  "Fetch Latest (aborts previous)"
+)
+```
+
+## Integration with Other Attributes
+
+`HxSync` works alongside trigger and timing attributes to coordinate complex request patterns:
+
+```scala
+import zio.blocks.html._
+import zio.http.htmx._
+import scala.concurrent.duration._
+
+input(
+  hxPost := "/search",
+  hxTrigger := HxTrigger.input.delay(500.millis).changed,
+  hxSync := HxSync(HxTarget.This, HxSyncStrategy.Replace),
+  hxParams := HxParams.only("query"),
+  hxTarget := HxTarget.css("#results"),
+  placeholder := "Search"
+)
+```
+
+The `ToHtmxValue[HxSync]` instance renders automatically, so `HxSync` values work seamlessly with the `hxSync` attribute key.