phlex-reactive 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6db6575334b8d59a054812e6815dc9b1968274a7917c66ec48c353dd95ba477d
-  data.tar.gz: 294d2d892c5e8a4b55466e0102b89fe945f7b4f23e1a882b06566c6898520f03
+  metadata.gz: 9b321b7411a892ec63333f9d85d988f7cf63609601386a03593efd736e88fb42
+  data.tar.gz: 00d40c394774eb54af634d328251f646a3fae1ac9bc0413ccbc89dd863608001
 SHA512:
-  metadata.gz: 362f900e12b5d4d0e3240d230b64b7ea1366e9109c1957c266d7695a7f3985b762ce29843c644c12dba6e91ffead0bf6ff7f7e73dc32eac046de79c5c5e3c8cc
-  data.tar.gz: 3fc968f66ea7892eba20e050e5be95ad75c878a5518052eaef4006a86b963ac3a3fd1e155d1d4b45f0ea05602d3db1decae1fbb3c75e3bd76cc93bc66a29a673
+  metadata.gz: bd7a2129ec09c6b33a9f623f201037f5bc6639f7b097c95f521a6bf7ba4999b8dc8e11f53f2b922f5e617d0dfd8e2b0185cc5676e20f040a9caf97637d2d9438
+  data.tar.gz: b6e611eab9a2ab3f3d3a6afff9c4780061ba07321ddb5db89970e076facc9d7a374f7809fe8bc38958040c34303a42484eefe25109495bdfb2b6f894a597ae3e

data/CHANGELOG.md

@@ -6,6 +6,52 @@ 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
+
+- **Model-scoped form fields feed a nested param (issue #21).** A Rails
+  `Form(model: @invoice)` posts flat bracketed keys (`invoice[date]`,
+  `invoice[status]`) because the client keeps each input's `name` verbatim. The
+  server did exact-key matching, so a nested schema (`params: { invoice: { date:
+  :string } }`) looked for the literal key `"invoice"`, never found it, and
+  dropped the whole param. Param normalization now expands bracket notation
+  before coercion — `invoice[date]` nests under `invoice`, and
+  `items_attributes[0][qty]` becomes the Rails index-hash form the array coercer
+  already understands. A nested schema matches a normal Rails form with zero
+  field renaming, which is what makes the issue #16 nested-param types useful for
+  real forms. Pre-nested objects, plain scalars, and non-string values (a
+  checkbox boolean) pass through unchanged.
+- **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

data/README.md

@@ -268,10 +268,62 @@ 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" => … }`).
+
+**Model-scoped form fields just work.** A standard Rails `Form(model: @invoice)`
+names its inputs `invoice[date]`, `invoice[status]`, … and the client posts those
+names verbatim. A nested schema matches them with zero field renaming — the
+endpoint expands bracket notation before coercion, so `invoice[date]` nests under
+`invoice` and `invoice_items_attributes[0][qty]` becomes the index-hash form
+above:
+
+```ruby
+action :save, params: {invoice: {date: :string, status: :string}}
+# client posts { "invoice[date]": "…", "invoice[status]": "…" }  → save(invoice: { date:, status: })
+```
+
+**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:

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

@@ -123,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
@@ -143,6 +188,84 @@ 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, then expand bracket notation so
+      # a model-scoped Rails form's flat keys nest (issue #21).
+      def to_param_hash(value)
+        flat =
+          if value.respond_to?(:to_unsafe_h)
+            value.to_unsafe_h.stringify_keys
+          elsif value.is_a?(Hash)
+            value.stringify_keys
+          else
+            return {}
+          end
+
+        expand_bracket_keys(flat)
+      end
+
+      # The client's #collectFields keeps a form input's name verbatim, so a
+      # Rails Form(model: @invoice) posts FLAT bracketed keys like
+      # "invoice[date]". Coercion does exact-key matching, so without this a
+      # nested schema (params: { invoice: { date: … } }) never finds "invoice"
+      # and drops everything. Expand "invoice[date]" => "2026-01-02" into
+      # { "invoice" => { "date" => "2026-01-02" } } — and "items[0][qty]" into
+      # the Rails index-hash form coerce_array already understands — deep-merging
+      # so sibling keys (invoice[date], invoice[status]) coalesce. Keys WITHOUT
+      # brackets and already-nested values pass through untouched, so a
+      # pre-nested object (issue #16) and plain scalars still work. Value types
+      # (a checkbox boolean, an explicit array) are preserved verbatim — unlike a
+      # round-trip through parse_nested_query, which only handles strings.
+      def expand_bracket_keys(flat)
+        flat.each_with_object({}) do |(key, value), out|
+          deep_assign(out, bracket_path(key), value)
+        end
+      end
+
+      # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
+      # "0", "qty"]. A key with no brackets is a single-element path.
+      def bracket_path(key)
+        return [key] unless key.include?("[")
+
+        head, rest = key.split("[", 2)
+        [head, *rest.scan(/[^\[\]]+/)]
+      end
+
+      # Walk/create nested hashes along `path`, then merge `value` at the leaf so
+      # a bracket key and a sibling pre-nested object coalesce regardless of which
+      # arrives first ({ "invoice[date]" => …, invoice: { status: … } } keeps
+      # both). #merge_value deep-merges hash/hash collisions and otherwise lets
+      # the later value win (a bracket key colliding with a flat scalar).
+      def deep_assign(hash, path, value)
+        *parents, leaf = path
+        node = parents.reduce(hash) do |acc, segment|
+          acc[segment] = {} unless acc[segment].is_a?(Hash)
+          acc[segment]
+        end
+        node[leaf] = merge_value(node[leaf], value)
+      end
+
+      # Combine an existing leaf value with a new one. Two hashes deep-merge (so
+      # bracket-expanded fields and a pre-nested object for the same key both
+      # survive); any other collision takes the new value.
+      def merge_value(existing, value)
+        return value unless existing.is_a?(Hash) && value.is_a?(Hash)
+
+        existing.merge(value.stringify_keys) { |_k, old, new| merge_value(old, new) }
+      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

@@ -45,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
@@ -53,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
@@ -61,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).
@@ -145,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") {
@@ -167,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/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.2.6"
+    VERSION = "0.2.8"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Mikael Henriksson