phlex-reactive 0.10.0 → 0.11.0

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

@@ -53,6 +53,8 @@ module Phlex
           record_key: :@reactive_own_record_key,
           # Form-field namespace — reactive_scope (issue #180).
           scope: :@reactive_own_scope,
+          # Dirty-tracking config — reactive_dirty (issue #184).
+          dirty: :@reactive_own_dirty,
           # Deferred reply segments — reactive_lazy (issue #165).
           lazy: :@reactive_own_lazy,
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the
@@ -124,7 +126,10 @@ module Phlex
             fetch(klass, kind) do
               inherited = inherited_value(klass, reader)
               own = own(klass, kind)
-              (inherited || EMPTY_HASH).merge(own || EMPTY_HASH)
+              # FROZEN (issue #186): the resolved hash is the public dispatch table
+              # (reactive_actions[:x] is the default-deny source of truth) — handing
+              # out a mutable memo would let a caller corrupt it. Mutation raises.
+              (inherited || EMPTY_HASH).merge(own || EMPTY_HASH).freeze
             end
           end
 

data/lib/phlex/reactive/component.rb

@@ -6,9 +6,9 @@ module Phlex
     # reactive unit: declare actions in Ruby, and the generic `reactive`
     # Stimulus controller wires clicks/inputs to an HTTP round trip that
     # re-renders the component and applies it back into the DOM (a plain replace
-    # by default; return Response.morph(self) to morph in place and keep the
-    # focused input — issue #28). No per-feature Stimulus controllers, no
-    # hand-picked Turbo targets.
+    # by default; return reply.morph to morph in place and keep the focused
+    # input — issue #28). No per-feature Stimulus controllers, no hand-picked
+    # Turbo targets.
     #
     # Including Component pulls in Phlex::Reactive::Streamable automatically
     # (Concern dependency — Streamable lands on the base first, exactly the old

data/lib/phlex/reactive/defer.rb

@@ -309,7 +309,7 @@ data-reactive-defer-pending="true" aria-busy="true">#{inner}</div>)
         end
 
         # Resolve the segment's placeholder to inner HTML — nil means "no
-        # shell". Same content contract as flash/also_update: a Phlex component
+        # shell". Same content contract as flash/also: a Phlex component
         # renders through the configured renderer (auto-escaped), a plain
         # String is DATA and gets escaped, an html_safe String is intentional
         # markup and passes verbatim (ERB::Util.html_escape's own contract).

data/lib/phlex/reactive/deferred_render_job.rb

@@ -32,7 +32,7 @@ module Phlex
         # — it raises loudly and broadcasts NOTHING, OUTSIDE the render rescue
         # below (a component with actions can't be forged past the signed
         # identity anyway, so this never fires for a real defer).
-        unless klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+        unless klass.respond_to?(:reactive_actions) && klass.include?(Phlex::Reactive::Component)
           raise ::ArgumentError,
             "#{component_class_name} is not a reactive component — refusing the deferred render"
         end
@@ -57,7 +57,7 @@ module Phlex
         component = klass.from_identity(payload)
         return broadcast_cleanup(stream_key, target) if component.respond_to?(:render?) && !component.render?
 
-        stream = morph ? component.to_stream_morph : component.to_stream_replace
+        stream = component.to_stream_replace(morph:)
         broadcast_payload(stream_key, stream.to_s + teardown_stream(target))
       rescue ::StandardError => e
         log_deferred_failure(e) unless e.is_a?(::ActiveRecord::RecordNotFound)

data/lib/phlex/reactive/engine.rb

@@ -35,6 +35,8 @@ module Phlex
             phlex/reactive/reactive_controller.min.js.map
             phlex/reactive/confirm.min.js
             phlex/reactive/confirm.min.js.map
+            phlex/reactive/confirm_predicate.min.js
+            phlex/reactive/confirm_predicate.min.js.map
             phlex/reactive/compute.min.js
             phlex/reactive/compute.min.js.map
             phlex/reactive/inspect.min.js
@@ -76,6 +78,16 @@ module Phlex
             to: "phlex/reactive/compute.min.js",
             preload: true
           )
+          # The client-side confirm-predicate registry (issue #179) — the
+          # multi-field escape hatch for conditional confirmation. Same bare-specifier
+          # rationale as confirm/compute: reactive_controller.js imports it, and an app
+          # registers predicates via `import { setConfirmPredicate } from
+          # "phlex/reactive/confirm_predicate"` — both resolve through this pin.
+          it.importmap.pin(
+            "phlex/reactive/confirm_predicate",
+            to: "phlex/reactive/confirm_predicate.min.js",
+            preload: true
+          )
           # The on-demand client inspector (issue #168). NOT preloaded — it is a
           # dev/debugging tool loaded only when you `import("phlex/reactive/inspect")`
           # from the console, so no page pays for it. The pin makes that dynamic
@@ -116,6 +128,8 @@ module Phlex
         # frozen registry makes runtime registration a loud error rather than a
         # never-validated type. Idempotent.
         Phlex::Reactive.freeze_param_types!
+        # Freeze the named-schema registry the same way (issue #184).
+        Phlex::Reactive.freeze_param_schemas!
       end
     end
   end

data/lib/phlex/reactive/js.rb

@@ -54,6 +54,19 @@ module Phlex
       # gets the SAME server-side default-deny as the JS chain (defense in depth;
       # the client also enforces it). Non-attr ops and malformed entries pass
       # through untouched — the client interpreter default-denies unknown ops.
+      # :root -> the sentinel; a String passes through as a CSS selector. Shared
+      # by the js op builder AND the on() pending-state hint normalizer (issue
+      # #181) so BOTH resolve a `to:` target through one code path. Anything else
+      # (a stray symbol, nil) is a bug at the call site — raise at render time
+      # instead of silently matching nothing in the browser.
+      def self.normalize_target(to)
+        return ROOT_SENTINEL if to == :root
+        return to if to.is_a?(String)
+
+        raise ArgumentError,
+          "target must be :root or a CSS selector string, got #{to.inspect}"
+      end
+
       def self.assert_ops_allowed!(list)
         Array(list).each do |op, args|
           next unless ATTR_NAME_OPS.include?(op.to_s) && args.is_a?(::Hash)
@@ -227,15 +240,23 @@ module Phlex
         self.class.assert_allowed_attr(name)
       end
 
-      # A transition must be exactly [during, from, to] class lists (strings).
+      # A transition is NAMED legs { during:, from:, to: } (issue #186), compiled to
+      # the [during, from, to] wire array (zero client change). The old positional
+      # Array form is removed — it raises with the caller's OWN values slotted into
+      # the named form, so the rewrite is copy-pasteable.
       def normalize_transition(transition)
-        list = Array(transition)
-        unless list.size == 3
+        if transition.is_a?(Array)
+          d, f, t = transition
           raise ArgumentError,
-            "#{self.class}: transition: must be [during, from, to] class lists, got #{transition.inspect}"
+            "#{self.class}: transition: takes named legs (issue #186) — " \
+            "transition: { during: #{d.inspect}, from: #{f.inspect}, to: #{t.inspect} }"
+        end
+        unless transition.is_a?(Hash) && %i[during from to].all? { transition.key?(it) }
+          raise ArgumentError,
+            "#{self.class}: transition: must name during:, from:, to: class lists, got #{transition.inspect}"
         end
 
-        list.map(&:to_s).freeze
+        [transition[:during], transition[:from], transition[:to]].map(&:to_s).freeze
       end
 
       def class_args(to, classes, global:)
@@ -248,16 +269,9 @@ module Phlex
         args.freeze
       end
 
-      # :root -> the sentinel; a String passes through as a CSS selector.
-      # Anything else (a stray symbol, nil) is a bug at the call site — raise at
-      # render time instead of silently matching nothing in the browser.
-      def normalize_target(to)
-        return ROOT_SENTINEL if to == :root
-        return to if to.is_a?(String)
-
-        raise ArgumentError,
-          "#{self.class}: target must be :root or a CSS selector string, got #{to.inspect}"
-      end
+      # Instance-side alias for the class method (used by the op builder). See
+      # JS.normalize_target — the shared :root/selector translation.
+      def normalize_target(to) = self.class.normalize_target(to)
     end
   end
 end

data/lib/phlex/reactive/reply.rb

@@ -2,35 +2,25 @@
 
 module Phlex
   module Reactive
-    # A component-bound facade over Response — the surface an action body uses to
-    # control its reply. Component#reply returns one, so an action writes
+    # The ONE door for building an action's reply (issue #182). Component#reply
+    # returns one, so an action writes
     #
     #   reply.replace.flash(:error, msg)
     #
-    # instead of
+    # There is no constant to qualify (reply is a method, resolved on the
+    # component — so a namespaced component needs no `Response = …` alias) and no
+    # `self` to thread (the component is bound).
     #
-    #   Phlex::Reactive::Response.replace(self).flash(:error, msg)
+    # Reply is NOT a Response and does NOT subclass one: each verb calls the
+    # Response `build_*` class method, supplying the bound component as the
+    # subject, and returns the real, frozen Response value the endpoint honors. So
+    # immutability, chaining (.flash/.stream/.also/.js/.defer), and render_self?
+    # come from the Response value object untouched — the chain is plain Response
+    # all the way down.
     #
-    # Two warts disappear: there is no constant to qualify (reply is a method,
-    # resolved on the component — so a namespaced component needs no
-    # `Response = …` alias) and no `self` to thread (the component is bound).
-    #
-    # Reply is NOT a Response and does NOT subclass one: each verb forwards to
-    # the Response class method, supplying the bound component as the subject, and
-    # returns the real, frozen Response value the endpoint already honors. So
-    # immutability, chaining (.flash/.stream/.also_update/.also_replace), and
-    # render_self? are inherited untouched — and there is no "verb after a chained
-    # Response" asymmetry, because the chain is plain Response all the way down.
-    #
-    # Response remains the public value object (it's what the endpoint reads); it
-    # is simply an internal detail you rarely name directly now.
+    # Response remains the value object the endpoint reads; you never construct it
+    # directly (its former public class verbs raise a guided rewrite).
     class Reply
-      # Distinguishes `reply.remove` (no args — remove the bound component
-      # itself) from `reply.remove(:items, model)` (remove a collection row).
-      # A sentinel, not nil, so `reply.remove(:items, nil)` stays unambiguous.
-      UNSET = Object.new
-      private_constant :UNSET
-
       def initialize(component)
         @component = component
       end
@@ -40,70 +30,86 @@ module Phlex
       # Re-render in place. `morph: true` morphs the subtree (preserves the
       # focused input + caret) instead of an outerHTML swap — see #morph.
       def replace(morph: false)
-        Response.replace(@component, morph:)
+        Response.build_replace(@component, morph:)
       end
 
       # Re-render in place via Idiomorph (method="morph") — keeps focus + caret.
       def morph
-        Response.morph(@component)
+        Response.build_morph(@component)
       end
 
       # Update only inner HTML (preserves the root element + its token attr).
       # `morph: true` morphs the inner HTML in place (issue #113) so a
       # cross-tab/per-field update keeps a focused input's caret.
       def update(morph: false)
-        Response.update(@component, morph:)
+        Response.build_update(@component, morph:)
       end
 
       # Reactive collections (issue #35) — add/remove a row in a declared
       # reactive_collection, emitting the row stream + the count companion +
       # the empty-state toggle as ONE Response. The bound component is the
-      # container (it carries the declaration + size resolver).
+      # container (it carries the declaration + size resolver). The collection is
+      # named by the `to:`/`from:` keyword (issue #182 — reads as Ruby, and a
+      # `to:` present unambiguously means "a collection row"):
       #
-      #   def add_item(...)    = (item = @list.items.create!(...); reply.append(:items, item))
-      #   def remove_item(id:) = (@list.items.find(id).destroy!;   reply.remove(:items, id))
+      #   def add_item(...)    = (item = @list.items.create!(...); reply.append(item, to: :items))
+      #   def remove_item(id:) = (@list.items.find(id).destroy!;   reply.remove(id, from: :items))
       #
       # `model` is the row's record; remove also accepts the row's dom-id string.
-      def append(name, model)
-        Response.collection_append(@component, name, model)
+      # Extra kwargs (issue #186) thread to the row component's new(model:, **row_kwargs)
+      # — e.g. reply.append(item, to: :items, autofocus: true) → ItemRow.new(item:,
+      # autofocus: true). Additive: a no-kwarg call is byte-identical to before.
+      def append(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, **row_kwargs)
+        collection_build!(:build_collection_append, :append, model, legacy_model, to, row_kwargs)
       end
 
-      def prepend(name, model)
-        Response.collection_prepend(@component, name, model)
+      def prepend(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, **row_kwargs)
+        collection_build!(:build_collection_prepend, :prepend, model, legacy_model, to, row_kwargs)
       end
 
-      # Two forms:
-      #   reply.remove               # remove the bound component's own element
-      #   reply.remove(:items, model) # remove a collection row + count + empty
-      def remove(name = UNSET, model = UNSET)
-        return Response.remove(@component) if name.equal?(UNSET)
+      # Two forms, dispatched on the PRESENCE of `from:` (issue #182 — no sentinel
+      # overload): bare `reply.remove` removes the bound component's own element;
+      # `reply.remove(model, from: :items)` removes a collection row + count +
+      # empty-state. `model` may be the record or the row's dom-id string.
+      #
+      #   reply.remove                       # remove the bound component's element
+      #   reply.remove(model, from: :items)  # remove a collection row
+      def remove(model = UNSET_ARG, legacy_model = UNSET_ARG, from: UNSET_ARG)
+        reject_legacy_form!(:remove, model, legacy_model)
+        # Bare `reply.remove` (no positional, no from:) removes self.
+        return Response.build_remove(@component) if from.equal?(UNSET_ARG) && model.equal?(UNSET_ARG)
 
-        Response.collection_remove(@component, name, model)
+        if from.equal?(UNSET_ARG)
+          raise ArgumentError,
+            "reply.remove(model, …) needs a source collection — reply.remove(model, from: :name)"
+        end
+        reject_symbol_first!(:remove, model, :from, from)
+        Response.build_collection_remove(@component, from, resolve_row_arg(model))
       end
 
       # Subject-free builders — pass straight through so they read naturally.
 
       # Client-side full navigation (Turbo.visit). Pass a *_url.
       def redirect(url)
-        Response.redirect(url)
+        Response.build_redirect(url)
       end
 
       # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
       def with(*strings)
-        Response.with(*strings)
+        Response.build_with(*strings)
       end
 
       # Self-targeting again: emit exactly these streams with a TOKEN-ONLY refresh
       # (issue #30) — partial/per-field update, NO full-self replace, so the
       # component's live inputs survive. The bound component supplies the token.
       def streams(*strings)
-        Response.streams(@component, *strings)
+        Response.build_streams(@component, *strings)
       end
 
       # Defer an expensive segment (issue #165): `reply.defer(Totals.new(...))`.
       #
       # With NO prior verb, the bound component's token is refreshed via a tiny
-      # token-only stream (Response.streams), NOT a full self-replace: a full
+      # token-only stream (reply.streams), NOT a full self-replace: a full
       # replace would re-render the acting component SYNCHRONOUSLY on the request
       # thread — and if you defer your OWN subject (`reply.defer(self)`), that is
       # the very render you meant to move OFF the critical path, so the defer
@@ -115,7 +121,62 @@ module Phlex
       #   reply.streams(volume_cell).defer(SessionTotals.new(workout: @workout))
       #   reply.replace.defer(Totals.new(order: @order))   # explicit self re-render
       def defer(component, placeholder: nil, morph: false)
-        Response.streams(@component).defer(component, placeholder:, morph:)
+        Response.build_streams(@component).defer(component, placeholder:, morph:)
+      end
+
+      private
+
+      # Sentinel distinguishing "keyword omitted" from an explicit nil value, so
+      # `reply.remove(nil, from: :items)` (remove a row whose id resolves to nil)
+      # stays distinct from bare `reply.remove` (remove self). Reused for the
+      # positional model too, so the Symbol-first misuse can be caught precisely.
+      UNSET_ARG = Object.new
+      private_constant :UNSET_ARG
+
+      # Shared append/prepend build: catch the old two-positional form, require the
+      # `to:` keyword, reject a Symbol-first model, then delegate to the Response
+      # builder (name first, model second — its internal order).
+      def collection_build!(builder, verb, model, legacy_model, to, row_kwargs)
+        # Old form `reply.append(:name, model)` passes a SECOND positional — the
+        # arity would just error, so intercept it with the guided rewrite.
+        reject_legacy_form!(verb, model, legacy_model)
+        if to.equal?(UNSET_ARG)
+          raise ArgumentError,
+            "reply.#{verb} needs a target collection — reply.#{verb}(model, to: :name)"
+        end
+        reject_symbol_first!(verb, model, :to, to)
+        Response.public_send(builder, @component, to, resolve_row_arg(model), **row_kwargs)
+      end
+
+      # The pre-#182 call `reply.<verb>(:name, model)` — a Symbol name first, the
+      # model second. Detect it by the presence of the second positional and print
+      # the exact keyword rewrite.
+      def reject_legacy_form!(verb, model, legacy_model)
+        return if legacy_model.equal?(UNSET_ARG)
+
+        keyword = verb == :remove ? :from : :to
+        raise ArgumentError,
+          "reply.#{verb}(#{model.inspect}, …) — the collection name moved to a keyword " \
+          "(issue #182): reply.#{verb}(model, #{keyword}: #{model.inspect})"
+      end
+
+      # Issue #182 removed the Symbol-first form (`reply.append(:items, model)`).
+      # A Symbol in the model position is almost certainly that old call shape, so
+      # raise the exact keyword rewrite instead of trying to build a row from a
+      # Symbol "record".
+      def reject_symbol_first!(verb, model, keyword, name)
+        return unless model.is_a?(Symbol)
+
+        raise ArgumentError,
+          "reply.#{verb}(#{model.inspect}, …) — the collection name moved to a keyword " \
+          "(issue #182): reply.#{verb}(model, #{keyword}: #{name.inspect})"
+      end
+
+      # A row build needs a real model/dom-id — never the omitted sentinel.
+      def resolve_row_arg(model)
+        raise ArgumentError, "reply collection verbs need a model or dom-id as the first argument" if model.equal?(UNSET_ARG)
+
+        model
       end
     end
   end