pagy 8.6.0 → 9.0.2

data/lib/pagy/extras/bulma.rb

@@ -8,9 +8,10 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module BulmaExtra
     # Pagination for bulma: it returns the html with the series of links to the pages
-    def pagy_bulma_nav(pagy, id: nil, classes: 'pagy-bulma nav pagination is-centered', aria_label: nil, **vars)
+    def pagy_bulma_nav(pagy, id: nil, classes: 'pagy-bulma nav pagination is-centered',
+                       aria_label: nil, **vars)
       id = %( id="#{id}") if id
-      a  = pagy_anchor(pagy)
+      a  = pagy_anchor(pagy, **vars)
 
       html = %(<nav#{id} class="#{classes}" #{nav_aria_label(pagy, aria_label:)}>)
       html << bulma_prev_next_html(pagy, a)
@@ -31,10 +32,11 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for bulma: it returns a nav with a data-pagy attribute used by the Pagy.nav javascript
-    def pagy_bulma_nav_js(pagy, id: nil, classes: 'pagy-bulma nav-js pagination is-centered', aria_label: nil, **vars)
+    def pagy_bulma_nav_js(pagy, id: nil, classes: 'pagy-bulma nav-js pagination is-centered',
+                          aria_label: nil, **vars)
       sequels = pagy.sequels(**vars)
       id      = %( id="#{id}") if id
-      a       = pagy_anchor(pagy)
+      a       = pagy_anchor(pagy, **vars)
       tokens = { 'before'  => %(#{bulma_prev_next_html(pagy, a)}<ul class="pagination-list">),
                  'a'       => %(<li>#{a.(PAGE_TOKEN, LABEL_TOKEN, classes: 'pagination-link')}</li>),
                  'current' => %(<li><a role="link" class="pagination-link is-current" aria-current="page" aria-disabled="true">#{
@@ -49,9 +51,10 @@ class Pagy # :nodoc:
     end
 
     # Javascript combo pagination for bulma: it returns a nav with a data-pagy attribute used by the pagy.js file
-    def pagy_bulma_combo_nav_js(pagy, id: nil, classes: 'pagy-bulma combo-nav-js pagination is-centered', aria_label: nil)
+    def pagy_bulma_combo_nav_js(pagy, id: nil, classes: 'pagy-bulma combo-nav-js pagination is-centered',
+                                aria_label: nil, **vars)
       id    = %( id="#{id}") if id
-      a     = pagy_anchor(pagy)
+      a     = pagy_anchor(pagy, **vars)
       pages = pagy.pages
 
       page_input = %(<input name="page" type="number" min="1" max="#{pages}" value="#{pagy.page}" aria-current="page") <<
@@ -61,7 +64,7 @@ class Pagy # :nodoc:
 
       %(<nav#{id} class="#{classes}" #{
           nav_aria_label(pagy, aria_label:)} #{
-          pagy_data(pagy, :combo, pagy_url_for(pagy, PAGE_TOKEN))
+          pagy_data(pagy, :combo, pagy_url_for(pagy, PAGE_TOKEN, **vars))
         }>#{
           bulma_prev_next_html(pagy, a)
         }<ul class="pagination-list"><li class="pagination-link"><label>#{

data/lib/pagy/extras/calendar.rb

@@ -27,7 +27,7 @@ class Pagy # :nodoc:
           end
           collection = pagy_calendar_filter(collection, from, to)
         end
-        pagy, results = send(conf[:pagy][:backend] || :pagy, collection, conf[:pagy])  # use backend: :pagy when omitted
+        pagy, results = send(conf[:pagy][:backend] || :pagy, collection, **conf[:pagy])  # use backend: :pagy when omitted
         [calendar, pagy, results]
       end
 
@@ -47,12 +47,11 @@ class Pagy # :nodoc:
     # Override the pagy_anchor
     module FrontendOverride
       # Consider the vars[:count]
-      def pagy_anchor(pagy)
+      def pagy_anchor(pagy, anchor_string: nil)
         return super unless (counts = pagy.vars[:counts])
 
-        a_string    = pagy.vars[:anchor_string]
-        a_string    = %( #{a_string}) if a_string
-        left, right = %(<a#{a_string} href="#{pagy_url_for(pagy, PAGE_TOKEN)}").split(PAGE_TOKEN, 2)
+        anchor_string &&= %( #{anchor_string})
+        left, right = %(<a#{anchor_string} href="#{pagy_url_for(pagy, PAGE_TOKEN)}").split(PAGE_TOKEN, 2)
         # lambda used by all the helpers
         lambda do |page, text = pagy.label_for(page), classes: nil, aria_label: nil|
           count     = counts[page - 1]

data/lib/pagy/extras/countless.rb

@@ -10,27 +10,29 @@ class Pagy # :nodoc:
   module CountlessExtra
     private
 
-    # Return Pagy object and items
-    def pagy_countless(collection, vars = {})
-      pagy = Countless.new(pagy_countless_get_vars(collection, vars))
+    # Return Pagy object and records
+    def pagy_countless(collection, **vars)
+      pagy = Countless.new(**pagy_countless_get_vars(collection, vars))
       [pagy, pagy_countless_get_items(collection, pagy)]
     end
 
-    # Sub-method called only by #pagy_countless: here for easy customization of variables by overriding
-    def pagy_countless_get_vars(_collection, vars)
-      pagy_set_items_from_params(vars) if defined?(ItemsExtra)
-      vars[:page] ||= pagy_get_page(vars)
-      vars
-    end
-
     # Sub-method called only by #pagy_countless: here for easy customization of record-extraction by overriding
     # You may need to override this method for collections without offset|limit
     def pagy_countless_get_items(collection, pagy)
-      return collection.offset(pagy.offset).limit(pagy.items) if pagy.vars[:countless_minimal]
+      return collection.offset(pagy.offset).limit(pagy.limit) if pagy.vars[:countless_minimal]
 
-      fetched = collection.offset(pagy.offset).limit(pagy.items + 1).to_a # eager load items + 1
+      fetched = collection.offset(pagy.offset).limit(pagy.limit + 1).to_a # eager load limit + 1
       pagy.finalize(fetched.size)                                         # finalize the pagy object
-      fetched[0, pagy.items]                                              # ignore eventual extra item
+      fetched[0, pagy.limit]                                              # ignore eventual extra item
+    end
+
+    # Sub-method called only by #pagy: here for easy customization of variables by overriding
+    # You may need to override the count call for non AR collections
+    def pagy_countless_get_vars(_collection, vars)
+      vars.tap do |v|
+        v[:limit] ||= pagy_get_limit(v)
+        v[:page]  ||= pagy_get_page(v)
+      end
     end
   end
   Backend.prepend CountlessExtra

data/lib/pagy/extras/elasticsearch_rails.rb

@@ -28,18 +28,18 @@ class Pagy # :nodoc:
           args.define_singleton_method(:method_missing) { |*a| args += a }
         end
       end
-      alias_method Pagy::DEFAULT[:elasticsearch_rails_pagy_search], :pagy_elasticsearch_rails
+      alias_method DEFAULT[:elasticsearch_rails_pagy_search], :pagy_elasticsearch_rails
     end
     Pagy::ElasticsearchRails = ModelExtension
 
     # Additions for the Pagy class
     module PagyAddOn
       # Create a Pagy object from an Elasticsearch::Model::Response::Response object
-      def new_from_elasticsearch_rails(response, vars = {})
-        vars[:items] = response.search.options[:size] || 10
-        vars[:page]  = ((response.search.options[:from] || 0) / vars[:items]) + 1
+      def new_from_elasticsearch_rails(response, **vars)
+        vars[:limit] = response.search.options[:size] || 10
+        vars[:page]  = ((response.search.options[:from] || 0) / vars[:limit]) + 1
         vars[:count] = ElasticsearchRailsExtra.total_count(response)
-        new(vars)
+        Pagy.new(**vars)
       end
     end
     Pagy.extend PagyAddOn
@@ -48,19 +48,19 @@ class Pagy # :nodoc:
     module BackendAddOn
       private
 
-      # Return Pagy object and items
-      def pagy_elasticsearch_rails(pagy_search_args, vars = {})
+      # Return Pagy object and records
+      def pagy_elasticsearch_rails(pagy_search_args, **vars)
         model, query_or_payload,
         options, *called = pagy_search_args
         vars             = pagy_elasticsearch_rails_get_vars(nil, vars)
-        options[:size]   = vars[:items]
-        options[:from]   = vars[:items] * (vars[:page] - 1)
+        options[:size]   = vars[:limit]
+        options[:from]   = vars[:limit] * ((vars[:page] || 1) - 1)
         response         = model.send(DEFAULT[:elasticsearch_rails_search], query_or_payload, **options)
         vars[:count]     = ElasticsearchRailsExtra.total_count(response)
 
-        pagy = ::Pagy.new(vars)
+        pagy = ::Pagy.new(**vars)
         # with :last_page overflow we need to re-run the method in order to get the hits
-        return pagy_elasticsearch_rails(pagy_search_args, vars.merge(page: pagy.page)) \
+        return pagy_elasticsearch_rails(pagy_search_args, **vars, page: pagy.page) \
                if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, called.empty? ? response : response.send(*called)]
@@ -69,10 +69,10 @@ class Pagy # :nodoc:
       # Sub-method called only by #pagy_elasticsearch_rails: here for easy customization of variables by overriding
       # the _collection argument is not available when the method is called
       def pagy_elasticsearch_rails_get_vars(_collection, vars)
-        pagy_set_items_from_params(vars) if defined?(ItemsExtra)
-        vars[:items] ||= DEFAULT[:items]
-        vars[:page]  ||= pagy_get_page(vars)
-        vars
+        vars.tap do |v|
+          v[:page]  ||= pagy_get_page(v)
+          v[:limit] ||= pagy_get_limit(v) || DEFAULT[:limit]
+        end
       end
     end
     Backend.prepend BackendAddOn

data/lib/pagy/extras/gearbox.rb

@@ -3,27 +3,39 @@
 
 class Pagy # :nodoc:
   DEFAULT[:gearbox_extra] = true # extra enabled by default
-  DEFAULT[:gearbox_items] = [15, 30, 60, 100]
+  DEFAULT[:gearbox_limit] = [15, 30, 60, 100]
 
-  # Automatically change the number of items per page depending on the page number
-  # accepts an array as the :gearbox_items variable, that will determine the items for the first pages
+  # Automatically change the limit depending on the page number
+  # accepts an array as the :gearbox_limit variable, that will determine the limit for the first pages
   module GearboxExtra
-    # Setup @items based on the :gearbox_items variable
-    def setup_items_var
-      return super if !@vars[:gearbox_extra] || @vars[:items_extra]
+    # Assign @limit based on the :gearbox_limit variable
+    def assign_limit
+      return super if !@vars[:gearbox_extra] || @vars[:limit_extra]
 
-      gears = @vars[:gearbox_items]
-      raise VariableError.new(self, :gearbox_items, 'to be an Array of positives', gears) \
+      gears = @vars[:gearbox_limit]
+      raise VariableError.new(self, :gearbox_limit, 'to be an Array of positives', gears) \
             unless gears.is_a?(Array) && gears.all? { |num| num.positive? rescue false } # rubocop:disable Style/RescueModifier
 
-      @items = gears[@page - 1] || gears.last
+      @limit = gears[@page - 1] || gears.last
     end
 
-    # Setup Pagy @last based on the :gearbox_items variable and @count
-    def setup_last_var
-      return super if !@vars[:gearbox_extra] || @vars[:items_extra]
+    # Asgnsi @offset based on the :gearbox_limit variable
+    def assign_offset
+      return super if !@vars[:gearbox_extra] || @vars[:limit_extra]
 
-      gears = @vars[:gearbox_items]
+      gears   = @vars[:gearbox_limit]
+      @offset = if @page <= gears.count
+                  gears[0, @page - 1].sum
+                else
+                  gears.sum + (gears.last * (@page - gears.count - 1))
+                end + @outset
+    end
+
+    # Assign @last based on the :gearbox_limit variable and @count
+    def assign_last
+      return super if !@vars[:gearbox_extra] || @vars[:limit_extra]
+
+      gears = @vars[:gearbox_limit]
       # This algorithm is thousands of times faster than the one in the geared_pagination gem
       @last = (if count > (sum = gears.sum)
                  [((count - sum).to_f / gears.last).ceil, 1].max + gears.count
@@ -36,19 +48,7 @@ class Pagy # :nodoc:
                  end
                  [pages, 1].max
                end)
-      @last = vars[:max_pages] if vars[:max_pages] && @last > vars[:max_pages]
-    end
-
-    # Setup @offset based on the :gearbox_items variable
-    def setup_offset_var
-      return super if !@vars[:gearbox_extra] || @vars[:items_extra]
-
-      gears   = @vars[:gearbox_items]
-      @offset = if @page <= gears.count
-                  gears[0, @page - 1].sum
-                else
-                  gears.sum + (gears.last * (@page - gears.count - 1))
-                end + @outset
+      @last = @vars[:max_pages] if @vars[:max_pages] && @last > @vars[:max_pages]
     end
   end
   prepend GearboxExtra

data/lib/pagy/extras/headers.rb

@@ -5,7 +5,7 @@ require_relative '../url_helpers'
 
 class Pagy # :nodoc:
   DEFAULT[:headers] = { page:  'current-page',
-                        items: 'page-items',
+                        limit: 'page-items',
                         count: 'total-count',
                         pages: 'total-pages' }
   # Add specialized backend methods to add pagination response headers
@@ -21,32 +21,33 @@ class Pagy # :nodoc:
 
     # Generate a hash of RFC-8288 compliant http headers
     def pagy_headers(pagy)
-      pagy_headers_hash(pagy).tap do |hash|
-        hash['link'] = hash['link'].map { |rel, link| %(<#{link}>; rel="#{rel}") }.join(', ')
-      end
-    end
+      headers = pagy.vars[:headers]
+      pagy_link_header(pagy).tap do |hash|
+        hash[headers[:page]]  = pagy.page.to_s if pagy.page && headers[:page]
+        hash[headers[:limit]] = pagy.limit.to_s \
+            if headers[:limit] && !(defined?(Calendar) && pagy.is_a?(Calendar::Unit))
+        return hash if (defined?(Countless) && pagy.is_a?(Countless)) || \
+                       (defined?(Keyset) && pagy.is_a?(Keyset))
 
-    # Generates a hash structure of the headers
-    def pagy_headers_hash(pagy)
-      countless             = defined?(Countless) && pagy.is_a?(Countless)
-      rel                   = { 'first' => 1, 'prev' => pagy.prev, 'next' => pagy.next }
-      rel['last']           = pagy.last unless countless
-      url_str               = pagy_url_for(pagy, PAGE_TOKEN, absolute: true)
-      link                  = rel.filter_map do |r, num|
-                                next unless num # rubocop:disable Layout/EmptyLineAfterGuardClause
-                                [r, url_str.sub(PAGE_TOKEN, num.to_s)]
-                              end.compact.to_h
-      hash                  = { 'link' => link }
-      headers               = pagy.vars[:headers]
-      hash[headers[:page]]  = pagy.page.to_s if headers[:page]
-      if headers[:items] && !(defined?(Calendar) && pagy.is_a?(Calendar))  # items is not for Calendar
-        hash[headers[:items]] = pagy.vars[:items].to_s
-      end
-      unless countless
-        hash[headers[:pages]] = pagy.pages.to_s if headers[:pages]
+        hash[headers[:pages]] = pagy.last.to_s if headers[:pages]
         hash[headers[:count]] = pagy.count.to_s if pagy.count && headers[:count] # count may be nil with Calendar
       end
-      hash
+    end
+
+    def pagy_link_header(pagy)
+      { 'link' => [].tap do |link|
+        if defined?(Keyset) && pagy.is_a?(Keyset)
+          link << %(<#{pagy_url_for(pagy, nil, absolute: true)}>; rel="first")
+          link << %(<#{pagy_url_for(pagy, pagy.next, absolute: true)}>; rel="next") if pagy.next
+        else
+          url_str = pagy_url_for(pagy, PAGE_TOKEN, absolute: true)
+          link << %(<#{url_str.sub(PAGE_TOKEN, '1')}>; rel="first")
+          link << %(<#{url_str.sub(PAGE_TOKEN, pagy.prev.to_s)}>; rel="prev") if pagy.prev
+          link << %(<#{url_str.sub(PAGE_TOKEN, pagy.next.to_s)}>; rel="next") if pagy.next
+          link << %(<#{url_str.sub(PAGE_TOKEN, pagy.last.to_s)}>; rel="last") \
+              unless defined?(Countless) && pagy.is_a?(Countless)
+        end
+      end.join(', ') }
     end
   end
   Backend.prepend HeadersExtra

data/lib/pagy/extras/js_tools.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../b64'
+
 class Pagy # :nodoc:
   DEFAULT[:steps] = false # default false will use {0 => @vars[:size]}
 
@@ -13,11 +15,11 @@ class Pagy # :nodoc:
       # `Pagy` instance method used by the `pagy*_nav_js` helpers.
       # It returns the sequels of width/series generated from the :steps hash
       # Example:
-      # >> pagy = Pagy.new(count:1000, page: 20, steps: {0 => [1,2,2,1], 350 => [2,3,3,2], 550 => [3,4,4,3]})
+      # >> pagy = Pagy.new(count:1000, page: 20, steps: {0 => 5, 350 => 7, 550 => 9})
       # >> pagy.sequels
-      # #=> { "0"   => [1, :gap, 18, 19, "20", 21, 22, :gap, 50],
-      #       "350" => [1, 2, :gap, 17, 18, 19, "20", 21, 22, 23, :gap, 49, 50],
-      #       "550" => [1, 2, 3, :gap, 16, 17, 18, 19, "20", 21, 22, 23, 24, :gap, 48, 49, 50] }
+      # #=> { "0"   => [18, 19, "20", 21, 22],
+      #       "350" => [1, :gap, 19, "20", 21, :gap, 50],
+      #       "550" => [1 :gap, 18, 19, "20", 21, 22, :gap, 50] }
       # Notice: if :steps is false it will use the single {0 => @vars[:size]} size
       def sequels(steps: @vars[:steps] || { 0 => @vars[:size] }, **_)
         raise VariableError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
@@ -51,8 +53,7 @@ class Pagy # :nodoc:
         # Base64 encoded JSON is smaller than HTML escaped JSON
         def pagy_data(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
-          strict_base64_encoded = [Oj.dump(args, mode: :strict)].pack('m0')
-          %(data-pagy="#{strict_base64_encoded}")
+          %(data-pagy="#{B64.encode(Oj.dump(args, mode: :strict))}")
         end
       else
         require 'json'
@@ -60,8 +61,7 @@ class Pagy # :nodoc:
         # Base64 encoded JSON is smaller than HTML escaped JSON
         def pagy_data(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
-          strict_base64_encoded = [args.to_json].pack('m0')
-          %(data-pagy="#{strict_base64_encoded}")
+          %(data-pagy="#{B64.encode(args.to_json)}")
         end
       end
     end

data/lib/pagy/extras/jsonapi.rb

@@ -24,10 +24,17 @@ class Pagy # :nodoc:
 
       # Return the jsonapi links
       def pagy_jsonapi_links(pagy, **opts)
-        { first: pagy_url_for(pagy, 1,         **opts),
-          last:  pagy_url_for(pagy, pagy.last, **opts),
-          prev:  pagy.prev ? pagy_url_for(pagy, pagy.prev, **opts) : nil,
-          next:  pagy.next ? pagy_url_for(pagy, pagy.next, **opts) : nil }
+        if defined?(Pagy::Keyset) && pagy.is_a?(Pagy::Keyset)
+          { first: pagy_url_for(pagy, nil, **opts),
+            last: nil,
+            prev: nil,
+            next:  pagy.next ? pagy_url_for(pagy, pagy.next, **opts) : nil }
+        else
+          { first: pagy_url_for(pagy, 1, **opts),
+            last:  pagy_url_for(pagy, pagy.last, **opts),
+            prev:  pagy.prev ? pagy_url_for(pagy, pagy.prev, **opts) : nil,
+            next:  pagy.next ? pagy_url_for(pagy, pagy.next, **opts) : nil }
+        end
       end
 
       # Should skip the jsonapi
@@ -40,38 +47,41 @@ class Pagy # :nodoc:
       # Override the Backend method
       def pagy_get_page(vars)
         return super if pagy_skip_jsonapi?(vars)
-        return 1 if params[:page].nil?
+        return if params[:page].nil?
 
-        [params[:page][vars[:page_param] || DEFAULT[:page_param]].to_i, 1].max
+        params[:page][vars[:page_param] || DEFAULT[:page_param]]
       end
     end
     Backend.prepend BackendOverride
 
-    # Module overriding ItemsExtra
-    module ItemsExtraOverride
+    # Module overriding LimitExtra
+    module LimitExtraOverride
       private
 
-      # Override the ItemsExtra::Backend method
-      def pagy_get_items_size(vars)
+      # Override the LimitExtra::Backend method
+      def pagy_get_limit_param(vars)
         return super if pagy_skip_jsonapi?(vars)
         return if params[:page].nil?
 
-        params[:page][vars[:items_param] || DEFAULT[:items_param]]
+        params[:page][vars[:limit_param] || DEFAULT[:limit_param]]
       end
     end
     # :nocov:
-    ItemsExtra::BackendAddOn.prepend ItemsExtraOverride if defined?(ItemsExtra::BackendAddOn)
+    LimitExtra::BackendAddOn.prepend LimitExtraOverride if defined?(LimitExtra::BackendAddOn)
     # :nocov:
 
     # Module overriding UrlHelper
     module UrlHelperOverride
       # Override UrlHelper method
-      def pagy_set_query_params(page, vars, params)
+      def pagy_set_query_params(page, vars, query_params)
         return super unless vars[:jsonapi]
 
-        params['page'] ||= {}
-        params['page'][vars[:page_param].to_s]  = page
-        params['page'][vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
+        query_params['page'] ||= {}
+        query_params['page'][vars[:page_param].to_s]  = page if page
+        query_params['page'][vars[:limit_param].to_s] = vars[:limit] if vars[:limit_extra]
+        # :nocov:
+        query_params.delete(:page) if query_params['page'].empty?
+        # :nocov:
       end
     end
     UrlHelpers.prepend UrlHelperOverride

data/lib/pagy/extras/keyset.rb

@@ -0,0 +1,36 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/keyset
+# frozen_string_literal: true
+
+require_relative '../keyset'
+
+class Pagy # :nodoc:
+  # Add keyset pagination
+  module KeysetExtra
+    private
+
+    # Return Pagy::Keyset object and paginated records
+    def pagy_keyset(set, **vars)
+      pagy = Keyset.new(set, **pagy_keyset_get_vars(vars))
+      [pagy, pagy.records]
+    end
+
+    # Sub-method called only by #pagy_keyset: here for easy customization of variables by overriding
+    def pagy_keyset_get_vars(vars)
+      vars.tap do |v|
+        v[:page]  ||= pagy_get_page(v)
+        v[:limit] ||= pagy_get_limit(v)
+      end
+    end
+
+    # Return the URL string for the first page
+    def pagy_keyset_first_url(pagy, **vars)
+      pagy_url_for(pagy, nil, **vars)
+    end
+
+    # Return the URL string for the next page or nil
+    def pagy_keyset_next_url(pagy, **vars)
+      pagy_url_for(pagy, pagy.next, **vars) if pagy.next
+    end
+  end
+  Backend.prepend KeysetExtra
+end

data/lib/pagy/extras/limit.rb

@@ -0,0 +1,63 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/limit
+# frozen_string_literal: true
+
+require_relative 'js_tools'
+
+class Pagy # :nodoc:
+  DEFAULT[:limit_param] = :limit
+  DEFAULT[:limit_max]   = 100
+  DEFAULT[:limit_extra] = true   # extra enabled by default
+
+  # Allow the client to request a custom limit per page with an optional selector UI
+  module LimitExtra
+    # Additions for the Backend module
+    module BackendAddOn
+      private
+
+      # Set the limit variable considering the params and other pagy variables
+      def pagy_get_limit(vars)
+        return unless vars.key?(:limit_extra) ? vars[:limit_extra] : DEFAULT[:limit_extra] # :limit_extra is false
+        return unless (limit_count = pagy_get_limit_param(vars))                            # no limit from request params
+
+        vars[:limit] = [limit_count.to_i, vars.key?(:limit_max) ? vars[:limit_max] : DEFAULT[:limit_max]].compact.min
+      end
+
+      # Get the limit count from the params
+      # Overridable by the jsonapi extra
+      def pagy_get_limit_param(vars)
+        params[vars[:limit_param] || DEFAULT[:limit_param]]
+      end
+    end
+    Backend.prepend LimitExtra::BackendAddOn
+
+    # Additions for the Frontend module
+    module FrontendAddOn
+      LIMIT_TOKEN = '__pagy_limit__'
+
+      # Return the limit selector HTML. For example "Show [20] items per page"
+      def pagy_limit_selector_js(pagy, id: nil, item_name: nil)
+        return '' unless pagy.vars[:limit_extra]
+
+        id           = %( id="#{id}") if id
+        vars         = pagy.vars
+        limit        = vars[:limit]
+        vars[:limit] = LIMIT_TOKEN
+        url_token    = pagy_url_for(pagy, PAGE_TOKEN)
+        vars[:limit] = limit # restore the limit
+
+        limit_input = %(<input name="limit" type="number" min="1" max="#{vars[:limit_max]}" value="#{
+                          limit}" style="padding: 0; text-align: center; width: #{limit.to_s.length + 1}rem;">#{JSTools::A_TAG})
+
+        %(<span#{id} class="pagy limit-selector-js" #{
+            pagy_data(pagy, :selector, pagy.from, url_token)
+          }><label>#{
+            pagy_t('pagy.limit_selector_js',
+                   item_name: item_name || pagy_t('pagy.item_name', count: limit),
+                   limit_input:,
+                   count: limit)
+          }</label></span>)
+      end
+    end
+    Frontend.prepend LimitExtra::FrontendAddOn
+  end
+end

data/lib/pagy/extras/meilisearch.rb

@@ -20,12 +20,12 @@ class Pagy # :nodoc:
     # Extension for the Pagy class
     module PagyExtension
       # Create a Pagy object from a Meilisearch results
-      def new_from_meilisearch(results, vars = {})
-        vars[:items] = results.raw_answer['hitsPerPage']
+      def new_from_meilisearch(results, **vars)
+        vars[:limit] = results.raw_answer['hitsPerPage']
         vars[:page]  = results.raw_answer['page']
         vars[:count] = results.raw_answer['totalHits']
 
-        new(vars)
+        new(**vars)
       end
     end
     Pagy.extend PagyExtension
@@ -35,17 +35,17 @@ class Pagy # :nodoc:
       private
 
       # Return Pagy object and results
-      def pagy_meilisearch(pagy_search_args, vars = {})
+      def pagy_meilisearch(pagy_search_args, **vars)
         model, term, options    = pagy_search_args
         vars                    = pagy_meilisearch_get_vars(nil, vars)
-        options[:hits_per_page] = vars[:items]
+        options[:hits_per_page] = vars[:limit]
         options[:page]          = vars[:page]
         results                 = model.send(:ms_search, term, options)
         vars[:count]            = results.raw_answer['totalHits']
 
-        pagy                    = ::Pagy.new(vars)
+        pagy                    = ::Pagy.new(**vars)
         # with :last_page overflow we need to re-run the method in order to get the hits
-        return pagy_meilisearch(pagy_search_args, vars.merge(page: pagy.page)) \
+        return pagy_meilisearch(pagy_search_args, **vars, page: pagy.page) \
                if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, results]
@@ -54,10 +54,10 @@ class Pagy # :nodoc:
       # Sub-method called only by #pagy_meilisearch: here for easy customization of variables by overriding.
       # The _collection argument is not available when the method is called.
       def pagy_meilisearch_get_vars(_collection, vars)
-        pagy_set_items_from_params(vars) if defined?(ItemsExtra)
-        vars[:items] ||= DEFAULT[:items]
-        vars[:page]  ||= pagy_get_page(vars)
-        vars
+        vars.tap do |v|
+          v[:page]  ||= pagy_get_page(v)
+          v[:limit] ||= pagy_get_limit(v) || DEFAULT[:limit]
+        end
       end
     end
     Backend.prepend BackendAddOn

data/lib/pagy/extras/metadata.rb

@@ -5,7 +5,7 @@ require_relative '../url_helpers'
 
 class Pagy # :nodoc:
   DEFAULT[:metadata] = %i[ scaffold_url first_url prev_url page_url next_url last_url
-                           count page items vars pages last in from to prev next series ]
+                           count page limit vars pages last in from to prev next series ]
 
   # Add a specialized backend method for pagination metadata
   module MetadataExtra
@@ -18,7 +18,7 @@ class Pagy # :nodoc:
       scaffold_url = pagy_url_for(pagy, PAGE_TOKEN, absolute:)
       {}.tap do |metadata|
         keys = if defined?(Calendar::Unit) && pagy.is_a?(Calendar::Unit)
-                 pagy.vars[:metadata] - %i[count items]
+                 pagy.vars[:metadata] - %i[count limit]
                else
                  pagy.vars[:metadata]
                end

data/lib/pagy/extras/overflow.rb

@@ -14,7 +14,7 @@ class Pagy # :nodoc:
       end
 
       # Add rescue clause for different behaviors
-      def initialize(vars)
+      def initialize(**vars)
         @overflow ||= false                            # still true if :last_page re-run the method after an overflow
         super
       rescue OverflowError
@@ -24,10 +24,10 @@ class Pagy # :nodoc:
           raise                                        # same as without the extra
         when :last_page
           requested_page = @vars[:page]                # save the requested page (even after re-run)
-          initialize vars.merge!(page: @last)          # re-run with the last page
+          initialize(**vars, page: @last)              # re-run with the last page
           @vars[:page] = requested_page                # restore the requested page
         when :empty_page
-          @offset = @items = @in = @from = @to = 0     # vars relative to the actual page
+          @offset = @limit = @in = @from = @to = 0     # vars relative to the actual page
           if defined?(Calendar::Unit) \
               && is_a?(Calendar::Unit)                 # only for Calendar::Units instances
             edge = @order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but any time would do)
@@ -57,7 +57,7 @@ class Pagy # :nodoc:
     # Support for Pagy::Countless class
     module CountlessOverride
       # Add rescue clause for different behaviors
-      def finalize(items)
+      def finalize(fetched_size)
         @overflow = false
         super
       rescue OverflowError
@@ -66,8 +66,8 @@ class Pagy # :nodoc:
         when :exception
           raise                                        # same as without the extra
         when :empty_page
-          @offset = @items = @from = @to = 0           # vars relative to the actual page
-          @vars[:size] = []                            # no page in the series
+          @offset = @limit = @from = @to = 0           # vars relative to the actual page
+          @vars[:size] = 0                             # no page in the series
           self
         else
           raise VariableError.new(self, :overflow, 'to be in [:empty_page, :exception]', @vars[:overflow])