pagy 3.8.2 → 9.4.0

data/lib/pagy/extras/gearbox.rb

@@ -0,0 +1,55 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/gearbox
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  DEFAULT[:gearbox_extra] = true # extra enabled by default
+  DEFAULT[:gearbox_limit] = [15, 30, 60, 100]
+
+  # 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
+    # Assign @limit based on the :gearbox_limit variable
+    def assign_limit
+      return super if !@vars[:gearbox_extra] || @vars[:limit_extra]
+
+      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
+
+      @limit = gears[@page - 1] || gears.last
+    end
+
+    # Asgnsi @offset based on the :gearbox_limit variable
+    def assign_offset
+      return super if !@vars[:gearbox_extra] || @vars[:limit_extra]
+
+      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
+               else
+                 pages     = 0
+                 remainder = count
+                 while remainder.positive?
+                   pages     += 1
+                   remainder -= gears[pages - 1]
+                 end
+                 [pages, 1].max
+               end)
+      @last = @vars[:max_pages] if @vars[:max_pages] && @last > @vars[:max_pages]
+    end
+  end
+  prepend GearboxExtra
+end

data/lib/pagy/extras/headers.rb

@@ -1,39 +1,54 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/headers
-# encoding: utf-8
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/headers
 # frozen_string_literal: true
 
-class Pagy
-  # Add specialized backend methods to add pagination response headers
-  module Backend ; private
+require_relative '../url_helpers'
 
-    VARS[:headers] = { page: 'Current-Page', items: 'Page-Items', count: 'Total-Count', pages: 'Total-Pages' }
+class Pagy # :nodoc:
+  DEFAULT[:headers] = { page:  'current-page',
+                        limit: 'page-items',
+                        count: 'total-count',
+                        pages: 'total-pages' }
+  # Add specialized backend methods to add pagination response headers
+  module HeadersExtra
+    include UrlHelpers
 
-    include Helpers
+    private
 
+    # Merge the pagy headers into the response.headers
     def pagy_headers_merge(pagy)
       response.headers.merge!(pagy_headers(pagy))
     end
 
+    # Generate a hash of RFC-8288 compliant http headers
     def pagy_headers(pagy)
-      hash = pagy_headers_hash(pagy)
-      hash['Link'] = hash['Link'].map{|rel, link| %(<#{link}>; rel="#{rel}")}.join(', ')
-      hash
-    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?(::Pagy::Calendar) && pagy.is_a?(Calendar::Unit))
+        return hash if (defined?(::Pagy::Countless) && pagy.is_a?(Countless)) || \
+                       (defined?(::Pagy::Keyset) && pagy.is_a?(Keyset))
 
-    def pagy_headers_hash(pagy)
-      countless = defined?(Pagy::Countless) && pagy.is_a?(Pagy::Countless)
-      rels      = { 'first' => 1, 'prev' => pagy.prev, 'next' => pagy.next }; rels['last'] = pagy.last unless countless
-      url_str   = pagy_url_for(PAGE_PLACEHOLDER, pagy, :url)
-      hash      = { 'Link' => Hash[rels.map{|rel, n|[rel, url_str.sub(PAGE_PLACEHOLDER, n.to_s)] if n}.compact] }
-      headers   = pagy.vars[:headers]
-      hash[headers[:page]]  = pagy.page.to_s         if headers[:page]
-      hash[headers[:items]] = pagy.vars[:items].to_s if headers[:items]
-      unless countless
-        hash[headers[:pages]] = pagy.pages.to_s if headers[:pages]
-        hash[headers[:count]] = pagy.count.to_s if headers[:count]
+        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?(::Pagy::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?(::Pagy::Countless) && pagy.is_a?(Countless)
+        end
+      end.join(', ') }
+    end
   end
+  Backend.prepend HeadersExtra
 end

data/lib/pagy/extras/i18n.rb

@@ -1,25 +1,26 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/i18n
-# encoding: utf-8
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/i18n
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   # Use ::I18n gem
-  module Frontend
-
-    ::I18n.load_path += Dir[Pagy.root.join('locales', '*.yml')]
-
-    Pagy::I18n.clear.instance_eval { undef :load; undef :t } # unload the pagy default constant for efficiency
-
-    alias_method :pagy_without_i18n, :pagy_t
-    if Gem::Version.new(::I18n::VERSION) < Gem::Version.new('1.6.0')
-      def pagy_t_with_i18n(*args) ::I18n.t(*args) end
-    else
-      # keep 1.9 compatibility by hiding 2.0+ syntax in string
-      module_eval <<-RUBY
-        def pagy_t_with_i18n(key, **opts) ::I18n.t(key, **opts) end
-      RUBY
+  module I18nExtra
+    # Frontend overriding for translation
+    module FrontendOverride
+      def pagy_t(key, **opts)
+        ::I18n.t(key, **opts)
+      end
     end
-    alias_method :pagy_t, :pagy_t_with_i18n
+    Frontend.prepend I18nExtra::FrontendOverride
 
+    # Calendar overriding for localization (see also the block in the calendar section of the config/pagy.rb initializer)
+    module CalendarOverride
+      def localize(time, opts)
+        ::I18n.l(time, **opts)
+      end
+    end
   end
+  Calendar::Unit.prepend I18nExtra::CalendarOverride if defined?(::Pagy::Calendar::Unit)
+
+  # Add the pagy locales to the I18n.load_path
+  ::I18n.load_path += Dir[Pagy.root.join('locales', '*.yml')]
 end

data/lib/pagy/extras/js_tools.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../b64'
+
+class Pagy # :nodoc:
+  DEFAULT[:steps] = false # default false will use {0 => @vars[:size]}
+
+  # Private module documented in the main classes
+  module JSTools
+    # Dummy tag for input helpers: needed because Turbo does not intercept window.location changes
+    A_TAG = '<a href="#" style="display: none;">#</a>'
+
+    # Additions for the Pagy class
+    module PagyAddOn
+      # `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 => 5, 350 => 7, 550 => 9})
+      # >> pagy.sequels
+      # #=> { "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)
+
+        {}.tap do |sequels|
+          steps.each { |width, step_size| sequels[width.to_s] = series(size: step_size) }
+        end
+      end
+
+      # Support for the Calendar API
+      def label_sequels(*); end
+    end
+    Pagy.prepend PagyAddOn
+
+    # Additions for Calendar class
+    module CalendarOverride
+      def label_sequels(sequels = self.sequels)
+        {}.tap do |label_sequels|
+          sequels.each do |width, series|
+            label_sequels[width] = series.map { |item| item == :gap ? :gap : label_for(item) }
+          end
+        end
+      end
+    end
+    Calendar::Unit.prepend CalendarOverride if defined?(::Pagy::Calendar::Unit)
+
+    # Additions for the Frontend
+    module FrontendAddOn
+      if defined?(::Oj)
+        # Return a data tag with the base64 encoded JSON-serialized args generated with the faster oj gem
+        # Base64 encoded JSON is smaller than HTML escaped JSON
+        def pagy_data(pagy, *args)
+          args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
+          %(data-pagy="#{B64.encode(Oj.dump(args, mode: :strict))}")
+        end
+      else
+        require 'json'
+        # Return a data tag with the base64 encoded JSON-serialized args generated with the slower to_json
+        # Base64 encoded JSON is smaller than HTML escaped JSON
+        def pagy_data(pagy, *args)
+          args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
+          %(data-pagy="#{B64.encode(args.to_json)}")
+        end
+      end
+    end
+    Frontend.prepend FrontendAddOn
+  end
+end

data/lib/pagy/extras/jsonapi.rb

@@ -0,0 +1,88 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/jsonapi
+# frozen_string_literal: true
+
+require_relative '../url_helpers'
+
+class Pagy # :nodoc:
+  DEFAULT[:jsonapi] = true
+
+  # Add a specialized backend method compliant with JSON:API
+  module JsonApiExtra
+    # JsonApi :page param error
+    class ReservedParamError < StandardError
+      # Inform about the actual value
+      def initialize(value)
+        super("expected reserved :page param to be nil or Hash-like; got #{value.inspect}")
+      end
+    end
+
+    # Module overriding Backend
+    module BackendOverride
+      include UrlHelpers
+
+      private(*UrlHelpers.instance_methods)
+
+      private
+
+      # Return the jsonapi links
+      def pagy_jsonapi_links(pagy, **opts)
+        if defined?(::Pagy::Keyset) && pagy.is_a?(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
+      def pagy_skip_jsonapi?(vars)
+        return true if vars[:jsonapi] == false || (vars[:jsonapi].nil? && DEFAULT[:jsonapi] == false)
+        # check the reserved :page param
+        raise ReservedParamError, params[:page] unless params[:page].respond_to?(:fetch) || params[:page].nil?
+      end
+
+      # Override the Backend method
+      def pagy_get_page(vars, force_integer: true)
+        return super if pagy_skip_jsonapi?(vars) || params[:page].nil?
+
+        page = params[:page][vars[:page_param] || DEFAULT[:page_param]]
+        force_integer ? (page || 1).to_i : page
+      end
+    end
+    Backend.prepend BackendOverride
+
+    # Module overriding LimitExtra
+    module LimitExtraOverride
+      private
+
+      # Override the LimitExtra::Backend method
+      def pagy_get_limit_param(vars)
+        return super if pagy_skip_jsonapi?(vars)
+        return unless params[:page]
+
+        params[:page][vars[:limit_param] || DEFAULT[:limit_param]]
+      end
+    end
+    # :nocov:
+    LimitExtra::BackendAddOn.prepend LimitExtraOverride if defined?(::Pagy::LimitExtra::BackendAddOn)
+    # :nocov:
+
+    # Module overriding UrlHelper
+    module UrlHelperOverride
+      # Override UrlHelper method
+      def pagy_set_query_params(page, vars, query_params)
+        return super unless vars[:jsonapi]
+
+        query_params['page'] ||= {}
+        query_params['page'][vars[:page_param].to_s]  = page
+        query_params['page'][vars[:limit_param].to_s] = vars[:limit] if vars[:limit_extra]
+      end
+    end
+    UrlHelpers.prepend UrlHelperOverride
+  end
+end

data/lib/pagy/extras/keyset.rb

@@ -0,0 +1,30 @@
+# 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)
+      vars[:page]  ||= pagy_get_page(vars, force_integer: false) # allow nil
+      vars[:limit] ||= pagy_get_limit(vars)
+      pagy = Keyset.new(set, **vars)
+      [pagy, pagy.records]
+    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 super unless vars.key?(:limit_extra) ? vars[:limit_extra] : DEFAULT[:limit_extra] # :limit_extra is false
+        return super 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

@@ -0,0 +1,57 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/meilisearch
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  DEFAULT[:meilisearch_search]      ||= :ms_search
+  DEFAULT[:meilisearch_pagy_search] ||= :pagy_search
+
+  # Paginate Meilisearch results
+  module MeilisearchExtra
+    module ModelExtension # :nodoc:
+      # Return an array used to delay the call of #search
+      # after the pagination variables are merged to the options
+      def pagy_meilisearch(query, params = {})
+        [self, query, params]
+      end
+      alias_method DEFAULT[:meilisearch_pagy_search], :pagy_meilisearch
+    end
+    Pagy::Meilisearch = ModelExtension
+
+    # Extension for the Pagy class
+    module PagyExtension
+      # Create a Pagy object from a Meilisearch results
+      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)
+      end
+    end
+    Pagy.extend PagyExtension
+
+    # Add specialized backend methods to paginate Meilisearch results
+    module BackendAddOn
+      private
+
+      # Return Pagy object and results
+      def pagy_meilisearch(pagy_search_args, **vars)
+        vars[:page]  ||= pagy_get_page(vars)
+        vars[:limit] ||= pagy_get_limit(vars)
+        model, term, options    = pagy_search_args
+        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)
+        # with :last_page overflow we need to re-run the method in order to get the hits
+        return pagy_meilisearch(pagy_search_args, **vars, page: pagy.page) \
+               if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
+
+        [pagy, results]
+      end
+    end
+    Backend.prepend BackendAddOn
+  end
+end

data/lib/pagy/extras/metadata.rb

@@ -1,37 +1,42 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/metadata
-# encoding: utf-8
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/metadata
 # frozen_string_literal: true
 
-class Pagy
-  # Add a specialized backend method for pagination metadata
-  module Backend ; private
+require_relative '../url_helpers'
 
-    METADATA = [ :scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url,
-                 :count, :page, :items, :vars, :pages, :last, :from, :to, :prev, :next, :series ]
-    METADATA << :sequels if VARS.key?(:steps)  # :steps gets defined along with the #sequels method
+class Pagy # :nodoc:
+  DEFAULT[:metadata] = %i[ scaffold_url first_url prev_url page_url next_url last_url
+                           count page limit vars pages last in from to prev next series ]
 
-    VARS[:metadata] = METADATA.dup
+  # Add a specialized backend method for pagination metadata
+  module MetadataExtra
+    private
 
-    include Helpers
+    include UrlHelpers
 
-    def pagy_metadata(pagy, url=false)
-      names = pagy.vars[:metadata]
-      (unknown = names - METADATA).empty? or raise(VariableError.new(pagy), "unknown metadata #{unknown.inspect}")
-      scaffold_url = pagy_url_for(PAGE_PLACEHOLDER, pagy, url)
-      metadata = {}
-      names.each do |key|
-        metadata[key] = case key
-                        when :scaffold_url ; scaffold_url
-                        when :first_url    ; scaffold_url.sub(PAGE_PLACEHOLDER, 1.to_s)
-                        when :prev_url     ; scaffold_url.sub(PAGE_PLACEHOLDER, pagy.prev.to_s)
-                        when :page_url     ; scaffold_url.sub(PAGE_PLACEHOLDER, pagy.page.to_s)
-                        when :next_url     ; scaffold_url.sub(PAGE_PLACEHOLDER, pagy.next.to_s)
-                        when :last_url     ; scaffold_url.sub(PAGE_PLACEHOLDER, pagy.last.to_s)
-                        else pagy.send(key)
-                        end
+    # Return the metadata hash
+    def pagy_metadata(pagy, absolute: nil)
+      scaffold_url = pagy_url_for(pagy, PAGE_TOKEN, absolute:)
+      {}.tap do |metadata|
+        keys = if defined?(::Pagy::Calendar::Unit) && pagy.is_a?(Calendar::Unit)
+                 pagy.vars[:metadata] - %i[count limit]
+               else
+                 pagy.vars[:metadata]
+               end
+        keys.each do |key|
+          metadata[key] = case key
+                          when :scaffold_url then scaffold_url
+                          when :first_url    then scaffold_url.sub(PAGE_TOKEN, 1.to_s)
+                          when :prev_url     then scaffold_url.sub(PAGE_TOKEN, pagy.prev.to_s)
+                          when :page_url     then scaffold_url.sub(PAGE_TOKEN, pagy.page.to_s)
+                          when :next_url     then scaffold_url.sub(PAGE_TOKEN, pagy.next.to_s)
+                          when :last_url     then scaffold_url.sub(PAGE_TOKEN, pagy.last.to_s)
+                          else pagy.send(key)
+                          end
+        rescue NoMethodError
+          raise VariableError.new(pagy, :metadata, 'to contain known keys', key)
+        end
       end
-      metadata
     end
-
   end
+  Backend.prepend MetadataExtra
 end