opal-vite 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5491e78891b38d4e302b86941b5bce99574452f0e361bad6c109711f9e0e247d
-  data.tar.gz: 70c7080aa2c98fc641c28e63c077aed1a601705a0c3b380031c0e822b7a6f1be
+  metadata.gz: d450e521fc2311f795d94b0a92a4d7b8f6e2b676d6320309fb8b3f69696e27ad
+  data.tar.gz: '05863ede7a7b4e8f44beceb2d3a7d0438d8e75102fde5dc496acb2251254d126'
 SHA512:
-  metadata.gz: 5951f4e205e1c6415062830331007db5592a51d8672f025a02cbee24ac4eef2239895c5f6ceb35e2a7c3b96187be54e80e85c032671e45640b815011e3fc98b7
-  data.tar.gz: c36245a857819c721caa5a5ab98f5beaeea97babf49168018abe84a104864696c19c3f34bd7393c9a2076b81599c3702babbd208e35a619239ae7336955a6905
+  metadata.gz: 390e78cf526a75c960387caaf4844923fe68814f271e11394a536d198cdcae1fbdaaca31290ddc58b60e6c0a4fe5b0d4d2598669ef246b040f3342b21892b51d
+  data.tar.gz: a15d5f251a90702fd67d93639b40a939d073fa43b008ec29693c44f2a32875e04d955b372547e74e4fb1c3355a200cb20012ffa7bb556a7fa0fb42c8618a7284

data/lib/opal/vite/version.rb

@@ -1,5 +1,5 @@
 module Opal
   module Vite
-    VERSION = "0.3.2"
+    VERSION = "0.3.4"
   end
 end

data/opal/opal_vite/concerns/v1/action_cable_helpers.rb

@@ -0,0 +1,379 @@
+# backtick_javascript: true
+
+module OpalVite
+  module Concerns
+    module V1
+      # ActionCableHelpers - Ruby-friendly DSL for ActionCable WebSocket communication
+      #
+      # This module provides methods for connecting to and interacting with
+      # Rails ActionCable channels from Opal/Stimulus controllers.
+      #
+      # Prerequisites:
+      # - @rails/actioncable package must be installed (npm install @rails/actioncable)
+      # - ActionCable consumer must be imported in your JavaScript entry point
+      #
+      # Usage:
+      #   # In your main.js:
+      #   import { createConsumer } from "@rails/actioncable"
+      #   window.ActionCable = { createConsumer }
+      #
+      #   # In your Opal controller:
+      #   class ChatController < StimulusController
+      #     include OpalVite::Concerns::V1::ActionCableHelpers
+      #
+      #     def connect
+      #       cable_connect("/cable")
+      #       subscribe_to("ChatChannel", room_id: 1) do |subscription|
+      #         on_cable_received(subscription) do |data|
+      #           append_message(data)
+      #         end
+      #       end
+      #     end
+      #
+      #     def disconnect
+      #       cable_disconnect
+      #     end
+      #
+      #     def send_message
+      #       cable_perform(:speak, message: target_value(:input))
+      #     end
+      #   end
+      module ActionCableHelpers
+        # ===== Consumer Management =====
+
+        # Create and store an ActionCable consumer
+        # @param url [String] WebSocket URL (e.g., "/cable" or "wss://example.com/cable")
+        # @return [Native] ActionCable consumer instance
+        # @example
+        #   cable_connect("/cable")
+        #   cable_connect("wss://api.example.com/cable")
+        def cable_connect(url = "/cable")
+          @_cable_consumer = `window.ActionCable.createConsumer(#{url})`
+        end
+
+        # Get the current ActionCable consumer
+        # @return [Native, nil] Consumer instance or nil
+        def cable_consumer
+          @_cable_consumer
+        end
+
+        # Disconnect and cleanup the ActionCable consumer
+        def cable_disconnect
+          return unless @_cable_consumer
+          `#{@_cable_consumer}.disconnect()`
+          @_cable_subscriptions = nil
+          @_cable_consumer = nil
+        end
+
+        # Check if ActionCable is connected
+        # @return [Boolean] true if connected
+        def cable_connected?
+          return false unless @_cable_consumer
+          `#{@_cable_consumer}.connection.isOpen()`
+        end
+
+        # ===== Subscription Management =====
+
+        # Subscribe to an ActionCable channel
+        # @param channel_name [String] Channel class name (e.g., "ChatChannel")
+        # @param params [Hash] Channel parameters (e.g., room_id: 1)
+        # @yield [subscription] Block that receives the subscription for setup
+        # @return [Native] Subscription instance
+        # @example
+        #   subscribe_to("ChatChannel", room_id: 1) do |subscription|
+        #     on_cable_connected(subscription) { puts "Connected!" }
+        #     on_cable_received(subscription) { |data| handle_data(data) }
+        #   end
+        def subscribe_to(channel_name, params = {}, &setup_block)
+          raise "Cable not connected. Call cable_connect first." unless @_cable_consumer
+
+          @_cable_subscriptions ||= {}
+          subscription_params = { channel: channel_name }.merge(params)
+          native_params = subscription_params.to_n
+
+          # Create subscription with empty callbacks (will be set via helpers)
+          subscription = `#{@_cable_consumer}.subscriptions.create(#{native_params}, {
+            connected: function() {},
+            disconnected: function() {},
+            received: function(data) {},
+            rejected: function() {}
+          })`
+
+          # Store subscription with a key
+          key = cable_subscription_key(channel_name, params)
+          @_cable_subscriptions[key] = subscription
+
+          # Yield for setting up callbacks
+          setup_block.call(subscription) if setup_block
+
+          subscription
+        end
+
+        # Unsubscribe from a channel
+        # @param channel_name [String] Channel class name
+        # @param params [Hash] Channel parameters
+        def unsubscribe_from(channel_name, params = {})
+          return unless @_cable_subscriptions
+          key = cable_subscription_key(channel_name, params)
+          subscription = @_cable_subscriptions.delete(key)
+          `#{subscription}.unsubscribe()` if subscription
+        end
+
+        # Get a subscription by channel name and params
+        # @param channel_name [String] Channel class name
+        # @param params [Hash] Channel parameters
+        # @return [Native, nil] Subscription instance or nil
+        def get_subscription(channel_name, params = {})
+          return nil unless @_cable_subscriptions
+          key = cable_subscription_key(channel_name, params)
+          @_cable_subscriptions[key]
+        end
+
+        # ===== Subscription Callbacks =====
+
+        # Set the connected callback for a subscription
+        # @param subscription [Native] Subscription instance
+        # @yield Block to execute when connected
+        def on_cable_connected(subscription, &block)
+          `#{subscription}.connected = function() { #{block.call} }`
+        end
+
+        # Set the disconnected callback for a subscription
+        # @param subscription [Native] Subscription instance
+        # @yield Block to execute when disconnected
+        def on_cable_disconnected(subscription, &block)
+          `#{subscription}.disconnected = function() { #{block.call} }`
+        end
+
+        # Set the received callback for a subscription
+        # @param subscription [Native] Subscription instance
+        # @yield [data] Block that receives incoming data
+        def on_cable_received(subscription, &block)
+          `#{subscription}.received = function(data) { #{block.call(`data`)} }`
+        end
+
+        # Set the rejected callback for a subscription
+        # @param subscription [Native] Subscription instance
+        # @yield Block to execute when subscription is rejected
+        def on_cable_rejected(subscription, &block)
+          `#{subscription}.rejected = function() { #{block.call} }`
+        end
+
+        # ===== Sending Data =====
+
+        # Perform an action on the default/first subscription
+        # @param action [Symbol, String] Action name (server-side method)
+        # @param data [Hash] Data to send
+        # @example
+        #   cable_perform(:speak, message: "Hello!")
+        #   cable_perform(:typing, user_id: current_user_id)
+        def cable_perform(action, data = {})
+          subscription = default_subscription
+          raise "No active subscription" unless subscription
+          perform_on(subscription, action, data)
+        end
+
+        # Perform an action on a specific subscription
+        # @param subscription [Native] Subscription instance
+        # @param action [Symbol, String] Action name
+        # @param data [Hash] Data to send
+        def perform_on(subscription, action, data = {})
+          native_data = data.to_n
+          `#{subscription}.perform(#{action.to_s}, #{native_data})`
+        end
+
+        # Send raw data on a subscription
+        # @param subscription [Native] Subscription instance
+        # @param data [Hash] Data to send
+        def cable_send(subscription, data)
+          native_data = data.to_n
+          `#{subscription}.send(#{native_data})`
+        end
+
+        # ===== Convenience Methods =====
+
+        # Subscribe and setup all callbacks in one call
+        # @param channel_name [String] Channel class name
+        # @param params [Hash] Channel parameters
+        # @param on_connected [Proc] Connected callback
+        # @param on_disconnected [Proc] Disconnected callback
+        # @param on_received [Proc] Received callback (receives data)
+        # @param on_rejected [Proc] Rejected callback
+        # @return [Native] Subscription instance
+        def cable_subscribe(channel_name, params: {}, on_connected: nil, on_disconnected: nil, on_received: nil, on_rejected: nil)
+          raise "Cable not connected. Call cable_connect first." unless @_cable_consumer
+
+          @_cable_subscriptions ||= {}
+          subscription_params = { channel: channel_name }.merge(params)
+          native_params = subscription_params.to_n
+
+          # Create subscription with callbacks directly
+          subscription = `#{@_cable_consumer}.subscriptions.create(#{native_params}, {
+            connected: function() {
+              #{on_connected.call if on_connected}
+            },
+            disconnected: function() {
+              #{on_disconnected.call if on_disconnected}
+            },
+            received: function(data) {
+              #{on_received.call(`data`) if on_received}
+            },
+            rejected: function() {
+              #{on_rejected.call if on_rejected}
+            }
+          })`
+
+          # Store subscription with a key
+          key = cable_subscription_key(channel_name, params)
+          @_cable_subscriptions[key] = subscription
+
+          subscription
+        end
+
+        # Quick subscription setup for simple channels
+        # @param channel_name [String] Channel class name
+        # @param params [Hash] Channel parameters
+        # @yield [data] Block that handles received data
+        # @return [Native] Subscription instance
+        # @example
+        #   quick_subscribe("NotificationChannel") do |data|
+        #     show_notification(data["message"])
+        #   end
+        def quick_subscribe(channel_name, params = {}, &on_received)
+          subscribe_to(channel_name, params) do |subscription|
+            on_cable_received(subscription) { |data| on_received.call(data) } if on_received
+          end
+        end
+
+        # ===== Broadcast Helpers =====
+        # These methods help handle specific broadcast patterns
+
+        # Handle a broadcast that contains HTML to insert
+        # @param data [Native] Received data object
+        # @param target_selector [String] CSS selector for target element
+        # @param position [Symbol] Insert position (:append, :prepend, :replace, :before, :after)
+        def handle_html_broadcast(data, target_selector, position = :append)
+          html = `#{data}.html || #{data}.content || #{data}.body || ""`
+          return if `#{html} === ""`
+
+          target = `document.querySelector(#{target_selector})`
+          return unless `#{target}`
+
+          case position
+          when :append
+            `#{target}.insertAdjacentHTML('beforeend', #{html})`
+          when :prepend
+            `#{target}.insertAdjacentHTML('afterbegin', #{html})`
+          when :replace
+            `#{target}.innerHTML = #{html}`
+          when :before
+            `#{target}.insertAdjacentHTML('beforebegin', #{html})`
+          when :after
+            `#{target}.insertAdjacentHTML('afterend', #{html})`
+          end
+        end
+
+        # Handle a broadcast that updates a specific element
+        # @param data [Native] Received data with id and content
+        # @param id_key [String] Key in data containing element ID
+        # @param content_key [String] Key in data containing new content
+        def handle_update_broadcast(data, id_key = "id", content_key = "content")
+          element_id = `#{data}[#{id_key}]`
+          content = `#{data}[#{content_key}]`
+          return if `#{element_id} === undefined || #{content} === undefined`
+
+          element = `document.getElementById(#{element_id})`
+          `#{element}.innerHTML = #{content}` if `#{element}`
+        end
+
+        # Handle a broadcast that removes an element
+        # @param data [Native] Received data with id
+        # @param id_key [String] Key in data containing element ID
+        def handle_remove_broadcast(data, id_key = "id")
+          element_id = `#{data}[#{id_key}]`
+          return if `#{element_id} === undefined`
+
+          element = `document.getElementById(#{element_id})`
+          `#{element}.remove()` if `#{element}`
+        end
+
+        # ===== Data Extraction Helpers =====
+
+        # Extract a value from received ActionCable data
+        # @param data [Native] Received data object
+        # @param key [String, Symbol] Key to extract
+        # @param default [Object] Default value if key doesn't exist
+        # @return [Object] Extracted value or default
+        def cable_data(data, key, default = nil)
+          key_s = key.to_s
+          value = `#{data}[#{key_s}]`
+          `#{value} === undefined` ? default : value
+        end
+
+        # Extract and parse a JSON string from received data
+        # @param data [Native] Received data object
+        # @param key [String, Symbol] Key containing JSON string
+        # @return [Native] Parsed JSON object or nil
+        def cable_data_json(data, key)
+          json_str = cable_data(data, key)
+          return nil if json_str.nil?
+          `JSON.parse(#{json_str})`
+        rescue
+          nil
+        end
+
+        # Check if received data has a specific key
+        # @param data [Native] Received data object
+        # @param key [String, Symbol] Key to check
+        # @return [Boolean] true if key exists
+        def cable_data_has?(data, key)
+          key_s = key.to_s
+          `#{data}.hasOwnProperty(#{key_s})`
+        end
+
+        # Get data type from received data (for routing actions)
+        # @param data [Native] Received data object
+        # @param type_key [String] Key containing type/action name
+        # @return [String, nil] Type value
+        def cable_data_type(data, type_key = "type")
+          cable_data(data, type_key)
+        end
+
+        # Route incoming data based on type/action
+        # @param data [Native] Received data object
+        # @param handlers [Hash] Map of type => handler proc
+        # @param type_key [String] Key containing type/action name
+        # @example
+        #   on_cable_received(subscription) do |data|
+        #     cable_route(data, {
+        #       "message" => -> { handle_message(data) },
+        #       "typing" => -> { handle_typing(data) },
+        #       "presence" => -> { handle_presence(data) }
+        #     })
+        #   end
+        def cable_route(data, handlers, type_key = "type")
+          data_type = cable_data_type(data, type_key)
+          return unless data_type
+          handler = handlers[data_type] || handlers[data_type.to_sym]
+          handler&.call
+        end
+
+        private
+
+        # Generate a unique key for subscription storage
+        def cable_subscription_key(channel_name, params)
+          "#{channel_name}:#{params.to_a.sort.map { |k, v| "#{k}=#{v}" }.join(',')}"
+        end
+
+        # Get the default (first) subscription
+        def default_subscription
+          return nil unless @_cable_subscriptions
+          @_cable_subscriptions.values.first
+        end
+      end
+    end
+  end
+end
+
+# Alias for backward compatibility
+ActionCableHelpers = OpalVite::Concerns::V1::ActionCableHelpers

data/opal/opal_vite/concerns/v1/debug_helpers.rb

@@ -0,0 +1,234 @@
+# backtick_javascript: true
+
+module OpalVite
+  module Concerns
+    module V1
+      # DebugHelpers concern - provides debugging utilities for Opal applications
+      # Outputs structured debug information to browser console
+      module DebugHelpers
+        # Log a debug message with optional data
+        # @param message [String] The message to log
+        # @param data [Object] Optional data to include
+        def debug_log(message, data = nil)
+          return unless debug_enabled?
+
+          if data
+            `console.log('[DEBUG] ' + #{message}, #{data.to_n})`
+          else
+            `console.log('[DEBUG] ' + #{message})`
+          end
+        end
+
+        # Log a warning message
+        # @param message [String] The warning message
+        # @param data [Object] Optional data to include
+        def debug_warn(message, data = nil)
+          return unless debug_enabled?
+
+          if data
+            `console.warn('[WARN] ' + #{message}, #{data.to_n})`
+          else
+            `console.warn('[WARN] ' + #{message})`
+          end
+        end
+
+        # Log an error message
+        # @param message [String] The error message
+        # @param error [Object] Optional error object or data
+        def debug_error(message, error = nil)
+          if error
+            `console.error('[ERROR] ' + #{message}, #{error.to_n})`
+          else
+            `console.error('[ERROR] ' + #{message})`
+          end
+        end
+
+        # Log a group of related debug messages
+        # @param label [String] Group label
+        # @yield Block containing debug_log calls
+        def debug_group(label)
+          return yield unless debug_enabled?
+
+          `console.group('[DEBUG] ' + #{label})`
+          yield
+          `console.groupEnd()`
+        end
+
+        # Log a collapsed group of related debug messages
+        # @param label [String] Group label
+        # @yield Block containing debug_log calls
+        def debug_group_collapsed(label)
+          return yield unless debug_enabled?
+
+          `console.groupCollapsed('[DEBUG] ' + #{label})`
+          yield
+          `console.groupEnd()`
+        end
+
+        # Start a performance timer
+        # @param label [String] Timer label
+        def debug_time(label)
+          return unless debug_enabled?
+          `console.time('[TIMER] ' + #{label})`
+        end
+
+        # End a performance timer and log the elapsed time
+        # @param label [String] Timer label (must match the one used in debug_time)
+        def debug_time_end(label)
+          return unless debug_enabled?
+          `console.timeEnd('[TIMER] ' + #{label})`
+        end
+
+        # Log a table of data (useful for arrays/objects)
+        # @param data [Array, Hash] Data to display as table
+        def debug_table(data)
+          return unless debug_enabled?
+          `console.table(#{data.to_n})`
+        end
+
+        # Log object inspection with Ruby-style formatting
+        # @param obj [Object] Object to inspect
+        # @param label [String] Optional label
+        def debug_inspect(obj, label = nil)
+          return unless debug_enabled?
+
+          inspected = obj.inspect
+          if label
+            `console.log('[INSPECT] ' + #{label} + ':', #{inspected})`
+          else
+            `console.log('[INSPECT]', #{inspected})`
+          end
+        end
+
+        # Log the current call stack
+        # @param message [String] Optional message
+        def debug_trace(message = nil)
+          return unless debug_enabled?
+
+          if message
+            `console.trace('[TRACE] ' + #{message})`
+          else
+            `console.trace('[TRACE]')`
+          end
+        end
+
+        # Assert a condition and log error if false
+        # @param condition [Boolean] Condition to check
+        # @param message [String] Message to show if assertion fails
+        def debug_assert(condition, message = 'Assertion failed')
+          `console.assert(#{condition}, '[ASSERT] ' + #{message})`
+        end
+
+        # Count and log how many times this is called with the given label
+        # @param label [String] Counter label
+        def debug_count(label = 'default')
+          return unless debug_enabled?
+          `console.count('[COUNT] ' + #{label})`
+        end
+
+        # Reset the counter for the given label
+        # @param label [String] Counter label
+        def debug_count_reset(label = 'default')
+          return unless debug_enabled?
+          `console.countReset('[COUNT] ' + #{label})`
+        end
+
+        # Check if debugging is enabled
+        # Override this method to control debug output
+        # @return [Boolean] true if debugging is enabled
+        def debug_enabled?
+          # Check for debug flag in multiple places
+          return @debug_enabled unless @debug_enabled.nil?
+
+          # Check window.OPAL_DEBUG or localStorage debug setting
+          @debug_enabled = `
+            (typeof window !== 'undefined' &&
+              (window.OPAL_DEBUG === true ||
+               (typeof localStorage !== 'undefined' &&
+                localStorage.getItem('opal_debug') === 'true')))
+          `
+        end
+
+        # Enable debugging
+        def debug_enable!
+          @debug_enabled = true
+          `
+            if (typeof window !== 'undefined') {
+              window.OPAL_DEBUG = true;
+              if (typeof localStorage !== 'undefined') {
+                localStorage.setItem('opal_debug', 'true');
+              }
+            }
+          `
+          debug_log('Debug mode enabled')
+        end
+
+        # Disable debugging
+        def debug_disable!
+          debug_log('Debug mode disabled')
+          @debug_enabled = false
+          `
+            if (typeof window !== 'undefined') {
+              window.OPAL_DEBUG = false;
+              if (typeof localStorage !== 'undefined') {
+                localStorage.removeItem('opal_debug');
+              }
+            }
+          `
+        end
+
+        # Measure execution time of a block
+        # @param label [String] Label for the measurement
+        # @yield Block to measure
+        # @return [Object] Return value of the block
+        def debug_measure(label)
+          return yield unless debug_enabled?
+
+          start_time = `performance.now()`
+          result = yield
+          end_time = `performance.now()`
+          duration = end_time - start_time
+
+          `console.log('[PERF] ' + #{label} + ': ' + #{duration.round(2)} + 'ms')`
+          result
+        end
+
+        # Log Stimulus controller connection info
+        # @param controller [Object] Stimulus controller instance
+        def debug_stimulus_connect(controller = nil)
+          return unless debug_enabled?
+
+          ctrl = controller || self
+          name = ctrl.class.respond_to?(:stimulus_name) ? ctrl.class.stimulus_name : ctrl.class.name
+          `console.log('[STIMULUS] Connected:', #{name})`
+        end
+
+        # Log Stimulus controller disconnection info
+        # @param controller [Object] Stimulus controller instance
+        def debug_stimulus_disconnect(controller = nil)
+          return unless debug_enabled?
+
+          ctrl = controller || self
+          name = ctrl.class.respond_to?(:stimulus_name) ? ctrl.class.stimulus_name : ctrl.class.name
+          `console.log('[STIMULUS] Disconnected:', #{name})`
+        end
+
+        # Log Stimulus action info
+        # @param action_name [String] Name of the action
+        # @param event [Object] Event object
+        def debug_stimulus_action(action_name, event = nil)
+          return unless debug_enabled?
+
+          if event
+            `console.log('[STIMULUS] Action:', #{action_name}, 'Event:', #{event.to_n})`
+          else
+            `console.log('[STIMULUS] Action:', #{action_name})`
+          end
+        end
+      end
+    end
+  end
+end
+
+# Alias for backward compatibility
+DebugHelpers = OpalVite::Concerns::V1::DebugHelpers

data/opal/opal_vite/concerns/v1/turbo_helpers.rb

@@ -0,0 +1,472 @@
+# backtick_javascript: true
+
+module OpalVite
+  module Concerns
+    module V1
+      # TurboHelpers - Ruby-friendly DSL for Hotwire Turbo integration
+      #
+      # This module provides methods for interacting with Turbo Drive, Frames, and Streams
+      # from Opal/Stimulus controllers.
+      #
+      # Prerequisites:
+      # - @hotwired/turbo package must be installed (npm install @hotwired/turbo)
+      # - Turbo must be imported in your JavaScript entry point
+      #
+      # Usage:
+      #   # In your main.js:
+      #   import * as Turbo from "@hotwired/turbo"
+      #   window.Turbo = Turbo
+      #
+      #   # In your Opal controller:
+      #   class NavigationController < StimulusController
+      #     include OpalVite::Concerns::V1::TurboHelpers
+      #
+      #     def navigate_to(event)
+      #       turbo_visit("/dashboard")
+      #     end
+      #
+      #     def refresh_frame
+      #       reload_turbo_frame("notifications")
+      #     end
+      #   end
+      module TurboHelpers
+        # ===== Turbo Drive =====
+
+        # Navigate to a URL using Turbo Drive
+        # @param url [String] URL to navigate to
+        # @param options [Hash] Visit options
+        # @option options [String] :action ("advance") "advance", "replace", or "restore"
+        # @option options [String] :frame Target frame ID (for frame navigation)
+        # @example
+        #   turbo_visit("/users/1")
+        #   turbo_visit("/login", action: "replace")
+        #   turbo_visit("/modal-content", frame: "modal")
+        def turbo_visit(url, options = {})
+          native_options = options.to_n
+          if options.empty?
+            `window.Turbo.visit(#{url})`
+          else
+            `window.Turbo.visit(#{url}, #{native_options})`
+          end
+        end
+
+        # Navigate to a URL replacing the current history entry
+        # @param url [String] URL to navigate to
+        def turbo_replace(url)
+          turbo_visit(url, action: "replace")
+        end
+
+        # Clear the Turbo Drive cache
+        def turbo_clear_cache
+          `window.Turbo.cache.clear()`
+        end
+
+        # Enable Turbo Drive (if previously disabled)
+        def turbo_enable
+          `document.documentElement.removeAttribute('data-turbo')`
+        end
+
+        # Disable Turbo Drive globally
+        def turbo_disable
+          `document.documentElement.setAttribute('data-turbo', 'false')`
+        end
+
+        # Check if Turbo Drive is enabled
+        # @return [Boolean] true if enabled
+        def turbo_enabled?
+          `document.documentElement.getAttribute('data-turbo') !== 'false'`
+        end
+
+        # Set Turbo Drive progress bar delay
+        # @param delay [Integer] Delay in milliseconds
+        def turbo_progress_delay(delay)
+          `window.Turbo.setProgressBarDelay(#{delay})`
+        end
+
+        # ===== Turbo Frames =====
+
+        # Get a Turbo Frame element by ID
+        # @param frame_id [String] Frame ID
+        # @return [Native, nil] Frame element or nil
+        def get_turbo_frame(frame_id)
+          frame = `document.querySelector('turbo-frame#' + #{frame_id})`
+          `#{frame} === null` ? nil : frame
+        end
+
+        # Reload a Turbo Frame
+        # @param frame_id [String] Frame ID to reload
+        # @param url [String, nil] Optional URL to load (uses src attribute if nil)
+        def reload_turbo_frame(frame_id, url = nil)
+          frame = get_turbo_frame(frame_id)
+          return unless frame
+
+          if url
+            `#{frame}.src = #{url}`
+          else
+            # Trigger reload by re-setting src
+            current_src = `#{frame}.src`
+            `#{frame}.src = #{current_src}`
+          end
+        end
+
+        # Set the src attribute of a Turbo Frame
+        # @param frame_id [String] Frame ID
+        # @param url [String] URL to load
+        def set_frame_src(frame_id, url)
+          frame = get_turbo_frame(frame_id)
+          `#{frame}.src = #{url}` if frame
+        end
+
+        # Disable a Turbo Frame (prevent loading)
+        # @param frame_id [String] Frame ID
+        def disable_turbo_frame(frame_id)
+          frame = get_turbo_frame(frame_id)
+          `#{frame}.setAttribute('disabled', '')` if frame
+        end
+
+        # Enable a Turbo Frame
+        # @param frame_id [String] Frame ID
+        def enable_turbo_frame(frame_id)
+          frame = get_turbo_frame(frame_id)
+          `#{frame}.removeAttribute('disabled')` if frame
+        end
+
+        # Check if a Turbo Frame is loading
+        # @param frame_id [String] Frame ID
+        # @return [Boolean] true if loading
+        def frame_loading?(frame_id)
+          frame = get_turbo_frame(frame_id)
+          return false unless frame
+          `#{frame}.hasAttribute('busy')`
+        end
+
+        # Wait for a Turbo Frame to finish loading
+        # @param frame_id [String] Frame ID
+        # @yield Block to execute when loaded
+        def on_frame_loaded(frame_id, &block)
+          frame = get_turbo_frame(frame_id)
+          return unless frame
+
+          if frame_loading?(frame_id)
+            `#{frame}.addEventListener('turbo:frame-load', function handler() {
+              #{frame}.removeEventListener('turbo:frame-load', handler);
+              #{block.call};
+            })`
+          else
+            block.call
+          end
+        end
+
+        # Get the target frame from current event
+        # @return [Native, nil] Frame element from event
+        def event_turbo_frame
+          `event.target.closest('turbo-frame')`
+        end
+
+        # ===== Turbo Streams =====
+
+        # Render a Turbo Stream action
+        # @param action [Symbol, String] Stream action (:append, :prepend, :replace, :update, :remove, :before, :after)
+        # @param target [String] Target element ID
+        # @param html [String] HTML content (not needed for :remove)
+        # @example
+        #   turbo_stream(:append, "messages", "<div>New message</div>")
+        #   turbo_stream(:remove, "message_1")
+        def turbo_stream(action, target, html = nil)
+          action_s = action.to_s
+          template_content = html ? "<template>#{html}</template>" : ""
+
+          stream_html = %{<turbo-stream action="#{action_s}" target="#{target}">#{template_content}</turbo-stream>}
+          render_turbo_stream(stream_html)
+        end
+
+        # Render raw Turbo Stream HTML
+        # @param stream_html [String] Full turbo-stream element HTML
+        def render_turbo_stream(stream_html)
+          `window.Turbo.renderStreamMessage(#{stream_html})`
+        end
+
+        # Append content to target element via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to append
+        def turbo_append(target, html)
+          turbo_stream(:append, target, html)
+        end
+
+        # Prepend content to target element via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to prepend
+        def turbo_prepend(target, html)
+          turbo_stream(:prepend, target, html)
+        end
+
+        # Replace target element via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to replace with
+        def turbo_replace_element(target, html)
+          turbo_stream(:replace, target, html)
+        end
+
+        # Update target element's content via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to update with
+        def turbo_update(target, html)
+          turbo_stream(:update, target, html)
+        end
+
+        # Remove target element via Turbo Stream
+        # @param target [String] Target element ID
+        def turbo_remove(target)
+          turbo_stream(:remove, target)
+        end
+
+        # Insert content before target element via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to insert
+        def turbo_before(target, html)
+          turbo_stream(:before, target, html)
+        end
+
+        # Insert content after target element via Turbo Stream
+        # @param target [String] Target element ID
+        # @param html [String] HTML content to insert
+        def turbo_after(target, html)
+          turbo_stream(:after, target, html)
+        end
+
+        # Create multiple Turbo Stream operations
+        # @yield Block that builds stream operations
+        # @example
+        #   turbo_streams do |s|
+        #     s.append("messages", "<div>Message 1</div>")
+        #     s.prepend("notifications", "<div>Alert!</div>")
+        #     s.remove("loading-indicator")
+        #   end
+        def turbo_streams(&block)
+          builder = TurboStreamBuilder.new
+          block.call(builder)
+          builder.render
+        end
+
+        # ===== Turbo Events =====
+
+        # Listen for Turbo Drive events
+        # @param event_name [String] Event name (without 'turbo:' prefix)
+        # @yield [event] Block to execute when event fires
+        # @example
+        #   on_turbo("before-visit") { |e| validate_form }
+        #   on_turbo("load") { init_components }
+        def on_turbo(event_name, &block)
+          full_name = event_name.start_with?("turbo:") ? event_name : "turbo:#{event_name}"
+          `document.addEventListener(#{full_name}, function(event) { #{block.call(`event`)} })`
+        end
+
+        # Listen for turbo:before-visit - cancel navigation
+        # @yield [event] Block to execute (call event.preventDefault to cancel)
+        def on_turbo_before_visit(&block)
+          on_turbo("before-visit", &block)
+        end
+
+        # Listen for turbo:visit - navigation started
+        # @yield [event] Block to execute
+        def on_turbo_visit(&block)
+          on_turbo("visit", &block)
+        end
+
+        # Listen for turbo:load - page fully loaded
+        # @yield [event] Block to execute
+        def on_turbo_load(&block)
+          on_turbo("load", &block)
+        end
+
+        # Listen for turbo:render - page rendered
+        # @yield [event] Block to execute
+        def on_turbo_render(&block)
+          on_turbo("render", &block)
+        end
+
+        # Listen for turbo:before-fetch-request - before fetch
+        # @yield [event] Block to execute
+        def on_turbo_before_fetch(&block)
+          on_turbo("before-fetch-request", &block)
+        end
+
+        # Listen for turbo:submit-start - form submission started
+        # @yield [event] Block to execute
+        def on_turbo_submit_start(&block)
+          on_turbo("submit-start", &block)
+        end
+
+        # Listen for turbo:submit-end - form submission ended
+        # @yield [event] Block to execute
+        def on_turbo_submit_end(&block)
+          on_turbo("submit-end", &block)
+        end
+
+        # Listen for turbo:frame-load - frame loaded
+        # @yield [event] Block to execute
+        def on_turbo_frame_load(&block)
+          on_turbo("frame-load", &block)
+        end
+
+        # Listen for turbo:before-stream-render - before stream renders
+        # @yield [event] Block to execute
+        def on_turbo_before_stream(&block)
+          on_turbo("before-stream-render", &block)
+        end
+
+        # ===== Form Helpers =====
+
+        # Submit a form via Turbo
+        # @param form_element [Native] Form element
+        def turbo_submit(form_element)
+          el = form_element.respond_to?(:to_n) ? form_element.to_n : form_element
+          `#{el}.requestSubmit()`
+        end
+
+        # Submit a form with custom target frame
+        # @param form_element [Native] Form element
+        # @param frame_id [String] Target frame ID
+        def turbo_submit_to_frame(form_element, frame_id)
+          el = form_element.respond_to?(:to_n) ? form_element.to_n : form_element
+          `#{el}.setAttribute('data-turbo-frame', #{frame_id})`
+          `#{el}.requestSubmit()`
+        end
+
+        # Disable Turbo on a specific form
+        # @param form_element [Native] Form element
+        def disable_turbo_form(form_element)
+          el = form_element.respond_to?(:to_n) ? form_element.to_n : form_element
+          `#{el}.setAttribute('data-turbo', 'false')`
+        end
+
+        # Enable Turbo on a specific form
+        # @param form_element [Native] Form element
+        def enable_turbo_form(form_element)
+          el = form_element.respond_to?(:to_n) ? form_element.to_n : form_element
+          `#{el}.removeAttribute('data-turbo')`
+        end
+
+        # ===== Stream over SSE =====
+
+        # Connect to a Turbo Stream over SSE endpoint
+        # @param url [String] SSE endpoint URL
+        # @return [Native] EventSource instance
+        # @example
+        #   source = turbo_stream_from("/notifications/stream")
+        #   # Turbo will automatically process incoming streams
+        def turbo_stream_from(url)
+          `window.Turbo.connectStreamSource(new EventSource(#{url}))`
+        end
+
+        # Disconnect a Turbo Stream SSE source
+        # @param source [Native] EventSource to disconnect
+        def turbo_stream_disconnect(source)
+          `window.Turbo.disconnectStreamSource(#{source})`
+          `#{source}.close()`
+        end
+
+        # ===== Confirmation Dialog =====
+
+        # Set custom Turbo confirmation handler
+        # @yield [message, element, submitter] Block that returns true/false
+        # @example
+        #   turbo_confirm_method do |message, element, submitter|
+        #     `window.confirm(message)`
+        #   end
+        def turbo_confirm_method(&block)
+          `window.Turbo.setConfirmMethod(function(message, element, submitter) {
+            return #{block.call(`message`, `element`, `submitter`)};
+          })`
+        end
+
+        # ===== Morphing (Turbo 8+) =====
+
+        # Refresh the page using Turbo's morph feature
+        # @param options [Hash] Refresh options
+        # @option options [Boolean] :request_id Custom request ID
+        def turbo_refresh(options = {})
+          if options.empty?
+            `window.Turbo.visit(window.location.href, { action: 'replace' })`
+          else
+            native_options = options.merge(action: "replace").to_n
+            `window.Turbo.visit(window.location.href, #{native_options})`
+          end
+        end
+
+        # ===== Utility Methods =====
+
+        # Check if Turbo is available
+        # @return [Boolean] true if Turbo is loaded
+        def turbo_available?
+          `typeof window.Turbo !== 'undefined'`
+        end
+
+        # Get current Turbo Drive visit location
+        # @return [String, nil] Current URL or nil
+        def turbo_current_url
+          `window.Turbo.navigator.location?.href`
+        end
+
+        # Cancel a pending Turbo visit
+        def turbo_cancel_visit
+          `window.Turbo.navigator.stop()`
+        end
+
+        # Add loading class during Turbo navigation
+        # @param element [Native] Element to add class to
+        # @param class_name [String] Class name to toggle
+        def turbo_loading_class(element, class_name = "turbo-loading")
+          el = element.respond_to?(:to_n) ? element.to_n : element
+
+          on_turbo("before-fetch-request") { `#{el}.classList.add(#{class_name})` }
+          on_turbo("before-fetch-response") { `#{el}.classList.remove(#{class_name})` }
+        end
+      end
+
+      # Builder for creating multiple Turbo Stream operations
+      class TurboStreamBuilder
+        def initialize
+          @streams = []
+        end
+
+        def append(target, html)
+          @streams << %{<turbo-stream action="append" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def prepend(target, html)
+          @streams << %{<turbo-stream action="prepend" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def replace(target, html)
+          @streams << %{<turbo-stream action="replace" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def update(target, html)
+          @streams << %{<turbo-stream action="update" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def remove(target)
+          @streams << %{<turbo-stream action="remove" target="#{target}"></turbo-stream>}
+        end
+
+        def before(target, html)
+          @streams << %{<turbo-stream action="before" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def after(target, html)
+          @streams << %{<turbo-stream action="after" target="#{target}"><template>#{html}</template></turbo-stream>}
+        end
+
+        def render
+          @streams.each do |stream_html|
+            `window.Turbo.renderStreamMessage(#{stream_html})`
+          end
+        end
+      end
+    end
+  end
+end
+
+# Alias for backward compatibility
+TurboHelpers = OpalVite::Concerns::V1::TurboHelpers

data/opal/opal_vite/concerns/v1.rb

@@ -8,3 +8,6 @@ require 'opal_vite/concerns/v1/vue_helpers'
 require 'opal_vite/concerns/v1/react_helpers'
 require 'opal_vite/concerns/v1/uri_helpers'
 require 'opal_vite/concerns/v1/base64_helpers'
+require 'opal_vite/concerns/v1/debug_helpers'
+require 'opal_vite/concerns/v1/action_cable_helpers'
+require 'opal_vite/concerns/v1/turbo_helpers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opal-vite
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.4
 platform: ruby
 authors:
 - stofu1234
@@ -120,13 +120,16 @@ files:
 - opal/opal_vite/concerns/storable.rb
 - opal/opal_vite/concerns/toastable.rb
 - opal/opal_vite/concerns/v1.rb
+- opal/opal_vite/concerns/v1/action_cable_helpers.rb
 - opal/opal_vite/concerns/v1/base64_helpers.rb
+- opal/opal_vite/concerns/v1/debug_helpers.rb
 - opal/opal_vite/concerns/v1/dom_helpers.rb
 - opal/opal_vite/concerns/v1/js_proxy_ex.rb
 - opal/opal_vite/concerns/v1/react_helpers.rb
 - opal/opal_vite/concerns/v1/stimulus_helpers.rb
 - opal/opal_vite/concerns/v1/storable.rb
 - opal/opal_vite/concerns/v1/toastable.rb
+- opal/opal_vite/concerns/v1/turbo_helpers.rb
 - opal/opal_vite/concerns/v1/uri_helpers.rb
 - opal/opal_vite/concerns/v1/vue_helpers.rb
 - opal/opal_vite/concerns/vue_helpers.rb