phlex-reactive 0.14.0 → 0.14.1

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) => {
@@ -1154,12 +1169,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 ||

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