@isometriks/live_cable 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +1275 -0
- package/app/assets/javascript/controllers/live_controller.js +158 -0
- package/app/assets/javascript/dom.js +161 -0
- package/app/assets/javascript/live_cable.js +50 -0
- package/app/assets/javascript/live_cable_blessing.js +20 -0
- package/app/assets/javascript/observer.js +74 -0
- package/app/assets/javascript/subscriptions.js +550 -0
- package/package.json +36 -0
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { Controller } from "@hotwired/stimulus"
|
|
2
|
+
import SubscriptionManager from "@isometriks/live_cable/subscriptions"
|
|
3
|
+
|
|
4
|
+
export default class extends Controller {
|
|
5
|
+
static values = {
|
|
6
|
+
defaults: Object,
|
|
7
|
+
status: String,
|
|
8
|
+
component: String,
|
|
9
|
+
actions: Array,
|
|
10
|
+
id: String,
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
#subscription
|
|
14
|
+
#debounces = new Map()
|
|
15
|
+
|
|
16
|
+
#callActionCallback = (event) => {
|
|
17
|
+
event.stopPropagation()
|
|
18
|
+
|
|
19
|
+
const { action, params } = event.detail
|
|
20
|
+
|
|
21
|
+
this.sendCall(action, params)
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
connect() {
|
|
25
|
+
this.element.addEventListener("call", this.#callActionCallback)
|
|
26
|
+
|
|
27
|
+
this.#subscription = SubscriptionManager.subscribe(
|
|
28
|
+
this.idValue,
|
|
29
|
+
this.componentValue,
|
|
30
|
+
this.defaultsValue,
|
|
31
|
+
this
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
// Create callbacks for each action or form
|
|
35
|
+
this.actionsValue.forEach((action) => {
|
|
36
|
+
this[`action_$${action}`] = ({ params }) => {
|
|
37
|
+
this.sendCall(action, this.#convertKeysToSnakeCase(params))
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
this[`form_$${action}`] = (event) => {
|
|
41
|
+
this.#form(action, event)
|
|
42
|
+
}
|
|
43
|
+
})
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
disconnect() {
|
|
47
|
+
this.element.removeEventListener("call", this.#callActionCallback)
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
sendCall(action, params = {}) {
|
|
51
|
+
this.#subscription.send(
|
|
52
|
+
this.#flushDebounced(this.#callMessage(params, action))
|
|
53
|
+
)
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
#callMessage(params, action) {
|
|
57
|
+
return {
|
|
58
|
+
_action: action,
|
|
59
|
+
params: new URLSearchParams(params).toString(),
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
#convertKeysToSnakeCase(params) {
|
|
64
|
+
return Object.fromEntries(
|
|
65
|
+
Object.entries(params).map(([key, value]) => [
|
|
66
|
+
key.replace(/([A-Z])/g, '_$1').toLowerCase(),
|
|
67
|
+
value
|
|
68
|
+
])
|
|
69
|
+
)
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
reactive({ target, params }) {
|
|
73
|
+
const debounce = params?.debounce
|
|
74
|
+
|
|
75
|
+
if (debounce) {
|
|
76
|
+
this.#setDebounce(target, debounce, () => {
|
|
77
|
+
this.sendReactive(target)
|
|
78
|
+
}, this.#reactiveMessage(target))
|
|
79
|
+
} else {
|
|
80
|
+
this.sendReactive(target)
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
sendReactive(target) {
|
|
85
|
+
this.#clearDebounce(target)
|
|
86
|
+
this.#subscription.send(
|
|
87
|
+
this.#flushDebounced(this.#reactiveMessage(target))
|
|
88
|
+
)
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
#reactiveMessage(target) {
|
|
92
|
+
return {
|
|
93
|
+
_action: '_reactive',
|
|
94
|
+
name: target.name,
|
|
95
|
+
value: target.value,
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
#form(action, { currentTarget, params }) {
|
|
100
|
+
const debounce = params.debounce
|
|
101
|
+
|
|
102
|
+
if (debounce) {
|
|
103
|
+
const formData = new FormData(currentTarget)
|
|
104
|
+
const formParams = new URLSearchParams(formData).toString()
|
|
105
|
+
|
|
106
|
+
this.#setDebounce(currentTarget, debounce, () => {
|
|
107
|
+
this.sendForm(action, currentTarget)
|
|
108
|
+
}, this.#callMessage(formParams, action))
|
|
109
|
+
} else {
|
|
110
|
+
this.sendForm(action, currentTarget)
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
sendForm(action, formEl) {
|
|
115
|
+
this.#clearDebounce(formEl)
|
|
116
|
+
|
|
117
|
+
const formData = new FormData(formEl)
|
|
118
|
+
const params = new URLSearchParams(formData).toString()
|
|
119
|
+
|
|
120
|
+
this.#subscription.send(
|
|
121
|
+
this.#flushDebounced(this.#callMessage(params, action))
|
|
122
|
+
)
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
#setDebounce(source, delay, callback, message) {
|
|
126
|
+
// Clear existing debounce for this source
|
|
127
|
+
this.#clearDebounce(source)
|
|
128
|
+
|
|
129
|
+
// Set new debounce
|
|
130
|
+
const timeout = setTimeout(callback, delay)
|
|
131
|
+
this.#debounces.set(source, { timeout, message })
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
#clearDebounce(source) {
|
|
135
|
+
const debounce = this.#debounces.get(source)
|
|
136
|
+
if (debounce) {
|
|
137
|
+
clearTimeout(debounce.timeout)
|
|
138
|
+
this.#debounces.delete(source)
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
#flushDebounced(message) {
|
|
143
|
+
const messages = [message]
|
|
144
|
+
|
|
145
|
+
// Add all pending debounced messages to be sent immediately
|
|
146
|
+
for (const [source, { timeout, message: debouncedMessage }] of this.#debounces) {
|
|
147
|
+
clearTimeout(timeout)
|
|
148
|
+
messages.unshift(debouncedMessage)
|
|
149
|
+
}
|
|
150
|
+
this.#debounces.clear()
|
|
151
|
+
|
|
152
|
+
return { messages, _csrf_token: this.#csrfToken }
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
get #csrfToken() {
|
|
156
|
+
return document.querySelector("meta[name='csrf-token']")?.getAttribute("content")
|
|
157
|
+
}
|
|
158
|
+
}
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DOM transformation module for LiveCable
|
|
3
|
+
*
|
|
4
|
+
* Converts live-* HTML attributes into Stimulus data-* attributes at runtime.
|
|
5
|
+
* This allows for a cleaner HTML syntax while maintaining full Stimulus compatibility.
|
|
6
|
+
*/
|
|
7
|
+
class DOM {
|
|
8
|
+
// All live-* attributes that trigger DOM processing
|
|
9
|
+
static LIVE_ATTRIBUTES = [
|
|
10
|
+
'live-id',
|
|
11
|
+
'live-component',
|
|
12
|
+
'live-defaults',
|
|
13
|
+
'live-actions',
|
|
14
|
+
'live-form',
|
|
15
|
+
'live-action',
|
|
16
|
+
'live-reactive'
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Transforms all live-* attributes on an element and its descendants
|
|
21
|
+
* @param {HTMLElement} element - The root element to process
|
|
22
|
+
*/
|
|
23
|
+
mutate(element) {
|
|
24
|
+
if (!element || !element.querySelectorAll) {
|
|
25
|
+
return
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// Build selector for all live-* attributes we care about
|
|
29
|
+
const selector = DOM.LIVE_ATTRIBUTES.map(attr => `[${attr}]`).join(', ')
|
|
30
|
+
|
|
31
|
+
// Get all elements with live-* attributes (including the root element if it matches)
|
|
32
|
+
const liveElements = []
|
|
33
|
+
if (element.matches && element.matches(selector)) {
|
|
34
|
+
liveElements.push(element)
|
|
35
|
+
}
|
|
36
|
+
liveElements.push(...element.querySelectorAll(selector))
|
|
37
|
+
|
|
38
|
+
liveElements.forEach(el => {
|
|
39
|
+
// Process component metadata attributes first
|
|
40
|
+
this.#processMetadataAttributes(el)
|
|
41
|
+
|
|
42
|
+
// Process interactive attributes (actions, forms, reactive)
|
|
43
|
+
this.#processInteractiveAttributes(el)
|
|
44
|
+
|
|
45
|
+
// Process live-id last so all other attributes are converted before
|
|
46
|
+
// the Stimulus controller is attached
|
|
47
|
+
if (el.hasAttribute('live-id')) {
|
|
48
|
+
this.#replaceLiveId(el)
|
|
49
|
+
}
|
|
50
|
+
})
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
#processMetadataAttributes(element) {
|
|
54
|
+
if (element.hasAttribute('live-component')) {
|
|
55
|
+
this.#replaceAttribute(element, 'live-component', 'data-live-component-value')
|
|
56
|
+
}
|
|
57
|
+
if (element.hasAttribute('live-defaults')) {
|
|
58
|
+
this.#replaceAttribute(element, 'live-defaults', 'data-live-defaults-value')
|
|
59
|
+
}
|
|
60
|
+
if (element.hasAttribute('live-actions')) {
|
|
61
|
+
this.#replaceAttribute(element, 'live-actions', 'data-live-actions-value')
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
#processInteractiveAttributes(element) {
|
|
66
|
+
// Note: convertValues and convertDebounce are called for each type as needed
|
|
67
|
+
if (element.hasAttribute('live-form')) {
|
|
68
|
+
this.#convertValues(element)
|
|
69
|
+
this.#convertDebounce(element)
|
|
70
|
+
this.#addActions(element, 'form', 'live-form', ':prevent')
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
if (element.hasAttribute('live-action')) {
|
|
74
|
+
this.#convertValues(element)
|
|
75
|
+
this.#convertDebounce(element)
|
|
76
|
+
this.#addActions(element, 'action', 'live-action')
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (element.hasAttribute('live-reactive')) {
|
|
80
|
+
this.#convertDebounce(element)
|
|
81
|
+
this.#convertReactive(element)
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
#replaceAttribute(element, oldAttr, newAttr) {
|
|
86
|
+
const value = element.getAttribute(oldAttr)
|
|
87
|
+
if (value !== null) {
|
|
88
|
+
element.removeAttribute(oldAttr)
|
|
89
|
+
element.setAttribute(newAttr, value)
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
#addActions(element, type, attribute, eventModifier = '') {
|
|
94
|
+
const attributeValue = element.getAttribute(attribute)
|
|
95
|
+
if (!attributeValue) return
|
|
96
|
+
|
|
97
|
+
const actions = attributeValue.trim().split(/\s+/).map(actionString => {
|
|
98
|
+
const parts = actionString.split(/->/)
|
|
99
|
+
const [event, action] = parts.length === 2 ? parts : [null, parts[0]]
|
|
100
|
+
const stimulusEvent = event ? `${event}->` : ''
|
|
101
|
+
|
|
102
|
+
return `${stimulusEvent}live#${type}_$${action}${eventModifier}`
|
|
103
|
+
})
|
|
104
|
+
|
|
105
|
+
element.removeAttribute(attribute)
|
|
106
|
+
this.#appendToAttribute(element, 'data-action', actions.join(' '))
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
#convertValues(element) {
|
|
110
|
+
// Get all attributes that start with 'live-value-'
|
|
111
|
+
Array.from(element.attributes).forEach(attr => {
|
|
112
|
+
if (attr.name.startsWith('live-value-')) {
|
|
113
|
+
const paramName = attr.name.substring('live-value-'.length)
|
|
114
|
+
element.removeAttribute(attr.name)
|
|
115
|
+
element.setAttribute(`data-live-${paramName}-param`, attr.value)
|
|
116
|
+
}
|
|
117
|
+
})
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
#convertDebounce(element) {
|
|
121
|
+
if (element.hasAttribute('live-debounce')) {
|
|
122
|
+
const value = element.getAttribute('live-debounce')
|
|
123
|
+
element.removeAttribute('live-debounce')
|
|
124
|
+
element.setAttribute('data-live-debounce-param', value)
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
#convertReactive(element) {
|
|
129
|
+
const value = element.getAttribute('live-reactive')
|
|
130
|
+
element.removeAttribute('live-reactive')
|
|
131
|
+
|
|
132
|
+
if (!value || value.trim() === '') {
|
|
133
|
+
// No events specified, use default Stimulus event
|
|
134
|
+
this.#appendToAttribute(element, 'data-action', 'live#reactive')
|
|
135
|
+
} else {
|
|
136
|
+
// Multiple events specified, convert each to event->live#reactive
|
|
137
|
+
const actions = value.trim().split(/\s+/).map(event => `${event}->live#reactive`)
|
|
138
|
+
this.#appendToAttribute(element, 'data-action', actions.join(' '))
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
#replaceLiveId(element) {
|
|
143
|
+
this.#replaceAttribute(element, 'live-id', 'data-live-id-value')
|
|
144
|
+
this.#appendToAttribute(element, 'data-controller', 'live')
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
#appendToAttribute(element, attributeName, value) {
|
|
148
|
+
const existing = element.getAttribute(attributeName)
|
|
149
|
+
|
|
150
|
+
if (existing) {
|
|
151
|
+
const values = existing.split(/\s+/)
|
|
152
|
+
if (!values.includes(value)) {
|
|
153
|
+
element.setAttribute(attributeName, `${existing} ${value}`)
|
|
154
|
+
}
|
|
155
|
+
} else {
|
|
156
|
+
element.setAttribute(attributeName, value)
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export default new DOM()
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import LiveObserver from '@isometriks/live_cable/observer'
|
|
2
|
+
import SubscriptionManager from '@isometriks/live_cable/subscriptions'
|
|
3
|
+
import DOM from '@isometriks/live_cable/dom'
|
|
4
|
+
|
|
5
|
+
const observer = new LiveObserver()
|
|
6
|
+
observer.start()
|
|
7
|
+
|
|
8
|
+
document.addEventListener('turbo:before-render', (event) => {
|
|
9
|
+
SubscriptionManager.prune(event.detail.newBody)
|
|
10
|
+
})
|
|
11
|
+
|
|
12
|
+
document.addEventListener('turbo:load', () => {
|
|
13
|
+
DOM.mutate(document.documentElement)
|
|
14
|
+
updateCacheControl()
|
|
15
|
+
})
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Ensure pages with live components are never stored in Turbo's page cache.
|
|
19
|
+
*
|
|
20
|
+
* Turbo's back/forward cache restores a snapshot of the page taken at
|
|
21
|
+
* navigate time. A restored snapshot would reconnect Stimulus controllers
|
|
22
|
+
* to subscriptions that were already closed server-side, causing a cold
|
|
23
|
+
* re-render that may fail. Preventing caching forces a fresh server fetch
|
|
24
|
+
* on back/forward, so components are always pre-rendered before their
|
|
25
|
+
* ActionCable subscription connects.
|
|
26
|
+
*
|
|
27
|
+
* If the developer has already set a turbo-cache-control meta tag (e.g.
|
|
28
|
+
* "no-store"), that value is left untouched so they can override this
|
|
29
|
+
* behaviour per-page.
|
|
30
|
+
*/
|
|
31
|
+
function updateCacheControl() {
|
|
32
|
+
// A meta tag without our marker was placed by the developer — leave it alone
|
|
33
|
+
const devMeta = document.querySelector('meta[name="turbo-cache-control"]:not([data-live-cable])')
|
|
34
|
+
if (devMeta) return
|
|
35
|
+
|
|
36
|
+
const ourMeta = document.querySelector('meta[name="turbo-cache-control"][data-live-cable]')
|
|
37
|
+
const hasLiveComponents = !!document.querySelector('[data-controller~="live"]')
|
|
38
|
+
|
|
39
|
+
if (hasLiveComponents && !ourMeta) {
|
|
40
|
+
const meta = document.createElement('meta')
|
|
41
|
+
meta.name = 'turbo-cache-control'
|
|
42
|
+
meta.content = 'no-cache'
|
|
43
|
+
meta.dataset.liveCable = ''
|
|
44
|
+
document.head.appendChild(meta)
|
|
45
|
+
} else if (!hasLiveComponents && ourMeta) {
|
|
46
|
+
ourMeta.remove()
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export default observer
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import LiveController from "@isometriks/live_cable/controller"
|
|
2
|
+
|
|
3
|
+
export default function LiveCableBlessing(constructor) {
|
|
4
|
+
Object.assign(constructor.prototype, {
|
|
5
|
+
liveCableAction(action, params = {}) {
|
|
6
|
+
this.context.logDebugActivity("liveCableAction", {
|
|
7
|
+
action,
|
|
8
|
+
params,
|
|
9
|
+
})
|
|
10
|
+
|
|
11
|
+
this.dispatch('call', {
|
|
12
|
+
detail: {
|
|
13
|
+
action,
|
|
14
|
+
params,
|
|
15
|
+
},
|
|
16
|
+
prefix: null,
|
|
17
|
+
})
|
|
18
|
+
}
|
|
19
|
+
})
|
|
20
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import DOM from "@isometriks/live_cable/dom"
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* LiveCable DOM Observer
|
|
5
|
+
*
|
|
6
|
+
* Observes the DOM for elements with the `live-id` attribute
|
|
7
|
+
*/
|
|
8
|
+
export default class LiveObserver {
|
|
9
|
+
#observer
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Start observing the DOM for live components
|
|
13
|
+
*/
|
|
14
|
+
start() {
|
|
15
|
+
if (this.#observer) {
|
|
16
|
+
return
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
this.#observer = new MutationObserver((mutations) => {
|
|
20
|
+
mutations.forEach((mutation) => {
|
|
21
|
+
// Handle added nodes
|
|
22
|
+
mutation.addedNodes.forEach((node) => {
|
|
23
|
+
if (node.nodeType === Node.ELEMENT_NODE) {
|
|
24
|
+
this.checkElement(node)
|
|
25
|
+
}
|
|
26
|
+
})
|
|
27
|
+
|
|
28
|
+
// Handle attribute changes
|
|
29
|
+
if (mutation.type === 'attributes' && mutation.attributeName === 'live-id') {
|
|
30
|
+
const element = mutation.target
|
|
31
|
+
if (element.hasAttribute('live-id')) {
|
|
32
|
+
DOM.mutate(element)
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
})
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
this.#observer.observe(document.documentElement, {
|
|
39
|
+
childList: true,
|
|
40
|
+
subtree: true,
|
|
41
|
+
attributes: true,
|
|
42
|
+
attributeFilter: ['live-id'],
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
// Check the DOM as well when we start
|
|
46
|
+
this.checkElement(document.documentElement)
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Stop observing the DOM
|
|
51
|
+
*/
|
|
52
|
+
stop() {
|
|
53
|
+
if (this.#observer) {
|
|
54
|
+
this.#observer.disconnect()
|
|
55
|
+
this.#observer = null
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Check if an element or its descendants have live-id attribute
|
|
61
|
+
*/
|
|
62
|
+
checkElement(element) {
|
|
63
|
+
if (element.hasAttribute && element.hasAttribute('live-id')) {
|
|
64
|
+
DOM.mutate(element)
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
if (element.querySelectorAll) {
|
|
68
|
+
const liveElements = element.querySelectorAll('[live-id]')
|
|
69
|
+
liveElements.forEach((liveElement) => {
|
|
70
|
+
DOM.mutate(liveElement)
|
|
71
|
+
})
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|