@isometriks/live_cable 0.4.0 → 0.5.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 CHANGED
@@ -6,7 +6,7 @@ The Ruby gem (`live_cable`) and the npm package (`@isometriks/live_cable`) are
6
6
  released together and share a single version number. Entries below note which
7
7
  side of the pair a change affects when it isn't both.
8
8
 
9
- ## Unreleased
9
+ ## 0.5.0 - 2026-11-19
10
10
 
11
11
  ### Upgrading from 0.4
12
12
 
@@ -14,84 +14,156 @@ The gem and the npm package work with each other at 0.4 in either
14
14
  direction, but upgrade both to get every fix. A few fixes change behaviour an
15
15
  application could notice:
16
16
 
17
+ - LiveCable now needs Rails 8.0 or later, and the gemspec says so. On Rails
18
+ 7.1 and 7.2, every action that takes params already failed on 0.4.
17
19
  - A template that reads a local assigned inside an earlier block, with no
18
- component method or view helper of that name, now raises `NoMethodError`
20
+ component method or view helper of that name, now raises `NameError`
19
21
  instead of rendering nothing.
22
+ - An `<%= %>` tag, or an `if`/`case`/loop group, that assigns a top-level
23
+ local that a later tag reads before assigning it itself (a second
24
+ `for item in …` loop doesn't) now runs and is re-sent on every update, and
25
+ so is every tag that reads it. Prefer a component method for anything
26
+ costly.
20
27
  - A component method named like a Kernel method (`open`, `test`, `select`, …)
21
28
  now wins over Kernel in its template; call it on `Kernel`, as in
22
- `Kernel.rand`, to reach Kernel's. Don't name a component method `format`:
23
- ActionView reads it as the template's format.
24
- - A tag that reassigns a local set by an earlier top-level `<% %>` tag now
25
- re-runs on every update, so later tags see the right value. Keep expensive
26
- work out of such tags.
27
- - A loading state now ends only on the component's own reply. A message held
28
- while the socket was down stays loading until it is answered.
29
- - A focused text field keeps what the user typed through renders it didn't
30
- ask for. To clear a field after a submit, bind it to a reactive variable and
31
- reset that in the action.
29
+ `Kernel.rand`, to reach Kernel's.
30
+ - A loading state now ends only on the component's own reply, and a nested
31
+ component's pending elements wait for it through its parent's renders. A
32
+ message held while the socket was down stays loading until it is answered.
33
+ The events an action dispatches without sending a render of its own arrive
34
+ on its `_ack`, where they used to come in a frame of their own before it.
35
+ Frames captured by `LiveCable::Testing` carry `_reply`, and subscribe frames
36
+ `_subscribed`, so a spec that compares whole frames needs those keys. An
37
+ `_ack` for a component whose new render went out inside its parent's
38
+ carries `_rendered: true`.
39
+ - A focused field keeps what the user typed through renders it didn't ask for,
40
+ and through a reply that only echoes the value its own `live-reactive`
41
+ update sent. To clear a field after a submit, bind it to a reactive variable
42
+ and reset that in the action.
32
43
  - `live_mount(..., raise_errors: false)` no longer raises when the first
33
- render fails; assert on `broadcasts(:_error)` instead.
44
+ render or a `connect` callback fails; assert on `broadcasts(:_error)`
45
+ instead.
46
+ - In component code, changing an element held in two reactive collections
47
+ now marks the one you changed it through, not the one it was first read
48
+ from. Call `dirty(...)` for the other if the page shows it there too.
34
49
  - A template now gets the plain Array, Hash or model inside a reactive
35
- variable, so Rails helpers and `case` see the real value. A template that
36
- changes a reactive value in place no longer marks it dirty; change it in the
50
+ variable, and inside what a component method returns, so Rails helpers and
51
+ `case` see the real value. An Array or Hash a template changes in place, or
52
+ a model inside one, no longer marks its variable dirty; change it in the
37
53
  component. `component.x` in a template still returns the tracked wrapper.
38
- - In component code, values reached through `fetch`, `dig`, `detect`,
39
- `Hash#each` and `each_value` are tracked wrappers now, so writes through
40
- them mark the variable dirty. Use `to_a`, `to_h` or `__getobj__` where code
41
- needs the real Array or Hash.
42
- - A model held in a reactive variable is watched on the record itself. A
43
- write through any reference to it, a `reload`, or a validation that
44
- normalises an attribute now marks the variable dirty and re-renders.
45
- - An error raised by an initial-value lambda goes through normal error
46
- handling instead of storing `nil`: a root's subscribe answers with an
47
- `_error`, and a failing child replaces its parent with the error box. An
48
- initial value that isn't a proc raises `ArgumentError` when the class loads.
49
- - Defaults are signed in their `as_json` form, and a prerendered root
50
- renders with that form too, so a Symbol default is a String on page load as
51
- well as after subscribe. In development and test, a default that changes on
52
- the way logs a warning.
53
- - A child its parent renders now runs its render callbacks on each of those
54
- renders. On page load they run before its connect callbacks, without
55
- connection identifiers such as `current_user`.
54
+ - In component code, values reached through `fetch`, `dig`, `detect`, `at`,
55
+ `min`/`max`, `min_by`/`max_by`, `sample`, `reverse_each`, a Hash's `find`
56
+ and the `each_*` iterators such as `each_slice` and `each_cons` (including
57
+ `Hash#each` and `each_value`) are tracked wrappers now, and a Hash's
58
+ `values`, `values_at` and `fetch_values` return a wrapper when they hold
59
+ nested Arrays, Hashes or models. Writes through them mark the variable
60
+ dirty. Use `to_a`, `to_h` or `LiveCable::Delegator.unwrap(value)` where
61
+ code needs the real value.
62
+ - A model stored directly in a reactive variable is watched on the record
63
+ itself, so a write through any reference to it, a `reload` that brings in
64
+ a change, or a validation that normalises an attribute marks the variable
65
+ dirty and re-renders. A model in a reactive Array or Hash re-renders on
66
+ any write made through the collection (`todos.first.title = x`,
67
+ `toggle!`, `reload`), not only `update`.
56
68
  - When a component re-renders, parts that read a non-reactive `shared`
57
- variable render again too.
69
+ variable render again and are sent too, whether or not it changed.
70
+ - Defaults are signed in their `as_json` form, and a prerendered root renders
71
+ with that form too, so a Symbol default is a String, and a nested Hash has
72
+ String keys, on page load as well as after subscribe. In development and
73
+ test, a default that changes on the way logs a warning.
74
+ - A top-level component's default that is or holds anything other than
75
+ strings, symbols, numbers, booleans, `nil`, times, dates and permitted
76
+ params, in Arrays and Hashes, now raises `ArgumentError` on page load, in
77
+ production too. That covers an ActiveRecord record or relation, params that
78
+ aren't permitted, and a `Struct`, `Set`, presenter or form object, whether
79
+ or not it holds a record. On 0.4 the page loaded and
80
+ the component got the object's `to_s` or `inspect` string, such as
81
+ `"#<User:0x…>"`, once connected. Pass an id and load the record in the
82
+ component.
83
+ - An error raised by an initial-value lambda goes through the error handling
84
+ of the subscribe or render that first reads it instead of storing `nil`: a
85
+ root's subscribe answers with an `_error`, and a failing child replaces its
86
+ parent with the error box. An initial value other than a proc or `nil`
87
+ raises `ArgumentError` when the class loads.
88
+ - A child its parent renders now runs its render callbacks on each of those
89
+ renders. The first time a parent renders it, on page load or when an action
90
+ first shows it, they run before its connect callbacks, without connection
91
+ identifiers such as `current_user`; pass such values from the parent. A
92
+ `before_render` that throws `:abort` on that first render leaves the child
93
+ out of the page until the parent renders it again and the callback lets it
94
+ through.
58
95
  - A checkbox with `live-reactive` sends `true` or `false`, and a `<select
59
96
  multiple>` sends an Array of values, instead of the element's `value`.
60
- - A render that changes nothing on the page is no longer sent. An action
61
- whose changes no part of the template shows is answered with an `_ack`, so
62
- a test expecting a `_refresh` after one should expect `broadcasts(:_ack)`.
63
- - Renders over the socket now share one controller per connection. A
64
- `helper_method` on `ApplicationController` that memoizes into an instance
65
- variable keeps its value for the connection rather than for one render.
66
- These renders have no session or params, so this only matters for a value
67
- that changes over time.
97
+ - A render in which no part re-renders is no longer sent. An action whose
98
+ changes no part of the template reads is answered with an `_ack`, so a test
99
+ expecting a `_refresh` after one should expect `broadcasts(:_ack)`. Such an
100
+ action also no longer resets its form: a field the server doesn't track
101
+ keeps what was typed. To clear it, bind it to a reactive variable and reset
102
+ that in the action. A part that reads a non-reactive `shared` variable or a
103
+ local an earlier tag assigns re-renders whenever its component does, so a
104
+ template with one still answers with a `_refresh`.
105
+ - A relative key such as `t('.title')` in a `.live.erb` template now looks
106
+ up the template's own scope on page load, `live.counter.title` for
107
+ `app/views/live/counter.html.live.erb`, instead of the page's, such as
108
+ `home.index.title`. Move any such translations under the component's key.
109
+
110
+ ### Security
111
+
112
+ - **A child component's id could inject markup that ran in the browser.**
113
+ Over the socket a parent sends each child it renders inline as a
114
+ `<LiveCable child-live-id="...">` placeholder, and the child's id went into
115
+ that attribute unescaped. An id built from user input, such as
116
+ `live('tag', id: tag.name)`, could close the attribute and add an element
117
+ with an event handler, which ran when the client put the parent's render on
118
+ the page. An id with a plain quote broke the placeholder, so that child
119
+ never rendered. The id is now escaped in the placeholder, and the client
120
+ and the test harness read it back decoded.
68
121
 
69
122
  ### Fixed
70
123
 
71
- - **A template local could render blank or stale.** Dependency
72
- tracking parsed each part of a `.live.erb` template on its own and ignored
73
- Ruby's block scopes. A local assigned inside a block leaked into later
74
- parts, so a later `<%= css %>` rendered blank instead of calling the
75
- component's `css`; a top-level local updated inside a block, as in
124
+ - **An inline child whose root element has an id broke on its first
125
+ action after the page loaded.** The client threw `TypeError:
126
+ rootNode.querySelectorAll is not a function` and the child didn't update.
127
+ The parent's first render over the socket brings the child's template, and
128
+ the client stored it with the element that render built. But the morph
129
+ kept the page's own element, because its id matched, so when the child's
130
+ controller connected on that element its subscription started empty. The
131
+ server only confirmed the subscription, since it had already sent the
132
+ template, and the child's first update arrived as a delta with nothing to
133
+ apply it to. A subscription now takes the state its parent's render left
134
+ for it, whichever element the controller connected on (npm).
135
+ - **A template local could render blank or stale.** Dependency tracking
136
+ parsed each part of a `.live.erb` template on its own and ignored Ruby's
137
+ block scopes. A local assigned inside a block leaked into later parts, so a
138
+ later `<%= css %>` rendered blank instead of calling the component's `css`;
139
+ a top-level local updated inside a block, as in
76
140
  `<% counts.each { |c| total += c } %>`, kept its earlier value in later
77
- parts; and a local reassigned in an `if` that didn't run became `nil`.
141
+ parts; a local reassigned in an `if` that didn't run became `nil`; and a
142
+ tag that read a local by hash shorthand (`total:`), or one set by multiple
143
+ assignment, pattern matching or a named regex capture, never re-rendered.
78
144
  Block parameters also counted as dependencies, so a part re-rendered
79
- whenever a reactive variable of the same name changed. Each part is now
80
- parsed with the earlier parts' locals in scope, so names resolve as they
81
- would in a plain ERB template. Two templates behave differently: one that
82
- reads a block's local after the block, with no component method or view
83
- helper of that name, now raises `NoMethodError` ("undefined method 'last'"
84
- for a local named `last`) instead of rendering nothing, much as plain ERB
85
- raises `NameError`; and a local reassigned in a branch that doesn't run
86
- keeps its value instead of becoming `nil` (gem).
145
+ whenever a reactive variable of the same name changed. And only a lone
146
+ `<% %>` tag always ran, so a local first assigned inside an `if`, `case` or
147
+ `for`, or in an `<%= %>` tag, was `nil` in a later part that re-rendered
148
+ while that tag was skipped. Each part is now parsed with the earlier parts'
149
+ locals in scope, so names resolve as they would in a plain ERB template,
150
+ and a part that assigns a top-level local a later tag reads always runs. Two
151
+ templates behave differently: one that reads a block's local after the
152
+ block, with no component method or view helper of that name, now raises
153
+ `NameError`, as plain ERB does, instead of rendering nothing; and a local
154
+ reassigned in a branch that doesn't run keeps its value instead of becoming
155
+ `nil` (gem).
87
156
  - **A block passed to a view helper that renders a partial landed above the
88
- partial.** A helper such as `def card(&) = render(layout: 'shared/card', &)`,
89
- used from a `.live.erb` template as `<%= card do %>`, wrote the block's
90
- content before the card and left stray escaped markup where the card
91
- yields. 0.4.0 fixed this for `render` called by the template itself; a
92
- block the template passes to any view helper is now handled the same way.
93
- Helpers that capture their block, such as `form_with` and `content_tag`,
94
- are unaffected (gem).
157
+ partial.** A helper such as
158
+ `def card(&) = render(layout: 'shared/card', &)`, used from a `.live.erb`
159
+ template as `<%= card do %>`, wrote the block's content before the card and
160
+ left stray escaped markup where the card yields. A presenter or any other
161
+ object that renders a partial with the template's block did the same.
162
+ 0.4.0 fixed this only for `render` called by the template itself. A block
163
+ in a `.live.erb` template now writes wherever the view is writing when it
164
+ runs, as in plain ERB, so it lands where the partial yields. Helpers that
165
+ capture their block, such as `form_with` and `content_tag`, work as before
166
+ (gem).
95
167
  - **The error for a `.live.erb` template rendered as a partial didn't say
96
168
  which template.** The message began "A .live.erb template", and the
97
169
  backtrace points into LiveCable rather than at the template. It now opens
@@ -103,12 +175,16 @@ application could notice:
103
175
  then the view context, but names the renderer already had from Kernel or
104
176
  Object never got that far. A component with `reactive :open` and
105
177
  `<% if open %>` raised an `ArgumentError` on the page and on mount, the
106
- `select` form helper raised a `TypeError`, and `j` printed to standard output
107
- instead of escaping. These names now go to the component or the view context
108
- whenever either defines them. When neither does they still call the Kernel
109
- method, so `format`, `rand` and `lambda` work as before. A component method
110
- with such a name now wins in its template; call it on `Kernel`, as in
111
- `Kernel.rand`, to reach the Kernel method (gem).
178
+ `select` form helper raised a `TypeError`, and `j` printed to standard
179
+ output instead of escaping. These names now go to the component or the view
180
+ context whenever either defines them. When neither does they still call the
181
+ Kernel method, so `format`, `rand` and `lambda` work as before. A component
182
+ method with such a name now wins in its template; call it on `Kernel`, as
183
+ in `Kernel.rand`, to reach the Kernel method. Names the renderer used for
184
+ its own state hid the component's in the same way: with `reactive :parts`,
185
+ `<%= parts %>` printed the compiled template, and with `reactive :changes`,
186
+ `changes` returned the variables being re-rendered. Those now reach the
187
+ component too (gem).
112
188
  - **A child hidden after its parent re-rendered something else was never
113
189
  destroyed.** A parent only remembered the inline children of the parts its
114
190
  last render had run, so after a render that skipped a child's part it no
@@ -137,49 +213,65 @@ application could notice:
137
213
  on every `_refresh`, including renders it never asked for - a `stream_from`
138
214
  callback's, or one caused by another component's action - and a parent's
139
215
  re-render rebuilt a nested component's pending button, so someone else's
140
- chat message could re-enable your Send button and invite a double submit.
141
- A nested component re-rendered only inside its parent's render got no reply
142
- at all, and stalled after 30 seconds. The server now
143
- marks the render that answers a message with `_reply`, or sends an `_ack`
144
- when the component sent no render of its own, and the client ends a loading
145
- state only on a reply, an `_ack` or an `_error`; pending elements keep their
146
- state through other renders and catch up when it comes. Frames captured by
147
- `LiveCable::Testing` carry the new `_reply` and `_subscribed` keys. A message
148
- held while the socket was down now stays loading until its own reply, and
149
- one lost with the socket stops when it closes or the component
150
- re-subscribes. Either side works with the other at 0.4.0 (gem + npm).
151
- - **Typing in a focused field was undone by a render the user didn't ask
152
- for.** Every refresh is morphed in from HTML rebuilt from the component's
153
- stored parts, which set each field back to the last value the server
154
- rendered. In a chat with a debounced `live-reactive` draft, each incoming
155
- `stream_from` message, or a render caused by another component, dropped
156
- what had been typed since the last send, and the debounced send that
157
- followed sent what was left. A focused text field or textarea now keeps
158
- what has been typed unless the server changed its value. A re-render that
159
- answers the field's own form or action still applies the server's value,
160
- so an input cleared after a submit is still cleared. Unfocused fields,
161
- checkboxes, radios and selects behave as before. A focused field that
162
- isn't bound to a reactive variable is no longer cleared by a render it
163
- didn't ask for; to clear it after a submit, bind it and reset the variable
164
- in the action (npm).
165
- - **A Turbo Drive visit removed the inline children of a component that
166
- stayed on the page.** Before Turbo renders a new page, LiveCable closes the
167
- subscription of every component that isn't on it. The HTTP prerender gives
168
- a live id only to the root component, so a child rendered inline by its
169
- parent looked like it was leaving, even when the parent (a layout
170
- component, say) was staying. The child was torn down on the server, and the
171
- parent had nothing to rebuild it from, so it disappeared from the page. A
172
- component that stays on the page now also keeps the children it renders
173
- with `.live.erb` templates, and theirs, with their subscriptions and live
216
+ chat message could re-enable your Send button and invite a double submit. A
217
+ nested component re-rendered only inside its parent's render got no reply at
218
+ all, and stalled after 30 seconds. The server now marks the render that
219
+ answers a message with `_reply`, or sends an `_ack` when the component sent
220
+ no render of its own, marked `_rendered` when its new render went out inside
221
+ its parent's. The client ends a loading state only on a reply, an `_ack` or
222
+ an `_error`. A render an action pushes with `broadcast_render` before it
223
+ returns isn't the reply. An `_ack` carries the events its message
224
+ dispatched, so their handlers run once the loading state has ended and the
225
+ component has caught up. Pending elements, and the `live-loading` on a
226
+ nested component's root, keep their state through other renders, even a
227
+ parent's render that carries the nested component's own, and catch up when
228
+ the loading state ends, whether by the answer, the socket closing, a
229
+ re-subscribe, a stall or a parent's render that moves the nested component,
230
+ as reordering a list does. An `_ack` now also turns a `stalled` status back
231
+ to `subscribed`, as a `_refresh` did. Frames captured by
232
+ `LiveCable::Testing` carry the new `_reply`, `_subscribed` and `_rendered`
233
+ keys. A message held while the socket was down now stays loading until its
234
+ own reply, and one lost with the socket stops when it closes or the
235
+ component re-subscribes.
236
+ Either side works with the other at 0.4.0.
237
+ - **Typing in a focused field was undone by renders that arrived while the
238
+ user typed.** Every refresh is morphed in from HTML rebuilt from the
239
+ component's stored parts, which set each field back to the last value the
240
+ server rendered. In a chat with a debounced `live-reactive` draft, an
241
+ incoming `stream_from` message, a render caused by another component, or the
242
+ reply to the draft's own last update dropped what had been typed since that
243
+ update, and the debounced send that followed sent what was left. A focused
244
+ field - a textarea, or any input a user types into or sets with a picker or
245
+ slider, such as text, number, date or range - now keeps what has been
246
+ entered unless the server changed its value. A re-render that answers the
247
+ field's own form or action still applies the server's value, so an input
248
+ cleared after a submit is still cleared, but a reply that only echoes the
249
+ value the field's own `live-reactive` update sent keeps what has been typed
250
+ since. Unfocused fields, checkboxes, radios and selects behave as before. A
251
+ focused field that isn't bound to a reactive variable is no longer cleared
252
+ by a render it didn't ask for; to clear it after a submit, bind it and reset
253
+ the variable in the action (npm).
254
+ - **A Turbo Drive visit removed the inline children of a component that stayed
255
+ on the page.** Before Turbo renders a new page, LiveCable closes the
256
+ subscription of every component that isn't on it. The HTTP prerender gives a
257
+ live id only to the root component, so a child rendered inline by its parent
258
+ looked like it was leaving, even when the parent (a layout component, say)
259
+ was staying. The child was torn down on the server, and the parent had
260
+ nothing to rebuild it from, so it disappeared from the page. A component
261
+ that stays on the page with the same defaults now also keeps the children it
262
+ renders with `.live.erb` templates, and theirs, with their subscriptions and
263
+ live state. One the new page renders with different defaults is still built
264
+ again from them, and its children with it, unless it is in a
265
+ `data-turbo-permanent` element that Turbo carries over: Turbo keeps the
266
+ element already on the page, so the component and its children keep their
174
267
  state (npm).
175
268
  - **`live_mount(..., raise_errors: false)` still raised when the first render
176
- or a `connect` callback failed.**
177
- `live_mount` ran `connect` and the first render with no rescue, so an error
178
- in either still raised, while production sends it through the connection's
179
- error handling and transmits an `_error`. `live_mount` now handles those
180
- errors the same way `LiveChannel#subscribed` does. With `raise_errors: false`
181
- it returns the component with the `_error` in its broadcasts, so a spec that
182
- expected `live_mount(..., raise_errors: false)` to raise now needs to assert
269
+ or a `connect` callback failed.** `live_mount` ran `connect` and the first
270
+ render with no rescue, so an error in either still raised, while production
271
+ sends it through the connection's error handling and transmits an `_error`.
272
+ `live_mount` now handles those errors the same way `LiveChannel#subscribed`
273
+ does. With `raise_errors: false` it returns the component with the `_error`
274
+ in its broadcasts, so a spec that expected it to raise now needs to assert
183
275
  on `broadcasts(:_error)` instead. The default, `raise_errors: true`, still
184
276
  raises (gem).
185
277
  - **`component.x` and `self.x` in a template didn't re-render when `x`
@@ -188,10 +280,11 @@ application could notice:
188
280
  `theme` changed and kept showing the old value. `self.x` also ran Kernel's
189
281
  method of that name when there was one, so `self.open` raised. Both forms
190
282
  now count as reads of the component (gem).
191
- - **A helper called with arguments rendered a template local of the same
192
- name instead.** After `<% t = Time.current %>`, a later `<%= t('.title') %>`
193
- printed the time: a call with arguments still found the stored local before
194
- the helper. A local now only answers a bare name, as in plain ERB (gem).
283
+ - **A call to a helper or component method rendered a template local of the
284
+ same name instead.** After `<% t = Time.current %>`, a later
285
+ `<%= t('.title') %>` printed the time, and after `<% count = 99 %>`,
286
+ `count()` and `self.count` printed 99 instead of calling the component's
287
+ `count`. A local is now read only by its bare name, as in plain ERB (gem).
195
288
  - **`items.each.with_index` raised `LocalJumpError` on reactive arrays.** A
196
289
  reactive array's `each` always yielded, so calling `each` without a block
197
290
  failed, and so did `each.with_index`, `each.with_object` and `each.lazy`. In
@@ -199,21 +292,6 @@ application could notice:
199
292
  but every socket render failed and the component never went live. `each`
200
293
  without a block now returns an enumerator, and elements yielded through it
201
294
  are tracked like those from `each` with a block (gem).
202
- - **Some common ways of changing a reactive Array or Hash didn't re-render.**
203
- Change tracking only knew the method names it listed, so aliases and
204
- ActiveSupport bang methods went straight through untracked. That covered
205
- `append`, `prepend`, `filter!`, `collect!`, `compact_blank!` and `extract!`,
206
- and on hashes `store`, `replace`, `slice!`, `with_defaults!`,
207
- `deep_symbolize_keys!` and others. Nested values read through `detect`,
208
- `fetch`, `dig`, `at`, `min_by`, `each_with_index`, `each_with_object`,
209
- `reverse_each`, `each_slice`, `values`, `each_value` or `Hash#each` came
210
- back untracked. So `todos.detect { ... }[:done] = true` answered with an
211
- `_ack` and left the page stale. All of these are now tracked, and a spec
212
- fails if a mutating method is missed. Values yielded by these methods are
213
- now tracked wrappers, like the ones `each` already yielded, so `is_a?(Hash)`
214
- on them is false. The blocks of `map`/`select` and the results of
215
- `to_a`/`to_h` are still untracked; see *Nested Structures* in the reactive
216
- variables guide (gem).
217
295
  - **`self.tags = tags.dup` stopped all later change tracking for `tags`.**
218
296
  `dup` dropped the wrapper's tracking modules, so the assignment rendered
219
297
  once and every later `tags << x` or nested change went unnoticed. A
@@ -227,11 +305,65 @@ application could notice:
227
305
  the element with `live(...)`, so the `done` part never re-rendered. Reactive
228
306
  collections now store the plain element rather than the tracked wrapper it
229
307
  was read through, and an element read back is tracked through the collection
230
- it was read from. An Array or Hash you pass in is copied only when it holds
231
- such a wrapper (gem).
308
+ it was read from. In component code, an element kept in both collections is
309
+ tracked through the one it is changed through, so a change through `done` no
310
+ longer marks `todos`; call `dirty(:todos)` if both show it. An element read
311
+ from a reactive collection and passed back to one of its mutators, as in
312
+ `todos.delete(todos.find { ... })` on a list of models, is now found. An
313
+ Array or Hash you pass in is copied only when it holds such a wrapper
314
+ (gem).
315
+ - **After connecting, reactive Arrays and Hashes rendered wrongly in Rails tag
316
+ helpers, and `where(id: reactive_array)` matched nothing.** A tracked value
317
+ isn't an `Array` or `Hash` to `case` or `===`. On socket renders,
318
+ `tag.span(class: classes)` printed `class="[&quot;btn&quot;,
319
+ &quot;primary&quot;]"` where the prerender printed `class="btn primary"`,
320
+ and `where(id: ids)` compiled to `id = NULL`. Templates now see the plain
321
+ value, also inside an Array or Hash a component method builds from reactive
322
+ values (`[todos.first, todos.last]`), so helpers and `case` behave as in any
323
+ Rails view, and `where(column: value)`, `where(association: records)`,
324
+ `in_order_of` and Arel's `in` and `not_in` accept reactive values instead of
325
+ matching nothing. A child given one of these with `live(...)` still shares
326
+ its change tracking, so the parent re-renders when the child changes it.
327
+ That covers a reactive value, an element of one, and a collection built from
328
+ one in the template or a component method. A child first rendered while two
329
+ reactive collections hold an element marks both. An Array or Hash changed in
330
+ place in a template, or a model inside one, no longer marks its variable
331
+ dirty. A variable's first read now returns the tracked value like later
332
+ reads, so changes made through it are tracked. `find`, `destroy` and
333
+ `update` given a reactive list of ids act on every id instead of one.
334
+ Component code sees plain values during the HTTP prerender and wrappers once
335
+ connected, so for `case`, `where(hash)` and association assignment it needs
336
+ `to_a`, `to_h` or `LiveCable::Delegator.unwrap(value)`, which work in both
337
+ (gem).
338
+ - **Some common ways of changing a reactive Array or Hash didn't re-render.**
339
+ Change tracking only knew the method names it listed, so aliases and
340
+ ActiveSupport bang methods went straight through untracked. That covered
341
+ `append`, `prepend`, `filter!`, `collect!`, `compact_blank!` and `extract!`,
342
+ and on hashes `store`, `replace`, `slice!`, `with_defaults!`,
343
+ `deep_symbolize_keys!` and others. Nested values read through `detect`,
344
+ `fetch`, `dig`, `at`, `min_by`, `each_with_index`, `each_with_object`,
345
+ `reverse_each`, `each_slice`, `values`, `each_value` or `Hash#each` came
346
+ back untracked. So `todos.detect { ... }[:done] = true` answered with an
347
+ `_ack` and left the page stale. All of these are now tracked, and a spec
348
+ fails if a bang method, or an alias of a tracked one, is left out. Values
349
+ these methods return or yield are now tracked wrappers, like the ones
350
+ `each` already yielded, so in component code `is_a?(Hash)` on them is
351
+ false. The elements passed to the blocks of `map`/`select`, the results of
352
+ methods that don't wrap what they return (a Hash's `select` or `slice`, an
353
+ Array's `second` or `partition`) and `to_a`/`to_h` are still untracked; see
354
+ *Nested Structures* in the reactive variables guide (gem).
355
+ - **`where(commentable: record)` with a reactive record dropped the
356
+ `commentable_type` condition and returned other models' rows.** ActiveRecord
357
+ finds a polymorphic association's type with `is_a?(ActiveRecord::Base)`,
358
+ which the wrapper answers false, so the query became
359
+ `WHERE commentable_id = 1` and matched rows of every model with that id;
360
+ `where.not` hid them instead. A plain Array holding reactive records, as in
361
+ `where(id: [first, last])`, matched nothing. The predicate builder now
362
+ unwraps reactive values, including those inside an Array, before
363
+ ActiveRecord expands the hash (gem).
232
364
  - **ActiveRecord models read from a reactive variable never compared equal.**
233
365
  Two reads of the same record, or a raw record and a wrapped one, compared
234
- unequal. So `todos.delete(todos.find { ... })` left the record in the list,
366
+ unequal. So `list.delete(found)` on a plain Array left the record in it,
235
367
  `include?`, `index` and `todos - [found]` missed it, and `t == selected` in
236
368
  a template never matched. Equality now compares the records themselves.
237
369
  Unsaved records still compare unequal, as ActiveRecord intends (gem).
@@ -243,49 +375,42 @@ application could notice:
243
375
  `update_column(s)`, `reload` and saved in-place JSON changes, so the
244
376
  streaming guide's `document.reload` example never refreshed the page. All of
245
377
  these writes are now tracked, at any depth. A replaced record no longer
246
- keeps marking the variable it was removed from. `reload`, and validations
247
- that normalize attributes, now re-render even when nothing visible changed.
378
+ keeps marking the variable it was removed from. A `reload` re-renders only
379
+ when the record's columns changed, so reloading to check a record before
380
+ writing costs nothing; validations that normalize attributes re-render even
381
+ when nothing visible changed.
248
382
  Association changes and unsaved in-place edits still need `dirty(:name)`
249
383
  (gem).
250
- - **After connecting, reactive Arrays and Hashes rendered wrongly in Rails tag
251
- helpers, and `where(id: reactive_array)` matched nothing.** A tracked value
252
- isn't an `Array` or `Hash` to `case` or `===`. On socket renders,
253
- `tag.span(class: classes)` printed `class="[&quot;btn&quot;,
254
- &quot;primary&quot;]"` where the prerender printed `class="btn primary"`,
255
- and `where(id: ids)` compiled to `id = NULL`. Templates now see the plain
256
- value, so helpers and `case` behave as in any Rails view, and `where(column:
257
- value)` accepts reactive values. A child given one of these with `live(...)`
258
- still shares its change tracking, so the parent re-renders when the child
259
- changes it. That covers a reactive value, an element of one, and a
260
- collection built from one in the template, such as `todos.reject { ... }`. A
261
- template that mutates a reactive value no longer marks it dirty. A
262
- variable's first read now returns the tracked value like later reads, so
263
- changes made through it are tracked. In component code, `case`,
264
- `where(hash)` and association assignment still need `to_a`, `to_h` or
265
- `__getobj__` (gem).
384
+ - **Writes through the `clone` of a model in a reactive variable didn't
385
+ re-render.** ActiveRecord's `clone` shares the original's attributes, so
386
+ `todo.clone.title = 'b'` changed the stored record, but the copy dropped
387
+ the original's change tracking and the page kept the old title. A clone of
388
+ a tracked model, held directly or read from a reactive Array or Hash, now
389
+ marks the same variables; a `dup` is still a separate, untracked record
390
+ (gem).
266
391
  - **A part that passed a reactive variable with hash shorthand (`render
267
392
  'badge', page:`) or called it with empty parentheses (`count()`) never
268
393
  re-rendered.** The dependency analysis only recognised a bare `page`, so
269
- these forms (`tag.span(data: { page: })`, `items_path(page:)`, a shorthand
270
- of a template local set in an earlier part) were left out and the part kept
271
- its first-render HTML. Any receiverless call with no arguments and no block
272
- now counts as a read. (gem)
394
+ these forms (`tag.span(data: { page: })`, `items_path(page:)`) were left
395
+ out and the part kept its first-render HTML. Any receiverless call with no
396
+ arguments and no block now counts as a read (gem).
273
397
  - **A component method's dependencies were lost when another def in the same
274
398
  file had the same name.** The method analyzer parses the component's whole
275
- file and the last def with a given name won, so a `def self.title`, a `class
276
- << self` method, a method in a nested class or `Struct.new` block, or a
277
- method of a second class in the file could leave every part calling `title`
278
- stale. Same-named defs now merge their dependencies, and singleton methods
279
- are ignored. Affected parts may now re-render where they were previously
280
- skipped. (gem)
399
+ file and the last def with a given name won, so a `def self.title`, a
400
+ `class << self` method, a method in a nested class or `Struct.new` block, or
401
+ a method of a second class in the file could leave every part calling
402
+ `title` stale. Same-named defs now merge their dependencies, and singleton
403
+ methods are ignored. Affected parts may now re-render where they were
404
+ previously skipped (gem).
281
405
  - **Parts reading a non-reactive `shared` variable in a `.live.erb` template
282
406
  never re-rendered.** They kept their first-render value even when the
283
- component re-rendered for its own reasons or wrote the variable itself, so
284
- the guide's FilterPanel badge example showed a stale count. Whenever a
285
- component re-renders, parts that read its `shared` variables, directly or
286
- through a component method, now re-render too. A change to a `shared`
287
- variable on its own still does not trigger a render. These parts are now
288
- sent on every re-render of the component. (gem)
407
+ component re-rendered for its own reasons, including in an action that also
408
+ wrote the variable, so the guide's FilterPanel badge example showed a stale
409
+ count. Whenever a component re-renders, parts that read its `shared`
410
+ variables, directly or through a component method, now re-render too. A
411
+ change to a `shared` variable on its own still does not trigger a render of
412
+ the components that declare it with `shared`. These parts are now sent on
413
+ every re-render of the component (gem).
289
414
  - **The guide's `reactive :user, ->(c) { User.find(c.defaults[:user_id]) }`
290
415
  raised `NoMethodError`.** `Component#defaults` was private, and an initial
291
416
  lambda gets the component as an explicit receiver. So the prerender failed,
@@ -300,15 +425,17 @@ application could notice:
300
425
  `JSON.generate`, a `Time` came back as its `to_s` and a record as
301
426
  `"#<User:0x…>"`. LiveCable now signs each default's `as_json` form, as 0.3's
302
427
  unsigned attribute did, and prerenders a top-level component with that same
303
- form, so both renders agree. In development and test it logs a warning for
304
- any default that isn't JSON-native. **Never pass a record to a top-level
305
- component: its JSON form is every one of its attributes, readable in the
306
- page.** The defaults are signed, not encrypted. Pass an id and load the
307
- record in the component. A top-level component now gets the JSON form on the
308
- HTTP prerender too. So `status: :open` is now `"open"` there, and
309
- `user.name` on a passed record now raises on page load (a 500 in production)
310
- instead of after connect. Children rendered by a parent and `live_mount`
311
- defaults are unchanged (gem).
428
+ form, so both renders agree: `status: :open` is now `"open"` on page load
429
+ too. The defaults are signed, not encrypted, and a record's JSON form is
430
+ every one of its attributes, and a plain object's is its instance variables,
431
+ so a top-level component given anything other than strings, symbols,
432
+ numbers, booleans, `nil`, times, dates and permitted params (which arrive as
433
+ a Hash), in Arrays and Hashes, now raises `ArgumentError` on page load in
434
+ every environment. That covers a record or
435
+ relation, and a `Struct`, `Set` or presenter holding one. Pass its id and
436
+ load the record in the component. In development and test, a Symbol, Time or
437
+ other default that comes back changed logs a warning. Children rendered by a
438
+ parent and `live_mount` defaults are unchanged (gem).
312
439
  - **An exception in a reactive variable's initial lambda was swallowed and the
313
440
  variable stuck at `nil` (or `true`).** On a connected component the error
314
441
  was reported, and then `handle_error`'s return value was stored as the
@@ -316,12 +443,12 @@ application could notice:
316
443
  component with a channel, and the lambda never ran again. A child whose
317
444
  lambda failed rendered blank, with nothing sent to the client, and a failed
318
445
  shared variable stayed broken for every later sharer. The error now goes
319
- through the normal handling for the render or action that read it, including
320
- `rescue_from`, and nothing is stored, so the next read retries. A top-level
321
- component's subscribe now sends just the `_error` (no trailing `_refresh`).
322
- A child's failing initial value now replaces its parent with the error box.
323
- A non-proc initial value now raises `ArgumentError` when the class loads
324
- (gem).
446
+ through the error handling of the subscribe or render that first reads it,
447
+ and nothing is stored, so the next read retries. A top-level component's
448
+ subscribe now sends just the `_error` (no trailing `_refresh`). A child's
449
+ failing initial value now replaces its parent with the error box. An initial
450
+ value other than a proc or `nil` now raises `ArgumentError` when the class
451
+ loads (gem).
325
452
  - **Initial lambdas ran again on every read during the HTTP prerender.** With
326
453
  no connection, the reactive getter never kept the value, so a `.live.erb`
327
454
  template ran the lambda once per reference, plus once for the render locals.
@@ -335,12 +462,20 @@ application could notice:
335
462
  confirmed its status. So state a child derived in `before_render` showed its
336
463
  initial value and went stale every time the parent rendered it again. A
337
464
  child's render callbacks now run each time a connected parent renders it,
338
- and an error in one replaces the parent with the error box. On page load the
339
- parent renders the child before the child subscribes, so the child's render
340
- callbacks run before its connect callbacks, without connection identifiers
341
- such as `current_user`. A child whose `before_render` uses one will now
342
- error its parent on page load. Render callbacks still don't run during the
343
- HTTP prerender, which the lifecycle guide now says (gem).
465
+ and an error in one replaces the parent with the error box. A
466
+ `before_render` that throws `:abort` keeps the child as it last rendered, or
467
+ leaves it out the first time the parent renders it, until the parent renders
468
+ it again and the callback lets it through. A grandchild that changed along
469
+ with its grandparent, or a child whose parent subscribed again, is no longer
470
+ also rendered on its own in the same update, so its callbacks run once. When
471
+ a callback halts a parent's own render, a child that changed now renders on
472
+ its own instead of being skipped. The first time a connected parent renders
473
+ a child, on page load or when an action first shows it, the child hasn't
474
+ subscribed yet, so its render callbacks run before its connect callbacks,
475
+ without connection identifiers such as `current_user`. A child whose
476
+ `before_render` uses one will now error its parent the first time the parent
477
+ renders it. Render callbacks still don't run during the HTTP prerender,
478
+ which the lifecycle guide now says (gem).
344
479
  - **A checkbox with `live-reactive` could never be unchecked, and a `<select
345
480
  multiple>` kept only its first choice.** `live-reactive` always sent the
346
481
  input's `value`. For a checkbox that is its `value` attribute ("on" by
@@ -350,22 +485,59 @@ application could notice:
350
485
  selects and text inputs still send their value as a String. If you were
351
486
  reading "on" (or a custom `value` attribute) from a checkbox, you now get a
352
487
  boolean (npm).
488
+ - **A `live-disable-with` button lost the markup in its label when an `_ack`
489
+ answered its message.** The label was saved and restored as text, which
490
+ flattened an icon or a `<span>` inside it. A `_refresh` reply rebuilds the
491
+ button from the stored render and hid that, but an `_ack` leaves the page
492
+ alone, and since a render in which no part re-renders is no longer sent,
493
+ more actions are answered with one: an icon in a click counter's button was
494
+ gone after the first click. The label is now saved and restored as HTML
495
+ (npm).
496
+ - **Every action on a component with `reactive :method` raised
497
+ `ArgumentError`.** The action was looked up with the component's `method`,
498
+ which the reactive variable's getter replaces. It is now looked up with
499
+ Kernel's `method`, so a reactive variable named `method` works (gem).
500
+ - **`t('.key')` in a component template raised over the socket and used the
501
+ page's scope on page load.** Rails scopes a relative key by the template
502
+ being rendered, but it only knows that while the template's compiled method
503
+ runs, and a `.live.erb` template's parts run after it returns. Over the
504
+ socket there was no template at all, so the lookup raised "Cannot use
505
+ t(".key") shortcut because path is not available"; on page load it used
506
+ the page's path, so `t('.title')` looked up `home.index.title`. Each
507
+ render of a component template now runs its parts with that template's
508
+ path, so a relative key resolves to the template's own scope, such as
509
+ `live.counter.title`, in a child component and in each template of a
510
+ compound component too (gem).
353
511
 
354
512
  ### Changed
355
513
 
514
+ - **The gemspec allowed Rails 7.1 and 7.2, where every action that takes
515
+ params raised `NameError`.** LiveCable parses action params with
516
+ `ActionDispatch::ParamBuilder` and `ActionDispatch::QueryParser`, which
517
+ Rails 8.0 added. The gem now requires Rails 8.0 or later, and the
518
+ installation guide, which said 7.1, says so (gem).
356
519
  - **A render that changed nothing on the page was still sent.** When a
357
520
  reactive variable changed but no part of the template showed it - a shared
358
521
  variable updated by another component, say - the component still sent a
359
522
  `_refresh` with every part empty, and the client rebuilt and morphed it for
360
- no visible change. Such a render is now skipped: its events still go out,
361
- its render callbacks still run, and the message it answers gets an `_ack`.
362
- - **Every render over the socket built a controller, request and response.**
363
- `Component#render` went through `ApplicationController.renderer`, which
364
- builds all three each time - about a fifth of the render time of a small
365
- component. A connection now builds them once, from the same renderer
366
- defaults, and each render takes a fresh view from that controller, so
367
- `content_for`, instance variables a template sets and memoized view helpers
368
- still don't carry over. The HTTP prerender is unchanged (gem).
523
+ no visible change. A render in which no part re-renders is now skipped: its
524
+ events still go out, its render callbacks still run, and the message it
525
+ answers gets an `_ack`, which carries the events of the component that sent
526
+ the message. An action answered this way no longer resets its form: a field
527
+ the server doesn't track keeps what was typed. A part that reads a
528
+ non-reactive `shared` variable or a local an earlier tag assigns re-renders
529
+ whenever its component does, so a template with one still sends a
530
+ `_refresh` (gem).
531
+ - **Every render over the socket went through a full controller render.**
532
+ `Component#render` used `ApplicationController.renderer`, which builds a
533
+ controller, request and response and renders through `render_to_string`
534
+ each time, about a sixth of the time of an action on a small component. A
535
+ connection now builds the request and response once, from the renderer's
536
+ current defaults, and each render calls the component's `render_in` on a
537
+ fresh controller and view, so nothing one render sets or memoizes on them
538
+ carries over to the next. A component with a public `format` method no
539
+ longer fails every socket render with `ArgumentError` (Invalid formats). The
540
+ HTTP prerender is unchanged (gem).
369
541
 
370
542
  ## 0.4.0 - 2026-09-29
371
543