pagy 9.4.0 → 43.2.0

data/lib/pagy/toolbox/helpers/support/series.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Pagy
+  SERIES_SLOTS = 7
+
+  protected
+
+  # Return the array of page numbers and :gap e.g. [1, :gap, 8, "9", 10, :gap, 36]
+  def series(slots: @options[:slots] || SERIES_SLOTS, compact: @options[:compact], **)
+    raise OptionError.new(self, :slots, 'to be an Integer >= 0', slots) \
+          unless slots.is_a?(Integer) && slots >= 0
+    return [] if slots.zero?
+
+    [].tap do |series|
+      if slots >= @last
+        series.push(*1..@last)
+      else
+        half  = (slots - 1) / 2                       # the left half might be 1 page shorter when the slots are even
+        start = if @page <= half                      # @page in the first half
+                  1
+                elsif @page > (@last - slots + half)  # @page in the last half
+                  @last - slots + 1
+                else                                  # @page in the middle
+                  @page - half
+                end
+        series.push(*(start...(start + slots)))
+        unless compact || slots < SERIES_SLOTS        # Set first, last and :gap when needed
+          series[0]  = 1
+          series[1]  = :gap unless series[1]  == 2
+          series[-2] = :gap unless series[-2] == @last - 1
+          series[-1] = @last
+        end
+      end
+      current = series.index(@page)
+      series[current] = @page.to_s if current
+    end
+  end
+end

data/lib/pagy/toolbox/helpers/support/wrap_input_nav_js.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'nav_aria_label_attribute'
+require_relative 'data_pagy_attribute'
+require_relative 'a_lambda' # inherited use
+
+# Relegate internal functions. Make overriding navs easier.
+class Pagy
+  private
+
+  # Build the input_nav_js tag, with the specific inner html for the style
+  def wrap_input_nav_js(html, nav_classes, id: nil, aria_label: nil, **)
+    %(<nav#{%( id="#{id}") if id} class="#{nav_classes}" #{
+      nav_aria_label_attribute(aria_label:)} #{
+      data = [:inj, compose_page_url(PAGE_TOKEN, **)]
+      data.push(@update) if keynav?
+      data_pagy_attribute(*data)
+      }>#{html}</nav>)
+  end
+end

data/lib/pagy/toolbox/helpers/support/wrap_series_nav.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'series'
+require_relative 'nav_aria_label_attribute'
+require_relative 'data_pagy_attribute'
+require_relative 'a_lambda' # inherited use
+
+# Relegate internal functions. Make overriding navs easier.
+class Pagy
+  private
+
+  # Build the nav tag, with the specific inner html for the style
+  def wrap_series_nav(html, nav_classes, id: nil, aria_label: nil, **)
+    data = %( #{data_pagy_attribute(:k, @update)}) if keynav?
+    %(<nav#{%( id="#{id}") if id} class="#{nav_classes}" #{nav_aria_label_attribute(aria_label:)}#{data}>#{html}</nav>)
+  end
+end

data/lib/pagy/toolbox/helpers/support/wrap_series_nav_js.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'series'
+require_relative 'nav_aria_label_attribute'
+require_relative 'data_pagy_attribute'
+require_relative 'a_lambda' # inherited use
+
+# Relegate internal functions. Make overriding navs easier.
+class Pagy
+  private
+
+  # Return the reverse sorted array of widths, series, and labels generated from the :steps hash
+  # If :steps is false it will use the single {0 => @options[:slots]} length
+  def sequels(steps: @options[:steps] || { 0 => @options[:slots] || SERIES_SLOTS }, **)
+    raise OptionError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
+
+    widths, series = steps.sort.reverse.map { |width, slots| [width, series(slots:)] }.transpose
+    [widths, series, page_labels(series)]
+  end
+
+  # Support for the Calendar API
+  def page_labels(series)
+    series.map { |s| s.map { |item| item == :gap ? :gap : page_label(item) } } if calendar?
+  end
+
+  # Build the nav_js tag, with the specific tokens for the style
+  def wrap_series_nav_js(tokens, nav_classes, id: nil, aria_label: nil, **)
+    sequels = sequels(**)
+    nav_classes = "pagy-rjs #{nav_classes}" if sequels[0].size > 1
+    %(<nav#{%( id="#{id}") if id} class="#{nav_classes}" #{
+      nav_aria_label_attribute(aria_label:)} #{
+      data = [:snj, tokens.values, sequels]
+      data.push(@update) if keynav?
+      data_pagy_attribute(*data)
+      }></nav>)
+  end
+end

data/lib/pagy/toolbox/helpers/urls_hash.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Generate the hash of the pagination links
+  def urls_hash(**)
+    template = compose_page_url(PAGE_TOKEN, **)
+
+    { first:    compose_page_url(nil, **),
+      previous: @previous && template.sub(PAGE_TOKEN, @previous.to_s),
+      next:     @next     && template.sub(PAGE_TOKEN, @next.to_s),
+      last:     @count    && template.sub(PAGE_TOKEN, @last.to_s) }.compact
+  end
+end

data/lib/pagy/toolbox/paginators/calendar.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Pagy
+  module CalendarPaginator
+    module_function
+
+    # Take a collection and a configuration Hash and return an array with 3 items: [calendar, pagy, results]
+    def paginate(context, collection, config)
+      context.instance_eval do
+        allowed_options = Calendar::UNITS + %i[offset disabled request]
+        raise ArgumentError, "keys must be in #{allowed_options.inspect}" \
+              unless config.is_a?(Hash) && (config.keys - allowed_options).empty?
+
+        config[:offset] ||= {}
+        unless config[:disabled]
+          calendar, from, to =
+            Calendar.send(:init, config,
+                          pagy_calendar_period(collection),
+                          config[:request].params) do |unit, period|
+              pagy_calendar_counts(collection, unit, *period) if respond_to?(:pagy_calendar_counts)
+            end
+          collection = pagy_calendar_filter(collection, from, to)
+        end
+        pagy, records = pagy(:offset, collection, **config[:offset])
+        [calendar, pagy, records]
+      end
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/countish.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/abilities/countable'
+
+class Pagy
+  module CountishPaginator
+    module_function
+
+    # Return the Offset::Countish instance and records
+    def paginate(collection, options)
+      options[:page] ||= options[:request].resolve_page(force_integer: false)
+      if options[:page].is_a?(String)
+        page, count, epoch = options[:page].split.map(&:to_i)
+        options[:page]     = page
+      end
+      setup_options(count, epoch, collection, options)
+      options[:limit] = options[:request].resolve_limit
+      pagy            = Offset::Countish.new(**options)
+      [pagy, pagy.records(collection)]
+    end
+
+    # Get the count from the page and set epoch when ttl (Time To Live) requires it
+    def setup_options(count, epoch, collection, options)
+      now = Time.now.to_i
+      if !options[:count] && count && (!options[:ttl] ||
+         (epoch && epoch <= now && now < (epoch + options[:ttl]))) # ongoing
+        # puts 'ongoing'
+        options[:count] = count
+        options[:epoch] = epoch if options[:ttl]
+      else # recount
+        # puts 'recount'
+        options[:count] ||= Countable.get_count(collection, options)
+        options[:epoch]   = now if options[:ttl]
+      end
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/countless.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Pagy
+  module CountlessPaginator
+    module_function
+
+    # Return the Offset::Countless instance and records
+    def paginate(collection, options)
+      options[:page] ||= options[:request].resolve_page(force_integer: false) # accept nil and strings
+      if options[:page].is_a?(String)
+        page, last     = options[:page].split.map(&:to_i) # decoded '+' added by the compose_page_url
+        options[:page] = page
+        options[:last] = last if last&.positive?
+      end
+      options[:limit] = options[:request].resolve_limit
+      pagy            = Offset::Countless.new(**options)
+      [pagy, pagy.records(collection)]
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/elasticsearch_rails.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/searcher'
+
+class Pagy
+  module ElasticsearchRailsPaginator
+    module_function
+
+    # Paginate from the search object
+    def paginate(search, options)
+      if search.is_a?(Search::Arguments)
+        # The search is the array of pagy_search arguments
+        Searcher.wrap(search, options) do
+          model, query_or_payload, search_options = search
+          search_options[:size] = options[:limit]
+          search_options[:from] = options[:limit] * ((options[:page] || 1) - 1)
+          response_object       = model.send(options[:search_method] || ElasticsearchRails::DEFAULT[:search_method],
+                                             query_or_payload, **search_options)
+          options[:count]       = total_count_from(response_object)
+          [ElasticsearchRails.new(**options), response_object]
+        end
+      else
+        from, size      = pagination_params_from(search)
+        options[:limit] = size
+        options[:page]  = ((from || 0) / options[:limit]) + 1
+        options[:count] = total_count_from(search)
+        ElasticsearchRails.new(**options)
+      end
+    end
+
+    # Get from and size params from the response object, supporting different versions of ElasticsearchRails
+    def pagination_params_from(response_object)
+      definition = response_object.search.definition
+      definition = definition.to_hash if definition.respond_to?(:to_hash)
+      container  = (definition.is_a?(Hash) && (definition[:body] || definition)) || response_object.search.options
+      from       = (container[:from] || container['from']).to_i
+      size       = (container[:size] || container['size']).to_i
+      size       = 10 if size.zero?
+      [from, size]
+    end
+
+    # Get the count from the response object, supporting different versions of ElasticsearchRails
+    def total_count_from(response_object)
+      total = response_object.instance_eval do
+                respond_to?(:response) ? response['hits']['total'] : raw_response['hits']['total']
+              end
+      total.is_a?(Hash) ? total['value'] : total
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/keynav_js.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../../../pagy/modules/b64'
+
+class Pagy
+  module KeynavJsPaginator
+    module_function
+
+    # Return the Pagy::Keyset::Keynav instance and paginated records.
+    # Fall back to :countless if the :page has no client data.
+    def paginate(set, options)
+      page = options[:request].resolve_page(force_integer: false) # allow nil
+      if page&.match(' ')       # countless page -> no augmentation -> fallback
+        return CountlessPaginator.paginate(set, page:, **options)
+      elsif page.is_a?(String)  # keynav page param
+        page_arguments = JSON.parse(B64.urlsafe_decode(page))
+        # Restart the pagination from page 1/nil if the url has been requested from another browser
+        options[:page] = page_arguments if options[:request].cookie == page_arguments.shift
+      end
+
+      options[:limit] = options[:request].resolve_limit
+      pagy = Keyset::Keynav.new(set, **options)
+      [pagy, pagy.records]
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/keyset.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Pagy
+  module KeysetPaginator
+    module_function
+
+    # Return Pagy::Keyset instance and paginated records
+    def paginate(set, options)
+      options[:page] ||= options[:request].resolve_page(force_integer: false) # allow nil
+      options[:limit]  = options[:request].resolve_limit
+      pagy = Keyset.new(set, **options)
+      [pagy, pagy.records]
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/meilisearch.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/searcher'
+
+class Pagy
+  module MeilisearchPaginator
+    module_function
+
+    # Paginate from the search object
+    def paginate(search, options)
+      if search.is_a?(Search::Arguments)
+        # The search is the array of pagy_search arguments
+        Searcher.wrap(search, options) do
+          model, term, search_options    = search
+          search_options[:hits_per_page] = options[:limit]
+          search_options[:page]          = options[:page]
+          results                        = model.send(options[:search_method] || Meilisearch::DEFAULT[:search_method],
+                                                      term, search_options)
+          options[:count]                = results.raw_answer['totalHits']
+          [Meilisearch.new(**options), results]
+        end
+      else
+        # The search is a meilisearch results object
+        options[:limit] = search.raw_answer['hitsPerPage']
+        options[:page]  = search.raw_answer['page']
+        options[:count] = search.raw_answer['totalHits']
+        Meilisearch.new(**options)
+      end
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/method.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../../classes/request'
+
+class Pagy
+  paginators = { offset:              :OffsetPaginator,
+                 countless:           :CountlessPaginator,
+                 countish:            :CountishPaginator,
+                 keyset:              :KeysetPaginator,
+                 keynav_js:           :KeynavJsPaginator,
+                 calendar:            :CalendarPaginator,
+                 elasticsearch_rails: :ElasticsearchRailsPaginator,
+                 meilisearch:         :MeilisearchPaginator,
+                 searchkick:          :SearchkickPaginator }.freeze
+
+  path = Pathname.new(__dir__)
+  paginators.each { |symbol, name| autoload name, path.join(symbol.to_s) }
+
+  # Pagy::Method defines the #pagy method to be included in the app controller/view.
+  Method = Module.new do
+             protected
+
+             define_method :pagy do |paginator = :offset, collection, **options|
+               arguments = if paginator == :calendar
+                             [self, collection, options]
+                           else
+                             [collection, options = Pagy.options.merge(options)]
+                           end
+               options[:root_key]  = 'page' if options[:jsonapi] # enforce 'page' root_key for JSON:API
+               options[:request] ||= request                     # user set request or self.request
+               options[:request]   = Request.new(options)        # Pagy::Request
+               Pagy.const_get(paginators[paginator]).paginate(*arguments)
+             end
+           end
+end

data/lib/pagy/toolbox/paginators/offset.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/abilities/countable'
+
+class Pagy
+  module OffsetPaginator
+    module_function
+
+    # Return the Pagy::Offset instance and results
+    def paginate(collection, options)
+      options[:page]  ||= options[:request].resolve_page
+      options[:limit]   = options[:request].resolve_limit
+      options[:count] ||= Countable.get_count(collection, options)
+      pagy = Offset.new(**options)
+      [pagy, collection.instance_of?(Array) ? collection[pagy.offset, pagy.limit] : pagy.records(collection)]
+    end
+  end
+end

data/lib/pagy/toolbox/paginators/searchkick.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/searcher'
+
+class Pagy
+  module SearchkickPaginator
+    module_function
+
+    # Paginate from the search object
+    def paginate(search, options)
+      if search.is_a?(Search::Arguments)
+        # The search is the array of pagy_search arguments
+        Searcher.wrap(search, options) do
+          model, term, search_options, block = search
+          search_options[:per_page] = options[:limit]
+          search_options[:page]     = options[:page]
+          results                   = model.send(options[:search_method] || Searchkick::DEFAULT[:search_method],
+                                                 term || '*', **search_options, &block)
+          options[:count]           = results.total_count
+          [Searchkick.new(**options), results]
+        end
+      else
+        # The search is a searchkick results object
+        options[:limit] = search.respond_to?(:options) ? search.options[:per_page] : search.per_page
+        options[:page]  = search.respond_to?(:options) ? search.options[:page]     : search.current_page
+        options[:count] = search.total_count
+        Searchkick.new(**options)
+      end
+    end
+  end
+end

data/lib/pagy.rb

@@ -1,106 +1,68 @@
-# See Pagy API documentation: https://ddnexus.github.io/pagy/docs/api/pagy
 # frozen_string_literal: true
 
 require 'pathname'
-require_relative 'pagy/shared_methods'
+require_relative 'pagy/classes/exceptions'
+require_relative 'pagy/modules/abilities/linkable'
+require_relative 'pagy/modules/abilities/configurable'
+require_relative 'pagy/toolbox/helpers/loader'
 
-# Top superclass: it should define only what's common to all the subclasses
+# Top superclass: it defines only what's common to all the subclasses
 class Pagy
-  VERSION = '9.4.0'
-
-  # Core default: constant for easy access, but mutable for customizable defaults
-  DEFAULT = { count_args: [:all], # rubocop:disable Style/MutableConstant
-              ends:       true,
-              limit:      20,
-              outset:     0,
-              page:       1,
-              page_param: :page,
-              size:       7 }  # AR friendly
-
-  # Gem root pathname to get the path of Pagy files stylesheets, javascripts, apps, locales, etc.
-  def self.root
-    @root ||= Pathname.new(__dir__).parent.freeze
-  end
-
-  include SharedMethods
-
-  attr_reader :count, :from, :in, :last, :next, :offset, :prev, :to
-  alias pages last
-
-  # Merge and validate the options, do some simple arithmetic and set the instance variables
-  def initialize(**vars)
-    assign_vars(DEFAULT, vars)
-    assign_and_check(count: 0, page: 1, outset: 0)
-    assign_limit
-    assign_offset
-    assign_last
-    check_overflow
-    @from = [@offset - @outset + 1, @count].min
-    @to   = [@offset - @outset + @limit, @count].min
-    @in   = [@to - @from + 1, @count].min
-    assign_prev_and_next
-  end
-
-  # Setup @last (overridden by the gearbox extra)
-  def assign_last
-    @last = [(@count.to_f / @limit).ceil, 1].max
-    @last = @vars[:max_pages] if @vars[:max_pages] && @last > vars[:max_pages]
-  end
-
-  # Assign @offset (overridden by the gearbox extra)
-  def assign_offset
-    @offset = (@limit * (@page - 1)) + @outset  # may be already set from gear_box
-  end
-
-  # Assign @prev and @next
-  def assign_prev_and_next
-    @prev = (@page - 1 unless @page == 1)
-    @next = @page == @last ? (1 if @vars[:cycle]) : @page + 1
-  end
-
-  # Checks the @page <= @last
-  def check_overflow
-    raise OverflowError.new(self, :page, "in 1..#{@last}", @page) if @page > @last
+  VERSION     = '43.2.0'
+  ROOT        = Pathname.new(__dir__).parent.freeze
+  DEFAULT     = { limit: 20, limit_key: 'limit', page_key: 'page' }.freeze
+  PAGE_TOKEN  = EscapedValue.new('P ')
+  LIMIT_TOKEN = EscapedValue.new('L ')
+  LABEL_TOKEN = 'L'
+  A_TAG       = '<a style="display: none;">#</a>'
+
+  path = Pathname.new(__FILE__).sub_ext('')
+  autoload :Method,             path.join('toolbox/paginators/method')
+  autoload :I18n,               path.join('modules/i18n/i18n')
+  autoload :Console,            path.join('modules/console')
+  autoload :Calendar,           path.join('classes/calendar/calendar')
+  autoload :Offset,             path.join('classes/offset/offset')
+  autoload :Search,             path.join('classes/offset/search')
+  autoload :ElasticsearchRails, path.join('classes/offset/search')
+  autoload :Meilisearch,        path.join('classes/offset/search')
+  autoload :Searchkick,         path.join('classes/offset/search')
+  autoload :Keyset,             path.join('classes/keyset/keyset')
+
+  def self.options = @options ||= {}
+
+  extend Configurable
+  include Linkable
+  include Loader
+
+  attr_reader :page, :next, :in, :limit, :options
+
+  protected
+
+  # Define the hierarchical identity methods, overridden by the respective classes
+  def offset?    = false
+  def countless? = false
+  def calendar?  = false
+  def search?    = false
+  def keyset?    = false
+  def keynav?    = false
+
+  # Validates and assign the passed options: they must be present and value.to_i must be >= min
+  def assign_and_check(name_min)
+    name_min.each do |name, min|
+      raise OptionError.new(self, name, ">= #{min}", @options[name]) \
+            unless @options[name].respond_to?(:to_i) && instance_variable_set(:"@#{name}", @options[name].to_i) >= min
+    end
   end
 
-  # Label for the current page. Allow the customization of the output (overridden by the calendar extra)
-  def label = @page.to_s
-
-  # Label for any page. Allow the customization of the output (overridden by the calendar extra)
-  def label_for(page) = page.to_s
-
-  # Return the array of page numbers and :gap e.g. [1, :gap, 8, "9", 10, :gap, 36]
-  def series(size: @vars[:size], **_)
-    raise VariableError.new(self, :size, 'to be an Integer >= 0', size) \
-    unless size.is_a?(Integer) && size >= 0
-    return [] if size.zero?
-
-    [].tap do |series|
-      if size >= @last
-        series.push(*1..@last)
-      else
-        left  = ((size - 1) / 2.0).floor             # left half might be 1 page shorter for even size
-        start = if @page <= left                     # beginning pages
-                  1
-                elsif @page > (@last - size + left)  # end pages
-                  @last - size + 1
-                else                                 # intermediate pages
-                  @page - left
-                end
-        series.push(*start...(start + size))
-        # Set first and last pages plus gaps when needed, respecting the size
-        if vars[:ends] && size >= 7
-          series[0]  = 1
-          series[1]  = :gap  unless series[1]  == 2
-          series[-2] = :gap  unless series[-2] == @last - 1
-          series[-1] = @last
-        end
-      end
-      series[series.index(@page)] = @page.to_s
-    end
+  # Merge all the DEFAULT constants of the class hierarchy with the options
+  def assign_options(**options)
+    @request = options.delete(:request) # internal object
+    default  = {}
+    current  = self.class
+    begin
+      default = current::DEFAULT.merge(default)
+      current = current.superclass
+    end until current == Object  # rubocop:disable Lint/Loop  -- see https://github.com/rubocop/rubocop-performance/issues/362
+    @options = default.merge!(options.delete_if { |k, v| default.key?(k) && (v.nil? || v == '') }).freeze
   end
 end
-
-require_relative 'pagy/backend'
-require_relative 'pagy/frontend'
-require_relative 'pagy/exceptions'

data/locales/ar.yml

@@ -1,6 +1,8 @@
-# :arabic pluralization (see https://github.com/ddnexus/pagy/blob/master/gem/lib/pagy/i18n.rb)
+# See https://ddnexus.github.io/pagy/resources/i18n
+
 ar:
   pagy:
+    p11n: 'Arabic'
     aria_label:
       nav:
         zero: "لا يوجد صفحات"
@@ -9,9 +11,9 @@ ar:
         few: "صفحات"
         many: "صفحات"
         other: "صفحات"
-      prev: "السابق"
+      previous: "السابق"
       next: "التالي"
-    prev: "<"
+    previous: "<"
     next: ">"
     gap: "…"
     item_name:
@@ -21,9 +23,10 @@ ar:
       few: "قليل"
       many: "كثير"
       other: "عناصر"
-    info:
+    info_tag:
+      no_count: "الصفحة %{page} من %{pages}"
       no_items: "لا يوجد %{item_name}"
       single_page: "عرض %{count} %{item_name}"
       multiple_pages: "عرض %{item_name} %{from}-%{to} من اجمالي %{count}"
-    combo_nav_js: "الصفحة %{page_input} من %{pages}"
-    limit_selector_js: "عرض %{limit_input} %{item_name} لكل صفحة"
+    input_nav_js: "الصفحة %{page_input} من %{pages}"
+    limit_tag_js: "عرض %{limit_input} %{item_name} لكل صفحة"