reactive_component 0.8.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77acde881234cd7b6013ab8618efd2cbeb1ffd1a4c6232199517a9b14f4aa9ce
-  data.tar.gz: 1854830f220dd61bb49625a1a2a69e29d4e42ce96a40cf371586d3dd898bcbfc
+  metadata.gz: 111726d46e0cac07d669edebc52f2d7e5e2ee05f5b94f7b766d2b400d647f196
+  data.tar.gz: d0cbaadaddb9b4b2c362ba2036e1f8a9efc5a67665a7673d9694134b1a439f64
 SHA512:
-  metadata.gz: 2721d5f6252603a600a4b297276a460cece0d4216303d40b6daa193b9d141a745c7024c347f6109463016f0f21d2beef01a083fa11d4fc3d294125973fa98630
-  data.tar.gz: 78a474176edff971af3979ca7c0b02d667c5be59e89f19b2dda28b770184f651799f0220eb2c65f5dfb47e938c4307253b52ad0bdf3df09a16a9679039bb832a
+  metadata.gz: b7df34cf75a7a5b83a6ab9d7c98995dcb5bed86b2a67269ab10ca00580af0b769d6aaba0ad37aa861740c4a7e2d242ae851dda561866a76858ae9ad022795f8d
+  data.tar.gz: 32e7b0d49b496c2fff61011751c13d66de283c0c661b6de755da3b2a8919739b6f04861f1de49f9e66c049147a30a960e9436403012ac48f954de0b4a1830d7d

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [0.9.0] - 2026-09-17
+
+### Added
+- `subscribes_to ..., strategy: :notify` declares notify mode for every
+  instance. A broadcast then sends the bare signal instead of building a
+  payload no notify client reads, and the wrapper needs no
+  `live_wrapper_options`. An instance cannot switch such a class back to push.
+
+### Changed
+- A broadcast now runs in an Active Job (`ReactiveComponent::BroadcastJob`)
+  instead of inside the request that committed the record, so rendering a
+  payload no longer holds the response. `subscribes_to ..., later: false`
+  keeps it inline. A destroy always broadcasts inline. The request id rides
+  along, so `skip_own_broadcasts` keeps working.
+- A morph leaves `[data-turbo-permanent]` elements alone, as Turbo's own morph
+  does. An open menu marks itself permanent while it is open, and an update
+  underneath it no longer closes it.
+- A `key` entity's dom id joins its parts with `_` instead of `-`
+  (`due_count_1_2`) and its gid with `/`. A page rendered before the deploy
+  routes broadcasts by the old id until it reloads.
+
+### Fixed
+- A `key` entity joined its id on `-`, so a part carrying a dash, a UUID for
+  instance, never split back: every lookup missed and a notify component
+  never re-rendered. The id is now the array of parts, the way Rails exposes
+  a composite primary key, and GlobalID and `dom_id` encode it themselves.
+
+## [0.8.5] - 2026-09-16
+
+### Added
+- `morphHooks`: register Idiomorph callbacks that run inside every component's
+  morph, for flashing changed values and similar page-wide behaviour, without
+  subclassing the controller. See Hooking into the morph.
+
+### Fixed
+- An app that does not eager load (development, test) broadcast nothing from a
+  process that had not rendered the subscribing component yet, such as a job or
+  a turbo-stream request. The engine now loads the components under
+  `app/components` that include `ReactiveComponent` on boot and after each
+  reload, and only those, so the rest of the app keeps lazy loading. Set
+  `ReactiveComponent::SubscriberLoader.paths` to look elsewhere.
+
 ## [0.8.4] - 2026-09-16
 
 ### Added

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

@@ -34,6 +34,32 @@ export async function decompress(base64) {
   return new Response(stream).json()
 }
 
+// Idiomorph's callbacks, open for the app to hook into: push an object with any
+// of them (a flash on changed numbers, a sound, a counter) and it runs for every
+// component. A hook returning false cancels that node, as Idiomorph expects.
+export const morphHooks = []
+
+const HOOK_NAMES = [
+  'beforeNodeAdded', 'afterNodeAdded', 'beforeNodeMorphed', 'afterNodeMorphed',
+  'beforeNodeRemoved', 'afterNodeRemoved', 'beforeAttributeUpdated'
+]
+
+// Turbo's convention: an element marked permanent is left as it is. A menu
+// that is open, or anything else the page is in the middle of, says so with
+// the attribute and the morph steps over it. Like Turbo's, it needs an id, so
+// the morph pairs it with its counterpart instead of adding a second copy.
+const isPermanent = (node) => node.nodeType === Node.ELEMENT_NODE && node.id !== "" && node.hasAttribute("data-turbo-permanent")
+
+const skipPermanent = {
+  beforeNodeMorphed: (currentNode) => !isPermanent(currentNode),
+  beforeNodeRemoved: (node) => !isPermanent(node)
+}
+
+const morphCallbacks = Object.fromEntries(HOOK_NAMES.map(name => [
+  name,
+  (...args) => [skipPermanent, ...morphHooks].reduce((ok, hook) => (hook[name]?.(...args) === false ? false : ok), true)
+]))
+
 export function morphElement(element, newHtml) {
   const parser = new DOMParser()
   const doc = parser.parseFromString(`<div>${newHtml}</div>`, "text/html")
@@ -42,7 +68,8 @@ export function morphElement(element, newHtml) {
   if (typeof Idiomorph !== "undefined") {
     Idiomorph.morph(element, newContent, {
       morphStyle: "innerHTML",
-      ignoreActiveValue: true
+      ignoreActiveValue: true,
+      callbacks: morphCallbacks
     })
   } else {
     element.innerHTML = newContent.innerHTML

data/app/jobs/reactive_component/broadcast_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ReactiveComponent
+  # Carries a broadcast out of the request that committed the record. The
+  # request id travels with it so a client can still skip its own broadcast.
+  # A record deleted before the job runs has nothing left to render, so the
+  # job is dropped rather than retried.
+  class BroadcastJob < ActiveJob::Base
+    discard_on ActiveJob::DeserializationError
+
+    def perform(component_class_name, record, action, request_id = nil)
+      Turbo.with_request_id(request_id) do
+        ReactiveComponent.broadcast_for(component_class_name.constantize, record, action: action.to_sym)
+      end
+    end
+  end
+end

data/lib/reactive_component/broadcastable.rb

@@ -28,7 +28,7 @@ module ReactiveComponent
     end
 
     def broadcast_reactive(action)
-      reactive_component_classes.each { |klass| ReactiveComponent.broadcast_for(klass, self, action: action) }
+      reactive_component_classes.each { |klass| _broadcast_reactive_for(klass, action) }
     end
 
     def broadcast_reactive_update  = broadcast_reactive(:update)
@@ -44,10 +44,20 @@ module ReactiveComponent
         fields = klass._subscribed_fields
         next if fields && !saved_changes.keys.intersect?(fields)
 
-        ReactiveComponent.broadcast_for(klass, self, action: :update)
+        _broadcast_reactive_for(klass, :update)
       end
     end
 
     def _broadcast_reactive_destroy = broadcast_reactive(:destroy)
+
+    # A destroyed record cannot ride a job: it is gone by the time the job
+    # looks it up. Its signal is cheap, so it goes out inline. So does a
+    # component the job could not find by name, an anonymous class in a test.
+    def _broadcast_reactive_for(klass, action)
+      later = action != :destroy && klass.name && klass.try(:_broadcast_later)
+      return ReactiveComponent.broadcast_for(klass, self, action: action) unless later
+
+      ReactiveComponent::BroadcastJob.perform_later(klass.name, self, action.to_s, Turbo.current_request_id)
+    end
   end
 end

data/lib/reactive_component/engine.rb

@@ -5,6 +5,7 @@
 # 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 'active_job/railtie'
 require 'global_id/railtie'
 
 module ReactiveComponent
@@ -15,6 +16,16 @@ module ReactiveComponent
       ReactiveComponent::DataEvaluator.finalize!
     end
 
+    # A component wires its model up when the class loads, so an app that does
+    # not eager load (development, test) would broadcast nothing from a process
+    # that has not rendered that component yet: a job, or a turbo-stream
+    # request. Load the subscribing components on boot and after each reload.
+    initializer 'reactive_component.load_subscribers' do |app|
+      next if app.config.eager_load
+
+      app.config.to_prepare { ReactiveComponent::SubscriberLoader.load_all }
+    end
+
     initializer 'reactive_component.importmap', before: 'importmap' do |app|
       if defined?(Importmap)
         app.config.importmap.paths <<

data/lib/reactive_component/entity.rb

@@ -36,6 +36,7 @@ module ReactiveComponent
   #   end
   module Entity
     extend ActiveSupport::Concern
+
     include ActiveModel::Model
     include Broadcastable
     include GlobalID::Identification
@@ -49,7 +50,7 @@ module ReactiveComponent
     # 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}"
+    def to_param = "#{self.class.model_name.param_key}/#{to_key.join('/')}"
 
     class_methods do
       # The record the entity is keyed on. Defines `initialize(<name>:)`, the
@@ -67,7 +68,10 @@ module ReactiveComponent
       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
+      # that is the array of values, the way Rails exposes a composite primary
+      # key: `dom_id` joins them with `_` and GlobalID escapes each on its own,
+      # so a part may carry a dash or a colon. `primary_key` names the parts
+      # for GlobalID's arity check. Also defines 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
@@ -95,11 +99,12 @@ module ReactiveComponent
         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_method(:id) { names.map { |n| public_send(n) } }
+        define_singleton_method(:primary_key) { names }
 
         define_singleton_method(:from_key) { |**values| new(**values) }
         define_singleton_method(:find_by) do |id:|
-          values = id.to_s.split('-')
+          values = Array(id)
           from_key(**names.zip(values).to_h) if values.size == names.size
         end
         define_singleton_method(:find) { |id| find_by(id: id) }

data/lib/reactive_component/subscriber_loader.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ReactiveComponent
+  # A component wires its model up when the class loads, so an app that does
+  # not eager load broadcasts nothing from a process that has not rendered that
+  # component yet. This loads the components that subscribe, and nothing else.
+  module SubscriberLoader
+    mattr_accessor :paths, default: ['app/components']
+
+    SUBSCRIBER = /include\s+ReactiveComponent\b/
+
+    module_function
+
+    def load_all
+      loader = Rails.autoloaders.main
+
+      files.each { |file| loader.cpath_expected_at(file)&.safe_constantize }
+    end
+
+    # The files under `paths` that include the concern, read rather than
+    # loaded, so an app keeps lazy loading for everything else.
+    def files
+      paths.flat_map do |path|
+        dir = Rails.root.join(path)
+        next [] unless Dir.exist?(dir)
+
+        Dir.glob(dir.join('**', '*.rb')).select { |file| File.read(file).match?(SUBSCRIBER) }
+      end
+    end
+  end
+end

data/lib/reactive_component/version.rb

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

data/lib/reactive_component/wrapper.rb

@@ -12,6 +12,12 @@ module ReactiveComponent
              params: nil, template_id: nil, skip_own_broadcasts: ReactiveComponent.skip_own_broadcasts)
       dom_id_val = component_class.dom_id_for(record)
 
+      # A notify class broadcasts no data, so an instance cannot go back to push.
+      if component_class.notify? && strategy.to_s != 'notify'
+        raise ArgumentError, "#{component_class.name} declares strategy: :notify; " \
+                             "the wrapper cannot switch it to #{strategy.inspect}"
+      end
+
       # 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.

data/lib/reactive_component.rb

@@ -8,6 +8,7 @@ require_relative 'reactive_component/compiler'
 require_relative 'reactive_component/data_evaluator'
 require_relative 'reactive_component/wrapper'
 require_relative 'reactive_component/broadcastable'
+require_relative 'reactive_component/subscriber_loader'
 require_relative 'reactive_component/entity'
 require_relative 'reactive_component/engine' if defined?(Rails::Engine)
 
@@ -37,6 +38,8 @@ module ReactiveComponent
     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
+    class_attribute :_strategy, instance_writer: false, default: nil
+    class_attribute :_broadcast_later, instance_writer: false, default: true
   end
 
   def render_in(view_context, &)
@@ -59,6 +62,7 @@ module ReactiveComponent
                    end
 
     extra_opts = respond_to?(:live_wrapper_options, true) ? live_wrapper_options : {}
+    extra_opts = { strategy: self.class._strategy }.merge(extra_opts) if self.class._strategy
 
     wrapped = ReactiveComponent::Wrapper.wrap(self.class, record, inner_html, stream: stream, client_state: client_state,
                                                                               **extra_opts)
@@ -115,6 +119,8 @@ module ReactiveComponent
   end
   private_class_method :raise_unsafe!
 
+  def self.signal_for(component_class, record) = { 'id' => record.id, 'dom_id' => component_class.dom_id_for(record) }
+
   def self.broadcast_for(component_class, record, action:)
     return unless component_class._subscribed_events.include?(action)
 
@@ -128,11 +134,11 @@ module ReactiveComponent
 
     case action
     when :update
-      Channel.broadcast_data(stream, action: :update, data: component_class.build_data(record))
+      data = component_class.notify? ? signal_for(component_class, record) : component_class.build_data(record)
+
+      Channel.broadcast_data(stream, action: :update, data: data)
     when :destroy
-      Channel.broadcast_data(stream, action: :destroy, data: {
-                               'id' => record.id, 'dom_id' => component_class.dom_id_for(record)
-                             })
+      Channel.broadcast_data(stream, action: :destroy, data: signal_for(component_class, record))
     when :create
       target = config&.dig(:prepend_target)
       return unless target
@@ -144,11 +150,13 @@ module ReactiveComponent
   end
 
   class_methods do
-    def subscribes_to(attr_name, class_name: nil, only: %i[create update destroy], fields: nil)
+    def subscribes_to(attr_name, class_name: nil, only: %i[create update destroy], fields: nil, strategy: nil, later: true)
       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)
+      self._strategy = strategy&.to_sym
+      self._broadcast_later = later
 
       component_class = self
 
@@ -173,6 +181,8 @@ module ReactiveComponent
       end
     end
 
+    def notify? = _strategy == :notify
+
     def live_model_class
       _live_model_class_name&.constantize
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reactive_component
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.9.0
 platform: ruby
 authors:
 - Przemyslaw Lusar
@@ -106,6 +106,7 @@ files:
 - app/controllers/reactive_component/actions_controller.rb
 - app/javascript/reactive_component/controllers/reactive_renderer_controller.js
 - app/javascript/reactive_component/lib/reactive_renderer_utils.js
+- app/jobs/reactive_component/broadcast_job.rb
 - config/importmap.rb
 - config/routes.rb
 - lib/reactive_component.rb
@@ -115,6 +116,7 @@ files:
 - lib/reactive_component/engine.rb
 - lib/reactive_component/entity.rb
 - lib/reactive_component/erubi.rb
+- lib/reactive_component/subscriber_loader.rb
 - lib/reactive_component/transpiler.rb
 - lib/reactive_component/version.rb
 - lib/reactive_component/wrapper.rb