reactive_component 0.8.3 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0a2f38ec2a6ac3161f8f5e0f9592aaa5241dfcecfb7992ca0c65f29e7f6ea84
-  data.tar.gz: 4a02ca05478a0675b8de4dde77336dab391fe397931ba7e952912455456b6915
+  metadata.gz: 5ec78650feb0396bbe85c2adc0994209dc4d1ab91a6cf0ca49d9692b17e0b316
+  data.tar.gz: c2d54ef039a0ea502c593a5eb1e173f509955e3e37b0f6eea1cd78c05ed365d5
 SHA512:
-  metadata.gz: 5029099159c30a18cbb2b354d913df8aeaa2003481d5a70864503e6f9cbc50638ccb9a7d7bf5258a3b2a6e879806be9c02ed1f86bf7f972781cc51b1cb846413
-  data.tar.gz: 87e761fb987f437b48787f5aa8e3b13009ef3025ba0ef9c080be39ce4b3e06a1b7d4ae63113729b98cd9c79391d34c91e8770b9623ba2998a3c73f3bea2ade83
+  metadata.gz: caf86cb2646eea037defb27405b486555e70377351c6fe3a61b7d1b00aa33cf330d6ace77a42936e9c93c2bbb992026d0a5a2138137ac6591ff6efd1a45f6c21
+  data.tar.gz: fc02fd8569b770ff6b6ed6583cdfbc4fb3dfb2630768eaa7d4f095ce755cc7ecf7617721fa542ca5f76a7a149984cbd5549e4f959911e67b739f96a4e2aa3a22

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [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
+- `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

data/app/channels/reactive_component/channel.rb

@@ -21,7 +21,7 @@ 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 record_matches?(record, params)
@@ -34,16 +34,15 @@ module ReactiveComponent
 
     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)
@@ -52,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
 

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

@@ -68,6 +68,7 @@ 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: {} },
     skipOwnBroadcasts: { type: Boolean, default: false }
@@ -165,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
       })

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

@@ -34,6 +34,21 @@ 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'
+]
+
+const morphCallbacks = Object.fromEntries(HOOK_NAMES.map(name => [
+  name,
+  (...args) => 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 +57,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/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
@@ -10,6 +15,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

@@ -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/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.3'
+  VERSION = '0.8.5'
 end

data/lib/reactive_component/wrapper.rb

@@ -2,15 +2,22 @@
 
 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, 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
-        params = { record_id: record.id }.merge(params || {})
+        sgid = record.to_sgid_param(for: SGID_PURPOSE)
       end
 
       attrs = [
@@ -42,6 +49,8 @@ module ReactiveComponent
 
       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

@@ -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)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reactive_component
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.5
 platform: ruby
 authors:
 - Przemyslaw Lusar
@@ -115,6 +115,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