live_cable 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22855e882f2fd803fffc8bf2614fd3aa4e1b47a3d0dd4a686a7d3adb90e79bba
+  data.tar.gz: 1c9522b46962dcb5cf0aa6336d2243edb162167344dc48c37820ef3a3a16154d
+SHA512:
+  metadata.gz: ee3630ec8ca212780062cbfc217d734c65d5b0ad558e2fb058858c1452e4f181ec5eba7b508e100921025683ffc44dc1b62c7a7163a0747c2e9f9bf6f27f8353
+  data.tar.gz: 8bc8de345fa73f1a67eefa9b59b09dfff59052758221c395a005ec4204708b4112724a355ec93f752c0758abd304d87fab3ca9321305262418213fecf79a4ce4

data/app/assets/javascript/controllers/live_controller.js

@@ -0,0 +1,123 @@
+import { Controller } from "@hotwired/stimulus"
+import SubscriptionManager from "live_cable_subscriptions"
+
+export default class extends Controller {
+  static values = {
+    defaults: Object,
+    status: String,
+    component: String,
+    liveId: String,
+  }
+
+  #subscription
+  #formDebounce
+  #reactiveDebounce
+  #reactiveDebouncedMessage
+
+  #callActionCallback = (event) => {
+    event.stopPropagation()
+
+    const { action, params } = event.detail
+
+    this.sendCall(action, params)
+  }
+
+  connect() {
+    this.element.addEventListener("call", this.#callActionCallback)
+
+    this.#subscription = SubscriptionManager.subscribe(
+      this.liveIdValue,
+      this.componentValue,
+      this.defaultsValue,
+      this
+    )
+  }
+
+  disconnect() {
+    this.element.removeEventListener("call", this.#callActionCallback)
+  }
+
+  call({ params }) {
+    this.sendCall(params.action, params)
+  }
+
+  sendCall(action, params = {}) {
+    this.#subscription.send(
+      this.#unshiftDebounced(this.#callMessage(params, action))
+    )
+  }
+
+  #callMessage(params, action) {
+    return {
+      _action: action,
+      params: new URLSearchParams(params).toString(),
+    }
+  }
+
+  reactive({ target }) {
+    this.sendReactive(target)
+  }
+
+  sendReactive(target) {
+    this.#subscription.send(
+      this.#unshiftDebounced(this.#reactiveMessage(target))
+    )
+  }
+
+  #reactiveMessage(target) {
+    return {
+      _action: '_reactive',
+      name: target.name,
+      value: target.value,
+    }
+  }
+
+  #unshiftDebounced(message) {
+    const messages = [message]
+
+    if (this.#reactiveDebouncedMessage) {
+      messages.unshift(this.#reactiveDebouncedMessage)
+      this.#reactiveDebouncedMessage = null
+    }
+
+    return { messages, _csrf_token: this.#csrfToken }
+  }
+
+  reactiveDebounce(event) {
+    clearTimeout(this.#reactiveDebounce)
+    this.#reactiveDebouncedMessage = this.#reactiveMessage(event.target)
+
+    this.#reactiveDebounce = setTimeout(() => {
+      this.#reactiveDebouncedMessage = null
+      this.reactive(event)
+    }, event.params.debounce || 200)
+  }
+
+  form({ currentTarget, params: { action } }) {
+    this.sendForm(action, currentTarget)
+  }
+
+  sendForm(action, formEl) {
+    // Clear reactive debounce so it doesn't fire after form
+    clearTimeout(this.#reactiveDebounce)
+    clearTimeout(this.#formDebounce)
+
+    const formData = new FormData(formEl)
+    const params = new URLSearchParams(formData).toString()
+
+    this.#subscription.send(
+      this.#unshiftDebounced(this.#callMessage(params, action))
+    )
+  }
+
+  formDebounce(event) {
+    clearTimeout(this.#formDebounce)
+    this.#formDebounce = setTimeout(() => {
+      this.form(event)
+    }, event.params.debounce || 200)
+  }
+
+  get #csrfToken() {
+    return document.querySelector("meta[name='csrf-token']")?.getAttribute("content")
+  }
+}

data/app/assets/javascript/live_cable_blessing.js

@@ -0,0 +1,20 @@
+import LiveController from "live_cable_controller"
+
+export default function LiveCableBlessing(constructor) {
+  Object.assign(constructor.prototype, {
+    liveCableAction(action, params = {}) {
+      this.context.logDebugActivity("liveCableAction", {
+        action,
+        params,
+      })
+
+      this.dispatch('call', {
+        detail: {
+          action,
+          params,
+        },
+        prefix: null,
+      })
+    }
+  })
+}

data/app/assets/javascript/subscriptions.js

@@ -0,0 +1,191 @@
+/**
+ * LiveCable Subscription Manager
+ *
+ * This module implements subscription persistence for LiveCable components.
+ * Instead of creating new ActionCable subscriptions every time a Stimulus controller
+ * connects/disconnects, we maintain a single subscription per component instance
+ * (identified by liveId) and simply update the controller reference.
+ *
+ * Architecture:
+ * - SubscriptionManager: Singleton that manages all active subscriptions
+ * - Subscription: Wraps an ActionCable subscription and handles morphdom updates
+ * - Controller reconnection: When a controller disconnects/reconnects (e.g., due to
+ *   Turbo navigation), the subscription persists and just updates its controller reference
+ *
+ * Benefits:
+ * - Reduces WebSocket churn
+ * - Maintains server-side state across page transitions
+ * - Eliminates race conditions from rapid connect/disconnect cycles
+ */
+
+import { createConsumer } from "@rails/actioncable"
+import morphdom from "morphdom"
+
+const consumer = createConsumer()
+
+/**
+ * Manages all LiveCable subscriptions across the application.
+ * Ensures that each component (identified by liveId) has at most one
+ * active ActionCable subscription at any time.
+ */
+class SubscriptionManager {
+  /** @type {Object.<string, Subscription>} */
+  #subscriptions = {}
+
+  /**
+   * Subscribe to or reconnect to a LiveCable component.
+   * If a subscription already exists for this liveId, updates the controller
+   * reference instead of creating a new subscription.
+   *
+   * @param {string} liveId - Unique identifier for the component instance
+   * @param {string} component - Component class name (e.g., "counter")
+   * @param {Object} defaults - Default values for reactive variables
+   * @param {Object} controller - Stimulus controller instance
+   * @returns {Subscription} The subscription instance
+   */
+  subscribe(liveId, component, defaults, controller) {
+    if (!this.#subscriptions[liveId]) {
+      this.#subscriptions[liveId] = new Subscription(liveId, component, defaults, controller)
+    }
+
+    this.#subscriptions[liveId].controller = controller
+
+    return this.#subscriptions[liveId]
+  }
+
+  /**
+   * Remove a subscription from the manager.
+   * Called when the server sends a 'destroy' status, indicating the
+   * component instance should be permanently removed.
+   *
+   * @param {string} liveId - Unique identifier for the component instance
+   */
+  unsubscribe(liveId) {
+    delete this.#subscriptions[liveId]
+  }
+}
+
+/**
+ * Represents a single ActionCable subscription to a LiveCable component.
+ * Handles receiving updates from the server and applying them to the DOM
+ * via morphdom.
+ */
+class Subscription {
+  /** @type {string} */
+  #liveId
+  /** @type {string} */
+  #component
+  /** @type {Object} */
+  #defaults
+  /** @type {Object|null} */
+  #controller
+  /** @type {Object} */
+  #subscription
+
+  /**
+   * Creates a new subscription to a LiveCable component.
+   *
+   * @param {string} liveId - Unique identifier for the component instance
+   * @param {string} component - Component class name (e.g., "counter")
+   * @param {Object} defaults - Default values for reactive variables
+   * @param {Object} controller - Stimulus controller instance
+   */
+  constructor(liveId, component, defaults, controller) {
+    this.#liveId = liveId
+    this.#component = component
+    this.#defaults = defaults
+    this.#controller = controller
+    this.#subscribe()
+  }
+
+  /**
+   * Update the controller reference.
+   * Called when a Stimulus controller reconnects to an existing subscription.
+   *
+   * @param {Object} controller - Stimulus controller instance
+   */
+  set controller(controller) {
+    this.#controller = controller
+  }
+
+  /**
+   * Send a message to the server through the ActionCable subscription.
+   *
+   * @param {Object} message - Message to send (e.g., action calls, reactive updates)
+   */
+  send(message) {
+    this.#subscription.send(message)
+  }
+
+  /**
+   * Create the underlying ActionCable subscription.
+   * @private
+   */
+  #subscribe() {
+    this.#subscription = consumer.subscriptions.create({
+      channel: "LiveChannel",
+      component: this.#component,
+      defaults: this.#defaults,
+      live_id: this.#liveId,
+    }, {
+      received: this.#received,
+    })
+  }
+
+  /**
+   * Handle incoming messages from the server.
+   * Processes status updates and DOM refreshes.
+   *
+   * @param {Object} data - Data received from the server
+   * @param {string} [data._status] - Status update (e.g., 'subscribed', 'destroy')
+   * @param {string} [data._refresh] - HTML to morph into the DOM
+   * @private
+   */
+  #received = (data) => {
+    // Handle destroy status - permanently remove this subscription
+    if (data['_status'] === 'destroy') {
+      this.#subscription.unsubscribe()
+      subscriptionManager.unsubscribe(this.#liveId)
+    }
+
+    // If no controller is attached, we can't update the DOM
+    if (!this.#controller) {
+      return
+    }
+
+    // Update connection status
+    if (data['_status']) {
+      this.#controller.statusValue = data['_status']
+    }
+    // Apply DOM updates via morphdom
+    else if (data['_refresh']) {
+      morphdom(this.#controller.element, data['_refresh'], {
+        // Preserve elements marked with live-ignore attribute
+        onBeforeElUpdated(fromEl, toEl) {
+          if (!fromEl.hasAttribute) {
+            return true
+          }
+
+          return !fromEl.hasAttribute('live-ignore')
+        },
+        // Use stable keys for better morphing performance and state preservation
+        getNodeKey(node) {
+          if (!node) {
+            return
+          }
+
+          if (node.getAttribute) {
+            return node.getAttribute('live-key') ||
+              node.getAttribute('data-live-live-io-value') ||
+              node.getAttribute('id') ||
+              node.id
+          }
+        }
+      })
+    }
+  }
+}
+
+const subscriptionManager = new SubscriptionManager()
+
+export default subscriptionManager

data/app/channels/live_channel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class LiveChannel < ActionCable::Channel::Base
+  def subscribed
+    instance = params[:live_id].present? && live_connection.get_component(params[:live_id])
+    rendered = instance.present?
+
+    unless instance
+      instance = LiveCable.instance_from_string(params[:component], params[:live_id])
+      live_connection.add_component(instance)
+      instance.defaults = params[:defaults]
+    end
+
+    stream_from(instance.channel_name)
+
+    instance.channel = self
+    instance.connected # @todo - Should this be called multiple times?
+    instance.broadcast_subscribe
+    instance.render_broadcast unless rendered
+
+    live_connection.set_channel(instance, self)
+
+    @component = instance
+  end
+
+  def receive(data)
+    live_connection.receive(component, data)
+  end
+
+  def unsubscribed
+    return unless component
+
+    stop_stream_from(component.channel_name)
+    component.disconnected
+    live_connection.remove_component(component)
+    live_connection.remove_channel(component)
+    component.live_connection = nil
+    @component = nil
+  end
+
+  private
+
+  # @return [LiveCable::Component, nil]
+  attr_reader :component
+end

data/app/helpers/live_cable_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module LiveCableHelper
+  def live_component(component, **, &block)
+    tag.div(**live_attributes(component, component.defaults, **)) do
+      capture { block.call }
+    end
+  end
+
+  # @param [LiveCable::Component] component
+  def with_render_context(component, &)
+    context = LiveCable::RenderContext.new(component)
+    context_stack.push(context)
+
+    begin
+      value = yield
+    ensure
+      context_stack.pop
+    end
+
+    [value, context]
+  end
+
+  def live(component, **options)
+    renderable = component
+    id = options.delete(:id)
+
+    if renderable.is_a?(String)
+      live_id = "#{renderable}/#{id}"
+
+      renderable = if (existing = render_context&.get_component(live_id))
+                     existing
+                   else
+                     LiveCable.instance_from_string(renderable, id)
+                   end
+    end
+
+    # @todo Move to live_component so direct renders work too, we would need to assign the options
+    #       again when a connection is assigned so it no loner uses the local container
+    render_context&.add_component(renderable)
+
+    renderable.defaults = options
+
+    render(renderable)
+  end
+
+  def live_attributes(component, defaults = {}, **options)
+    options.merge(
+      {
+        data: {
+          controller: "live #{options.with_indifferent_access.dig(:data, :controller)}".rstrip,
+          live_defaults_value: defaults.to_json,
+          live_component_value: component.class.component_string,
+          live_live_id_value: component.live_id,
+          live_status_value: component.status,
+        },
+      }
+    )
+  end
+
+  private
+
+  def context_stack
+    @context_stack ||= []
+  end
+
+  def render_context
+    context_stack.last
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+pin 'live_cable_controller', to: 'controllers/live_controller.js'
+pin 'live_cable_blessing', to: 'live_cable_blessing.js'
+pin 'live_cable_subscriptions', to: 'subscriptions.js'