live_cable 0.0.1 → 0.1.2

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

@@ -1,18 +1,17 @@
 import { Controller } from "@hotwired/stimulus"
-import SubscriptionManager from "live_cable_subscriptions"
+import SubscriptionManager from "@isometriks/live_cable/subscriptions"
 
 export default class extends Controller {
   static values = {
     defaults: Object,
     status: String,
     component: String,
-    liveId: String,
+    actions: Array,
+    id: String,
   }
 
   #subscription
-  #formDebounce
-  #reactiveDebounce
-  #reactiveDebouncedMessage
+  #debounces = new Map()
 
   #callActionCallback = (event) => {
     event.stopPropagation()
@@ -26,24 +25,31 @@ export default class extends Controller {
     this.element.addEventListener("call", this.#callActionCallback)
 
     this.#subscription = SubscriptionManager.subscribe(
-      this.liveIdValue,
+      this.idValue,
       this.componentValue,
       this.defaultsValue,
       this
     )
+
+    // Create callbacks for each action or form
+    this.actionsValue.forEach((action) => {
+      this[`action_$${action}`] = ({ params }) => {
+        this.sendCall(action, this.#convertKeysToSnakeCase(params))
+      }
+
+      this[`form_$${action}`] = (event) => {
+        this.#form(action, event)
+      }
+    })
   }
 
   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))
+      this.#flushDebounced(this.#callMessage(params, action))
     )
   }
 
@@ -54,13 +60,31 @@ export default class extends Controller {
     }
   }
 
-  reactive({ target }) {
-    this.sendReactive(target)
+  #convertKeysToSnakeCase(params) {
+    return Object.fromEntries(
+      Object.entries(params).map(([key, value]) => [
+        key.replace(/([A-Z])/g, '_$1').toLowerCase(),
+        value
+      ])
+    )
+  }
+
+  reactive({ target, params }) {
+    const debounce = params?.debounce
+
+    if (debounce) {
+      this.#setDebounce(target, debounce, () => {
+        this.sendReactive(target)
+      }, this.#reactiveMessage(target))
+    } else {
+      this.sendReactive(target)
+    }
   }
 
   sendReactive(target) {
+    this.#clearDebounce(target)
     this.#subscription.send(
-      this.#unshiftDebounced(this.#reactiveMessage(target))
+      this.#flushDebounced(this.#reactiveMessage(target))
     )
   }
 
@@ -72,49 +96,60 @@ export default class extends Controller {
     }
   }
 
-  #unshiftDebounced(message) {
-    const messages = [message]
-
-    if (this.#reactiveDebouncedMessage) {
-      messages.unshift(this.#reactiveDebouncedMessage)
-      this.#reactiveDebouncedMessage = null
-    }
-
-    return { messages, _csrf_token: this.#csrfToken }
-  }
+  #form(action, { currentTarget, params }) {
+    const debounce = params.debounce
 
-  reactiveDebounce(event) {
-    clearTimeout(this.#reactiveDebounce)
-    this.#reactiveDebouncedMessage = this.#reactiveMessage(event.target)
+    if (debounce) {
+      const formData = new FormData(currentTarget)
+      const formParams = new URLSearchParams(formData).toString()
 
-    this.#reactiveDebounce = setTimeout(() => {
-      this.#reactiveDebouncedMessage = null
-      this.reactive(event)
-    }, event.params.debounce || 200)
-  }
-
-  form({ currentTarget, params: { action } }) {
-    this.sendForm(action, currentTarget)
+      this.#setDebounce(currentTarget, debounce, () => {
+        this.sendForm(action, currentTarget)
+      }, this.#callMessage(formParams, action))
+    } else {
+      this.sendForm(action, currentTarget)
+    }
   }
 
   sendForm(action, formEl) {
-    // Clear reactive debounce so it doesn't fire after form
-    clearTimeout(this.#reactiveDebounce)
-    clearTimeout(this.#formDebounce)
+    this.#clearDebounce(formEl)
 
     const formData = new FormData(formEl)
     const params = new URLSearchParams(formData).toString()
 
     this.#subscription.send(
-      this.#unshiftDebounced(this.#callMessage(params, action))
+      this.#flushDebounced(this.#callMessage(params, action))
     )
   }
 
-  formDebounce(event) {
-    clearTimeout(this.#formDebounce)
-    this.#formDebounce = setTimeout(() => {
-      this.form(event)
-    }, event.params.debounce || 200)
+  #setDebounce(source, delay, callback, message) {
+    // Clear existing debounce for this source
+    this.#clearDebounce(source)
+
+    // Set new debounce
+    const timeout = setTimeout(callback, delay)
+    this.#debounces.set(source, { timeout, message })
+  }
+
+  #clearDebounce(source) {
+    const debounce = this.#debounces.get(source)
+    if (debounce) {
+      clearTimeout(debounce.timeout)
+      this.#debounces.delete(source)
+    }
+  }
+
+  #flushDebounced(message) {
+    const messages = [message]
+
+    // Add all pending debounced messages to be sent immediately
+    for (const [source, { timeout, message: debouncedMessage }] of this.#debounces) {
+      clearTimeout(timeout)
+      messages.unshift(debouncedMessage)
+    }
+    this.#debounces.clear()
+
+    return { messages, _csrf_token: this.#csrfToken }
   }
 
   get #csrfToken() {

data/app/assets/javascript/dom.js

@@ -0,0 +1,161 @@
+/**
+ * DOM transformation module for LiveCable
+ *
+ * Converts live-* HTML attributes into Stimulus data-* attributes at runtime.
+ * This allows for a cleaner HTML syntax while maintaining full Stimulus compatibility.
+ */
+class DOM {
+  // All live-* attributes that trigger DOM processing
+  static LIVE_ATTRIBUTES = [
+    'live-id',
+    'live-component',
+    'live-defaults',
+    'live-actions',
+    'live-form',
+    'live-action',
+    'live-reactive'
+  ]
+
+  /**
+   * Transforms all live-* attributes on an element and its descendants
+   * @param {HTMLElement} element - The root element to process
+   */
+  mutate(element) {
+    if (!element || !element.querySelectorAll) {
+      return
+    }
+
+    // Build selector for all live-* attributes we care about
+    const selector = DOM.LIVE_ATTRIBUTES.map(attr => `[${attr}]`).join(', ')
+
+    // Get all elements with live-* attributes (including the root element if it matches)
+    const liveElements = []
+    if (element.matches && element.matches(selector)) {
+      liveElements.push(element)
+    }
+    liveElements.push(...element.querySelectorAll(selector))
+
+    liveElements.forEach(el => {
+      // Process component metadata attributes first
+      this.#processMetadataAttributes(el)
+
+      // Process interactive attributes (actions, forms, reactive)
+      this.#processInteractiveAttributes(el)
+
+      // Process live-id last so all other attributes are converted before
+      // the Stimulus controller is attached
+      if (el.hasAttribute('live-id')) {
+        this.#replaceLiveId(el)
+      }
+    })
+  }
+
+  #processMetadataAttributes(element) {
+    if (element.hasAttribute('live-component')) {
+      this.#replaceAttribute(element, 'live-component', 'data-live-component-value')
+    }
+    if (element.hasAttribute('live-defaults')) {
+      this.#replaceAttribute(element, 'live-defaults', 'data-live-defaults-value')
+    }
+    if (element.hasAttribute('live-actions')) {
+      this.#replaceAttribute(element, 'live-actions', 'data-live-actions-value')
+    }
+  }
+
+  #processInteractiveAttributes(element) {
+    // Note: convertValues and convertDebounce are called for each type as needed
+    if (element.hasAttribute('live-form')) {
+      this.#convertValues(element)
+      this.#convertDebounce(element)
+      this.#addActions(element, 'form', 'live-form', ':prevent')
+    }
+
+    if (element.hasAttribute('live-action')) {
+      this.#convertValues(element)
+      this.#convertDebounce(element)
+      this.#addActions(element, 'action', 'live-action')
+    }
+
+    if (element.hasAttribute('live-reactive')) {
+      this.#convertDebounce(element)
+      this.#convertReactive(element)
+    }
+  }
+
+  #replaceAttribute(element, oldAttr, newAttr) {
+    const value = element.getAttribute(oldAttr)
+    if (value !== null) {
+      element.removeAttribute(oldAttr)
+      element.setAttribute(newAttr, value)
+    }
+  }
+
+  #addActions(element, type, attribute, eventModifier = '') {
+    const attributeValue = element.getAttribute(attribute)
+    if (!attributeValue) return
+
+    const actions = attributeValue.trim().split(/\s+/).map(actionString => {
+      const parts = actionString.split(/->/)
+      const [event, action] = parts.length === 2 ? parts : [null, parts[0]]
+      const stimulusEvent = event ? `${event}->` : ''
+
+      return `${stimulusEvent}live#${type}_$${action}${eventModifier}`
+    })
+
+    element.removeAttribute(attribute)
+    this.#appendToAttribute(element, 'data-action', actions.join(' '))
+  }
+
+  #convertValues(element) {
+    // Get all attributes that start with 'live-value-'
+    Array.from(element.attributes).forEach(attr => {
+      if (attr.name.startsWith('live-value-')) {
+        const paramName = attr.name.substring('live-value-'.length)
+        element.removeAttribute(attr.name)
+        element.setAttribute(`data-live-${paramName}-param`, attr.value)
+      }
+    })
+  }
+
+  #convertDebounce(element) {
+    if (element.hasAttribute('live-debounce')) {
+      const value = element.getAttribute('live-debounce')
+      element.removeAttribute('live-debounce')
+      element.setAttribute('data-live-debounce-param', value)
+    }
+  }
+
+  #convertReactive(element) {
+    const value = element.getAttribute('live-reactive')
+    element.removeAttribute('live-reactive')
+
+    if (!value || value.trim() === '') {
+      // No events specified, use default Stimulus event
+      this.#appendToAttribute(element, 'data-action', 'live#reactive')
+    } else {
+      // Multiple events specified, convert each to event->live#reactive
+      const actions = value.trim().split(/\s+/).map(event => `${event}->live#reactive`)
+      this.#appendToAttribute(element, 'data-action', actions.join(' '))
+    }
+  }
+
+  #replaceLiveId(element) {
+    this.#replaceAttribute(element, 'live-id', 'data-live-id-value')
+    this.#appendToAttribute(element, 'data-controller', 'live')
+  }
+
+  #appendToAttribute(element, attributeName, value) {
+    const existing = element.getAttribute(attributeName)
+
+    if (existing) {
+      const values = existing.split(/\s+/)
+      if (!values.includes(value)) {
+        element.setAttribute(attributeName, `${existing} ${value}`)
+      }
+    } else {
+      element.setAttribute(attributeName, value)
+    }
+  }
+}
+
+export default new DOM()

data/app/assets/javascript/live_cable.js

@@ -0,0 +1,50 @@
+import LiveObserver from '@isometriks/live_cable/observer'
+import SubscriptionManager from '@isometriks/live_cable/subscriptions'
+import DOM from '@isometriks/live_cable/dom'
+
+const observer = new LiveObserver()
+observer.start()
+
+document.addEventListener('turbo:before-render', (event) => {
+  SubscriptionManager.prune(event.detail.newBody)
+})
+
+document.addEventListener('turbo:load', () => {
+  DOM.mutate(document.documentElement)
+  updateCacheControl()
+})
+
+/**
+ * Ensure pages with live components are never stored in Turbo's page cache.
+ *
+ * Turbo's back/forward cache restores a snapshot of the page taken at
+ * navigate time. A restored snapshot would reconnect Stimulus controllers
+ * to subscriptions that were already closed server-side, causing a cold
+ * re-render that may fail. Preventing caching forces a fresh server fetch
+ * on back/forward, so components are always pre-rendered before their
+ * ActionCable subscription connects.
+ *
+ * If the developer has already set a turbo-cache-control meta tag (e.g.
+ * "no-store"), that value is left untouched so they can override this
+ * behaviour per-page.
+ */
+function updateCacheControl() {
+  // A meta tag without our marker was placed by the developer — leave it alone
+  const devMeta = document.querySelector('meta[name="turbo-cache-control"]:not([data-live-cable])')
+  if (devMeta) return
+
+  const ourMeta = document.querySelector('meta[name="turbo-cache-control"][data-live-cable]')
+  const hasLiveComponents = !!document.querySelector('[data-controller~="live"]')
+
+  if (hasLiveComponents && !ourMeta) {
+    const meta = document.createElement('meta')
+    meta.name = 'turbo-cache-control'
+    meta.content = 'no-cache'
+    meta.dataset.liveCable = ''
+    document.head.appendChild(meta)
+  } else if (!hasLiveComponents && ourMeta) {
+    ourMeta.remove()
+  }
+}
+
+export default observer

data/app/assets/javascript/live_cable_blessing.js

@@ -1,4 +1,4 @@
-import LiveController from "live_cable_controller"
+import LiveController from "@isometriks/live_cable/controller"
 
 export default function LiveCableBlessing(constructor) {
   Object.assign(constructor.prototype, {

data/app/assets/javascript/observer.js

@@ -0,0 +1,74 @@
+import DOM from "@isometriks/live_cable/dom"
+
+/**
+ * LiveCable DOM Observer
+ *
+ * Observes the DOM for elements with the `live-id` attribute
+ */
+export default class LiveObserver {
+  #observer
+
+  /**
+   * Start observing the DOM for live components
+   */
+  start() {
+    if (this.#observer) {
+      return
+    }
+
+    this.#observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        // Handle added nodes
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.checkElement(node)
+          }
+        })
+
+        // Handle attribute changes
+        if (mutation.type === 'attributes' && mutation.attributeName === 'live-id') {
+          const element = mutation.target
+          if (element.hasAttribute('live-id')) {
+            DOM.mutate(element)
+          }
+        }
+      })
+    })
+
+    this.#observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['live-id'],
+    })
+
+    // Check the DOM as well when we start
+    this.checkElement(document.documentElement)
+  }
+
+  /**
+   * Stop observing the DOM
+   */
+  stop() {
+    if (this.#observer) {
+      this.#observer.disconnect()
+      this.#observer = null
+    }
+  }
+
+  /**
+   * Check if an element or its descendants have live-id attribute
+   */
+  checkElement(element) {
+    if (element.hasAttribute && element.hasAttribute('live-id')) {
+      DOM.mutate(element)
+    }
+
+    if (element.querySelectorAll) {
+      const liveElements = element.querySelectorAll('[live-id]')
+      liveElements.forEach((liveElement) => {
+        DOM.mutate(liveElement)
+      })
+    }
+  }
+}