pagy 5.1.3 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a490edf32ff73a19ad4f36527bac6d78fafef9d8fbffa856cecdf69acaa12a0c
-  data.tar.gz: 88c7c87f8ebaaadf628921b0ad3defe769875f2a7d87c55b61c09ee3eba72ea0
+  metadata.gz: 75bb34a884999d7ec40e067e8218a43c4d12193680014731a3c469c435370709
+  data.tar.gz: fcd39cc96ec420b6f2365b57ab3256559ec34cfbf72e0980cf555d60c5086122
 SHA512:
-  metadata.gz: 3af70d18f3d74f1bed4df53e21473117365b7b8fb4e58912f1cdae5ca9ac4c59c7bd76ab31856c3617381c0a0fc78dd23f9508f5f4620d7756326d174844f6a1
-  data.tar.gz: 5ca447531cfeb68d3c5cd2c729ac6f32c17f214db2438fb4a54704ec0e6dc634f81a367ed176e76deffe3b08e3e78829af2870db8e66c47ca0f6440d78ab906b
+  metadata.gz: 2aab474d8a2780320e4c13f2a79e9c6dbbe82657bbc9bc75135902c7c9ee27e1a742cf415b9588a712e4629914decc7abdfbc4e2dca0fdbf0eaf3436ca6b4376
+  data.tar.gz: ae28683579224c8cfe7442fafef13e7f767e926d34f4e56d420efd234622f93758ec270a036d7b7e900a2e0a3637a3cdcf2f6e1cee6dbf945f1b593fc4291e9e

data/lib/config/pagy.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.1.3)
+# Pagy initializer file (5.2.0)
 # Customize only what you really need and notice that Pagy works also without any of the following lines.
 # Should you just cherry pick part of this file, please maintain the require-order of the extras
 
 
-# Pagy Variables
+# Pagy DEFAULT Variables
 # See https://ddnexus.github.io/pagy/api/pagy#variables
-# All the Pagy::DEFAULT are set for all the Pagy instances but can be overridden
-# per instance by just passing them to Pagy.new or the #pagy controller method
+# All the Pagy::DEFAULT are set for all the Pagy instances but can be overridden per instance
+# by just passing them to Pagy.new|Pagy::Countless.new|Pagy::Calendar.new or the #pagy controller method
 
 
 # Instance variables
@@ -39,6 +39,18 @@
 # See https://ddnexus.github.io/pagy/extras/array
 # require 'pagy/extras/array'
 
+# Calendar extra: Paginate a collection by calendar Time unit (year, month, week or day)
+# See https://ddnexus.github.io/pagy/extras/calendar
+# require 'pagy/extras/calendar'
+# Pagy::DEFAULT[:local_minmax] = []          # Min and max local Time period must be set by the user (better not not as default)
+# Pagy::DEFAULT[:unit]         = :month      # Time unit allowed %i[year month week day]
+# Pagy::DEFAULT[:week_offset]  = 0           # Day offset from Sunday (0: Sunday; 1: Monday;... 6: Saturday)
+# Pagy::DEFAULT[:order]         = :asc        # Time direction of pagination
+# Pagy::DEFAULT[:year_format]  = '%Y'        # strftime format for :year unit
+# Pagy::DEFAULT[:month_format] = '%Y-%m'     # strftime format for :month unit
+# Pagy::DEFAULT[:week_format]  = '%Y-%W'     # strftime format for :week unit
+# Pagy::DEFAULT[:day_format]   = '%Y-%m-%d'  # strftime format for :day unit
+
 # Countless extra: Paginate without any count, saving one query per rendering
 # See https://ddnexus.github.io/pagy/extras/countless
 # require 'pagy/extras/countless'
@@ -72,7 +84,7 @@
 # require 'pagy/extras/shared'
 # require 'pagy/extras/metadata'
 # For performance reason, you should explicitly set ONLY the metadata you use in the frontend
-# Pagy::DEFAULT[:metadata] = [:scaffold_url, :count, :page, :prev, :next, :last]    # example
+# Pagy::DEFAULT[:metadata] = %i[scaffold_url count page prev next last]   # example
 
 # Searchkick extra: Paginate `Searchkick::Results` objects
 # See https://ddnexus.github.io/pagy/extras/searchkick

data/lib/javascripts/pagy.js

@@ -3,7 +3,7 @@
 // Container of the whole pagy stuff
 function Pagy(){}
 
-Pagy.version = '5.1.3'
+Pagy.version = '5.2.0'
 
 // Used by the waitForMe function
 Pagy.delay = 100

data/lib/pagy/calendar.rb

@@ -0,0 +1,143 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+require 'pagy'
+require 'date'
+
+class Pagy # :nodoc:
+  DEFAULT[:local_minmax] = []          # Min and max Time period must be set by the user
+  DEFAULT[:unit]         = :month      # Time unit allowed %i[year month week day]
+  DEFAULT[:week_offset]  = 0           # Day offset from Sunday (0: Sunday; 1: Monday;... 6: Saturday)
+  DEFAULT[:order]        = :asc        # Time direction of pagination
+  DEFAULT[:year_format]  = '%Y'        # strftime format for :year unit
+  DEFAULT[:month_format] = '%Y-%m'     # strftime format for :month unit
+  DEFAULT[:week_format]  = '%Y-%W'     # strftime format for :week unit
+  DEFAULT[:day_format]   = '%Y-%m-%d'  # strftime format for :day unit
+
+  # Paginate a Time period by units (year, month, week or day)
+  class Calendar < Pagy
+    attr_reader :utc_from, :utc_to, :unit, :week_offset, :order
+    attr_writer :count, :in
+
+    # Merge and validate the options, do some simple arithmetic and set a few instance variables
+    def initialize(vars) # rubocop:disable Lint/MissingSuper
+      normalize_vars(vars)
+      setup_vars(page: 1, week_offset: 0)
+      setup_unit_vars
+      raise OverflowError.new(self, :page, "in 1..#{@last}", @page) if @page > @last
+
+      @prev = (@page - 1 unless @page == 1)
+      @next = @page == @last ? (1 if @vars[:cycle]) : @page + 1
+    end
+
+    # Generate a label for each page, with the specific `Time` period it refers to
+    def page_label(num = @page)
+      snap = snap(num.to_i)
+      case @unit
+      when :year  then new_time(@initial.year + snap)
+      when :month then bump_month(@initial, snap)
+      when :week  then @initial + (snap * WEEK)
+      when :day   then @initial + (snap * DAY)
+      else raise InternalError, "expected @unit to be in [:year, :month, :week, :day]; got #{@unit.inspect}"
+      end.strftime(@vars[:"#{@unit}_format"])
+    end
+
+    DAY  = 60 * 60 * 24
+    WEEK = DAY * 7
+
+    protected
+
+    def setup_unit_vars
+      (units = %i[year month week day]).each do |unit|
+        raise VariableError.new(self, :format, 'to be a strftime format', @vars[:"#{unit}_format"]) \
+              unless @vars[:"#{unit}_format"].is_a?(String)
+      end
+      raise VariableError.new(self, :unit, "to be in #{units.inspect}", @unit) \
+            unless units.include?(@unit = @vars[:unit])
+      raise VariableError.new(self, :order, 'to be in [:asc, :desc]', @order) \
+            unless %i[asc desc].include?(@order = @vars[:order])
+
+      min, max = @vars[:local_minmax]
+      raise VariableError.new(self, :local_minmax, 'to be a an Array of min and max local Time instances', @vars[:local_minmax]) \
+            unless min.is_a?(Time) && max.is_a?(Time) && !min.utc? && !min.utc? && min <= max \
+                   && (@utc_offset = min.utc_offset) == max.utc_offset
+
+      send :"setup_#{@unit}_vars", min, max
+    end
+
+    # IMPORTANT: all the Time objects created and passed as arguments MUST be local!
+
+    # @initial:  beginning of the first day of the period that encloses the min local time
+    # @final:    beginning of the first day of the NEXT period AFTER the period that encloses the max local time
+    # @utc_from: beginning of the first day of the period of the current page as UTC time
+    # @utc_to:   beginning of the first day of the NEXT period AFTER the current page as UTC time
+
+    # Setup the calendar vars when the unit is :year
+    def setup_year_vars(min, max)
+      @initial  = new_time(min.year)
+      @final    = new_time(max.year + 1)
+      @pages    = @last = @final.year - @initial.year
+      @utc_from = new_time(@initial.year + snap).utc
+      @utc_to   = new_time(@initial.year + snap + 1).utc
+    end
+
+    # Setup the calendar vars when the unit is :month
+    def setup_month_vars(min, max)
+      @initial  = new_time(min.year, min.month)
+      @final    = bump_month(max)
+      @pages    = @last = months(@final) - months(@initial)
+      @utc_from = bump_month(@initial, snap).utc
+      @utc_to   = bump_month(@initial, snap + 1).utc
+    end
+
+    # Setup the calendar vars when the unit is :week
+    def setup_week_vars(min, max)
+      @initial  = week_start(min)
+      @final    = week_start(max) + WEEK
+      @pages    = @last = (@final - @initial).to_i / WEEK
+      @utc_from = (@initial + (snap * WEEK)).utc
+      @utc_to   = @utc_from + WEEK
+    end
+
+    # Setup the calendar vars when the unit is :day
+    def setup_day_vars(min, max)
+      @initial  = new_time(min.year, min.month, min.day)
+      @final    = new_time(max.year, max.month, max.day) + DAY
+      @pages    = @last = (@final - @initial).to_i / DAY
+      @utc_from = (@initial + (snap * DAY)).utc
+      @utc_to   = @utc_from + DAY
+    end
+
+    private
+
+    # Simple trick to snap the page into its ordered position,
+    # without actually reordering anything in the internal structure
+    def snap(page = @page)
+      @order == :asc ? page - 1 : @pages - page
+    end
+
+    # Create a new local time at the beginning of the day
+    def new_time(year, month = 1, day = 1)
+      Time.new(year, month, day, 0, 0, 0, @utc_offset)
+    end
+
+    # Months in local time
+    def months(time)
+      (time.year * 12) + time.month
+    end
+
+    # Add 1 or more months to local time
+    def bump_month(time, months = 1)
+      months += months(time)
+      year  = months / 12
+      month = months % 12
+      month.zero? ? new_time(year - 1, 12) : new_time(year, month)
+    end
+
+    # Return the start of the week for local time
+    def week_start(time)
+      start = time - (((time.wday - @week_offset) * DAY) % WEEK)
+      new_time(start.year, start.month, start.day)
+    end
+  end
+end

data/lib/pagy/countless.rb

@@ -16,7 +16,7 @@ class Pagy
 
     # Finalize the instance variables based on the fetched size
     def finalize(fetched_size)
-      raise OverflowError.new(self, :page, "to be < #{@page}") if fetched_size.zero? && @page > 1
+      raise OverflowError.new(self, :page, "to be < #{@page}", @page) if fetched_size.zero? && @page > 1
 
       @pages = @last = (fetched_size > @items ? @page + 1 : @page)
       @in    = [fetched_size, @items].min

data/lib/pagy/exceptions.rb

@@ -6,13 +6,11 @@ class Pagy
     attr_reader :pagy, :variable, :value
 
     # Set the variables and prepare the message
-    def initialize(pagy, variable, description, value = nil)
+    def initialize(pagy, variable, description, value)
       @pagy     = pagy
       @variable = variable
       @value    = value
-      message   = +"expected :#{@variable} #{description}"
-      message  << "; got #{@value.inspect}" if value
-      super message
+      super "expected :#{@variable} #{description}; got #{@value.inspect}"
     end
   end
 

data/lib/pagy/extras/arel.rb

@@ -1,7 +1,8 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/arel
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
+  # Better performance of grouped ActiveRecord collections
   module ArelExtra
     private
 

data/lib/pagy/extras/array.rb

@@ -1,8 +1,8 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/array
 # frozen_string_literal: true
 
-class Pagy
-  # Add specialized backend methods to paginate array collections
+class Pagy # :nodoc:
+  # Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding
   module ArrayExtra
     private
 

data/lib/pagy/extras/bootstrap.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module BootstrapExtra

data/lib/pagy/extras/bulma.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module BulmaExtra

data/lib/pagy/extras/calendar.rb

@@ -0,0 +1,46 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/calendar
+# frozen_string_literal: true
+
+require 'pagy/calendar'
+
+class Pagy # :nodoc:
+  # Paginate based on calendar periods (year month week day)
+  module CalendarExtra
+    # Additions for the Backend module
+    module Backend
+      private
+
+      # Return Pagy object and items
+      def pagy_calendar(collection, vars = {})
+        pagy = Calendar.new(pagy_calendar_get_vars(collection, vars))
+        [pagy, pagy_calendar_get_items(collection, pagy)]
+      end
+
+      # Sub-method called only by #pagy_calendar: here for easy customization of variables by overriding.
+      # You may want to override it in order to implement the dynamic set of the :minmax variable.
+      def pagy_calendar_get_vars(_collection, vars)
+        # vars[:minmax] ||= your_own_method_to_get_the_period_from(collection)
+        vars[:page] ||= params[vars[:page_param] || DEFAULT[:page_param]]
+        vars
+      end
+
+      # This method should be implemented in the application and should return the records
+      # for the unit by selecting the records with DateTime from pagy.from to pagy.to
+      def pagy_calendar_get_items(_collection, _pagy)
+        # collection.your_own_method_to_get_the_items_with(pagy.from, pagy.to)
+        raise NoMethodError, 'The pagy_calendar_get_items method must be implemented in the application and must return ' \
+                             'the items for the unit by selecting the records with Time from pagy.from to pagy.to'
+      end
+    end
+
+    # Additions for the Frontend module
+    module Frontend
+      # Change the text shown in the nav bar links to the actual unit of each page.
+      def pagy_labeler(pagy, num)
+        pagy.is_a?(Calendar) ? pagy.page_label(num) : num
+      end
+    end
+  end
+  Backend.prepend CalendarExtra::Backend
+  Frontend.prepend CalendarExtra::Frontend
+end

data/lib/pagy/extras/countless.rb

@@ -3,15 +3,16 @@
 
 require 'pagy/countless'
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:countless_minimal] = false
 
+  # Paginate without the need of any count, saving one query per rendering
   module CountlessExtra
     private
 
     # Return Pagy object and items
     def pagy_countless(collection, vars = {})
-      pagy = Pagy::Countless.new(pagy_countless_get_vars(collection, vars))
+      pagy = Countless.new(pagy_countless_get_vars(collection, vars))
       [pagy, pagy_countless_get_items(collection, pagy)]
     end
 

data/lib/pagy/extras/elasticsearch_rails.rb

@@ -1,9 +1,10 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/elasticsearch_rails
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:elasticsearch_rails_search_method] ||= :pagy_search
 
+  # Paginate ElasticsearchRails response objects
   module ElasticsearchRailsExtra
     module_function
 
@@ -17,7 +18,7 @@ class Pagy
       total.is_a?(Hash) ? total['value'] : total
     end
 
-    module ElasticsearchRails
+    module ElasticsearchRails # :nodoc:
       # Return an array used to delay the call of #search
       # after the pagination variables are merged to the options.
       # It also pushes to the same array an optional method call.

data/lib/pagy/extras/foundation.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module FoundationExtra
@@ -17,7 +17,7 @@ class Pagy
       pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<li>#{link.call item}</li>)                        # page link
-                when String  then %(<li class="current">#{item}</li>)                  # active page
+                when String  then %(<li class="current">#{pagy_labeler(pagy, item)}</li>)                  # active page
                 when :gap    then %(<li class="ellipsis gap" aria-hidden="true"></li>) # page gap
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end

data/lib/pagy/extras/gearbox.rb

@@ -1,14 +1,14 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/gearbox
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:gearbox_extra] = true # extra enabled by default
   DEFAULT[:gearbox_items] = [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
   module GearboxExtra
-    # Setup @items based on the :items variable
+    # Setup @items based on the :gearbox_items variable
     def setup_items_var
       return super if !@vars[:gearbox_extra] || @vars[:items_extra]
 
@@ -19,7 +19,7 @@ class Pagy
       @items = gearbox_items[@page - 1] || gearbox_items.last
     end
 
-    # Setup @pages and @last based on the :items variable
+    # Setup @pages and @last based on the :gearbox_items variable
     def setup_pages_var
       return super if !@vars[:gearbox_extra] || @vars[:items_extra]
 

data/lib/pagy/extras/headers.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/url_helpers'
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:headers] = { page:  'Current-Page',
                         items: 'Page-Items',
                         count: 'Total-Count',
@@ -38,11 +38,13 @@ class Pagy
                               end.compact.to_h
       hash                  = { 'Link' => link }
       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]
+      hash[headers[:page]]  = pagy.page.to_s if headers[:page]
+      if headers[:items] && !(defined?(Pagy::Calendar) && pagy.is_a?(Pagy::Calendar))  # 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[:count]] = pagy.count.to_s if headers[:count]
+        hash[headers[:count]] = pagy.count.to_s if pagy.count && headers[:count] # count may be nil with Calendar
       end
       hash
     end

data/lib/pagy/extras/i18n.rb

@@ -1,7 +1,7 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/i18n
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   # Use ::I18n gem
   module I18nExtra
     def pagy_t(key, **opts)

data/lib/pagy/extras/items.rb

@@ -3,12 +3,14 @@
 
 require 'pagy/extras/shared'
 
-class Pagy  # Default variables for this extra
+class Pagy # :nodoc:
   DEFAULT[:items_param] = :items
   DEFAULT[:max_items]   = 100
   DEFAULT[:items_extra] = true   # extra enabled by default
 
+  # Allow the client to request a custom number of items per page with an optional selector UI
   module ItemsExtra
+    # Additions for the Backend module
     module Backend
       private
 
@@ -22,6 +24,7 @@ class Pagy  # Default variables for this extra
       end
     end
 
+    # Additions for the Frontend module
     module Frontend
       ITEMS_PLACEHOLDER = '__pagy_items__'
 

data/lib/pagy/extras/materialize.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module MaterializeExtra

data/lib/pagy/extras/meilisearch.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:meilisearch_search_method] ||= :pagy_search
 
+  # Paginate Meilisearch results
   module MeilisearchExtra
-    module Meilisearch
+    module Meilisearch # :nodoc:
       # Return an array used to delay the call of #search
       # after the pagination variables are merged to the options
       def pagy_meilisearch(term = nil, **vars)

data/lib/pagy/extras/metadata.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/url_helpers'
 
-class Pagy
+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 ]
 
@@ -17,7 +17,8 @@ class Pagy
     def pagy_metadata(pagy, absolute: nil)
       scaffold_url = pagy_url_for(pagy, PAGE_PLACEHOLDER, absolute: absolute)
       {}.tap do |metadata|
-        pagy.vars[:metadata].each do |key|
+        keys = pagy.is_a?(Calendar) ? pagy.vars[:metadata] - %i[count items] : pagy.vars[:metadata]
+        keys.each do |key|
           metadata[key] = case key
                           when :scaffold_url then scaffold_url
                           when :first_url    then scaffold_url.sub(PAGE_PLACEHOLDER, 1.to_s)

data/lib/pagy/extras/navs.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module NavsExtra

data/lib/pagy/extras/overflow.rb

@@ -1,7 +1,7 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/overflow
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:overflow] = :empty_page
 
   # Handles OverflowError exceptions with different options
@@ -27,7 +27,8 @@ class Pagy
           initialize vars.merge!(page: @last)       # re-run with the last page
           @vars[:page] = initial_page               # restore the initial page
         when :empty_page
-          @offset = @items = @from = @to = 0        # vars relative to the actual page
+          @offset = @in = @from = @to = 0           # vars relative to the actual page
+          @utc_from = @utc_to = @final              # calendar variables out of local_minmax
           @prev = @last                             # prev relative to the actual page
           extend Series                             # special series for :empty_page
         else
@@ -59,7 +60,7 @@ class Pagy
         when :exception
           raise                                 # same as without the extra
         when :empty_page
-          @offset = @items = @from = @to = 0    # vars relative to the actual page
+          @offset = @in = @from = @to = 0    # vars relative to the actual page
           @vars[:size] = []                     # no page in the series
           self
         else
@@ -69,5 +70,6 @@ class Pagy
     end
   end
   prepend OverflowExtra::Pagy
+  Calendar.prepend OverflowExtra::Pagy if defined?(Calendar)
   Countless.prepend OverflowExtra::Countless if defined?(Countless)
 end

data/lib/pagy/extras/searchkick.rb

@@ -1,11 +1,12 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/searchkick
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:searchkick_search_method] ||= :pagy_search
 
+  # Paginate Searchkick::Results objects
   module SearchkickExtra
-    module Searchkick
+    module Searchkick # :nodoc:
       # Return an array used to delay the call of #search
       # after the pagination variables are merged to the options.
       # It also pushes to the same array an optional method call.

data/lib/pagy/extras/semantic.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module SemanticExtra
@@ -16,9 +16,9 @@ class Pagy
       html << pagy_semantic_prev_html(pagy, link)
       pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
-                when Integer then link.call item                                                 # page link
-                when String  then %(<a class="item active">#{item}</a>)                          # current page
-                when :gap    then %(<div class="disabled item">#{pagy_t 'pagy.nav.gap'}</div>)   # page gap
+                when Integer then link.call item
+                when String  then %(<a class="item active">#{pagy_labeler(pagy, item)}</a>)
+                when :gap    then %(<div class="disabled item">#{pagy_t 'pagy.nav.gap'}</div>)
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end

data/lib/pagy/extras/shared.rb

@@ -2,7 +2,7 @@
 
 require 'digest'
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:steps] = false # default false will use {0 => @vars[:size]}
 
   module SharedExtra

data/lib/pagy/extras/standalone.rb

@@ -2,7 +2,8 @@
 # frozen_string_literal: true
 
 require 'uri'
-class Pagy
+
+class Pagy # :nodoc:
   # Use pagy without any request object, nor Rack environment/gem, nor any defined params method,
   # even in the irb/rails console without any app or config.
   module StandaloneExtra

data/lib/pagy/extras/support.rb

@@ -1,7 +1,8 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/support
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
+  # Extra support for features like: incremental, auto-incremental and infinite pagination
   module SupportExtra
     # Return the previous page URL string or nil
     def pagy_prev_url(pagy)

data/lib/pagy/extras/trim.rb

@@ -1,9 +1,10 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/trim
 # frozen_string_literal: true
 
-class Pagy
+class Pagy # :nodoc:
   DEFAULT[:trim_extra] = true   # extra enabled by default
 
+  # Remove the page=1 param from the first page link
   module TrimExtra
     # Override the original pagy_link_proc.
     # Call the pagy_trim method if the trim_extra is enabled.

data/lib/pagy/extras/uikit.rb

@@ -3,7 +3,7 @@
 
 require 'pagy/extras/shared'
 
-class Pagy
+class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module UikitExtra
@@ -16,7 +16,7 @@ class Pagy
       pagy.series.each do |item|
         html << case item
                 when Integer then %(<li>#{link.call item}</li>)
-                when String  then %(<li class="uk-active"><span>#{item}</span></li>)
+                when String  then %(<li class="uk-active"><span>#{pagy_labeler(pagy, item)}</span></li>)
                 when :gap    then %(<li class="uk-disabled"><span>#{pagy_t 'pagy.nav.gap'}</span></li>)
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end

data/lib/pagy/frontend.rb

@@ -28,9 +28,9 @@ class Pagy
               end
       pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
-                when Integer then %(<span class="page">#{link.call item}</span> )               # page link
-                when String  then %(<span class="page active">#{item}</span> )                  # current page
-                when :gap    then %(<span class="page gap">#{pagy_t('pagy.nav.gap')}</span> )   # page gap
+                when Integer then %(<span class="page">#{link.call item}</span> )
+                when String  then %(<span class="page active">#{pagy_labeler(pagy, item)}</span> )
+                when :gap    then %(<span class="page gap">#{pagy_t('pagy.nav.gap')}</span> )
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
@@ -64,7 +64,7 @@ class Pagy
       p_next      = pagy.next
       left, right = %(<a href="#{pagy_url_for pagy, PAGE_PLACEHOLDER}" #{
                         pagy.vars[:link_extra]} #{link_extra}).split(PAGE_PLACEHOLDER, 2)
-      lambda do |num, text = num, extra_attrs = ''|
+      lambda do |num, text = pagy_labeler(pagy, num), extra_attrs = ''|
         %(#{left}#{num}#{right}#{ case num
                                   when p_prev then ' rel="prev"'
                                   when p_next then ' rel="next"'
@@ -73,6 +73,11 @@ class Pagy
       end
     end
 
+    # Allow customization of the output by overriding (used by the calendar extra)
+    def pagy_labeler(_pagy, num)
+      num
+    end
+
     # Similar to I18n.t: just ~18x faster using ~10x less memory
     # (@pagy_locale explicitly initialized in order to avoid warning)
     def pagy_t(key, **opts)

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.1.3'
+  VERSION = '5.2.0'
 
   # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root
@@ -46,7 +46,7 @@ class Pagy
   def series(size = @vars[:size])
     return [] if size.empty?
     raise VariableError.new(self, :size, 'to contain 4 items >= 0', size) \
-          unless size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier
+          unless size.is_a?(Array) && size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier
 
     # This algorithm is up to ~5x faster and ~2.3x lighter than the previous one (pagy < 4.3)
     left_gap_start  =     1 + size[0]   # rubocop:disable Layout/ExtraSpacing, Layout/SpaceAroundOperators

data/lib/templates/foundation_nav.html.erb

@@ -13,7 +13,7 @@
 <% end                         -%>
 <% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
 <%   if    item.is_a?(Integer) -%>    <li><%== link.call(item) %></li>
-<%   elsif item.is_a?(String)  -%>    <li class="current"><%= item %></li>
+<%   elsif item.is_a?(String)  -%>    <li class="current"><%= pagy_labeler(pagy, item) %></li>
 <%   elsif item == :gap        -%>    <li class="ellipsis gap" aria-hidden="true"></li>
 <%   end                       -%>
 <% end                         -%>

data/lib/templates/foundation_nav.html.haml

@@ -22,7 +22,7 @@
 
       - elsif item.is_a?(String)                      # current page
         %li.current
-          = item
+          = pagy_labeler(pagy, item)
 
       - elsif item == :gap                            # page gap
         %li.ellipsis.gap{"aria-hidden" => true}

data/lib/templates/foundation_nav.html.slim

@@ -22,7 +22,7 @@ nav.pagy-foundation-nav role="navigation" aria-label="Pagination"
 
       - elsif item.is_a?(String)                 # current page
         li.current
-          = item
+          = pagy_labeler(pagy, item)
 
       - elsif item == :gap                       # page gap
         li.ellipsis.gap aria-hidden="true"

data/lib/templates/uikit_nav.html.erb

@@ -5,7 +5,7 @@
 <% end                         -%>
 <% pagy.series.each do |item|  -%>
 <%   if    item.is_a?(Integer) -%>   <li><%== link.call(item) %></li>
-<%   elsif item.is_a?(String)  -%>   <li class="uk-active"><span><%== item %></span></li>
+<%   elsif item.is_a?(String)  -%>   <li class="uk-active"><span><%== pagy_labeler(pagy, item) %></span></li>
 <%   elsif item == :gap        -%>   <li class="uk-disabled"><span><%== pagy_t('pagy.nav.gap') %></span></li>
 <%   end                       -%>
 <% end                         -%>

data/lib/templates/uikit_nav.html.haml

@@ -14,7 +14,7 @@
 
     - elsif item.is_a?(String)
       %li.uk-active
-        %span!= item
+        %span!= pagy_labeler(pagy, item)
 
     - elsif item == :gap
       %li.uk-disabled

data/lib/templates/uikit_nav.html.slim

@@ -14,7 +14,7 @@ ul.uk-pagination.uk-flex-center
 
     - elsif item.is_a?(String)
       li.uk-active
-        span== item
+        span== pagy_labeler(pagy, item)
 
     - elsif item == :gap
       li.uk-disabled

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 5.1.3
+  version: 5.2.0
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-27 00:00:00.000000000 Z
+date: 2021-11-06 00:00:00.000000000 Z
 dependencies: []
 description: Agnostic pagination in plain ruby. It does it all. Better.
 email:
@@ -53,6 +53,7 @@ files:
 - lib/locales/zh-TW.yml
 - lib/pagy.rb
 - lib/pagy/backend.rb
+- lib/pagy/calendar.rb
 - lib/pagy/console.rb
 - lib/pagy/countless.rb
 - lib/pagy/exceptions.rb
@@ -60,6 +61,7 @@ files:
 - lib/pagy/extras/array.rb
 - lib/pagy/extras/bootstrap.rb
 - lib/pagy/extras/bulma.rb
+- lib/pagy/extras/calendar.rb
 - lib/pagy/extras/countless.rb
 - lib/pagy/extras/elasticsearch_rails.rb
 - lib/pagy/extras/foundation.rb