phlex-reactive 0.14.1 → 0.14.2

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

@@ -846,8 +846,8 @@ function parseOps(raw) {
 }
 
 // --- on_client binding records (issue #271) -----------------------------------
-// Each on_client call emits ONE record ({on, ops, window?, outside?, confirm?,
-// confirmWhen?}); mix space-joins several onto one element (spaces inside a
+// Each on_client call emits ONE record ({on, ops, window?, outside?, once?,
+// detail?, confirm?, confirmWhen?}); mix space-joins several onto one element (spaces inside a
 // record ride as \u0020, so the join is unambiguous). Stimulus hands every
 // runOps descriptor on an element the SAME event.params, so runOps selects the
 // record(s) whose descriptor matches the firing event: event.type, the key
@@ -940,6 +940,21 @@ function bindingMatches(record, event, keyMappings) {
   return dot < 0 || keyMappings === null || keyFilterMatches(on.slice(dot + 1), event, keyMappings)
 }
 
+// Issue #346: a record's `detail` lists top-level keys of event.detail and the
+// JSON scalar each must strictly equal — on_client("turbo:submit-end", ops,
+// detail: { success: true }) runs only after a successful submit. A missing or
+// non-object event.detail, or a missing key, never matches (default-deny); a
+// record without `detail` matches whatever the event carries.
+function detailMatches(record, event) {
+  const expected = record.detail
+  if (expected === undefined) return true
+  if (expected === null || typeof expected !== "object" || Array.isArray(expected)) return false
+  const detail = event.detail
+  if (detail === null || typeof detail !== "object") return false
+  // A missing key reads undefined, which no JSON scalar (null included) equals.
+  return Object.keys(expected).every((key) => detail[key] === expected[key])
+}
+
 // A `once: true` record (PR #272) is spent after its first run. Stimulus
 // removes only that binding's own listener; a regular same-event sibling on
 // the element keeps calling runOps with BOTH records, so the spent one is
@@ -2364,6 +2379,9 @@ export default class extends Controller {
       // An early replay never runs an outside: record (issue #303: an outside
       // click before connect had nothing to close).
       if (record.outside && event[EARLY_KEY]) continue
+      // A detail miss (issue #346) is a complete no-op — checked before the
+      // once record is spent, preventDefault and the confirm gate.
+      if (!detailMatches(record, event)) continue
       if (onceBindingSpent(this, event, record)) continue
       this.#runBinding(record.legacy ? { ...params, ops: record.ops } : record, event, trigger)
     }

data/lib/phlex/reactive/component/helpers.rb

@@ -417,6 +417,16 @@ module Phlex
         #             on_client(:click, js.hide("#menu"), outside: true),
         #             on_client("keydown.esc", js.hide("#menu"))))
         #
+        # Issue #346: `detail:` gates the binding on the event's payload — a Hash
+        # of top-level event.detail keys to the JSON scalar each must strictly
+        # equal. The ops run after a SUCCESSFUL submit only, and a failed one
+        # keeps the selection for the retry:
+        #   form(**on_client("turbo:submit-end", js.check_group("ids[]", false),
+        #                    detail: { success: true }))
+        # A missing event.detail or key never matches; a miss is a complete
+        # no-op (no confirm, no preventDefault). Not Turbo-specific: any
+        # CustomEvent whose detail carries a flag works.
+        #
         # Ops are EPHEMERAL UI: any server re-render of the component (an action
         # reply, a broadcast, a morph) rebuilds from server state and resets
         # whatever they toggled — by design (the LiveView JS-commands caveat). Use
@@ -425,7 +435,7 @@ module Phlex
         # Validation is loud: only a non-empty Phlex::Reactive::JS chain is
         # accepted — a dead trigger should fail at render, not no-op in the
         # browser.
-        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil)
+        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -443,7 +453,7 @@ module Phlex
               "(change/input), or gate it behind a reducer's $ops / reactive_on_complete."
           end
           window_bound = window || outside
-          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
+          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
           attrs = {
             data: {
               action: "#{event}#{"@window" if window_bound}->reactive#runOps#{":once" if once}",
@@ -1440,13 +1450,14 @@ module Phlex
         # overridable confirmResolver on(:action, confirm:) uses (#52/#55); the
         # client prompts BEFORE applying the ops. Issue #179: a Hash confirm: is
         # CONDITIONAL, compiled by the shared compile_conditional_confirm.
-        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
+        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
           record = { "on" => event }
           record["window"] = true if window_bound
           record["outside"] = true if outside
           # A mix-ed regular sibling keeps calling runOps after Stimulus drops
           # this binding's :once listener — the client skips a spent once record.
           record["once"] = true if once
+          record["detail"] = client_binding_detail(detail, once:) unless detail.nil?
           case confirm
           when nil, false then nil
           when String then record["confirm"] = confirm
@@ -1457,6 +1468,44 @@ module Phlex
           record
         end
 
+        # Issue #346: validate + stringify on_client's detail: filter. Loud at
+        # render, like the other on_client validations — a dead filter fails
+        # here, never silently in the browser.
+        def client_binding_detail(detail, once:)
+          unless detail.is_a?(Hash) && !detail.empty?
+            raise ArgumentError,
+              "on_client detail: takes a non-empty Hash of event.detail keys to values " \
+              "(e.g. detail: { success: true }), got #{detail.inspect}"
+          end
+          if once
+            raise ArgumentError,
+              "on_client detail: cannot combine with once: — Stimulus removes a :once listener on its " \
+              "first event, so a first non-matching event would leave the binding dead"
+          end
+          normalized = detail.to_h do |key, value|
+            unless client_detail_scalar?(value)
+              raise ArgumentError,
+                "on_client detail: values must be JSON scalars (true/false/nil, a String or a finite " \
+                "number), got #{value.inspect} for #{key.inspect}"
+            end
+            [key.to_s, value]
+          end
+          # :success and "success" would collapse into one key, dropping a condition.
+          if normalized.size < detail.size
+            raise ArgumentError, "on_client detail: keys must be unique as strings, got #{detail.keys.inspect}"
+          end
+
+          normalized
+        end
+
+        def client_detail_scalar?(value)
+          case value
+          when true, false, nil, String, Integer then true
+          when Float then value.finite?
+          else false
+          end
+        end
+
         def apply_confirm!(data, confirm)
           case confirm
           when String

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.14.1"
+    VERSION = "0.14.2"
   end
 end

metadata

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