phlex-reactive 0.4.8 → 0.9.0

data/lib/phlex/reactive/response.rb

@@ -17,14 +17,15 @@ 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, :token_component
+      attr_reader :streams, :redirect_url, :token_component, :subject_component
 
       class << self
         # Re-render the component in place (explicit form of today's default).
         # `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])
+          new(streams: [morph ? component.to_stream_morph : component.to_stream_replace],
+            subject_component: component)
         end
 
         # Re-render the component in place via Idiomorph (issue #28). Emits
@@ -33,10 +34,14 @@ module Phlex
         # 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])
+        def morph(component) = new(streams: [component.to_stream_morph], subject_component: component)
 
-        # Morph only inner HTML (preserves the root element + its token attr).
-        def update(component) = new(streams: [component.to_stream_update])
+        # Update only inner HTML (preserves the root element + its token attr).
+        # `morph: true` morphs the inner HTML in place (issue #113) instead of
+        # replacing it, so a cross-tab update keeps a peer's focus/caret.
+        def update(component, morph: false)
+          new(streams: [component.to_stream_update(morph:)], subject_component: component)
+        end
 
         # Remove the component's element from the DOM. Uses the instance
         # to_stream_remove (the component already knows its own #id — no
@@ -130,7 +135,7 @@ module Phlex
         # 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)
+            Phlex::Reactive.stream_builder.remove(model)
           else
             definition.item.remove(model)
           end
@@ -167,18 +172,111 @@ module Phlex
 
         # 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 —
-        # supplied by the caller because the render context is off-request
-        # (there is no Rails `flash`).
-        def flash_stream(_level, content, target:)
-          Phlex::Reactive.flash_builder.append(target, html: render_html(content))
+        # the configured renderer so t()/url_for work) or a String — supplied
+        # by the caller because the render context is off-request (there is no
+        # Rails `flash`). The LEVEL reaches the wire (issue #77): string
+        # content gets a level-carrying wrapper (or the configured
+        # Phlex::Reactive.flash_component); component content renders VERBATIM
+        # — the caller owns the markup, no wrapper, no double-wrapping.
+        def flash_stream(level, content, target:, dismiss_after: nil)
+          Phlex::Reactive.stream_builder.append(target, html: flash_html(level, content, dismiss_after))
+        end
+
+        # Resolve flash `content` to HTML, carrying the level (issue #77):
+        #   * a Phlex component instance — rendered verbatim, exactly as before
+        #     (byte-identical; it also bypasses flash_component).
+        #   * a String with Phlex::Reactive.flash_component configured — the
+        #     app's component is instantiated new(level:, content:) and
+        #     rendered through the existing render_html path.
+        #   * a String otherwise — the default level-carrying wrapper below.
+        def flash_html(level, content, dismiss_after = nil)
+          # Verbatim Phlex component content owns its own markup (and lifecycle),
+          # so dismiss_after has nowhere to hang — it wraps only string content.
+          return render_html(content) if content.is_a?(::Phlex::SGML)
+
+          component_class = Phlex::Reactive.flash_component
+          if component_class
+            html = render_html(component_class.new(level:, content:))
+            return dismiss_after ? wrap_dismiss(html, dismiss_after) : html
+          end
+
+          default_flash_html(level, content, dismiss_after)
+        end
+
+        # The default string-flash wrapper:
+        #   <div class="reactive-flash reactive-flash--{level}"
+        #        data-reactive-flash-level="{level}">{content}</div>
+        # The level is unconditionally HTML-escaped (it lands in a class name
+        # and a data attribute). The content keeps the exact pre-#77 injection
+        # contract, now applied INSIDE the wrapper: ERB::Util.html_escape
+        # escapes a plain String but passes an html_safe String verbatim —
+        # the same behavior Turbo's TagBuilder gave the unwrapped string, so
+        # a model value still can't inject markup while intentional raw HTML
+        # (html_safe) still renders. The wrapper is html_safe by construction
+        # (both interpolations are escaped above), so the TagBuilder emits it
+        # as-is.
+        def default_flash_html(level, content, dismiss_after = nil)
+          level_attr = CGI.escapeHTML(level.to_s)
+          body = ERB::Util.html_escape(content.to_s)
+
+          # html_safe is safe by construction: every interpolated piece is escaped
+          # (dismiss_attr coerces to an integer, so it can't inject an attribute).
+          %(<div class="reactive-flash reactive-flash--#{level_attr}" \
+data-reactive-flash-level="#{level_attr}"#{dismiss_attr(dismiss_after)}>#{body}</div>).html_safe
+        end
+
+        # The self-dismiss attribute, or "" when off. The value is forced through
+        # to_i so a String/float (or an injection attempt) becomes a plain integer
+        # — the client's document-level handler reads it as a timeout in ms.
+        def dismiss_attr(dismiss_after)
+          return "" if dismiss_after.nil?
+
+          %( data-reactive-dismiss-after="#{dismiss_after.to_i}")
+        end
+
+        # Wrap already-rendered flash HTML (the flash_component path) in a
+        # dismiss-bearing div. SafeBuffer#to_s returns SELF, so concatenate the
+        # html_safe pieces (never .to_s + raw) to keep the buffer safe.
+        def wrap_dismiss(html, dismiss_after)
+          (%(<div#{dismiss_attr(dismiss_after)}>).html_safe + html.html_safe + "</div>".html_safe)
         end
 
         # Build a turbo-stream that updates an arbitrary target id with `content`
         # (a Phlex component instance or an HTML string). Used by #also_update to
         # re-render a companion element that isn't itself a Streamable component.
         def update_stream(target, content)
-          Phlex::Reactive.flash_builder.update(target, html: render_html(content))
+          Phlex::Reactive.stream_builder.update(target, html: render_html(content))
+        end
+
+        # Build a `reactive:js` turbo-stream carrying server-pushed client DOM
+        # ops (issue #97). `ops` is a Phlex::Reactive::JS chain or a raw
+        # [[op, args], ...] array; `target` (an element id or nil) scopes op
+        # resolution on the client (nil → document-scoped). The ops JSON is
+        # HTML-escaped into the attribute exactly like to_stream_token — a raw
+        # interpolation would be an injection vector. The client's registered
+        # reactive:js handler runs the ops through the SAME whitelist interpreter
+        # as on_client (default-deny), so an unknown op is warn-and-skipped there.
+        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} \
+data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
+        end
+
+        # Normalize `ops` to its JSON wire form, rejecting an empty chain — a
+        # reactive:js stream with no ops is a dead stream (a mistake at the call
+        # site), so fail loudly rather than emit an inert tag.
+        def js_ops_json(ops)
+          if ops.is_a?(Phlex::Reactive::JS)
+            raise ArgumentError, "js(...) got no ops — a dead reactive:js stream" if ops.empty?
+
+            ops.to_json
+          else
+            list = Array(ops)
+            raise ArgumentError, "js(...) got no ops — a dead reactive:js stream" if list.empty?
+
+            list.to_json
+          end
         end
 
         # Resolve `content` to the HTML for a turbo-stream's `html:`. Two forms,
@@ -204,11 +302,19 @@ module Phlex
       # 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)
+      #
+      # subject_component: the component a self-targeting builder (replace/morph/
+      # update) re-renders (issue #97). Distinct from token_component so it does
+      # NOT trip refresh_token? — it exists only to default #js's target to the
+      # bound component's id, so reply.morph.js(js.focus("@root")) scopes to the
+      # morphed root without the caller repeating the id.
+      def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil,
+                     subject_component: nil)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
         @token_component = token_component
+        @subject_component = subject_component
         freeze
       end
 
@@ -219,14 +325,38 @@ module Phlex
           streams: @streams + more.flatten,
           redirect_url: @redirect_url,
           render_self: @render_self,
-          token_component: @token_component
+          token_component: @token_component,
+          subject_component: @subject_component
         )
       end
 
+      # Chain a `reactive:js` op stream — server-pushed client DOM ops (issue
+      # #97) — onto this reply, so a focus/dispatch/class toggle runs on the
+      # client after the render applies:
+      #
+      #   reply.morph.js(js.focus("[name=next]").dispatch("app:saved"))
+      #
+      # `ops` is a Phlex::Reactive::JS chain (or a raw [[op, args], ...] array).
+      # `target` (an element id) scopes op resolution on the client; it defaults
+      # to the bound component's id (subject_component/token_component) so
+      # self-scoped ops (@root, a component-relative selector) just work, and is
+      # nil (document-scoped) for a subject-free reply.with. Returns a NEW
+      # Response (immutable) — the op stream rides the same stream() plumbing, so
+      # the endpoint emits it LAST (after all render streams) and a focus op sees
+      # the post-render DOM.
+      def js(ops, target: :__default)
+        resolved = target == :__default ? default_js_target : target
+        stream(self.class.js_stream(ops, target: resolved))
+      end
+
       # Append a flash turbo-stream into a host-app container (default
       # <div id="flash">, configurable via Phlex::Reactive.flash_target).
-      def flash(level, content, target: Phlex::Reactive.flash_target)
-        stream(self.class.flash_stream(level, content, target:))
+      # `dismiss_after:` (ms) makes the flash self-remove after the timeout — a
+      # document-level client handler removes any [data-reactive-dismiss-after]
+      # container, so it works for reply AND broadcast flashes (issue #100). It
+      # wraps only STRING content; a verbatim Phlex component owns its lifecycle.
+      def flash(level, content, target: Phlex::Reactive.flash_target, dismiss_after: nil)
+        stream(self.class.flash_stream(level, content, target:, dismiss_after:))
       end
 
       # Also re-render a COMPANION element alongside self — a page heading, a
@@ -259,6 +389,16 @@ module Phlex
       # 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?
+
+      private
+
+      # The default `target` for #js: the bound component's id when this reply is
+      # component-scoped (replace/morph/update set subject_component; .streams and
+      # collections set token_component), else nil — a subject-free reply.with is
+      # document-scoped unless the caller passes target: explicitly.
+      def default_js_target
+        (@subject_component || @token_component)&.id
+      end
     end
   end
 end

data/lib/phlex/reactive/stream.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # A Turbo Stream that IS an html_safe String — it drops into
+    # `render turbo_stream:`, ERB/Phlex interpolation, and Turbo test-helper
+    # substring asserts unchanged — but ALSO carries the structural facts the
+    # action endpoint needs: `rx_action`, `rx_target`, `rx_renders_root?`, and a
+    # token flag computed ONCE from ground truth (the html bytes).
+    #
+    # WHY (issue #114): the endpoint used to reverse-engineer turbo-stream
+    # SEMANTICS out of MARKUP — substring-scanning every stream for
+    # `data-reactive-token-value` and regexing the opening tag's `action="..."`
+    # against a self-render allowlist. The gem was parsing strings it just built,
+    # and every new stream shape needed a new patch to the heuristics. A Stream
+    # knows its action, target, and token-ness at CONSTRUCTION, so the endpoint
+    # reads fields instead of scanning markup.
+    #
+    # Subclasses ActiveSupport::SafeBuffer deliberately. The sole thing
+    # `render turbo_stream: [s1, s2]` does to each element is `plain_string << s`
+    # (verified against actionpack 8.1.3 / turbo-rails 2.0.23: the renderer
+    # returns the array unchanged, Response#body= stores it, and Buffer#body does
+    # `buf = +""; each { |chunk| buf << chunk }`). `String#<<` needs `#to_str`,
+    # which a SafeBuffer subclass inherits — so the ivars ride to the wire and
+    # the bytes are byte-identical to today's TagBuilder output. Being IS-A-String
+    # also satisfies every public-API interop requirement (clause 2) for free.
+    #
+    # Metadata-loss is a FEATURE, not a bug. `dup`/`+` keep the class + ivars, so
+    # they stay on the structural path with accurate fields (the bytes are
+    # unchanged). `gsub`/interpolation/`*` reshape the bytes and return a plain
+    # String/SafeBuffer — precisely when the object is no longer a
+    # structurally-known stream and SHOULD be treated as opaque. The endpoint's
+    # `is_a?(Stream) && rx_action` guard turns every such loss into the SAFE
+    # legacy regex path. INVARIANT: never `+`/`gsub`/`<<` a built Stream and keep
+    # using it as a Stream — re-`wrap` the result to recompute the flags.
+    class Stream < ActiveSupport::SafeBuffer
+      # The attribute the client's #extractToken reads. Its PRESENCE (by name) is
+      # what "carries a token" means — the same contract the old substring scan
+      # used, so an accidentally-empty token still flags true (not a regression;
+      # the real cosmos#1939 guard lives upstream in #to_stream_token).
+      TOKEN_ATTR = "data-reactive-token-value"
+
+      # Actions whose OPENING tag re-renders the component's OWN root, so the
+      # root's fresh token rolls the signed identity forward. `append`/`prepend`
+      # insert CHILDREN and are deliberately excluded (issue #44): a child row's
+      # token embedded in an append `<template>` must NEVER count as the
+      # container's refresh. `reactive:token` is our inert token-only refresh.
+      SELF_RENDER_ACTIONS = %w[replace update reactive:token].freeze
+
+      class << self
+        # The single construction seam every builder routes its already-html_safe
+        # output through. `html` MUST already be html_safe (a TagBuilder result or
+        # an explicitly `.html_safe` string) — we do NOT escape, so the wire stays
+        # byte-identical. `renders_root` is set STRUCTURALLY by the builder that
+        # knows its own semantics; `carries_token` is GROUND TRUTH.
+        def wrap(html, action:, target:, renders_root:)
+          new(html.to_s, action: action, target: target, renders_root: renders_root)
+        end
+      end
+
+      def initialize(html = "", action: nil, target: nil, renders_root: false)
+        super(html) # SafeBuffer copies the bytes verbatim — byte-identical wire.
+        @rx_action = action&.to_s
+        @rx_target = target&.to_s
+        @rx_renders_root = renders_root ? true : false
+        # ONE O(bytes) scan at BUILD time — the ground-truth token flag. A
+        # `with(...)` raw string that omits the token and a replace whose render
+        # happened to include one both answer honestly; the flag is NEVER
+        # inferred from `action` (that would reintroduce cosmos#1939).
+        @rx_carries_token = include?(TOKEN_ATTR)
+        freeze # an immutable value object
+      end
+
+      attr_reader :rx_action, :rx_target
+
+      def rx_renders_root? = @rx_renders_root
+      def rx_carries_token? = @rx_carries_token
+
+      # Does THIS stream ALREADY refresh `component_target`'s signed token by
+      # re-rendering its own root? Purely structural — replaces the two-method
+      # opening-tag regex (carries_token_for? + self_render_stream_for?). All must
+      # hold: it carries a token AND re-renders the root AND targets THIS
+      # component AND the action is a self-render action.
+      #   * A sibling replace (different target) → false, so ours still refreshes
+      #     (issue #30).
+      #   * An appended child row (renders_root false) → false, so the container's
+      #     token still refreshes even though the row embeds its own (issue #44).
+      # `component_target` is the RAW dom id (never the escaped `target="..."`
+      # attribute); escaping happens only in the emitted HTML.
+      def rx_refreshes_token_for?(component_target)
+        @rx_carries_token &&
+          @rx_renders_root &&
+          @rx_target == component_target.to_s &&
+          SELF_RENDER_ACTIONS.include?(@rx_action)
+      end
+    end
+  end
+end