live_cable 0.1.1 → 0.2.0

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/engine.rb

@@ -12,8 +12,10 @@ module LiveCable
         warn("[LiveCable Warning] #{live_component_dir} does not exist for components.")
       end
 
-      # Add LiveCable to importmap
-      app.config.importmap.paths << root.join('config/importmap.rb')
+      # Add LiveCable to importmap (skip when using jsbundling/npm)
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join('config/importmap.rb')
+      end
     end
 
     initializer 'live_cable.assets_precompile' do |app|

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.1'
+  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)