phlex-reactive 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913a7629041138c8daf5a4538e694a557f77aeffd137fe7320ce1654efff6aae
-  data.tar.gz: ea6dc93c905242537e00b05d651b98cbea3933a9188e0ae0e10594c87b997504
+  metadata.gz: 25876f4b6f97e3cd517a4b5a575e3156ac7cadd4025e9f5cdf5f10b0bb001346
+  data.tar.gz: f5ea2f6cee8e7b17f66725549e98f2bc9d1cc3c29cf90acfb2d1b88c1176e2ea
 SHA512:
-  metadata.gz: 49f1fbd3b2caa40817f91968e4c39658e8fb02a6ab11850ef8a5a5ba7c5f901b4910e7196642b670c61b74060242f550740937b60c71a8fee3af31c5a080f270
-  data.tar.gz: e1fcfbbc3f8c2cb3e22b0929830f7191f59d440b3b1b023a14222547c74fef509face1fdfed4d3a19b3ef13df33f7d4584a1545cc67970cce9ad8de637daf6bf
+  metadata.gz: ec2bc617e5a888e268e6e746f85a225e92d88145114687be55b825c9659b2d9ef75b35d25d67d6dc950070acadf3f387b2d2608108f4b91d2a0dfcd8982495e1
+  data.tar.gz: c2249b5dd3783ec5f9d4881290e15030ca4de9e6e4e1af238f239feb55c63df76a5c5f4d1098e9bb1022547766752a03825b63d7dac60830dcc6cd5526d929ca

data/CHANGELOG.md

@@ -6,6 +6,27 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.0]
+
+### Added
+
+- **Actor-echo suppression.** `broadcast_*_to` now accepts `exclude:` (and
+  `visible_to:`), forwarded to the stream transport. Pass
+  `exclude: reactive_connection_id` from an action so the actor doesn't receive
+  the echo of its own broadcast — making `append`/`prepend` and optimistic UI
+  safe. The client sends its SSE connection id as `X-Pgbus-Connection`; the
+  endpoint exposes it via `Phlex::Reactive.current_connection_id` /
+  `reactive_connection_id`. Honored by pgbus; ignored (harmless) on Action Cable.
+
+### Requires
+
+- **pgbus >= 0.9.4** when using `exclude:`/`visible_to:` — it ships the
+  `exclude:`/`visible_to:`/`event:` forwarding through Turbo's broadcast
+  helpers. phlex-reactive still works on Action Cable without pgbus; the
+  `exclude:` argument is simply ignored there.
+
+## [0.1.0]
+
 ### Added
 
 - `Phlex::Reactive::Streamable` — class methods (`replace`, `update`, `append`,
@@ -22,5 +43,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   synchronous token threading, auto field collection; no per-feature controllers.
 - Rails engine — mounts the action endpoint, registers and auto-pins the client
   runtime for importmap apps.
+- **Generators.** `rails g phlex:reactive:install` registers the `reactive`
+  Stimulus controller (eagerly) and writes a config initializer.
+  `rails g phlex:reactive:component Name [actions] [--record name | --state vars]`
+  scaffolds a reactive component (and an RSpec spec when the app uses RSpec),
+  state-backed by default or record-backed with `--record`.
 
-[Unreleased]: https://github.com/mhenrixon/phlex-reactive/commits/main
+[Unreleased]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/mhenrixon/phlex-reactive/releases/tag/v0.1.0

data/README.md

@@ -1,9 +1,15 @@
 # phlex-reactive
 
+[![CI](https://github.com/mhenrixon/phlex-reactive/actions/workflows/main.yml/badge.svg)](https://github.com/mhenrixon/phlex-reactive/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/phlex-reactive)](https://rubygems.org/gems/phlex-reactive)
+[![Docs](https://img.shields.io/badge/docs-mhenrixon.github.io-blue)](https://mhenrixon.github.io/phlex-reactive)
+
 **Reactive [Phlex](https://www.phlex.fun) components for Rails — Livewire-style
 actions and live cross-tab updates, without writing Stimulus controllers or
 hand-picking Turbo Stream targets.**
 
+📖 **[Full documentation](https://mhenrixon.github.io/phlex-reactive)**
+
 ```ruby
 class Counter < ApplicationComponent
   include Phlex::Reactive::Streamable
@@ -75,9 +81,19 @@ gem "phlex-reactive"
 bundle install
 ```
 
-That's it for **importmap** apps — the engine mounts the action endpoint at
-`/reactive/actions` and auto-pins (and preloads) the client runtime. Register
-the controller eagerly so a click immediately after load is never missed:
+Then run the installer — it registers the client controller and writes a config
+initializer:
+
+```bash
+bin/rails generate phlex:reactive:install
+```
+
+That's all for **importmap** apps: the engine mounts the action endpoint at
+`/reactive/actions` and auto-pins (and preloads) the client runtime, and the
+installer adds the eager registration below to your Stimulus entrypoint.
+
+<details>
+<summary>What the installer wires (or do it by hand)</summary>
 
 ```js
 // app/javascript/controllers/index.js
@@ -86,6 +102,21 @@ import ReactiveController from "phlex/reactive/reactive_controller"
 application.register("reactive", ReactiveController)
 ```
 
+Register eagerly (not lazily) so a click immediately after load is never missed.
+</details>
+
+### Scaffold a component
+
+```bash
+# state-backed (record-less)
+bin/rails generate phlex:reactive:component Counter increment decrement
+
+# record-backed (signed GlobalID identity)
+bin/rails generate phlex:reactive:component Todos::Item toggle rename --record todo
+```
+
+Generates the component (and an RSpec spec if your app uses RSpec).
+
 <details>
 <summary>esbuild / webpack / bun</summary>
 
@@ -234,6 +265,19 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
 in the schema is dropped before reaching your method.
 
+**Combining `on(...)` / `reactive_attrs` with your own attributes.** Both return
+a hash that includes a `data:` key. Spreading them *and* passing another `data:`
+(or `class:`, `id:`) would clobber it — use Phlex's `mix` to deep-merge:
+
+```ruby
+# ✅ merges cleanly (data-action survives, your data-testid/class are added)
+button(**mix(on(:increment), class: "btn", data: { testid: "inc" })) { "+" }
+div(**mix(reactive_attrs, id:, class: "card")) { ... }
+
+# ❌ the extra data: overwrites on()'s data:, so the action never binds
+button(**on(:increment), data: { testid: "inc" }) { "+" }
+```
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby

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

@@ -52,12 +52,19 @@ module Phlex
       # Run the action inside a transaction so transactional broadcasts (pgbus
       # broadcasts_to ... durable:) defer to after_commit and never fire for a
       # rolled-back change. Override to add per-request instrumentation.
+      #
+      # The actor's SSE connection id (sent as X-Pgbus-Connection) is exposed
+      # for the duration of the action via Phlex::Reactive.current_connection_id,
+      # so a broadcast in the action can pass exclude: reactive_connection_id
+      # and skip the actor's own echo.
       def run_action(component, action_def, coerced)
-        transaction_wrapper do
-          if coerced.any?
-            component.public_send(action_def.name, **coerced)
-          else
-            component.public_send(action_def.name)
+        Phlex::Reactive.with_connection_id(request.headers["X-Pgbus-Connection"]) do
+          transaction_wrapper do
+            if coerced.any?
+              component.public_send(action_def.name, **coerced)
+            else
+              component.public_send(action_def.name)
+            end
           end
         end
       end
@@ -97,7 +104,7 @@ module Phlex
       def coerce(value, type)
         case type
         when :integer then value.to_i
-        when :float   then value.to_f
+        when :float then value.to_f
         when :boolean then ActiveModel::Type::Boolean.new.cast(value)
         else value.to_s
         end
@@ -107,7 +114,7 @@ module Phlex
       # already gates this; defense in depth against constant injection.
       def resolve_component(name)
         klass = name.to_s.safe_constantize
-        unless klass && klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+        unless klass&.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
           raise Phlex::Reactive::InvalidToken
         end
 

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

@@ -60,13 +60,20 @@ export default class extends Controller {
     this.element.setAttribute("aria-busy", "true")
 
     try {
+      const headers = {
+        "Content-Type": "application/json",
+        Accept: "text/vnd.turbo-stream.html",
+        "X-CSRF-Token": this.#csrfToken(),
+      }
+      // Send the pgbus SSE connection id (if subscribed) so the server can
+      // exclude this connection from its own broadcast echo — the actor
+      // already gets the action's HTTP response. Harmless without pgbus.
+      const connectionId = this.#connectionId()
+      if (connectionId) headers["X-Pgbus-Connection"] = connectionId
+
       const response = await fetch(this.#actionPath(), {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Accept: "text/vnd.turbo-stream.html",
-          "X-CSRF-Token": this.#csrfToken(),
-        },
+        headers,
         body,
         credentials: "same-origin",
       })
@@ -146,4 +153,17 @@ export default class extends Controller {
   #csrfToken() {
     return document.querySelector('meta[name="csrf-token"]')?.content ?? ""
   }
+
+  // The pgbus SSE connection id, if the page is subscribed to a stream. pgbus
+  // reflects it onto the <pgbus-stream-source connection-id="…"> element (and
+  // apps may mirror it to <meta name="pgbus-connection-id">). Returns null
+  // when not present (e.g. no pgbus, or no active subscription) — the header
+  // is then simply omitted.
+  #connectionId() {
+    return (
+      document.querySelector("pgbus-stream-source[connection-id]")?.getAttribute("connection-id") ||
+      document.querySelector('meta[name="pgbus-connection-id"]')?.content ||
+      null
+    )
+  }
 }

data/lib/generators/phlex/reactive/component/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Scaffolds a reactive Phlex component (and an RSpec spec) with the given
+    actions. State-backed by default; pass --record for a record-backed
+    component whose identity is a signed GlobalID.
+
+Examples:
+    bin/rails generate phlex:reactive:component Counter increment decrement
+        State-backed component with two actions, signed state (default :value).
+
+    bin/rails generate phlex:reactive:component Counter increment --state count
+        State-backed, signing @count.
+
+    bin/rails generate phlex:reactive:component Todos::Item toggle rename --record todo
+        Record-backed component; identity = todo.to_gid; #id = dom_id(@todo).

data/lib/generators/phlex/reactive/component/component_generator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Phlex
+  module Reactive
+    module Generators
+      # `rails g phlex:reactive:component Counter [actions] [options]`
+      #
+      # Examples:
+      #   rails g phlex:reactive:component Counter increment decrement
+      #     → state-backed component with two actions
+      #
+      #   rails g phlex:reactive:component Todos::Item toggle rename --record=todo
+      #     → record-backed component (signed GlobalID) with two actions
+      #
+      # Generates the component under app/components and a matching spec under
+      # spec/components (or test/components for Minitest apps).
+      class ComponentGenerator < ::Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        argument :actions, type: :array, default: [], banner: "action action"
+
+        class_option :record, type: :string, default: nil,
+          desc: "Record-backed component: the init kwarg / GlobalID record name (e.g. --record=todo)"
+        class_option :state, type: :array, default: nil,
+          desc: "State-backed: instance vars to sign (e.g. --state=count open). Default for record-less."
+
+        def create_component
+          @component_path = File.join("app/components", class_path, "#{file_name}.rb")
+          template "component.rb.erb", File.join(destination_root, @component_path)
+        end
+
+        def create_spec
+          return unless defined_rspec?
+
+          @spec_path = File.join("spec/components", class_path, "#{file_name}_spec.rb")
+          template "component_spec.rb.erb", File.join(destination_root, @spec_path)
+        end
+
+        private
+
+        def record_name
+          options[:record]&.to_sym
+        end
+
+        def record_backed?
+          record_name.present?
+        end
+
+        def state_keys
+          options[:state] || (record_backed? ? [] : %w[value])
+        end
+
+        def action_names
+          actions.presence || %w[example_action]
+        end
+
+        def defined_rspec?
+          File.directory?(File.join(destination_root, "spec"))
+        end
+      end
+    end
+  end
+end

data/lib/generators/phlex/reactive/component/templates/component.rb.erb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+<% if record_backed? -%>
+  reactive_record :<%= record_name %>
+<% action_names.each do |a| -%>
+  action :<%= a %>
+<% end -%>
+
+  def initialize(<%= record_name %>:)
+    @<%= record_name %> = <%= record_name %>
+  end
+
+  def id = dom_id(@<%= record_name %>)
+<% action_names.each do |a| -%>
+
+  def <%= a %>
+    # authorize! @<%= record_name %>, :update?   # authorize mutating actions
+    # @<%= record_name %>.update!(...)
+  end
+<% end -%>
+
+  def view_template
+    div(id:, **reactive_attrs) do
+<% action_names.each do |a| -%>
+      button(**on(:<%= a %>)) { "<%= a.to_s.humanize %>" }
+<% end -%>
+    end
+  end
+<% else -%>
+  reactive_state <%= state_keys.map { |k| ":#{k}" }.join(", ") %>
+<% action_names.each do |a| -%>
+  action :<%= a %>
+<% end -%>
+
+  def initialize(<%= state_keys.map { |k| "#{k}: nil" }.join(", ") %>)
+<% state_keys.each do |k| -%>
+    @<%= k %> = <%= k %>
+<% end -%>
+  end
+
+  def id = "<%= file_name.dasherize %>"
+<% action_names.each do |a| -%>
+
+  def <%= a %>
+    # mutate @<%= state_keys.first %> here
+  end
+<% end -%>
+
+  def view_template
+    div(id:, **reactive_attrs) do
+<% state_keys.each do |k| -%>
+      span(data: { <%= file_name %>_<%= k %>: true }) { @<%= k %>.to_s }
+<% end -%>
+<% action_names.each do |a| -%>
+      button(**on(:<%= a %>)) { "<%= a.to_s.humanize %>" }
+<% end -%>
+    end
+  end
+<% end -%>
+end

data/lib/generators/phlex/reactive/component/templates/component_spec.rb.erb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe <%= class_name %> do
+  describe "reactive declarations" do
+<% action_names.each do |a| -%>
+    it "declares the :<%= a %> action" do
+      expect(described_class.reactive_action?(:<%= a %>)).to be(true)
+    end
+<% end -%>
+  end
+<% if record_backed? -%>
+
+  describe "identity" do
+    it "signs the record's GlobalID into a verifiable token" do
+      # record = <%= record_name %>_fixture_or_factory
+      # token = described_class.new(<%= record_name %>: record).send(:reactive_token)
+      # expect(Phlex::Reactive.verify(token)["gid"]).to eq(record.to_gid.to_s)
+      skip "provide a <%= record_name %> record to assert identity round-trip"
+    end
+  end
+<% else -%>
+
+  describe "identity" do
+    it "signs state into a verifiable token and rebuilds it" do
+      component = described_class.new(<%= state_keys.map { |k| "#{k}: #{k == state_keys.first ? "1" : "nil"}" }.join(", ") %>)
+      payload = Phlex::Reactive.verify(component.send(:reactive_token))
+      expect(payload["c"]).to eq("<%= class_name %>")
+      expect(described_class.from_identity(payload)).to be_a(described_class)
+    end
+  end
+<% end -%>
+end

data/lib/generators/phlex/reactive/install/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Sets up phlex-reactive in your app: registers the generic `reactive`
+    Stimulus controller (eagerly) and writes a config initializer.
+
+    The action endpoint (POST /reactive/actions) and the client auto-pin are
+    provided by the engine, so this only wires the host-app bits.
+
+Example:
+    bin/rails generate phlex:reactive:install
+
+    Registers the controller in app/javascript/controllers/index.js and
+    creates config/initializers/phlex_reactive.rb.

data/lib/generators/phlex/reactive/install/install_generator.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Phlex
+  module Reactive
+    module Generators
+      # `rails g phlex:reactive:install`
+      #
+      # One-command setup for phlex-reactive:
+      #   * registers the generic `reactive` Stimulus controller (eagerly)
+      #   * writes a config initializer with the common options commented out
+      #
+      # The action endpoint and client auto-pin are provided by the engine, so
+      # this generator only wires the bits that live in the host app.
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        IMPORT_LINE = 'import ReactiveController from "phlex/reactive/reactive_controller"'
+        REGISTER_LINE = 'application.register("reactive", ReactiveController)'
+
+        def create_initializer
+          template "phlex_reactive.rb.erb", "config/initializers/phlex_reactive.rb"
+        end
+
+        # Register the controller eagerly in the Stimulus entrypoint. Eager (not
+        # lazy) so a click immediately after page load is never missed.
+        def register_stimulus_controller
+          index = stimulus_index_path
+
+          unless index
+            say_status :skip, "no Stimulus controllers entrypoint found — register manually:\n" \
+                              "    #{IMPORT_LINE}\n    #{REGISTER_LINE}", :yellow
+            return
+          end
+
+          if File.read(index).include?(REGISTER_LINE)
+            say_status :identical, relative(index), :blue
+            return
+          end
+
+          inject_into_file index, after: %r{import \{ application \} from ["']controllers/application["']\n} do
+            "#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
+          end
+
+          # Fallback: if the standard import line wasn't found, append both lines.
+          unless File.read(index).include?(REGISTER_LINE)
+            append_to_file index, "\n#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
+          end
+        end
+
+        def show_post_install
+          say_status :info, "phlex-reactive installed. Include the mixins in a component:", :green
+          say <<~MSG
+
+            class Counter < ApplicationComponent
+              include Phlex::Reactive::Streamable
+              include Phlex::Reactive::Component
+              # ... reactive_state / reactive_record, action :name, on(:name) ...
+            end
+
+            Scaffold one with:  rails g phlex:reactive:component Counter
+          MSG
+        end
+
+        private
+
+        def stimulus_index_path
+          %w[
+            app/javascript/controllers/index.js
+            app/javascript/controllers/application.js
+          ].map { |p| File.join(destination_root, p) }.find { |p| File.exist?(p) }
+        end
+
+        def relative(path)
+          path.sub("#{destination_root}/", "")
+        end
+      end
+    end
+  end
+end

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# phlex-reactive configuration. The engine mounts POST /reactive/actions and
+# auto-pins the client runtime; these options are the ones you typically tune.
+
+# Inherit auth/CSRF/Current on the action endpoint (recommended for real apps).
+# Ensure the endpoint isn't force-redirected to a login page for logged-out
+# users if you have public reactive components.
+# Phlex::Reactive.base_controller_name = "ApplicationController"
+
+# Render components with your app's view context (helpers, Current, etc.).
+# Phlex::Reactive.renderer = ApplicationController
+
+# Render your authorization library's error as 403 from a reactive action.
+# Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]
+# Phlex::Reactive.authorization_errors = [ActionPolicy::Unauthorized]
+
+# Sign identity tokens with a dedicated key instead of secret_key_base.
+# Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(ENV["REACTIVE_KEY"])
+
+# Change the action endpoint path (default "/reactive/actions"). If you change
+# it, expose it to the client with:
+#   <meta name="phlex-reactive-action-path" content="<%%= Phlex::Reactive.action_path %>">
+# Phlex::Reactive.action_path = "/_r/actions"

data/lib/phlex/reactive/component.rb

@@ -116,6 +116,21 @@ module Phlex
         end
       end
 
+      # The acting client's SSE connection id during the current action (nil
+      # outside an action, or when the client isn't subscribed to a stream).
+      # Pass it as `exclude:` when broadcasting from an action so the actor
+      # doesn't receive the echo of its own change — it already gets the
+      # action's HTTP response:
+      #
+      #   def send_message(body:)
+      #     msg = ChatMessage.create!(room: @room, body:)
+      #     ChatMessage::Item.broadcast_append_to("chat", @room,
+      #       target: "messages", model: msg, exclude: reactive_connection_id)
+      #   end
+      def reactive_connection_id
+        Phlex::Reactive.current_connection_id
+      end
+
       # Root-element attributes: marks the element reactive and carries the
       # signed identity token. Spread onto the root:
       #   div(id:, **reactive_attrs) { ... }
@@ -154,12 +169,12 @@ module Phlex
         payload =
           if self.class.reactive_record_key
             record = instance_variable_get(:"@#{self.class.reactive_record_key}")
-            { "c" => self.class.name, "gid" => record.to_gid.to_s }
+            {"c" => self.class.name, "gid" => record.to_gid.to_s}
           else
             state = self.class.reactive_state_keys.to_h do |k|
               [k.to_s, instance_variable_get(:"@#{k}").as_json]
             end
-            { "c" => self.class.name, "s" => state }
+            {"c" => self.class.name, "s" => state}
           end
 
         Phlex::Reactive.sign(payload)

data/lib/phlex/reactive/streamable.rb

@@ -35,11 +35,18 @@ module Phlex
         end
 
         def component_args(model, options)
-          { model_param_name => model }.merge(options)
+          {model_param_name => model}.merge(options)
         end
 
+        # Turbo::Streams::TagBuilder needs a real VIEW CONTEXT (it calls
+        # `.formats` on it), not a controller class. Build one off-request from
+        # the configured renderer controller. Memoized per class.
         def turbo_stream_builder
-          ::Turbo::Streams::TagBuilder.new(renderer)
+          ::Turbo::Streams::TagBuilder.new(turbo_view_context)
+        end
+
+        def turbo_view_context
+          renderer.new.view_context
         end
 
         # Render a component to HTML with a full Rails view context. Routing
@@ -83,37 +90,49 @@ module Phlex
         # broadcaster builds the key itself, and double-keying can trip the
         # transport's separator guard.
 
-        def broadcast_replace_to(*streamables, model: nil, **options)
+        # `exclude:` / `visible_to:` are TRANSPORT options forwarded to the
+        # stream (pgbus), not component init args. `exclude:` is the actor's
+        # connection id — pass it to suppress the actor's own echo (the actor
+        # already got the action's HTTP response). With Action Cable these are
+        # ignored; with pgbus they reach the dispatcher. See docs/broadcasting.
+        def broadcast_replace_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
           component = build(model, options)
           ::Turbo::StreamsChannel.broadcast_replace_to(
-            *streamables, target: component.id, html: render_component(component)
+            *streamables, target: component.id, html: render_component(component),
+            **broadcast_transport_opts(exclude:, visible_to:)
           )
         end
 
-        def broadcast_update_to(*streamables, model: nil, **options)
+        def broadcast_update_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
           component = build(model, options)
           ::Turbo::StreamsChannel.broadcast_update_to(
-            *streamables, target: component.id, html: render_component(component)
+            *streamables, target: component.id, html: render_component(component),
+            **broadcast_transport_opts(exclude:, visible_to:)
           )
         end
 
-        def broadcast_append_to(*streamables, target:, model: nil, **options)
+        def broadcast_append_to(*streamables, target:, model: nil, exclude: nil, visible_to: nil, **options)
           component = build(model, options)
           ::Turbo::StreamsChannel.broadcast_append_to(
-            *streamables, target:, html: render_component(component)
+            *streamables, target:, html: render_component(component),
+            **broadcast_transport_opts(exclude:, visible_to:)
           )
         end
 
-        def broadcast_prepend_to(*streamables, target:, model: nil, **options)
+        def broadcast_prepend_to(*streamables, target:, model: nil, exclude: nil, visible_to: nil, **options)
           component = build(model, options)
           ::Turbo::StreamsChannel.broadcast_prepend_to(
-            *streamables, target:, html: render_component(component)
+            *streamables, target:, html: render_component(component),
+            **broadcast_transport_opts(exclude:, visible_to:)
           )
         end
 
-        def broadcast_remove_to(*streamables, model: nil, **options)
+        def broadcast_remove_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
           component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: component.id)
+          ::Turbo::StreamsChannel.broadcast_remove_to(
+            *streamables, target: component.id,
+            **broadcast_transport_opts(exclude:, visible_to:)
+          )
         end
 
         private
@@ -122,6 +141,15 @@ module Phlex
           new(**(model ? component_args(model, options) : options))
         end
 
+        # Only include transport opts that were actually given, so on Action
+        # Cable (which doesn't accept them) the common no-opts call is unchanged.
+        def broadcast_transport_opts(exclude:, visible_to:)
+          opts = {}
+          opts[:exclude] = exclude unless exclude.nil?
+          opts[:visible_to] = visible_to unless visible_to.nil?
+          opts
+        end
+
         def renderer
           Phlex::Reactive.renderer
         end
@@ -133,6 +161,15 @@ module Phlex
         raise NotImplementedError, "#{self.class} must implement #id for Turbo Stream targeting"
       end
 
+      # Render-context-free dom_id, safe to use inside `#id`. The streamable
+      # machinery calls `#id` BEFORE rendering, so Phlex's render-time `dom_id`
+      # helper would raise HelpersCalledBeforeRenderError. This delegates to
+      # ActionView::RecordIdentifier, which works anywhere — so
+      # `def id = dom_id(@todo)` is safe.
+      def dom_id(record, prefix = nil)
+        ::ActionView::RecordIdentifier.dom_id(record, prefix)
+      end
+
       # Render THIS already-built instance as a replace stream (used by the
       # reactive action endpoint after an action mutated state).
       def to_stream_replace

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/phlex/reactive.rb

@@ -90,6 +90,23 @@ module Phlex
         verifier.generate(payload, purpose: IDENTITY_PURPOSE)
       end
 
+      # The acting client's SSE connection id during an action, or nil. Set by
+      # the ActionsController from the X-Pgbus-Connection header. A component
+      # action passes `exclude: Phlex::Reactive.current_connection_id` (or the
+      # `reactive_connection_id` helper) to suppress the actor's own broadcast
+      # echo.
+      def current_connection_id
+        Thread.current[:phlex_reactive_connection_id]
+      end
+
+      def with_connection_id(connection_id)
+        previous = Thread.current[:phlex_reactive_connection_id]
+        Thread.current[:phlex_reactive_connection_id] = connection_id.presence
+        yield
+      ensure
+        Thread.current[:phlex_reactive_connection_id] = previous
+      end
+
       private
 
       def default_verifier

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -118,6 +118,13 @@ files:
 - README.md
 - app/controllers/phlex/reactive/actions_controller.rb
 - app/javascript/phlex/reactive/reactive_controller.js
+- lib/generators/phlex/reactive/component/USAGE
+- lib/generators/phlex/reactive/component/component_generator.rb
+- lib/generators/phlex/reactive/component/templates/component.rb.erb
+- lib/generators/phlex/reactive/component/templates/component_spec.rb.erb
+- lib/generators/phlex/reactive/install/USAGE
+- lib/generators/phlex/reactive/install/install_generator.rb
+- lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb
 - lib/phlex-reactive.rb
 - lib/phlex/reactive.rb
 - lib/phlex/reactive/component.rb
@@ -146,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Reactive Phlex components for Rails — Livewire-style actions and live cross-tab
   updates, no Stimulus boilerplate.