phlex-reactive 0.13.4 → 0.14.1

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -117,6 +117,24 @@
 #   <meta name="phlex-reactive-defer-path" content="<%%= Phlex::Reactive.defer_path %>">
 # Phlex::Reactive.defer_path = "/_r/defer"
 
+# Cacheable lazy fragments (reactive_lazy cache: { max_age: … }): the GET
+# endpoint's path prefix (default "/reactive/fragment") and the longest max-age
+# a component may be answered with (default 1 hour — within it the browser does
+# not ask the server, so it also bounds how long a revoked permission can keep
+# showing a cached fragment). If you change the path, expose it to the client
+# in the layout <head> (the client refuses fragment URLs outside the path it
+# knows; phlex_reactive:doctor checks for the tag):
+#   <meta name="phlex-reactive-fragment-path" content="<%%= Phlex::Reactive.fragment_path %>">
+# Phlex::Reactive.fragment_path = "/_r/fragment"
+# Phlex::Reactive.fragment_cache_max_age_limit = 10.minutes
+
+# Early triggers (issue #273): with `import "phlex/reactive/early"` in your
+# entry point, a trigger that fires before a lazily loaded controller connects
+# is replayed on connect — unless it is older than this (ms, default 10s).
+# Render it into your layout head for the client to read:
+#   <meta name="phlex-reactive-early-ttl" content="<%%= Phlex::Reactive.early_event_ttl_ms %>">
+# Phlex::Reactive.early_event_ttl_ms = 10_000
+
 # Client request timeout (default 30s). There is NO server-side setting — a hung
 # request aborts client-side after this window (reactive:error kind "timeout"),
 # so the per-component queue never wedges. Override in your layout head:

data/lib/phlex/reactive/claude/skills/phlex-reactive-debugging/SKILL.md

@@ -33,13 +33,15 @@ Run this FIRST — most "nothing happens" reports are a red ✗ here.
 ```bash
 bin/rails phlex_reactive:actions            # every component × action: params, file:line, auth
 bin/rails phlex_reactive:actions FORMAT=json
+bin/rails phlex_reactive:actions UNVERIFIED=1   # only the unverified rows (the review queue)
 bin/rails "phlex_reactive:find[counter]"    # fuzzy-find one; prints each action's method source
 ```
 
 Answers "what reactive actions exist, where are they defined, and is each
-authorized?" without grepping. The `auth` column is a heuristic (`authorized*` =
-an authorization call was detected in the body; `unverified` = none — a helper
-may still authorize indirectly).
+authorized?" without grepping. The `auth` column is a heuristic: `authorized*` =
+an authorization call was detected in the body; `skipped` / `skipped (class)` =
+the author opted out with `skip_verify_authorized` (for that action / for the
+whole class); `unverified` = neither — a helper may still authorize indirectly.
 
 ## 3. Scan the live page (browser inspector)
 

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

@@ -213,8 +213,29 @@ module Phlex
           # root's element for content that can't legally hold a <div> — a
           # `reactive_lazy tag: :tr` component rooting at <tr> inside <tbody>
           # ships a <tr> shell, not a <div> the HTML parser would hoist away.
-          def reactive_lazy(tag: :div)
-            Registry.write_scalar(self, :lazy, { tag: tag.to_sym })
+          #
+          # `on:` (issue #276) defers the REQUEST itself, not just server time:
+          #   reactive_lazy on: "panel:opened"        # a DOM event on (or bubbling into) the shell
+          #   reactive_lazy on: :visible              # the shell first scrolls into view
+          #   reactive_lazy on: { visible: "200px" }  # …with an IntersectionObserver rootMargin
+          # The shell then carries the identity token (no TTL) and materializes
+          # once through the action endpoint. See Component::Lazy.
+          #
+          # `cache:` (issue #277) makes the real render a privately cacheable GET:
+          #   reactive_lazy cache: { max_age: 10.minutes }   # combine with on:/tag: freely
+          # The shell carries a stable signed URL instead of a per-render token,
+          # and the endpoint answers `Cache-Control: private, max-age=…`, so the
+          # browser reuses the fragment across page views. Define
+          # `reactive_cache_version` to bust the URL when the content changes,
+          # and `reactive_cache_viewer` (e.g. Current.user&.id) to key the URL
+          # on the viewer instead of `Vary: Cookie` — needed for reuse ACROSS
+          # page views when the session cookie changes on every response
+          # (Rails' cookie store does).
+          def reactive_lazy(tag: :div, on: nil, cache: nil)
+            declaration = { tag: tag.to_sym }
+            declaration[:trigger] = Lazy.normalize_trigger(on) unless on.nil?
+            declaration[:cache] = Lazy.normalize_cache(cache) unless cache.nil?
+            Registry.write_scalar(self, :lazy, declaration)
           end
 
           # The RAW resolved lazy declaration ({ tag: } or nil) — the reader the
@@ -238,6 +259,22 @@ module Phlex
             value.is_a?(::Hash) ? value.fetch(:tag, :div) : :div
           end
 
+          # The normalized `on:` trigger of a lazy component — `{ event: "x" }`
+          # or `{ visible: "<rootMargin>" }` — or nil (plain reactive_lazy, or
+          # not lazy at all). The endpoint's `__materialize` gate reads it.
+          def reactive_lazy_trigger
+            value = reactive_lazy_declaration
+            value[:trigger] if value.is_a?(::Hash)
+          end
+
+          # The normalized `cache:` of a lazy component — `{ max_age: <seconds> }`
+          # — or nil. The fragment endpoint's opt-in gate reads it: only a
+          # component that declared `cache:` is reachable over GET.
+          def reactive_lazy_cache
+            value = reactive_lazy_declaration
+            value[:cache] if value.is_a?(::Hash)
+          end
+
           # Declare a client-invokable action with an optional param schema.
           #   action :increment
           #   action :rename, params: { title: :string }
@@ -258,6 +295,13 @@ module Phlex
           # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
           def action(name, params: {})
             require_server_actions!(:action)
+            # Issue #276: the endpoint routes `__materialize` to the lazy render
+            # before the action registry is consulted — a declared one would be
+            # dead code that looks invokable.
+            if name.to_sym == Lazy::MATERIALIZE_ACTION
+              raise ArgumentError, "action #{name.inspect} is reserved for reactive_lazy(on:)"
+            end
+
             # Issue #184: params: :symbol resolves a registered named schema.
             params = Phlex::Reactive.param_schema(params) if params.is_a?(Symbol)
             # If a scope is already declared, reject a schema nested under the scope
@@ -293,6 +337,34 @@ module Phlex
               "use reactive_actions.key?(#{name.inspect})"
           end
 
+          # Dormant root (issue #274): every root of this component renders
+          # data-reactive-dormant="reactive" instead of data-controller=
+          # "reactive", so the client is neither mounted nor (when loaded
+          # lazily) fetched until one of the root's triggers fires — for a root
+          # that only matters after a gesture (a closed dialog, a menu that
+          # loads on open). The app must import "phlex/reactive/early", which
+          # wakes the root. Inherited; `reactive_dormant false` turns it off
+          # again in a subclass, and reactive_root(dormant:) overrides per
+          # render. See Phlex::Reactive::Dormant.
+          #
+          # Not with reactive_lazy(on: :visible): that shell has no trigger to
+          # wake on (refused here, or at render for the other declaration order).
+          # A plain reactive_lazy shell ignores it: it fetches on connect, so it
+          # always mounts. reactive_lazy(on: "event") shells do go dormant.
+          def reactive_dormant(dormant = true) # rubocop:disable Style/OptionalBooleanParameter
+            unless [true, false].include?(dormant)
+              raise ArgumentError, "#{self}: reactive_dormant takes true or false, got #{dormant.inspect}"
+            end
+
+            Phlex::Reactive::Dormant.reject_visible_lazy!(self) if dormant
+
+            Registry.write_scalar(self, :dormant, dormant)
+          end
+
+          def reactive_dormant?
+            Registry.resolve_scalar(self, :dormant, :reactive_dormant?) == true
+          end
+
           # Opt out of the default-ON verify_authorized guard (issue #168).
           # Bare skips the WHOLE component (a public counter, a client-only
           # filter); with names skips just those actions:

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

@@ -12,6 +12,7 @@ module Phlex
       # no signing (those live in DSL and Identity).
       module Helpers
         extend ActiveSupport::Concern
+        include Selection
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).
@@ -72,8 +73,22 @@ module Phlex
         # Root-element attributes: marks the element reactive and carries the
         # signed identity token. Spread onto the root:
         #   div(id:, **reactive_attrs) { ... }
-        def reactive_attrs
-          data = { controller: "reactive" }
+        #
+        # `dormant: true` (issue #274; default: the class's reactive_dormant)
+        # renders data-reactive-dormant="reactive" IN PLACE of the controller
+        # attribute: nothing mounts until a trigger fires and phlex/reactive/early
+        # wakes the root. The actor's own reply renders awake (Dormant.awake).
+        def reactive_attrs(dormant: nil)
+          dormant = self.class.reactive_dormant? if dormant.nil? && self.class.respond_to?(:reactive_dormant?)
+          data =
+            if dormant && !Phlex::Reactive::Dormant.awake?
+              # The lazy SHELL (not the real render) of an on: :visible component
+              # can never wake — refuse it rather than ship a dead placeholder.
+              Phlex::Reactive::Dormant.reject_visible_lazy!(self.class) unless Phlex::Reactive::Defer.real_render?
+              { reactive_dormant: "reactive" }
+            else
+              { controller: "reactive" }
+            end
           # A CLIENT-ONLY component (Phlex::Reactive::ClientBindings, issue #180)
           # has no Identity, so no token — the root is tokenless (show/filter/
           # compute need no signed round trip). reactive_token is private, so the
@@ -137,7 +152,12 @@ module Phlex
         # fields, and — for warn_unsaved: true — the navigate-away marker (STRING
         # "true", since a boolean-true attr renders valueless → "" → falsy client-
         # side). The removed track_dirty:/warn_unsaved: kwargs raise a guided error.
-        def reactive_root(**overrides)
+        #
+        # `dormant: true` (issue #274) is handed to reactive_attrs: the root mounts
+        # on its first trigger instead of on page load. On a reactive_lazy
+        # component declare `reactive_dormant` on the class instead: the lazy
+        # SHELL is rendered by the framework and reads only the class declaration.
+        def reactive_root(dormant: nil, **overrides)
           # A CLIENT-ONLY component (ClientBindings, issue #180) needs no #id —
           # there's no token to self-match by id. Use an explicit override, else
           # #id when the component defines one, else nothing (no id attr).
@@ -151,7 +171,7 @@ module Phlex
           # Issue #184: dirty tracking is a class-level reactive_dirty declaration.
           dirty = self.class.reactive_dirty_config if self.class.respond_to?(:reactive_dirty_config)
 
-          attrs = mix({ **reactive_attrs }, overrides)
+          attrs = mix({ **reactive_attrs(dormant:) }, overrides)
           attrs = mix(attrs, { id: root_id }) unless root_id.nil?
           # Root-level delegation tracks the whole subtree UNLESS only: scoped it to
           # named fields (those carry their own descriptor via reactive_field).
@@ -1575,14 +1595,22 @@ module Phlex
         def apply_first_paint_hidden(attrs, groups, values_override)
           return attrs if attrs.key?(:hidden)
 
+          visible = first_paint_match(groups, values_override)
+          visible.nil? ? attrs : attrs.merge(hidden: !visible)
+        end
+
+        # The server-side evaluation of a binding's conditions for first paint
+        # (reactive_show's hidden:, reactive_enable's disabled:): true/false
+        # when reactive_values (merged under values:) covers EVERY referenced
+        # field, else nil — the client seeds it at connect.
+        def first_paint_match(groups, values_override)
           provided = show_values(values_override)
-          return attrs if provided.nil?
+          return nil if provided.nil?
 
           referenced = Phlex::Reactive::ShowConditions.fields(groups)
-          return attrs unless referenced.all? { provided.key?(it) }
+          return nil unless referenced.all? { provided.key?(it) }
 
-          visible = Phlex::Reactive::ShowConditions.match?(groups, provided)
-          attrs.merge(hidden: !visible)
+          Phlex::Reactive::ShowConditions.match?(groups, provided)
         end
 
         # The { field => current-string-value } map the first-paint evaluator
@@ -1598,7 +1626,9 @@ module Phlex
           merged = {}
           merged.merge!(base) if base
           merged.merge!(values_override) if values_override
-          merged.to_h { |name, value| [name.to_s, show_value_string(value)] }
+          # An Array (a checkbox group's checked values, issue #319) stays an
+          # Array so a checked: term can count it.
+          merged.to_h { |name, value| [name.to_s, value.is_a?(Array) ? value.map(&:to_s) : show_value_string(value)] }
         end
 
         # Stringify a reactive_values entry the way the client's #showFieldValue

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

@@ -14,9 +14,66 @@ module Phlex
       # the defer endpoint/job, the class stream builders — runs inside
       # Defer.with_real_render, so it renders the REAL template. Anything else
       # would make an action on a lazy component cost two round trips.
+      #
+      # `reactive_lazy(on:)` (issue #276) defers the REQUEST, not just the
+      # server time: the shell carries the identity token (no TTL, unlike the
+      # defer token). An event shell binds a `__materialize` trigger `once` to
+      # its event; a visibility shell has no binding — the client's
+      # IntersectionObserver starts the same `__materialize` request itself.
+      # The action endpoint routes `__materialize` to the same real render the
+      # defer endpoint does. The real render never contains the shell or its
+      # trigger, so `once` cannot re-arm.
       module Lazy
         extend ActiveSupport::Concern
 
+        # The framework-owned act the on: shell dispatches. Reserved: `action`
+        # refuses it, and the endpoint answers it only for reactive_lazy(on:).
+        MATERIALIZE_ACTION = :__materialize
+        # A DOM event name usable in a Stimulus descriptor: no key filter (.),
+        # no target (@), no descriptor syntax (->, #) — `panel:opened` is fine.
+        EVENT_NAME = /\A[A-Za-z][\w:-]*\z/
+        # An IntersectionObserver rootMargin: one to four px/% lengths.
+        # Any CSS whitespace between lengths; normalized to single spaces.
+        ROOT_MARGIN = /\A\s*-?\d+(?:\.\d+)?(?:px|%)(?:\s+-?\d+(?:\.\d+)?(?:px|%)){0,3}\s*\z/
+
+        # `on:` → { event: "x" } | { visible: "<rootMargin>" }, or raise.
+        def self.normalize_trigger(on)
+          case on
+          when String
+            return { event: on } if on.match?(EVENT_NAME)
+          when :visible
+            return { visible: "0px" }
+          when ::Hash
+            margin = on[:visible]
+            if on.keys == [:visible] && margin.is_a?(String) && margin.match?(ROOT_MARGIN)
+              return { visible: margin.split.join(" ") }
+            end
+          end
+          raise ArgumentError,
+            "reactive_lazy on: expects a DOM event name (\"panel:opened\"), :visible, or " \
+            "{ visible: \"200px\" } (a px/% rootMargin) — got #{on.inspect}"
+        end
+
+        # `cache:` → { max_age: <seconds> }, or raise. Only a whole, positive
+        # number of seconds (an Integer or an ActiveSupport::Duration) is a
+        # lifetime; the endpoint caps it at fragment_cache_max_age_limit.
+        def self.normalize_cache(cache)
+          unless cache.is_a?(::Hash) && cache.keys == [:max_age]
+            raise ArgumentError,
+              "reactive_lazy cache: expects { max_age: <seconds> } (e.g. { max_age: 10.minutes }) — got #{cache.inspect}"
+          end
+
+          max_age = cache[:max_age]
+          # Duration#to_i truncates (1.5.seconds → 1): only an exact one converts.
+          seconds = max_age.is_a?(ActiveSupport::Duration) && max_age.to_i == max_age ? max_age.to_i : max_age
+          unless seconds.is_a?(::Integer) && seconds.positive?
+            raise ArgumentError,
+              "reactive_lazy cache: max_age must be a positive whole number of seconds — got #{max_age.inspect}"
+          end
+
+          { max_age: seconds }
+        end
+
         private
 
         # Phlex 2's render hook: the template runs inside the block. Overridden
@@ -26,18 +83,92 @@ module Phlex
         def around_template(&)
           klass = self.class
           if klass.respond_to?(:reactive_lazy?) && klass.reactive_lazy? && !Phlex::Reactive::Defer.real_render?
-            render_defer_shell
+            (trigger = klass.reactive_lazy_trigger) ? render_trigger_shell(trigger) : render_defer_shell
           else
             super
           end
         end
 
+        # The on: shell (issue #276): the same placeholder contract as the
+        # defer shell (id, class, aria-busy, deferred_placeholder), but mounted
+        # like a reactive root — reactive_attrs' identity token. No defer token
+        # and no pending marker: the client's lazy probe gates on the token, so
+        # it skips this shell, and nothing is in flight until the trigger fires.
+        #
+        # The marker tells the client which shell this is, on connect AND after
+        # a Turbo morph re-shows it on a connected root (no Stimulus lifecycle):
+        #   * data-reactive-lazy-on="<event>" — plus the once-bound Stimulus
+        #     descriptor for `__materialize`, so the first event takes the
+        #     ordinary action path. The client re-arms the event itself after a
+        #     morph, because a spent `once` binding never fires again.
+        #   * data-reactive-lazy-visible="<rootMargin>" — no descriptor at all;
+        #     the client's IntersectionObserver materializes directly.
+        #
+        # A `cache:` component (issue #277) adds its fragment URL: the client
+        # then loads with a cacheable GET instead of the __materialize POST.
+        # Such a shell carries NO identity token (issue #306): every load, and
+        # the fallback for a URL the client refuses (a GET under the fragment
+        # path it knows), goes through the URL — a second signature of the same
+        # identity would only make the shell heavier than what it defers.
+        def render_trigger_shell(trigger)
+          src = fragment_src
+          root = reactive_attrs
+          root[:data].delete(:reactive_token_value) if src
+          attrs = mix(
+            { id:, class: "reactive-defer-placeholder", aria: { busy: "true" } },
+            root,
+            { data: trigger_shell_data(trigger) }
+          )
+          # Mixed in only when present: a non-cached shell allocates nothing extra.
+          attrs = mix(attrs, { data: { reactive_defer_src: src } }) if src
+          public_send(self.class.reactive_lazy_tag, **attrs) { render_deferred_placeholder_content }
+        end
+
+        # The cacheable fragment URL (issue #277) for a `cache:` component, else
+        # nil (Phlex omits a nil attribute, so a non-cached shell is unchanged).
+        # Deterministic: the same identity (+ version) renders the same URL on
+        # every page view, which is what lets the browser's HTTP cache hit.
+        def fragment_src
+          return unless self.class.reactive_lazy_cache
+
+          version = respond_to?(:reactive_cache_version, true) ? send(:reactive_cache_version) : nil
+          Phlex::Reactive::Fragment.src(reactive_identity_payload, version:, viewer: fragment_viewer_param)
+        end
+
+        # The `u` of the fragment URL: the keyed digest of reactive_cache_viewer
+        # when the component declares who its render is for AND that value names
+        # someone, else nil (the default, `Vary: Cookie` mode). The shell renders
+        # it; the endpoint recomputes it in the requesting session and compares
+        # (see FragmentsController).
+        def fragment_viewer_param
+          return unless respond_to?(:reactive_cache_viewer, true)
+
+          Phlex::Reactive::Fragment.viewer_param(send(:reactive_cache_viewer), owner: self.class)
+        end
+
+        def trigger_shell_data(trigger)
+          return { reactive_lazy_visible: trigger[:visible] } if trigger[:visible]
+
+          event = trigger[:event]
+          {
+            action: "#{event}->reactive#dispatch:once",
+            reactive_action_param: MATERIALIZE_ACTION.to_s,
+            reactive_params_param: Helpers::EMPTY_PARAMS_JSON,
+            reactive_lazy_on: event
+          }
+        end
+
         # The shell: owns the component's id (the arrival replaces it by that
         # id), mounts the generic controller, and carries the defer token as a
         # ROOT attribute — the controller's connect() probes it and enters the
         # same module-level fetch path a reply directive uses. Pending markers
         # + the .reactive-defer-placeholder class are the CSS hooks.
+        #
+        # A `cache:` component (issue #277) carries its stable fragment URL in
+        # data-reactive-defer-src INSTEAD of the token: the client GETs it, and
+        # the browser's private cache can answer.
         def render_defer_shell
+          src = fragment_src
           public_send(
             self.class.reactive_lazy_tag,
             id:,
@@ -46,6 +177,10 @@ module Phlex
             data: {
               controller: "reactive",
               reactive_defer_pending: "true",
+              # The same verbose stamp reactive_attrs writes (nil is omitted):
+              # the shell may be the page's only reactive root when its mount
+              # fetch runs, and the client's verbose gate reads it (issue #279).
+              reactive_verbose: (Phlex::Reactive.verbose_errors ? "true" : nil),
               # UNBOUND (issue #165 security): a lazy shell renders during the
               # page render — on a fresh visit the session doesn't exist yet, so
               # the token can't be actor-bound (it would 400 at the endpoint,
@@ -53,7 +188,8 @@ module Phlex
               # small leak surface); the TTL + `authorize!` are its bound. Only
               # reply.defer tokens (in action responses that can transit proxies)
               # are actor-bound.
-              reactive_defer_token: Phlex::Reactive.sign_defer(reactive_identity_payload, unbound: true)
+              reactive_defer_token: (Phlex::Reactive.sign_defer(reactive_identity_payload, unbound: true) unless src),
+              reactive_defer_src: src
             }
           ) { render_deferred_placeholder_content }
         end

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

@@ -59,6 +59,8 @@ module Phlex
           dirty: :@reactive_own_dirty,
           # Deferred reply segments — reactive_lazy (issue #165).
           lazy: :@reactive_own_lazy,
+          # Mount on first use — reactive_dormant (issue #274).
+          dormant: :@reactive_own_dormant,
           # Enter/exit/update effects — reactive_effects (issue #215).
           effects: :@reactive_own_effects,
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Bulk-selection bindings (issue #319): a list with a row checkbox per
+      # item, a "select all" header, a "Delete (n)" count, and actions that stay
+      # disabled until something is ticked — with no per-list JavaScript.
+      #
+      #   form(id: "bulk", action: "/posts/bulk", method: "post") do
+      #     input(type: "checkbox", **reactive_select_all("ids[]"))   # header
+      #     @posts.each { input(type: "checkbox", name: "ids[]", value: it.id) }
+      #     span(**reactive_count("ids[]")) { "0" }                    # ticked count
+      #     button(**reactive_enable(if: { "ids[]" => { checked: 1.. } })) { "Delete" }
+      #   end
+      #
+      # The group is a checkbox NAME, resolved like any reactive_show field
+      # (owned boxes only — a nested reactive root's boxes are its own, #15;
+      # a bare name takes reactive_scope, a bracketed one like "ids[]" is used
+      # verbatim). The client re-syncs the header, the count and every
+      # binding when a box changes and when boxes are added or removed (a
+      # stream append, a morph, a removal). All client-only: no token, no
+      # round trip.
+      module Selection
+        # The sibling of reactive_show: the same if:/if_any:/unless: conditions
+        # (including the { checked: n } count term), but it flips the
+        # element's OWN `disabled` — a button, a fieldset — instead of
+        # `hidden`. First paint is computed from reactive_values exactly like
+        # reactive_show's `hidden:` (an explicit `disabled:` wins; `values:`
+        # merges over reactive_values).
+        def reactive_enable(**options)
+          conditions = options.slice(*Helpers::SHOW_CONDITION_KEYS)
+          values_override = options.delete(:values)
+          attrs = options.except(*Helpers::SHOW_CONDITION_KEYS)
+
+          groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          result = mix({ data: { reactive_enable: { "any" => groups }.to_json } }, attrs)
+          return result if result.key?(:disabled)
+
+          match = first_paint_match(groups, values_override)
+          match.nil? ? result : result.merge(disabled: !match)
+        end
+
+        # The header box of a checkbox group. Its `change` ticks or unticks
+        # every owned box of the group (dispatching `input` + `change` on each one it
+        # flips, so computes, shows and counts re-run); its own checked /
+        # indeterminate state follows the group. Give the header NO `name` —
+        # it would post, and count as a member.
+        def reactive_select_all(group, **attrs)
+          mix({ data: { reactive_select_all: selection_group!(:reactive_select_all, group) } }, attrs)
+        end
+
+        # A text binding that shows how many owned boxes of the group are
+        # ticked (written via textContent, change-guarded). Seed the first
+        # paint in the element's own content: span(**reactive_count("ids[]")) { "0" }.
+        def reactive_count(group, **attrs)
+          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?
+
+          raise ArgumentError, "#{helper} needs a checkbox group name (e.g. \"ids[]\"), got #{group.inspect}"
+        end
+      end
+    end
+  end
+end