opal-vite 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5274b86604ed917278cf1739cb4663c1d93246cd6bf82876876fea56c239c6c2
-  data.tar.gz: 72291ac54ac2770b38b7ade5a8907751c9845926efbc54ff479b6ac8623d485e
+  metadata.gz: 8736c0cccd990adbc7f614480718ba0bab767f94ad281f508b0a01b9898deb3d
+  data.tar.gz: 93ab376b58edb586aed577d0d4a19011f7f84660c62eebffe418eccb4b9b1e73
 SHA512:
-  metadata.gz: 1b134a748ab8322e8889dcd64e687632581ae5da768c5a5b26e0e2e52c032c309e0b39ebd9e0dd2a0645bdaf9ae53e60ed0450985611b220970a9a1ef802d682
-  data.tar.gz: a309c63ca72694695797d1d5ad0edef41427664a2fd5e4d827776b42bd4a4e02c940f772f6aab2afb5b857fa1b49f31ee749ddd674893ca7207566035ea7eeb1
+  metadata.gz: 1c0d8a02384a2e1f958d2a0ce62f66fe8f63db8c87cbe709089e04ca9441e2d37a9a41b860170cdb2ca8f24467a79ce12b2587d1312e0d59dd22e75020429911
+  data.tar.gz: 7aae2b96e735993cfd583cdc98ea0ad6bbd49110ef63209b17f6f49e614bf7edc0d1948612f40522ed9aa6e1839fa6e02731a7f6764ef269b3b61c17cee5c2b3

data/lib/opal/vite/version.rb

@@ -1,5 +1,5 @@
 module Opal
   module Vite
-    VERSION = "0.3.0"
+    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

@@ -1645,6 +1645,300 @@ module OpalVite
         `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.3.0
+  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/