phlex-reactive 0.2.9 → 0.4.0

data/lib/phlex/reactive/component.rb

@@ -5,8 +5,10 @@ module Phlex
     # Component turns a self-contained Phlex component into a Livewire-style
     # 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 morphs it back into the DOM. No per-feature
-    # Stimulus controllers, no hand-picked Turbo targets.
+    # 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.
     #
     # Include alongside Phlex::Reactive::Streamable (which provides #id and the
     # re-render machinery).
@@ -60,12 +62,31 @@ module Phlex
       # A declared, client-invokable action and its param schema.
       Action = Data.define(:name, :params)
 
+      # A declared add/remove-row collection (issue #35): the list contract tied
+      # into one unit — the per-row item component, the container DOM id rows
+      # live in, an optional companion count id, an optional empty-state
+      # component, and a size resolver (a proc evaluated against the container
+      # instance) used to re-render the count and toggle the empty-state at the
+      # 0<->1 boundary. count/empty/size are nil when not declared, and the
+      # corresponding stream is simply omitted — so a list with just rows still
+      # works.
+      CollectionDefinition = Data.define(:name, :item, :container, :count, :empty, :size) do
+        # The collection's current size, evaluated against the bound container
+        # instance (instance_exec so the proc reads the component's ivars /
+        # association). nil when no resolver was declared — callers skip the
+        # count/empty streams that need a number.
+        def size_for(component)
+          size && component.instance_exec(&size)
+        end
+      end
+
       class_methods do
         # Declare the ActiveRecord (GlobalID-able) record this component is
         # rebuilt from. The signed token carries its GlobalID; the server
         # re-finds it on each action. State lives in the DB.
         def reactive_record(name)
           @reactive_record_key = name.to_sym
+          remove_instance_variable(:@reactive_record_ivar) if defined?(@reactive_record_ivar)
         end
 
         def reactive_record_key
@@ -78,6 +99,7 @@ module Phlex
         #   reactive_state :count, :open
         def reactive_state(*names)
           reactive_state_keys.concat(names.map(&:to_sym))
+          @reactive_state_ivars = nil # rebuild the cached [key, ivar] pairs
         end
 
         def reactive_state_keys
@@ -118,6 +140,59 @@ module Phlex
           reactive_actions.key?(name.to_sym)
         end
 
+        # Declare an add/remove-row collection (issue #35) — the list contract
+        # in one place, so actions append/prepend/remove a row WITHOUT
+        # re-deriving the container id, count, and empty-state in every action:
+        #
+        #   reactive_collection :items,
+        #     item: ItemRowComponent,    # the per-row Streamable component
+        #     container: "items-list",   # the DOM id rows live in
+        #     count: "items-count",      # optional companion id (the size badge)
+        #     empty: ItemsEmptyComponent, # optional empty-state component
+        #     size: -> { @record.items.size } # resolves the live size
+        #
+        # An action then governs the reply with one call:
+        #   reply.append(:items, item)   # row append + count + clear empty-state
+        #   reply.remove(:items, id)     # row remove + count + restore empty-state
+        #
+        # count/empty/size are optional: a list with just rows omits them and the
+        # corresponding stream isn't emitted. See Phlex::Reactive::Reply and the
+        # README "Reactive collections" section.
+        def reactive_collection(name, item:, container:, count: nil, empty: nil, size: nil)
+          reactive_collections[name.to_sym] =
+            CollectionDefinition.new(name: name.to_sym, item:, container:, count:, empty:, size:)
+        end
+
+        def reactive_collections
+          @reactive_collections ||= superclass.respond_to?(:reactive_collections) ? superclass.reactive_collections.dup : {}
+        end
+
+        def reactive_collection_def(name)
+          reactive_collections[name.to_sym]
+        end
+
+        def reactive_collection?(name)
+          reactive_collections.key?(name.to_sym)
+        end
+
+        # The record's instance-variable symbol (e.g. :@todo), computed once.
+        # reactive_token reads it on every render; interpolating :"@#{key}" each
+        # time would allocate a symbol per render. Nil when record-less. Memoized
+        # per class; reset alongside reactive_record so it can't go stale.
+        def reactive_record_ivar
+          return @reactive_record_ivar if defined?(@reactive_record_ivar)
+
+          @reactive_record_ivar = reactive_record_key ? :"@#{reactive_record_key}" : nil
+        end
+
+        # [string_key, ivar_symbol] pairs for the signed state, computed once.
+        # reactive_token walks these every render; precomputing the "count"/:@count
+        # forms avoids a String + Symbol allocation per key per render. Memoized
+        # per class; reset when reactive_state adds a key.
+        def reactive_state_ivars
+          @reactive_state_ivars ||= reactive_state_keys.map { [it.to_s, :"@#{it}"] }
+        end
+
         # Rebuild a component instance from a verified identity payload. Called
         # by the action endpoint after the token signature is verified.
         #
@@ -137,14 +212,14 @@ module Phlex
 
           if reactive_state_keys.any?
             state = payload.fetch("s", {})
-            reactive_state_keys.each do |key|
+            reactive_state_keys.each do
               # Use key presence, not the value: a signed `nil` (nullable state)
               # must round-trip distinctly. Only a genuinely absent key falls
               # back to the component's initialize default; `false` and `nil`
               # both survive.
-              next unless state.key?(key.to_s)
+              next unless state.key?(it.to_s)
 
-              kwargs[key] = state[key.to_s]
+              kwargs[it] = state[it.to_s]
             end
           end
 
@@ -167,6 +242,22 @@ module Phlex
         Phlex::Reactive.current_connection_id
       end
 
+      # Subject-bound reply builder — the preferred way to control an action's
+      # reply. `reply.replace.flash(:error, msg)` reads cleaner than
+      # `Phlex::Reactive::Response.replace(self).flash(:error, msg)`: the
+      # component is the implicit subject (no `self` to thread) and there's no
+      # constant to qualify (reply is a method, so a namespaced component needs
+      # no `Response = …` alias). It returns the same immutable Response the
+      # endpoint reads, so chaining and the legacy return-value contract are
+      # unchanged. See Phlex::Reactive::Reply.
+      #
+      #   def archive       = reply.remove
+      #   def go_home       = reply.redirect("/todos")
+      #   def update(name:) = (@account.update!(name:); reply.morph)
+      def reply
+        Phlex::Reactive::Reply.new(self)
+      end
+
       # Root-element attributes: marks the element reactive and carries the
       # signed identity token. Spread onto the root:
       #   div(id:, **reactive_attrs) { ... }
@@ -193,12 +284,18 @@ module Phlex
       # live-update-as-you-type doesn't POST per keystroke. A blur flushes a
       # pending dispatch so the last edit is never dropped. Omit it for the
       # immediate-dispatch default.
+      # The verbatim JSON for an empty explicit-params payload. The common
+      # trigger (on(:increment), no params) hits this on EVERY render — skipping
+      # params.to_json (which re-serializes {} to the same "{}" each time) avoids
+      # a per-render allocation while keeping the wire format byte-identical.
+      EMPTY_PARAMS_JSON = "{}"
+
       def on(action_name, event: "click", debounce: nil, **params)
         attrs = {
           data: {
             action: "#{event}->reactive#dispatch",
             reactive_action_param: action_name.to_s,
-            reactive_params_param: params.to_json
+            reactive_params_param: params.empty? ? EMPTY_PARAMS_JSON : params.to_json
           }
         }
         attrs[:data][:reactive_debounce_param] = debounce if debounce
@@ -216,7 +313,7 @@ module Phlex
       # hatch). The trigger (on(:save)) stays on the button, not the field — so
       # focusing the input doesn't dispatch and collapse edit mode.
       def reactive_field(param, **attrs)
-        {name: param.to_s, **attrs}
+        { name: param.to_s, **attrs }
       end
 
       # Render an <input> already bound to an action param (issue #23). Sugar for
@@ -230,8 +327,8 @@ module Phlex
       # is the element's content, so the awkward FormBuilder positional split
       # (where name: lands after the options/html-options args) goes away:
       #   reactive_select(:status) { @statuses.each { |s| option(value: s, selected: s == @record.status) { s } } }
-      def reactive_select(param, **attrs, &block)
-        select(**reactive_field(param, **attrs), &block)
+      def reactive_select(param, **attrs, &)
+        select(**reactive_field(param, **attrs), &)
       end
 
       # Map a declared nested param onto Rails' <assoc>_attributes, carrying the
@@ -247,7 +344,7 @@ module Phlex
         existing = reactive_record_for_nested.public_send(association)
         merged[:id] = existing.id if existing
 
-        {"#{association}_attributes": merged}
+        { "#{association}_attributes": merged }
       end
 
       # Map a nested param onto <assoc>_attributes (with id preservation) AND
@@ -265,9 +362,7 @@ module Phlex
       # record-backed component).
       def reactive_record_for_nested
         key = self.class.reactive_record_key
-        unless key
-          raise Error, "#{self.class} must declare `reactive_record` to use nested_update!/nested_attributes"
-        end
+        raise Error, "#{self.class} must declare `reactive_record` to use nested_update!/nested_attributes" unless key
 
         instance_variable_get(:"@#{key}")
       end
@@ -279,17 +374,18 @@ module Phlex
       # record. Record-only ({c, gid}) and state-only ({c, s}) shapes are
       # unchanged.
       def reactive_token
-        payload = {"c" => self.class.name}
+        klass = self.class
+        payload = { "c" => klass.name }
 
-        if self.class.reactive_record_key
-          record = instance_variable_get(:"@#{self.class.reactive_record_key}")
-          payload["gid"] = record.to_gid.to_s
+        if (record_ivar = klass.reactive_record_ivar)
+          payload["gid"] = instance_variable_get(record_ivar).to_gid.to_s
         end
 
-        if self.class.reactive_state_keys.any?
-          payload["s"] = self.class.reactive_state_keys.to_h do |k|
-            [k.to_s, instance_variable_get(:"@#{k}").as_json]
-          end
+        state_ivars = klass.reactive_state_ivars
+        unless state_ivars.empty?
+          state = {}
+          state_ivars.each { |key, ivar| state[key] = instance_variable_get(ivar).as_json }
+          payload["s"] = state
         end
 
         Phlex::Reactive.sign(payload)

data/lib/phlex/reactive/engine.rb

@@ -13,27 +13,27 @@ module Phlex
 
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create.
       # Apps can change the path with Phlex::Reactive.action_path before boot.
-      initializer "phlex_reactive.routes" do |app|
-        app.routes.append do
+      initializer "phlex_reactive.routes" do
+        it.routes.append do
           post Phlex::Reactive.action_path, to: "phlex/reactive/actions#create", as: :phlex_reactive_action
         end
       end
 
       # Make reactive_controller.js available to Propshaft/Sprockets so it can
       # be included via the asset pipeline or pinned in importmap.
-      initializer "phlex_reactive.assets" do |app|
-        if app.config.respond_to?(:assets)
-          app.config.assets.paths << root.join("app/javascript").to_s
-          app.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
+      initializer "phlex_reactive.assets" do
+        if it.config.respond_to?(:assets)
+          it.config.assets.paths << root.join("app/javascript").to_s
+          it.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
         end
       end
 
       # Auto-pin the client controller for importmap apps so it loads without
       # manual configuration. Apps that don't use importmap include it via the
       # asset pipeline instead (see README).
-      initializer "phlex_reactive.importmap", after: "importmap" do |app|
-        if defined?(::Importmap::Map) && app.respond_to?(:importmap)
-          app.importmap.pin(
+      initializer "phlex_reactive.importmap", after: "importmap" do
+        if defined?(::Importmap::Map) && it.respond_to?(:importmap)
+          it.importmap.pin(
             "phlex/reactive/reactive_controller",
             to: "phlex/reactive/reactive_controller.js",
             preload: true
@@ -41,6 +41,15 @@ module Phlex
         end
       end
 
+      # Flush memoized off-request view contexts on every code reload (dev) so a
+      # reloaded renderer controller class is never served from a stale memo. In
+      # production to_prepare runs once (eager load), so the cache simply builds
+      # fresh after boot. See Streamable.reset_all_view_contexts!.
+      config.to_prepare do
+        Phlex::Reactive::Streamable.reset_all_view_contexts!
+        Phlex::Reactive.reset_flash_builder!
+      end
+
       # Boot-time guard (issue #26): warn if the action path doesn't resolve to
       # the gem controller. Runs after_initialize so the host's full route set
       # (including a bottom-of-file catch-all that would shadow our appended

data/lib/phlex/reactive/reply.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+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
+    #
+    #   reply.replace.flash(:error, msg)
+    #
+    # instead of
+    #
+    #   Phlex::Reactive::Response.replace(self).flash(:error, msg)
+    #
+    # 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.
+    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
+
+      # Self-targeting builders — the bound component is supplied implicitly.
+
+      # 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:)
+      end
+
+      # Re-render in place via Idiomorph (method="morph") — keeps focus + caret.
+      def morph
+        Response.morph(@component)
+      end
+
+      # Morph only inner HTML (preserves the root element + its token attr).
+      def update
+        Response.update(@component)
+      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).
+      #
+      #   def add_item(...)    = (item = @list.items.create!(...); reply.append(:items, item))
+      #   def remove_item(id:) = (@list.items.find(id).destroy!;   reply.remove(:items, id))
+      #
+      # `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)
+      end
+
+      def prepend(name, model)
+        Response.collection_prepend(@component, name, model)
+      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)
+
+        Response.collection_remove(@component, name, 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)
+      end
+
+      # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
+      def with(*strings)
+        Response.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)
+      end
+    end
+  end
+end

data/lib/phlex/reactive/response.rb

@@ -17,11 +17,23 @@ module Phlex
     #   Response.redirect(article_url(@article))        # slug changed -> Turbo.visit the new URL
     #   Response.replace(self).stream(Totals.update(@order))  # multi-stream
     class Response
-      attr_reader :streams, :redirect_url
+      attr_reader :streams, :redirect_url, :token_component
 
       class << self
         # Re-render the component in place (explicit form of today's default).
-        def replace(component) = new(streams: [component.to_stream_replace])
+        # `morph: true` morphs the subtree (preserves the focused input + caret)
+        # instead of an outerHTML swap — see .morph (issue #28).
+        def replace(component, morph: false)
+          new(streams: [morph ? component.to_stream_morph : component.to_stream_replace])
+        end
+
+        # Re-render the component in place via Idiomorph (issue #28). Emits
+        # `<turbo-stream action="replace" method="morph">`, so Turbo 8 morphs the
+        # subtree — the focused <input> + caret survive the save. Use this for
+        # per-field reactive editing (a "spreadsheet" grid where a debounced save
+        # fires while the user is still typing/tabbing). The morphed root still
+        # carries the fresh signed token, so the next action verifies.
+        def morph(component) = new(streams: [component.to_stream_morph])
 
         # Morph only inner HTML (preserves the root element + its token attr).
         def update(component) = new(streams: [component.to_stream_update])
@@ -39,6 +51,120 @@ module Phlex
         # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
         def with(*strings) = new(streams: strings.flatten)
 
+        # --- Reactive collections (issue #35) ---
+        # Add/remove a row in a declared reactive_collection, emitting the row
+        # stream + the count companion update + the empty-state toggle as ONE
+        # Response. `component` is the bound CONTAINER (it carries the
+        # declaration and the size resolver); `model` is the row's record (or, for
+        # remove, a model OR a dom-id string). count/empty/size are optional — a
+        # stream is emitted only for the pieces declared.
+        #
+        # render_self is false: the row append/prepend/remove IS the update, so
+        # we must NOT also replace the whole container (that would re-render every
+        # row and clobber the just-streamed delta).
+        #
+        # token_component is the CONTAINER (cosmos#1939): a reply that does NOT
+        # re-render self must STILL refresh self's signed token, or the list is
+        # add-once-only — correct on the first click, then every subsequent dispatch
+        # from the list root is rejected (its token went stale) with no error. The
+        # container owns the add/remove trigger, so the endpoint appends its inert
+        # `reactive:token` stream (the same #30 machinery reply.streams uses) to roll
+        # the token forward without re-rendering the rows.
+        def collection_append(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_add_streams(definition, component, model, :append),
+            render_self: false, token_component: component)
+        end
+
+        def collection_prepend(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_add_streams(definition, component, model, :prepend),
+            render_self: false, token_component: component)
+        end
+
+        def collection_remove(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_remove_streams(definition, component, model),
+            render_self: false, token_component: component)
+        end
+
+        private
+
+        # Resolve the declaration off the container's class, raising a clear error
+        # for an undeclared name (a typo'd collection should fail loudly, not
+        # silently emit an empty Response).
+        def collection_def!(component, name)
+          component.class.reactive_collection_def(name) ||
+            raise(Phlex::Reactive::Error, "undeclared reactive_collection :#{name} on #{component.class}")
+        end
+
+        # Row add (append/prepend) + count + empty-state clear. The empty-state is
+        # removed only when the list just crossed 0->1 (size == 1) — appending to
+        # an already-populated list leaves it untouched.
+        def collection_add_streams(definition, component, model, action)
+          streams = [definition.item.public_send(action, target: definition.container, model:)]
+          append_count_stream(streams, definition, component)
+
+          size = definition.size_for(component)
+          streams << definition.empty.new.to_stream_remove if definition.empty && size == 1
+          streams
+        end
+
+        # Row remove + count + empty-state restore. The empty-state is appended
+        # back into the container only when the list just emptied (size == 0).
+        def collection_remove_streams(definition, component, model)
+          streams = [collection_row_remove(definition, model)]
+          append_count_stream(streams, definition, component)
+
+          size = definition.size_for(component)
+          if definition.empty && size&.zero?
+            # Render the empty-state and append it INTO the container (not its
+            # own id) — restoring "No items yet" when the last row was removed.
+            # model: nil builds it argument-free (an empty-state is a static view).
+            streams << definition.empty.append(target: definition.container, model: nil)
+          end
+          streams
+        end
+
+        # Remove the row by its DOM id. Accepts the record (so dom_id is derived)
+        # or an already-built dom-id string (e.g. the value the row used as #id).
+        def collection_row_remove(definition, model)
+          if model.is_a?(String)
+            Phlex::Reactive.flash_builder.remove(model)
+          else
+            definition.item.remove(model)
+          end
+        end
+
+        # Append the count companion's update stream when a count id + a size
+        # resolver are both declared. The size is a number, HTML-escaped by Turbo.
+        def append_count_stream(streams, definition, component)
+          return unless definition.count
+
+          size = definition.size_for(component)
+          return if size.nil?
+
+          streams << update_stream(definition.count, size.to_s)
+        end
+
+        public
+
+        # Partial / per-field update with a TOKEN-ONLY refresh (issue #30). Emits
+        # EXACTLY the given streams — no forced full-self replace — but binds
+        # `component` so the endpoint appends its tiny `to_stream_token` stream.
+        # So the signed token rolls forward (the next action verifies) while the
+        # component's own live inputs are never torn down: ideal for a
+        # spreadsheet-like grid where a debounced save re-streams only a total
+        # cell and the user is still typing in a sibling field.
+        #
+        #   Response.streams(self, Totals.update(@invoice))   # update only the totals
+        #
+        # render_self is false (we do NOT inject the full replace); the token is
+        # refreshed by the bound component's token stream instead.
+        def streams(component, *strings)
+          new(streams: strings.flatten, render_self: false, token_component: component)
+        end
+
         # Build a flash turbo-stream that appends `content` into a host-app
         # container. `content` is a Phlex component instance (rendered through
         # the configured renderer so t()/url_for work) or a ready HTML string —
@@ -73,10 +199,16 @@ module Phlex
       # GUARANTEES the component's own replace is present so its
       # data-reactive-token-value refreshes (the client extracts the next token
       # from the response HTML). remove/redirect set it false (nothing stays).
-      def initialize(streams: [], redirect_url: nil, render_self: true)
+      #
+      # token_component: set by .streams (issue #30) — a partial update that opts
+      # OUT of the full-self replace but still needs the token refreshed. The
+      # endpoint appends this component's tiny to_stream_token instead, so the
+      # token rolls forward without re-rendering (and clobbering) the children.
+      def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
+        @token_component = token_component
         freeze
       end
 
@@ -86,7 +218,8 @@ module Phlex
         self.class.new(
           streams: @streams + more.flatten,
           redirect_url: @redirect_url,
-          render_self: @render_self
+          render_self: @render_self,
+          token_component: @token_component
         )
       end
 
@@ -113,12 +246,19 @@ module Phlex
       # Like #also_update, but renders ANOTHER Streamable component and replaces
       # it by its own #id — for a companion that is itself a component.
       #   Response.replace(self).also_replace(SummaryCard.new(order: @order))
-      def also_replace(component)
-        stream(component.to_stream_replace)
+      # `morph: true` morphs the companion in place (issue #28) — use it when the
+      # companion also holds focusable inputs that must survive the re-render.
+      def also_replace(component, morph: false)
+        stream(morph ? component.to_stream_morph : component.to_stream_replace)
       end
 
       def redirect? = !@redirect_url.nil?
       def render_self? = @render_self
+
+      # True when a partial update (.streams) opted out of the full-self replace
+      # but still needs the token rolled forward — the endpoint appends the bound
+      # component's tiny token-only stream (issue #30).
+      def refresh_token? = !@token_component.nil?
     end
   end
 end