live_cable 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0376ac919c3ed29e3c63181364e512f51aa39aeeb84f1b8a0584b42e1c89985
-  data.tar.gz: 8bb42eb86866bddf18fb83e0a16770c4ddb48c3ec22524b680e272d155e22431
+  metadata.gz: a08ab617cc974271c9f4b2784bb52ca53d1430942fd72e761fe52cd650a86141
+  data.tar.gz: abd1b26ca97b149de015b9fb7b9b457ff6b6f21e224a61318788876115fcd9d9
 SHA512:
-  metadata.gz: 4f95c867c6f65a85ceca7fad4c23cc572bc1cfb6c90e008ebb24403dbc7624cd9977ae711bc133484612b0e3ac16440f3d18bf365c656c8d537f009387dfd0fe
-  data.tar.gz: 01d716fd63f39335bbaaed9aa8b0643f5b9a1493b9f1ca449635b4aa7f3cecc6d67992f31503412cbba6fd53860778918627430365af614b8598beb0666306b4
+  metadata.gz: e3b932fcbdfcf3fb5d6b939320798eb151c82d0e6bc85c61c2452ff729233855b477752e10465c8098f4601651d04f9e67449293b9635cde3eefa47bde08733c
+  data.tar.gz: 6476ba238c1960655922da93588b175ed0468294364dd1252b05ad044eb26cb0d94360254581cb791ddc6def81155940c82d310835398b7c791b8cb3daf6884c

data/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The Ruby gem (`live_cable`) and the npm package (`@isometriks/live_cable`) are
+released together and share a single version number. Entries below note which
+side of the pair a change affects when it isn't both.
+
+## 0.2.0
+
+The gem and npm package versions are realigned in this release. The npm package
+jumps from 0.1.1 straight to 0.2.0, skipping 0.1.2, which was published for the
+gem only.
+
+### Added
+
+- **Server-dispatched DOM events.** Components can queue browser events with
+  `dispatch_event`, delivered with the next broadcast and fired after the DOM has
+  been morphed, so handlers observe the updated markup. Events are bubbling
+  `CustomEvent`s dispatched from the component root (or from `window` with
+  `window: true`), so they can be wired up with plain Stimulus `data-action`
+  syntax. (`LiveCable::Component::Events`)
+- **Loading states.** While a message is in flight, a `live-loading` attribute is
+  added to the component's root element and to the element that triggered the
+  message, so pending feedback can be styled with plain CSS. `live-disable-with`
+  on a button or submit button swaps its label and disables it for the duration
+  of the round trip; form values are serialized before anything is disabled.
+  Reactive inputs (`live-reactive`) receive `live-loading` but are never
+  disabled, so typing is not interrupted.
+- **Component test harness.** `LiveCable::Testing` can be included in specs to
+  mount and drive components without a browser, via `live_mount`.
+- `./loading` subpath export for the new loading module (npm).
+- Gemspec `homepage_uri`, `documentation_uri`, and `bug_tracker_uri` metadata.
+
+### Changed
+
+- Minimum Rails version raised from 7.0 to 7.1 (`actioncable`, `actionview`,
+  `activemodel`, `activesupport`) (gem).
+- Herb upgraded from `~> 0.8.10` to `~> 0.10.2`, and `prism >= 1.0` added as an
+  explicit dependency (gem).
+- Gem homepage now points at https://livecable.io rather than the RubyGems page.
+- The `Live` namespace for user components moved out of `lib/live_cable.rb` into
+  its own `lib/live.rb`, required explicitly and ignored by the gem's Zeitwerk
+  loader (gem).
+- Dev dependencies updated: Vitest 2.x to 4.x, happy-dom 15.x to 20.x (npm).
+
+### Fixed
+
+- Template compiler: block sentinel tokens now carry a newline value so Herb's
+  whitespace helpers (`at_line_start?`, `preceding_token_ends_with_newline?`)
+  treat them as a line boundary instead of raising on a `nil` value.
+- Template compiler: the closing `end` of an output block is emitted as plain
+  code instead of going through Herb's paren-balancing block-end helper, since
+  escaping is delegated to Rails' output buffer.
+
+## 0.1.2 - 2026-03-25
+
+Gem only; no corresponding npm release.
+
+### Added
+
+- JavaScript assets packaged so they can be consumed from package managers as
+  well as through the asset pipeline.
+
+## 0.1.1 - 2026-03-25
+
+### Added
+
+- Component generator.
+
+### Changed
+
+- Herb pinned to `0.8.*`, and other library versions pinned.
+
+### Fixed
+
+- `render` inside a live template.
+- Generator no longer creates `app/live` when the directory does not exist.
+
+## 0.1.0
+
+Initial public release.

data/README.md

@@ -3,7 +3,7 @@
 LiveCable is a Phoenix LiveView-style live component system for Ruby on Rails that tracks state server-side and allows
 you to call actions from the frontend using Stimulus with a React style state management API.
 
-**Full documentation: [livecable.io](https://livecable.io)**
+**Full documentation: [livecable.io](https://livecable.io)** | **Sandbox app: [live_cable_app](https://github.com/isometriks/live_cable_app)**
 
 ## Features
 
@@ -1000,6 +1000,53 @@ The `live-key` attribute acts as a hint for the diffing algorithm to identify el
 <% end %>
 ```
 
+## Loading States
+
+Every interaction is a round trip to the server. While a message is in flight, LiveCable adds a `live-loading` attribute to the component's root element and to the element that triggered the message, so you can show pending feedback with plain CSS:
+
+```css
+button[live-loading] { opacity: 0.5; cursor: wait; }
+
+.spinner { display: none; }
+[live-loading] .spinner { display: inline-block; }
+```
+
+To prevent double-clicks, mark buttons with `live-disable-with`. The element is disabled while the message is in flight and restored when the server responds. Give the attribute a value to also swap the label:
+
+```erb
+<button live-action="checkout" live-disable-with="Processing...">Checkout</button>
+
+<form live-form="save">
+  <input type="text" name="title">
+  <button type="submit" live-disable-with="Saving...">Save</button>
+</form>
+```
+
+For forms, put `live-disable-with` on the submit button(s); form values are serialized before anything is disabled. Reactive inputs (`live-reactive`) get the `live-loading` attribute but are never disabled, so typing is not interrupted.
+
+The loading state is cleared when the server responds — with a re-render, an error, or a lightweight acknowledgement when the action didn't change any state — so it never gets stuck.
+
+## Server Events
+
+Components can trigger DOM events on the client with `dispatch_event` — for scroll-to-bottom, closing modals, toasts, or anything else the client should do after the server finishes:
+
+```ruby
+def send_message(params)
+  messages << { text: params[:text] }
+  dispatch_event('chat:message-sent')
+end
+```
+
+Events fire as bubbling `CustomEvent`s from the component's root element **after the DOM has been morphed**, so handlers see the updated markup. Plain Stimulus `data-action` syntax handles them — no LiveCable-specific JavaScript:
+
+```erb
+<div data-controller="chat" data-action="chat:message-sent->chat#scrollToBottom">
+  ...
+</div>
+```
+
+Pass a payload (`dispatch_event('toast:show', message: 'Saved')`, available as `event.detail`) or target global listeners with `dispatch_event('analytics:tracked', window: true)`. Events work from actions, lifecycle callbacks, and `stream_from` callbacks, and are delivered exactly once, in order, whether or not the action re-rendered.
+
 ## Compound Components
 
 By default, components render the partial at `app/views/live/component_name.html.live.erb`. You can organize your templates differently by marking a component as `compound`.
@@ -1237,6 +1284,27 @@ When a broadcast is received:
 - **Live dashboards**: Update metrics and charts in real-time
 - **Presence tracking**: Show who's currently online or viewing a resource
 
+## Testing Components
+
+LiveCable includes a test harness for fast, browser-free component tests. Actions go through the real message pipeline (whitelisting, parameter parsing, change tracking, re-rendering), so tests exercise what production runs:
+
+```ruby
+RSpec.describe Live::Counter do
+  include LiveCable::Testing
+
+  it 'increments by the step size' do
+    counter = live_mount('counter', step: 2)
+
+    counter.perform(:increment)
+
+    expect(counter.count).to eq(2)
+    expect(counter.rendered).to have_css('[data-testid="counter-value"]', text: '2')
+  end
+end
+```
+
+The harness supports client reactive updates (`set_reactive`), broadcast assertions (`broadcasts(:_refresh)`), simulated stream broadcasts (`receive_stream`), shared state across components mounted on the same connection, connection identifiers like `current_user`, and lifecycle testing via `unmount`. See the [testing guide](https://livecable.io/guide/testing) for the full API.
+
 ## Error Handling
 
 When an unhandled exception is raised inside a component action, LiveCable replaces the component in the DOM with an error message and cleans up the server-side component.

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

@@ -1,5 +1,6 @@
 import { Controller } from "@hotwired/stimulus"
 import SubscriptionManager from "@isometriks/live_cable/subscriptions"
+import LoadingState from "@isometriks/live_cable/loading"
 
 export default class extends Controller {
   static values = {
@@ -12,16 +13,18 @@ export default class extends Controller {
 
   #subscription
   #debounces = new Map()
+  #loading
 
   #callActionCallback = (event) => {
     event.stopPropagation()
 
     const { action, params } = event.detail
 
-    this.sendCall(action, params)
+    this.sendCall(action, params, event.target)
   }
 
   connect() {
+    this.#loading = new LoadingState(this.element)
     this.element.addEventListener("call", this.#callActionCallback)
 
     this.#subscription = SubscriptionManager.subscribe(
@@ -33,8 +36,8 @@ export default class extends Controller {
 
     // Create callbacks for each action or form
     this.actionsValue.forEach((action) => {
-      this[`action_$${action}`] = ({ params }) => {
-        this.sendCall(action, this.#convertKeysToSnakeCase(params))
+      this[`action_$${action}`] = ({ params, currentTarget }) => {
+        this.sendCall(action, this.#convertKeysToSnakeCase(params), currentTarget)
       }
 
       this[`form_$${action}`] = (event) => {
@@ -47,12 +50,30 @@ export default class extends Controller {
     this.element.removeEventListener("call", this.#callActionCallback)
   }
 
-  sendCall(action, params = {}) {
+  sendCall(action, params = {}, trigger = null) {
+    this.#loading.start(trigger)
     this.#subscription.send(
       this.#flushDebounced(this.#callMessage(params, action))
     )
   }
 
+  // Called by the subscription when the server answers a message
+  // (refresh, ack, or error). Restores any live-loading / live-disable-with
+  // state once all in-flight messages have been answered.
+  finishLoading() {
+    this.#loading?.finish()
+  }
+
+  // Whether any message is still awaiting a server response
+  get isLoading() {
+    return this.#loading?.active ?? false
+  }
+
+  // Called by the subscription when the component is being torn down.
+  resetLoading() {
+    this.#loading?.reset()
+  }
+
   #callMessage(params, action) {
     return {
       _action: action,
@@ -83,6 +104,8 @@ export default class extends Controller {
 
   sendReactive(target) {
     this.#clearDebounce(target)
+    // Never disable reactive inputs while in flight - it would drop focus
+    this.#loading.start(target, { disable: false })
     this.#subscription.send(
       this.#flushDebounced(this.#reactiveMessage(target))
     )
@@ -114,9 +137,13 @@ export default class extends Controller {
   sendForm(action, formEl) {
     this.#clearDebounce(formEl)
 
+    // Serialize before starting the loading state - disabled controls
+    // (live-disable-with) are excluded from FormData
     const formData = new FormData(formEl)
     const params = new URLSearchParams(formData).toString()
 
+    this.#loading.start(formEl)
+
     this.#subscription.send(
       this.#flushDebounced(this.#callMessage(params, action))
     )

data/app/assets/javascript/loading.js

@@ -0,0 +1,162 @@
+/**
+ * Loading state tracking for LiveCable components.
+ *
+ * Tracks in-flight messages for a single component and reflects them in the
+ * DOM so users can style pending states with CSS:
+ *
+ * - The component root element gets a `live-loading` attribute while any
+ *   message is awaiting a server response.
+ * - The element that triggered the message (button, form, input) also gets
+ *   a `live-loading` attribute.
+ * - Elements with a `live-disable-with` attribute are disabled while the
+ *   message is in flight. If the attribute has a value, the element's label
+ *   (textContent, or value for inputs) is swapped for it.
+ *
+ * The state is cleared when the server responds with a refresh, an error,
+ * or an ack (sent when an action didn't change any reactive variables).
+ * Multiple in-flight messages are counted; the DOM is only restored once
+ * all of them have been answered.
+ */
+export default class LoadingState {
+  /** @type {HTMLElement} */
+  #root
+  /** @type {number} */
+  #inFlight = 0
+  /** @type {Set<Element>} - Elements marked with the live-loading attribute */
+  #markedElements = new Set()
+  /** @type {Map<Element, Object>} - Original state of disabled elements */
+  #disabledElements = new Map()
+
+  /**
+   * @param {HTMLElement} root - The component's root element
+   */
+  constructor(root) {
+    this.#root = root
+  }
+
+  /**
+   * Whether any message is currently awaiting a server response.
+   * @returns {boolean}
+   */
+  get active() {
+    return this.#inFlight > 0
+  }
+
+  /**
+   * Mark the component as loading.
+   * Called right before a message is sent to the server.
+   *
+   * @param {Element|null} trigger - The element that triggered the message
+   * @param {Object} options
+   * @param {boolean} options.disable - Whether to process live-disable-with
+   *   elements. Disabled for reactive inputs so typing doesn't lose focus.
+   */
+  start(trigger = null, { disable = true } = {}) {
+    this.#inFlight++
+
+    this.#mark(this.#root)
+
+    if (trigger instanceof Element && trigger !== this.#root) {
+      this.#mark(trigger)
+
+      if (disable) {
+        this.#disableElements(trigger)
+      }
+    }
+  }
+
+  /**
+   * Record a server response for this component.
+   * Restores the DOM once all in-flight messages have been answered.
+   *
+   * @returns {boolean} true if the loading state was fully cleared
+   */
+  finish() {
+    if (this.#inFlight === 0) {
+      return false
+    }
+
+    this.#inFlight--
+
+    if (this.#inFlight > 0) {
+      return false
+    }
+
+    this.#restore()
+    return true
+  }
+
+  /**
+   * Clear all loading state immediately, regardless of in-flight count.
+   * Used when the component is being torn down (e.g. on error).
+   */
+  reset() {
+    this.#inFlight = 0
+    this.#restore()
+  }
+
+  #mark(element) {
+    element.setAttribute('live-loading', '')
+    this.#markedElements.add(element)
+  }
+
+  /**
+   * Disable the trigger and/or its descendants marked with live-disable-with.
+   * For a button the attribute lives on the button itself; for a form it
+   * usually lives on the submit button(s) inside it.
+   */
+  #disableElements(trigger) {
+    const elements = []
+
+    if (trigger.hasAttribute('live-disable-with')) {
+      elements.push(trigger)
+    }
+
+    elements.push(...trigger.querySelectorAll('[live-disable-with]'))
+
+    elements.forEach(element => {
+      // Already disabled by an earlier in-flight message
+      if (this.#disabledElements.has(element)) {
+        return
+      }
+
+      const text = element.getAttribute('live-disable-with')
+      const isInput = element instanceof HTMLInputElement
+
+      this.#disabledElements.set(element, {
+        disabled: element.disabled,
+        content: text ? (isInput ? element.value : element.textContent) : null,
+      })
+
+      element.disabled = true
+
+      if (text) {
+        if (isInput) {
+          element.value = text
+        } else {
+          element.textContent = text
+        }
+      }
+    })
+  }
+
+  #restore() {
+    this.#markedElements.forEach(element => {
+      element.removeAttribute('live-loading')
+    })
+    this.#markedElements.clear()
+
+    this.#disabledElements.forEach(({ disabled, content }, element) => {
+      element.disabled = disabled
+
+      if (content !== null) {
+        if (element instanceof HTMLInputElement) {
+          element.value = content
+        } else {
+          element.textContent = content
+        }
+      }
+    })
+    this.#disabledElements.clear()
+  }
+}

data/app/assets/javascript/subscriptions.js

@@ -396,6 +396,10 @@ class Subscription {
    * @param {string} [data._status] - Status update (e.g., 'subscribed', 'destroy')
    * @param {string} [data._refresh] - HTML to morph into the DOM
    * @param {string} [data._error] - Raw error HTML to replace the component with
+   * @param {boolean} [data._ack] - Acknowledgement that a message was processed
+   *   without producing a re-render; clears the loading state
+   * @param {Array} [data._events] - Events to dispatch as CustomEvents; when
+   *   attached to a _refresh they fire after the DOM has been morphed
    * @private
    */
   #received = (data) => {
@@ -405,7 +409,32 @@ class Subscription {
       this.#handleRefresh(data['_refresh'])
     } else if (data['_error']) {
       this.#handleError(data['_error'])
+    } else if (data['_ack']) {
+      this.#controller?.finishLoading()
     }
+
+    // Dispatch after the branch above so events attached to a refresh fire
+    // once the morph has completed and handlers see the updated DOM
+    if (data['_events']) {
+      this.#dispatchEvents(data['_events'])
+    }
+  }
+
+  /**
+   * Fire server-dispatched events as bubbling CustomEvents from the
+   * component's root element, or from window when the event asks for it.
+   *
+   * @param {Array<{name: string, detail: Object, window: boolean}>} events
+   * @private
+   */
+  #dispatchEvents(events) {
+    events.forEach(({ name, detail, window: onWindow }) => {
+      const target = onWindow ? window : this.#controller?.element
+
+      if (target) {
+        target.dispatchEvent(new CustomEvent(name, { detail, bubbles: true }))
+      }
+    })
   }
 
   /**
@@ -420,6 +449,7 @@ class Subscription {
       return
     }
 
+    this.#controller.resetLoading()
     this.#controller.element.outerHTML = html
     this.unsubscribe()
   }
@@ -458,10 +488,40 @@ class Subscription {
       return
     }
 
-    morphdom(this.#controller.element, this.#buildRefreshDOM(refresh), {
+    // Restore live-loading / live-disable-with state before morphing so the
+    // morph applies the server-rendered truth on top of the original DOM.
+    // With multiple messages in flight this only restores once the last
+    // response arrives - until then the morph below preserves the pending
+    // elements so live-disable-with buttons can't be clicked early.
+    this.#controller.finishLoading()
+
+    const rootElement = this.#controller.element
+    const stillLoading = this.#controller.isLoading
+
+    const refreshDOM = this.#buildRefreshDOM(refresh)
+
+    if (stillLoading) {
+      refreshDOM.setAttribute('live-loading', '')
+    }
+
+    morphdom(rootElement, refreshDOM, {
       // Preserve elements marked with live-ignore attribute
       onBeforeElUpdated(fromEl, toEl) {
-        return fromEl.hasAttribute && !fromEl.hasAttribute('live-ignore')
+        if (!fromEl.hasAttribute) {
+          return true
+        }
+
+        if (fromEl.hasAttribute('live-ignore')) {
+          return false
+        }
+
+        // Keep elements that are still awaiting a server response untouched
+        // (the root is handled above so the rest of the tree still morphs)
+        if (stillLoading && fromEl !== rootElement && fromEl.hasAttribute('live-loading')) {
+          return false
+        }
+
+        return true
       },
       // Use stable keys for better morphing performance and state preservation
       getNodeKey(node) {

data/config/importmap.rb

@@ -6,6 +6,7 @@ pin 'morphdom', to: 'https://ga.jspm.io/npm:morphdom@2.7.8/dist/morphdom-esm.js'
 pin '@isometriks/live_cable/controller', to: 'controllers/live_controller.js'
 pin '@isometriks/live_cable/blessing', to: 'live_cable_blessing.js'
 pin '@isometriks/live_cable/subscriptions', to: 'subscriptions.js'
+pin '@isometriks/live_cable/loading', to: 'loading.js'
 pin '@isometriks/live_cable/observer', to: 'observer.js'
 pin '@isometriks/live_cable/dom', to: 'dom.js'
 pin '@isometriks/live_cable', to: 'live_cable.js'

data/lib/live.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Live
+  # For components to live in
+end

data/lib/live_cable/component/broadcasting.rb

@@ -13,6 +13,12 @@ module LiveCable
         broadcast({ _status: 'subscribed', id: live_id })
       end
 
+      # Sent when a received message didn't change any reactive variables,
+      # so the client can clear its loading state without a re-render.
+      def broadcast_ack
+        broadcast({ _ack: true })
+      end
+
       def broadcast_destroy
         broadcast({ _status: 'destroy' })
         @subscribed = false
@@ -20,9 +26,14 @@ module LiveCable
 
       def broadcast_render
         run_callbacks :render do
-          broadcast(
-            _refresh: render.as_json
-          )
+          data = { _refresh: render.as_json }
+
+          # Events ride along with the render so the client can fire them
+          # after the DOM has been morphed
+          events = flush_events
+          data[:_events] = events if events.any?
+
+          broadcast(data)
         end
       end
     end

data/lib/live_cable/component/events.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LiveCable
+  class Component
+    module Events
+      extend ActiveSupport::Concern
+
+      # Queue a DOM event to be dispatched on the client. Events are
+      # delivered with the next broadcast for this component - attached to
+      # the render when state changed, or on their own when it didn't - and
+      # fire on the client after the DOM has been morphed, so handlers see
+      # the updated markup.
+      #
+      # On the client the event is a bubbling CustomEvent dispatched from
+      # the component's root element (or from window with window: true), so
+      # it can be handled with plain Stimulus data-action syntax:
+      #
+      #   <div data-controller="chat" data-action="chat:message-sent->chat#scrollToBottom">
+      #
+      # @param name [String, Symbol] The event name (e.g. 'chat:message-sent')
+      # @param detail [Hash] JSON-serializable payload, available as event.detail.
+      #   Can be passed positionally or as bare keyword arguments; use the
+      #   positional form if the payload itself needs a :window key.
+      # @param window [Boolean] Dispatch on window instead of the component root
+      def dispatch_event(name, positional_detail = nil, window: false, **detail)
+        detail = positional_detail if positional_detail
+
+        pending_events << { name: name.to_s, detail: detail.as_json, window: }
+      end
+
+      # Drain the queued events. Called when a broadcast is sent so each
+      # event is delivered exactly once.
+      #
+      # @return [Array<Hash>]
+      def flush_events
+        events = pending_events.dup
+        pending_events.clear
+        events
+      end
+
+      private
+
+      # @return [Array<Hash>]
+      def pending_events
+        @pending_events ||= []
+      end
+    end
+  end
+end

data/lib/live_cable/component.rb

@@ -7,6 +7,7 @@ module LiveCable
     include Identification
     include Lifecycle
     include Broadcasting
+    include Events
     include Rendering
     include Streaming
     include MethodDependencyTracking

data/lib/live_cable/connection/broadcasting.rb

@@ -5,6 +5,8 @@ module LiveCable
     module Broadcasting
       extend ActiveSupport::Concern
 
+      # @return [Array<LiveCable::Component>] Components that were broadcast to
+      #   (rendered or errored), including children rendered by their parents
       def broadcast_changeset
         rendered = []
         shared_changeset = containers[SHARED_CONTAINER]&.changeset
@@ -25,8 +27,18 @@ module LiveCable
             handle_error(component, error)
           end
 
-          rendered |= component.rendered_children
+          rendered |= [component] | component.rendered_children
         end
+
+        # Deliver events from components that didn't broadcast a render this
+        # cycle (no state change, or rendered inline by a parent) - rendered
+        # components already flushed their events with the refresh
+        components.each_value do |component|
+          events = component.flush_events
+          component.broadcast(_events: events) if events.any?
+        end
+
+        rendered
       end
     end
   end

data/lib/live_cable/connection/messaging.rb

@@ -11,13 +11,22 @@ module LiveCable
 
         return unless data['messages'].present?
 
+        # An error broadcasts an _error, which is itself the batch's one
+        # response - so a failed message must suppress the trailing _ack
+        errored = false
         data['messages'].each do |message|
-          action(component, message)
+          errored = true unless action(component, message)
         end
 
-        broadcast_changeset
+        rendered = broadcast_changeset
+
+        # Guarantee exactly one response per message batch so the client can
+        # clear its loading state even when nothing changed
+        component.broadcast_ack unless errored || rendered.include?(component)
       end
 
+      # @return [Boolean] true when the message was processed, false when an
+      #   error was handled (and an _error broadcast in its place)
       def action(component, data)
         params = parse_params(data)
 
@@ -40,18 +49,25 @@ module LiveCable
             method.call
           end
         end
+
+        true
       rescue StandardError => e
         handle_error(component, e)
+        false
       end
 
+      # @return [Boolean] true when applied, false when an error was handled
       def reactive(component, data)
         unless component.class.writable_reactive_variables.include?(data['name'].to_sym)
           raise LiveCable::Error, "Non-writable reactive variable: #{data['name']}"
         end
 
         component.public_send("#{data['name']}=", data['value'])
+
+        true
       rescue StandardError => e
         handle_error(component, e)
+        false
       end
 
       private

data/lib/live_cable/rendering/compiler.rb

@@ -3,16 +3,19 @@
 module LiveCable
   module Rendering
     class Compiler < ::Herb::Engine::Compiler
+      # Sentinel tokens carry a "\n" value so herb's whitespace helpers
+      # (at_line_start?, preceding_token_ends_with_newline?) treat them like
+      # a line boundary instead of crashing on a nil value.
       def visit_erb_control_node(node)
-        @tokens << [:block_start]
+        @tokens << [:block_start, "\n"]
         super
-        @tokens << [:block_end]
+        @tokens << [:block_end, "\n"]
       end
 
       def visit_erb_block_node(node)
-        @tokens << [:block_start]
+        @tokens << [:block_start, "\n"]
         super
-        @tokens << [:block_end]
+        @tokens << [:block_end, "\n"]
       end
 
       def generate_output
@@ -29,11 +32,14 @@ module LiveCable
         end
       end
 
-      def generate_for_token(type, value, context)
+      def generate_for_token(type, value, _context = nil, _escaped = nil)
         case type
         when :text
           @engine.send(:add_text, value)
-        when :code
+        when :code, :expr_block_end
+          # Escaping is delegated to Rails' output buffer, so the closing
+          # `end` of an output block (:expr_block_end) is emitted as plain
+          # code rather than herb's paren-balancing add_expression_block_end.
           @engine.send(:add_code, value)
         when :expr
           indicator = @escape ? '==' : '='

data/lib/live_cable/testing/render_state.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Testing
+    # Reconstructs a component's rendered HTML from _refresh broadcasts,
+    # mirroring what the JavaScript client does: the first refresh carries
+    # all parts, subsequent refreshes carry only the changed parts (nil
+    # means unchanged), and child components arrive as separate results
+    # referenced by <LiveCable child-live-id="..."> placeholders.
+    class RenderState
+      CHILD_PLACEHOLDER = %r{<LiveCable child-live-id="(?<live_id>[^"]+)"></LiveCable>}
+
+      def initialize
+        @parts_by_template = {}
+        @last_template = nil
+        @children = Hash.new { |hash, key| hash[key] = RenderState.new }
+      end
+
+      # @param refresh [Hash] A _refresh payload ({ h:, p:, c: })
+      def apply(refresh)
+        refresh = refresh.as_json # Normalize symbol/string keys
+
+        template = refresh['h'] || @last_template || 'default'
+        @last_template = template
+
+        parts = refresh['p'] || []
+
+        if @parts_by_template.key?(template)
+          parts.each_with_index do |part, index|
+            @parts_by_template[template][index] = part unless part.nil?
+          end
+        else
+          @parts_by_template[template] = parts.dup
+        end
+
+        (refresh['c'] || {}).each do |live_id, child_refresh|
+          @children[live_id].apply(child_refresh)
+        end
+      end
+
+      # @return [String] The reconstructed HTML with child placeholders resolved
+      def html
+        parts = @parts_by_template[@last_template]
+        return '' unless parts
+
+        parts.join.gsub(CHILD_PLACEHOLDER) do
+          @children[Regexp.last_match[:live_id]].html
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/testing/test_cable_connection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Testing
+    # Stand-in for an ActionCable connection exposing identified_by values
+    # (e.g. current_user) to components and their templates.
+    class TestCableConnection
+      # @return [Set<Symbol>]
+      attr_reader :identifiers
+
+      def initialize(identifiers = {})
+        identifiers = identifiers.symbolize_keys
+        @identifiers = identifiers.keys.to_set
+
+        identifiers.each do |name, value|
+          define_singleton_method(name) { value }
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/testing/test_channel.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LiveCable
+  module Testing
+    # Stand-in for an ActionCable channel. Records streams started via
+    # stream_from so tests can trigger their callbacks with receive_stream.
+    class TestChannel
+      # @return [Hash<String, Hash>] Stream name => { coder:, callback: }
+      attr_reader :streams
+
+      # @return [LiveCable::Testing::TestCableConnection]
+      attr_reader :connection
+
+      def initialize(identifiers = {})
+        @streams = {}
+        @connection = TestCableConnection.new(identifiers)
+      end
+
+      def stream_from(name, coder: nil, &block)
+        @streams[name] = { coder:, callback: block }
+      end
+
+      def stop_stream_from(name)
+        @streams.delete(name)
+      end
+
+      # Simulate an external broadcast arriving on a stream.
+      # The payload goes through the stream's coder round trip, so a Hash
+      # payload arrives with string keys just like a production broadcast.
+      #
+      # @param name [String] The stream name passed to stream_from
+      # @param payload [Object] The broadcast payload
+      def broadcast_to(name, payload)
+        stream = @streams.fetch(name) do
+          raise LiveCable::Error, "Component is not streaming from #{name.inspect} " \
+                                  "(active streams: #{@streams.keys.inspect})"
+        end
+
+        callback = stream[:callback]
+        raise LiveCable::Error, "Stream #{name.inspect} has no callback" unless callback
+
+        coder = stream[:coder]
+        payload = coder.decode(coder.encode(payload)) if coder
+
+        callback.call(payload)
+      end
+    end
+  end
+end

data/lib/live_cable/testing/test_component.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module LiveCable
+  module Testing
+    # Wraps a mounted component for testing. Delegates unknown methods to
+    # the component itself, so reactive variables and component methods can
+    # be read directly (e.g. +counter.count+).
+    class TestComponent < SimpleDelegator
+      # @return [LiveCable::Connection]
+      attr_reader :connection
+
+      # @return [LiveCable::Testing::TestChannel]
+      attr_reader :channel
+
+      def initialize(component, connection, channel)
+        super(component)
+        @connection = connection
+        @channel = channel
+        @broadcasts = []
+
+        capture_broadcasts(component)
+      end
+
+      # @return [LiveCable::Component] The underlying component instance
+      def component
+        __getobj__
+      end
+
+      # Dispatch an action through the real message pipeline, as if it was
+      # triggered by live-action or live-form in the browser.
+      #
+      # Params go through a query-string round trip, so values arrive as
+      # ActionController::Parameters with string values - exactly like
+      # production.
+      #
+      # @param action [Symbol, String] The action name
+      # @param params [Hash] Parameters for the action
+      def perform(action, params = {})
+        receive_message(
+          '_action' => action.to_s,
+          'params' => ::Rack::Utils.build_nested_query(params)
+        )
+      end
+
+      # Update a writable reactive variable, as if the client sent a
+      # live-reactive input update. Raises (or broadcasts an _error when
+      # mounted with raise_errors: false) for non-writable variables.
+      #
+      # @param name [Symbol, String] The reactive variable name
+      # @param value [Object] The new value
+      def set_reactive(name, value)
+        receive_message(
+          '_action' => '_reactive',
+          'name' => name.to_s,
+          'value' => value
+        )
+      end
+
+      # Simulate an external ActionCable broadcast arriving on a stream the
+      # component subscribed to via stream_from.
+      #
+      # @param stream_name [String] The stream name
+      # @param payload [Object] The broadcast payload
+      def receive_stream(stream_name, payload)
+        channel.broadcast_to(stream_name, payload)
+      end
+
+      # Everything the component has broadcast since mounting (renders,
+      # acks, status updates, errors), oldest first.
+      #
+      # @param key [Symbol, nil] Filter to broadcasts containing this key
+      #   (e.g. :_refresh, :_ack, :_error, :_status)
+      # @return [Array<Hash>]
+      def broadcasts(key = nil)
+        return @broadcasts.dup unless key
+
+        @broadcasts.select { |broadcast| broadcast.key?(key) }
+      end
+
+      # Forget previously captured broadcasts. Useful after mounting, to
+      # assert on the effects of a single action.
+      def clear_broadcasts
+        @broadcasts.clear
+      end
+
+      # All events the component has dispatched via dispatch_event, in
+      # order, whether they rode along with a render or were broadcast on
+      # their own.
+      #
+      # @return [Array<Hash>] Event hashes ({ name:, detail:, window: })
+      def dispatched_events
+        broadcasts(:_events).flat_map { |broadcast| broadcast[:_events] }
+      end
+
+      # The component's current HTML, reconstructed from its _refresh
+      # broadcasts the same way the JavaScript client builds the DOM.
+      #
+      # @return [String]
+      def rendered_html
+        state = RenderState.new
+
+        broadcasts(:_refresh).each do |broadcast|
+          state.apply(broadcast[:_refresh])
+        end
+
+        state.html
+      end
+
+      # The rendered HTML wrapped in a Capybara node, for use with matchers
+      # like have_css / have_content. Requires the capybara gem.
+      #
+      # @return [Capybara::Node::Simple]
+      def rendered
+        # ::-prefixed because Delegator subclasses can't resolve top-level
+        # constants through their BasicObject ancestry
+        unless defined?(::Capybara)
+          raise ::LiveCable::Error,
+            'Capybara is required for rendered - add it to your Gemfile or use rendered_html'
+        end
+
+        ::Capybara.string(rendered_html)
+      end
+
+      # Disconnect the component, running disconnect lifecycle callbacks and
+      # cleaning up its state - like a client unsubscribing.
+      def unmount
+        component.disconnect
+      end
+
+      private
+
+      def receive_message(message)
+        connection.receive(component, { 'messages' => [message] })
+      end
+
+      def capture_broadcasts(component)
+        captured = @broadcasts
+
+        component.define_singleton_method(:broadcast) do |data|
+          captured << data
+        end
+      end
+    end
+  end
+end

data/lib/live_cable/testing.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module LiveCable
+  # Test helpers for unit testing LiveCable components without a browser
+  # or a real ActionCable connection.
+  #
+  # Include the module in your specs and use +live_mount+ to mount a
+  # component. Actions and reactive updates are dispatched through the real
+  # message pipeline, so action whitelisting, parameter parsing, writability
+  # checks, change tracking, and re-rendering are all exercised exactly as
+  # they are in production.
+  #
+  # @example RSpec
+  #   RSpec.describe Live::Counter do
+  #     include LiveCable::Testing
+  #
+  #     it 'increments by the step size' do
+  #       counter = live_mount('counter', step: 2)
+  #
+  #       counter.perform(:increment)
+  #
+  #       expect(counter.count).to eq(2)
+  #       expect(counter.rendered).to have_css('[data-testid="counter-value"]', text: '2')
+  #     end
+  #   end
+  module Testing
+    # Mount a component for testing.
+    #
+    # Mirrors what +LiveChannel#subscribed+ does in production: the component
+    # is registered on a connection, defaults are applied, lifecycle connect
+    # callbacks run, and the initial render is broadcast.
+    #
+    # @param component [String, Class, LiveCable::Component] Component name
+    #   (e.g. 'counter' or 'chat/room'), component class, or instance
+    # @param id [String] The component id (defaults to 'test')
+    # @param connection [LiveCable::Connection, nil] Mount onto an existing
+    #   test connection (from another mounted component) to share state
+    #   between components
+    # @param identifiers [Hash] ActionCable connection identifiers made
+    #   available to the component (e.g. current_user: user)
+    # @param raise_errors [Boolean] Raise errors from actions and rendering
+    #   instead of broadcasting an _error like production does (default true)
+    # @param defaults [Hash] Default values for reactive variables
+    # @return [LiveCable::Testing::TestComponent]
+    def live_mount(component, id: 'test', connection: nil, identifiers: {}, raise_errors: true, **defaults)
+      connection ||= build_test_connection(raise_errors:)
+
+      instance =
+        case component
+        when LiveCable::Component then component
+        when Class then component.new(id)
+        else LiveCable.instance_from_string(component.to_s, id)
+        end
+
+      test_component = TestComponent.new(instance, connection, TestChannel.new(identifiers))
+
+      connection.add_component(instance)
+      instance.defaults = defaults
+      instance.apply_defaults
+      instance.connect(test_component.channel)
+      instance.broadcast_render
+
+      test_component
+    end
+
+    private
+
+    def build_test_connection(raise_errors:)
+      require 'action_dispatch/testing/test_request'
+
+      # An empty session skips the CSRF check, like a session-less request
+      request = ActionDispatch::TestRequest.create('rack.session' => {})
+      connection = LiveCable::Connection.new(request)
+
+      if raise_errors
+        def connection.handle_error(_component, error)
+          raise error
+        end
+      end
+
+      connection
+    end
+  end
+end

data/lib/live_cable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LiveCable
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/live_cable.rb

@@ -5,6 +5,7 @@ require 'herb'
 
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/live.rb")
 loader.setup
 
 require_relative 'live_cable/configuration'
@@ -12,6 +13,11 @@ require_relative 'live_cable/configuration'
 # Require helpers explicitly (Zeitwerk doesn't autoload app/ directory)
 require_relative '../app/helpers/live_cable_helper'
 
+# Namespace for user components (e.g. Live::Chat); lives outside the gem's
+# own LiveCable namespace, so it's ignored by the gem loader above and
+# required explicitly instead.
+require_relative 'live'
+
 module LiveCable
   def self.instance_from_string(string, id)
     klass = Live
@@ -40,8 +46,4 @@ module LiveCable
   end
 end
 
-module Live
-  # For components to live in
-end
-
 require 'live_cable/engine' if defined?(Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: live_cable
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Craig Blanchette
@@ -15,70 +15,84 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: actionview
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: herb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.10
+        version: 0.10.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.10
+        version: 0.10.2
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -101,12 +115,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - app/assets/javascript/controllers/live_controller.js
 - app/assets/javascript/dom.js
 - app/assets/javascript/live_cable.js
 - app/assets/javascript/live_cable_blessing.js
+- app/assets/javascript/loading.js
 - app/assets/javascript/observer.js
 - app/assets/javascript/subscriptions.js
 - app/channels/live_channel.rb
@@ -115,9 +131,11 @@ files:
 - lib/generators/live_cable/component/component_generator.rb
 - lib/generators/live_cable/component/templates/component.rb.tt
 - lib/generators/live_cable/component/templates/view.html.live.erb.tt
+- lib/live.rb
 - lib/live_cable.rb
 - lib/live_cable/component.rb
 - lib/live_cable/component/broadcasting.rb
+- lib/live_cable/component/events.rb
 - lib/live_cable/component/identification.rb
 - lib/live_cable/component/lifecycle.rb
 - lib/live_cable/component/method_dependency_tracking.rb
@@ -155,14 +173,23 @@ files:
 - lib/live_cable/rendering/partial_renderer.rb
 - lib/live_cable/rendering/render_result.rb
 - lib/live_cable/rendering/renderer.rb
+- lib/live_cable/testing.rb
+- lib/live_cable/testing/render_state.rb
+- lib/live_cable/testing/test_cable_connection.rb
+- lib/live_cable/testing/test_channel.rb
+- lib/live_cable/testing/test_component.rb
 - lib/live_cable/version.rb
-homepage: https://rubygems.org/gems/live_cable
+homepage: https://livecable.io
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/isometriks/live_cable
+  homepage_uri: https://livecable.io
+  documentation_uri: https://livecable.io
+  bug_tracker_uri: https://github.com/isometriks/live_cable/issues
+  changelog_uri: https://github.com/isometriks/live_cable/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib