phlex-reactive 0.14.0 → 0.14.2

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

@@ -682,6 +682,21 @@ const CLIENT_OPS = Object.freeze({
     if (el.textContent !== text) el.textContent = text
   },
 
+  // Tick or untick a whole checkbox group (issue #342) — "clear selection".
+  // The bindings feature flips the root's OWNED boxes the way its select-all
+  // header does (every box set, then input + change on each flipped one) and
+  // re-syncs the group bindings once. global: true ignores the op's own root
+  // and asks every reactive root on the page; each flips only the boxes it
+  // owns (nested roots included), so every root holding the group answers.
+  check_group: (el, args) => {
+    const roots = args.global ? document.querySelectorAll('[data-controller~="reactive"]') : [el]
+    for (const root of roots) {
+      __SPLIT__
+        ? withFeature("bindings", (bindings) => bindings.checkGroup(root, args.group, args.checked))
+        : bindingsFeature.checkGroup(root, args.group, args.checked)
+    }
+  },
+
   // Dispatch a bubbling CustomEvent (issue #96). RAW element.dispatchEvent — the
   // controller SHADOWS Stimulus's this.dispatch helper, so it must not be used.
   dispatch: (el, args) => {
@@ -831,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
@@ -925,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
@@ -1154,12 +1184,13 @@ function formNeeded(root) {
 
 // Show bindings and cross-root show targets, completion bindings, option
 // filtering, the bulk-selection group bindings (enable, select-all, count —
-// issue #319), the tag-chip input and draft nested rows: a form's client-only
-// bindings. The root declares one, or owns an element that does. (The probes
-// the connect-time gates ran before the split, unchanged.)
+// issue #319) and their cross-root targets (#343), the tag-chip input and
+// draft nested rows: a form's client-only bindings. The root declares one, or
+// owns an element that does. (The probes the connect-time gates ran before
+// the split, unchanged.)
 function bindingsNeeded(root) {
   return (
-    ["show-targets", "on-complete", "filter-input", "tags-field"].some(
+    ["show-targets", "group-targets", "on-complete", "filter-input", "tags-field"].some(
       (marker) => root.getAttribute?.(`data-reactive-${marker}`) != null,
     ) ||
     (root.querySelectorAll?.("[data-reactive-show-field], [data-reactive-show]") ?? []).length > 0 ||
@@ -2348,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/component/selection.rb

@@ -57,8 +57,125 @@ module Phlex
           mix({ data: { reactive_count: selection_group!(:reactive_count, group) } }, attrs)
         end
 
+        # CROSS-ROOT group bindings (issue #343) — the count and enable
+        # sibling of reactive_show_targets. The group bindings above only see
+        # boxes this root owns (#15), so a list that is its own reactive root
+        # cannot drive a bulk bar the page renders outside it. The root that
+        # OWNS the boxes declares the outside ids it drives instead. Spread it
+        # on the ROOT (mix alongside reactive_root and reactive_show_targets):
+        #
+        #   div(**mix(reactive_root,
+        #     reactive_show_targets("#bulk-bar" => { if: { "ids[]" => { checked: 1.. } } }),
+        #     reactive_group_targets("ids[]",
+        #       count:  "#bulk-count",                  # textContent = ticked count
+        #       enable: { "#bulk-archive" => 1.. })))   # disabled = !(count in range)
+        #
+        # Targets are SINGLE ID SELECTORS (raised here, warn-skipped by the
+        # client) resolved document-wide; a missing one is skipped. An enable
+        # value is an Integer (an exact count), a Range (a threshold) or a full
+        # if:/if_any:/unless: conditions Hash. They re-sync with the in-root
+        # bindings: every change, a morph, rows added or removed.
+        #
+        # ONE call per root (mix space-joins a second call's JSON into an
+        # unparseable attr); several groups go in the hash form:
+        #
+        #   reactive_group_targets("ids[]" => { count: "#c" }, "tags[]" => { enable: { "#t" => 1.. } })
+        #
+        # The outside markup gets its first paint from reactive_group_target_attrs.
+        def reactive_group_targets(group = nil, **options)
+          if group.nil? && (options.key?(:count) || options.key?(:enable))
+            raise ArgumentError, "reactive_group_targets needs the group first: " \
+                                 "reactive_group_targets(\"ids[]\", #{options.keys.map { "#{it}: ..." }.join(", ")})"
+          end
+
+          groups =
+            if group.nil? then options
+            elsif group.is_a?(Hash) then group
+            else { group => options }
+            end
+          if groups.empty?
+            raise ArgumentError, "reactive_group_targets needs a group and its targets: " \
+                                 "reactive_group_targets(\"ids[]\", count: \"#id\", enable: { \"#id\" => 1.. })"
+          end
+
+          wire = groups.to_h do |name, targets|
+            name = selection_group!(:reactive_group_targets, name)
+            [name, normalize_group_targets(name, targets)]
+          end
+          { data: { reactive_group_targets: wire.to_json } }
+        end
+
+        # First paint for an element a reactive_group_targets root drives but
+        # another component renders (computed from THIS component's
+        # reactive_values, so the outside markup never flashes):
+        #
+        #   span(id: "bulk-count") { reactive_group_target_attrs("ids[]", :count).to_s }   # the ticked count
+        #   button(id: "bulk-archive", **reactive_group_target_attrs("ids[]", :enable, 1..)) # { disabled: }
+        #
+        # :count is the Integer (0 for an empty or absent group). :enable is
+        # { disabled: true|false }, or {} when reactive_values does not cover
+        # the group (the client seeds it at connect).
+        def reactive_group_target_attrs(group, kind, condition = nil)
+          name = selection_group!(:reactive_group_target_attrs, group)
+          case kind
+          when :count then Phlex::Reactive::ShowConditions.checked_count(show_values(nil)&.dig(name))
+          when :enable
+            match = first_paint_match(group_enable_payload(name, "reactive_group_target_attrs", condition)["any"], nil)
+            match.nil? ? {} : { disabled: !match }
+          else
+            raise ArgumentError, "reactive_group_target_attrs takes :count or :enable, got #{kind.inspect}"
+          end
+        end
+
         private
 
+        def normalize_group_targets(name, targets)
+          unless targets.is_a?(Hash) && (targets.key?(:count) || targets.key?(:enable))
+            raise ArgumentError, "reactive_group_targets(#{name.inspect}) needs count: or enable:, got #{targets.inspect}"
+          end
+          if (unknown = targets.keys - %i[count enable]).any?
+            raise ArgumentError, "reactive_group_targets(#{name.inspect}): unknown option(s) " \
+                                 "#{unknown.map(&:inspect).join(", ")} — it takes count: and enable:"
+          end
+
+          wire = {}
+          wire["count"] = Array(targets[:count]).map { group_target_selector!(name, it) } if targets.key?(:count)
+          if targets.key?(:enable)
+            wire["enable"] = targets[:enable].to_h do |selector, condition|
+              [group_target_selector!(name, selector), group_enable_payload(name, "reactive_group_targets", condition)]
+            end
+          end
+          wire
+        end
+
+        def group_target_selector!(name, selector)
+          selector = selector.to_s
+          return selector if selector.match?(DSL::MIRROR_ID_SELECTOR)
+
+          raise ArgumentError, "reactive_group_targets(#{name.inspect}) target #{selector.inspect} must be a single " \
+                               "ID selector (\"#id\") — cross-root targets are id-allowlisted, like reactive_show_targets"
+        end
+
+        # An enable condition as the { "any" => groups } DNF payload: an
+        # Integer or Range is the group's checked count, a Hash is the full
+        # reactive_show conditions language.
+        def group_enable_payload(name, helper, condition)
+          conditions =
+            case condition
+            when Integer, Range then { if: { name => { checked: condition } } }
+            when Hash
+              if (unknown = condition.keys - Helpers::SHOW_CONDITION_KEYS).any?
+                raise ArgumentError, "#{helper}(#{name.inspect}): unknown conditions key(s) " \
+                                     "#{unknown.map(&:inspect).join(", ")} — it takes if:/if_any:/unless:"
+              end
+              condition
+            else
+              raise ArgumentError, "#{helper}(#{name.inspect}) enable takes an Integer (exact count), a Range " \
+                                   "(threshold) or an if:/if_any:/unless: conditions Hash, got #{condition.inspect}"
+            end
+          { "any" => Phlex::Reactive::ShowConditions.normalize(**conditions) }
+        end
+
         def selection_group!(helper, group)
           name = group.to_s
           return name unless name.strip.empty?

data/lib/phlex/reactive/js.rb

@@ -259,6 +259,36 @@ module Phlex
         append("text", args.freeze)
       end
 
+      # --- Tick or untick a checkbox group (issue #342) ---
+      #
+      # check_group(group, checked = true) — set every OWNED box of the group
+      # (the #15 rule: a nested root's boxes are its own) the way a
+      # reactive_select_all header does: every box first, then `input` +
+      # `change` on each one it flipped, then ONE re-sync of the header, count,
+      # show and enable bindings. The group is a checkbox name resolved like
+      # reactive_select_all's: a bare name takes reactive_scope, a bracketed one
+      # ("ids[]") is used verbatim. `global: true` is for a trigger outside the
+      # root that owns the group: EVERY connected reactive root on the page flips the
+      # boxes of that name it owns (nested roots included). ACTOR-ONLY like focus/submit: a broadcast that cleared
+      # every subscriber's selection would be hostile (BROADCAST_REFUSED_OPS).
+      #   button(**on_client(:click, js.check_group("ids[]", false))) { "✕" }
+
+      # Positional `checked` on purpose: js.check_group("ids[]", false) reads as
+      # the op it is (the issue #342 API).
+      def check_group(group, checked = true, global: false) # rubocop:disable Style/OptionalBooleanParameter
+        name = -group.to_s
+        if name.strip.empty?
+          raise ArgumentError, "check_group needs a checkbox group name (e.g. \"ids[]\"), got #{group.inspect}"
+        end
+        unless [true, false].include?(checked)
+          raise ArgumentError, "check_group(#{name.inspect}) takes true or false, got #{checked.inspect}"
+        end
+
+        args = { "to" => ROOT_SENTINEL, "group" => name, "checked" => checked }
+        args["global"] = true if global
+        append("check_group", args.freeze)
+      end
+
       # --- Dispatch a bubbling CustomEvent (issue #96) ---
       #
       # dispatch(name, to: nil, detail: {}) — emit a bubbling CustomEvent so other

data/lib/phlex/reactive/streamable.rb

@@ -36,10 +36,11 @@ module Phlex
       # Actor-only ops: a js broadcast rejects a broadcast that carries one.
       # Focus ops steal focus in every subscriber's tab (issue #96); submit
       # (issue #226) would force-submit every subscriber's form; paste_into
-      # (issue #228) would read every subscriber's clipboard. They belong to
-      # the actor's own reply (reply.js) or gesture (on_client / a reducer's
-      # $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
-      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear].freeze
+      # (issue #228) would read every subscriber's clipboard; check_group
+      # (issue #342) would tick or clear every subscriber's selection. They
+      # belong to the actor's own reply (reply.js) or gesture (on_client / a
+      # reducer's $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
+      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear check_group].freeze
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
       # SELF-TARGETING verbs derive the target from the component's #id (require a
@@ -191,7 +192,8 @@ module Phlex
             raise ArgumentError,
               "broadcast_to(js:) refuses actor-only op(s) #{refused.join(", ")} — broadcasting focus " \
               "steals it in every subscriber's tab; broadcasting submit force-submits every " \
-              "subscriber's form; broadcasting paste_into reads every subscriber's clipboard. " \
+              "subscriber's form; broadcasting paste_into reads every subscriber's clipboard; " \
+              "broadcasting check_group ticks or clears every subscriber's selection. " \
               "These are actor concerns (reply.js / on_client / $ops)."
           end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.14.0"
+    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.0
+  version: 0.14.2
 platform: ruby
 authors:
 - Mikael Henriksson