reactive_component 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f5fd3fc0f10d7fd47f43039a0ba4b58824915989d618d97e32c48b09397ceed
+  data.tar.gz: 4755871d523443f453f870939d01183bdd165e1f39f97092f7c87c0a367c89fe
+SHA512:
+  metadata.gz: cc558b9d15841f9cab6c359450f3324c4f98a38078240437e951a60699e3eeb33cd58acd057622926b62c094fc9b1d68aa58b971fa70efa779a22d8bc83fbe81
+  data.tar.gz: 1a785c4e6d55be8b767d90b2a483eb5415d684da8513cf1a96c6abdb8811273a6bc5890bcd08f8ce65a6b4cd3043dfc0a8ed2f8e6e2c9d9f5a5522b23f1efd8f

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-03-15
+
+### Added
+- Initial extraction of reactive component system
+- Core `ReactiveComponent` concern with DSL: `subscribes_to`, `broadcasts`, `live_action`, `client_state`
+- ERB-to-JavaScript compiler pipeline for client-side re-rendering
+- ActionCable channel with configurable `filter_callback` for broadcast filtering
+- Actions controller for secure server-side action invocation
+- Stimulus controller and utilities for client-side rendering
+- Rails Engine with automatic route mounting
+- Multi-Rails version support (7.1, 7.2, 8.0)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Przemyslaw Lusar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/app/channels/reactive_component/channel.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ReactiveComponent
+  class Channel < ActionCable::Channel::Base
+    mattr_accessor :compress, default: false
+
+    class_attribute :filter_callback, default: nil
+
+    def subscribed
+      stream_name = verified_stream_name
+      if stream_name
+        stream_from stream_name
+      else
+        reject
+      end
+    end
+
+    def unsubscribed
+      stop_all_streams
+    end
+
+    def request_update(data)
+      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 = model_class.find_by(id: record_id)
+      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
+        result = component_class.build_data(record, **params.symbolize_keys)
+        transmit({"action" => "render", "data" => result})
+      end
+    end
+
+    private
+
+    def record_matches?(record, params)
+      return true unless self.class.filter_callback
+
+      self.class.filter_callback.call(record, params)
+    end
+
+    def verified_stream_name
+      Turbo::StreamsChannel.verified_stream_name(params[:signed_stream_name])
+    rescue
+      nil
+    end
+
+    class << self
+      def broadcast_data(streamables, action:, data:)
+        signed = Turbo::StreamsChannel.signed_stream_name(streamables)
+        stream_name = Turbo::StreamsChannel.verified_stream_name(signed)
+
+        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))})
+        else
+          ActionCable.server.broadcast(stream_name, payload)
+        end
+      end
+    end
+  end
+end

data/app/controllers/reactive_component/actions_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ReactiveComponent
+  class ActionsController < ActionController::Base
+    def create
+      payload = verify_token!.symbolize_keys
+      component_class = payload[:c].constantize
+      record = payload[:m].constantize.find(payload[:r])
+
+      component_class.execute_action(
+        params[:action_name],
+        record,
+        params.fetch(:params, {}).permit!.to_h
+      )
+
+      head :ok
+    end
+
+    private
+
+    def verify_token!
+      Rails.application.message_verifier(:reactive_component_action)
+        .verify(params[:token], purpose: :reactive_component_action)
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      raise ActionController::RoutingError, "Not found"
+    end
+  end
+end

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

@@ -0,0 +1,224 @@
+import { Controller } from "@hotwired/stimulus"
+import { createConsumer } from "@rails/actioncable"
+import { compileTemplate, decompress, morphElement, buildActionBody, routeMessage } from "reactive_component/lib/reactive_renderer_utils"
+
+const consumer = createConsumer()
+const log = (...args) => {
+  if (localStorage.getItem("devToolbar:debug") !== "false") {
+    console.log("[reactive-renderer]", ...args)
+  }
+}
+
+function findSubscription(streamValue) {
+  const identifier = JSON.stringify({ channel: "ReactiveComponent::Channel", signed_stream_name: streamValue })
+  return consumer.subscriptions.subscriptions.find(s => s.identifier === identifier)
+}
+
+function subscribe(streamValue, controller) {
+  let sub = findSubscription(streamValue)
+
+  if (!sub) {
+    sub = consumer.subscriptions.create(
+      { channel: "ReactiveComponent::Channel", signed_stream_name: streamValue },
+      {
+        received: async (message) => {
+          const decoded = message.z ? await decompress(message.z) : message
+          for (const handler of sub.handlers) {
+            handler.handleMessage(decoded)
+          }
+        }
+      }
+    )
+    sub.handlers = new Set()
+  }
+  sub.handlers.add(controller)
+}
+
+function unsubscribe(streamValue, controller) {
+  const sub = findSubscription(streamValue)
+  if (!sub) return
+
+  sub.handlers.delete(controller)
+  if (sub.handlers.size === 0) {
+    consumer.subscriptions.remove(sub)
+  }
+}
+
+export default class extends Controller {
+  static values = {
+    template: String,
+    templateId: String,
+    stream: String,
+    actionUrl: String,
+    actionToken: String,
+    state: { type: Object, default: {} },
+    data: { type: Object, default: {} },
+    strategy: { type: String, default: "push" },
+    component: { type: String, default: "" },
+    params: { type: Object, default: {} },
+    fieldMap: { type: Object, default: {} }
+  }
+
+  connect() {
+    this.clientState = { ...this.stateValue }
+    this.lastServerData = Object.keys(this.dataValue).length > 0 ? this.dataValue : null
+
+    const encoded = this.resolveTemplate()
+    this.renderFn = encoded ? compileTemplate(encoded) : null
+
+    if (!this.renderFn) {
+      if (!this.streamValue) return
+    }
+
+    if (!this.streamValue) return
+
+    subscribe(this.streamValue, this)
+  }
+
+  disconnect() {
+    if (this.streamValue) {
+      unsubscribe(this.streamValue, this)
+    }
+  }
+
+  resolveTemplate() {
+    if (this.hasTemplateValue) return this.templateValue
+
+    if (this.hasTemplateIdValue) {
+      const el = document.getElementById(this.templateIdValue)
+      if (el) return el.textContent
+    }
+
+    return null
+  }
+
+  handleMessage(message) {
+    const route = routeMessage(message, this.element.id, this.strategyValue)
+
+    switch (route.type) {
+      case "render":
+        log("render", this.element.id, route.data)
+        this.lastServerData = route.data
+        if (this.renderFn) this.render({ ...route.data, ...this.clientState })
+        break
+
+      case "request_update":
+        log("update", this.element.id, { action: message.action, strategy: "notify" })
+        this.requestUpdate()
+        break
+
+      case "update":
+        log("update", this.element.id, route.data)
+        this.lastServerData = route.data
+        if (this.renderFn) this.render({ ...route.data, ...this.clientState })
+        this.element.dispatchEvent(new CustomEvent("reactive-renderer:updated", {
+          bubbles: true,
+          detail: { data: route.data }
+        }))
+        break
+
+      case "remove":
+      case "destroy":
+        this.element.remove()
+        break
+    }
+  }
+
+  requestUpdate() {
+    if (this._updateTimer) clearTimeout(this._updateTimer)
+
+    this._updateTimer = setTimeout(() => {
+      this._updateTimer = null
+      const sub = findSubscription(this.streamValue)
+      if (!sub) return
+
+      sub.perform("request_update", {
+        component: this.componentValue,
+        record_id: this.dataValue?.id,
+        dom_id: this.element.id,
+        params: this.paramsValue
+      })
+    }, 50)
+  }
+
+  render(data) {
+    const newHtml = this.renderFn(data)
+    this.morph(newHtml)
+  }
+
+  performAction(event) {
+    event.preventDefault()
+    event.stopPropagation()
+
+    const actionName = event.params.action
+    if (!actionName || !this.hasActionUrlValue || !this.hasActionTokenValue) return
+
+    // --- Optimistic update ---
+    const optimisticExpr = event.params.optimistic
+    let rollbackData = null
+
+    if (optimisticExpr && this.lastServerData && this.renderFn && this.fieldMapValue) {
+      const dataKey = this.fieldMapValue[optimisticExpr]
+      if (dataKey && dataKey in this.lastServerData) {
+        rollbackData = { ...this.lastServerData }
+        this.lastServerData[dataKey] = !this.lastServerData[dataKey]
+        this.render({ ...this.lastServerData, ...this.clientState })
+      }
+    }
+    // --- End optimistic ---
+
+    const formData = event.type === "submit" ? new FormData(event.target) : null
+    const { body, redirect } = buildActionBody(actionName, this.actionTokenValue, event.params, formData)
+
+    fetch(this.actionUrlValue, {
+      method: "POST",
+      headers: {
+        "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content,
+      },
+      body
+    }).then(response => {
+      if (!response.ok && rollbackData) {
+        this.lastServerData = rollbackData
+        this.render({ ...this.lastServerData, ...this.clientState })
+      }
+      if (redirect && response.ok) {
+        Turbo.visit(redirect)
+      } else if (response.ok && response.headers.get("content-type")?.includes("text/html")) {
+        return response.text()
+      }
+    }).then(html => {
+      if (html) this.morph(html)
+    }).catch(() => {
+      if (rollbackData) {
+        this.lastServerData = rollbackData
+        this.render({ ...this.lastServerData, ...this.clientState })
+      }
+    })
+  }
+
+  setState(event) {
+    const updates = { ...event.params }
+    delete updates.action
+
+    if (updates.exclusive) {
+      delete updates.exclusive
+      const container = this.element.parentElement
+      if (container) {
+        container.querySelectorAll(`:scope > [data-controller~="reactive-renderer"]`).forEach(el => {
+          if (el === this.element) return
+          const ctrl = this.application.getControllerForElementAndIdentifier(el, "reactive-renderer")
+          if (!ctrl?.clientState) return
+          for (const key of Object.keys(updates)) {
+            if (ctrl.clientState[key]) ctrl.clientState[key] = false
+          }
+        })
+      }
+    }
+
+    Object.assign(this.clientState, updates)
+  }
+
+  morph(newHtml) {
+    morphElement(this.element, newHtml)
+  }
+}

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

@@ -0,0 +1,99 @@
+const templateCache = new Map()
+
+export function isBase64(str) {
+  return /^[A-Za-z0-9+/\n]+=*$/.test(str.trim())
+}
+
+export function compileTemplate(source) {
+  if (templateCache.has(source)) return templateCache.get(source)
+
+  try {
+    const body = isBase64(source) ? atob(source) : source
+    const fn = new Function("data", body)
+    templateCache.set(source, fn)
+    return fn
+  } catch (e) {
+    console.log("[reactive-renderer] ERROR compiling template:", e)
+    return null
+  }
+}
+
+export function clearTemplateCache() {
+  templateCache.clear()
+}
+
+export async function decompress(base64) {
+  const bytes = Uint8Array.from(atob(base64), c => c.charCodeAt(0))
+  const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"))
+  return new Response(stream).json()
+}
+
+export function morphElement(element, newHtml) {
+  const parser = new DOMParser()
+  const doc = parser.parseFromString(`<div>${newHtml}</div>`, "text/html")
+  const newContent = doc.body.firstChild
+
+  if (typeof Idiomorph !== "undefined") {
+    Idiomorph.morph(element, newContent, {
+      morphStyle: "innerHTML",
+      ignoreActiveValue: true
+    })
+  } else {
+    element.innerHTML = newContent.innerHTML
+  }
+
+  element.classList.remove("reactive-morph-flash")
+  void element.offsetWidth
+  element.classList.add("reactive-morph-flash")
+}
+
+export function buildActionBody(actionName, actionToken, stimulusParams, formData) {
+  const body = new URLSearchParams({
+    token: actionToken,
+    action_name: actionName
+  })
+
+  const params = { ...stimulusParams }
+  delete params.action
+  const redirect = params.redirect
+  delete params.redirect
+
+  for (const [key, value] of Object.entries(params)) {
+    const snakeKey = key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`)
+    body.append(`params[${snakeKey}]`, value)
+  }
+
+  if (formData) {
+    for (const [key, value] of formData.entries()) {
+      body.append(`params[${key}]`, value)
+    }
+  }
+
+  return { body, redirect }
+}
+
+export function routeMessage(message, elementId, strategy) {
+  const { action, data } = message
+
+  if (action === "render" && data?.dom_id === elementId) {
+    return { type: "render", data }
+  }
+
+  if (strategy === "notify" && (action === "update" || action === "destroy")) {
+    return { type: "request_update" }
+  }
+
+  if (action === "update" && data?.dom_id === elementId) {
+    return { 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/config/importmap.rb

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

data/config/routes.rb

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