phlex-reactive 0.15.2 → 0.15.4

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Render-time checks for a binding that names ANOTHER field: same:
+      # (issue #395), after: (#396) and clear: (#394). The binding's attrs are
+      # built before its section's children render, so the check waits for the
+      # end of the OUTERMOST Phlex render in progress and reads the fields that
+      # render produced — a field below the binding, or inside a nested
+      # component, counts. An unknown name (or a file input named in clear:)
+      # raises ArgumentError at render, never silently in the browser.
+      #
+      # Nothing is recorded when no binding names a field, and a helper called
+      # outside a render (no buffer to read) is not checked. A fragment render
+      # (only part of the template reaches the buffer) is not checked either,
+      # nor is a render that calls `flush`. The scan accepts any element with
+      # that name, including one inside a nested reactive root the client will
+      # not read (ownership is the client's rule), so it catches typos, not
+      # misplaced fields.
+      module FieldReferences
+        REFS_KEY = :__phlex_reactive_field_refs
+
+        # A start tag and its attributes (quoted values may hold ">").
+        TAG = %r{<[a-zA-Z][\w-]*((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>]+))?)*)\s*/?>}
+        # One attribute of that list, walked in order so a "name=" inside
+        # another attribute's quoted value is never read as the name.
+        ATTR = %r{\s+([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?}
+
+        private
+
+        def around_template(&)
+          # Thread#[] is fiber-local: a nested component, or a capture inside
+          # this render, shares the outermost render's list. `true` marks a
+          # render in progress with nothing recorded yet, so a render without
+          # such a binding allocates nothing here.
+          return super if Thread.current[REFS_KEY] || !defined?(@_state) || @_state.nil?
+
+          buffer = @_state.buffer
+          start = buffer.bytesize
+          Thread.current[REFS_KEY] = true
+          begin
+            super
+            refs = Thread.current[REFS_KEY]
+          ensure
+            Thread.current[REFS_KEY] = nil
+          end
+          check_field_references!(refs, buffer.byteslice(start..)) if refs.is_a?(Array) && !@_state.fragments
+        end
+
+        public
+
+        # A flush moves the buffer out mid-render, so the end-of-render scan
+        # would miss fields above it: record the references as unchecked.
+        def flush
+          Thread.current[REFS_KEY] = :flushed if Thread.current[REFS_KEY]
+          super
+        end
+
+        private
+
+        # Record a binding's field references for the end-of-render check.
+        # `names` are bare show names (scope-aware, like the client resolver);
+        # `no_file` refuses a file input under the name.
+        def reference_fields!(helper, key, names, no_file: false)
+          refs = Thread.current[REFS_KEY]
+          return unless refs
+
+          return if refs == :flushed
+
+          refs = Thread.current[REFS_KEY] = [] if refs == true
+          names.each { refs << [helper, key, it, field_wire_name(it), no_file] }
+        end
+
+        # Every same: name in a binding's compiled groups (issue #395).
+        def reference_same_fields!(helper, groups)
+          names = groups.flatten.filter_map { it["same"] }
+          reference_fields!(helper, :same, names.uniq) if names.any?
+        end
+
+        # The name the client's resolver queries: scope[name] under
+        # reactive_scope, a bracketed name (an author's raw wire name) verbatim.
+        def field_wire_name(name)
+          name.include?("[") ? name : scoped_field_name(name)
+        end
+
+        def check_field_references!(refs, html)
+          names, files = rendered_fields(html)
+          refs.each do |helper, key, name, wire, no_file|
+            unless names.include?(wire)
+              raise ArgumentError,
+                "#{helper} #{key}: #{name.to_sym.inspect} names no field this render produced " \
+                "(no element with name=\"#{wire}\")"
+            end
+            next unless no_file && files.include?(wire)
+
+            raise ArgumentError,
+              "#{helper} #{key}: #{name.to_sym.inspect} is a file input — a file field cannot be cleared"
+          end
+        end
+
+        # The name of every element the HTML renders, and those that are
+        # file inputs.
+        def rendered_fields(html)
+          names = Set.new
+          files = Set.new
+          html.scan(TAG) do
+            attrs = tag_attributes(Regexp.last_match(1).to_s)
+            next unless (name = attrs["name"])
+
+            names << name
+            files << name if attrs["type"]&.casecmp?("file")
+          end
+          [names, files]
+        end
+
+        # A tag's attributes by lowercased name (HTML attribute names are
+        # case-insensitive); the first occurrence wins, as in the browser.
+        def tag_attributes(text)
+          attrs = {}
+          text.scan(ATTR) do |key, double, single, bare|
+            value = double || single || bare
+            attrs[key.downcase] ||= value.nil? ? "" : CGI.unescapeHTML(value)
+          end
+          attrs
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,10 @@ module Phlex
         include Sortable
         include Editable
         include MediaBinding
+        include ImageFallbackBinding
+        include CountdownBinding
+        include FieldReferences
+        include ShowOptions
 
         # 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).
@@ -386,11 +390,7 @@ module Phlex
               "(declared: #{actions.keys.inspect})"
           end
 
-          if debounce && throttle
-            raise ArgumentError,
-              "on(#{action_name.inspect}) got both debounce: and throttle: — they are mutually " \
-              "exclusive (debounce is trailing-edge, throttle is leading-edge); pick one"
-          end
+          raise ArgumentError, both_waits_message("on(#{action_name.inspect})") if debounce && throttle
 
           # Guarded here, not inside: building the caller label allocates (on() is a hot path).
           shortcut = shortcut_for!("on(#{action_name.inspect})", shortcut, event:, window:, outside:) unless shortcut.nil?
@@ -467,6 +467,13 @@ module Phlex
         # no-op (no confirm, no preventDefault). Not Turbo-specific: any
         # CustomEvent whose detail carries a flag works.
         #
+        # Issue #393: `debounce:` (trailing edge) and `throttle:` (leading edge)
+        # wait the way on()'s do — non-negative Integer milliseconds, never both,
+        # on the same client timers (a blur flushes a pending debounce). once:
+        # still means one run, after the wait:
+        #   input(**on_client(:input, js.submit("#search"), debounce: 300))
+        #   div(**on_client(:scroll, js.add_class("#bar", "stuck"), window: true, throttle: 250))
+        #
         # 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
@@ -476,7 +483,7 @@ module Phlex
         # 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, detail: nil,
-                      shortcut: nil)
+                      shortcut: nil, debounce: nil, throttle: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -496,6 +503,7 @@ module Phlex
           shortcut = client_shortcut!(event, shortcut, window:, outside:)
           window_bound = window || outside || !shortcut.nil?
           record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
+          client_binding_wait!(record, event, debounce, throttle) unless debounce.nil? && throttle.nil?
           # The record's `on` stays the bare keydown: the client reads a key
           # filter from `on`, and `mod` is not a key.
           record["shortcut"] = shortcut.param if shortcut
@@ -673,13 +681,19 @@ module Phlex
           conditions = options.slice(*SHOW_CONDITION_KEYS)
           disable = options.delete(:disable)
           values_override = options.delete(:values)
-          attrs = options.except(*SHOW_CONDITION_KEYS)
+          after, clear, focus, scroll = options.values_at(:after, :clear, :focus, :scroll)
+          attrs = options.except(*SHOW_CONDITION_KEYS, *SHOW_OPTION_KEYS)
 
           groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          reference_same_fields!(:reactive_show, groups)
           data = { reactive_show: { "any" => groups }.to_json }
           data[:reactive_show_disable] = "true" if disable
+          data.merge!(show_option_data(groups, after:, clear:, focus:, scroll:))
 
           result = mix({ data: }, attrs)
+          # after: — the server never saw a blur, so the section starts hidden.
+          return result.key?(:hidden) ? result : result.merge(hidden: true) unless after.nil?
+
           apply_first_paint_hidden(result, groups, values_override)
         end
 
@@ -1182,10 +1196,11 @@ module Phlex
           { data: { reactive_show_targets: normalized.to_json } }
         end
 
-        # Client-only localStorage draft over the fields this root OWNS (issue
-        # #239) — "don't make me start over". Spread on the ROOT (mix with
+        # Client-only browser-storage draft over the fields this root OWNS
+        # (issue #239) — "don't make me start over". Spread on the ROOT (mix with
         # reactive_root, like reactive_show_targets); the generic controller
-        # then writes every owned control's value to localStorage as the user
+        # then writes every owned control's value to the selected store
+        # (localStorage, or sessionStorage with `storage: :session`) as the user
         # types (debounced on `input`, immediate on `change`, flushed on
         # disconnect), restores the draft on the NEXT connect, and forgets it
         # when the owning form submits successfully (turbo:submit-end), when
@@ -1214,14 +1229,22 @@ module Phlex
         # control the server rendered BLANK, so a 422 re-render's submitted
         # values win over an older draft; `:always` lets the draft win.
         #
+        # `storage:` — `:local` (default) keeps the draft in localStorage,
+        # shared by every tab and outliving them; `:session` (issue #397) keeps
+        # it in sessionStorage: this tab only, restored on reload, gone when
+        # the tab closes (a tab opened from it with an opener, or duplicated,
+        # starts with the browser's one-time copy of the session store). A
+        # string of the same word is accepted. Each store is
+        # read on its own: a `:local` draft is never restored by `:session`.
+        #
         # Same posture as reactive_show: no token, no POST, no expression
         # surface. Stored values are plain user input replayed via
         # .value/.checked (never HTML) — a tampered draft can only fill what
-        # the user could type. PII sits in localStorage for `ttl`; the
-        # successful-submit clear and `ttl` are the shared-computer mitigation
-        # (see docs/security). ONE call per root — Phlex `mix` space-joins
+        # the user could type. PII sits in the selected store for `ttl`; the
+        # successful-submit clear, `ttl` and `storage: :session` are the
+        # shared-computer mitigation (see docs/security). ONE call per root — Phlex `mix` space-joins
         # duplicate string data values, so a second call would corrupt the JSON.
-        def reactive_persist(key:, ttl: 7.days, fields: nil, restore: :blank, debounce: 300)
+        def reactive_persist(key:, ttl: 7.days, fields: nil, restore: :blank, debounce: 300, storage: :local)
           payload = {
             "key" => validate_persist_key!(key),
             "ttl" => validate_persist_ttl!(ttl),
@@ -1229,6 +1252,7 @@ module Phlex
           }
           payload["restore"] = "always" if validate_persist_restore!(restore) == :always
           payload["fields"] = validate_persist_fields!(fields) if fields
+          payload["storage"] = "session" if validate_persist_storage!(storage) == :session
 
           { data: { reactive_persist: payload.to_json } }
         end
@@ -1265,6 +1289,16 @@ module Phlex
           raise ArgumentError, "reactive_persist restore: must be :blank or :always, got #{restore.inspect}"
         end
 
+        PERSIST_STORAGES = %w[local session].freeze
+        private_constant :PERSIST_STORAGES
+
+        def validate_persist_storage!(storage)
+          name = storage.to_s if storage.is_a?(Symbol) || storage.is_a?(String)
+          return name.to_sym if PERSIST_STORAGES.include?(name)
+
+          raise ArgumentError, "reactive_persist storage: must be :local or :session, got #{storage.inspect}"
+        end
+
         def validate_persist_fields!(fields)
           list = Array(fields)
           raise ArgumentError, "reactive_persist fields: needs at least one field name" if list.empty?
@@ -1378,6 +1412,10 @@ module Phlex
         # vocabulary; there are no predicate kwargs any more.
         SHOW_CONDITION_KEYS = %i[if if_any unless].freeze
 
+        # reactive_show's own keywords beyond disable:/values: (ShowOptions):
+        # the after: blur gate (#396) and the visibility transitions (#394).
+        SHOW_OPTION_KEYS = %i[after clear focus scroll].freeze
+
         # The removed 0.9.5 surface (issue #180 clean break): each of these
         # kwargs — and a positional field — now raises a GUIDED error printing
         # the if:/if_any:/unless: rewrite. Kept only to detect the legacy call
@@ -1513,6 +1551,27 @@ module Phlex
           record
         end
 
+        # Issue #393: the one message on() and on_client() raise when given both
+        # waits. Built only on that error path (on() is a hot path).
+        def both_waits_message(label)
+          "#{label} got both debounce: and throttle: — they are mutually exclusive " \
+            "(debounce is trailing-edge, throttle is leading-edge); pick one"
+        end
+
+        # Issue #393: on_client's debounce:/throttle: ride on the binding record,
+        # validated loud at render (non-negative Integer ms, never both).
+        def client_binding_wait!(record, event, debounce, throttle)
+          label = "on_client(#{event.inspect})"
+          raise ArgumentError, both_waits_message(label) if debounce && throttle
+
+          key, ms = debounce.nil? ? ["throttle", throttle] : ["debounce", debounce]
+          unless ms.is_a?(Integer) && !ms.negative?
+            raise ArgumentError, "#{label} #{key}: must be a non-negative Integer (ms), got #{ms.inspect}"
+          end
+
+          record[key] = ms
+        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.
@@ -1766,13 +1825,16 @@ module Phlex
 
         private_constant :REMOVED_ON_KWARGS, :PENDING_CLASS_OPS
 
+        # Runs on every on() (a hot path): a key lookup per removed name, no arrays.
         def reject_removed_on_kwargs!(action_name, params)
-          removed = params.keys & REMOVED_ON_KWARGS.keys
-          return if removed.empty?
+          return if params.empty?
 
-          key = removed.first
-          raise ArgumentError,
-            "on(#{action_name.inspect}) #{key}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[key]}"
+          REMOVED_ON_KWARGS.each_key do
+            next unless params.key?(it)
+
+            raise ArgumentError,
+              "on(#{action_name.inspect}) #{it}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[it]}"
+          end
         end
 
         # Issue #357: parse on()'s shortcut: (nil when absent). A shortcut

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

@@ -18,6 +18,16 @@ module Phlex
       module Identity
         extend ActiveSupport::Concern
 
+        # Whether the installed GlobalID gives a class its own app
+        # (global_id_app, then GlobalID.app — rails/globalid after 1.4).
+        # Read once: it is a fact about the loaded gem.
+        def self.per_class_gid_app?
+          return @per_class_gid_app if defined?(@per_class_gid_app)
+
+          @per_class_gid_app = ::GlobalID::Identification.const_defined?(:ClassMethods, false) &&
+                               ::GlobalID::Identification::ClassMethods.method_defined?(:global_id_app)
+        end
+
         class_methods do
           # The record's instance-variable symbol (e.g. :@todo), computed once.
           # reactive_token reads it on every render; interpolating :"@#{key}" each
@@ -74,7 +84,7 @@ module Phlex
           # before to_gid (nil.to_gid would raise).
           if (record_ivar = klass.reactive_record_ivar) &&
              (record = instance_variable_get(record_ivar)) && signable_gid?(record)
-            payload["gid"] = record.to_gid.to_s
+            payload["gid"] = reactive_gid(record)
           end
 
           state_ivars = klass.reactive_state_ivars
@@ -95,6 +105,29 @@ module Phlex
         def signable_gid?(record)
           !(record.respond_to?(:persisted?) && !record.persisted?)
         end
+
+        # record.to_gid.to_s, without the URI. For a record whose to_gid is
+        # GlobalID's own (not overridden on its class or on itself) and whose
+        # id is an Integer, GlobalID's string is exactly
+        # "gid://<GlobalID.app>/<class name>/<id>": an Integer needs no
+        # escaping and there are no params. Building it directly skips a
+        # validated URI::GID (~37 objects, about half a record token's cost),
+        # once per record-backed row per render. Anything else goes through
+        # to_gid unchanged, its errors included.
+        def reactive_gid(record)
+          if record.is_a?(::GlobalID::Identification) &&
+             record.method(:to_gid).owner.equal?(::GlobalID::Identification) &&
+             (id = record.id).is_a?(Integer) && (app = reactive_gid_app(record.class)) && (name = record.class.name)
+            "gid://#{app}/#{name}/#{id}"
+          else
+            record.to_gid.to_s
+          end
+        end
+
+        # The app to_gid would use: the class's own where GlobalID has one.
+        def reactive_gid_app(klass)
+          (Identity.per_class_gid_app? && klass.global_id_app) || ::GlobalID.app
+        end
       end
     end
   end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # An <img> that falls back when its src fails and recovers when the src
+      # changes (issue #383).
+      #
+      #   img(id: "logo", alt: "", **reactive_image_fallback(hide: true))
+      #   img(id: "logo", alt: "Bank", **reactive_image_fallback(show_alt: "#bank-name"))
+      #   span(id: "bank-name", hidden: true)
+      #
+      # On `error` the client sets data-reactive-image-state="error", adds
+      # `hidden` (hide: true, the default) and, with show_alt:, writes the
+      # img's alt into that node (a CSS selector inside the root) and shows it.
+      # On `load` the state is "loaded". A later src — copy_media,
+      # reactive_media, preview_file, a morph, or any src that loads — clears
+      # the error and shows the img again; an img with no src is never an
+      # error. hide: false leaves visibility alone: style the state with CSS.
+      # Composes with reactive_media (its **attrs mix the data attribute in):
+      #
+      #   img(**reactive_media(from: :rib, pool: POOL, **reactive_image_fallback))
+      #
+      #
+      # wrap: (issue #392) names the box around the img (a CSS selector inside
+      # the root, like show_alt:). On error the client hides it and marks the
+      # hide as its own (data-reactive-wrap-hidden); recovery shows it again
+      # only when that mark is there, so a wrapper the author hid stays
+      # hidden. The wrapper may hold the img: its text is never written.
+      # hide: false with wrap: hides the wrapper only.
+      #
+      #   span(id: "badge", class: "rounded-full p-1") do
+      #     img(id: "logo", alt: "", **reactive_image_fallback(hide: false, wrap: "#badge"))
+      #   end
+      #
+      # Named ImageFallbackBinding for the reason MediaBinding is (issue #233).
+      module ImageFallbackBinding
+        def reactive_image_fallback(hide: true, show_alt: nil, wrap: nil, **attrs)
+          wire = { "hide" => image_fallback_hide!(hide) }
+          wire["alt"] = image_fallback_selector!(:show_alt, show_alt, "#bank-name") unless show_alt.nil?
+          wire["wrap"] = image_fallback_selector!(:wrap, wrap, "#badge") unless wrap.nil?
+          mix({ data: { reactive_image_fallback: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def image_fallback_hide!(hide)
+          return hide if [true, false].include?(hide)
+
+          raise ArgumentError, "reactive_image_fallback hide: must be true or false, got #{hide.inspect}"
+        end
+
+        # A selector the client passes to querySelector, never a URL.
+        def image_fallback_selector!(key, selector, example)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_image_fallback #{key}: #{selector} names the whole root — pass the selector of a node inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_image_fallback #{key}: must be a CSS selector (e.g. \"#{example}\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -20,18 +20,37 @@ module Phlex
       # first n characters as the key; omit it to use the whole value. A pool
       # value is a CSS SELECTOR for an <img> inside the root, never a URL: the
       # client copies that element's src, srcset and alt the way
-      # js.copy_media does. A key, selector or element that misses clears the
-      # preview. `label:` names a node whose textContent becomes the chosen
-      # image's alt (`blank_label`, or "", on a miss). Client-only: no token,
+      # js.copy_media does. A key, selector or element that misses (or is not
+      # an <img>) clears the preview. A pool <img> with an alt and no src is a
+      # hit without an image: the preview drops its src and takes the alt
+      # (issue #381). `label:` names a node whose textContent becomes the
+      # chosen image's alt (`blank_label`, or "", on a miss). Client-only: no token,
       # no round trip.
       #
+      # Until the field has `take` characters, or while `match:` (a Regexp,
+      # anchored to the whole key) rejects the key, the binding is PENDING
+      # (issue #380): never `blank_label`. `pending: :clear` (the default)
+      # clears the preview and empties the label; `pending: :keep` leaves both
+      # alone. The preview's data-reactive-media-state reads pending, hit or
+      # miss, so a row can hide itself with CSS until there is an answer.
+      #
+      # `when:` (a Regexp, anchored to the WHOLE field value, issue #390) is
+      # tested before the pool lookup while the key stays the `take` prefix: a
+      # value it rejects is pending too ("007bad" never hits "007"). It follows
+      # match:'s MediaPattern rules; match: still tests the key only.
+      #
       # Named MediaBinding, not Media: this module sits in every reactive
       # component's ancestry, and a bare `Media` would shadow a host app's kit
       # component of that name (issue #233).
       module MediaBinding
-        def reactive_media(from:, pool: nil, take: nil, label: nil, blank_label: nil, **attrs)
+        def reactive_media(from:, pool: nil, take: nil, match: nil, when: nil, pending: :clear, label: nil,
+                           blank_label: nil, **attrs)
+          whole = binding.local_variable_get(:when)
           wire = { "field" => media_field!(from) }
           wire["take"] = media_take!(take) unless take.nil?
+          wire["match"] = MediaPattern.to_js(match) unless match.nil?
+          wire["when"] = MediaPattern.to_js(whole, :when) unless whole.nil?
+          wire["pending"] = "keep" if media_pending!(pending) == "keep"
           wire["pool"] = media_pool!(pool)
           wire["label"] = media_selector!(:label, label) unless label.nil?
           wire["blank"] = blank_label.to_s unless blank_label.nil?
@@ -54,6 +73,13 @@ module Phlex
                                "got #{take.inspect}"
         end
 
+        def media_pending!(pending)
+          mode = pending.to_s if pending.is_a?(Symbol) || pending.is_a?(String)
+          return mode if %w[clear keep].include?(mode)
+
+          raise ArgumentError, "reactive_media pending: must be :clear or :keep, got #{pending.inspect}"
+        end
+
         def media_pool!(pool)
           if pool.nil?
             raise ArgumentError, "reactive_media needs pool: — a Hash of key => selector of a server-rendered <img> " \

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # reactive_media's match: (issue #380) and when: (issue #390) — a Ruby
+      # Regexp as the JavaScript source the client anchors as ^(?:…)$ and
+      # compiles without flags. Errors name the keyword. The source is tokenized (an escape is one token, so an escaped backslash is
+      # never mistaken for one): a leading \A and a trailing \z/\Z are dropped,
+      # and anything JavaScript would read differently raises at render rather
+      # than matching silently wrong in the browser.
+      module MediaPattern
+        # Escapes Ruby reads as an anchor or a class and JS reads as a letter,
+        # plus \s/\S, whose JS class also holds Unicode spaces Ruby's does not.
+        RUBY_ONLY_ESCAPES = %w[\A \z \Z \G \h \H \R \X \K \p \P \s \S].freeze
+        # The group openers both engines read alike: (?: (?= (?! (?<= (?<! (?<name>
+        SHARED_GROUPS = [":", "=", "!", "<"].freeze
+        OPTIONS = Regexp::IGNORECASE | Regexp::EXTENDED | Regexp::MULTILINE
+
+        module_function
+
+        def to_js(match, name = :match)
+          unless match.is_a?(Regexp)
+            raise ArgumentError,
+              "reactive_media #{name}: must be a Regexp (e.g. /\\A\\d{3}\\z/), got #{match.inspect}"
+          end
+
+          unless match.options.nobits?(OPTIONS)
+            refuse!(name, match,
+              "has options (i, m, x) the client would read differently — drop them")
+          end
+
+          tokens = match.source.scan(/\\.|./m)
+          tokens.shift if tokens.first == "\\A"
+          final = tokens.pop if %w[\z \Z].include?(tokens.last)
+          check!(tokens, match, name)
+          # Ruby's \Z also matches before one final newline.
+          final == "\\Z" ? "#{tokens.join}\\n?" : tokens.join
+        end
+
+        def check!(tokens, match, name)
+          in_class = false
+          tokens.each_with_index do |token, i|
+            if RUBY_ONLY_ESCAPES.include?(token)
+              refuse!(name, match,
+                "uses #{token}, which is Ruby-only (JavaScript reads it differently)")
+            end
+            refuse!(name, match, "has a character above U+FFFF (the client pattern has no u flag)") if token.ord > 0xFFFF
+            if token == "\\u" && tokens[i + 1] == "{"
+              refuse!(name, match,
+                "uses \\u{…}, which JavaScript without the u flag reads as a repeated u")
+            end
+            if in_class
+              in_class = false if token == "]"
+              class_syntax!(tokens, i, match, name)
+            elsif token == "["
+              in_class = true
+            elsif token == "(" && tokens[i + 1] == "?" && !SHARED_GROUPS.include?(tokens[i + 2])
+              refuse!(name, match, "uses (?#{tokens[i + 2]}…), a group JavaScript does not read the same way")
+            end
+          end
+        end
+
+        # A [ inside a class (a nested class or a POSIX [:digit:]) and && (an
+        # intersection) are Ruby-only: JavaScript reads them as literals.
+        def class_syntax!(tokens, index, match, name)
+          token = tokens[index]
+          return unless token == "[" || (token == "&" && tokens[index + 1] == "&")
+
+          refuse!(name, match, "has a nested character class, a POSIX [:class:] or && — JavaScript reads them literally")
+        end
+
+        def refuse!(name, match, why)
+          raise ArgumentError, "reactive_media #{name}: #{match.inspect} #{why}"
+        end
+      end
+    end
+  end
+end

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

@@ -34,6 +34,7 @@ module Phlex
           attrs = options.except(*Helpers::SHOW_CONDITION_KEYS)
 
           groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          reference_same_fields!(:reactive_enable, groups)
           result = mix({ data: { reactive_enable: { "any" => groups }.to_json } }, attrs)
           return result if result.key?(:disabled)
 
@@ -46,8 +47,21 @@ module Phlex
         # 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)
+        #
+        # Nested groups (issue #398): under: "library.books" is a GROUP PATH.
+        # The header then owns only the boxes of the name whose
+        # data-reactive-group is that path or below it ("library.books.view"),
+        # so every leaf still posts under ONE name while a tree of headers
+        # ticks, unticks and goes indeterminate per branch. A header with no
+        # under: is the whole name, as before.
+        #
+        #   input(type: "checkbox", **reactive_select_all("perms[]"))                    # everything
+        #   input(type: "checkbox", **reactive_select_all("perms[]", under: "library"))  # a branch
+        #   input(type: "checkbox", name: "perms[]", value: "books", data: { reactive_group: "library" })
+        def reactive_select_all(group, under: nil, **attrs)
+          data = { reactive_select_all: selection_group!(:reactive_select_all, group) }
+          data[:reactive_select_all_under] = selection_path!(group, under) unless under.nil?
+          mix({ data: }, attrs)
         end
 
         # A text binding that shows how many owned boxes of the group are
@@ -176,6 +190,14 @@ module Phlex
           { "any" => Phlex::Reactive::ShowConditions.normalize(**conditions) }
         end
 
+        def selection_path!(group, under)
+          path = under.to_s
+          return path unless path.strip.empty? || path.split(".", -1).any? { it.empty? || it != it.strip }
+
+          raise ArgumentError, "reactive_select_all(#{group.to_s.inspect}) under: needs a group path like " \
+                               "\"library\" or \"library.books\" (no empty or space-padded segment), got #{under.inspect}"
+        end
+
         def selection_group!(helper, group)
           name = group.to_s
           return name unless name.strip.empty?