@isometriks/live_cable 0.2.1 → 0.4.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/CHANGELOG.md +629 -0
- package/README.md +27 -17
- package/app/assets/javascript/controllers/live_controller.js +54 -13
- package/app/assets/javascript/live_cable.js +2 -0
- package/app/assets/javascript/loading.js +58 -6
- package/app/assets/javascript/subscriptions.js +292 -22
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -30,21 +30,19 @@ bundle install
|
|
|
30
30
|
|
|
31
31
|
## Configuration
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
end
|
|
47
|
-
```
|
|
33
|
+
There is nothing to configure on the cable side. LiveCable attaches itself to
|
|
34
|
+
`ActionCable::Connection::Base`, so your `ApplicationCable::Connection` stays as
|
|
35
|
+
it is, with whatever `identified_by` it declares or none at all. LiveCable needs
|
|
36
|
+
no identifiers of its own.
|
|
37
|
+
|
|
38
|
+
If you followed an earlier version of this guide, remove the
|
|
39
|
+
`identified_by :live_connection` line and the `connect` override that went with
|
|
40
|
+
it. Remove both at once, since either one on its own breaks every connection.
|
|
41
|
+
Together they keep working, but they make a per-socket object part of the
|
|
42
|
+
connection's identity, which stops `ActionCable.server.remote_connections` from
|
|
43
|
+
ever finding your users' sockets. See the
|
|
44
|
+
[architecture guide](https://livecable.io/guide/architecture#sign-in-and-sign-out)
|
|
45
|
+
for what to do about sockets when a user signs in or out.
|
|
48
46
|
|
|
49
47
|
## JavaScript Setup
|
|
50
48
|
|
|
@@ -591,7 +589,7 @@ self.count.+(1)
|
|
|
591
589
|
self.name.concat("Doe")
|
|
592
590
|
```
|
|
593
591
|
|
|
594
|
-
For more details on the change tracking architecture, see [
|
|
592
|
+
For more details on the change tracking architecture, see the [architecture guide](https://livecable.io/guide/architecture).
|
|
595
593
|
|
|
596
594
|
## Shared Variables
|
|
597
595
|
|
|
@@ -651,7 +649,7 @@ module Live
|
|
|
651
649
|
end
|
|
652
650
|
```
|
|
653
651
|
|
|
654
|
-
**Use case**: FilterPanel can read the cart to show item count in a badge, but doesn't need to re-render every time an item is added—only when the filter changes.
|
|
652
|
+
**Use case**: FilterPanel can read the cart to show item count in a badge, but doesn't need to re-render every time an item is added—only when the filter changes. Whenever FilterPanel re-renders for its own reasons, parts that read `cart_items` (directly or through a method) re-render too, so the badge picks up the latest count.
|
|
655
653
|
|
|
656
654
|
## Action Whitelisting
|
|
657
655
|
|
|
@@ -899,6 +897,18 @@ Updates a reactive variable when an input changes. The corresponding reactive va
|
|
|
899
897
|
<input type="text" name="query" live-reactive="keydown keyup">
|
|
900
898
|
```
|
|
901
899
|
|
|
900
|
+
The value sent depends on the input: a checkbox sends `true` or `false` (whether it is checked, regardless of its `value` attribute), a `<select multiple>` sends an Array of the selected option values, and everything else, radio buttons included, sends its `value` as a String.
|
|
901
|
+
|
|
902
|
+
```html
|
|
903
|
+
<input type="checkbox" name="notify" live-reactive <%= 'checked' if notify %>>
|
|
904
|
+
|
|
905
|
+
<select multiple name="tags" live-reactive="change">
|
|
906
|
+
<% %w[ruby rails].each do |tag| %>
|
|
907
|
+
<option value="<%= tag %>" <%= 'selected' if tags.include?(tag) %>><%= tag %></option>
|
|
908
|
+
<% end %>
|
|
909
|
+
</select>
|
|
910
|
+
```
|
|
911
|
+
|
|
902
912
|
**Transformation:** `live-reactive` becomes `data-action="live#reactive"`, and `live-reactive="keydown"` becomes `data-action="keydown->live#reactive"`
|
|
903
913
|
|
|
904
914
|
### `live-debounce`
|
|
@@ -4,7 +4,9 @@ import LoadingState from "@isometriks/live_cable/loading"
|
|
|
4
4
|
|
|
5
5
|
export default class extends Controller {
|
|
6
6
|
static values = {
|
|
7
|
-
|
|
7
|
+
// Opaque signed blob produced by the server; forwarded verbatim to the
|
|
8
|
+
// channel on subscribe, where it is verified and decoded.
|
|
9
|
+
defaults: String,
|
|
8
10
|
status: String,
|
|
9
11
|
component: String,
|
|
10
12
|
actions: Array,
|
|
@@ -24,7 +26,7 @@ export default class extends Controller {
|
|
|
24
26
|
}
|
|
25
27
|
|
|
26
28
|
connect() {
|
|
27
|
-
this.#loading = new LoadingState(this.element)
|
|
29
|
+
this.#loading = new LoadingState(this.element, { onStalled: () => this.#stalled() })
|
|
28
30
|
this.element.addEventListener("call", this.#callActionCallback)
|
|
29
31
|
|
|
30
32
|
this.#subscription = SubscriptionManager.subscribe(
|
|
@@ -34,6 +36,12 @@ export default class extends Controller {
|
|
|
34
36
|
this
|
|
35
37
|
)
|
|
36
38
|
|
|
39
|
+
// The subscription outlives a controller, so messages held from before a
|
|
40
|
+
// disconnect need this controller's watchdog
|
|
41
|
+
for (let i = this.#subscription.pendingCount; i > 0; i--) {
|
|
42
|
+
this.#loading.start()
|
|
43
|
+
}
|
|
44
|
+
|
|
37
45
|
// Create callbacks for each action or form
|
|
38
46
|
this.actionsValue.forEach((action) => {
|
|
39
47
|
this[`action_$${action}`] = ({ params, currentTarget }) => {
|
|
@@ -48,6 +56,9 @@ export default class extends Controller {
|
|
|
48
56
|
|
|
49
57
|
disconnect() {
|
|
50
58
|
this.element.removeEventListener("call", this.#callActionCallback)
|
|
59
|
+
// A new controller brings its own loading state; don't leave this one's
|
|
60
|
+
// watchdog to fire on an element that has gone
|
|
61
|
+
this.#loading?.reset()
|
|
51
62
|
}
|
|
52
63
|
|
|
53
64
|
sendCall(action, params = {}, trigger = null) {
|
|
@@ -57,11 +68,12 @@ export default class extends Controller {
|
|
|
57
68
|
)
|
|
58
69
|
}
|
|
59
70
|
|
|
60
|
-
// Called by the subscription when the server answers a message
|
|
61
|
-
//
|
|
62
|
-
// state once all in-flight messages have been answered
|
|
71
|
+
// Called by the subscription when the server answers a message (its
|
|
72
|
+
// reply, an ack, or an error). Restores any live-loading / live-disable-with
|
|
73
|
+
// state once all in-flight messages have been answered, and returns true
|
|
74
|
+
// when it did.
|
|
63
75
|
finishLoading() {
|
|
64
|
-
this.#loading?.finish()
|
|
76
|
+
return this.#loading?.finish() ?? false
|
|
65
77
|
}
|
|
66
78
|
|
|
67
79
|
// Whether any message is still awaiting a server response
|
|
@@ -69,11 +81,31 @@ export default class extends Controller {
|
|
|
69
81
|
return this.#loading?.active ?? false
|
|
70
82
|
}
|
|
71
83
|
|
|
84
|
+
// How many messages are still awaiting a server response
|
|
85
|
+
get inFlight() {
|
|
86
|
+
return this.#loading?.inFlight ?? 0
|
|
87
|
+
}
|
|
88
|
+
|
|
72
89
|
// Called by the subscription when the component is being torn down.
|
|
73
90
|
resetLoading() {
|
|
74
91
|
this.#loading?.reset()
|
|
75
92
|
}
|
|
76
93
|
|
|
94
|
+
// The loading state gave up waiting for a reply. Anything still held for a
|
|
95
|
+
// reconnect is dropped with it, so a message the page has said didn't go
|
|
96
|
+
// through can't go through later - the user would click again, and it
|
|
97
|
+
// would run twice. A message already sent can't be recalled; the event
|
|
98
|
+
// says how many were dropped so the page can word its message.
|
|
99
|
+
#stalled() {
|
|
100
|
+
const discarded = this.#subscription?.discardPending() ?? 0
|
|
101
|
+
|
|
102
|
+
this.statusValue = 'stalled'
|
|
103
|
+
this.element.dispatchEvent(new CustomEvent('live:stalled', {
|
|
104
|
+
bubbles: true,
|
|
105
|
+
detail: { discarded },
|
|
106
|
+
}))
|
|
107
|
+
}
|
|
108
|
+
|
|
77
109
|
#callMessage(params, action) {
|
|
78
110
|
return {
|
|
79
111
|
_action: action,
|
|
@@ -115,10 +147,22 @@ export default class extends Controller {
|
|
|
115
147
|
return {
|
|
116
148
|
_action: '_reactive',
|
|
117
149
|
name: target.name,
|
|
118
|
-
value: target
|
|
150
|
+
value: this.#reactiveValue(target),
|
|
119
151
|
}
|
|
120
152
|
}
|
|
121
153
|
|
|
154
|
+
#reactiveValue(target) {
|
|
155
|
+
if (target.type === 'checkbox') {
|
|
156
|
+
return target.checked
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
if (target.type === 'select-multiple') {
|
|
160
|
+
return Array.from(target.selectedOptions, (option) => option.value)
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
return target.value
|
|
164
|
+
}
|
|
165
|
+
|
|
122
166
|
#form(action, { currentTarget, params }) {
|
|
123
167
|
const debounce = params.debounce
|
|
124
168
|
|
|
@@ -166,20 +210,17 @@ export default class extends Controller {
|
|
|
166
210
|
}
|
|
167
211
|
}
|
|
168
212
|
|
|
213
|
+
// Batch any pending debounced messages ahead of this one so they are sent
|
|
214
|
+
// in the order they were triggered
|
|
169
215
|
#flushDebounced(message) {
|
|
170
216
|
const messages = [message]
|
|
171
217
|
|
|
172
|
-
// Add all pending debounced messages to be sent immediately
|
|
173
218
|
for (const [source, { timeout, message: debouncedMessage }] of this.#debounces) {
|
|
174
219
|
clearTimeout(timeout)
|
|
175
220
|
messages.unshift(debouncedMessage)
|
|
176
221
|
}
|
|
177
222
|
this.#debounces.clear()
|
|
178
223
|
|
|
179
|
-
return { messages
|
|
180
|
-
}
|
|
181
|
-
|
|
182
|
-
get #csrfToken() {
|
|
183
|
-
return document.querySelector("meta[name='csrf-token']")?.getAttribute("content")
|
|
224
|
+
return { messages }
|
|
184
225
|
}
|
|
185
226
|
}
|
|
@@ -4,8 +4,10 @@ import DOM from '@isometriks/live_cable/dom'
|
|
|
4
4
|
|
|
5
5
|
const observer = new LiveObserver()
|
|
6
6
|
observer.start()
|
|
7
|
+
SubscriptionManager.syncIdentity()
|
|
7
8
|
|
|
8
9
|
document.addEventListener('turbo:before-render', (event) => {
|
|
10
|
+
SubscriptionManager.syncIdentity()
|
|
9
11
|
SubscriptionManager.prune(event.detail.newBody)
|
|
10
12
|
})
|
|
11
13
|
|
|
@@ -12,12 +12,26 @@
|
|
|
12
12
|
* message is in flight. If the attribute has a value, the element's label
|
|
13
13
|
* (textContent, or value for inputs) is swapped for it.
|
|
14
14
|
*
|
|
15
|
-
* The state is cleared when the server
|
|
16
|
-
* or an ack (sent when
|
|
17
|
-
* Multiple in-flight messages are counted; the DOM is
|
|
18
|
-
* all of them have been answered.
|
|
15
|
+
* The state is cleared when the server replies with the component's own
|
|
16
|
+
* re-render, an error, or an ack (sent when the action didn't re-render the
|
|
17
|
+
* component by itself). Multiple in-flight messages are counted; the DOM is
|
|
18
|
+
* only restored once all of them have been answered.
|
|
19
|
+
*
|
|
20
|
+
* If no reply comes for `LoadingState.timeout` milliseconds while a message
|
|
21
|
+
* is in flight, the state gives up: it resets and calls `onStalled`. That is
|
|
22
|
+
* the backstop for a reply that is never coming - the server stopped while
|
|
23
|
+
* running the message, say - which would otherwise leave a button disabled
|
|
24
|
+
* until the page is reloaded.
|
|
19
25
|
*/
|
|
20
26
|
export default class LoadingState {
|
|
27
|
+
/**
|
|
28
|
+
* Milliseconds to wait for any reply before giving up. Long enough to
|
|
29
|
+
* cover a reconnect after a deploy, since messages held for one count too.
|
|
30
|
+
* Set it before components connect to change it everywhere.
|
|
31
|
+
* @type {number}
|
|
32
|
+
*/
|
|
33
|
+
static timeout = 30_000
|
|
34
|
+
|
|
21
35
|
/** @type {HTMLElement} */
|
|
22
36
|
#root
|
|
23
37
|
/** @type {number} */
|
|
@@ -26,12 +40,20 @@ export default class LoadingState {
|
|
|
26
40
|
#markedElements = new Set()
|
|
27
41
|
/** @type {Map<Element, Object>} - Original state of disabled elements */
|
|
28
42
|
#disabledElements = new Map()
|
|
43
|
+
/** @type {Function|null} */
|
|
44
|
+
#onStalled
|
|
45
|
+
/** @type {number|null} */
|
|
46
|
+
#timer = null
|
|
29
47
|
|
|
30
48
|
/**
|
|
31
49
|
* @param {HTMLElement} root - The component's root element
|
|
50
|
+
* @param {Object} options
|
|
51
|
+
* @param {Function} [options.onStalled] - Called after the state gives up
|
|
52
|
+
* waiting and resets itself
|
|
32
53
|
*/
|
|
33
|
-
constructor(root) {
|
|
54
|
+
constructor(root, { onStalled = null } = {}) {
|
|
34
55
|
this.#root = root
|
|
56
|
+
this.#onStalled = onStalled
|
|
35
57
|
}
|
|
36
58
|
|
|
37
59
|
/**
|
|
@@ -42,6 +64,14 @@ export default class LoadingState {
|
|
|
42
64
|
return this.#inFlight > 0
|
|
43
65
|
}
|
|
44
66
|
|
|
67
|
+
/**
|
|
68
|
+
* How many messages are awaiting a server response.
|
|
69
|
+
* @returns {number}
|
|
70
|
+
*/
|
|
71
|
+
get inFlight() {
|
|
72
|
+
return this.#inFlight
|
|
73
|
+
}
|
|
74
|
+
|
|
45
75
|
/**
|
|
46
76
|
* Mark the component as loading.
|
|
47
77
|
* Called right before a message is sent to the server.
|
|
@@ -52,7 +82,9 @@ export default class LoadingState {
|
|
|
52
82
|
* elements. Disabled for reactive inputs so typing doesn't lose focus.
|
|
53
83
|
*/
|
|
54
84
|
start(trigger = null, { disable = true } = {}) {
|
|
55
|
-
this.#inFlight++
|
|
85
|
+
if (this.#inFlight++ === 0) {
|
|
86
|
+
this.#arm()
|
|
87
|
+
}
|
|
56
88
|
|
|
57
89
|
this.#mark(this.#root)
|
|
58
90
|
|
|
@@ -79,9 +111,12 @@ export default class LoadingState {
|
|
|
79
111
|
this.#inFlight--
|
|
80
112
|
|
|
81
113
|
if (this.#inFlight > 0) {
|
|
114
|
+
// Still waiting on others, but the server is evidently answering
|
|
115
|
+
this.#arm()
|
|
82
116
|
return false
|
|
83
117
|
}
|
|
84
118
|
|
|
119
|
+
this.#disarm()
|
|
85
120
|
this.#restore()
|
|
86
121
|
return true
|
|
87
122
|
}
|
|
@@ -92,9 +127,26 @@ export default class LoadingState {
|
|
|
92
127
|
*/
|
|
93
128
|
reset() {
|
|
94
129
|
this.#inFlight = 0
|
|
130
|
+
this.#disarm()
|
|
95
131
|
this.#restore()
|
|
96
132
|
}
|
|
97
133
|
|
|
134
|
+
#arm() {
|
|
135
|
+
this.#disarm()
|
|
136
|
+
this.#timer = setTimeout(() => this.#stall(), LoadingState.timeout)
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
#disarm() {
|
|
140
|
+
clearTimeout(this.#timer)
|
|
141
|
+
this.#timer = null
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
#stall() {
|
|
145
|
+
this.#timer = null
|
|
146
|
+
this.reset()
|
|
147
|
+
this.#onStalled?.()
|
|
148
|
+
}
|
|
149
|
+
|
|
98
150
|
#mark(element) {
|
|
99
151
|
element.setAttribute('live-loading', '')
|
|
100
152
|
this.#markedElements.add(element)
|