phlex-reactive 0.13.3 → 0.14.0

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

@@ -36,6 +36,30 @@ module Phlex
         # twin of wait_for_turbo watching the Turbo progress bar.
         ACTIVE_MARKER = "data-reactive-active"
 
+        # The <html> attribute the client keeps its per-kind request totals in
+        # (issue #279), as JSON ({"action":1,"defer":0}). Lockstep with
+        # reactive_controller.js REQUESTS_ATTR. Written only under the verbose
+        # gate (dev/test by default).
+        REQUESTS_ATTR = "data-reactive-requests"
+
+        # Parse the attribute value into { action:, defer: } Integers — zeros for
+        # an absent or garbled value. Shared by the helpers and
+        # ReactiveRequestsMatcher.
+        def self.parse_reactive_requests(raw)
+          parsed = raw.is_a?(::String) ? ::JSON.parse(raw) : {}
+          parsed = {} unless parsed.is_a?(::Hash)
+          { action: reactive_request_total(parsed["action"]), defer: reactive_request_total(parsed["defer"]) }
+        rescue ::JSON::ParserError
+          { action: 0, defer: 0 }
+        end
+
+        # One total as an Integer. Only a number or a numeric string counts; any
+        # other JSON value (array, object, boolean, null) is garbled, so zero.
+        def self.reactive_request_total(value)
+          value.is_a?(::Numeric) || value.is_a?(::String) ? value.to_i : 0
+        end
+        private_class_method :reactive_request_total
+
         # Block until the reactive layer is IDLE — every dispatch round trip and
         # deferred render has settled and the <html data-reactive-active> marker is
         # gone. The system-test twin of wait_for_turbo (which watches the Turbo
@@ -92,6 +116,42 @@ module Phlex
         def have_reactive_text(id, value, **)
           have_css("##{id}", text: value, **)
         end
+
+        # How many reactive requests the page has made since the last
+        # reset_reactive_requests! (or since the page loaded), per kind (issue
+        # #279):
+        #
+        #   reactive_request_count # => { action: 1, defer: 0 }
+        #
+        # A snapshot, not a wait — barrier on wait_for_reactive (or use
+        # have_reactive_requests) before reading it after a gesture.
+        def reactive_request_count
+          System.parse_reactive_requests(
+            page.evaluate_script("document.documentElement.getAttribute(#{REQUESTS_ATTR.to_json})")
+          )
+        end
+
+        # Baseline the request totals to zero. The attribute IS the client's
+        # store, so writing zeros re-baselines it — including after a Turbo Drive
+        # visit, where the <html> element (and its totals) survives navigation.
+        def reset_reactive_requests!
+          zeros = { action: 0, defer: 0 }.to_json
+          page.execute_script("document.documentElement.setAttribute(#{REQUESTS_ATTR.to_json}, '#{zeros}')")
+          nil
+        end
+
+        # Assert (waiting) that exactly `count` reactive requests were made — of
+        # `kind` (:action or :defer), or of any kind — since the last reset, AND
+        # that nothing is still in flight. Fails at once if the count overshoots
+        # (totals only grow until a reset).
+        #
+        #   reset_reactive_requests!
+        #   find("#open-panel").click
+        #   expect(page).to have_reactive_requests(1)
+        #   expect(page).to have_reactive_requests(0, kind: :defer)
+        def have_reactive_requests(count, kind: nil, timeout: nil, wait: nil)
+          ReactiveRequestsMatcher.new(count, kind:, wait: timeout || wait)
+        end
         # rubocop:enable Naming/PredicatePrefix
 
         # A waiting matcher that asserts a field's live `.value` PROPERTY (issue
@@ -190,3 +250,5 @@ module Phlex
     end
   end
 end
+
+require "phlex/reactive/test_helpers/system/reactive_requests_matcher"

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.3"
+    VERSION = "0.14.0"
   end
 end

data/lib/phlex/reactive.rb

@@ -133,6 +133,12 @@ module Phlex
       # ActionPolicy::Unauthorized, ...).
       attr_accessor :authorization_errors
 
+      # Import maps `phlex_reactive:doctor` checks for the `phlex/reactive/early`
+      # pin (issue #307): a callable returning `{ name => Importmap::Map }`, for
+      # an app with more than one map (one per entry point). nil (the default)
+      # checks `Rails.application.importmap` only.
+      attr_accessor :importmaps
+
       # The path the action endpoint is mounted at. Default "/reactive/actions".
       # Set before boot if it collides with an app route. The client runtime
       # reads it from a <meta name="phlex-reactive-action-path"> tag if present,
@@ -532,6 +538,29 @@ module Phlex
         instance.view_context
       end
 
+      # --- Early triggers (issue #273) -----------------------------------
+
+      # How long (ms) a trigger captured by phlex/reactive/early before the
+      # controller connected stays replayable. Older entries are dropped on
+      # connect (warned under data-reactive-verbose): a click from long ago must
+      # not fire a request out of nowhere. The client reads it from a meta tag
+      # in the host layout (the engine can't inject into it):
+      #   <meta name="phlex-reactive-early-ttl" content="<%= Phlex::Reactive.early_event_ttl_ms %>">
+      # Without the meta the client uses the same 10 s default. nil resets.
+      # Validated at assignment: the client reads a non-positive TTL as "use
+      # the default", so 0 can never mean "replay nothing" — fail here instead.
+      def early_event_ttl_ms=(value)
+        unless value.nil? || (value.is_a?(Integer) && value.positive?)
+          raise ArgumentError, "early_event_ttl_ms must be a positive Integer (milliseconds) or nil, got #{value.inspect}"
+        end
+
+        @early_event_ttl_ms = value
+      end
+
+      def early_event_ttl_ms
+        @early_event_ttl_ms ||= 10_000
+      end
+
       # --- Deferred reply segments (issue #165) --------------------------
 
       # Lifetime (seconds) of a defer token. It only needs to cover the
@@ -552,6 +581,44 @@ module Phlex
         @defer_path ||= "/reactive/defer"
       end
 
+      # The path prefix of the cacheable-fragment GET endpoint (issue #277):
+      # GET <fragment_path>/<signed id>. Default "/reactive/fragment"; set
+      # before boot if it collides. The shell renders the full URL, but the
+      # client only fetches one under the path it knows: when you change this,
+      # also render <meta name="phlex-reactive-fragment-path" content="…">.
+      attr_writer :fragment_path
+
+      def fragment_path
+        @fragment_path ||= "/reactive/fragment"
+      end
+
+      # The longest max-age (seconds) a `reactive_lazy cache:` component may
+      # ask the browser to keep its fragment for. A component declaring more
+      # is answered with this cap. Within max-age the browser reuses its copy
+      # WITHOUT asking the server — so this also bounds how long a revoked
+      # permission can keep showing a stale fragment. Default 1 hour; nil
+      # restores it; 0 makes every cached fragment revalidate on each use.
+      def fragment_cache_max_age_limit=(value)
+        seconds = value.is_a?(ActiveSupport::Duration) && value.to_i == value ? value.to_i : value
+        unless seconds.nil? || (seconds.is_a?(::Integer) && !seconds.negative?)
+          raise ArgumentError,
+            "Phlex::Reactive.fragment_cache_max_age_limit must be a whole, non-negative number of seconds " \
+            "(or nil for the default) — got #{value.inspect}"
+        end
+
+        @fragment_cache_max_age_limit = seconds
+      end
+
+      def fragment_cache_max_age_limit
+        @fragment_cache_max_age_limit ||= 3600
+      end
+
+      # The deterministic, no-expiry, purpose-scoped fragment id of an identity
+      # payload, and its verification (issue #277). See Phlex::Reactive::Fragment.
+      def sign_fragment(payload) = Fragment.sign(payload)
+
+      def verify_fragment(id) = Fragment.verify(id)
+
       # How deferred segments reach the actor: :auto (push iff capable, else
       # pull), :fetch (always pull), :stream (push; degrades to pull with a
       # warning when the capability is absent). Validated at assignment — a
@@ -1056,6 +1123,7 @@ module Phlex
       # The controller a correctly-mounted action path resolves to. Used by the
       # route guard below.
       ACTIONS_CONTROLLER = "phlex/reactive/actions"
+      FRAGMENTS_CONTROLLER = "phlex/reactive/fragments"
 
       # True when a POST to `path` resolves to the gem's ActionsController. A host
       # catch-all route (match "*path", ...) appended above the engine's route
@@ -1076,6 +1144,20 @@ module Phlex
         false
       end
 
+      # Does GET <fragment_path>/<id> resolve to the gem's FragmentsController
+      # (issue #277)? A host GET catch-all shadows it otherwise, and every
+      # `reactive_lazy cache:` fetch then gets the host's fallback page. The
+      # doctor reports it, like the defer route.
+      def fragment_route_ok?(path = fragment_path)
+        return false unless defined?(::Rails) && ::Rails.application
+
+        ensure_routes_loaded
+        recognized = ::Rails.application.routes.recognize_path("#{path}/probe", method: :get)
+        recognized[:controller] == FRAGMENTS_CONTROLLER
+      rescue ActionController::RoutingError, ActiveRecord::RecordNotFound
+        false
+      end
+
       # Log a clear warning (once, at boot) when the action path doesn't resolve
       # to the gem controller — pointing at the catch-all shadow rather than
       # leaving an adopter to guess. Called from the engine's after_initialize.
@@ -1184,6 +1266,8 @@ loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
 # only when Capybara is present, so the loader must ignore it (otherwise an
 # eager-load in production would define browser helpers with no Capybara).
 loader.ignore("#{lib}/phlex/reactive/test_helpers/system.rb")
+# ...and its matcher subdirectory (issue #279), required by system.rb itself.
+loader.ignore("#{lib}/phlex/reactive/test_helpers/system")
 # The MCP diagnostic tool tree (issue #168) subclasses the OPTIONAL `mcp` gem's
 # constants (MCP::Tool) at class-definition time, so the whole mcp/ subdirectory
 # must stay out of the autoloader — Phlex::Reactive::MCP.load! requires it in

data/lib/tasks/phlex_reactive.rake

@@ -12,14 +12,18 @@ namespace :phlex_reactive do
     abort unless Phlex::Reactive::Doctor.run
   end
 
-  desc "List every declared reactive action (component | action | params | file:line | auth); FORMAT=json for tooling"
+  desc "List every declared reactive action (component | action | params | file:line | auth); " \
+       "FORMAT=json for tooling, UNVERIFIED=1 for only the unverified rows"
   task actions: :environment do
     # eager_load! so every app component is in the Streamable registry the
     # Inspector reads. Plain text by default (no ANSI, like the doctor);
     # FORMAT=json emits a parseable array for tooling. Names/paths/schemas only.
+    # UNVERIFIED=1 keeps only actions with neither a detected authorization call
+    # nor a skip_verify_authorized — the review queue (issue #278).
     Rails.application.eager_load!
     format = ENV["FORMAT"].to_s.downcase == "json" ? :json : :text
-    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:)
+    unverified_only = %w[1 true yes].include?(ENV["UNVERIFIED"].to_s.downcase)
+    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:, unverified_only:)
   end
 
   desc "Fuzzy-find a reactive component and print its actions with method-definition source — phlex_reactive:find[query]"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.13.3
+  version: 0.14.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -118,6 +118,7 @@ files:
 - README.md
 - app/assets/stylesheets/phlex/reactive/effects.css
 - app/controllers/phlex/reactive/actions_controller.rb
+- app/controllers/phlex/reactive/fragments_controller.rb
 - app/javascript/phlex/reactive/compute.js
 - app/javascript/phlex/reactive/compute.min.js
 - app/javascript/phlex/reactive/compute.min.js.map
@@ -127,12 +128,43 @@ files:
 - app/javascript/phlex/reactive/confirm_predicate.js
 - app/javascript/phlex/reactive/confirm_predicate.min.js
 - app/javascript/phlex/reactive/confirm_predicate.min.js.map
+- app/javascript/phlex/reactive/core.js
+- app/javascript/phlex/reactive/core.min.js
+- app/javascript/phlex/reactive/core.min.js.map
+- app/javascript/phlex/reactive/early.js
+- app/javascript/phlex/reactive/early.min.js
+- app/javascript/phlex/reactive/early.min.js.map
+- app/javascript/phlex/reactive/features/bindings.js
+- app/javascript/phlex/reactive/features/bindings.min.js
+- app/javascript/phlex/reactive/features/bindings.min.js.map
+- app/javascript/phlex/reactive/features/compute.js
+- app/javascript/phlex/reactive/features/compute.min.js
+- app/javascript/phlex/reactive/features/compute.min.js.map
+- app/javascript/phlex/reactive/features/defer.js
+- app/javascript/phlex/reactive/features/defer.min.js
+- app/javascript/phlex/reactive/features/defer.min.js.map
+- app/javascript/phlex/reactive/features/devtools.js
+- app/javascript/phlex/reactive/features/devtools.min.js
+- app/javascript/phlex/reactive/features/devtools.min.js.map
+- app/javascript/phlex/reactive/features/effects.js
+- app/javascript/phlex/reactive/features/effects.min.js
+- app/javascript/phlex/reactive/features/effects.min.js.map
+- app/javascript/phlex/reactive/features/form.js
+- app/javascript/phlex/reactive/features/form.min.js
+- app/javascript/phlex/reactive/features/form.min.js.map
+- app/javascript/phlex/reactive/features/hints.js
+- app/javascript/phlex/reactive/features/hints.min.js
+- app/javascript/phlex/reactive/features/hints.min.js.map
+- app/javascript/phlex/reactive/features/persist.js
+- app/javascript/phlex/reactive/features/persist.min.js
+- app/javascript/phlex/reactive/features/persist.min.js.map
 - app/javascript/phlex/reactive/inspect.js
 - app/javascript/phlex/reactive/inspect.min.js
 - app/javascript/phlex/reactive/inspect.min.js.map
 - app/javascript/phlex/reactive/reactive_controller.js
 - app/javascript/phlex/reactive/reactive_controller.min.js
 - app/javascript/phlex/reactive/reactive_controller.min.js.map
+- app/javascript/phlex/reactive/runtime.js
 - lib/generators/phlex/reactive/claude/USAGE
 - lib/generators/phlex/reactive/claude/claude_generator.rb
 - lib/generators/phlex/reactive/component/USAGE
@@ -160,11 +192,15 @@ files:
 - lib/phlex/reactive/component/identity.rb
 - lib/phlex/reactive/component/lazy.rb
 - lib/phlex/reactive/component/registry.rb
+- lib/phlex/reactive/component/selection.rb
 - lib/phlex/reactive/defer.rb
 - lib/phlex/reactive/deferred_render_job.rb
 - lib/phlex/reactive/doctor.rb
+- lib/phlex/reactive/doctor/fiber_isolation.rb
+- lib/phlex/reactive/dormant.rb
 - lib/phlex/reactive/effects.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/fragment.rb
 - lib/phlex/reactive/inspector.rb
 - lib/phlex/reactive/inspector/report.rb
 - lib/phlex/reactive/js.rb
@@ -180,6 +216,7 @@ files:
 - lib/phlex/reactive/mcp/tools/find_tool.rb
 - lib/phlex/reactive/param_schema.rb
 - lib/phlex/reactive/pending.rb
+- lib/phlex/reactive/pending/markup.rb
 - lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
 - lib/phlex/reactive/settle.rb
@@ -190,6 +227,7 @@ files:
 - lib/phlex/reactive/test_helpers.rb
 - lib/phlex/reactive/test_helpers/matchers.rb
 - lib/phlex/reactive/test_helpers/system.rb
+- lib/phlex/reactive/test_helpers/system/reactive_requests_matcher.rb
 - lib/phlex/reactive/version.rb
 - lib/tasks/phlex_reactive.rake
 homepage: https://github.com/zoolutions/phlex-reactive