pagy_infinite_scroll 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b9818e60d4272ee1490013e0c73ed9afbcf7ba081420668c7b1ecfd5e3b3685
-  data.tar.gz: f01be9e52a172cc5e18f96ca63ce5f6e21e991d16152a1fd771a686c7bba3511
+  metadata.gz: b82bfda46dc2de115eeaac522f4f982df35e6517413522ff12446bef637e3b03
+  data.tar.gz: abf34ba36bdf896c79a4fb723b287d65c55d70f5487bcec92259486f41c1bb28
 SHA512:
-  metadata.gz: 3f8f33471cc148d24c5745c6841c72a2bf8e3f919a5ba0cc8007fb71908072fc20b6ae4156e5f994c10ac3c9286d4081efadce8f6703174ad8849cb770bea143
-  data.tar.gz: ffdf94c5b5ef5310ab7fe7916257e7e67e8153c877ced315fa890b550405988b08c4a3a8a81df27d876cdea3c2f07890a48de130e285a2b6e2ba8f7aa13c60c4
+  metadata.gz: 2655b2c6353d27bd94f8839aeaa1203c0ab6a3f13e2f4a38b409760fefb31dcabcab48b2dc4519c1153d1688cbaea908be022dae1fb6aab8069caba61234aadf
+  data.tar.gz: 4e6d2003f79144666d2ca6f28d20bca2d29613c1ca52a1d2f1266510adadc5cef07277f0723b0d1674a239de14209050445a920b26f6d05d18977ba3151d6be8

data/README.md

@@ -16,7 +16,7 @@ A Rails gem that adds infinite scroll functionality using Pagy and Stimulus. Loa
 Add to your Gemfile:
 
 ```ruby
-gem 'pagy_infinite_scroll', github: 'hassanharoon86/pagy_infinite_scroll'
+gem 'pagy_infinite_scroll', '~> 0.2.0'
 ```
 
 Then run:
@@ -44,6 +44,19 @@ The generator will:
 
 ## Quick Start
 
+This gem provides **two approaches** for infinite scrolling:
+
+1. **Server-Side Rendering** (Simple) - HTML rendered on the server using `.js.erb` templates
+2. **JSON API** (Advanced) - JSON responses with client-side HTML rendering
+
+Choose the approach that fits your needs!
+
+---
+
+## Approach 1: Server-Side Rendering (Recommended for Simple Use Cases)
+
+This approach is simpler and requires minimal JavaScript knowledge. Perfect for standard CRUD operations.
+
 ### 1. Controller Setup
 
 Use the gem's helper methods:
@@ -51,13 +64,61 @@ Use the gem's helper methods:
 ```ruby
 class ProductsController < ApplicationController
   def index
-    # Use pagy_infinite_scroll instead of regular pagy
+    @pagy, @products = pagy_infinite_scroll(Product.all, limit: 50)
+
+    respond_to do |format|
+      format.html
+      format.js  # Responds to .js.erb template
+    end
+  end
+end
+```
+
+### 2. View Setup (HTML)
+
+```erb
+<!-- app/views/products/index.html.erb -->
+<%= infinite_scroll_container(@pagy, products_path(format: :js),
+      data: { render_mode: 'js' }) do %>
+  <%= infinite_scroll_items_container(tag: 'div', class: 'products-list') do %>
+    <%= render @products %>
+  <% end %>
+  <%= infinite_scroll_loading_indicator %>
+<% end %>
+```
+
+### 3. Create JavaScript Response Template
+
+```erb
+<!-- app/views/products/index.js.erb -->
+<%= pagy_infinite_scroll_append '.products-list', @pagy, @products %>
+```
+
+**That's it!** The gem automatically:
+- Renders your `_product.html.erb` partial for each item
+- Appends the HTML to the container
+- Updates pagination state
+- No JavaScript customization needed!
+
+---
+
+## Approach 2: JSON API (For Complex Use Cases)
+
+Use this approach when you need:
+- API reusability (mobile apps, SPAs)
+- Complex client-side logic
+- Full control over rendering
+
+### 1. Controller Setup
+
+```ruby
+class ProductsController < ApplicationController
+  def index
     @pagy, @products = pagy_infinite_scroll(Product.all, limit: 50)
 
     respond_to do |format|
       format.html
       format.json do
-        # Use the JSON helper to format response
         render json: pagy_infinite_scroll_json(@pagy, @products) { |product|
           {
             id: product.id,
@@ -73,45 +134,18 @@ end
 
 ### 2. View Setup
 
-Add the infinite scroll container to your view:
-
 ```erb
-<div data-controller="pagy-infinite-scroll"
-     data-pagy-infinite-scroll-url-value="<%= products_path(format: :json) %>"
-     data-pagy-infinite-scroll-page-value="1"
-     data-pagy-infinite-scroll-has-more-value="<%= @pagy.next.present? %>"
-     style="max-height: 600px; overflow-y: auto;">
-
-  <!-- Container for items -->
-  <div data-pagy-infinite-scroll-target="itemsContainer">
-    <% @products.each do |product| %>
-      <div class="product-card">
-        <h3><%= product.title %></h3>
-        <p><%= product.price %></p>
-      </div>
-    <% end %>
-  </div>
-
-  <!-- Loading indicator -->
-  <div data-pagy-infinite-scroll-target="loadingIndicator" class="hidden">
-    <p>Loading more...</p>
-  </div>
-</div>
+<%= infinite_scroll_container(@pagy, products_path(format: :json)) do %>
+  <%= infinite_scroll_items_container do %>
+    <%= render @products %>
+  <% end %>
+  <%= infinite_scroll_loading_indicator %>
+<% end %>
 ```
 
-## ⚠️ Important: Custom HTML Rendering
-
-**The gem provides the core infinite scroll functionality, but you need to tell it how to render YOUR specific HTML.**
-
-### Why?
-
-The gem cannot know:
-- Your specific HTML structure (forms, checkboxes, badges, etc.)
-- Your CSS classes and styling
-- Your form field names
-- Your Stimulus action targets
+### 3. Create Custom Stimulus Controller
 
-### Solution: Extend the Controller
+**For JSON API approach, you MUST override the `createItemHTML` method** to tell the gem how to render your specific HTML.
 
 **For jsbundling-rails apps:**
 
@@ -221,11 +255,12 @@ Edit `config/initializers/pagy_infinite_scroll.rb`:
 
 ```ruby
 PagyInfiniteScroll.configure do |config|
-  config.items_per_page = 50      # Items per page (default: 25)
+  config.items_per_page = 50      # Items per page (default: 50)
   config.scroll_threshold = 100   # Pixels from bottom to trigger load (default: 100)
   config.loading_indicator = true # Show loading indicator (default: true)
   config.preserve_state = true    # Preserve URL params (default: true)
   config.debounce_delay = 500     # Debounce for search in ms (default: 500)
+  config.render_mode = 'json'     # Rendering mode: 'json' or 'js' (default: 'json')
 end
 ```
 

data/app/assets/javascripts/pagy_infinite_scroll/infinite_scroll_controller.js

@@ -10,7 +10,8 @@ export default class PagyInfiniteScrollController extends Controller {
     loading: Boolean,
     hasMore: Boolean,
     threshold: { type: Number, default: 100 },
-    preserveState: { type: Boolean, default: true }
+    preserveState: { type: Boolean, default: true },
+    renderMode: { type: String, default: 'json' } // 'json' or 'js'
   }
 
   connect() {
@@ -19,6 +20,9 @@ export default class PagyInfiniteScrollController extends Controller {
     this.loadingValue = false
     this.boundHandleScroll = this.handleScroll.bind(this)
     this.element.addEventListener('scroll', this.boundHandleScroll)
+
+    // Make controller accessible for server-side updates
+    this.element.pagyInfiniteScroll = this
   }
 
   disconnect() {
@@ -55,9 +59,14 @@ export default class PagyInfiniteScrollController extends Controller {
         }
       })
 
+      // Determine Accept header based on render mode
+      const acceptHeader = this.renderModeValue === 'js'
+        ? 'text/javascript, application/javascript, application/ecmascript, application/x-ecmascript'
+        : 'application/json'
+
       const response = await fetch(url, {
         headers: {
-          'Accept': 'application/json',
+          'Accept': acceptHeader,
           'X-Requested-With': 'XMLHttpRequest'
         }
       })
@@ -66,32 +75,41 @@ export default class PagyInfiniteScrollController extends Controller {
         throw new Error(`HTTP error! status: ${response.status}`)
       }
 
-      const data = await response.json()
-
-      // Dispatch event with data for custom handling
-      const event = this.dispatch('beforeAppend', {
-        detail: { data },
-        cancelable: true
-      })
-
-      if (!event.defaultPrevented) {
-        this.appendItems(data)
-      }
+      // Handle different response types
+      if (this.renderModeValue === 'js') {
+        // For .js.erb responses, evaluate the JavaScript
+        const jsCode = await response.text()
+        eval(jsCode)
+        // Note: State is updated by the server-rendered JS via pagy_infinite_scroll_append
+      } else {
+        // For JSON responses, use the client-side rendering
+        const data = await response.json()
+
+        // Dispatch event with data for custom handling
+        const event = this.dispatch('beforeAppend', {
+          detail: { data },
+          cancelable: true
+        })
+
+        if (!event.defaultPrevented) {
+          this.appendItems(data)
+        }
 
-      // Update pagination state
-      this.pageValue = data.pagy.page
-      this.hasMoreValue = data.pagy.next !== null
+        // Update pagination state
+        this.pageValue = data.pagy.page
+        this.hasMoreValue = data.pagy.next !== null
 
-      console.log(`[PagyInfiniteScroll] Loaded page ${this.pageValue}, has more: ${this.hasMoreValue}`)
+        console.log(`[PagyInfiniteScroll] Loaded page ${this.pageValue}, has more: ${this.hasMoreValue}`)
 
-      // Dispatch success event
-      this.dispatch('loaded', {
-        detail: {
-          page: this.pageValue,
-          hasMore: this.hasMoreValue,
-          count: data.records.length
-        }
-      })
+        // Dispatch success event
+        this.dispatch('loaded', {
+          detail: {
+            page: this.pageValue,
+            hasMore: this.hasMoreValue,
+            count: data.records.length
+          }
+        })
+      }
 
     } catch (error) {
       console.error('[PagyInfiniteScroll] Error loading more items:', error)

data/app/assets/javascripts/pagy_infinite_scroll_controller.js

@@ -21,7 +21,8 @@
       loading: Boolean,
       hasMore: Boolean,
       threshold: { type: Number, default: 100 },
-      preserveState: { type: Boolean, default: true }
+      preserveState: { type: Boolean, default: true },
+      renderMode: { type: String, default: 'json' } // 'json' or 'js'
     }
 
     connect() {
@@ -30,6 +31,9 @@
       this.loadingValue = false
       this.boundHandleScroll = this.handleScroll.bind(this)
       this.element.addEventListener('scroll', this.boundHandleScroll)
+
+      // Make controller accessible for server-side updates
+      this.element.pagyInfiniteScroll = this
     }
 
     disconnect() {
@@ -66,9 +70,14 @@
           }
         })
 
+        // Determine Accept header based on render mode
+        const acceptHeader = this.renderModeValue === 'js'
+          ? 'text/javascript, application/javascript, application/ecmascript, application/x-ecmascript'
+          : 'application/json'
+
         const response = await fetch(url, {
           headers: {
-            'Accept': 'application/json',
+            'Accept': acceptHeader,
             'X-Requested-With': 'XMLHttpRequest'
           }
         })
@@ -77,32 +86,41 @@
           throw new Error(`HTTP error! status: ${response.status}`)
         }
 
-        const data = await response.json()
-
-        // Dispatch event with data for custom handling
-        const event = this.dispatch('beforeAppend', {
-          detail: { data },
-          cancelable: true
-        })
-
-        if (!event.defaultPrevented) {
-          this.appendItems(data)
-        }
+        // Handle different response types
+        if (this.renderModeValue === 'js') {
+          // For .js.erb responses, evaluate the JavaScript
+          const jsCode = await response.text()
+          eval(jsCode)
+          // Note: State is updated by the server-rendered JS via pagy_infinite_scroll_append
+        } else {
+          // For JSON responses, use the client-side rendering
+          const data = await response.json()
+
+          // Dispatch event with data for custom handling
+          const event = this.dispatch('beforeAppend', {
+            detail: { data },
+            cancelable: true
+          })
+
+          if (!event.defaultPrevented) {
+            this.appendItems(data)
+          }
 
-        // Update pagination state
-        this.pageValue = data.pagy.page
-        this.hasMoreValue = data.pagy.next !== null
+          // Update pagination state
+          this.pageValue = data.pagy.page
+          this.hasMoreValue = data.pagy.next !== null
 
-        console.log(`[PagyInfiniteScroll] Loaded page ${this.pageValue}, has more: ${this.hasMoreValue}`)
+          console.log(`[PagyInfiniteScroll] Loaded page ${this.pageValue}, has more: ${this.hasMoreValue}`)
 
-        // Dispatch success event
-        this.dispatch('loaded', {
-          detail: {
-            page: this.pageValue,
-            hasMore: this.hasMoreValue,
-            count: data.records.length
-          }
-        })
+          // Dispatch success event
+          this.dispatch('loaded', {
+            detail: {
+              page: this.pageValue,
+              hasMore: this.hasMoreValue,
+              count: data.records.length
+            }
+          })
+        }
 
       } catch (error) {
         console.error('[PagyInfiniteScroll] Error loading more items:', error)

data/lib/generators/pagy_infinite_scroll/install/install_generator.rb

@@ -53,7 +53,19 @@ module PagyInfiniteScroll
         end
 
         say "\n"
-        say "  3. Use in your controllers: pagy_infinite_scroll(collection)"
+        say "  3. Choose your rendering approach:", :yellow
+        say "\n"
+        say "     Option A: Server-Side Rendering (Simpler - Recommended for most apps)"
+        say "       - Use format.js in controller"
+        say "       - Create .js.erb template with: <%= pagy_infinite_scroll_append '.selector', @pagy, @records %>"
+        say "       - Set data-pagy-infinite-scroll-render-mode-value='js' in view"
+        say "       - No JavaScript customization needed!"
+        say "\n"
+        say "     Option B: JSON API (Advanced - For APIs/SPAs)"
+        say "       - Use format.json in controller"
+        say "       - Create custom Stimulus controller and override createItemHTML()"
+        say "       - Full control over client-side rendering"
+        say "\n"
         say "  4. See full documentation: https://github.com/hassanharoon86/pagy_infinite_scroll"
         say "\n"
       end

data/lib/generators/pagy_infinite_scroll/install/templates/initializer.rb

@@ -22,4 +22,12 @@ PagyInfiniteScroll.configure do |config|
   # Debounce delay for search in milliseconds
   # Default: 500
   config.debounce_delay = 500
+
+  # Default rendering mode for infinite scroll
+  # Options: 'json' (client-side rendering) or 'js' (server-side rendering with .js.erb)
+  # Default: 'json'
+  #
+  # 'json' mode: Requires custom Stimulus controller with createItemHTML() method
+  # 'js' mode: Uses server-rendered HTML via .js.erb templates (simpler, recommended for most apps)
+  config.render_mode = 'json'
 end

data/lib/pagy_infinite_scroll/configuration.rb

@@ -7,7 +7,8 @@ module PagyInfiniteScroll
                   :loading_indicator,
                   :auto_initialize,
                   :preserve_state,
-                  :debounce_delay
+                  :debounce_delay,
+                  :render_mode
 
     def initialize
       @items_per_page = 50
@@ -16,6 +17,7 @@ module PagyInfiniteScroll
       @auto_initialize = true
       @preserve_state = true
       @debounce_delay = 500 # milliseconds
+      @render_mode = 'json' # 'json' or 'js' (for .js.erb templates)
     end
   end
 end

data/lib/pagy_infinite_scroll/engine.rb

@@ -7,8 +7,9 @@ module PagyInfiniteScroll
     # Don't isolate namespace to allow helpers to load into main app
     engine_name 'pagy_infinite_scroll'
 
-    # Ensure lib files are loaded
-    config.eager_load_paths << File.expand_path("../../", __FILE__)
+    # Don't eager load lib directory - we manually require what we need
+    # This avoids Zeitwerk trying to autoload version.rb as a constant
+    config.eager_load_paths.delete(File.expand_path("../../", __FILE__))
 
     # Load assets if asset pipeline is available
     initializer "pagy_infinite_scroll.assets", before: :load_config_initializers do |app|

data/lib/pagy_infinite_scroll/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PagyInfiniteScroll
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/pagy_infinite_scroll/view_helper.rb

@@ -33,6 +33,7 @@ module PagyInfiniteScroll
                     pagy_infinite_scroll_page_value: pagy.page,
                     pagy_infinite_scroll_loading_value: false,
                     pagy_infinite_scroll_has_more_value: pagy.next.present?,
+                    pagy_infinite_scroll_render_mode_value: PagyInfiniteScroll.config.render_mode,
                     **stimulus_data_attributes(data_attrs)
                   } do
         block.call
@@ -93,6 +94,67 @@ module PagyInfiniteScroll
       end
     end
 
+    # Server-side rendering helper for .js.erb templates
+    # This provides a simpler alternative to the JSON API approach
+    #
+    # @param container_selector [String] jQuery/CSS selector for the container
+    # @param pagy [Pagy] The pagy object
+    # @param records [ActiveRecord::Relation, Array] Records or render options
+    # @param options [Hash] Rendering options
+    # @option options [String] :partial Partial path (if not using collection inference)
+    # @option options [Hash] :locals Additional local variables for the partial
+    #
+    # @example Simple usage (auto-detects partial from collection)
+    #   <%= pagy_infinite_scroll_append "#products", @pagy, @products %>
+    #
+    # @example With explicit partial
+    #   <%= pagy_infinite_scroll_append "#products", @pagy, @products, partial: "products/card" %>
+    #
+    # @example With locals
+    #   <%= pagy_infinite_scroll_append "#items", @pagy, @items, partial: "items/row", locals: { show_actions: true } %>
+    #
+    def pagy_infinite_scroll_append(container_selector, pagy, records, options = {})
+      # Render the HTML for the records
+      html = if options[:partial]
+               render partial: options[:partial], collection: records, locals: options[:locals] || {}
+             else
+               render records
+             end
+
+      # Escape the HTML for JavaScript
+      escaped_html = escape_javascript(html)
+
+      # Generate JavaScript to append items and update pagination state
+      javascript = <<~JS
+        (function() {
+          var container = document.querySelector('#{container_selector}');
+          if (container) {
+            container.insertAdjacentHTML('beforeend', '#{escaped_html}');
+
+            // Dispatch event for custom handling
+            var event = new CustomEvent('pagy-infinite-scroll:appended', {
+              detail: {
+                page: #{pagy.page},
+                hasMore: #{pagy.next.present?},
+                count: #{records.size}
+              }
+            });
+            document.dispatchEvent(event);
+
+            // Update controller values if using Stimulus controller
+            var scrollContainer = container.closest('[data-controller~="pagy-infinite-scroll"]');
+            if (scrollContainer && scrollContainer.pagyInfiniteScroll) {
+              scrollContainer.pagyInfiniteScroll.pageValue = #{pagy.page};
+              scrollContainer.pagyInfiniteScroll.hasMoreValue = #{pagy.next.present?};
+              scrollContainer.pagyInfiniteScroll.loadingValue = false;
+            }
+          }
+        })();
+      JS
+
+      javascript.html_safe
+    end
+
     private
 
     def spinner_svg

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pagy_infinite_scroll
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Hassan Haroon