phlex-reactive 0.12.4 → 0.12.6

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

@@ -267,7 +267,7 @@ module Phlex
             assert_no_scope_double_nesting!(scope, params, name.to_sym) if scope
             Registry.write_entry(
               self, :actions, name.to_sym,
-              Action.new(name: name.to_sym, params: params, schema: Phlex::Reactive::ParamSchema.compile(params))
+              ActionDefinition.new(name: name.to_sym, params: params, schema: Phlex::Reactive::ParamSchema.compile(params))
             )
           end
 

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

@@ -85,6 +85,10 @@ module Phlex
           # JS), so the client's attr check would never fire (the on()/warn_unsaved
           # precedent). Off by default → no key, no string, zero client surface.
           data[:reactive_debug] = "true" if Phlex::Reactive.debug
+          # Issue #237: the verbose gate for the client's zero-target op warning.
+          # ON by default in dev/test (Rails.env.local?), so the papercut warning
+          # works out of the box; production renders no attr and stays silent.
+          data[:reactive_verbose] = "true" if Phlex::Reactive.verbose_errors
           # Field-name scope (issue #180): the client prefixes bare binding field
           # names with `scope[...]`. Omitted entirely when undeclared — byte-stable
           # wire for unscoped components.
@@ -1080,6 +1084,91 @@ 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
+        # reactive_root, like reactive_show_targets); the generic controller
+        # then writes every owned control's value to localStorage 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
+        # `ttl` elapses, or on a js.persist_clear op:
+        #
+        #   div(**mix(reactive_root, reactive_persist(key: "village-apply", ttl: 7.days))) do
+        #     input(**reactive_field(:name))                       # persisted
+        #     input(name: "fuckery", **reactive_persist_skip)      # honeypot — never
+        #     input(type: "hidden", name: "tz")                    # hidden — never (default)
+        #   end
+        #
+        # Never persisted: type=hidden/file/password/submit/button/reset/image,
+        # anything carrying reactive_persist_skip, a nested reactive root's
+        # controls (#15 ownership), and — when `fields:` narrows the set —
+        # any name outside it (scope-aware symbols, the reactive_show form).
+        # `autocomplete="off"` is NOT an implicit skip: honeypots (an
+        # invisible_captcha text input looks like any other) must opt out
+        # explicitly or sit outside the root.
+        #
+        # `restore:` — `:blank` (default) restores a draft value only into a
+        # control the server rendered BLANK, so a 422 re-render's submitted
+        # values win over an older draft; `:always` lets the draft win.
+        #
+        # 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
+        # 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)
+          payload = {
+            "key" => validate_persist_key!(key),
+            "ttl" => validate_persist_ttl!(ttl),
+            "debounce" => validate_persist_debounce!(debounce)
+          }
+          payload["restore"] = "always" if validate_persist_restore!(restore) == :always
+          payload["fields"] = validate_persist_fields!(fields) if fields
+
+          { data: { reactive_persist: payload.to_json } }
+        end
+
+        # Mark ONE control as never persisted (issue #239) — a honeypot, a
+        # one-time code. Spread on the control: input(name: "x", **reactive_persist_skip).
+        def reactive_persist_skip
+          { data: { reactive_persist: "off" } }
+        end
+
+        def validate_persist_key!(key)
+          return key if key.is_a?(String) && !key.strip.empty?
+
+          raise ArgumentError, "reactive_persist key: must be a non-blank String, got #{key.inspect}"
+        end
+
+        # Seconds on the wire: an ActiveSupport::Duration (7.days) or an Integer.
+        def validate_persist_ttl!(ttl)
+          seconds = ttl.is_a?(ActiveSupport::Duration) ? ttl.to_i : ttl
+          return seconds if seconds.is_a?(Integer) && seconds.positive?
+
+          raise ArgumentError, "reactive_persist ttl: must be a positive duration or Integer seconds, got #{ttl.inspect}"
+        end
+
+        def validate_persist_debounce!(debounce)
+          return debounce if debounce.is_a?(Integer) && !debounce.negative?
+
+          raise ArgumentError, "reactive_persist debounce: must be a non-negative Integer (ms), got #{debounce.inspect}"
+        end
+
+        def validate_persist_restore!(restore)
+          return restore if %i[blank always].include?(restore)
+
+          raise ArgumentError, "reactive_persist restore: must be :blank or :always, got #{restore.inspect}"
+        end
+
+        def validate_persist_fields!(fields)
+          list = Array(fields)
+          raise ArgumentError, "reactive_persist fields: needs at least one field name" if list.empty?
+
+          list.map { scoped_field_name(it) }
+        end
+
         # Scoped busy indicator (issue #99). Marks an element so the generic
         # controller toggles `data-reactive-busy` on it ONLY while `action` is in
         # flight — the scoped sibling of the always-on `data-reactive-busy` the

data/lib/phlex/reactive/component.rb

@@ -84,7 +84,14 @@ module Phlex
       # is the compiled Phlex::Reactive::ParamSchema (issue #109) the endpoint
       # coerces through — built ONCE at declaration so a typo'd type symbol
       # raises Phlex::Reactive::UnknownParamType at class load, not at click time.
-      Action = Data.define(:name, :params, :schema)
+      #
+      # Named ActionDefinition (issue #233), NOT Action: this module sits in
+      # every reactive component's ancestry, so a bare `Action` constant
+      # shadows a host app's Phlex kit component of the same name under lazy
+      # autoloading (Kit's LazyLoader resolves through the calling class's
+      # const_get). Keep every constant here suffixed / implausible as a kit
+      # component name — and never alias the old name back.
+      ActionDefinition = Data.define(:name, :params, :schema)
 
       # A declared client-side computation (data binding). `inputs`/`outputs` are
       # the action-param names of the fields the reducer reads/writes; `reducer`

data/lib/phlex/reactive/js.rb

@@ -252,6 +252,36 @@ module Phlex
         @ops.empty?
       end
 
+      # --- Client-only drafts (issue #239) ---
+      #
+      # persist_state(**state) — merge a FLAT bag of scalars (a wizard's
+      # current step) into the root's reactive_persist draft alongside the
+      # owned fields' values; the client restores it on the next connect as
+      # data-reactive-persist-state on the root plus the
+      # reactive:persist-restored event's detail.state. Always targets the
+      # ROOT (the draft lives there). persist_clear — forget the draft now
+      # (the explicit sibling of the automatic turbo:submit-end clear).
+      # Both ACTOR-ONLY like focus/submit: a broadcast that rewrote or wiped
+      # every subscriber's draft would be hostile (BROADCAST_REFUSED_OPS).
+
+      def persist_state(**state)
+        raise ArgumentError, "#{self.class}: persist_state needs at least one key (e.g. step: 2)" if state.empty?
+
+        state.each do |name, value|
+          next if value.nil? || [String, Numeric, TrueClass, FalseClass].any? { value.is_a?(it) }
+
+          raise ArgumentError,
+            "#{self.class}: persist_state values must be scalar (String/Numeric/true/false/nil) — " \
+            "#{name.inspect} is #{value.class} (the draft stays flat)"
+        end
+
+        append("persist_state", { "to" => ROOT_SENTINEL, "state" => state.transform_keys(&:to_s).freeze }.freeze)
+      end
+
+      def persist_clear
+        append("persist_clear", { "to" => ROOT_SENTINEL }.freeze)
+      end
+
       private
 
       # Immutability: every verb funnels here and returns a NEW frozen chain —

data/lib/phlex/reactive/response.rb

@@ -314,7 +314,11 @@ data-reactive-flash-level="#{level_attr}"#{dismiss_attr(dismiss_after)}>#{body}<
         def js_stream(ops, target: nil)
           json = js_ops_json(ops)
           target_attr = target ? %( target="#{ERB::Util.html_escape(target)}") : ""
-          %(<turbo-stream action="reactive:js"#{target_attr} \
+          # Issue #237: carry the verbose gate on the stream element itself, so
+          # the client can warn on zero-target resolution even for a
+          # document-scoped op with no controller root to read the flag from.
+          verbose_attr = Phlex::Reactive.verbose_errors ? %( data-reactive-verbose="true") : ""
+          %(<turbo-stream action="reactive:js"#{target_attr}#{verbose_attr} \
 data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
         end
 

data/lib/phlex/reactive/show_conditions.rb

@@ -121,11 +121,10 @@ module Phlex
         end
 
         alternatives = negative.flat_map { |field, value| negative_alternatives(field, value) }
-        # rubocop:disable Style/ItBlockParameter -- nested block: `it` would shadow `group`
+        # rubocop:disable-next Style/ItBlockParameter -- nested block: `it` would shadow `group`
         groups.flat_map do |group|
           alternatives.map { |extra| group + extra }
         end
-        # rubocop:enable Style/ItBlockParameter
       end
 
       # --- the value language (positive) -------------------------------------

data/lib/phlex/reactive/streamable.rb

@@ -39,7 +39,7 @@ module Phlex
       # (issue #228) would read every subscriber's clipboard. They belong to
       # the actor's own reply (reply.js) or gesture (on_client / a reducer's
       # $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
-      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into].freeze
+      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear].freeze
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
       # SELF-TARGETING verbs derive the target from the component's #id (require a
@@ -137,7 +137,13 @@ module Phlex
             "broadcast", { component: component_name, stream_action: BROADCAST_VERBS[verb], streamables: keys.size }
           ) do
             with_pgbus_broadcast_opts(exclude:, visible_to:) do
-              html = verb == :js ? nil : render_broadcast_html(component)
+              # A broadcast render NEVER inherits the actor's url_options (issue
+              # #232): this call may run inside an action request (where the
+              # endpoint threaded the actor's host), but subscribers can be on
+              # different hosts — absolute URLs in broadcast-rendered components
+              # keep the process defaults, so "host-relative URLs" stays the
+              # broadcast contract. Off-request callers pay one nil-write pair.
+              html = verb == :js ? nil : Phlex::Reactive.with_url_options(nil) { render_broadcast_html(component) }
               ops_json = verb == :js ? broadcast_js_ops_json(payload) : nil
               keys.each { dispatch_broadcast(verb, it, resolved_target, html, ops_json, morph, effect) }
             end
@@ -237,8 +243,12 @@ module Phlex
           when :prepend then ::Turbo::StreamsChannel.broadcast_prepend_to(*parts, target:, html:, **wire)
           when :remove then ::Turbo::StreamsChannel.broadcast_remove_to(*parts, target:, **wire)
           when :js
+            # Issue #237: the broadcast op stream carries the verbose gate too
+            # (same server env for every subscriber of this payload).
+            data = { reactive_ops: ops_json }
+            data[:reactive_verbose] = "true" if Phlex::Reactive.verbose_errors
             ::Turbo::StreamsChannel.broadcast_action_to(
-              *parts, action: "reactive:js", target:, attributes: { data: { reactive_ops: ops_json } }, render: false
+              *parts, action: "reactive:js", target:, attributes: { data: }, render: false
             )
           end
         end
@@ -487,7 +497,7 @@ module Phlex
         # Define the guided-error stub for each removed broadcast method (issue
         # #185). `verb` is referenced in define_method AND the message, so the outer
         # block param must be named — `it` is illegal here.
-        # rubocop:disable Style/ItBlockParameter
+        # rubocop:disable-next Style/ItBlockParameter
         Phlex::Reactive::Streamable::REMOVED_BROADCASTS.each_key do |verb|
           define_method(verb) do |*, **|
             raise NoMethodError,
@@ -495,7 +505,6 @@ module Phlex
               "use #{name}.#{Phlex::Reactive::Streamable::REMOVED_BROADCASTS[verb]}"
           end
         end
-        # rubocop:enable Style/ItBlockParameter
 
         private
 

data/lib/phlex/reactive/test_helpers/system.rb

@@ -122,7 +122,7 @@ module Phlex
 
           # does_not_match? is RSpec's REQUIRED negated-matcher protocol method — its
           # name is fixed by RSpec, not a predicate we get to rename.
-          # rubocop:disable Naming/PredicatePrefix
+          # rubocop:disable-next Naming/PredicatePrefix
           def does_not_match?(page)
             @page = page
             # The negative is satisfied the moment the property is NOT the expected
@@ -130,7 +130,6 @@ module Phlex
             # as that holds, false if it stayed equal for the whole budget.
             poll_until { current_value != @expected }
           end
-          # rubocop:enable Naming/PredicatePrefix
 
           def failure_message
             "expected ##{@id} to have value #{@expected.inspect} (its .value property), " \

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.12.4"
+    VERSION = "0.12.6"
   end
 end

data/lib/phlex/reactive.rb

@@ -513,6 +513,22 @@ module Phlex
         instance = controller_class.new
         instance.set_request!(request)
         instance.set_response!(controller_class.make_response!(request))
+
+        # Issue #232: during a reactive request the endpoint threads the actor's
+        # protocol/host/port via with_url_options; merge them over this
+        # instance's defaults so absolute URL helpers in a reply render the
+        # REQUESTING host. View contexts delegate url_options to their
+        # controller (ActionView::RoutingUrlFor), so this one override covers
+        # every helper spelling. Off-request (thread-local nil — jobs, console,
+        # broadcasts) returns super's frozen memo untouched: zero-alloc, byte-
+        # identical URLs. Defined on the singleton because this instance is
+        # MEMOIZED per thread — its request (and super's @_url_options) never
+        # changes, so the per-call merge is the only per-request seam.
+        def instance.url_options
+          overrides = Phlex::Reactive.current_url_options
+          overrides ? super.merge(overrides) : super
+        end
+
         instance.view_context
       end
 
@@ -968,6 +984,40 @@ module Phlex
         Thread.current[:phlex_reactive_connection_id] = previous
       end
 
+      # The acting request's url_options during a reactive request, or nil
+      # (issue #232). Set by the ActionsController (the action AND defer
+      # endpoints) so absolute URL helpers in a reply-rendered component —
+      # image_tag on an Active Storage attachment being the everyday case —
+      # carry the REQUESTING host/port/protocol instead of the process default
+      # (the ActiveStorage::SetCurrent move). The memoized off-request view
+      # context merges this over its defaults per call (see
+      # request_bound_view_context); nil (jobs, console, plain broadcasts)
+      # leaves the defaults untouched — byte-identical to before.
+      def current_url_options
+        Thread.current[:phlex_reactive_url_options]
+      end
+
+      # Thread `options` for the block, restoring the previous value after.
+      # `nil` CLEARS the actor options — the broadcast render uses this to keep
+      # a broadcast fired inside an action on process defaults (subscribers can
+      # be on different hosts; "URLs in broadcast-rendered components must be
+      # host-relative" is the broadcast contract).
+      def with_url_options(options)
+        previous = Thread.current[:phlex_reactive_url_options]
+        Thread.current[:phlex_reactive_url_options] = options.presence
+        yield
+      ensure
+        Thread.current[:phlex_reactive_url_options] = previous
+      end
+
+      # The url_options trio derived from a live request. `port` is optional_port
+      # — nil on the default port — and is INCLUDED even when nil so a
+      # default-port request clears any configured default port rather than
+      # inheriting it (the merge must own the whole trio).
+      def url_options_for(request)
+        { protocol: request.protocol, host: request.host, port: request.optional_port }
+      end
+
       # The controller a correctly-mounted action path resolves to. Used by the
       # route guard below.
       ACTIONS_CONTROLLER = "phlex/reactive/actions"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 0.12.6
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -188,13 +188,13 @@ files:
 - lib/phlex/reactive/test_helpers/system.rb
 - lib/phlex/reactive/version.rb
 - lib/tasks/phlex_reactive.rake
-homepage: https://github.com/mhenrixon/phlex-reactive
+homepage: https://github.com/zoolutions/phlex-reactive
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/mhenrixon/phlex-reactive
-  source_code_uri: https://github.com/mhenrixon/phlex-reactive/tree/main
-  changelog_uri: https://github.com/mhenrixon/phlex-reactive/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/zoolutions/phlex-reactive
+  source_code_uri: https://github.com/zoolutions/phlex-reactive/tree/main
+  changelog_uri: https://github.com/zoolutions/phlex-reactive/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: