phlex-reactive 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83d418e64d127a079e74679e4920d85803fedff629e8d8b135c2896a79b5bbdd
-  data.tar.gz: 16c68638d96348ea94c0fa25d411486e49c0b2dab01f07fe9e67fefba630a537
+  metadata.gz: 479ff63041e0a402939303aec9ea5fc8064dc0b01f5e63c8c58cfe989e5173b3
+  data.tar.gz: b81323095162d6b0662ff18b91b0c8cb34a8e2000028353c695e255ffa13093f
 SHA512:
-  metadata.gz: cc16a212daaeb236631702db89fe846dabf936d532e18919c0a371d408f29ce94ae94028eff8cc82e3ff66f1ee25a8acb75f2df29f0b1e2ceb819e49ee3b7217
-  data.tar.gz: 0b9721189cb032d6a91ae163b15742cb1cb163ef93da4b5ced1d4382811b43da5b5ba3ea25041b5919b20fb58d2dd4d582d8c1ba1345b6d8accf7ac94cdeb978
+  metadata.gz: 80070c0e2868530f8499008a603e6f32c4815916fa34c4fccc050b3fb0772c0501ea27e569ee88ada9acb68d7f3eca5fc7333201fc3b9e4358780abd9b6e5d6a
+  data.tar.gz: 6412dc6000663fd888193bf9a1b071b9d2f1984692cac474217ebd4955f302e963103bb4bd5ad5c3407b351dfe69a5c2a7079fcdd04b65d73dfed34092c60765

data/CHANGELOG.md

@@ -6,6 +6,69 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **Nested & array param types (issue #16).** Action param schemas can now
+  declare arrays and nested hashes, not just scalars: wrap a type in an array
+  (`bank_account_ids: [:integer]`) for an array param, or wrap a hash schema in
+  an array (`invoice_items_attributes: [{ id: :integer, quantity: :float,
+  _destroy: :boolean }]`) for Rails-style nested attributes. Coercion recurses
+  per field, drops undeclared nested keys (no mass assignment), and accepts an
+  array as either a JSON array or a Rails index hash (`{ "0" => …, "1" => … }`).
+  A malformed (present-but-non-array) value for an array param is dropped — not
+  coerced to `[]` — so a bad payload can't read as an explicit "clear all" on an
+  `update!(declared_array:)`; a real empty array still passes through as `[]`.
+  A reactive form can now mirror a normal nested-attributes update in one action
+  instead of being forced into a per-row component architecture.
+- **Debounce option on `on(...)` (issue #17).** A trigger can declare
+  `on(:update, event: "input", debounce: 300)` (milliseconds) to coalesce rapid
+  events — typically keystrokes — into a SINGLE action round trip fired after the
+  quiet period, instead of one POST per keystroke. A `blur` flushes a pending
+  dispatch so the last edit is never dropped, `preventDefault` still fires
+  synchronously (a debounced `submit` won't navigate), and the debounced round
+  trip still goes through the per-component queue so token threading holds.
+  Omitting `debounce:` keeps the immediate-dispatch default.
+
+### Fixed
+
+- **Nested reactive roots no longer leak fields (issue #15).** When a reactive
+  component is rendered inside another (both are `data-controller="reactive"`
+  roots), an action on the outer root previously swept *every* descendant named
+  input — including the nested roots' inputs — into its own params. Field
+  collection now stops at nested reactive roots: an action collects only the
+  inputs whose nearest `[data-controller~="reactive"]` ancestor is its own root.
+  Outer flat fields and per-row reactive editing compose cleanly, with no
+  name-disjointness workarounds.
+
+## [0.2.6]
+
+### Added
+
+- **Action response control via `Phlex::Reactive::Response`.** An action MAY now
+  return a `Response` to govern the actor's HTTP reply, instead of only the
+  implicit single re-render. Returning anything else keeps the legacy default
+  (re-render the component in place), so existing actions are unaffected.
+  - `Response.replace(self)` / `.update(self)` — explicit re-render.
+  - `Response.replace(self).flash(:error, msg_or_component)` — surface a
+    validation error / notice (the `#1` driver). `.flash` is additive on a
+    self-replace, so the component's signed token always refreshes. Flash
+    content is supplied explicitly (the render context is off-request — there is
+    no Rails `flash`); pass a string or a Phlex component. Target container is
+    `Phlex::Reactive.flash_target` (default `flash`).
+  - `Response.remove(self)` — drop the element (e.g. a moderation queue). New
+    instance helper `Streamable#to_stream_remove` backs it.
+  - `Response.redirect(url)` — client-side `Turbo.visit` for when the current
+    URL is dead (e.g. a slug rename). Rides a 200 turbo-stream carrying a
+    `reactive:visit` custom action (registered in the client), **not** an HTTP
+    3xx (which the client bails on). Pass a `*_url`.
+  - `Response.with(*streams)` / `#stream(*more)` — multi-stream (replace self +
+    a sibling component).
+- The endpoint guarantees the component's own replace is present (token refresh)
+  for non-remove/redirect responses, and never double-prepends when the action
+  already included a self-targeted stream.
+
+## [0.2.5]
+
 ### Fixed
 
 - **Form submit navigated instead of running the reactive action.** A component

data/README.md

@@ -149,7 +149,8 @@ for broadcasting.
    │                                          verify signed token (no state trusted)
    │                                          rebuild component (record from DB)
    │                                          run the whitelisted action
-   │                                          re-render → <turbo-stream replace id>
+   │                                          re-render → <turbo-stream replace id>   (default; an action
+   │                                          may return a Response — see "Controlling the action's reply")
    └──────── Turbo morphs it in ◀───────────────────────────────┘
 
    ...and for OTHER tabs/users:
@@ -254,7 +255,7 @@ The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
 | `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
 | `.broadcast_replace_to(*streamables, model:)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable) |
 | `.broadcast_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
-| `#to_stream_replace` / `#to_stream_update` | Stream the *already-built* instance (used internally after an action) |
+| `#to_stream_replace` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `Response`) |
 
 Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 
@@ -267,10 +268,50 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `action :name, params: { x: :integer }` | Declare a client-invokable action + its param schema. **Default-deny.** |
 | `reactive_attrs` | Spread onto the root element: marks it reactive + carries the signed token. |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
+| `on(:action, event: "input", debounce: 300)` | Coalesce rapid events into one round trip after a quiet period (live-as-you-type). |
 
 Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
 in the schema is dropped before reaching your method.
 
+**Array & nested params.** Wrap a type in an array for an array param, or a hash
+schema in an array for Rails-style nested attributes — so one reactive action can
+mirror a normal nested-attributes update instead of forcing a per-row component:
+
+```ruby
+action :save, params: {
+  date: :string,
+  bank_account_ids: [:integer],                         # array of scalar
+  invoice_items_attributes: [                            # array of hash
+    { id: :integer, quantity: :float, price: :float, _destroy: :boolean }
+  ]
+}
+
+def save(date:, bank_account_ids:, invoice_items_attributes:)
+  @invoice.update!(date:, bank_account_ids:, invoice_items_attributes:)
+end
+```
+
+Nested coercion recurses per field, drops undeclared nested keys, and accepts an
+array as either a JSON array or a Rails index hash (`{ "0" => …, "1" => … }`).
+
+**Nested reactive components compose.** A reactive component rendered inside
+another is its own root — field collection stops at nested
+`data-controller="reactive"` roots, so an outer action collects only *its own*
+named inputs, never a nested component's. An invoice editor's `save` sees its
+flat fields; each line-item row's `quantity`/`price` belong to that row's own
+action. No name-disjointness workarounds required.
+
+**Debounced triggers (live-as-you-type).** Pass `debounce:` (milliseconds) to
+coalesce rapid events — typically keystrokes on an `"input"` trigger — into a
+single action round trip fired after the quiet period, instead of one POST per
+keystroke. A blur flushes a pending dispatch so the last edit is never dropped.
+Omit `debounce:` for the immediate-dispatch default.
+
+```ruby
+# Recompute a total live as the user types, without hammering the endpoint.
+input(**mix(on(:update, event: "input", debounce: 300), name: "quantity", value: @item.quantity))
+```
+
 **Combining `on(...)` / `reactive_attrs` with your own attributes.** Both return
 a hash that includes a `data:` key. Spreading them *and* passing another `data:`
 (or `class:`, `id:`) would clobber it — use Phlex's `mix` to deep-merge:
@@ -284,6 +325,41 @@ div(**mix(reactive_attrs, id:, class: "card")) { ... }
 button(**on(:increment), data: { testid: "inc" }) { "+" }
 ```
 
+### `Phlex::Reactive::Response` — controlling the action's reply
+
+By default an action re-renders its component in place. **Return** a
+`Phlex::Reactive::Response` to do more (it governs only the actor's HTTP reply —
+cross-tab updates still use `broadcast_*_to(..., exclude: reactive_connection_id)`).
+Returning anything else keeps the default, so existing actions are unaffected.
+
+The snippets below alias the constant for brevity (`Response.replace(self)` won't
+resolve to `Phlex::Reactive::Response` inside a namespaced component — fully
+qualify it, or add the alias shown):
+
+```ruby
+Response = Phlex::Reactive::Response # or qualify each call below
+
+def rename(title:)
+  return Response.replace(self).flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
+  Response.replace(self)
+end
+
+def approve   = (@row.approve!; Response.remove(self))          # drop the element
+def publish   = (@article.publish!; Response.redirect(article_url(@article)))  # slug changed → Turbo.visit
+def add(item:) = Response.replace(self).stream(Totals.update(@order))           # multi-stream
+```
+
+| Builder | Reply |
+|---|---|
+| `Response.replace(self)` / `.update(self)` | re-render in place (explicit default) |
+| `.flash(level, content, target: …)` | append a flash; `content` is a string or Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
+| `Response.remove(self)` | remove the element (backed by `Streamable#to_stream_remove`) |
+| `Response.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
+| `Response.with(*streams)` / `#stream(*more)` | multi-stream |
+
+`.flash`/`.stream` are additive on a self-replace, so the component's signed
+token always refreshes.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -36,9 +36,9 @@ module Phlex
         component = component_class.from_identity(payload)
         coerced = coerce_params(action_def.params)
 
-        run_action(component, action_def, coerced)
+        result = run_action(component, action_def, coerced)
 
-        render turbo_stream: component.to_stream_replace
+        render turbo_stream: response_streams(result, component)
       rescue Phlex::Reactive::InvalidToken
         head :bad_request
       rescue ActiveRecord::RecordNotFound
@@ -69,6 +69,39 @@ module Phlex
         end
       end
 
+      # Turn the action's return value into the turbo-stream(s) to render for
+      # the actor. A Phlex::Reactive::Response is honored explicitly; any other
+      # value (the legacy contract — return value ignored) falls back to the
+      # implicit single replace, so existing actions are unaffected.
+      def response_streams(result, component)
+        return [component.to_stream_replace] unless result.is_a?(Phlex::Reactive::Response)
+        return [redirect_stream(result.redirect_url)] if result.redirect?
+
+        streams = result.streams
+        # Guarantee the component's signed identity token is refreshed unless the
+        # Response opted out (remove/redirect navigate away — handled above). The
+        # client reads the next token from the response body (#extractToken), so
+        # the real invariant is "a fresh data-reactive-token-value is present",
+        # NOT "some stream targets self". Checking the token directly is correct
+        # for replace AND update of self (both re-render the root via
+        # render_component, carrying the token), and still adds the fallback
+        # replace when a hand-built `with(...)` stream omits it. Idempotent: a
+        # Response.replace(self)/update(self) already carries the token, so we
+        # don't double the self-render.
+        if result.render_self? && streams.none? { |s| s.include?("data-reactive-token-value") }
+          streams = [component.to_stream_replace, *streams]
+        end
+        streams
+      end
+
+      # A 200 turbo-stream carrying a namespaced custom action the client turns
+      # into Turbo.visit — NOT an HTTP 3xx, which the client hard-bails on
+      # (response.redirected). The matching client handler is registered in
+      # reactive_controller.js.
+      def redirect_stream(url)
+        %(<turbo-stream action="reactive:visit" data-url="#{ERB::Util.html_escape(url)}"></turbo-stream>)
+      end
+
       def transaction_wrapper(&block)
         if defined?(::ActiveRecord::Base)
           ::ActiveRecord::Base.transaction(&block)
@@ -90,18 +123,63 @@ module Phlex
 
       # Coerce client params against the action's declared schema. Anything not
       # in the schema is dropped — no raw mass assignment reaches the component.
+      # The top-level params arrive as an ActionController::Parameters; coerce
+      # them against the action's hash schema (same recursion as nested hashes).
       def coerce_params(schema)
         return {} if schema.blank?
 
-        raw = params.fetch(:params, {})
+        coerce_hash(params.fetch(:params, {}), schema)
+      end
+
+      # Sentinel: a declared key whose value can't be coerced to its type is
+      # DROPPED (not assigned), so the method's keyword default applies — exactly
+      # as if the client had omitted the key. Distinct from a coerced nil/[].
+      DROP = Object.new
+      private_constant :DROP
+
+      # Coerce a value against a declared type. A type is one of:
+      #   * a scalar symbol            (:string/:integer/:float/:boolean)
+      #   * a Hash schema              ({ id: :integer, ... })   — nested object
+      #   * a one-element Array        ([:integer] / [{ ... }])  — array of that
+      # Arrays accept both a real JSON array and a Rails-style index hash
+      # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
+      def coerce(value, type)
+        if type.is_a?(Array)
+          coerce_array(value, type.first)
+        elsif type.is_a?(Hash)
+          coerce_hash(value, type)
+        else
+          coerce_scalar(value, type)
+        end
+      end
+
+      # A real array (or Rails index hash) coerces element-wise. A malformed
+      # present-but-non-array value returns DROP rather than [] — coercing a stray
+      # scalar to an empty array would let a bad payload read as an explicit
+      # "clear everything" on update!(declared_array:).
+      def coerce_array(value, element_type)
+        values = array_values(value)
+        return DROP if values.nil?
+
+        values.map { |element| coerce(element, element_type) }
+      end
+
+      # Keep declared keys only (drop undeclared — no mass assignment), recursing
+      # for nested hash/array element types. Symbolizes keys to splat as kwargs.
+      # A key whose value coerces to DROP is skipped (keyword default applies).
+      def coerce_hash(value, schema)
+        hash = to_param_hash(value)
         schema.each_with_object({}) do |(key, type), out|
-          next unless raw.key?(key.to_s)
+          next unless hash.key?(key.to_s)
 
-          out[key.to_sym] = coerce(raw[key.to_s], type)
+          coerced = coerce(hash[key.to_s], type)
+          next if coerced.equal?(DROP)
+
+          out[key.to_sym] = coerced
         end
       end
 
-      def coerce(value, type)
+      def coerce_scalar(value, type)
         case type
         when :integer then value.to_i
         when :float then value.to_f
@@ -110,6 +188,27 @@ module Phlex
         end
       end
 
+      # Normalize an array param: a real array passes through; a Rails index hash
+      # ({ "0" => ..., "1" => ... }) becomes its values in index order. Anything
+      # else (a stray scalar, nil) is malformed → nil, so the caller drops the
+      # param rather than fabricating an empty array.
+      def array_values(value)
+        return value.to_a if value.is_a?(Array)
+
+        if value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
+          to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
+        end
+      end
+
+      # Unwrap ActionController::Parameters (or a plain Hash) to a string-keyed
+      # Hash so coercion can index it uniformly.
+      def to_param_hash(value)
+        return value.to_unsafe_h.stringify_keys if value.respond_to?(:to_unsafe_h)
+        return value.stringify_keys if value.is_a?(Hash)
+
+        {}
+      end
+
       # Only components that opt into Reactive may be resolved. The signature
       # already gates this; defense in depth against constant injection.
       def resolve_component(name)

data/app/javascript/phlex/reactive/reactive_controller.js

@@ -17,6 +17,25 @@ import { Controller } from "@hotwired/stimulus"
 // .broadcast_* methods — so a click and a background broadcast converge on
 // one re-render unit.
 //
+// Custom turbo-stream action: the server tells the actor to full-navigate
+// (e.g. the record's slug changed and the current URL is now dead). It rides a
+// 200 turbo-stream — NOT an HTTP 3xx — so it never trips the response.redirected
+// bail below (which still correctly catches real auth/CSRF redirects). Registered
+// once on the Turbo global (no @hotwired/turbo import — the gem uses window.Turbo
+// everywhere, and a named import is unreliable under importmap/esbuild).
+export function registerReactiveVisit() {
+  const actions = window.Turbo?.StreamActions
+  if (!actions || actions["reactive:visit"]) return
+  actions["reactive:visit"] = function () {
+    const url = this.getAttribute("data-url")
+    if (url) window.Turbo.visit(url, { action: "advance" })
+  }
+}
+if (typeof window !== "undefined") {
+  if (window.Turbo) registerReactiveVisit()
+  else document.addEventListener("turbo:load", registerReactiveVisit, { once: true })
+}
+
 // Register this controller eagerly (not lazily) so a click immediately after
 // page load is never missed. The phlex-reactive engine auto-pins it with
 // preload: true for importmap apps; see the README for esbuild/webpack.
@@ -26,6 +45,15 @@ export default class extends Controller {
   }
 
   #tokenCache // freshest token, threaded synchronously across queued requests
+  #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
+
+  // Tear down any pending debounce timers when the controller leaves the DOM
+  // (Turbo morph/navigation removes the element). Otherwise a timer that hasn't
+  // fired yet would later call #enqueue on a disconnected controller — a round
+  // trip against a detached element / stale token (issue #17 follow-up).
+  disconnect() {
+    this.#clearAllDebounces()
+  }
 
   // Serialize requests per component. Each round trip rewrites the signed
   // token in the DOM (state lives in the token, not the client). If events
@@ -34,7 +62,7 @@ export default class extends Controller {
   // a per-controller promise makes each dispatch wait for the previous one, so
   // it always uses the freshest token.
   dispatch(event) {
-    const { action, params } = event.params
+    const { action, params, debounce } = event.params
     if (!action) return
 
     // Stop native behavior (button submit / FORM NAVIGATION) HERE, synchronously
@@ -42,15 +70,57 @@ export default class extends Controller {
     // still being handled — deferring it into the request-queue microtask (below)
     // is too late: a `submit` trigger would natively POST the form and navigate
     // before the reactive round trip runs (issue #11). For a `click` trigger
-    // there's no default to miss, so this was previously invisible.
+    // there's no default to miss, so this was previously invisible. This holds
+    // for debounced triggers too — the round trip is deferred, but the native
+    // default must still be prevented now.
     event.preventDefault()
 
+    // Debounced trigger (e.g. on(:update, event: "input", debounce: 300)):
+    // coalesce rapid events into ONE round trip after a quiet period, instead of
+    // one POST per keystroke (issue #17). A blur flushes a pending dispatch.
+    const ms = Number(debounce) || 0
+    if (ms > 0) return this.#debounceDispatch(event.target, ms, action, params)
+
     // Capture action/params now; the queued work runs in a later microtask, by
     // which point the event object may have been reset by the browser.
+    return this.#enqueue(action, params)
+  }
+
+  #enqueue(action, params) {
     this.queue = (this.queue ?? Promise.resolve()).then(() => this.#perform(action, params))
     return this.queue
   }
 
+  // Reset a per-element timer; only enqueue the round trip after `ms` of quiet.
+  // Also flush immediately on blur so leaving the field never drops the last
+  // edit (a long debounce shouldn't swallow a value the user tabbed away from).
+  #debounceDispatch(target, ms, action, params) {
+    this.#clearDebounce(target)
+
+    const flush = () => {
+      this.#clearDebounce(target)
+      this.#enqueue(action, params)
+    }
+    const timer = setTimeout(flush, ms)
+    target?.addEventListener?.("blur", flush, { once: true })
+    this.#debounceTimers.set(target, { timer, flush })
+  }
+
+  #clearDebounce(target) {
+    const pending = this.#debounceTimers.get(target)
+    if (!pending) return
+    clearTimeout(pending.timer)
+    target?.removeEventListener?.("blur", pending.flush)
+    this.#debounceTimers.delete(target)
+  }
+
+  // Clear every pending debounce timer (used on disconnect). Reuses
+  // #clearDebounce so all timer/listener teardown stays in one place. Snapshot
+  // the keys first — #clearDebounce mutates the map as it goes.
+  #clearAllDebounces() {
+    for (const target of [...this.#debounceTimers.keys()]) this.#clearDebounce(target)
+  }
+
   async #perform(action, params) {
     // Auto-collect named field values inside this component so a button-
     // triggered action still receives sibling inputs (Livewire-style).
@@ -126,10 +196,21 @@ export default class extends Controller {
     return match?.[1]
   }
 
+  // True when `el` is collected by THIS reactive root and not by a nested one.
+  // A reactive component can be rendered inside another (both are
+  // data-controller="reactive" roots). querySelectorAll() descends into nested
+  // roots, so without this guard an outer action would sweep the inner roots'
+  // inputs into its own params (issue #15). An element belongs to this root iff
+  // its nearest [data-controller~="reactive"] ancestor is this.element.
+  #ownsField(el) {
+    return el.closest('[data-controller~="reactive"]') === this.element
+  }
+
   #collectFields() {
     const fields = {}
-    // Standard form controls.
+    // Standard form controls owned by THIS root (not a nested reactive root).
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
+      if (!this.#ownsField(field)) return
       if (field.type === "checkbox") {
         fields[field.name] = field.checked
       } else if (field.type === "radio") {
@@ -148,6 +229,7 @@ export default class extends Controller {
     this.element
       .querySelectorAll("[name]:is(lexxy-editor, trix-editor, [contenteditable=''], [contenteditable=true], [contenteditable=plaintext-only])")
       .forEach((el) => {
+        if (!this.#ownsField(el)) return // skip editors owned by a nested reactive root (issue #15)
         // A plain element (e.g. a <div contenteditable>) has no `name` IDL
         // property — only the attribute — so read getAttribute, not el.name.
         const name = el.getAttribute("name")

data/lib/phlex/reactive/component.rb

@@ -87,7 +87,21 @@ module Phlex
         # Declare a client-invokable action with an optional param schema.
         #   action :increment
         #   action :rename, params: { title: :string }
-        # Param types: :string (default), :integer, :float, :boolean.
+        #
+        # Param types are coerced server-side; anything not in the schema is
+        # dropped before reaching your method (no mass assignment):
+        #   * Scalars — :string (default), :integer, :float, :boolean
+        #   * Array of scalar — wrap the type in an array: [:integer]
+        #   * Array of hash (Rails nested attributes) — wrap a hash schema:
+        #       action :save, params: {
+        #         date: :string,
+        #         bank_account_ids: [:integer],
+        #         invoice_items_attributes: [
+        #           { id: :integer, quantity: :float, price: :float, _destroy: :boolean }
+        #         ]
+        #       }
+        # Array params accept BOTH a JSON array and a Rails-style index hash
+        # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
         def action(name, params: {})
           reactive_actions[name.to_sym] = Action.new(name: name.to_sym, params: params)
         end
@@ -168,11 +182,18 @@ module Phlex
       # Attributes for an element that triggers an action.
       #   button(**on(:toggle)) { "○" }
       #   form(**on(:save, event: "submit")) { ... }
+      #   input(**on(:update, event: "input", debounce: 300))  # live-as-you-type
       #
       # Extra keyword args become explicit params merged over collected form
       # fields. For click triggers we force type="button" so a bare button
       # inside a <form> can't submit it and cause a full-page navigation.
-      def on(action_name, event: "click", **params)
+      #
+      # `debounce:` (milliseconds) coalesces rapid events (e.g. keystrokes on an
+      # "input" trigger) into ONE round trip fired after the quiet period — so
+      # live-update-as-you-type doesn't POST per keystroke. A blur flushes a
+      # pending dispatch so the last edit is never dropped. Omit it for the
+      # immediate-dispatch default.
+      def on(action_name, event: "click", debounce: nil, **params)
         attrs = {
           data: {
             action: "#{event}->reactive#dispatch",
@@ -180,6 +201,7 @@ module Phlex
             reactive_params_param: params.to_json
           }
         }
+        attrs[:data][:reactive_debounce_param] = debounce if debounce
         attrs[:type] = "button" if event == "click"
         attrs
       end

data/lib/phlex/reactive/response.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # An explicit, immutable description of the ACTOR's HTTP response to a
+    # reactive action. An action MAY return one; if it returns anything else
+    # (the legacy contract — return value ignored), the endpoint falls back to
+    # the implicit single component.to_stream_replace.
+    #
+    # A Response governs ONLY the actor's HTTP reply. Cross-tab updates still go
+    # through Streamable's broadcast_*_to(..., exclude: reactive_connection_id).
+    #
+    #   Response.replace(self)                          # re-render in place (the default, explicit)
+    #   Response.replace(self).flash(:error, msg)       # surface a validation error
+    #   Response.remove(self)                           # drop the element (e.g. moderation queue)
+    #   Response.redirect(article_url(@article))        # slug changed -> Turbo.visit the new URL
+    #   Response.replace(self).stream(Totals.update(@order))  # multi-stream
+    class Response
+      attr_reader :streams, :redirect_url
+
+      class << self
+        # Re-render the component in place (explicit form of today's default).
+        def replace(component) = new(streams: [component.to_stream_replace])
+
+        # Morph only inner HTML (preserves the root element + its token attr).
+        def update(component) = new(streams: [component.to_stream_update])
+
+        # Remove the component's element from the DOM. Uses the instance
+        # to_stream_remove (the component already knows its own #id — no
+        # class-builder reconstruction; works for record- and state-backed).
+        def remove(component) = new(streams: [component.to_stream_remove], render_self: false)
+
+        # Client-side full navigation (Turbo.visit). Use when the current URL
+        # is dead (slug rename) or the outcome belongs on another page. Pass a
+        # *_url (the off-request render context has no request host for *_path).
+        def redirect(url) = new(redirect_url: url, render_self: false)
+
+        # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
+        def with(*strings) = new(streams: strings.flatten)
+
+        # Build a flash turbo-stream that appends `content` into a host-app
+        # container. `content` is a Phlex component instance (rendered through
+        # the configured renderer so t()/url_for work) or a ready HTML string —
+        # supplied by the caller because the render context is off-request
+        # (there is no Rails `flash`).
+        def flash_stream(_level, content, target:)
+          html = content.is_a?(::Phlex::SGML) ? Phlex::Reactive.render(content) : content.to_s
+          Phlex::Reactive.flash_builder.append(target, html: html)
+        end
+      end
+
+      # render_self: when true (default for replace/update/with), the endpoint
+      # GUARANTEES the component's own replace is present so its
+      # data-reactive-token-value refreshes (the client extracts the next token
+      # from the response HTML). remove/redirect set it false (nothing stays).
+      def initialize(streams: [], redirect_url: nil, render_self: true)
+        @streams = streams.freeze
+        @redirect_url = redirect_url
+        @render_self = render_self
+        freeze
+      end
+
+      # Append extra turbo-stream strings (a sibling component, a flash).
+      # Returns a NEW Response (immutable).
+      def stream(*more)
+        self.class.new(
+          streams: @streams + more.flatten,
+          redirect_url: @redirect_url,
+          render_self: @render_self
+        )
+      end
+
+      # Append a flash turbo-stream into a host-app container (default
+      # <div id="flash">, configurable via Phlex::Reactive.flash_target).
+      def flash(level, content, target: Phlex::Reactive.flash_target)
+        stream(self.class.flash_stream(level, content, target:))
+      end
+
+      def redirect? = !@redirect_url.nil?
+      def render_self? = @render_self
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -187,6 +187,13 @@ module Phlex
       def to_stream_update
         self.class.turbo_stream_builder.update(id, html: self.class.render_component(self))
       end
+
+      # Render THIS instance as a remove stream. The component already knows its
+      # own #id, so no record/class reconstruction is needed (works for record-
+      # and state-backed components alike). Used by Response.remove.
+      def to_stream_remove
+        self.class.turbo_stream_builder.remove(id)
+      end
     end
   end
 end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.2.5"
+    VERSION = "0.2.7"
   end
 end

data/lib/phlex/reactive.rb

@@ -78,6 +78,26 @@ module Phlex
         @renderer ||= defined?(::ActionController::Base) ? ::ActionController::Base : nil
       end
 
+      # DOM id of the host-app container a Response#flash appends into.
+      # Default "flash"; override to match your layout's flash region.
+      def flash_target
+        @flash_target ||= "flash"
+      end
+
+      attr_writer :flash_target
+
+      # Render a Phlex component to HTML with a full (off-request) view context.
+      def render(component)
+        renderer.render(component, layout: false)
+      end
+
+      # A Turbo::Streams::TagBuilder bound to an off-request view context, used
+      # to build standalone streams (e.g. a Response flash append) not tied to a
+      # specific component's id.
+      def flash_builder
+        ::Turbo::Streams::TagBuilder.new(renderer.new.view_context)
+      end
+
       def base_controller_name
         @base_controller_name ||= "ActionController::Base"
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -129,6 +129,7 @@ files:
 - lib/phlex/reactive.rb
 - lib/phlex/reactive/component.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/response.rb
 - lib/phlex/reactive/streamable.rb
 - lib/phlex/reactive/version.rb
 homepage: https://github.com/mhenrixon/phlex-reactive