islandjs-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d78a2c4f572cfe85c3a5a220463132357e77077654fd8445a0b44fc98035f991
-  data.tar.gz: 5e5db353b07167587ad36572da27688ecb7409eec0124ede59a41604831f0c7a
+  metadata.gz: 26c1475ed8f02b2c2c3217af0e96e95d3444083e94a35b9094d46170d0d88f00
+  data.tar.gz: ed6cd8e18382dcc1445b861f55b46aa7d1624ec4c4f9d063b2a0c87c1cb372a3
 SHA512:
-  metadata.gz: 79d300dd1047994557c217aaae37aa88cda075d1b5aeb4d3f8d95de635add49441102bdda8622fb528ba6e0c1202bcc2746381a50505a2fac37606120160f696
-  data.tar.gz: 2acd431790e153784cb7e78eb31973684afdbc02c02510c4b393e724f12c44b0dd204550b91ae4e5b0bf7cf60fbcaa19519644a0abaf708c59f342ec27e0714a
+  metadata.gz: dac3858a5b178e3186850a22e01beed9b384ecd053cc653ee5572743bdef78562cf17c5b51a8c6d51a7f08fecd2aca31fd82cbb830339508c85c2daf1a69f4b4
+  data.tar.gz: 3887d3aad9bcc0072df24e933804daf4827e097eec4baa2ec7945d184e23356f819bb45d9f5fb2f74642a89a10573561642c532f8340d8f5051e8c4ec506a01d

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-01-04
+
+### Added
+- **Placeholder Support**: New placeholder functionality for `react_component` helper to prevent layout shift during component mounting
+- **Three Placeholder Patterns**: ERB block, CSS class, and inline style options for maximum flexibility
+- **Turbo Stream Optimization**: Perfect integration with Turbo Stream updates to eliminate "jumpy" content behavior
+- **Automatic Cleanup**: Leverages React's natural DOM replacement for reliable placeholder removal
+- **Error Handling**: Graceful fallback that keeps placeholder visible if React fails to mount
+
+### Enhanced
+- `react_component` helper now accepts optional block for custom placeholder content
+- Added `placeholder_class` and `placeholder_style` options for quick placeholder styling
+- Improved error resilience in React mounting process
+
+### Documentation
+- Comprehensive placeholder documentation with real-world examples
+- Turbo Stream integration patterns and best practices
+- Updated helper method signatures and available options
+
 ## [0.1.0] - 2025-08-04
 
 ### Added

data/README.md

@@ -38,6 +38,11 @@ rails "islandjs:install[react-dom,18.3.1]"
 ```erb
 <!-- In any view -->
 <%= react_component('DashboardApp', { userId: current_user.id }) %>
+
+<!-- With placeholder (v0.2.0+) to prevent layout shift -->
+<%= react_component('DashboardApp', { userId: current_user.id }) do %>
+  <div class="loading-skeleton">Loading dashboard...</div>
+<% end %>
 ```
 
 > 💡 **Turbo Cache Compatible**: React components automatically persist state across Turbo navigation! See [Turbo Cache Integration](#turbo-cache-integration) for details.
@@ -98,13 +103,24 @@ Modern Rails developers face a painful choice:
 
 ### The IslandJS Rails Solution
 ```bash
-# Instead of complex webpack configuration:
-rails "islandjs:install[react]"
+# Instead of complex vite/webpack configuration:
+rails "islandjs:install[react,18.3.1]"
+rails "islandjs:install[react-beautiful-dnd]"
+rails "islandjs:install[quill]"
+rails "islandjs:install[recharts]"
 rails "islandjs:install[lodash]"
 ```
 
 **Result**: Zero-to-no webpack configuration, instant prod builds, access to hundreds of UMD packages.
 
+### Access UMD installed JS packages via the window from within React components:
+```bash
+\\ in SomeComponent.jsx
+const quill = new window.Quill("#editor", {
+  theme: "snow",
+});
+```
+
 ## Rails 8 Ready
 
 ✅ **Tested against Rails 8**  
@@ -119,6 +135,7 @@ rails "islandjs:install[lodash]"
 - **CDN Downloads** - Fetches UMD builds from unpkg.com and jsdelivr.net
 - **Rails Integration** - Serves auto-generated vendor UMD files for seamless integration
 - **Webpack Externals** - Updates webpack config to prevent duplicate bundling while allowing development in jsx or other formats
+- **Placeholder Support** - Eliminate layout shift with automatic placeholder management ⚡ *New in v0.2.0*
 - **Flexible Architecture** - Compose and namespace libraries as needed
 
 ## CLI Commands
@@ -363,8 +380,8 @@ This automatically loads:
 - Your webpack bundle
 - Debug information in development
 
-#### `react_component(name, props, options)`
-Renders a React component with Turbo-compatible lifecycle.
+#### `react_component(name, props, options, &block)`
+Renders a React component with Turbo-compatible lifecycle and optional placeholder support.
 
 ```erb
 <%= react_component('UserProfile', { 
@@ -376,6 +393,92 @@ Renders a React component with Turbo-compatible lifecycle.
 }) %>
 ```
 
+**Available Options:**
+- `container_id`: Custom ID for the container element
+- `namespace`: JavaScript namespace for component access (default: `window.islandjsRails`)
+- `tag`: HTML tag for container (default: `div`)
+- `class`: CSS class for container
+- `placeholder_class`: CSS class for placeholder content
+- `placeholder_style`: Inline styles for placeholder content
+
+## Placeholder Support
+
+⚡ **New in v0.2.0** - Prevent layout shift when React components mount!
+
+The `react_component` helper now supports placeholder content that displays while your React component loads, eliminating the "jumpy" effect common in dynamic content updates via Turbo Streams.
+
+### Problem Solved
+
+When React components mount (especially via Turbo Stream updates), there's often a brief moment where content height changes, causing layout shift:
+
+```erb
+<!-- Before: Content jumps when component mounts -->
+<%= react_component("Reactions", { postId: post.id }) %>
+<!-- Page content shifts down when reactions component renders -->
+```
+
+### Solution: Three Placeholder Patterns
+
+#### 1. ERB Block Placeholder (Most Flexible)
+```erb
+<%= react_component("Reactions", { postId: post.id }) do %>
+  <div class="reactions-skeleton">
+    <div class="skeleton-button">👍</div>
+    <div class="skeleton-button">❤️</div>
+    <div class="skeleton-button">🚀</div>
+    <div class="skeleton-count">Loading...</div>
+  </div>
+<% end %>
+```
+
+#### 2. CSS Class Placeholder (Design System Friendly)
+```erb
+<%= react_component("Reactions", { postId: post.id }, {
+  placeholder_class: "reactions-skeleton"
+}) %>
+```
+
+#### 3. Inline Style Placeholder (Quick & Simple)
+```erb
+<%= react_component("Reactions", { postId: post.id }, {
+  placeholder_style: "height: 40px; background: #f8f9fa; border-radius: 4px;"
+}) %>
+```
+
+### How It Works
+
+1. **Placeholder renders** immediately with your ERB content or styles
+2. **React mounts** and automatically replaces the entire container contents
+3. **Zero manual cleanup** - React's natural DOM replacement handles removal
+4. **On mount errors** - placeholder stays visible as graceful fallback
+
+### Perfect for Turbo Streams
+
+Placeholders shine in Turbo Stream scenarios where content updates dynamically:
+
+```erb
+<!-- app/views/posts/_reactions.html.erb -->
+<%= turbo_stream.replace "post_#{@post.id}_reactions" do %>
+  <%= react_component("Reactions", { 
+    postId: @post.id, 
+    initialCount: @post.reactions.count 
+  }) do %>
+    <div class="reactions-placeholder" style="height: 32px;">
+      <span class="text-muted">Loading reactions...</span>
+    </div>
+  <% end %>
+<% end %>
+```
+
+### Benefits
+
+- ✅ **Eliminates layout shift** during component mounting
+- ✅ **Turbo Stream compatible** - perfect for dynamic updates  
+- ✅ **Zero JavaScript required** - handled automatically by the helper
+- ✅ **Graceful degradation** - placeholder persists if React fails to load
+- ✅ **Design system friendly** - use your existing skeleton/loading styles
+- ✅ **Performance optimized** - leverages React's natural DOM clearing
+
 ## Turbo Cache Integration
 
 IslandJS Rails includes **built-in Turbo cache compatibility** for React components, ensuring state persists seamlessly across navigation.
@@ -751,4 +854,4 @@ Planned features for future releases:
 ### 🎯 **Developer Experience**
 - **Zero Webpack Expertise**: Rails developers stay in Rails
 - **Turbo Compatible**: Seamless navigation and caching
-- **Progressive Enhancement**: Start with Hotwire, add React islands
+- **Progressive Enhancement**: Start with Hotwire, add React islands

data/lib/islandjs_rails/core_methods.rb

@@ -398,7 +398,8 @@ module IslandjsRails
       response = Net::HTTP.get_response(uri)
       
       if response.code == '200'
-        response.body
+        # Force UTF-8 encoding to avoid encoding errors when writing to file
+        response.body.force_encoding('UTF-8')
       else
         raise IslandjsRails::Error, "Failed to download UMD from #{url}: #{response.code}"
       end

data/lib/islandjs_rails/rails_helpers.rb

@@ -49,7 +49,8 @@ module IslandjsRails
     end
 
     # Mount a React component with props and Turbo-compatible lifecycle
-    def react_component(component_name, props = {}, options = {})
+    # Supports optional placeholder content via block or options
+    def react_component(component_name, props = {}, options = {}, &block)
       # Generate component ID - use custom container_id if provided
       if options[:container_id]
         component_id = options[:container_id]
@@ -62,6 +63,10 @@ module IslandjsRails
       css_class = options[:class] || ''
       namespace = options[:namespace] || 'window.islandjsRails'
       
+      # Handle placeholder options
+      placeholder_class = options[:placeholder_class]
+      placeholder_style = options[:placeholder_style]
+      
       # For turbo-cache compatibility, store initial state as JSON in data attribute
       initial_state_json = props.to_json
       
@@ -95,7 +100,24 @@ module IslandjsRails
       # Add data-initial-state for turbo-cache compatibility
       initial_state_attr = " data-initial-state=\"#{initial_state_json.gsub('"', '"')}\""
       
-      container_html = "<#{tag_name} id=\"#{component_id}\"#{class_part}#{data_part}#{initial_state_attr}></#{tag_name}>"
+      # Generate placeholder content
+      placeholder_content = if block_given?
+        placeholder_html = capture(&block)
+        "<div data-island-placeholder=\"true\">#{placeholder_html}</div>"
+      elsif placeholder_class || placeholder_style
+        class_attr = placeholder_class ? " class=\"#{placeholder_class}\"" : ""
+        style_attr = placeholder_style ? " style=\"#{placeholder_style}\"" : ""
+        "<div data-island-placeholder=\"true\"#{class_attr}#{style_attr}></div>"
+      else
+        ""
+      end
+      
+      # Build container HTML with optional placeholder
+      if placeholder_content.empty?
+        container_html = "<#{tag_name} id=\"#{component_id}\"#{class_part}#{data_part}#{initial_state_attr}></#{tag_name}>"
+      else
+        container_html = "<#{tag_name} id=\"#{component_id}\"#{class_part}#{data_part}#{initial_state_attr}>#{placeholder_content}</#{tag_name}>"
+      end
       
       html_safe_string("#{container_html}\n#{mount_script}")
     end
@@ -241,30 +263,48 @@ module IslandjsRails
         <script>
           (function() {
             function mount#{component_name}() {
+              const container = document.getElementById('#{component_id}');
+              if (!container) return;
+              
+              // Check for component availability
               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.');
+                // Restore placeholder visibility if component fails to load
+                const placeholder = container.querySelector('[data-island-placeholder="true"]');
+                if (placeholder) {
+                  placeholder.style.display = '';
+                }
                 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]"');
+                // Restore placeholder visibility if React fails to load
+                const placeholder = container.querySelector('[data-island-placeholder="true"]');
+                if (placeholder) {
+                  placeholder.style.display = '';
+                }
                 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);
+              try {
+                // 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);
+                  // React 18 automatically clears container - no manual cleanup needed
+                } else {
+                  // React 17 - render is synchronous and clears container automatically
+                  window.ReactDOM.render(element, container);
                 }
-                container._reactRoot.render(element);
-              } else {
-                window.ReactDOM.render(element, container);
+              } catch (error) {
+                console.error('IslandJS: Failed to mount #{component_name}:', error);
+                // On error, keep placeholder visible by not modifying container
               }
             }
             

data/lib/islandjs_rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: islandjs-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Eric Arnold