phlex-reactive 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83d418e64d127a079e74679e4920d85803fedff629e8d8b135c2896a79b5bbdd
-  data.tar.gz: 16c68638d96348ea94c0fa25d411486e49c0b2dab01f07fe9e67fefba630a537
+  metadata.gz: 6db6575334b8d59a054812e6815dc9b1968274a7917c66ec48c353dd95ba477d
+  data.tar.gz: 294d2d892c5e8a4b55466e0102b89fe945f7b4f23e1a882b06566c6898520f03
 SHA512:
-  metadata.gz: cc16a212daaeb236631702db89fe846dabf936d532e18919c0a371d408f29ce94ae94028eff8cc82e3ff66f1ee25a8acb75f2df29f0b1e2ceb819e49ee3b7217
-  data.tar.gz: 0b9721189cb032d6a91ae163b15742cb1cb163ef93da4b5ced1d4382811b43da5b5ba3ea25041b5919b20fb58d2dd4d582d8c1ba1345b6d8accf7ac94cdeb978
+  metadata.gz: 362f900e12b5d4d0e3240d230b64b7ea1366e9109c1957c266d7695a7f3985b762ce29843c644c12dba6e91ffead0bf6ff7f7e73dc32eac046de79c5c5e3c8cc
+  data.tar.gz: 3fc968f66ea7892eba20e050e5be95ad75c878a5518052eaef4006a86b963ac3a3fd1e155d1d4b45f0ea05602d3db1decae1fbb3c75e3bd76cc93bc66a29a673

data/CHANGELOG.md

@@ -6,6 +6,35 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.6]
+
+### Added
+
+- **Action response control via `Phlex::Reactive::Response`.** An action MAY now
+  return a `Response` to govern the actor's HTTP reply, instead of only the
+  implicit single re-render. Returning anything else keeps the legacy default
+  (re-render the component in place), so existing actions are unaffected.
+  - `Response.replace(self)` / `.update(self)` — explicit re-render.
+  - `Response.replace(self).flash(:error, msg_or_component)` — surface a
+    validation error / notice (the `#1` driver). `.flash` is additive on a
+    self-replace, so the component's signed token always refreshes. Flash
+    content is supplied explicitly (the render context is off-request — there is
+    no Rails `flash`); pass a string or a Phlex component. Target container is
+    `Phlex::Reactive.flash_target` (default `flash`).
+  - `Response.remove(self)` — drop the element (e.g. a moderation queue). New
+    instance helper `Streamable#to_stream_remove` backs it.
+  - `Response.redirect(url)` — client-side `Turbo.visit` for when the current
+    URL is dead (e.g. a slug rename). Rides a 200 turbo-stream carrying a
+    `reactive:visit` custom action (registered in the client), **not** an HTTP
+    3xx (which the client bails on). Pass a `*_url`.
+  - `Response.with(*streams)` / `#stream(*more)` — multi-stream (replace self +
+    a sibling component).
+- The endpoint guarantees the component's own replace is present (token refresh)
+  for non-remove/redirect responses, and never double-prepends when the action
+  already included a self-targeted stream.
+
+## [0.2.5]
+
 ### Fixed
 
 - **Form submit navigated instead of running the reactive action.** A component

data/README.md

@@ -149,7 +149,8 @@ for broadcasting.
    │                                          verify signed token (no state trusted)
    │                                          rebuild component (record from DB)
    │                                          run the whitelisted action
-   │                                          re-render → <turbo-stream replace id>
+   │                                          re-render → <turbo-stream replace id>   (default; an action
+   │                                          may return a Response — see "Controlling the action's reply")
    └──────── Turbo morphs it in ◀───────────────────────────────┘
 
    ...and for OTHER tabs/users:
@@ -254,7 +255,7 @@ The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
 | `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
 | `.broadcast_replace_to(*streamables, model:)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable) |
 | `.broadcast_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
-| `#to_stream_replace` / `#to_stream_update` | Stream the *already-built* instance (used internally after an action) |
+| `#to_stream_replace` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `Response`) |
 
 Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 
@@ -284,6 +285,41 @@ div(**mix(reactive_attrs, id:, class: "card")) { ... }
 button(**on(:increment), data: { testid: "inc" }) { "+" }
 ```
 
+### `Phlex::Reactive::Response` — controlling the action's reply
+
+By default an action re-renders its component in place. **Return** a
+`Phlex::Reactive::Response` to do more (it governs only the actor's HTTP reply —
+cross-tab updates still use `broadcast_*_to(..., exclude: reactive_connection_id)`).
+Returning anything else keeps the default, so existing actions are unaffected.
+
+The snippets below alias the constant for brevity (`Response.replace(self)` won't
+resolve to `Phlex::Reactive::Response` inside a namespaced component — fully
+qualify it, or add the alias shown):
+
+```ruby
+Response = Phlex::Reactive::Response # or qualify each call below
+
+def rename(title:)
+  return Response.replace(self).flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
+  Response.replace(self)
+end
+
+def approve   = (@row.approve!; Response.remove(self))          # drop the element
+def publish   = (@article.publish!; Response.redirect(article_url(@article)))  # slug changed → Turbo.visit
+def add(item:) = Response.replace(self).stream(Totals.update(@order))           # multi-stream
+```
+
+| Builder | Reply |
+|---|---|
+| `Response.replace(self)` / `.update(self)` | re-render in place (explicit default) |
+| `.flash(level, content, target: …)` | append a flash; `content` is a string or Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
+| `Response.remove(self)` | remove the element (backed by `Streamable#to_stream_remove`) |
+| `Response.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
+| `Response.with(*streams)` / `#stream(*more)` | multi-stream |
+
+`.flash`/`.stream` are additive on a self-replace, so the component's signed
+token always refreshes.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -36,9 +36,9 @@ module Phlex
         component = component_class.from_identity(payload)
         coerced = coerce_params(action_def.params)
 
-        run_action(component, action_def, coerced)
+        result = run_action(component, action_def, coerced)
 
-        render turbo_stream: component.to_stream_replace
+        render turbo_stream: response_streams(result, component)
       rescue Phlex::Reactive::InvalidToken
         head :bad_request
       rescue ActiveRecord::RecordNotFound
@@ -69,6 +69,39 @@ module Phlex
         end
       end
 
+      # Turn the action's return value into the turbo-stream(s) to render for
+      # the actor. A Phlex::Reactive::Response is honored explicitly; any other
+      # value (the legacy contract — return value ignored) falls back to the
+      # implicit single replace, so existing actions are unaffected.
+      def response_streams(result, component)
+        return [component.to_stream_replace] unless result.is_a?(Phlex::Reactive::Response)
+        return [redirect_stream(result.redirect_url)] if result.redirect?
+
+        streams = result.streams
+        # Guarantee the component's signed identity token is refreshed unless the
+        # Response opted out (remove/redirect navigate away — handled above). The
+        # client reads the next token from the response body (#extractToken), so
+        # the real invariant is "a fresh data-reactive-token-value is present",
+        # NOT "some stream targets self". Checking the token directly is correct
+        # for replace AND update of self (both re-render the root via
+        # render_component, carrying the token), and still adds the fallback
+        # replace when a hand-built `with(...)` stream omits it. Idempotent: a
+        # Response.replace(self)/update(self) already carries the token, so we
+        # don't double the self-render.
+        if result.render_self? && streams.none? { |s| s.include?("data-reactive-token-value") }
+          streams = [component.to_stream_replace, *streams]
+        end
+        streams
+      end
+
+      # A 200 turbo-stream carrying a namespaced custom action the client turns
+      # into Turbo.visit — NOT an HTTP 3xx, which the client hard-bails on
+      # (response.redirected). The matching client handler is registered in
+      # reactive_controller.js.
+      def redirect_stream(url)
+        %(<turbo-stream action="reactive:visit" data-url="#{ERB::Util.html_escape(url)}"></turbo-stream>)
+      end
+
       def transaction_wrapper(&block)
         if defined?(::ActiveRecord::Base)
           ::ActiveRecord::Base.transaction(&block)

data/app/javascript/phlex/reactive/reactive_controller.js

@@ -17,6 +17,25 @@ import { Controller } from "@hotwired/stimulus"
 // .broadcast_* methods — so a click and a background broadcast converge on
 // one re-render unit.
 //
+// Custom turbo-stream action: the server tells the actor to full-navigate
+// (e.g. the record's slug changed and the current URL is now dead). It rides a
+// 200 turbo-stream — NOT an HTTP 3xx — so it never trips the response.redirected
+// bail below (which still correctly catches real auth/CSRF redirects). Registered
+// once on the Turbo global (no @hotwired/turbo import — the gem uses window.Turbo
+// everywhere, and a named import is unreliable under importmap/esbuild).
+export function registerReactiveVisit() {
+  const actions = window.Turbo?.StreamActions
+  if (!actions || actions["reactive:visit"]) return
+  actions["reactive:visit"] = function () {
+    const url = this.getAttribute("data-url")
+    if (url) window.Turbo.visit(url, { action: "advance" })
+  }
+}
+if (typeof window !== "undefined") {
+  if (window.Turbo) registerReactiveVisit()
+  else document.addEventListener("turbo:load", registerReactiveVisit, { once: true })
+}
+
 // Register this controller eagerly (not lazily) so a click immediately after
 // page load is never missed. The phlex-reactive engine auto-pins it with
 // preload: true for importmap apps; see the README for esbuild/webpack.

data/lib/phlex/reactive/response.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # An explicit, immutable description of the ACTOR's HTTP response to a
+    # reactive action. An action MAY return one; if it returns anything else
+    # (the legacy contract — return value ignored), the endpoint falls back to
+    # the implicit single component.to_stream_replace.
+    #
+    # A Response governs ONLY the actor's HTTP reply. Cross-tab updates still go
+    # through Streamable's broadcast_*_to(..., exclude: reactive_connection_id).
+    #
+    #   Response.replace(self)                          # re-render in place (the default, explicit)
+    #   Response.replace(self).flash(:error, msg)       # surface a validation error
+    #   Response.remove(self)                           # drop the element (e.g. moderation queue)
+    #   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
+
+      class << self
+        # Re-render the component in place (explicit form of today's default).
+        def replace(component) = new(streams: [component.to_stream_replace])
+
+        # Morph only inner HTML (preserves the root element + its token attr).
+        def update(component) = new(streams: [component.to_stream_update])
+
+        # Remove the component's element from the DOM. Uses the instance
+        # to_stream_remove (the component already knows its own #id — no
+        # class-builder reconstruction; works for record- and state-backed).
+        def remove(component) = new(streams: [component.to_stream_remove], render_self: false)
+
+        # Client-side full navigation (Turbo.visit). Use when the current URL
+        # is dead (slug rename) or the outcome belongs on another page. Pass a
+        # *_url (the off-request render context has no request host for *_path).
+        def redirect(url) = new(redirect_url: url, render_self: false)
+
+        # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
+        def with(*strings) = new(streams: strings.flatten)
+
+        # 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:)
+          html = content.is_a?(::Phlex::SGML) ? Phlex::Reactive.render(content) : content.to_s
+          Phlex::Reactive.flash_builder.append(target, html: html)
+        end
+      end
+
+      # render_self: when true (default for replace/update/with), the endpoint
+      # 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)
+        @streams = streams.freeze
+        @redirect_url = redirect_url
+        @render_self = render_self
+        freeze
+      end
+
+      # Append extra turbo-stream strings (a sibling component, a flash).
+      # Returns a NEW Response (immutable).
+      def stream(*more)
+        self.class.new(
+          streams: @streams + more.flatten,
+          redirect_url: @redirect_url,
+          render_self: @render_self
+        )
+      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:))
+      end
+
+      def redirect? = !@redirect_url.nil?
+      def render_self? = @render_self
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -187,6 +187,13 @@ module Phlex
       def to_stream_update
         self.class.turbo_stream_builder.update(id, html: self.class.render_component(self))
       end
+
+      # Render THIS instance as a remove stream. The component already knows its
+      # own #id, so no record/class reconstruction is needed (works for record-
+      # and state-backed components alike). Used by Response.remove.
+      def to_stream_remove
+        self.class.turbo_stream_builder.remove(id)
+      end
     end
   end
 end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.2.5"
+    VERSION = "0.2.6"
   end
 end

data/lib/phlex/reactive.rb

@@ -78,6 +78,26 @@ module Phlex
         @renderer ||= defined?(::ActionController::Base) ? ::ActionController::Base : nil
       end
 
+      # DOM id of the host-app container a Response#flash appends into.
+      # Default "flash"; override to match your layout's flash region.
+      def flash_target
+        @flash_target ||= "flash"
+      end
+
+      attr_writer :flash_target
+
+      # Render a Phlex component to HTML with a full (off-request) view context.
+      def render(component)
+        renderer.render(component, layout: false)
+      end
+
+      # A Turbo::Streams::TagBuilder bound to an off-request view context, used
+      # to build standalone streams (e.g. a Response flash append) not tied to a
+      # specific component's id.
+      def flash_builder
+        ::Turbo::Streams::TagBuilder.new(renderer.new.view_context)
+      end
+
       def base_controller_name
         @base_controller_name ||= "ActionController::Base"
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -129,6 +129,7 @@ files:
 - lib/phlex/reactive.rb
 - lib/phlex/reactive/component.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/response.rb
 - lib/phlex/reactive/streamable.rb
 - lib/phlex/reactive/version.rb
 homepage: https://github.com/mhenrixon/phlex-reactive