reactive_component 0.8.2 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57187b540320b1d5dd751025492c59fb67e76f5afaed973f2a4fff05883ed395
-  data.tar.gz: 3f0df40aa790788a6f4e45d56607bb9a3c2bbcb7185a45e5c31b536b06da5acf
+  metadata.gz: 77acde881234cd7b6013ab8618efd2cbeb1ffd1a4c6232199517a9b14f4aa9ce
+  data.tar.gz: 1854830f220dd61bb49625a1a2a69e29d4e42ce96a40cf371586d3dd898bcbfc
 SHA512:
-  metadata.gz: 32eec25b4d7094e9568fa77fdea0618d2bcbb7f6bf0aa139cbc883f1ff8a95c9fab74c4a023ae2bdab6304aae7a0d503ade97e809c005a8df036fadc73290ac7
-  data.tar.gz: 81e833202a96c9b6be055db18d12c5c89612c446edc30e58d271a8222817bb1c8a8351b52db90754f31ed4290e9d42be86e1c35bfa439508e1f1092f0bcf1bc4
+  metadata.gz: 2721d5f6252603a600a4b297276a460cece0d4216303d40b6daa193b9d141a745c7024c347f6109463016f0f21d2beef01a083fa11d4fc3d294125973fa98630
+  data.tar.gz: 78a474176edff971af3979ca7c0b02d667c5be59e89f19b2dda28b770184f651799f0220eb2c65f5dfb47e938c4307253b52ad0bdf3df09a16a9679039bb832a

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.8.4] - 2026-09-16
+
+### Added
+- `key :company_id, :user_id` on a derived entity, for an entity keyed on a
+  tuple of values instead of one root record. It defines the readers, the
+  keyword initializer, a joined `id`, and `find` / `find_by(id:)`. A key of
+  the wrong arity resolves to nil instead of raising. The readers, the
+  initializer and `from_key` are defaults: an entity built from records
+  rather than ids replaces them, and `find` rebuilds it through `from_key`.
+- `rebuilds_on ..., entities: ->(record) { ... }` fans one commit out to
+  every entity it affects, for when the entity is not reachable through a
+  single foreign key. Mutually exclusive with `via:`.
+- Entities are `GlobalID::Identification`, so an entity used as a streamable
+  names its stream through `to_gid_param` like a model does.
+
+### Changed
+- A notify component names its record to the server with a signed global id
+  instead of a raw one, and the channel resolves it with `locate_signed`
+  scoped to this gem. The stream check is unchanged. Upgrading re-renders
+  every page, so no client keeps the old payload.
+
+### Fixed
+- The README linked to `.html` documentation URLs the site does not serve.
+
+## [0.8.3] - 2026-09-15
+
+### Added
+- Notify mode guide. A notify component re-renders from the server instead of
+  the broadcast payload, and `filter_callback` can remove it from a filtered
+  list. See Notify Mode.
+- Notify wrappers fill in the component name and record id, so
+  `live_wrapper_options` only needs `strategy: :notify`.
+- `ReactiveComponent.skip_own_broadcasts`: the component that ran a
+  `live_action` ignores the broadcast it caused and keeps its optimistic
+  update. Off by default; override per component with `live_wrapper_options`.
+- `subscribes_to ..., fields:` limits a component's update broadcasts to
+  changes in the listed columns, like `rebuilds_on ..., fields:` on entities.
+
+### Fixed
+- Notify components only react to changes to their own record. Before, every
+  notify component on a shared stream requested a re-render on any change.
+- A destroyed record's notify component is removed instead of staying on the
+  page.
+- `filter_callback` runs on every notify request, not only for components
+  that declare client state.
+- The configuration docs set `Channel` options inside `to_prepare`; the
+  previous initializer example raised `NameError`.
+
 ## [0.8.2] - 2026-09-15
 
 ### Added

data/app/channels/reactive_component/channel.rb

@@ -21,34 +21,28 @@ module ReactiveComponent
 
     def request_update(data)
       params = data['params'] || {}
-      component_class, record = subscribed_component_and_record(data, params)
+      component_class, record = subscribed_component_and_record(data)
       return unless record
 
-      if data['record_id'].present?
-        if record_matches?(record, params)
-          transmit({ 'action' => 'render', 'data' => component_class.build_data(record) })
-        else
-          transmit({ 'action' => 'remove', 'dom_id' => data['dom_id'] })
-        end
-      else
+      if record_matches?(record, params)
         client_state = params.slice(*component_class._client_state_fields.keys.map(&:to_s))
-        result = component_class.build_data(record, **client_state.symbolize_keys)
-        transmit({ 'action' => 'render', 'data' => result })
+        transmit({ 'action' => 'render', 'data' => component_class.build_data(record, **client_state.symbolize_keys) })
+      else
+        transmit({ 'action' => 'remove', 'dom_id' => data['dom_id'] })
       end
     end
 
     private
 
-    # The component must be a reactive component and the record must broadcast
-    # to the stream this subscriber verified: the same stream the wrapper
-    # signed into the page. Anything else is a guess at a record id the client
-    # was never shown.
-    def subscribed_component_and_record(data, params)
+    # The component must be a reactive component, the record must come from a
+    # signed id this gem minted, and it must broadcast to the stream this
+    # subscriber verified: the same stream the wrapper signed into the page.
+    def subscribed_component_and_record(data)
       component_class = data['component'].to_s.safe_constantize
       return unless component_class.is_a?(Class) && component_class.include?(ReactiveComponent)
 
-      record = component_class.live_model_class.find_by(id: data['record_id'] || params.delete('record_id'))
-      return unless record
+      record = locate_signed(data['sgid'])
+      return unless record.is_a?(component_class.live_model_class)
 
       stream = ReactiveComponent::Wrapper.find_stream_for(component_class, record)
       signed = Turbo::StreamsChannel.signed_stream_name(stream)
@@ -57,6 +51,14 @@ module ReactiveComponent
       [component_class, record]
     end
 
+    # An id we did not sign, one signed for another purpose, an expired one,
+    # or one pointing at a row that is gone: all of them are a miss.
+    def locate_signed(sgid)
+      GlobalID::Locator.locate_signed(sgid, for: ReactiveComponent::Wrapper::SGID_PURPOSE)
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
     def record_matches?(record, params)
       return true unless self.class.filter_callback
 
@@ -75,6 +77,7 @@ module ReactiveComponent
         stream_name = Turbo::StreamsChannel.verified_stream_name(signed)
 
         payload = { action: action, data: data }
+        payload[:request_id] = Turbo.current_request_id if Turbo.current_request_id
 
         if compress
           json = ActiveSupport::JSON.encode(payload)

data/app/javascript/reactive_component/controllers/reactive_renderer_controller.js

@@ -68,8 +68,10 @@ export default class extends Controller {
     data: { type: Object, default: {} },
     strategy: { type: String, default: "push" },
     component: { type: String, default: "" },
+    sgid: { type: String, default: "" },
     params: { type: Object, default: {} },
-    fieldMap: { type: Object, default: {} }
+    fieldMap: { type: Object, default: {} },
+    skipOwnBroadcasts: { type: Boolean, default: false }
   }
 
   connect() {
@@ -123,7 +125,7 @@ export default class extends Controller {
   }
 
   handleMessage(message) {
-    const route = routeMessage(message, this.element.id, this.strategyValue)
+    const route = routeMessage(message, this.element.id, this.strategyValue, this.ownRequestIds)
 
     switch (route.type) {
       case "render":
@@ -164,7 +166,7 @@ export default class extends Controller {
 
       sub.perform("request_update", {
         component: this.componentValue,
-        record_id: this.dataValue?.id,
+        sgid: this.sgidValue,
         dom_id: this.element.id,
         params: this.paramsValue
       })
@@ -205,9 +207,7 @@ export default class extends Controller {
 
     fetch(this.actionUrlValue, {
       method: "POST",
-      headers: {
-        "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content,
-      },
+      headers: this.actionHeaders(),
       body
     }).then(response => {
       if (!response.ok && rollbackData) {
@@ -229,6 +229,20 @@ export default class extends Controller {
     })
   }
 
+  // With skipOwnBroadcasts, tags the request so the broadcast it causes can be
+  // recognised and ignored. Turbo's header name, so turbo-rails tracks the id.
+  actionHeaders() {
+    const headers = { "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content }
+    if (!this.skipOwnBroadcastsValue) return headers
+
+    const requestId = crypto.randomUUID?.() ?? Math.random().toString(36).slice(2)
+    this.ownRequestIds ??= new Set()
+    this.ownRequestIds.add(requestId)
+    if (this.ownRequestIds.size > 20) this.ownRequestIds.delete(this.ownRequestIds.values().next().value)
+    headers["X-Turbo-Request-Id"] = requestId
+    return headers
+  }
+
   setState(event) {
     const updates = { ...event.params }
     delete updates.action

data/app/javascript/reactive_component/lib/reactive_renderer_utils.js

@@ -78,29 +78,29 @@ export function buildActionBody(actionName, actionToken, stimulusParams, formDat
   return { body, redirect }
 }
 
-export function routeMessage(message, elementId, strategy) {
+export function routeMessage(message, elementId, strategy, ownRequestIds) {
   const { action, data } = message
 
+  if (action === "update" && ownRequestIds?.has(message.request_id)) {
+    return { type: "ignore" }
+  }
+
   if (action === "render" && data?.dom_id === elementId) {
     return { type: "render", data }
   }
 
-  if (strategy === "notify" && (action === "update" || action === "destroy")) {
-    return { type: "request_update" }
+  if (action === "destroy" && data?.dom_id === elementId) {
+    return { type: "destroy" }
   }
 
   if (action === "update" && data?.dom_id === elementId) {
-    return { type: "update", data }
+    return strategy === "notify" ? { type: "request_update" } : { type: "update", data }
   }
 
   if (action === "remove" && (message.dom_id || data?.dom_id) === elementId) {
     return { type: "remove" }
   }
 
-  if (action === "destroy" && data?.dom_id === elementId) {
-    return { type: "destroy" }
-  }
-
   return { type: "ignore" }
 }
 

data/lib/reactive_component/broadcastable.rb

@@ -36,8 +36,18 @@ module ReactiveComponent
 
     private
 
-    def _broadcast_reactive_create  = broadcast_reactive(:create)
-    def _broadcast_reactive_update  = broadcast_reactive(:update)
+    def _broadcast_reactive_create = broadcast_reactive(:create)
+
+    # Skips components subscribed to `fields:` when none of them changed.
+    def _broadcast_reactive_update
+      reactive_component_classes.each do |klass|
+        fields = klass._subscribed_fields
+        next if fields && !saved_changes.keys.intersect?(fields)
+
+        ReactiveComponent.broadcast_for(klass, self, action: :update)
+      end
+    end
+
     def _broadcast_reactive_destroy = broadcast_reactive(:destroy)
   end
 end

data/lib/reactive_component/engine.rb

@@ -2,6 +2,11 @@
 
 # This file should be required from the main lib/reactive_component.rb module file.
 
+# Entities and signed stream ids are GlobalIDs. ActiveJob pulls this railtie in
+# for its own arguments; an app without ActiveJob would otherwise have no
+# `GlobalID.app` and could not create one.
+require 'global_id/railtie'
+
 module ReactiveComponent
   class Engine < ::Rails::Engine
     isolate_namespace ReactiveComponent

data/lib/reactive_component/entity.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_model'
+require 'global_id'
 
 module ReactiveComponent
   # A derived entity: a plain object built on top of several ActiveRecord
@@ -19,6 +20,16 @@ module ReactiveComponent
   #     def total = order.payments.sum(:amount)
   #   end
   #
+  # An entity that is not keyed on one record uses `key` instead of `root`:
+  #
+  #   class DueCount
+  #     include ReactiveComponent::Entity
+  #
+  #     key :company_id, :user_id
+  #     rebuilds_on Task, fields: %i[due_on],
+  #                       entities: ->(task) { new(company_id: task.company_id, user_id: task.assignee_id) }
+  #   end
+  #
   #   class OrderSummaryComponent < ApplicationComponent
   #     include ReactiveComponent
   #     subscribes_to :summary, class_name: "OrderSummary"
@@ -27,6 +38,7 @@ module ReactiveComponent
     extend ActiveSupport::Concern
     include ActiveModel::Model
     include Broadcastable
+    include GlobalID::Identification
 
     included do
       class_attribute :root_name, instance_writer: false
@@ -34,8 +46,9 @@ module ReactiveComponent
 
     def persisted? = true
 
-    # Default stream when the component declares no `broadcasts stream:`.
-    # A bare id would collide with every other entity sharing it.
+    # Turbo's `stream_name_from` prefers `to_gid_param`, so an entity names its
+    # own stream. `to_param` stays as the fallback for when `GlobalID.app`
+    # isn't set: a bare id would collide with every other entity sharing it.
     def to_param = "#{self.class.model_name.param_key}/#{id}"
 
     class_methods do
@@ -53,20 +66,65 @@ module ReactiveComponent
         define_singleton_method(:find_by) { |id:| (record = class_name.constantize.find_by(id: id)) && new(name => record) }
       end
 
+      # An entity keyed on plain values instead of a record. Defines an `id`
+      # that joins the values the way Rails joins a composite primary key, the
+      # `find` / `find_by(id:)` the channel and actions controller need, and,
+      # as defaults you can replace, the readers, `initialize(company_id:,
+      # user_id:)` and `from_key`. A key with the wrong arity resolves to nil
+      # rather than raising.
+      #
+      # `find` turns an id back into an entity through `from_key`, so an
+      # entity that would rather be built from records than from ids defines
+      # its own `initialize` and its own `from_key` to match:
+      #
+      #   key :company_id, :user_id
+      #
+      #   def initialize(company, user)
+      #     @company = company
+      #     @user = user
+      #   end
+      #
+      #   delegate :id, to: :company, prefix: true
+      #   delegate :id, to: :user, prefix: true
+      #
+      #   def self.from_key(company_id:, user_id:)
+      #     new(Company.find(company_id), User.find(user_id))
+      #   end
+      def key(*names)
+        names = names.map(&:to_sym)
+        attr_reader(*names)
+
+        define_method(:initialize) { |**kwargs| names.each { |n| instance_variable_set(:"@#{n}", kwargs.fetch(n)) } }
+        define_method(:id) { names.map { |n| public_send(n) }.join('-') }
+
+        define_singleton_method(:from_key) { |**values| new(**values) }
+        define_singleton_method(:find_by) do |id:|
+          values = id.to_s.split('-')
+          from_key(**names.zip(values).to_h) if values.size == names.size
+        end
+        define_singleton_method(:find) { |id| find_by(id: id) }
+      end
+
       # Rebroadcast the entity after `model` commits. `via:` is the foreign key
       # on `model` pointing at the root; omit it when `model` is the root.
       # `fields:` narrows updates to the listed columns; create and destroy
       # always count.
-      def rebuilds_on(model, via: nil, fields: nil)
+      # `entities:` is the alternative to `via:` when one commit touches more
+      # than one entity, or when the entity is not reachable through a single
+      # foreign key: it takes the record and returns the entities to rebuild.
+      def rebuilds_on(model, via: nil, fields: nil, entities: nil)
+        raise ArgumentError, 'rebuilds_on takes either via: or entities:, not both' if via && entities
+
         entity = self
         fields = fields&.map(&:to_s)
 
-        model.after_commit { entity.rebuild_from(self, via: via, fields: fields) }
+        model.after_commit { entity.rebuild_from(self, via: via, fields: fields, entities: entities) }
       end
 
-      def rebuild_from(record, via:, fields:)
+      def rebuild_from(record, via:, fields:, entities: nil)
         action = commit_action(record)
-        return if action == :update && fields && !record.saved_changes.keys.intersect?(fields)
+        return if unlisted_change?(record, action, fields)
+        return Array(entities.call(record)).each { |e| e.broadcast_reactive(:update) } if entities
         return find_by(id: record.public_send(via))&.broadcast_reactive(:update) if via
 
         new(root_name => record).broadcast_reactive(action)
@@ -74,6 +132,10 @@ module ReactiveComponent
 
       private
 
+      def unlisted_change?(record, action, fields)
+        action == :update && fields && !record.saved_changes.keys.intersect?(fields)
+      end
+
       def commit_action(record)
         return :destroy if record.destroyed?
         return :create if record.previously_new_record?

data/lib/reactive_component/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReactiveComponent
-  VERSION = '0.8.2'
+  VERSION = '0.8.4'
 end

data/lib/reactive_component/wrapper.rb

@@ -2,12 +2,24 @@
 
 module ReactiveComponent
   module Wrapper
+    # Scopes the signed ids a notify wrapper puts on the page: a signed id
+    # minted elsewhere in the app cannot be replayed at our channel.
+    SGID_PURPOSE = 'reactive_component'
+
     module_function
 
     def wrap(component_class, record, inner_html, stream: nil, client_state: nil, strategy: nil, component_name: nil,
-             params: nil, template_id: nil)
+             params: nil, template_id: nil, skip_own_broadcasts: ReactiveComponent.skip_own_broadcasts)
       dom_id_val = component_class.dom_id_for(record)
 
+      # A notify component asks the server to re-render it, so it carries a
+      # signed id of the record it is allowed to ask about. The raw id stays
+      # out of it: the client already has one in its data.
+      if strategy.to_s == 'notify'
+        component_name ||= component_class.name
+        sgid = record.to_sgid_param(for: SGID_PURPOSE)
+      end
+
       attrs = [
         %(id="#{dom_id_val}"),
         %(data-controller="reactive-renderer"),
@@ -33,8 +45,12 @@ module ReactiveComponent
 
       attrs << %(data-reactive-renderer-strategy-value="#{strategy}") if strategy
 
+      attrs << %(data-reactive-renderer-skip-own-broadcasts-value="true") if skip_own_broadcasts
+
       attrs << %(data-reactive-renderer-component-value="#{component_name}") if component_name
 
+      attrs << %(data-reactive-renderer-sgid-value="#{sgid}") if sgid
+
       attrs << %(data-reactive-renderer-params-value="#{ERB::Util.html_escape(params.to_json)}") if params
 
       if ReactiveComponent.debug

data/lib/reactive_component.rb

@@ -18,6 +18,8 @@ module ReactiveComponent
   mattr_accessor :renderer, default: nil
   # How long a live_action token minted into a page stays valid.
   mattr_accessor :action_token_ttl, default: 1.day
+  # Whether a component ignores the broadcast caused by its own live_action.
+  mattr_accessor :skip_own_broadcasts, default: false
 
   class Error < StandardError; end
 
@@ -34,6 +36,7 @@ module ReactiveComponent
     class_attribute :_broadcast_config, instance_writer: false
     class_attribute :_client_state_fields, instance_writer: false, default: {}
     class_attribute :_subscribed_events, instance_writer: false, default: %i[create update destroy]
+    class_attribute :_subscribed_fields, instance_writer: false, default: nil
   end
 
   def render_in(view_context, &)
@@ -141,10 +144,11 @@ module ReactiveComponent
   end
 
   class_methods do
-    def subscribes_to(attr_name, class_name: nil, only: %i[create update destroy])
+    def subscribes_to(attr_name, class_name: nil, only: %i[create update destroy], fields: nil)
       self._live_model_attr = attr_name.to_sym
       self._live_model_class_name = class_name || attr_name.to_s.classify
       self._subscribed_events = Array(only).map(&:to_sym)
+      self._subscribed_fields = fields && Array(fields).map(&:to_s)
 
       component_class = self
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reactive_component
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.4
 platform: ruby
 authors:
 - Przemyslaw Lusar