@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/README.md CHANGED
@@ -30,21 +30,19 @@ bundle install
30
30
 
31
31
  ## Configuration
32
32
 
33
- To use LiveCable, you need to set up your `ApplicationCable::Connection` to initialize a `LiveCable::Connection`.
34
-
35
- Add this to your `app/channels/application_cable/connection.rb`:
36
-
37
- ```ruby
38
- module ApplicationCable
39
- class Connection < ActionCable::Connection::Base
40
- identified_by :live_connection
41
-
42
- def connect
43
- self.live_connection = LiveCable::Connection.new(self.request)
44
- end
45
- end
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 [ARCHITECTURE.md](ARCHITECTURE.md).
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
- defaults: Object,
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
- // (refresh, ack, or error). Restores any live-loading / live-disable-with
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.value,
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, _csrf_token: this.#csrfToken }
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 responds with a refresh, an error,
16
- * or an ack (sent when an action didn't change any reactive variables).
17
- * Multiple in-flight messages are counted; the DOM is only restored once
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)