islandjs-rails 0.1.0

data/lib/islandjs_rails/vendor_manager.rb

@@ -0,0 +1,271 @@
+require 'json'
+require 'digest'
+require 'fileutils'
+
+module IslandjsRails
+  class VendorManager
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Install a package to vendor directory
+    def install_package!(package_name, version = nil)
+      puts "📦 Installing #{package_name} to vendor directory..."
+      
+      # Download UMD content
+      content, actual_version = download_umd_content(package_name, version)
+      return false unless content
+
+      # Ensure vendor directory exists
+      FileUtils.mkdir_p(configuration.vendor_dir)
+
+      # Save to vendor file
+      vendor_file = configuration.vendor_file_path(package_name, actual_version)
+      File.write(vendor_file, content)
+
+      # Update manifest
+      update_manifest!(package_name, actual_version, File.basename(vendor_file))
+
+      # Regenerate vendor partial
+      regenerate_vendor_partial!
+
+      puts "✅ #{package_name}@#{actual_version} installed to vendor"
+      true
+    end
+
+    # Remove a package from vendor directory
+    def remove_package!(package_name)
+      puts "🗑️  Removing #{package_name} from vendor..."
+      
+      manifest = read_manifest
+      lib_entry = manifest['libs'].find { |lib| lib['name'] == package_name }
+      
+      return false unless lib_entry
+
+      # Remove file
+      vendor_file = configuration.vendor_dir.join(lib_entry['file'])
+      File.delete(vendor_file) if File.exist?(vendor_file)
+
+      # Update manifest
+      manifest['libs'].reject! { |lib| lib['name'] == package_name }
+      write_manifest(manifest)
+
+      # Regenerate vendor partial
+      regenerate_vendor_partial!
+
+      puts "✅ #{package_name} removed from vendor"
+      true
+    end
+
+    # Rebuild combined bundle (for :external_combined mode)
+    def rebuild_combined_bundle!
+      return unless configuration.vendor_script_mode == :external_combined
+
+      puts "🔨 Building combined vendor bundle..."
+      
+      manifest = read_manifest
+      return if manifest['libs'].empty?
+
+      # Order libraries according to vendor_order
+      ordered_libs = order_libraries(manifest['libs'])
+      
+      # Combine all UMD content
+      combined_content = build_combined_content(ordered_libs)
+      
+      # Generate hash for cache busting
+      content_hash = Digest::SHA256.hexdigest(combined_content)[0, 12]
+      
+      # Write combined file
+      combined_file = configuration.combined_vendor_path(content_hash)
+      File.write(combined_file, combined_content)
+      
+      # Update manifest with combined info
+      manifest['combined'] = {
+        'hash' => content_hash,
+        'file' => File.basename(combined_file),
+        'size_kb' => (combined_content.bytesize / 1024.0).round(1)
+      }
+      write_manifest(manifest)
+
+      # Warn if bundle is too large
+      size_mb = combined_content.bytesize / (1024.0 * 1024.0)
+      if size_mb > 1.0
+        puts "⚠️  Warning: Combined bundle is #{size_mb.round(1)}MB - consider splitting libraries"
+      end
+
+      # Clean up old combined files
+      cleanup_old_combined_files!
+
+      # Regenerate vendor partial
+      regenerate_vendor_partial!
+
+      puts "✅ Combined bundle built: #{content_hash}"
+      true
+    end
+
+    private
+
+    def download_umd_content(package_name, version = nil)
+      # Use existing UMD download logic from core
+      core = IslandjsRails.core
+      
+      # Try to find working UMD URL
+      version ||= core.version_for(package_name) || 'latest'
+      url = core.find_working_island_url(package_name, version)
+      
+      return [nil, nil] unless url
+
+      content = core.download_umd_content(url)
+      return [nil, nil] unless content
+
+      # Extract actual version from URL if needed
+      actual_version = extract_version_from_url(url) || version
+      
+      [content, actual_version]
+    end
+
+    def extract_version_from_url(url)
+      # Extract version from CDN URLs like unpkg.com/react@18.2.0/...
+      match = url.match(/@([^\/]+)\//)
+      match ? match[1] : nil
+    end
+
+    def read_manifest
+      manifest_path = configuration.vendor_manifest_path
+      
+      if File.exist?(manifest_path)
+        begin
+          JSON.parse(File.read(manifest_path))
+        rescue JSON::ParserError
+          { 'libs' => [] }
+        end
+      else
+        { 'libs' => [] }
+      end
+    end
+
+    def write_manifest(manifest)
+      FileUtils.mkdir_p(File.dirname(configuration.vendor_manifest_path))
+      File.write(configuration.vendor_manifest_path, JSON.pretty_generate(manifest))
+    end
+
+    def update_manifest!(package_name, version, filename)
+      manifest = read_manifest
+      
+      # Remove existing entry for this package
+      manifest['libs'].reject! { |lib| lib['name'] == package_name }
+      
+      # Add new entry
+      manifest['libs'] << {
+        'name' => package_name,
+        'version' => version,
+        'file' => filename
+      }
+      
+      write_manifest(manifest)
+    end
+
+    def order_libraries(libs)
+      # Sort according to vendor_order, then alphabetically
+      ordered = []
+      remaining = libs.dup
+      
+      # Add libraries in vendor_order first
+      configuration.vendor_order.each do |name|
+        lib = remaining.find { |l| l['name'] == name }
+        if lib
+          ordered << lib
+          remaining.delete(lib)
+        end
+      end
+      
+      # Add remaining libraries alphabetically
+      ordered + remaining.sort_by { |lib| lib['name'] }
+    end
+
+    def build_combined_content(ordered_libs)
+      content_parts = []
+      
+      ordered_libs.each do |lib|
+        vendor_file = configuration.vendor_dir.join(lib['file'])
+        next unless File.exist?(vendor_file)
+        
+        # Add header comment
+        content_parts << "// #{lib['name']}@#{lib['version']}"
+        
+        # Add library content
+        content_parts << File.read(vendor_file)
+        
+        # Add separator
+        content_parts << ""
+      end
+      
+      content_parts.join("\n")
+    end
+
+    def cleanup_old_combined_files!
+      # Keep only the 2 most recent combined files
+      pattern = configuration.vendor_dir.join("#{configuration.combined_basename}-*.js")
+      combined_files = Dir.glob(pattern).sort_by { |f| File.mtime(f) }.reverse
+      
+      # Delete all but the 2 most recent
+      combined_files[2..-1]&.each do |file|
+        File.delete(file)
+        puts "  🗑️  Cleaned up old combined file: #{File.basename(file)}"
+      end
+    end
+
+    def regenerate_vendor_partial!
+      case configuration.vendor_script_mode
+      when :external_split
+        generate_split_partial!
+      when :external_combined
+        generate_combined_partial!
+      else
+        raise "Unknown vendor_script_mode: #{configuration.vendor_script_mode}"
+      end
+    end
+
+    def generate_split_partial!
+      manifest = read_manifest
+      
+      content = <<~ERB
+        <%# IslandJS Rails Vendor UMD Scripts (Split Mode) %>
+        <%# Generated automatically - do not edit manually %>
+        <% # Load each library separately for better caching %>
+      ERB
+      
+      manifest['libs'].each do |lib|
+        content += <<~ERB
+          <script src="/islands/vendor/#{lib['file']}" data-turbo-track="reload"></script>
+        ERB
+      end
+      
+      write_vendor_partial(content)
+    end
+
+    def generate_combined_partial!
+      manifest = read_manifest
+      combined_info = manifest['combined']
+      
+      return generate_split_partial! unless combined_info
+      
+      content = <<~ERB
+        <%# IslandJS Rails Vendor UMD Scripts (Combined Mode) %>
+        <%# Generated automatically - do not edit manually %>
+        <%# Combined bundle: #{combined_info['size_kb']}KB %>
+        <script src="/islands/vendor/#{combined_info['file']}" data-turbo-track="reload"></script>
+      ERB
+      
+      write_vendor_partial(content)
+    end
+
+    def write_vendor_partial(content)
+      FileUtils.mkdir_p(File.dirname(configuration.vendor_partial_path))
+      File.write(configuration.vendor_partial_path, content)
+      puts "  ✓ Generated vendor partial: #{configuration.vendor_partial_path}"
+    end
+  end
+end

data/lib/islandjs_rails/version.rb

@@ -0,0 +1,3 @@
+module IslandjsRails
+  VERSION = "0.1.0"
+end

data/lib/islandjs_rails.rb

@@ -0,0 +1,142 @@
+require_relative "islandjs_rails/version"
+require_relative "islandjs_rails/configuration"
+require_relative "islandjs_rails/core"
+require_relative "islandjs_rails/vendor_manager"
+require_relative "islandjs_rails/cli"
+
+# Conditionally require Rails-specific components
+if defined?(Rails)
+  require_relative "islandjs_rails/railtie"
+  require_relative "islandjs_rails/rails_helpers"
+end
+
+module IslandjsRails
+  # Custom error classes
+  class Error < StandardError; end
+  class YarnError < Error; end
+  class PackageNotFoundError < Error; end
+  class UmdNotFoundError < Error; end
+
+  # Constants for compatibility with tests
+  UMD_PATH_PATTERNS = [
+    'umd/{name}.production.min.js',
+    'umd/{name}.development.js',
+    'umd/{name}.min.js',
+    'umd/{name}.js', 
+    'dist/{name}.min.js',
+    'dist/{name}.js',
+    'dist/{name}.umd.min.js',
+    'dist/{name}.umd.js',
+    'lib/index.iife.min.js',  # Solana Web3.js pattern
+    'lib/index.iife.js',      # Solana Web3.js pattern
+    'lib/{name}.js',
+    'lib/{name}.min.js',
+    '{name}.min.js',
+    '{name}.js',
+    'build/{name}.min.js',
+    'build/{name}.js',
+    'bundles/{name}.min.js',
+    'bundles/{name}.js'
+  ].freeze
+
+  CDN_BASES = [
+    'https://unpkg.com',
+    'https://cdn.jsdelivr.net/npm'
+  ].freeze
+
+  BUILT_IN_GLOBAL_NAME_OVERRIDES = {
+    # React ecosystem
+    'react' => 'React',
+    'react-dom' => 'ReactDOM',
+    'react-router' => 'ReactRouter',
+    'react-router-dom' => 'ReactRouterDOM',
+    
+    # Utility libraries
+    'lodash' => '_',
+    'underscore' => '_',
+    'jquery' => '$',
+    'zepto' => '$',
+    'date-fns' => 'dateFns',
+    
+    # Frameworks
+    'vue' => 'Vue',
+    'angular' => 'ng',
+    
+    # Blockchain
+    '@solana/web3.js' => 'solanaWeb3',
+    'web3' => 'Web3',
+    
+    # Visualization
+    'chart.js' => 'Chart',
+    'plotly.js' => 'Plotly',
+    
+    # State management
+    'redux' => 'Redux'
+  }.freeze
+
+  class << self
+    # Configuration management
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Core instance management
+    def core
+      @core ||= Core.new
+    end
+
+    # Vendor manager instance
+    def vendor_manager
+      @vendor_manager ||= VendorManager.new(configuration)
+    end
+
+    # Delegate common methods to core
+    def init!
+      core.init!
+    end
+
+    def install!(package_name, version = nil)
+      core.install!(package_name, version)
+    end
+
+    def update!(package_name, version = nil)
+      core.update!(package_name, version)
+    end
+
+    def remove!(package_name)
+      core.remove!(package_name)
+    end
+
+    def sync!
+      core.sync!
+    end
+
+    def status!
+      core.status!
+    end
+
+    def clean!
+      core.clean!
+    end
+
+    def package_installed?(package_name)
+      core.package_installed?(package_name)
+    end
+
+    def version_for(library_name)
+      core.version_for(library_name)
+    end
+
+    def detect_global_name(package_name)
+      core.detect_global_name(package_name)
+    end
+
+    def find_working_island_url(package_name, version)
+      core.find_working_island_url(package_name, version)
+    end
+  end
+end

data/lib/templates/app/controllers/islandjs_demo_controller.rb

@@ -0,0 +1,9 @@
+class IslandjsDemoController < ApplicationController
+  def index
+    # IslandJS Rails demo homepage
+  end
+  
+  def react
+    # Demo route for showcasing IslandJS React integration
+  end
+end

data/lib/templates/app/javascript/islands/components/HelloWorld.jsx

@@ -0,0 +1,117 @@
+import React, { useState, useEffect } from 'react';
+import { useTurboProps, useTurboCache } from '../utils/turbo.js';
+
+const HelloWorld = ({ containerId }) => {
+  // Get initial state from the div's data-initial-state attribute
+  const initialProps = useTurboProps(containerId);
+  
+  // Component state with defaults, restored from turbo cache if available
+  const [count, setCount] = useState(initialProps.count || 0);
+  const [message, setMessage] = useState(initialProps.message || "Hello from IslandJS Rails!");
+  const [customMessage, setCustomMessage] = useState(initialProps.customMessage || '');
+
+  // Current state object for turbo caching
+  const currentState = {
+    count,
+    message,
+    customMessage
+  };
+
+  // Setup turbo cache persistence - this should run on mount and whenever state changes
+  useEffect(() => {
+    const cleanup = useTurboCache(containerId, currentState, true);
+    return cleanup;
+  }, [containerId, count, message, customMessage]);
+
+  const handleMessageChange = (e) => {
+    setCustomMessage(e.target.value);
+  };
+
+  const applyCustomMessage = () => {
+    if (customMessage.trim()) {
+      setMessage(customMessage.trim());
+      setCustomMessage('');
+    }
+  };
+
+  return (
+    <div style={{
+      padding: '20px',
+      border: '2px solid #4F46E5',
+      borderRadius: '8px',
+      backgroundColor: '#F8FAFC',
+      textAlign: 'center',
+      fontFamily: 'system-ui, sans-serif'
+    }}>
+      <h2 style={{ color: '#4F46E5', margin: '0 0 16px 0' }}>
+        🏝️ React + IslandjsRails (Turbo-Cache Compatible)
+      </h2>
+      <p style={{ margin: '0 0 16px 0', fontSize: '18px' }}>
+        {message}
+      </p>
+      
+      <div style={{ margin: '16px 0' }}>
+        <input
+          type="text"
+          placeholder="Enter custom message"
+          value={customMessage}
+          onChange={handleMessageChange}
+          style={{
+            padding: '8px',
+            marginRight: '8px',
+            border: '1px solid #D1D5DB',
+            borderRadius: '4px',
+            fontSize: '14px'
+          }}
+        />
+        <button
+          onClick={applyCustomMessage}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: '#059669',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: 'pointer',
+            fontSize: '14px',
+            marginRight: '8px'
+          }}
+        >
+          Apply Message
+        </button>
+      </div>
+
+      <button
+        onClick={() => setCount(count + 1)}
+        style={{
+          padding: '8px 16px',
+          backgroundColor: '#4F46E5',
+          color: 'white',
+          border: 'none',
+          borderRadius: '4px',
+          cursor: 'pointer',
+          fontSize: '16px'
+        }}
+      >
+        Clicked {count} times
+      </button>
+
+      <div style={{ 
+        marginTop: '16px', 
+        fontSize: '12px', 
+        color: '#6B7280',
+        textAlign: 'left',
+        backgroundColor: '#F9FAFB',
+        padding: '12px',
+        borderRadius: '4px'
+      }}>
+        <strong>Turbo-Cache Demo:</strong>
+        <br />• Navigate away and back - your count and message persist!
+        <br />• Container ID: <code>{containerId}</code>
+        <br />• State: <code>{JSON.stringify(currentState)}</code>
+      </div>
+    </div>
+  );
+};
+
+export default HelloWorld;

data/lib/templates/app/javascript/islands/index.js

@@ -0,0 +1,10 @@
+// IslandJS Rails - Main entry point
+// This file is the webpack entry point for your JavaScript islands
+
+// React component imports
+import HelloWorld from './components/HelloWorld.jsx';
+
+// Mount components to the global islandjsRails namespace
+window.islandjsRails = {
+  HelloWorld
+};

data/lib/templates/app/javascript/islands/utils/turbo.js

@@ -0,0 +1,87 @@
+// Turbo-compatible state management utilities for React components
+
+/**
+ * Get initial state from a container's data-initial-state attribute
+ * @param {string} containerId - The ID of the container element
+ * @returns {Object} - Parsed initial state object
+ */
+export function useTurboProps(containerId) {
+  const container = document.getElementById(containerId);
+  if (!container) {
+    console.warn(`IslandJS Turbo: Container ${containerId} not found`);
+    return {};
+  }
+
+  const initialStateJson = container.dataset.initialState;
+  if (!initialStateJson) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(initialStateJson);
+  } catch (e) {
+    console.warn('IslandJS Turbo: Failed to parse initial state', e);
+    return {};
+  }
+}
+
+/**
+ * Set up Turbo cache persistence for React component state
+ * @param {string} containerId - The ID of the container element
+ * @param {Object} currentState - Current component state to persist
+ * @param {boolean} autoRestore - Whether to automatically restore state on turbo:load
+ * @returns {Function} - Cleanup function to remove event listeners
+ */
+export function useTurboCache(containerId, currentState, autoRestore = true) {
+  const container = document.getElementById(containerId);
+  if (!container) {
+    console.warn(`IslandJS Turbo: Container ${containerId} not found for caching`);
+    return () => {};
+  }
+
+  // Immediately persist the current state to the div (don't wait for turbo:before-cache)
+  try {
+    const stateJson = JSON.stringify(currentState);
+    container.dataset.initialState = stateJson;
+  } catch (e) {
+    console.warn('IslandJS Turbo: Failed to immediately serialize state', e);
+  }
+}
+
+/**
+ * Hook for React components to automatically manage Turbo cache persistence
+ * This is a React hook that should be called from within a React component
+ * @param {string} containerId - The ID of the container element
+ * @param {Object} state - Current component state to persist
+ * @param {Array} dependencies - Dependencies array for useEffect
+ */
+export function useTurboCacheEffect(containerId, state, dependencies = []) {
+  // This assumes React is available globally
+  if (typeof React !== 'undefined' && React.useEffect) {
+    React.useEffect(() => {
+      return useTurboCache(containerId, state, false);
+    }, [containerId, ...dependencies]);
+  } else {
+    console.warn('IslandJS Turbo: React.useEffect not available for useTurboCacheEffect');
+  }
+}
+
+/**
+ * Manually persist state to container for components that don't use the hook
+ * @param {string} containerId - The ID of the container element  
+ * @param {Object} state - State object to persist
+ */
+export function persistState(containerId, state) {
+  const container = document.getElementById(containerId);
+  if (!container) {
+    console.warn(`IslandJS Turbo: Container ${containerId} not found for state persistence`);
+    return;
+  }
+
+  try {
+    const stateJson = JSON.stringify(state);
+    container.dataset.initialState = stateJson;
+  } catch (e) {
+    console.warn('IslandJS Turbo: Failed to serialize state', e);
+  }
+}