reactive_component 0.1.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f5fd3fc0f10d7fd47f43039a0ba4b58824915989d618d97e32c48b09397ceed
-  data.tar.gz: 4755871d523443f453f870939d01183bdd165e1f39f97092f7c87c0a367c89fe
+  metadata.gz: b0c408bc69906500eee92927b43eb4f307039d4faab5e6fda80b5461ba922db0
+  data.tar.gz: 6ccf997e199cdd409138b48b187199b55c625dcdb165aabb808c2ed0657a23f6
 SHA512:
-  metadata.gz: cc558b9d15841f9cab6c359450f3324c4f98a38078240437e951a60699e3eeb33cd58acd057622926b62c094fc9b1d68aa58b971fa70efa779a22d8bc83fbe81
-  data.tar.gz: 1a785c4e6d55be8b767d90b2a483eb5415d684da8513cf1a96c6abdb8811273a6bc5890bcd08f8ce65a6b4cd3043dfc0a8ed2f8e6e2c9d9f5a5522b23f1efd8f
+  metadata.gz: 689c1ffeab1b2b2c93b7df69765a9a0660c9cd5c215704b63cd5ac9128d152ac34bd39b0f8934b2798e37a649b3d6b2486aad3cf97d977f0cf3c374885f42a92
+  data.tar.gz: 6596df41e9f41b447e9e8365c5f7c1fd8603fca4212eb2f15e429278a78e65c09c929edf753d353f1f65311533c9018bdcb4236aadf0d47a97a4964cdbb6af71

data/CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## [0.6.2] - 2026-09-06
+
+### Changed
+- Gem metadata points at the right places: homepage and documentation
+  are the GitHub Pages docs, source/changelog/issues are
+  `lluzak/reactive_component`. (First release on RubyGems since 0.1.0.)
+
+## [0.6.1] - 2026-09-06
+
+### Changed
+- Docs describe the 0.6 compiler (Prism, prefixed ids, typed conditions,
+  compile errors); the live-action examples use the real Stimulus params.
+- RuboCop pinned to `~> 1.90.0` so CI and local lint agree. The 0.6.0 tag
+  was never published: its commit failed lint on CI.
+
+## [0.6.0] - 2026-09-05
+
+### Changed
+- **ruby2js is gone; the compiler runs on Prism's own tree.** One pass
+  over the Prism AST lifts every Ruby expression to a server-evaluated
+  data key and emits the template skeleton as JavaScript — a whitelist
+  (literals, data reads, `if`/`unless`/ternaries, boolean and comparison
+  operators, `.each`, the `_tag*`/`_render_*` helpers). Anything else raises
+  `ReactiveComponent::CompileError` naming the source, where ruby2js used
+  to guess (`present?` became a `.present` property read). Dependencies:
+  `ruby2js` out, `erubi` in; no `parser` gem. The compiled JS keeps the
+  same shape (`function render({ … })`, `_buf +=`, `for..of`,
+  `_tag_open(...)`).
+- `"#{@x}!"` — an interpolated string with an ivar or helper — is now
+  server-evaluated and escaped like any other expression, instead of being
+  emitted as an unescaped template literal.
+- The extractor now lifts a chain rooted at a self call
+  (`content.present?`, `current_user.name`) whole, like an ivar chain.
+- **Wrapper ids are now component-prefixed by default** —
+  `message_row_message_1` instead of `message_1`. Two components rendering
+  the same record previously shared one id, and because broadcasts are
+  routed by id each rendered the *other's* payload: a `TypeError` deep in
+  the compiled template as soon as the shapes differed, plus duplicate ids
+  in the page. `dom_id_prefix` still overrides the default. Anything that
+  targeted the old bare ids (CSS, Turbo Stream targets, tests) needs the
+  new prefix.
+
+### Fixed
+- **Block variables in conditions.** Inside a `.each`, an item read in a
+  non-output position — `<% if item.flag %>`, a ternary, `"x" if item.y` —
+  passed through ruby2js as `item.flag`, a property the client never
+  receives (items ship as their extracted expressions only, never the raw
+  record). Conditions were silently false after every broadcast and
+  `item.x.present?` threw `Cannot read properties of undefined`. They are
+  now server-evaluated per item like output expressions, but keep their
+  type (`"false"` is truthy in JS).
+
+### Added
+- **Compile-time invariant for loops.** After a `.each` body is processed,
+  any surviving read of the loop variable that is not an extracted
+  `item["vN"]` raises `ReactiveComponent::CompileError` naming the
+  expression — an item ships only as its extracted expressions, so such a
+  read could never resolve on the client. Guards the block-variable fix
+  against new syntactic positions.
+- **Debug-mode strict payloads.** With `ReactiveComponent.debug` on, the
+  client renders through a Proxy that throws on reading a key the payload
+  does not carry, naming the key, its path, and the keys present — instead
+  of an `undefined` that is silently falsy in an `if`.
+- The Stimulus controller checks for other elements sharing its id on
+  connect and logs a `console.error` naming the collision and the fix.
+  Piggybacks on Stimulus's own MutationObserver, so it also catches
+  hand-picked `dom_id_prefix`es that collide.
+
+## [0.4.1] - 2026-05-29
+
+### Changed
+- Bumped Rails to 8.1.3 (and matching patches across the 8.1.x stack)
+  in development and test gemfiles.
+- Upgraded `view_component` to 4.11.0 — full test suite (119 runs,
+  308 assertions) green on Rails 7.1, 7.2, and 8.0 appraisals.
+- Refreshed transitive dependencies (rack 3.2.6, nokogiri 1.19.3,
+  loofah 2.25.1, zeitwerk 2.8.2, propshaft 1.3.2, sqlite3 2.9.4,
+  rubocop 1.86.2, etc.).
+
+## [0.4.0] - 2026-04-18
+
+### Security
+- **Broadcast payloads now refuse non-primitive values.** Previously
+  `build_data` could ship full `ActiveRecord` records over ActionCable,
+  leaking every column (including `password_digest`, tokens). The
+  sanitizer now raises `ReactiveComponent::UnsafeBroadcastValueError`
+  with a context-aware hint pointing at the offending ERB expression.
+
+### Added
+- `ReactiveComponent.sanitize_for_broadcast(value, source:)` — the
+  strict gatekeeper. Allows primitives (`nil`, booleans, `Integer`,
+  `Float`, `String`), `Symbol` (downcast to `String`), and `Array`/
+  `Hash` of those; raises on everything else.
+- Node-based compiler regression test: actually executes compiled
+  templates so undefined-identifier runtime bugs fail the build.
+- `RichRowComponent` + `WrapperComponent` dummy fixtures exercising
+  every shape that has historically broken the extractor.
+
+### Fixed
+- `<%= tag.xxx(attrs) do %> … <% end %>` now compiles into
+  `_tag_open` + body + `_tag_close`, so inner expressions stay
+  per-field reactive instead of collapsing into invalid JS.
+- `<%= raw bare_helper %>` extracts the inner call as a server-
+  computed raw field (previously emitted an undefined JS identifier).
+- `**@options` keyword-splat on `tag.xxx` no longer emits `#options`
+  (a JS private-field reference, which is a syntax error outside a
+  class body).
+- Bare helper calls in conditions and tag attrs (`banner_visible?`,
+  `row_classes`, `status_label(@x)`) are extracted as server-computed
+  fields instead of surfacing as undefined JS identifiers.
+- Bare `<%= @ivar %>` output alongside `<%= @ivar.chain %>` — both
+  destructures are now provided in the broadcast payload.
+- ViewComponent sidecar template layout (`foo_component/foo_component.html.erb`)
+  is now supported by `Compiler.read_erb`.
+- `escapeHTML` is aliased in the compiled preamble (ruby2js emits it
+  in some nested-component paths).
+- `_render_attrs` now expands `data:`/`aria:` hashes, handles mixed
+  `class: [string, {name => cond}]` arrays, and emits bare boolean
+  attributes — matching Rails tag-builder semantics.
+- Live-model ivar (e.g. `@message` under `subscribes_to :message`) is
+  excluded from broadcast payloads — it's the subscription key, not a
+  data field.
+
+## [0.3.0] - 2026-04-16
+
+### Added
+- `broadcast_reactive_update` public method on models for manual broadcasts without touching the record
+- Client state rendering: `setState` now re-renders components after updating client state
+- Exclusive client state: `setState` with `exclusive` param deselects sibling components
+- Folder navigation (Inbox, Starred, Sent, Archive, Trash) in dummy app
+- Documentation for `client_state` usage (setState, exclusive mode, selectable lists)
+- Documentation for `broadcast_reactive_update` with examples
+- DataEvaluator tests for path helper resolution
+
+### Fixed
+- Path helpers (e.g. `message_path`) returning nil in reactive broadcasts — added engine initializer to finalize DataEvaluator at boot
+- `setState` not triggering re-render after updating client state
+- Turbo frame navigation breaking when `setState` morphed the DOM synchronously — deferred with `requestAnimationFrame`
+- `live_action` documentation using outdated Stimulus data attribute conventions
+
+## [0.2.0] - 2026-03-25
+
+### Added
+- "How It Works" architecture documentation page
+- "Nested Components" guide
+- "Collections & Loops" guide
+- "Troubleshooting" page
+- Enriched README with architecture summary, advanced features, and license section
+- Reorganized docs sidebar for logical learning path
+
 ## [0.1.0] - 2026-03-15
 
 ### Added

data/app/channels/reactive_component/channel.rb

@@ -20,23 +20,23 @@ module ReactiveComponent
     end
 
     def request_update(data)
-      component_class = data["component"].constantize
-      params = data["params"] || {}
+      component_class = data['component'].constantize
+      params = data['params'] || {}
 
       model_class = component_class.live_model_class
-      record_id = data["record_id"] || params.delete("record_id")
+      record_id = data['record_id'] || params.delete('record_id')
       record = model_class.find_by(id: record_id)
       return unless record
 
-      if data["record_id"].present?
+      if data['record_id'].present?
         if record_matches?(record, params)
-          transmit({"action" => "render", "data" => component_class.build_data(record)})
+          transmit({ 'action' => 'render', 'data' => component_class.build_data(record) })
         else
-          transmit({"action" => "remove", "dom_id" => data["dom_id"]})
+          transmit({ 'action' => 'remove', 'dom_id' => data['dom_id'] })
         end
       else
         result = component_class.build_data(record, **params.symbolize_keys)
-        transmit({"action" => "render", "data" => result})
+        transmit({ 'action' => 'render', 'data' => result })
       end
     end
 
@@ -50,7 +50,7 @@ module ReactiveComponent
 
     def verified_stream_name
       Turbo::StreamsChannel.verified_stream_name(params[:signed_stream_name])
-    rescue
+    rescue StandardError
       nil
     end
 
@@ -59,11 +59,11 @@ module ReactiveComponent
         signed = Turbo::StreamsChannel.signed_stream_name(streamables)
         stream_name = Turbo::StreamsChannel.verified_stream_name(signed)
 
-        payload = {action: action, data: data}
+        payload = { action: action, data: data }
 
         if compress
           json = ActiveSupport::JSON.encode(payload)
-          ActionCable.server.broadcast(stream_name, {z: Base64.strict_encode64(ActiveSupport::Gzip.compress(json))})
+          ActionCable.server.broadcast(stream_name, { z: Base64.strict_encode64(ActiveSupport::Gzip.compress(json)) })
         else
           ActionCable.server.broadcast(stream_name, payload)
         end

data/app/controllers/reactive_component/actions_controller.rb

@@ -20,9 +20,9 @@ module ReactiveComponent
 
     def verify_token!
       Rails.application.message_verifier(:reactive_component_action)
-        .verify(params[:token], purpose: :reactive_component_action)
+           .verify(params[:token], purpose: :reactive_component_action)
     rescue ActiveSupport::MessageVerifier::InvalidSignature
-      raise ActionController::RoutingError, "Not found"
+      raise ActionController::RoutingError, 'Not found'
     end
   end
 end

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

@@ -1,6 +1,6 @@
 import { Controller } from "@hotwired/stimulus"
 import { createConsumer } from "@rails/actioncable"
-import { compileTemplate, decompress, morphElement, buildActionBody, routeMessage } from "reactive_component/lib/reactive_renderer_utils"
+import { compileTemplate, decompress, morphElement, buildActionBody, routeMessage, duplicateIds, strictData } from "reactive_component/lib/reactive_renderer_utils"
 
 const consumer = createConsumer()
 const log = (...args) => {
@@ -60,6 +60,15 @@ export default class extends Controller {
   }
 
   connect() {
+    const clashes = duplicateIds(document, this.element)
+    if (clashes.length) {
+      console.error(
+        `[reactive-renderer] ${clashes.length + 1} components share id "${this.element.id}" — ` +
+        "each will render every other's broadcast. Give the component a distinct dom_id_prefix.",
+        this.element, ...clashes
+      )
+    }
+
     this.clientState = { ...this.stateValue }
     this.lastServerData = Object.keys(this.dataValue).length > 0 ? this.dataValue : null
 
@@ -142,7 +151,10 @@ export default class extends Controller {
   }
 
   render(data) {
-    const newHtml = this.renderFn(data)
+    // ReactiveComponent.debug marks the wrapper; a missing key then throws
+    // with its name rather than rendering as a silent falsy/undefined.
+    const input = this.element.hasAttribute("data-reactive-debug") ? strictData(data, this.element.id) : data
+    const newHtml = this.renderFn(input)
     this.morph(newHtml)
   }
 
@@ -208,14 +220,24 @@ export default class extends Controller {
           if (el === this.element) return
           const ctrl = this.application.getControllerForElementAndIdentifier(el, "reactive-renderer")
           if (!ctrl?.clientState) return
+          let changed = false
           for (const key of Object.keys(updates)) {
-            if (ctrl.clientState[key]) ctrl.clientState[key] = false
+            if (ctrl.clientState[key]) {
+              ctrl.clientState[key] = false
+              changed = true
+            }
+          }
+          if (changed && ctrl.lastServerData && ctrl.renderFn) {
+            requestAnimationFrame(() => ctrl.render({ ...ctrl.lastServerData, ...ctrl.clientState }))
           }
         })
       }
     }
 
     Object.assign(this.clientState, updates)
+    if (this.lastServerData && this.renderFn) {
+      requestAnimationFrame(() => this.render({ ...this.lastServerData, ...this.clientState }))
+    }
   }
 
   morph(newHtml) {

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

@@ -97,3 +97,37 @@ export function routeMessage(message, elementId, strategy) {
 
   return { type: "ignore" }
 }
+
+// Every element in `doc` that shares `element`'s id, excluding `element`.
+// Broadcasts are routed to a component by its id, so a duplicate means one
+// payload renders into several components — and a TypeError deep in the
+// compiled template as soon as their shapes differ. Checked on connect, which
+// Stimulus already fires for every component entering the DOM (its own
+// MutationObserver), so nothing else needs to watch the page.
+export function duplicateIds(doc, element) {
+  if (!element.id) return []
+  const selector = `[id="${element.id.replace(/["\\]/g, "\\$&")}"]`
+  return [...doc.querySelectorAll(selector)].filter(other => other !== element)
+}
+
+// Debug mode only: `data` (and every item inside it) wrapped so that reading
+// a key the payload does not carry THROWS, naming the key and what is there,
+// instead of yielding undefined — which is silently falsy in an `if` and
+// only ever surfaces as a mystery `.x of undefined` further down. Keys on the
+// prototype chain (map, toString, constructor) and symbols pass through, so
+// only a genuinely missing field trips it.
+export function strictData(data, label) {
+  const wrap = (target, path) => new Proxy(target, {
+    get(obj, key, receiver) {
+      if (typeof key === "symbol" || key in obj) {
+        const value = Reflect.get(obj, key, receiver)
+        return value && typeof value === "object" ? wrap(value, `${path}${String(key)}.`) : value
+      }
+      throw new TypeError(
+        `[reactive-renderer] ${label}: template read "${path}${String(key)}" but the payload only has: ` +
+        Object.keys(obj).join(", ")
+      )
+    }
+  })
+  return wrap(data, "")
+}

data/config/importmap.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
-pin_all_from ReactiveComponent::Engine.root.join("app/javascript/reactive_component"),
-             under: "reactive_component"
+pin_all_from ReactiveComponent::Engine.root.join('app/javascript/reactive_component'),
+             under: 'reactive_component'

data/config/routes.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 ReactiveComponent::Engine.routes.draw do
-  post "actions", to: "actions#create", as: :reactive_component_actions
+  post 'actions', to: 'actions#create', as: :reactive_component_actions
 end

data/lib/reactive_component/broadcastable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ReactiveComponent
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :reactive_component_classes, instance_writer: false, default: Set.new
+    end
+
+    class_methods do
+      def register_reactive_component(component_class)
+        return if reactive_component_classes.include?(component_class)
+
+        self.reactive_component_classes = reactive_component_classes | [component_class]
+
+        return if _commit_callbacks.map(&:filter).include?(:_broadcast_reactive_create)
+
+        after_create_commit  :_broadcast_reactive_create
+        after_update_commit  :_broadcast_reactive_update
+        after_destroy_commit :_broadcast_reactive_destroy
+      end
+    end
+
+    def broadcast_reactive_update
+      _broadcast_reactive(:update)
+    end
+
+    private
+
+    def _broadcast_reactive_create  = _broadcast_reactive(:create)
+    def _broadcast_reactive_update  = _broadcast_reactive(:update)
+    def _broadcast_reactive_destroy = _broadcast_reactive(:destroy)
+
+    def _broadcast_reactive(action)
+      reactive_component_classes.each { |klass| ReactiveComponent.broadcast_for(klass, self, action: action) }
+    end
+  end
+end