pagy_infinite_scroll 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4030148cd309dc18ac97b40df152d44d8b6ba1895be2998c4d5f1a31e3855171
+  data.tar.gz: 341f3089353a36671eca179db57c402f7b028649cf839b6fb30a4437046aa2e9
+SHA512:
+  metadata.gz: efb49c31d7b1e5b665089e2332b4e37ea112faf763c9bbdacf95efe11968aaa08e3b5904f9a057ee97e2572bb15bc1bd70ee7547f0546b8e698d54851093f61d
+  data.tar.gz: 0ce1a7f8f8bd6bbbd1d4cda4f5fbc53def5b850c6e8adc683e46af8934e7544dca9b6855bd9616ccdb86fcef84c21213ca5322f0446fc28cec74d80f68a5a31a

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Hassan Haroon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,330 @@
+# PagyInfiniteScroll
+
+A Rails gem that adds infinite scroll functionality using Pagy and Stimulus. Load initial records and automatically fetch more as users scroll down - perfect for optimizing pages with large datasets.
+
+## Features
+
+- 🚀 Easy integration with existing Rails apps
+- 📦 Built on Pagy (fast, lightweight pagination)
+- ⚡ Stimulus controller for smooth infinite scrolling
+- 🎨 Customizable HTML rendering
+- 🔧 Configurable scroll threshold and items per page
+- 💾 Preserves URL parameters during scroll
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'pagy_infinite_scroll', github: 'hassanharoon86/pagy_infinite_scroll'
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate pagy_infinite_scroll:install
+```
+
+The generator will automatically detect your JavaScript setup and configure accordingly:
+
+### For importmap-rails (auto-configured ✅)
+The generator will:
+- Add pin to `config/importmap.rb`
+- Add import to `app/javascript/application.js`
+- Auto-register controller with Stimulus
+- **No manual steps needed!**
+
+### For jsbundling-rails (esbuild/webpack/rollup)
+The generator will:
+- Create `config/initializers/pagy_infinite_scroll.rb`
+- Copy controller to `app/javascript/controllers/pagy_infinite_scroll_controller.js`
+- Display registration instructions
+- Run `yarn build` after setup
+
+## Quick Start
+
+### 1. Controller Setup
+
+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.json do
+        # Use the JSON helper to format response
+        render json: pagy_infinite_scroll_json(@pagy, @products) { |product|
+          {
+            id: product.id,
+            title: product.title,
+            price: product.price
+          }
+        }
+      end
+    end
+  end
+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>
+```
+
+## ⚠️ 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
+
+### Solution: Extend the Controller
+
+**For jsbundling-rails apps:**
+
+Create a custom Stimulus controller that extends the gem's base controller:
+
+```javascript
+// app/javascript/controllers/products_scroll_controller.js
+import PagyInfiniteScrollController from "./pagy_infinite_scroll_controller"
+
+export default class extends PagyInfiniteScrollController {
+  // Override this method to customize HTML for loaded items
+  createItemHTML(record) {
+    return `
+      <div class="product-card">
+        <h3>${record.title}</h3>
+        <p class="price">$${record.price}</p>
+        <span class="badge">${record.category}</span>
+      </div>
+    `
+  }
+}
+```
+
+Register it in `app/javascript/controllers/index.js`:
+
+```javascript
+import ProductsScrollController from "./products_scroll_controller"
+application.register("products-scroll", ProductsScrollController)
+```
+
+**For importmap-rails apps:**
+
+The controller is available globally as `window.PagyInfiniteScrollController`:
+
+```javascript
+// app/javascript/controllers/products_scroll_controller.js
+class ProductsScrollController extends window.PagyInfiniteScrollController {
+  createItemHTML(record) {
+    return `
+      <div class="product-card">
+        <h3>${record.title}</h3>
+        <p class="price">$${record.price}</p>
+        <span class="badge">${record.category}</span>
+      </div>
+    `
+  }
+}
+
+// Register with Stimulus
+Stimulus.register("products-scroll", ProductsScrollController)
+```
+
+Use in your view:
+
+```erb
+<div data-controller="products-scroll"
+     data-products-scroll-url-value="<%= products_path(format: :json) %>"
+     data-products-scroll-page-value="1"
+     data-products-scroll-has-more-value="<%= @pagy.next.present? %>">
+  ...
+</div>
+```
+
+### Real-World Example: Form with Checkboxes
+
+```javascript
+// app/javascript/controllers/distribution_preferences_scroll_controller.js
+import PagyInfiniteScrollController from "./pagy_infinite_scroll_controller"
+
+export default class extends PagyInfiniteScrollController {
+  createItemHTML(record) {
+    const isChecked = record.selected ? 'checked' : ''
+
+    return `
+      <div class="flex items-center gap-4 p-4">
+        <input type="checkbox"
+               name="product_ids[]"
+               value="${record.id}"
+               id="product_${record.id}"
+               ${isChecked}
+               class="form-checkbox">
+
+        <label for="product_${record.id}" class="flex-1">
+          <div class="font-medium">${record.title}</div>
+          ${record.vendor_name ? `
+            <span class="badge">${record.vendor_name}</span>
+          ` : ''}
+          <span class="text-gray-500">
+            ${record.variants_count} variants
+          </span>
+        </label>
+      </div>
+    `
+  }
+}
+```
+
+**Key Points:**
+- Only ~60 lines of custom JavaScript needed
+- The gem handles all the scroll detection, AJAX, and state management
+- You only define the HTML structure for your specific use case
+- This keeps your code DRY and maintainable
+
+## Configuration
+
+Edit `config/initializers/pagy_infinite_scroll.rb`:
+
+```ruby
+PagyInfiniteScroll.configure do |config|
+  config.items_per_page = 50      # Items per page (default: 25)
+  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)
+end
+```
+
+## Data Attributes Reference
+
+### Container Attributes
+- `data-pagy-infinite-scroll-url-value` - JSON endpoint URL (required)
+- `data-pagy-infinite-scroll-page-value` - Current page number (default: 1)
+- `data-pagy-infinite-scroll-has-more-value` - Has more pages? (required, true/false)
+- `data-pagy-infinite-scroll-threshold-value` - Scroll threshold in pixels (optional)
+
+### Targets
+- `data-pagy-infinite-scroll-target="itemsContainer"` - Where to append items
+- `data-pagy-infinite-scroll-target="loadingIndicator"` - Loading indicator element
+
+## Events
+
+The controller dispatches custom events you can listen to:
+
+```javascript
+// In your custom controller
+connect() {
+  super.connect()
+
+  this.element.addEventListener('pagy-infinite-scroll:loaded', (event) => {
+    console.log('Loaded page:', event.detail.page)
+    console.log('Has more:', event.detail.hasMore)
+    console.log('Count:', event.detail.count)
+  })
+
+  this.element.addEventListener('pagy-infinite-scroll:error', (event) => {
+    console.error('Error:', event.detail.error)
+  })
+}
+```
+
+## Troubleshooting
+
+### Items not loading on scroll
+
+1. **Check browser console** for JavaScript errors
+2. **Verify JSON endpoint** returns correct format:
+   ```json
+   {
+     "records": [...],
+     "pagy": {
+       "page": 1,
+       "pages": 10,
+       "next": 2,
+       "count": 500
+     }
+   }
+   ```
+3. **Check Network tab** to see if AJAX requests are being made
+4. **Verify controller is connected** - should see console log on page load
+
+### Controller not found error
+
+Run `yarn build` (or `npm run build`) to rebuild JavaScript bundle.
+
+### Helpers not available in controller
+
+Restart your Rails server after installing the gem.
+
+### Items render as JSON instead of HTML
+
+You need to create a custom controller that extends the base controller and overrides the `createItemHTML()` method (see "Custom HTML Rendering" section above).
+
+## JavaScript Setup: importmap vs jsbundling
+
+This gem works with **both** importmap-rails and jsbundling-rails:
+
+### importmap-rails ✅
+- **Setup**: Automatic via generator
+- **Controller**: Standalone file, auto-registers with Stimulus
+- **Extending**: Use `window.PagyInfiniteScrollController` as base class
+- **Advantages**: Zero build step, simpler setup
+- **File location**: Served from gem's assets
+
+### jsbundling-rails (esbuild/webpack/rollup) ✅
+- **Setup**: Manual file copy (bundlers can't access gem paths)
+- **Controller**: Import from `./pagy_infinite_scroll_controller`
+- **Extending**: Use ES6 `import` and `extends`
+- **Advantages**: Full ES6 module support, tree-shaking
+- **File location**: `app/javascript/controllers/`
+
+Both setups support the same features and API!
+
+## Requirements
+
+- Rails 7.0+
+- Pagy gem (add `gem 'pagy'` to your Gemfile)
+- Stimulus (Hotwire)
+- Either importmap-rails OR jsbundling-rails (esbuild, webpack, or rollup)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hassanharoon86/pagy_infinite_scroll/issues
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

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

@@ -0,0 +1,13 @@
+// Pagy Infinite Scroll - Main Entry Point
+// This file provides the controller for manual registration
+
+import PagyInfiniteScrollController from "./infinite_scroll_controller"
+
+// Export for manual registration in host app
+export { PagyInfiniteScrollController }
+export default PagyInfiniteScrollController
+
+// Auto-register if Stimulus application is available globally
+if (typeof window !== 'undefined' && window.Stimulus) {
+  window.Stimulus.register("pagy-infinite-scroll", PagyInfiniteScrollController)
+}

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

@@ -0,0 +1,151 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Infinite Scroll Controller for Pagy
+// Can be used standalone or extended
+export default class PagyInfiniteScrollController extends Controller {
+  static targets = ['itemsContainer', 'loadingIndicator']
+  static values = {
+    url: String,
+    page: Number,
+    loading: Boolean,
+    hasMore: Boolean,
+    threshold: { type: Number, default: 100 },
+    preserveState: { type: Boolean, default: true }
+  }
+
+  connect() {
+    console.log('[PagyInfiniteScroll] Controller connected')
+    this.pageValue = this.pageValue || 1
+    this.loadingValue = false
+    this.boundHandleScroll = this.handleScroll.bind(this)
+    this.element.addEventListener('scroll', this.boundHandleScroll)
+  }
+
+  disconnect() {
+    this.element.removeEventListener('scroll', this.boundHandleScroll)
+  }
+
+  handleScroll() {
+    const scrollThreshold = this.hasThresholdValue ? this.thresholdValue : 100
+    const nearBottom = this.element.scrollHeight - this.element.scrollTop - this.element.clientHeight < scrollThreshold
+
+    if (nearBottom && !this.loadingValue && this.hasMoreValue) {
+      this.loadMore()
+    }
+  }
+
+  async loadMore() {
+    if (this.loadingValue || !this.hasMoreValue) return
+
+    console.log('[PagyInfiniteScroll] Loading more items...')
+    this.loadingValue = true
+    this.showLoading()
+
+    const nextPage = this.pageValue + 1
+
+    try {
+      const url = new URL(this.urlValue, window.location.origin)
+      url.searchParams.set('page', nextPage)
+
+      // Preserve current URL parameters
+      const currentParams = new URLSearchParams(window.location.search)
+      currentParams.forEach((value, key) => {
+        if (key !== 'page') {
+          url.searchParams.set(key, value)
+        }
+      })
+
+      const response = await fetch(url, {
+        headers: {
+          'Accept': 'application/json',
+          'X-Requested-With': 'XMLHttpRequest'
+        }
+      })
+
+      if (!response.ok) {
+        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)
+      }
+
+      // 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}`)
+
+      // 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)
+      this.dispatch('error', { detail: { error } })
+    } finally {
+      this.loadingValue = false
+      this.hideLoading()
+    }
+  }
+
+  appendItems(data) {
+    if (!this.hasItemsContainerTarget) {
+      console.warn('[PagyInfiniteScroll] No items container target found')
+      return
+    }
+
+    const records = data.records || data.items || data.products || []
+
+    records.forEach(record => {
+      const html = this.createItemHTML(record)
+      this.itemsContainerTarget.insertAdjacentHTML('beforeend', html)
+    })
+  }
+
+  createItemHTML(record) {
+    // This method should be overridden by the application
+    // or use a custom event listener
+    console.warn('[PagyInfiniteScroll] createItemHTML should be overridden')
+    return `<div>${JSON.stringify(record)}</div>`
+  }
+
+  showLoading() {
+    if (this.hasLoadingIndicatorTarget) {
+      this.loadingIndicatorTarget.classList.remove('hidden')
+    }
+  }
+
+  hideLoading() {
+    if (this.hasLoadingIndicatorTarget) {
+      this.loadingIndicatorTarget.classList.add('hidden')
+    }
+  }
+
+  // Public API methods
+  reset() {
+    this.pageValue = 1
+    this.hasMoreValue = true
+    if (this.hasItemsContainerTarget) {
+      this.itemsContainerTarget.innerHTML = ''
+    }
+  }
+
+  reload() {
+    this.reset()
+    this.loadMore()
+  }
+}

data/app/assets/javascripts/pagy_infinite_scroll_controller.js

@@ -0,0 +1,177 @@
+// Pagy Infinite Scroll Controller - Importmap Compatible Version
+// This is a standalone file that works with both importmap-rails and jsbundling-rails
+//
+// For importmap-rails: This file will be pinned and auto-loaded
+// For jsbundling-rails: Import from the modular version in app/javascript/controllers/
+
+// IIFE to avoid polluting global scope while still working with importmap
+(() => {
+  // Check if Stimulus is available
+  if (typeof Stimulus === 'undefined') {
+    console.error('[PagyInfiniteScroll] Stimulus is not loaded. Make sure @hotwired/stimulus is loaded before this controller.')
+    return
+  }
+
+  // Define the controller class
+  class PagyInfiniteScrollController extends Stimulus.Controller {
+    static targets = ['itemsContainer', 'loadingIndicator']
+    static values = {
+      url: String,
+      page: Number,
+      loading: Boolean,
+      hasMore: Boolean,
+      threshold: { type: Number, default: 100 },
+      preserveState: { type: Boolean, default: true }
+    }
+
+    connect() {
+      console.log('[PagyInfiniteScroll] Controller connected')
+      this.pageValue = this.pageValue || 1
+      this.loadingValue = false
+      this.boundHandleScroll = this.handleScroll.bind(this)
+      this.element.addEventListener('scroll', this.boundHandleScroll)
+    }
+
+    disconnect() {
+      this.element.removeEventListener('scroll', this.boundHandleScroll)
+    }
+
+    handleScroll() {
+      const scrollThreshold = this.hasThresholdValue ? this.thresholdValue : 100
+      const nearBottom = this.element.scrollHeight - this.element.scrollTop - this.element.clientHeight < scrollThreshold
+
+      if (nearBottom && !this.loadingValue && this.hasMoreValue) {
+        this.loadMore()
+      }
+    }
+
+    async loadMore() {
+      if (this.loadingValue || !this.hasMoreValue) return
+
+      console.log('[PagyInfiniteScroll] Loading more items...')
+      this.loadingValue = true
+      this.showLoading()
+
+      const nextPage = this.pageValue + 1
+
+      try {
+        const url = new URL(this.urlValue, window.location.origin)
+        url.searchParams.set('page', nextPage)
+
+        // Preserve current URL parameters
+        const currentParams = new URLSearchParams(window.location.search)
+        currentParams.forEach((value, key) => {
+          if (key !== 'page') {
+            url.searchParams.set(key, value)
+          }
+        })
+
+        const response = await fetch(url, {
+          headers: {
+            'Accept': 'application/json',
+            'X-Requested-With': 'XMLHttpRequest'
+          }
+        })
+
+        if (!response.ok) {
+          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)
+        }
+
+        // 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}`)
+
+        // 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)
+        this.dispatch('error', { detail: { error } })
+      } finally {
+        this.loadingValue = false
+        this.hideLoading()
+      }
+    }
+
+    appendItems(data) {
+      if (!this.hasItemsContainerTarget) {
+        console.warn('[PagyInfiniteScroll] No items container target found')
+        return
+      }
+
+      const records = data.records || data.items || data.products || []
+
+      records.forEach(record => {
+        const html = this.createItemHTML(record)
+        this.itemsContainerTarget.insertAdjacentHTML('beforeend', html)
+      })
+    }
+
+    createItemHTML(record) {
+      // This method should be overridden by extending this controller
+      // or by listening to the 'beforeAppend' event
+      console.warn('[PagyInfiniteScroll] createItemHTML should be overridden in a custom controller')
+      return `<div class="pagy-item">${JSON.stringify(record)}</div>`
+    }
+
+    showLoading() {
+      if (this.hasLoadingIndicatorTarget) {
+        this.loadingIndicatorTarget.classList.remove('hidden')
+      }
+    }
+
+    hideLoading() {
+      if (this.hasLoadingIndicatorTarget) {
+        this.loadingIndicatorTarget.classList.add('hidden')
+      }
+    }
+
+    // Public API methods
+    reset() {
+      this.pageValue = 1
+      this.hasMoreValue = true
+      if (this.hasItemsContainerTarget) {
+        this.itemsContainerTarget.innerHTML = ''
+      }
+    }
+
+    reload() {
+      this.reset()
+      this.loadMore()
+    }
+  }
+
+  // Register the controller with Stimulus
+  if (window.Stimulus) {
+    window.Stimulus.register('pagy-infinite-scroll', PagyInfiniteScrollController)
+    console.log('[PagyInfiniteScroll] Controller registered with Stimulus')
+  }
+
+  // Also export for manual registration (jsbundling compatibility)
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = PagyInfiniteScrollController
+  }
+
+  // Make available globally for importmap apps that want to extend it
+  window.PagyInfiniteScrollController = PagyInfiniteScrollController
+})()

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module PagyInfiniteScroll
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Install Pagy Infinite Scroll into your application"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/pagy_infinite_scroll.rb"
+      end
+
+      def add_javascript_import
+        if using_importmap?
+          add_importmap_pin
+        elsif using_jsbundling?
+          add_jsbundling_import
+        else
+          say "Please manually import the Stimulus controller in your JavaScript setup", :yellow
+        end
+      end
+
+      def show_post_install_message
+        say "\n"
+        say "Pagy Infinite Scroll installed successfully!", :green
+        say "\n"
+        say "Next steps:", :yellow
+        say "  1. Make sure you have Pagy gem installed: gem 'pagy'"
+        say "\n"
+
+        if using_importmap?
+          say "  2. Importmap setup (already configured!):", :green
+          say "     - Pin added to config/importmap.rb"
+          say "     - Import added to app/javascript/application.js"
+          say "     - Controller auto-registers with Stimulus on page load"
+          say "     - No manual registration needed!"
+        elsif using_jsbundling?
+          say "  2. jsbundling setup:", :yellow
+          say "     Copy the controller to your app:"
+          say "       cp $(bundle show pagy_infinite_scroll)/app/assets/javascripts/pagy_infinite_scroll/infinite_scroll_controller.js app/javascript/controllers/pagy_infinite_scroll_controller.js"
+          say "\n"
+          say "     Then register in app/javascript/controllers/index.js:"
+          say "       import PagyInfiniteScrollController from './pagy_infinite_scroll_controller'"
+          say "       application.register('pagy-infinite-scroll', PagyInfiniteScrollController)"
+          say "\n"
+          say "     Finally run: yarn build (or npm run build)"
+        else
+          say "  2. Manual setup required", :yellow
+          say "     See documentation for your JavaScript setup"
+        end
+
+        say "\n"
+        say "  3. Use in your controllers: pagy_infinite_scroll(collection)"
+        say "  4. See full documentation: https://github.com/hassanharoon86/pagy_infinite_scroll"
+        say "\n"
+      end
+
+      private
+
+      def using_importmap?
+        File.exist?("config/importmap.rb")
+      end
+
+      def using_jsbundling?
+        File.exist?("package.json") && (
+          File.exist?("app/javascript/application.js") ||
+          File.exist?("app/javascript/packs/application.js")
+        )
+      end
+
+      def add_importmap_pin
+        # Pin the standalone importmap-compatible controller
+        append_to_file "config/importmap.rb" do
+          "\n# Pagy Infinite Scroll - Standalone controller (auto-registers with Stimulus)\npin 'pagy_infinite_scroll_controller', to: 'pagy_infinite_scroll_controller.js'\n"
+        end
+
+        # Add import to application.js if it exists
+        if File.exist?("app/javascript/application.js")
+          append_to_file "app/javascript/application.js" do
+            "\n// Pagy Infinite Scroll - Auto-registers with Stimulus\nimport 'pagy_infinite_scroll_controller'\n"
+          end
+        end
+
+        say "\n"
+        say "Importmap configuration added!", :green
+        say "The controller will auto-register with Stimulus when loaded.", :green
+        say "\n"
+      end
+
+      def add_jsbundling_import
+        say "For jsbundling, you'll need to manually register the controller", :yellow
+        say "See the post-install message above for instructions", :yellow
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# Pagy Infinite Scroll Configuration
+#
+# Configure the default settings for infinite scroll pagination
+
+PagyInfiniteScroll.configure do |config|
+  # Number of items to load per page
+  # Default: 50
+  config.items_per_page = 50
+
+  # Distance from bottom of container in pixels to trigger loading more items
+  # Default: 100
+  config.scroll_threshold = 100
+
+  # Show loading indicator while fetching new items
+  # Default: true
+  config.loading_indicator = true
+
+  # Preserve form state and URL parameters during infinite scroll
+  # Default: true
+  config.preserve_state = true
+
+  # Debounce delay for search in milliseconds
+  # Default: 500
+  config.debounce_delay = 500
+end

data/lib/pagy_infinite_scroll/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PagyInfiniteScroll
+  class Configuration
+    attr_accessor :items_per_page,
+                  :scroll_threshold,
+                  :loading_indicator,
+                  :auto_initialize,
+                  :preserve_state,
+                  :debounce_delay
+
+    def initialize
+      @items_per_page = 50
+      @scroll_threshold = 100 # pixels from bottom
+      @loading_indicator = true
+      @auto_initialize = true
+      @preserve_state = true
+      @debounce_delay = 500 # milliseconds
+    end
+  end
+end

data/lib/pagy_infinite_scroll/controller_helper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module PagyInfiniteScroll
+  module ControllerHelper
+    extend ActiveSupport::Concern
+
+    included do
+      begin
+        require 'pagy'
+        include Pagy::Backend
+      rescue LoadError
+        raise LoadError, "Pagy gem is required. Add 'gem \"pagy\"' to your Gemfile and run 'bundle install'"
+      rescue NameError
+        raise NameError, "Pagy::Backend not found. Make sure Pagy is properly installed."
+      end
+    end
+
+    # Pagy with infinite scroll support
+    #
+    # @param collection [ActiveRecord::Relation] The collection to paginate
+    # @param options [Hash] Options for pagy and infinite scroll
+    # @return [Array<Pagy, Array>] The pagy object and paginated collection
+    #
+    # @example
+    #   @pagy, @products = pagy_infinite_scroll(Product.all)
+    #
+    # @example With custom options
+    #   @pagy, @products = pagy_infinite_scroll(Product.all, limit: 25)
+    #
+    def pagy_infinite_scroll(collection, **options)
+      options[:limit] ||= PagyInfiniteScroll.config.items_per_page
+      pagy, records = pagy(collection, **options)
+
+      [pagy, records]
+    end
+
+    # Respond with infinite scroll format
+    #
+    # @param pagy [Pagy] The pagy object
+    # @param records [Array] The paginated records
+    # @param serializer [Proc, nil] Optional custom serializer for records
+    # @yield [record] Block to serialize each record
+    # @return [Hash] JSON response with records and pagination data
+    #
+    # @example Basic usage
+    #   respond_to do |format|
+    #     format.html
+    #     format.json do
+    #       render json: pagy_infinite_scroll_json(@pagy, @products) { |product|
+    #         {
+    #           id: product.id,
+    #           title: product.title,
+    #           price: product.price
+    #         }
+    #       }
+    #     end
+    #   end
+    #
+    def pagy_infinite_scroll_json(pagy, records, &serializer)
+      {
+        records: serialize_records(records, &serializer),
+        pagy: {
+          page: pagy.page,
+          pages: pagy.pages,
+          count: pagy.count,
+          next: pagy.next,
+          prev: pagy.prev,
+          from: pagy.from,
+          to: pagy.to
+        }
+      }
+    end
+
+    private
+
+    def serialize_records(records, &serializer)
+      return records unless block_given?
+
+      records.map { |record| serializer.call(record) }
+    end
+  end
+end

data/lib/pagy_infinite_scroll/engine.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module PagyInfiniteScroll
+  class Engine < ::Rails::Engine
+    # 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__)
+
+    # Load assets if asset pipeline is available
+    initializer "pagy_infinite_scroll.assets", before: :load_config_initializers do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        app.config.assets.precompile += %w[
+          pagy_infinite_scroll/infinite_scroll_controller.js
+          pagy_infinite_scroll/index.js
+          pagy_infinite_scroll_controller.js
+        ]
+      end
+    end
+
+    # Support for importmap-rails
+    initializer "pagy_infinite_scroll.importmap", before: "importmap" do |app|
+      if defined?(Importmap)
+        # Make the standalone controller available to importmap
+        app.config.assets.paths << root.join("app/assets/javascripts") unless app.config.assets.paths.include?(root.join("app/assets/javascripts"))
+      end
+    end
+
+    # Load helpers into ActionController and ActionView
+    initializer "pagy_infinite_scroll.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper PagyInfiniteScroll::ViewHelper if defined?(PagyInfiniteScroll::ViewHelper)
+        include PagyInfiniteScroll::ControllerHelper if defined?(PagyInfiniteScroll::ControllerHelper)
+      end
+
+      ActiveSupport.on_load(:action_view) do
+        include PagyInfiniteScroll::ViewHelper if defined?(PagyInfiniteScroll::ViewHelper)
+      end
+    end
+
+    # Fallback for direct inclusion
+    config.after_initialize do
+      if defined?(ActionController::Base)
+        ActionController::Base.include(PagyInfiniteScroll::ControllerHelper) unless ActionController::Base.include?(PagyInfiniteScroll::ControllerHelper)
+        ActionController::Base.helper(PagyInfiniteScroll::ViewHelper) if defined?(PagyInfiniteScroll::ViewHelper)
+      end
+    end
+  end
+end

data/lib/pagy_infinite_scroll/version.rb

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

data/lib/pagy_infinite_scroll/view_helper.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module PagyInfiniteScroll
+  module ViewHelper
+    # Renders an infinite scroll container
+    #
+    # @param pagy [Pagy] The pagy object
+    # @param url [String] The URL to fetch more items
+    # @param options [Hash] HTML and Stimulus options
+    # @option options [String] :container_class CSS classes for the container
+    # @option options [String] :max_height Maximum height (e.g., "600px")
+    # @option options [Hash] :data Additional data attributes
+    # @yield The content to render inside the container
+    #
+    # @example
+    #   <%= infinite_scroll_container(@pagy, products_path(format: :json)) do %>
+    #     <div data-infinite-scroll-target="itemsContainer">
+    #       <%= render @products %>
+    #     </div>
+    #   <% end %>
+    #
+    def infinite_scroll_container(pagy, url, options = {}, &block)
+      container_class = options[:container_class] || ''
+      max_height = options[:max_height] || '600px'
+      data_attrs = options[:data] || {}
+
+      content_tag :div,
+                  class: container_class,
+                  style: "max-height: #{max_height}; overflow-y: auto;",
+                  data: {
+                    controller: 'pagy-infinite-scroll',
+                    pagy_infinite_scroll_url_value: url,
+                    pagy_infinite_scroll_page_value: pagy.page,
+                    pagy_infinite_scroll_loading_value: false,
+                    pagy_infinite_scroll_has_more_value: pagy.next.present?,
+                    **stimulus_data_attributes(data_attrs)
+                  } do
+        block.call
+      end
+    end
+
+    # Renders the loading indicator
+    #
+    # @param options [Hash] Options for the loading indicator
+    # @option options [String] :text Loading text
+    # @option options [String] :class CSS classes
+    #
+    # @example
+    #   <%= infinite_scroll_loading_indicator %>
+    #
+    # @example Custom text
+    #   <%= infinite_scroll_loading_indicator(text: "Loading products...") %>
+    #
+    def infinite_scroll_loading_indicator(options = {})
+      text = options[:text] || 'Loading more items...'
+      css_class = options[:class] || 'hidden p-4 text-center'
+
+      content_tag :div,
+                  class: css_class,
+                  data: { pagy_infinite_scroll_target: 'loadingIndicator' } do
+        content_tag :div, class: 'inline-flex items-center gap-2 text-gray-600' do
+          concat(spinner_svg)
+          concat(content_tag(:span, text))
+        end
+      end
+    end
+
+    # Renders a scroll target container for items
+    #
+    # @param options [Hash] HTML options
+    # @option options [String] :class CSS classes
+    # @option options [String] :tag HTML tag (default: 'div')
+    # @yield The content to render inside the container
+    #
+    # @example
+    #   <%= infinite_scroll_items_container do %>
+    #     <%= render @products %>
+    #   <% end %>
+    #
+    # @example With table rows
+    #   <%= infinite_scroll_items_container(tag: 'tbody') do %>
+    #     <%= render @items %>
+    #   <% end %>
+    #
+    def infinite_scroll_items_container(options = {}, &block)
+      tag = options.delete(:tag) || 'div'
+      css_class = options.delete(:class) || ''
+
+      content_tag tag,
+                  class: css_class,
+                  data: { pagy_infinite_scroll_target: 'itemsContainer' } do
+        block.call
+      end
+    end
+
+    private
+
+    def spinner_svg
+      <<~SVG.html_safe
+        <svg class="animate-spin h-5 w-5" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+        </svg>
+      SVG
+    end
+
+    def stimulus_data_attributes(attrs)
+      attrs.transform_keys { |key| "pagy_infinite_scroll_#{key}_value".to_sym }
+    end
+  end
+end

data/lib/pagy_infinite_scroll.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "pagy_infinite_scroll/version"
+require_relative "pagy_infinite_scroll/configuration"
+require_relative "pagy_infinite_scroll/controller_helper"
+require_relative "pagy_infinite_scroll/view_helper"
+require_relative "pagy_infinite_scroll/engine" if defined?(Rails)
+
+module PagyInfiniteScroll
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def config
+      self.configuration ||= Configuration.new
+    end
+  end
+end

data/sig/pagy_infinite_scroll.rbs

@@ -0,0 +1,4 @@
+module PagyInfiniteScroll
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: pagy_infinite_scroll
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hassan Haroon
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: A Rails gem that adds infinite scroll functionality to any Rails application
+  using Pagy for efficient pagination and Stimulus for smooth frontend interactions.
+  Features include automatic lazy loading, state preservation, AJAX support, and customizable
+  behavior.
+email:
+- hassanharoon86@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/pagy_infinite_scroll/index.js
+- app/assets/javascripts/pagy_infinite_scroll/infinite_scroll_controller.js
+- app/assets/javascripts/pagy_infinite_scroll_controller.js
+- lib/generators/pagy_infinite_scroll/install/install_generator.rb
+- lib/generators/pagy_infinite_scroll/install/templates/initializer.rb
+- lib/pagy_infinite_scroll.rb
+- lib/pagy_infinite_scroll/configuration.rb
+- lib/pagy_infinite_scroll/controller_helper.rb
+- lib/pagy_infinite_scroll/engine.rb
+- lib/pagy_infinite_scroll/version.rb
+- lib/pagy_infinite_scroll/view_helper.rb
+- sig/pagy_infinite_scroll.rbs
+homepage: https://github.com/hassanharoon86/pagy_infinite_scroll
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hassanharoon86/pagy_infinite_scroll
+  source_code_uri: https://github.com/hassanharoon86/pagy_infinite_scroll
+  changelog_uri: https://github.com/hassanharoon86/pagy_infinite_scroll/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Infinite scroll pagination for Rails using Pagy and Stimulus
+test_files: []