opal-vite 0.2.19 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6fe0d4b79fe6f2f19296adc07c985911e700798992b4db56ee884b6fd43d72
-  data.tar.gz: 3d0543a0e7bd1d719a85f68c0429a2b8bbc8c7b67f84b85c115a88283684f28d
+  metadata.gz: 8736c0cccd990adbc7f614480718ba0bab767f94ad281f508b0a01b9898deb3d
+  data.tar.gz: 93ab376b58edb586aed577d0d4a19011f7f84660c62eebffe418eccb4b9b1e73
 SHA512:
-  metadata.gz: f576e967b72b0b4df43f54e7be1d02ad7e10a4623230cc4a57ef17fb64ede2763e11eea0954756a36b53e64a7c297347c8b48ec9019b144964e8df3cea0944eb
-  data.tar.gz: 7e8b1dae798ceea304b01df2ee82b0943f59f2b93657084f79ba886c419bbba3b1cebfede142df91172abebc20c5a609ee4563b9e926fe4483fff00b8bbb28fb
+  metadata.gz: 1c0d8a02384a2e1f958d2a0ce62f66fe8f63db8c87cbe709089e04ca9441e2d37a9a41b860170cdb2ca8f24467a79ce12b2587d1312e0d59dd22e75020429911
+  data.tar.gz: 7aae2b96e735993cfd583cdc98ea0ad6bbd49110ef63209b17f6f49e614bf7edc0d1948612f40522ed9aa6e1839fa6e02731a7f6764ef269b3b61c17cee5c2b3

data/lib/opal/vite/version.rb

@@ -1,5 +1,5 @@
 module Opal
   module Vite
-    VERSION = "0.2.19"
+    VERSION = "0.3.1"
   end
 end

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

@@ -0,0 +1,275 @@
+# backtick_javascript: true
+
+module OpalVite
+  module Concerns
+    module V1
+      # Base64Helpers - provides Base64 encoding/decoding utilities
+      #
+      # This module wraps JavaScript's btoa/atob and provides additional
+      # utilities for Base64 operations commonly needed in web applications.
+      #
+      # @example Basic usage
+      #   class MyController < StimulusController
+      #     include OpalVite::Concerns::V1::Base64Helpers
+      #
+      #     def connect
+      #       encoded = base64_encode("Hello, World!")
+      #       puts encoded  # => "SGVsbG8sIFdvcmxkIQ=="
+      #
+      #       decoded = base64_decode(encoded)
+      #       puts decoded  # => "Hello, World!"
+      #     end
+      #   end
+      #
+      module Base64Helpers
+        # ===== Basic Encoding/Decoding =====
+
+        # Encode a string to Base64
+        # @param str [String] String to encode
+        # @return [String] Base64 encoded string
+        def base64_encode(str)
+          `btoa(#{str})`
+        rescue
+          nil
+        end
+
+        # Decode a Base64 string
+        # @param str [String] Base64 string to decode
+        # @return [String] Decoded string
+        def base64_decode(str)
+          `atob(#{str})`
+        rescue
+          nil
+        end
+
+        # ===== URL-Safe Base64 =====
+
+        # Encode a string to URL-safe Base64
+        # @param str [String] String to encode
+        # @return [String] URL-safe Base64 encoded string
+        def base64_encode_urlsafe(str)
+          encoded = base64_encode(str)
+          return nil unless encoded
+
+          # Replace + with -, / with _, and remove =
+          encoded.gsub('+', '-').gsub('/', '_').gsub('=', '')
+        end
+
+        # Decode a URL-safe Base64 string
+        # @param str [String] URL-safe Base64 string to decode
+        # @return [String] Decoded string
+        def base64_decode_urlsafe(str)
+          # Restore standard Base64 characters
+          standard = str.gsub('-', '+').gsub('_', '/')
+
+          # Add padding if needed
+          case standard.length % 4
+          when 2
+            standard += '=='
+          when 3
+            standard += '='
+          end
+
+          base64_decode(standard)
+        end
+
+        # ===== Unicode Support =====
+
+        # Encode a Unicode string to Base64
+        # @param str [String] Unicode string to encode
+        # @return [String] Base64 encoded string
+        def base64_encode_unicode(str)
+          # Convert to UTF-8 bytes, then encode
+          `btoa(unescape(encodeURIComponent(#{str})))`
+        rescue
+          nil
+        end
+
+        # Decode a Base64 string to Unicode
+        # @param str [String] Base64 string to decode
+        # @return [String] Decoded Unicode string
+        def base64_decode_unicode(str)
+          `decodeURIComponent(escape(atob(#{str})))`
+        rescue
+          nil
+        end
+
+        # ===== Binary Data (ArrayBuffer/Uint8Array) =====
+
+        # Encode an ArrayBuffer or Uint8Array to Base64
+        # @param buffer [Native] ArrayBuffer or Uint8Array
+        # @return [String] Base64 encoded string
+        def base64_encode_buffer(buffer)
+          `
+            var bytes = new Uint8Array(#{buffer});
+            var binary = '';
+            for (var i = 0; i < bytes.byteLength; i++) {
+              binary += String.fromCharCode(bytes[i]);
+            }
+            return btoa(binary);
+          `
+        rescue
+          nil
+        end
+
+        # Decode a Base64 string to Uint8Array
+        # @param str [String] Base64 string to decode
+        # @return [Native] Uint8Array
+        def base64_decode_to_buffer(str)
+          `
+            var binary = atob(#{str});
+            var bytes = new Uint8Array(binary.length);
+            for (var i = 0; i < binary.length; i++) {
+              bytes[i] = binary.charCodeAt(i);
+            }
+            return bytes;
+          `
+        rescue
+          nil
+        end
+
+        # ===== Data URL Support =====
+
+        # Create a data URL from content
+        # @param content [String] Content to encode
+        # @param mime_type [String] MIME type (default: "text/plain")
+        # @return [String] Data URL
+        def to_data_url(content, mime_type = 'text/plain')
+          encoded = base64_encode_unicode(content)
+          return nil unless encoded
+
+          "data:#{mime_type};base64,#{encoded}"
+        end
+
+        # Parse a data URL
+        # @param data_url [String] Data URL
+        # @return [Hash, nil] Hash with :mime_type and :data keys, or nil
+        def parse_data_url(data_url)
+          return nil unless data_url.to_s.start_with?('data:')
+
+          match = `#{data_url}.match(/^data:([^;]+);base64,(.+)$/)`
+          return nil if `#{match} === null`
+
+          {
+            mime_type: `#{match}[1]`,
+            data: base64_decode_unicode(`#{match}[2]`)
+          }
+        end
+
+        # ===== Authentication Helpers =====
+
+        # Create a Basic Auth header value
+        # @param username [String] Username
+        # @param password [String] Password
+        # @return [String] Basic auth header value
+        def basic_auth_header(username, password)
+          credentials = "#{username}:#{password}"
+          encoded = base64_encode(credentials)
+          "Basic #{encoded}"
+        end
+
+        # Parse a Basic Auth header value
+        # @param header [String] Authorization header value
+        # @return [Hash, nil] Hash with :username and :password keys, or nil
+        def parse_basic_auth(header)
+          return nil unless header.to_s.start_with?('Basic ')
+
+          encoded = header[6..-1]
+          decoded = base64_decode(encoded)
+          return nil unless decoded
+
+          parts = decoded.split(':', 2)
+          return nil if parts.length != 2
+
+          {
+            username: parts[0],
+            password: parts[1]
+          }
+        end
+
+        # ===== JWT Helpers =====
+
+        # Decode a JWT payload (without verification)
+        # @param token [String] JWT token
+        # @return [Hash, nil] Decoded payload or nil
+        # @note This does NOT verify the signature - use only for reading claims
+        def decode_jwt_payload(token)
+          parts = token.to_s.split('.')
+          return nil if parts.length != 3
+
+          payload_base64 = parts[1]
+          payload_json = base64_decode_urlsafe(payload_base64)
+          return nil unless payload_json
+
+          `JSON.parse(#{payload_json})`
+        rescue
+          nil
+        end
+
+        # Check if a JWT is expired
+        # @param token [String] JWT token
+        # @return [Boolean] True if expired
+        def jwt_expired?(token)
+          payload = decode_jwt_payload(token)
+          return true unless payload
+
+          exp = `#{payload}.exp`
+          return false if `#{exp} === undefined || #{exp} === null`
+
+          now = `Math.floor(Date.now() / 1000)`
+          `#{exp} < #{now}`
+        end
+
+        # Get JWT expiration time
+        # @param token [String] JWT token
+        # @return [Time, nil] Expiration time or nil
+        def jwt_expires_at(token)
+          payload = decode_jwt_payload(token)
+          return nil unless payload
+
+          exp = `#{payload}.exp`
+          return nil if `#{exp} === undefined || #{exp} === null`
+
+          # Convert Unix timestamp to Ruby-like time representation
+          `new Date(#{exp} * 1000)`
+        end
+
+        # ===== Utility Methods =====
+
+        # Check if a string is valid Base64
+        # @param str [String] String to check
+        # @return [Boolean] True if valid Base64
+        def valid_base64?(str)
+          return false if str.nil? || str.empty?
+
+          # Check for valid Base64 characters
+          `
+            var regex = /^[A-Za-z0-9+/]*={0,2}$/;
+            if (!regex.test(#{str})) return false;
+            if (#{str}.length % 4 !== 0) return false;
+            try {
+              atob(#{str});
+              return true;
+            } catch (e) {
+              return false;
+            }
+          `
+        end
+
+        # Get the decoded length of a Base64 string
+        # @param str [String] Base64 string
+        # @return [Integer] Decoded length in bytes
+        def base64_decoded_length(str)
+          return 0 if str.nil? || str.empty?
+
+          len = str.length
+          padding = str.end_with?('==') ? 2 : (str.end_with?('=') ? 1 : 0)
+          (len * 3 / 4) - padding
+        end
+      end
+    end
+  end
+end
+
+# Alias for convenience
+Base64Helpers = OpalVite::Concerns::V1::Base64Helpers

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

@@ -450,12 +450,7 @@ module OpalVite
       # @param name [String] Event name
       # @yield Block to execute when event fires
       def on_controller_event(name, &block)
-        `
-          const handler = #{block};
-          this.element.addEventListener(#{name}, function(e) {
-            handler(e);
-          });
-        `
+        `this.element.addEventListener(#{name}, #{block})`
       end
 
       # Get the current event's target element
@@ -1307,6 +1302,643 @@ module OpalVite
         `#{promise}.finally(#{block})`
       end
 
+      # ===== Stimulus Values API =====
+      # Access Stimulus values defined with `static values = { name: Type }`
+      # Note: These methods use "stimulus_value" prefix to avoid conflict with
+      # get_value(element) which gets an element's value attribute.
+
+      # Get a Stimulus value
+      # @param name [Symbol, String] Value name (e.g., :count, :url)
+      # @return [Object] The value (auto-converted by Stimulus based on type)
+      # @example
+      #   # With self.values = { count: :number, url: :string }
+      #   stimulus_value(:count)  # => 0
+      #   stimulus_value(:url)    # => "/api/items"
+      def stimulus_value(name)
+        prop_name = "#{camelize(name, false)}Value"
+        `this[#{prop_name}]`
+      end
+
+      # Set a Stimulus value
+      # @param name [Symbol, String] Value name
+      # @param value [Object] The value to set
+      # @example
+      #   set_stimulus_value(:count, 5)
+      #   set_stimulus_value(:items, [1, 2, 3])
+      def set_stimulus_value(name, value)
+        prop_name = "#{camelize(name, false)}Value"
+        native_value = value.respond_to?(:to_n) ? value.to_n : value
+        `this[#{prop_name}] = #{native_value}`
+      end
+
+      # Check if a Stimulus value exists (has data attribute)
+      # @param name [Symbol, String] Value name
+      # @return [Boolean] true if value's data attribute exists
+      # @example
+      #   if has_stimulus_value?(:api_url)
+      #     fetch_json(stimulus_value(:api_url)) { |data| ... }
+      #   end
+      def has_stimulus_value?(name)
+        prop_name = "has#{camelize(name)}Value"
+        `this[#{prop_name}]`
+      end
+
+      # Increment a numeric Stimulus value
+      # @param name [Symbol, String] Value name
+      # @param amount [Number] Amount to increment (default: 1)
+      def increment_stimulus_value(name, amount = 1)
+        set_stimulus_value(name, stimulus_value(name) + amount)
+      end
+
+      # Decrement a numeric Stimulus value
+      # @param name [Symbol, String] Value name
+      # @param amount [Number] Amount to decrement (default: 1)
+      def decrement_stimulus_value(name, amount = 1)
+        set_stimulus_value(name, stimulus_value(name) - amount)
+      end
+
+      # Toggle a boolean Stimulus value
+      # @param name [Symbol, String] Value name
+      def toggle_stimulus_value(name)
+        set_stimulus_value(name, !stimulus_value(name))
+      end
+
+      # ===== Stimulus CSS Classes API =====
+      # Access CSS classes defined with `static classes = [ "loading", "active" ]`
+
+      # Get a Stimulus CSS class (singular)
+      # @param name [Symbol, String] Class logical name
+      # @return [String] The CSS class name
+      # @example
+      #   # With static classes = [ "loading" ] and data-controller-loading-class="spinner"
+      #   get_class(:loading)  # => "spinner"
+      def get_class(name)
+        prop_name = "#{camelize(name, false)}Class"
+        `this[#{prop_name}]`
+      end
+
+      # Get all Stimulus CSS classes (plural, for space-separated values)
+      # @param name [Symbol, String] Class logical name
+      # @return [Array] Array of CSS class names
+      # @example
+      #   # With data-controller-loading-class="spinner bg-gray-500"
+      #   get_classes(:loading)  # => ["spinner", "bg-gray-500"]
+      def get_classes(name)
+        prop_name = "#{camelize(name, false)}Classes"
+        `Array.from(this[#{prop_name}] || [])`
+      end
+
+      # Check if a Stimulus CSS class is defined
+      # @param name [Symbol, String] Class logical name
+      # @return [Boolean] true if class data attribute exists
+      def has_class_definition?(name)
+        prop_name = "has#{camelize(name)}Class"
+        `this[#{prop_name}]`
+      end
+
+      # Apply a Stimulus CSS class to an element
+      # @param element [Native] DOM element
+      # @param name [Symbol, String] Class logical name
+      def apply_class(element, name)
+        el = to_native_element(element)
+        class_name = get_class(name)
+        `#{el}.classList.add(#{class_name})` if class_name
+      end
+
+      # Apply all Stimulus CSS classes to an element
+      # @param element [Native] DOM element
+      # @param name [Symbol, String] Class logical name
+      def apply_classes(element, name)
+        el = to_native_element(element)
+        classes = get_classes(name)
+        `#{el}.classList.add(...#{classes})` if classes
+      end
+
+      # Remove a Stimulus CSS class from an element
+      # @param element [Native] DOM element
+      # @param name [Symbol, String] Class logical name
+      def remove_applied_class(element, name)
+        el = to_native_element(element)
+        class_name = get_class(name)
+        `#{el}.classList.remove(#{class_name})` if class_name
+      end
+
+      # Remove all Stimulus CSS classes from an element
+      # @param element [Native] DOM element
+      # @param name [Symbol, String] Class logical name
+      def remove_applied_classes(element, name)
+        el = to_native_element(element)
+        classes = get_classes(name)
+        `#{el}.classList.remove(...#{classes})` if classes
+      end
+
+      # ===== Stimulus Outlets API =====
+      # Access outlets defined with `static outlets = [ "result" ]`
+
+      # Check if an outlet exists
+      # @param name [Symbol, String] Outlet identifier
+      # @return [Boolean] true if outlet is connected
+      # @example
+      #   if has_outlet?(:modal)
+      #     get_outlet(:modal).open
+      #   end
+      def has_outlet?(name)
+        prop_name = "has#{camelize(name)}Outlet"
+        `this[#{prop_name}]`
+      end
+
+      # Get a single outlet controller instance
+      # @param name [Symbol, String] Outlet identifier
+      # @return [Native] The outlet controller instance
+      # @note Throws error if outlet doesn't exist - use has_outlet? first
+      def get_outlet(name)
+        prop_name = "#{camelize(name, false)}Outlet"
+        `this[#{prop_name}]`
+      end
+
+      # Get all outlet controller instances
+      # @param name [Symbol, String] Outlet identifier
+      # @return [Array] Array of outlet controller instances
+      def get_outlets(name)
+        prop_name = "#{camelize(name, false)}Outlets"
+        `Array.from(this[#{prop_name}] || [])`
+      end
+
+      # Get a single outlet's element
+      # @param name [Symbol, String] Outlet identifier
+      # @return [Native] The outlet's controller element
+      # @note Throws error if outlet doesn't exist - use has_outlet? first
+      def get_outlet_element(name)
+        prop_name = "#{camelize(name, false)}OutletElement"
+        `this[#{prop_name}]`
+      end
+
+      # Get all outlet elements
+      # @param name [Symbol, String] Outlet identifier
+      # @return [Array] Array of outlet controller elements
+      def get_outlet_elements(name)
+        prop_name = "#{camelize(name, false)}OutletElements"
+        `Array.from(this[#{prop_name}] || [])`
+      end
+
+      # Call a method on an outlet controller
+      # @param name [Symbol, String] Outlet identifier
+      # @param method [Symbol, String] Method name to call
+      # @param args [Array] Arguments to pass
+      # @return [Object] Method return value
+      def call_outlet(name, method, *args)
+        return nil unless has_outlet?(name)
+        outlet = get_outlet(name)
+        js_call_on(outlet, method, *args)
+      end
+
+      # Call a method on all outlet controllers
+      # @param name [Symbol, String] Outlet identifier
+      # @param method [Symbol, String] Method name to call
+      # @param args [Array] Arguments to pass
+      def call_all_outlets(name, method, *args)
+        get_outlets(name).each do |outlet|
+          js_call_on(outlet, method, *args)
+        end
+      end
+
+      # ===== Stimulus dispatch() API =====
+      # Emit custom events with controller identifier prefix
+
+      # Dispatch a Stimulus-style custom event
+      # @param name [String] Event name (will be prefixed with controller identifier)
+      # @param detail [Hash] Event detail data
+      # @param target [Native, nil] Target element (default: controller element)
+      # @param prefix [String, nil] Custom prefix (default: controller identifier)
+      # @param bubbles [Boolean] Whether event bubbles (default: true)
+      # @param cancelable [Boolean] Whether event is cancelable (default: true)
+      # @return [Native] The dispatched event
+      # @example
+      #   # In a "clipboard" controller:
+      #   stimulus_dispatch("copied", detail: { content: text })
+      #   # Dispatches "clipboard:copied" event
+      def stimulus_dispatch(name, detail: {}, target: nil, prefix: nil, bubbles: true, cancelable: true)
+        native_detail = detail.respond_to?(:to_n) ? detail.to_n : detail
+        # Build options object, only including target/prefix if explicitly provided
+        # Note: Ruby nil becomes Opal.nil in JS (truthy), so we must check explicitly
+        options = `{ detail: #{native_detail}, bubbles: #{bubbles}, cancelable: #{cancelable} }`
+        `#{options}.target = #{target}` unless target.nil?
+        `#{options}.prefix = #{prefix}` unless prefix.nil?
+        `this.dispatch(#{name}, #{options})`
+      end
+
+      # Dispatch event and check if it was cancelled
+      # @param name [String] Event name
+      # @param detail [Hash] Event detail data
+      # @return [Boolean] true if event was NOT cancelled
+      def stimulus_dispatch_confirm(name, detail: {})
+        event = stimulus_dispatch(name, detail: detail, cancelable: true)
+        `!#{event}.defaultPrevented`
+      end
+
+      # ===== Stimulus Action Parameters API =====
+      # Access action parameters from data-[identifier]-[name]-param attributes
+
+      # Get all action parameters from the current event
+      # @return [Native] JavaScript object with all parameters
+      # @example
+      #   # <button data-action="item#delete" data-item-id-param="123">
+      #   def delete(event)
+      #     params = action_params  # => { id: 123 }
+      #   end
+      def action_params
+        `event.params || {}`
+      end
+
+      # Get a specific action parameter
+      # @param name [Symbol, String] Parameter name
+      # @return [Object] Parameter value (auto-typecast by Stimulus)
+      # @example
+      #   action_param(:id)   # => 123 (Number)
+      #   action_param(:url)  # => "/api/item" (String)
+      def action_param(name)
+        `(event.params || {})[#{name.to_s}]`
+      end
+
+      # Get action parameter as integer with default
+      # @param name [Symbol, String] Parameter name
+      # @param default [Integer] Default value if missing or NaN
+      # @return [Integer] Parameter value
+      def action_param_int(name, default = 0)
+        value = action_param(name)
+        result = parse_int(value)
+        is_nan?(result) ? default : result
+      end
+
+      # Get action parameter as boolean
+      # @param name [Symbol, String] Parameter name
+      # @return [Boolean] Parameter value
+      def action_param_bool(name)
+        value = action_param(name)
+        `!!#{value} && #{value} !== "false" && #{value} !== "0"`
+      end
+
+      # Check if an action parameter exists
+      # @param name [Symbol, String] Parameter name
+      # @return [Boolean] true if parameter exists
+      def has_action_param?(name)
+        `(event.params || {}).hasOwnProperty(#{name.to_s})`
+      end
+
+      # ===== Stimulus Controller Access =====
+      # Access controller properties and other controllers
+
+      # Get the controller's application instance
+      # @return [Native] Stimulus Application
+      def this_application
+        `this.application`
+      end
+
+      # Get the controller's identifier
+      # @return [String] Controller identifier (e.g., "modal", "tabs")
+      def this_identifier
+        `this.identifier`
+      end
+
+      # Get the controller's element
+      # @return [Native] Controller's root element
+      def this_element
+        `this.element`
+      end
+
+      # Get another controller instance by element and identifier
+      # @param element [Native] DOM element with the controller
+      # @param identifier [String] Controller identifier
+      # @return [Native, nil] Controller instance or nil
+      # @example
+      #   modal = get_controller(modal_element, "modal")
+      #   modal.open if modal
+      def get_controller(element, identifier)
+        el = to_native_element(element)
+        `this.application.getControllerForElementAndIdentifier(#{el}, #{identifier})`
+      end
+
+      # Get all controllers of a type within an element's scope
+      # @param element [Native] Container element
+      # @param identifier [String] Controller identifier
+      # @return [Array] Array of controller instances
+      def get_controllers(element, identifier)
+        el = to_native_element(element)
+        `Array.from(#{el}.querySelectorAll('[data-controller~="' + #{identifier} + '"]'))
+          .map(el => this.application.getControllerForElementAndIdentifier(el, #{identifier}))
+          .filter(c => c !== null)`
+      end
+
+      # ===== Stimulus Scope Helpers =====
+
+      # Get the controller's scope (element and descendants, excluding nested controllers)
+      # @return [Native] Controller's scope element
+      def this_scope
+        `this.scope.element`
+      end
+
+      # Check if an element is within this controller's scope
+      # @param element [Native] Element to check
+      # @return [Boolean] true if element is in scope
+      def in_scope?(element)
+        el = to_native_element(element)
+        `this.element.contains(#{el})`
+      end
+
+      # ===== Debounce/Throttle Utilities =====
+
+      # Create a debounced version of a block
+      # @param wait [Integer] Milliseconds to wait
+      # @yield Block to debounce
+      # @return [Native] Debounced function
+      def debounce(wait, &block)
+        `
+          var timeout;
+          return function(...args) {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => #{block.call}, wait);
+          };
+        `
+      end
+
+      # Create a throttled version of a block
+      # @param wait [Integer] Milliseconds between calls
+      # @yield Block to throttle
+      # @return [Native] Throttled function
+      def throttle(wait, &block)
+        `
+          var lastTime = 0;
+          return function(...args) {
+            var now = Date.now();
+            if (now - lastTime >= #{wait}) {
+              lastTime = now;
+              #{block.call};
+            }
+          };
+        `
+      end
+
+      # Debounce a method call
+      # @param wait [Integer] Milliseconds to wait
+      # @param key [String] Unique key for this debounce
+      # @yield Block to execute after debounce
+      def debounced(wait, key = 'default', &block)
+        @_debounce_timers ||= {}
+        timer_key = "_debounce_#{key}"
+
+        `clearTimeout(#{@_debounce_timers[timer_key]})`
+        @_debounce_timers[timer_key] = `setTimeout(function() { #{block.call} }, #{wait})`
+      end
+
+      # Throttle a method call
+      # @param wait [Integer] Milliseconds between calls
+      # @param key [String] Unique key for this throttle
+      # @yield Block to execute if not throttled
+      def throttled(wait, key = 'default', &block)
+        @_throttle_times ||= {}
+        time_key = "_throttle_#{key}"
+
+        now = `Date.now()`
+        last_time = @_throttle_times[time_key] || 0
+
+        if `#{now} - #{last_time} >= #{wait}`
+          @_throttle_times[time_key] = now
+          block.call
+        end
+      end
+
+      # ===== Clipboard Utilities =====
+
+      # Copy text to clipboard
+      # @param text [String] Text to copy
+      # @yield Optional callback on success
+      def copy_to_clipboard(text, &on_success)
+        `navigator.clipboard.writeText(#{text}).then(function() {
+          #{on_success.call if on_success}
+        })`
+      end
+
+      # Read text from clipboard
+      # @yield Block receiving clipboard text
+      def read_from_clipboard(&block)
+        `navigator.clipboard.readText().then(function(text) {
+          #{block.call(`text`)}
+        })`
+      end
+
+      # ===== Object Utilities =====
+
+      # Deep clone an object
+      # @param obj [Object] Object to clone
+      # @return [Object] Cloned object
+      def deep_clone(obj)
+        `JSON.parse(JSON.stringify(#{obj.to_n}))`
+      end
+
+      # Deep merge two objects
+      # @param target [Hash] Target object
+      # @param source [Hash] Source object
+      # @return [Hash] Merged object
+      def deep_merge(target, source)
+        `
+          function deepMerge(target, source) {
+            var result = Object.assign({}, target);
+            for (var key in source) {
+              if (source.hasOwnProperty(key)) {
+                if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+                  result[key] = deepMerge(result[key] || {}, source[key]);
+                } else {
+                  result[key] = source[key];
+                }
+              }
+            }
+            return result;
+          }
+          return deepMerge(#{target.to_n}, #{source.to_n});
+        `
+      end
+
+      # Pick specific keys from an object
+      # @param obj [Hash] Source object
+      # @param keys [Array<String, Symbol>] Keys to pick
+      # @return [Hash] Object with only specified keys
+      def pick(obj, *keys)
+        result = {}
+        keys.flatten.each do |key|
+          key_s = key.to_s
+          native_obj = obj.to_n
+          if `#{native_obj}.hasOwnProperty(#{key_s})`
+            result[key_s] = `#{native_obj}[#{key_s}]`
+          end
+        end
+        result
+      end
+
+      # Omit specific keys from an object
+      # @param obj [Hash] Source object
+      # @param keys [Array<String, Symbol>] Keys to omit
+      # @return [Hash] Object without specified keys
+      def omit(obj, *keys)
+        keys_to_omit = keys.flatten.map(&:to_s)
+        result = {}
+        native_obj = obj.to_n
+        `Object.keys(#{native_obj}).forEach(function(key) {
+          if (!#{keys_to_omit}.includes(key)) {
+            #{result[`key`] = `#{native_obj}[key]`}
+          }
+        })`
+        result
+      end
+
+      # ===== Set Utilities =====
+
+      # Create a unique array (like Set)
+      # @param arr [Array] Array with possible duplicates
+      # @return [Array] Array with unique values
+      def unique(arr)
+        `[...new Set(#{arr.to_n})]`
+      end
+
+      # Get intersection of two arrays
+      # @param arr1 [Array] First array
+      # @param arr2 [Array] Second array
+      # @return [Array] Intersection
+      def intersection(arr1, arr2)
+        set2 = `new Set(#{arr2.to_n})`
+        `#{arr1.to_n}.filter(x => #{set2}.has(x))`
+      end
+
+      # Get difference of two arrays (arr1 - arr2)
+      # @param arr1 [Array] First array
+      # @param arr2 [Array] Second array
+      # @return [Array] Difference
+      def difference(arr1, arr2)
+        set2 = `new Set(#{arr2.to_n})`
+        `#{arr1.to_n}.filter(x => !#{set2}.has(x))`
+      end
+
+      # Get union of two arrays
+      # @param arr1 [Array] First array
+      # @param arr2 [Array] Second array
+      # @return [Array] Union (unique values)
+      def union(arr1, arr2)
+        `[...new Set([...#{arr1.to_n}, ...#{arr2.to_n}])]`
+      end
+
+      # ===== Validation Utilities =====
+
+      # Validate an email address
+      # @param email [String] Email to validate
+      # @return [Boolean] True if valid
+      def valid_email?(email)
+        `/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(#{email})`
+      end
+
+      # Validate a URL
+      # @param url [String] URL to validate
+      # @return [Boolean] True if valid
+      def valid_url?(url)
+        `
+          try {
+            new URL(#{url});
+            return true;
+          } catch (e) {
+            return false;
+          }
+        `
+      end
+
+      # Validate a phone number (basic)
+      # @param phone [String] Phone number to validate
+      # @return [Boolean] True if valid
+      def valid_phone?(phone)
+        # Remove common separators and check for digits
+        cleaned = `#{phone}.replace(/[\s\-\(\)\.]/g, '')`
+        `
+          var pattern = /^[\+]?[0-9]{10,15}$/;
+          return pattern.test(#{cleaned});
+        `
+      end
+
+      # Check if a value is blank (nil, empty string, or whitespace only)
+      # @param value [Object] Value to check
+      # @return [Boolean] True if blank
+      def blank?(value)
+        return true if value.nil?
+        return `#{value}.trim() === ''` if `typeof #{value} === 'string'`
+        return `#{value}.length === 0` if `Array.isArray(#{value})`
+        false
+      end
+
+      # Check if a value is present (not blank)
+      # @param value [Object] Value to check
+      # @return [Boolean] True if present
+      def present?(value)
+        !blank?(value)
+      end
+
+      # Validate minimum length
+      # @param value [String] Value to check
+      # @param min [Integer] Minimum length
+      # @return [Boolean] True if valid
+      def min_length?(value, min)
+        return false if value.nil?
+        `#{value}.length >= #{min}`
+      end
+
+      # Validate maximum length
+      # @param value [String] Value to check
+      # @param max [Integer] Maximum length
+      # @return [Boolean] True if valid
+      def max_length?(value, max)
+        return false if value.nil?
+        `#{value}.length <= #{max}`
+      end
+
+      # Validate a value matches a pattern
+      # @param value [String] Value to check
+      # @param pattern [String] Regular expression pattern
+      # @return [Boolean] True if matches
+      def matches_pattern?(value, pattern)
+        return false if value.nil?
+        `new RegExp(#{pattern}).test(#{value})`
+      end
+
+      # ===== Console Helpers =====
+
+      # Log a styled message to console
+      # @param message [String] Message to log
+      # @param style [String] CSS style string
+      def console_styled(message, style = 'color: blue; font-weight: bold;')
+        `console.log('%c' + #{message}, #{style})`
+      end
+
+      # Log a grouped set of messages
+      # @param label [String] Group label
+      # @yield Block that logs messages
+      def console_group(label, collapsed: false, &block)
+        if collapsed
+          `console.groupCollapsed(#{label})`
+        else
+          `console.group(#{label})`
+        end
+        block.call
+        `console.groupEnd()`
+      end
+
+      # Log a table
+      # @param data [Array, Hash] Data to display as table
+      def console_table(data)
+        `console.table(#{data.to_n})`
+      end
+
+      # Log with timestamp
+      # @param message [String] Message to log
+      def console_time(message)
+        timestamp = `new Date().toISOString()`
+        `console.log('[' + #{timestamp} + '] ' + #{message})`
+      end
+
       private
 
       # Convert snake_case to camelCase, preserving existing camelCase

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

@@ -0,0 +1,316 @@
+# backtick_javascript: true
+
+module OpalVite
+  module Concerns
+    module V1
+      # URIHelpers - provides URL parsing and manipulation utilities
+      #
+      # This module wraps JavaScript's URL and URLSearchParams APIs
+      # to provide Ruby-friendly methods for URL operations.
+      #
+      # @example Basic usage
+      #   class MyController < StimulusController
+      #     include OpalVite::Concerns::V1::URIHelpers
+      #
+      #     def connect
+      #       url = parse_url("https://example.com/path?foo=bar")
+      #       puts url_hostname(url)  # => "example.com"
+      #       puts url_param(url, "foo")  # => "bar"
+      #     end
+      #   end
+      #
+      module URIHelpers
+        # ===== URL Parsing =====
+
+        # Parse a URL string into a URL object
+        # @param url_string [String] URL string to parse
+        # @return [Native] JavaScript URL object
+        def parse_url(url_string)
+          `new URL(#{url_string})`
+        rescue
+          nil
+        end
+
+        # Parse a URL with a base URL
+        # @param url_string [String] Relative or absolute URL
+        # @param base [String] Base URL
+        # @return [Native] JavaScript URL object
+        def parse_url_with_base(url_string, base)
+          `new URL(#{url_string}, #{base})`
+        rescue
+          nil
+        end
+
+        # Get the current page URL
+        # @return [Native] JavaScript URL object
+        def current_url
+          `new URL(window.location.href)`
+        end
+
+        # ===== URL Components =====
+
+        # Get the protocol (scheme) of a URL
+        # @param url [Native] URL object
+        # @return [String] Protocol (e.g., "https:")
+        def url_protocol(url)
+          `#{url}.protocol`
+        end
+
+        # Get the hostname of a URL
+        # @param url [Native] URL object
+        # @return [String] Hostname (e.g., "example.com")
+        def url_hostname(url)
+          `#{url}.hostname`
+        end
+
+        # Get the host (hostname + port) of a URL
+        # @param url [Native] URL object
+        # @return [String] Host (e.g., "example.com:8080")
+        def url_host(url)
+          `#{url}.host`
+        end
+
+        # Get the port of a URL
+        # @param url [Native] URL object
+        # @return [String] Port number or empty string
+        def url_port(url)
+          `#{url}.port`
+        end
+
+        # Get the pathname of a URL
+        # @param url [Native] URL object
+        # @return [String] Pathname (e.g., "/path/to/page")
+        def url_pathname(url)
+          `#{url}.pathname`
+        end
+
+        # Get the search string (query string with ?)
+        # @param url [Native] URL object
+        # @return [String] Search string (e.g., "?foo=bar")
+        def url_search(url)
+          `#{url}.search`
+        end
+
+        # Get the hash (fragment) of a URL
+        # @param url [Native] URL object
+        # @return [String] Hash (e.g., "#section")
+        def url_hash(url)
+          `#{url}.hash`
+        end
+
+        # Get the origin of a URL
+        # @param url [Native] URL object
+        # @return [String] Origin (e.g., "https://example.com")
+        def url_origin(url)
+          `#{url}.origin`
+        end
+
+        # Get the full URL as a string
+        # @param url [Native] URL object
+        # @return [String] Full URL string
+        def url_to_string(url)
+          `#{url}.href`
+        end
+
+        # ===== Query Parameters =====
+
+        # Get a query parameter value
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        # @return [String, nil] Parameter value or nil
+        def url_param(url, name)
+          result = `#{url}.searchParams.get(#{name})`
+          `#{result} === null` ? nil : result
+        end
+
+        # Get all values for a query parameter
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        # @return [Array<String>] Array of values
+        def url_params(url, name)
+          `Array.from(#{url}.searchParams.getAll(#{name}))`
+        end
+
+        # Check if a query parameter exists
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        # @return [Boolean] True if parameter exists
+        def url_has_param?(url, name)
+          `#{url}.searchParams.has(#{name})`
+        end
+
+        # Get all query parameters as a Hash
+        # @param url [Native] URL object
+        # @return [Hash] Hash of parameter names to values
+        def url_all_params(url)
+          result = {}
+          `#{url}.searchParams.forEach((value, key) => {
+            #{result[`key`] = `value`}
+          })`
+          result
+        end
+
+        # Set a query parameter (mutates the URL object)
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        # @param value [String] Parameter value
+        def url_set_param(url, name, value)
+          `#{url}.searchParams.set(#{name}, #{value})`
+        end
+
+        # Append a query parameter (allows duplicates)
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        # @param value [String] Parameter value
+        def url_append_param(url, name, value)
+          `#{url}.searchParams.append(#{name}, #{value})`
+        end
+
+        # Delete a query parameter
+        # @param url [Native] URL object
+        # @param name [String] Parameter name
+        def url_delete_param(url, name)
+          `#{url}.searchParams.delete(#{name})`
+        end
+
+        # ===== URL Building =====
+
+        # Build a URL from components
+        # @param options [Hash] URL components
+        # @option options [String] :protocol Protocol (default: "https:")
+        # @option options [String] :hostname Hostname (required)
+        # @option options [String] :port Port number
+        # @option options [String] :pathname Path
+        # @option options [Hash] :params Query parameters
+        # @option options [String] :hash Fragment
+        # @return [String] Built URL string
+        def build_url(options = {})
+          protocol = options[:protocol] || 'https:'
+          hostname = options[:hostname] || 'localhost'
+          port = options[:port]
+          pathname = options[:pathname] || '/'
+          params = options[:params] || {}
+          hash = options[:hash]
+
+          # Build base URL
+          base = "#{protocol}//#{hostname}"
+          base += ":#{port}" if port && !port.to_s.empty?
+          base += pathname
+
+          url = parse_url(base)
+          return nil unless url
+
+          # Add query parameters
+          params.each do |key, value|
+            url_set_param(url, key.to_s, value.to_s)
+          end
+
+          # Add hash
+          `#{url}.hash = #{hash}` if hash
+
+          url_to_string(url)
+        end
+
+        # ===== URL Encoding =====
+
+        # Encode a URI component
+        # @param str [String] String to encode
+        # @return [String] Encoded string
+        def encode_uri_component(str)
+          `encodeURIComponent(#{str})`
+        end
+
+        # Decode a URI component
+        # @param str [String] String to decode
+        # @return [String] Decoded string
+        def decode_uri_component(str)
+          `decodeURIComponent(#{str})`
+        rescue
+          str
+        end
+
+        # Encode a full URI
+        # @param str [String] URI to encode
+        # @return [String] Encoded URI
+        def encode_uri(str)
+          `encodeURI(#{str})`
+        end
+
+        # Decode a full URI
+        # @param str [String] URI to decode
+        # @return [String] Decoded URI
+        def decode_uri(str)
+          `decodeURI(#{str})`
+        rescue
+          str
+        end
+
+        # ===== Query String Utilities =====
+
+        # Parse a query string into a Hash
+        # @param query_string [String] Query string (with or without leading ?)
+        # @return [Hash] Parsed parameters
+        def parse_query_string(query_string)
+          # Remove leading ? if present
+          qs = query_string.to_s
+          qs = qs[1..-1] if qs.start_with?('?')
+
+          result = {}
+          params = `new URLSearchParams(#{qs})`
+          `#{params}.forEach((value, key) => {
+            #{result[`key`] = `value`}
+          })`
+          result
+        end
+
+        # Build a query string from a Hash
+        # @param params [Hash] Parameters
+        # @return [String] Query string (without leading ?)
+        def build_query_string(params)
+          search_params = `new URLSearchParams()`
+          params.each do |key, value|
+            `#{search_params}.append(#{key.to_s}, #{value.to_s})`
+          end
+          `#{search_params}.toString()`
+        end
+
+        # ===== Path Utilities =====
+
+        # Join path segments
+        # @param segments [Array<String>] Path segments
+        # @return [String] Joined path
+        def join_path(*segments)
+          segments.map { |s| s.to_s.gsub(%r{^/|/$}, '') }.reject(&:empty?).join('/')
+        end
+
+        # Get the filename from a path
+        # @param path [String] Path
+        # @return [String] Filename
+        def path_basename(path)
+          path.to_s.split('/').last || ''
+        end
+
+        # Get the directory from a path
+        # @param path [String] Path
+        # @return [String] Directory path
+        def path_dirname(path)
+          parts = path.to_s.split('/')
+          parts.pop
+          parts.join('/') || '/'
+        end
+
+        # Get the file extension from a path
+        # @param path [String] Path
+        # @return [String] Extension (with dot) or empty string
+        def path_extname(path)
+          basename = path_basename(path)
+          idx = basename.rindex('.')
+          idx ? basename[idx..-1] : ''
+        end
+      end
+    end
+  end
+end
+
+# Alias for convenience
+URIHelpers = OpalVite::Concerns::V1::URIHelpers

data/opal/opal_vite/concerns/v1.rb

@@ -6,3 +6,5 @@ require 'opal_vite/concerns/v1/storable'
 require 'opal_vite/concerns/v1/stimulus_helpers'
 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opal-vite
 version: !ruby/object:Gem::Version
-  version: 0.2.19
+  version: 0.3.1
 platform: ruby
 authors:
 - stofu1234
@@ -120,12 +120,14 @@ files:
 - opal/opal_vite/concerns/storable.rb
 - opal/opal_vite/concerns/toastable.rb
 - opal/opal_vite/concerns/v1.rb
+- opal/opal_vite/concerns/v1/base64_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/uri_helpers.rb
 - opal/opal_vite/concerns/v1/vue_helpers.rb
 - opal/opal_vite/concerns/vue_helpers.rb
 homepage: https://stofu1234.github.io/opal-vite/