phlex-reactive 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6db6575334b8d59a054812e6815dc9b1968274a7917c66ec48c353dd95ba477d
-  data.tar.gz: 294d2d892c5e8a4b55466e0102b89fe945f7b4f23e1a882b06566c6898520f03
+  metadata.gz: 479ff63041e0a402939303aec9ea5fc8064dc0b01f5e63c8c58cfe989e5173b3
+  data.tar.gz: b81323095162d6b0662ff18b91b0c8cb34a8e2000028353c695e255ffa13093f
 SHA512:
-  metadata.gz: 362f900e12b5d4d0e3240d230b64b7ea1366e9109c1957c266d7695a7f3985b762ce29843c644c12dba6e91ffead0bf6ff7f7e73dc32eac046de79c5c5e3c8cc
-  data.tar.gz: 3fc968f66ea7892eba20e050e5be95ad75c878a5518052eaef4006a86b963ac3a3fd1e155d1d4b45f0ea05602d3db1decae1fbb3c75e3bd76cc93bc66a29a673
+  metadata.gz: 80070c0e2868530f8499008a603e6f32c4815916fa34c4fccc050b3fb0772c0501ea27e569ee88ada9acb68d7f3eca5fc7333201fc3b9e4358780abd9b6e5d6a
+  data.tar.gz: 6412dc6000663fd888193bf9a1b071b9d2f1984692cac474217ebd4955f302e963103bb4bd5ad5c3407b351dfe69a5c2a7079fcdd04b65d73dfed34092c60765

data/CHANGELOG.md

@@ -6,6 +6,40 @@ 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

data/README.md

@@ -268,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:

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,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

@@ -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.7"
   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.7
 platform: ruby
 authors:
 - Mikael Henriksson