islandjs-rails 0.1.0

data/lib/islandjs_rails/rails_helpers.rb

@@ -0,0 +1,394 @@
+module IslandjsRails
+  module RailsHelpers
+    # Main helper method that combines all IslandJS functionality
+    def islands
+      output = []
+      output << island_partials  # Now uses vendor UMD partial
+      output << island_bundle_script
+      output << umd_versions_debug if Rails.env.development?
+      output.compact.join("\n").html_safe
+    end
+
+    # Render all island partials (CDN scripts for external libraries)
+    # Now delegates to the vendor UMD partial for better performance
+    def island_partials
+      render(partial: "shared/islands/vendor_umd").html_safe
+    rescue ActionView::MissingTemplate
+      if Rails.env.development?
+        "<!-- IslandJS: Vendor UMD partial missing. Run: rails islandjs:init -->".html_safe
+      else
+        "".html_safe
+      end
+    end
+
+    # Render the main IslandJS bundle script tag
+    def island_bundle_script
+      manifest_path = Rails.root.join('public', 'islands_manifest.json')
+      bundle_path = '/islands_bundle.js'
+      
+      unless File.exist?(manifest_path)
+        # Fallback to direct bundle path when no manifest
+        return html_safe_string("<script src=\"#{bundle_path}\" defer></script>")
+      end
+      
+      begin
+        manifest = JSON.parse(File.read(manifest_path))
+        # Look for islands_bundle.js in manifest
+        bundle_file = manifest['islands_bundle.js']
+        
+        if bundle_file
+          html_safe_string("<script src=\"#{bundle_file}\" defer></script>")
+        else
+          # Fallback to direct bundle path
+          html_safe_string("<script src=\"#{bundle_path}\" defer></script>")
+        end
+      rescue JSON::ParserError
+        # Fallback to direct bundle path on manifest parse error
+        html_safe_string("<script src=\"#{bundle_path}\" defer></script>")
+      end
+    end
+
+    # Mount a React component with props and Turbo-compatible lifecycle
+    def react_component(component_name, props = {}, options = {})
+      # Generate component ID - use custom container_id if provided
+      if options[:container_id]
+        component_id = options[:container_id]
+      else
+        component_id = "react-#{component_name.gsub(/([A-Z])/, '-\1').downcase.gsub(/^-/, '')}-#{SecureRandom.hex(4)}"
+      end
+      
+      # Extract options
+      tag_name = options[:tag] || 'div'
+      css_class = options[:class] || ''
+      namespace = options[:namespace] || 'window.islandjsRails'
+      
+      # For turbo-cache compatibility, store initial state as JSON in data attribute
+      initial_state_json = props.to_json
+      
+      # Generate data attributes from props with proper HTML escaping (keeping for backward compatibility)
+      data_attrs = props.map do |key, value|
+        # Convert both camelCase and snake_case to kebab-case
+        attr_name = key.to_s.gsub(/([A-Z])/, '-\1').gsub('_', '-').downcase.gsub(/^-/, '')
+        # Properly escape HTML entities
+        attr_value = if value.nil?
+          ''
+        else
+          value.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;').gsub('"', '&quot;')
+        end
+        "data-#{attr_name}=\"#{attr_value}\""
+      end.join(' ')
+      
+      # Generate optional chaining syntax for custom namespaces
+      namespace_with_optional = if namespace != 'window.islandjsRails' && !namespace.include?('?')
+        namespace + '?'
+      else
+        namespace
+      end
+      
+      # Generate the mounting script - pass container_id as the only prop for turbo-cache pattern
+      mount_script = generate_react_mount_script(component_name, component_id, namespace, namespace_with_optional)
+      
+      # Return the container div with data-initial-state and script
+      data_part = data_attrs.empty? ? '' : " #{data_attrs}"
+      class_part = css_class.empty? ? '' : " class=\"#{css_class}\""
+      
+      # Add data-initial-state for turbo-cache compatibility
+      initial_state_attr = " data-initial-state=\"#{initial_state_json.gsub('"', '&quot;')}\""
+      
+      container_html = "<#{tag_name} id=\"#{component_id}\"#{class_part}#{data_part}#{initial_state_attr}></#{tag_name}>"
+      
+      html_safe_string("#{container_html}\n#{mount_script}")
+    end
+
+    # Mount a Vue component with props and Turbo-compatible lifecycle  
+    def vue_component(component_name, props = {}, options = {})
+      # Generate unique ID for this component instance
+      component_id = "vue-#{component_name.downcase}-#{SecureRandom.hex(4)}"
+      
+      # Prepare props as JSON
+      props_json = props.to_json
+      
+      # Extract options
+      tag_name = options[:tag] || 'div'
+      css_class = options[:class] || ''
+      
+      # Generate the mounting script
+      mount_script = generate_vue_mount_script(component_name, component_id, props_json)
+      
+      # Return the container div and script
+      container_html = "<#{tag_name} id=\"#{component_id}\" class=\"#{css_class}\"></#{tag_name}>"
+      
+      html_safe_string("#{container_html}\n#{mount_script}")
+    end
+
+    # Generic island component helper
+    def island_component(framework, component_name, props = {}, options = {})
+      case framework.to_s.downcase
+      when 'react'
+        react_component(component_name, props, options)
+      when 'vue'
+        vue_component(component_name, props, options)
+      else
+        html_safe_string("<!-- Unsupported framework: #{framework} -->")
+      end
+    end
+
+    # Debug helper to show available components
+    def island_debug
+      return '' unless Rails.env.development?
+      
+      debug_info = {
+        bundle_path: find_bundle_path,
+        partials_count: Dir.glob(File.join(IslandjsRails.configuration.partials_dir, '*.html.erb')).count,
+        webpack_config_exists: File.exist?(IslandjsRails.configuration.webpack_config_path),
+        package_json_exists: File.exist?(IslandjsRails.configuration.package_json_path)
+      }
+      
+      debug_html = <<~HTML
+        <div style="background: #f0f0f0; padding: 10px; margin: 10px 0; border: 1px solid #ccc; font-family: monospace; font-size: 12px;">
+          <strong>🏝️ IslandJS Debug Info:</strong><br>
+          Bundle Path: #{debug_info[:bundle_path] || 'Not found'}<br>
+          Partials: #{debug_info[:partials_count]} found<br>
+          Webpack Config: #{debug_info[:webpack_config_exists] ? '✓' : '✗'}<br>
+          Package.json: #{debug_info[:package_json_exists] ? '✓' : '✗'}
+        </div>
+      HTML
+      
+      html_safe_string(debug_html)
+    end
+
+    # Legacy UMD helper methods for backward compatibility with tests
+    def umd_versions_debug
+      return unless Rails.env.development?
+      
+      begin
+        installed = IslandjsRails.core.send(:installed_packages)
+        supported = installed.select { |pkg| IslandjsRails.core.send(:supported_package?, pkg) }
+        
+        if supported.empty?
+          return %(<div style="position: fixed; bottom: 10px; right: 10px; background: #666; color: #fff; padding: 5px; font-size: 10px; z-index: 9999;">UMD: No packages</div>).html_safe
+        end
+        
+        versions = supported.map do |package_name|
+          begin
+            version = IslandjsRails.version_for(package_name)
+            "#{package_name}: #{version}"
+          rescue
+            "#{package_name}: error"
+          end
+        end.join(', ')
+        
+        %(<div style="position: fixed; bottom: 10px; right: 10px; background: #000; color: #fff; padding: 5px; font-size: 10px; z-index: 9999;">UMD: #{versions}</div>).html_safe
+      rescue => e
+        %(<div style="position: fixed; bottom: 10px; right: 10px; background: #f00; color: #fff; padding: 5px; font-size: 10px; z-index: 9999;">UMD Error: #{e.message}</div>).html_safe
+      end
+    end
+
+    def umd_partial_for(package_name)
+      # Backward compatibility: delegate to vendor UMD partial
+      # Individual package partials are no longer used
+      if Rails.env.development?
+        "<!-- IslandJS: umd_partial_for('#{package_name}') is deprecated. Use island_partials or render 'shared/islands/vendor_umd' instead -->".html_safe
+      else
+        # In production, silently delegate to vendor partial
+        render(partial: "shared/islands/vendor_umd").html_safe
+      end
+    rescue ActionView::MissingTemplate
+      if Rails.env.development?
+        "<!-- IslandJS: Vendor UMD partial missing. Run: rails islandjs:init -->".html_safe
+      else
+        "".html_safe
+      end
+    end
+
+    def react_partials
+      packages = ['react', 'react-dom']
+      partials = packages.map { |pkg| umd_partial_for(pkg) }.compact.join("\n")
+      html_safe_string(partials)
+    end
+
+    private
+
+    # Find the bundle file path (with manifest support)
+    def find_bundle_path
+      # Try manifest first (production)
+      manifest_path = Rails.root.join('public', 'islands_manifest.json')
+      
+      if File.exist?(manifest_path)
+        begin
+          manifest = JSON.parse(File.read(manifest_path))
+          # Look for islands_bundle in manifest
+          bundle_key = manifest.keys.find { |key| key.include?('islands_bundle') }
+          return "/#{manifest[bundle_key]}" if bundle_key && manifest[bundle_key]
+        rescue JSON::ParserError
+          # Fall through to direct file check
+        end
+      end
+      
+      # Try direct file (development)
+      direct_bundle_path = Rails.root.join('public', 'islands_bundle.js')
+      if File.exist?(direct_bundle_path)
+        return '/islands_bundle.js'
+      end
+      
+      # Bundle not found
+      nil
+    end
+
+    # Generate React component mounting script with Turbo compatibility
+    def generate_react_mount_script(component_name, component_id, namespace, namespace_with_optional)
+      <<~JAVASCRIPT
+        <script>
+          (function() {
+            function mount#{component_name}() {
+              if (typeof #{namespace_with_optional} === 'undefined' || !#{namespace_with_optional}.#{component_name}) {
+                console.warn('IslandJS: #{component_name} component not found. Make sure it\\'s exported in your bundle.');
+                return;
+              }
+              
+              if (typeof React === 'undefined' || typeof window.ReactDOM === 'undefined') {
+                console.warn('IslandJS: React or ReactDOM not loaded. Install with: rails "islandjs:install[react]" and rails "islandjs:install[react-dom]"');
+                return;
+              }
+              
+              const container = document.getElementById('#{component_id}');
+              if (!container) return;
+              
+              const props = { containerId: '#{component_id}' };
+              const element = React.createElement(#{namespace_with_optional}.#{component_name}, props);
+              
+              // Use React 18 createRoot if available, fallback to React 17 render
+              if (window.ReactDOM.createRoot) {
+                if (!container._reactRoot) {
+                  container._reactRoot = window.ReactDOM.createRoot(container);
+                }
+                container._reactRoot.render(element);
+              } else {
+                window.ReactDOM.render(element, container);
+              }
+            }
+            
+            function cleanup#{component_name}() {
+              const container = document.getElementById('#{component_id}');
+              if (!container) return;
+              
+              // React 18 unmount
+              if (container._reactRoot) {
+                container._reactRoot.unmount();
+                container._reactRoot = null;
+              } else if (typeof window.ReactDOM !== 'undefined' && window.ReactDOM.unmountComponentAtNode) {
+                // React 17 unmount
+                window.ReactDOM.unmountComponentAtNode(container);
+              }
+            }
+            
+            // Mount on page load and Turbo navigation
+            if (document.readyState === 'loading') {
+              document.addEventListener('DOMContentLoaded', mount#{component_name});
+            } else {
+              mount#{component_name}();
+            }
+            
+            // Turbo compatibility
+            document.addEventListener('turbo:load', mount#{component_name});
+            document.addEventListener('turbo:before-cache', cleanup#{component_name});
+            document.addEventListener('turbo:render', mount#{component_name});
+            document.addEventListener('turbo:before-render', cleanup#{component_name});
+            
+            // Legacy Turbolinks compatibility
+            document.addEventListener('turbolinks:load', mount#{component_name});
+            document.addEventListener('turbolinks:before-cache', cleanup#{component_name});
+          })();
+        </script>
+      JAVASCRIPT
+    end
+
+    # Generate Vue component mounting script with Turbo compatibility
+    def generate_vue_mount_script(component_name, component_id, props_json)
+      <<~JAVASCRIPT
+        <script>
+          (function() {
+            let vueApp = null;
+            
+            function mount#{component_name}() {
+              if (typeof window.islandjsRails === 'undefined' || !window.islandjsRails.#{component_name}) {
+                console.warn('IslandJS: #{component_name} component not found. Make sure it\\'s exported in your bundle.');
+                return;
+              }
+              
+              if (typeof Vue === 'undefined') {
+                console.warn('IslandJS: Vue not loaded. Install with: rails "islandjs:install[vue]"');
+                return;
+              }
+              
+              const container = document.getElementById('#{component_id}');
+              if (!container) return;
+              
+              const props = #{props_json};
+              
+              // Vue 3 syntax
+              if (Vue.createApp) {
+                vueApp = Vue.createApp({
+                  render() {
+                    return Vue.h(window.islandjsRails.#{component_name}, props);
+                  }
+                });
+                vueApp.mount('##{component_id}');
+              } else {
+                // Vue 2 syntax
+                vueApp = new Vue({
+                  el: '##{component_id}',
+                  render: function(h) {
+                    return h(window.islandjsRails.#{component_name}, { props: props });
+                  }
+                });
+              }
+            }
+            
+            function unmount#{component_name}() {
+              if (vueApp) {
+                if (vueApp.unmount) {
+                  // Vue 3
+                  vueApp.unmount();
+                } else if (vueApp.$destroy) {
+                  // Vue 2
+                  vueApp.$destroy();
+                }
+                vueApp = null;
+              }
+            }
+            
+            // Mount on page load and Turbo navigation
+            if (document.readyState === 'loading') {
+              document.addEventListener('DOMContentLoaded', mount#{component_name});
+            } else {
+              mount#{component_name}();
+            }
+            
+            // Turbo compatibility
+            document.addEventListener('turbo:load', mount#{component_name});
+            document.addEventListener('turbo:before-cache', unmount#{component_name});
+            
+            // Legacy Turbolinks compatibility
+            document.addEventListener('turbolinks:load', mount#{component_name});
+            document.addEventListener('turbolinks:before-cache', unmount#{component_name});
+          })();
+        </script>
+      JAVASCRIPT
+    end
+
+    # Cross-Rails version html_safe compatibility
+    def html_safe_string(string)
+      if string.respond_to?(:html_safe)
+        string.html_safe
+      else
+        string
+      end
+    end
+  end
+end
+
+# Auto-include in ActionView if Rails is present
+if defined?(ActionView::Base)
+  ActionView::Base.include IslandjsRails::RailsHelpers
+end

data/lib/islandjs_rails/railtie.rb

@@ -0,0 +1,59 @@
+require 'rails/railtie'
+
+module IslandjsRails
+  class Railtie < Rails::Railtie
+    railtie_name :islandjs_rails
+
+    rake_tasks do
+      load File.expand_path('tasks.rb', __dir__)
+    end
+
+    initializer 'islandjs_rails.helpers' do
+      ActiveSupport.on_load(:action_view) do
+        include IslandjsRails::RailsHelpers
+      end
+    end
+
+    # Development-only warnings and checks
+    initializer 'islandjs_rails.development_warnings', after: :load_config_initializers do
+      if Rails.env.development?
+        # Check for common setup issues
+        Rails.application.config.after_initialize do
+          check_development_setup
+        end
+      end
+    end
+
+    private
+
+    def check_development_setup
+      # Check if package.json exists
+      unless File.exist?(Rails.root.join('package.json'))
+        Rails.logger.warn "IslandJS: package.json not found. Run 'rails islandjs:init' to set up."
+        return
+      end
+
+      # Check if webpack config exists
+      unless File.exist?(Rails.root.join('webpack.config.js'))
+        Rails.logger.warn "IslandJS: webpack.config.js not found. Run 'rails islandjs:init' to set up."
+        return
+      end
+
+      # Check if yarn is available
+      unless system('which yarn > /dev/null 2>&1')
+        Rails.logger.warn "IslandJS: yarn not found. Please install yarn for package management."
+        return
+      end
+
+      # Check if essential webpack dependencies are installed
+      essential_deps = ['webpack', 'webpack-cli', '@babel/core']
+      missing_deps = essential_deps.select do |dep|
+        !system("yarn list #{dep} > /dev/null 2>&1")
+      end
+
+      unless missing_deps.empty?
+        Rails.logger.warn "IslandJS: Missing dependencies: #{missing_deps.join(', ')}. Run 'rails islandjs:init' to install."
+      end
+    end
+  end
+end

data/lib/islandjs_rails/tasks.rb

@@ -0,0 +1,118 @@
+require 'rake'
+
+namespace :islandjs do
+  desc "Initialize IslandJS in this Rails project"
+  task :init => :environment do
+    IslandjsRails.init!
+  end
+
+  desc "Install a JavaScript island package"
+  task :install, [:package_name, :version] => :environment do |t, args|
+    package_name = args[:package_name]
+    version = args[:version]
+    
+    if package_name.nil?
+      puts "❌ Package name is required"
+      puts "Usage: rails \"islandjs:install[react,18.3.1]\""
+      exit 1
+    end
+    
+    IslandjsRails.install!(package_name, version)
+  end
+
+  desc "Update a JavaScript island package"
+  task :update, [:package_name, :version] => :environment do |t, args|
+    package_name = args[:package_name]
+    version = args[:version]
+    
+    if package_name.nil?
+      puts "❌ Package name is required"
+      puts "Usage: rails \"islandjs:update[react,18.3.1]\""
+      exit 1
+    end
+    
+    IslandjsRails.update!(package_name, version)
+  end
+
+  desc "Remove a JavaScript island package"
+  task :remove, [:package_name] => :environment do |t, args|
+    package_name = args[:package_name]
+    
+    if package_name.nil?
+      puts "❌ Package name is required"
+      puts "Usage: rails \"islandjs:remove[react]\""
+      exit 1
+    end
+    
+    IslandjsRails.remove!(package_name)
+  end
+
+  desc "Sync all JavaScript island packages with current package.json"
+  task :sync => :environment do
+    IslandjsRails.sync!
+  end
+
+  desc "Show status of all JavaScript island packages"
+  task :status => :environment do
+    IslandjsRails.status!
+  end
+
+  desc "Clean all island partials and reset webpack externals"
+  task :clean => :environment do
+    IslandjsRails.clean!
+  end
+
+  desc "Show IslandJS configuration"
+  task :config => :environment do
+    config = IslandjsRails.configuration
+            puts "📊 IslandjsRails Configuration"
+    puts "=" * 40
+    puts "Package.json path: #{config.package_json_path}"
+    puts "Partials directory: #{config.partials_dir}"
+    puts "Webpack config path: #{config.webpack_config_path}"
+    puts "Supported CDNs: #{config.supported_cdns.join(', ')}"
+    puts "Built-in global name overrides: #{IslandjsRails::BUILT_IN_GLOBAL_NAME_OVERRIDES.size} available"
+  end
+
+  desc "Show IslandJS version"
+  task :version do
+    puts "IslandjsRails #{IslandjsRails::VERSION}"
+  end
+
+  namespace :vendor do
+    desc "Rebuild combined vendor bundle (for :external_combined mode)"
+    task :rebuild_combined => :environment do
+      IslandjsRails.vendor_manager.rebuild_combined_bundle!
+    end
+
+    desc "Show vendor configuration and status"
+    task :status => :environment do
+      config = IslandjsRails.configuration
+      puts "📦 IslandJS Vendor Status"
+      puts "=" * 40
+      puts "Mode: #{config.vendor_script_mode}"
+      puts "Vendor directory: #{config.vendor_dir}"
+      puts "Combined basename: #{config.combined_basename}"
+      puts "Vendor order: #{config.vendor_order.join(', ')}"
+      
+      # Show manifest info
+      manifest_path = config.vendor_manifest_path
+      if File.exist?(manifest_path)
+        require 'json'
+        manifest = JSON.parse(File.read(manifest_path))
+        puts "\nInstalled libraries: #{manifest['libs'].length}"
+        manifest['libs'].each do |lib|
+          puts "  • #{lib['name']}@#{lib['version']} (#{lib['file']})"
+        end
+        
+        if manifest['combined']
+          puts "\nCombined bundle: #{manifest['combined']['file']} (#{manifest['combined']['size_kb']}KB)"
+        end
+      else
+        puts "\nNo vendor manifest found"
+      end
+    end
+  end
+end
+
+