pagy 5.1.1 → 5.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5300f9784ba9ab19522910b10e2f100a9823b5b52c91738966e946c91a08702a
-  data.tar.gz: 2dc3599be82ee24dba9e8074c1b84e5443d69550ddec6fd32967f66a316ecedd
+  metadata.gz: 7e5a33b40f2a12b18d7a3a4d86d367836a2e5bce8e675fea912292558f41d7bf
+  data.tar.gz: d79570153a77422382c17eed7bf00c446c5cc13aadb237c7df3207fb57db3766
 SHA512:
-  metadata.gz: 36b6893409fad1745593238f9a169623841dc4b55172fd2263f0bba09b3436e8c7f4e6f5ff6fc65bd56233b510daef44df60238189249547205f17087ddd69ab
-  data.tar.gz: bddaf3afe21358ed1b9ed73de5585931f4dac9018cc37b30c268aae29cdd7f836ac4f77e4ea419f9268dc4f9f247907996ab2461cd6fc6a44d9e80467b513567
+  metadata.gz: 6e7881aac396c5049ecbdf6430d87a748e95f184bbe71b38d2c0b0cbc705cc0309c7148788534ea337a0236fae8591226d2158c78e34f06c4e557e29577f357c
+  data.tar.gz: 166af959cf2fb5b05746a5d0a1431f29775c13059f86402003a1f1a0fd8cbd0b13af58ab7a110fd5604266507a860c24df1b538378a5a28ff4932b68b482dc2d

data/lib/config/pagy.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.1.1)
+# Pagy initializer file (5.2.1)
 # 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.1'
+Pagy.version = '5.2.1'
 
 // Used by the waitForMe function
 Pagy.delay = 100

data/lib/pagy/calendar.rb

@@ -0,0 +1,148 @@
+# 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, format = nil)
+      snap = snap(num.to_i)
+      format ||= @vars[:"#{@unit}_format"]
+      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(format)
+    end
+
+    def current_page_label(format = nil)
+      page_label(@page, 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,10 +1,10 @@
 # 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
+  # Handles OverflowError exceptions for different classes with different options
   module OverflowExtra
     # Support for Pagy class
     module Pagy
@@ -15,21 +15,25 @@ class Pagy
 
       # Add rescue clause for different behaviors
       def initialize(vars)
-        @overflow ||= false                         # don't override if :last_page re-run the method after an overflow
+        @overflow ||= false                            # still true if :last_page re-run the method after an overflow
         super
       rescue OverflowError
-        @overflow = true                            # add the overflow flag
+        @overflow = true                               # add the overflow flag
         case @vars[:overflow]
         when :exception
-          raise                                     # same as without the extra
+          raise                                        # same as without the extra
         when :last_page
-          initial_page = @vars[:page]               # save the very initial page (even after re-run)
-          initialize vars.merge!(page: @last)       # re-run with the last page
-          @vars[:page] = initial_page               # restore the initial page
+          requested_page = @vars[:page]                # save the requested page (even after re-run)
+          initialize vars.merge!(page: @last)          # re-run with the last page
+          @vars[:page] = requested_page                # restore the requested page
         when :empty_page
-          @offset = @items = @from = @to = 0        # vars relative to the actual page
-          @prev = @last                             # prev relative to the actual page
-          extend Series                             # special series for :empty_page
+          @offset = @in = @from = @to = 0              # vars relative to the actual page
+          if is_a?(Calendar)                           # only for Calendar instances
+            edge = @order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but it would work with any time)
+            @utc_from = @utc_to = edge.getutc          # set both to the edge utc time (a query with >= && < will get no record)
+          end
+          @prev = @last                                # prev relative to the actual page
+          extend Series                                # special series for :empty_page
         else
           raise VariableError.new(self, :overflow, 'to be in [:last_page, :empty_page, :exception]', @vars[:overflow])
         end
@@ -38,10 +42,10 @@ class Pagy
       # Special series for empty page
       module Series
         def series(size = @vars[:size])
-          @page = @last                             # series for last page
-          super(size).tap do |s|                    # call original series
-            s[s.index(@page.to_s)] = @page          # string to integer (i.e. no current page)
-            @page = @vars[:page]                    # restore the actual page
+          @page = @last                                # series for last page
+          super(size).tap do |s|                       # call original series
+            s[s.index(@page.to_s)] = @page             # string to integer (i.e. no current page)
+            @page = @vars[:page]                       # restore the actual page
           end
         end
       end
@@ -54,13 +58,13 @@ class Pagy
         @overflow = false
         super
       rescue OverflowError
-        @overflow = true                        # add the overflow flag
+        @overflow = true                               # add the overflow flag
         case @vars[:overflow]
         when :exception
-          raise                                 # same as without the extra
+          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 = @in = @from = @to = 0              # vars relative to the actual page
+          @vars[:size] = []                            # no page in the series
           self
         else
           raise VariableError.new(self, :overflow, 'to be in [:empty_page, :exception]', @vars[:overflow])
@@ -69,5 +73,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,10 @@
 # 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
     # Extracted from Rack::Utils and reformatted for rubocop
     module QueryUtils
@@ -34,15 +37,15 @@ class Pagy
     # it works exactly as the regular #pagy_url_for, relying on the params method and Rack.
     # If there is a defined pagy.vars[:url] variable it does not need the params method nor Rack.
     def pagy_url_for(pagy, page, absolute: nil)
-      p_vars = pagy.vars
-      return super unless (url = p_vars[:url])
+      vars = pagy.vars
+      return super unless (url = vars[:url])
 
-      params                            = p_vars[:params]
-      params[p_vars[:page_param].to_s]  = page
-      params[p_vars[:items_param].to_s] = p_vars[:items] if defined?(ItemsExtra)
+      params                     = vars[:params].clone  # safe when it gets reused
+      params[vars[:page_param]]  = page
+      params[vars[:items_param]] = vars[:items] if vars[:items_extra]
 
       query_string = "?#{QueryUtils.build_nested_query(pagy_massage_params(params))}"
-      "#{url}#{query_string}#{p_vars[:fragment]}"
+      "#{url}#{query_string}#{vars[:fragment]}"
     end
   end
   # In ruby 3+ `UrlHelpers.prepend StandaloneExtra` would be enough instead of using the next 2 lines

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/url_helpers.rb

@@ -7,13 +7,13 @@ class Pagy
     # It supports all Rack-based frameworks (Sinatra, Padrino, Rails, ...).
     # For non-rack environments you can use the standalone extra
     def pagy_url_for(pagy, page, absolute: nil)
-      p_vars                            = pagy.vars
-      params                            = request.GET.merge(p_vars[:params])
-      params[p_vars[:page_param].to_s]  = page
-      params[p_vars[:items_param].to_s] = p_vars[:items] if defined?(ItemsExtra)
+      vars                            = pagy.vars
+      params                          = request.GET.merge(vars[:params].transform_keys(&:to_s))
+      params[vars[:page_param].to_s]  = page
+      params[vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
 
       query_string = "?#{Rack::Utils.build_nested_query(pagy_massage_params(params))}"
-      "#{request.base_url if absolute}#{request.path}#{query_string}#{p_vars[:fragment]}"
+      "#{request.base_url if absolute}#{request.path}#{query_string}#{vars[:fragment]}"
     end
 
     # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.1.1'
+  VERSION = '5.2.1'
 
   # 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.1
+  version: 5.2.1
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-25 00:00:00.000000000 Z
+date: 2021-11-07 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