pagy 5.3.1 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3530b69891d7c069acdb707d6fa54e8b5d31763a80e57dae2e0fe3afafce8b2
-  data.tar.gz: defdc75e9f60ae351e8b071fffd3bf4767e28d51edd8ec6398a1b5958d688084
+  metadata.gz: 4a62cb4c6decfdc1013da6d14b38220aa361246637301a8d92b2d781440397bc
+  data.tar.gz: 2555195198def80d6ec002928da8cef07419a76da9a196d8971d50e7fb5095e2
 SHA512:
-  metadata.gz: 13dc93a7f0de2f1e4a688292e1901905df218d500fe1543e4d518dab1f1e7f7d2276cc63f197c251b1ed14e8fea4b46d8be4590ccbad89cfed11d70481a769a2
-  data.tar.gz: f6ddac95479d63445920df9bad22142f59b9b14e2a4c758303c76389eefd1a475ce49dd1e781e70519bed0a081c1b2296bb19be6ca6e50feefa0abb9660749a6
+  metadata.gz: f665f63cb281c25d6fcf430c12888def46ea46911e45a566fd52cb4943763efe775b094015d3b658b8322ade23a9a43a5888c60f10471bd567f000d5a67352c7
+  data.tar.gz: 8c22ab2ad5efc0bd91b648d89217d1b71d77fbf669e1153b015954b79c2506c8f5ffe29d80e7d5988bea76b4bed35e7a76bb9c3657f60de0db3cde84b38e62e2

data/lib/config/pagy.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.3.1)
+# Pagy initializer file (5.6.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
 
@@ -40,17 +40,30 @@
 # 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)
+# Calendar extra: Add pagination filtering by calendar time unit (Year, Month, Week 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
+# Default for each unit
+# Pagy::Calendar::Year::DEFAULT[:order]   = :asc        # Time direction of pagination
+# Pagy::Calendar::Year::DEFAULT[:format]  = '%Y'        # strftime format
+#
+# Pagy::Calendar::Month::DEFAULT[:order]  = :asc        # Time direction of pagination
+# Pagy::Calendar::Month::DEFAULT[:format] = '%Y-%m'     # strftime format
+#
+# Pagy::Calendar::Week::DEFAULT[:order]   = :asc        # Time direction of pagination
+# Pagy::Calendar::Week::DEFAULT[:format]  = '%Y-%W'     # strftime format
+# Pagy::Calendar::Week::DEFAULT[:offset]  = 0           # Day offset from Sunday (0: Sunday; 1: Monday;... 6: Saturday)
+#
+# Pagy::Calendar::Day::DEFAULT[:order]    = :asc        # Time direction of pagination
+# Pagy::Calendar::Day::DEFAULT[:format]   = '%Y-%m-%d'  # strftime format
+#
+# Uncomment the following block, if you need calendar localization without using the I18n extra
+# module LocalizePagyCalendar
+#   def localize(time, opts)
+#     ::I18n.l(time, **opts)
+#   end
+# end
+# Pagy::Calendar.prepend LocalizePagyCalendar
 
 # Countless extra: Paginate without any count, saving one query per rendering
 # See https://ddnexus.github.io/pagy/extras/countless
@@ -219,6 +232,5 @@
 # Pagy::DEFAULT[:i18n_key] = 'pagy.item_name'   # default
 
 
-# When you are done setting your own defaults freeze it,
-# so it will not changed accidentally
+# When you are done setting your own default freeze it, so it will not get changed accidentally
 Pagy::DEFAULT.freeze

data/lib/javascripts/pagy.js

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

data/lib/pagy/calendar/day.rb

@@ -0,0 +1,29 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Calendar day subclass
+    class Day < Calendar
+      DEFAULT = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                  format: '%Y-%m-%d' }
+
+      protected
+
+      # Setup the calendar variables
+      def setup_unit_vars
+        super
+        @initial = new_time(@starting.year, @starting.month, @starting.day)
+        @final   = new_time(@ending.year, @ending.month, @ending.day) + DAY
+        @pages   = @last = (@final - @initial).to_i / DAY
+        @from    = start_for(@page)
+        @to      = @from + DAY
+      end
+
+      # Time for the page
+      def start_for(page)
+        @initial + (snap(page) * DAY)
+      end
+    end
+  end
+end

data/lib/pagy/calendar/month.rb

@@ -0,0 +1,16 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+require_relative 'month_mixin'
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Calendar month subclass
+    class Month < Calendar
+      DEFAULT = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                  format: '%Y-%m' }
+      MONTHS  = 1  # number of months in the unit
+      include MonthMixin
+    end
+  end
+end

data/lib/pagy/calendar/month_mixin.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Calendar
+    # Mixin for month based unit periods
+    # It is used for month and quarter, but you could use it to implement less common unit of 6, 4, 2 months
+    # (see the https://ddnexus.github.io/pagy/api/calendar#custom-units sections for details).
+    # The class that includes it needs to set the MONTH duration for the unit and the usual DEFAULT.
+    module MonthMixin
+      protected
+
+      # Setup the calendar variables
+      def setup_unit_vars
+        super
+        @months  = self.class::MONTHS  # number of months in the unit
+        @initial = new_time(@starting.year, beginning_month(@starting.month))
+        @final   = add_to(new_time(@ending.year, beginning_month(@ending.month)), @months)
+        @pages   = @last = (months_in(@final) - months_in(@initial)) / @months
+        @from    = start_for(@page)
+        @to      = add_to(@from, @months)
+      end
+
+      # Time for the page
+      def start_for(page)
+        add_to(@initial, snap(page) * @months)
+      end
+
+      # Return the beginning month for the unit (e.g. quarter) that includes the month argument
+      def beginning_month(month)
+        (@months * ((month - 1) / @months)) + 1
+      end
+
+      private
+
+      # Months in time
+      def months_in(time)
+        (time.year * 12) + time.month
+      end
+
+      # Add months to time
+      def add_to(time, months)
+        months += months_in(time)
+        year  = months / 12
+        month = months % 12
+        month.zero? ? new_time(year - 1, 12) : new_time(year, month)
+      end
+    end
+  end
+end

data/lib/pagy/calendar/quarter.rb

@@ -0,0 +1,16 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+require_relative 'month_mixin'
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Calendar quarter subclass
+    class Quarter < Calendar
+      DEFAULT = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                  format: '%Y-Q%q' }
+      MONTHS  = 3  # number of months of the unit
+      include MonthMixin
+    end
+  end
+end

data/lib/pagy/calendar/week.rb

@@ -0,0 +1,39 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Calendar week subclass
+    class Week < Calendar
+      DEFAULT = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                  format: '%Y-%W',
+                  offset: 0 }
+
+      protected
+
+      # Setup the calendar variables
+      def setup_unit_vars
+        setup_vars(offset: 0)
+        super
+        @initial = week_start(@starting)
+        @final   = week_start(@ending) + WEEK
+        @pages   = @last = (@final - @initial).to_i / WEEK
+        @from    = start_for(@page)
+        @to      = @from + WEEK
+      end
+
+      # Time for the page
+      def start_for(page)
+        @initial + (snap(page) * WEEK)
+      end
+
+      private
+
+      # Return the start of the week for time
+      def week_start(time)
+        start = time - (((time.wday - @offset) * DAY) % WEEK)
+        new_time(start.year, start.month, start.day)
+      end
+    end
+  end
+end

data/lib/pagy/calendar/year.rb

@@ -0,0 +1,29 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Calendar year subclass
+    class Year < Calendar
+      DEFAULT = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                  format: '%Y' }
+
+      protected
+
+      # Setup the calendar variables
+      def setup_unit_vars
+        super
+        @initial = new_time(@starting.year)
+        @final   = new_time(@ending.year + 1)
+        @pages   = @last = @final.year - @initial.year
+        @from    = start_for(@page)
+        @to      = new_time(@from.year + 1)
+      end
+
+      # Time for the page
+      def start_for(page)
+        new_time(@initial.year + snap(page))
+      end
+    end
+  end
+end

data/lib/pagy/calendar.rb

@@ -2,27 +2,24 @@
 # 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)
+  # Base class for time units subclasses (Year, Quarter, Month, Week, Day)
   class Calendar < Pagy
-    attr_reader :utc_from, :utc_to, :unit, :week_offset, :order
-    attr_writer :count, :in
+    # List of units in desc order of duration. It can be used for custom units.
+    UNITS = %i[year quarter month week day]  # rubocop:disable Style/MutableConstant
+    DAY   = 60 * 60 * 24  # One day in seconds
+    WEEK  = DAY * 7       # One week in seconds
+
+    attr_reader :order
 
     # 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)
+      raise InternalError, 'Pagy::Calendar is a base class; use one of its subclasses' if instance_of?(Pagy::Calendar)
+
+      vars = self.class::DEFAULT.merge(vars)  # subclass specific default
+      normalize_vars(vars)                    # general default
+      setup_vars(page: 1)
       setup_unit_vars
       setup_params_var
       raise OverflowError.new(self, :page, "in 1..#{@last}", @page) if @page > @last
@@ -31,104 +28,45 @@ class Pagy # :nodoc:
       @next = @page == @last ? (1 if @vars[:cycle]) : @page + 1
     end
 
-    # Generate a label for each page, with the specific `Time` period it refers to
-    # (it can pass along the I18n gem opts when it's used with the i18n extra)
-    def label_for(page, **opts)
-      snap = snap(page.to_i)
-      time = 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
-      opts[:format] ||= @vars[:"#{@unit}_format"]
-      localize(time, **opts)
-    end
-
-    # The label for the current page
-    # (it can pass along the I18n gem opts when it's used with the i18n extra)
+    # The label for the current page (it can pass along the I18n gem opts when it's used with the i18n extra)
     def label(**opts)
       label_for(@page, **opts)
     end
 
-    DAY  = 60 * 60 * 24
-    WEEK = DAY * 7
+    # The label for any page (it can pass along the I18n gem opts when it's used with the i18n extra)
+    def label_for(page, **opts)
+      opts[:format] ||= @vars[:format]
+      start = start_for(page.to_i)
+      opts[:format] = opts[:format].gsub('%q') { (start.month / 4) + 1 }
+      localize(start, **opts)
+    end
+
+    # Period of the active page (used for nested units)
+    def active_period
+      [[@starting, @from].max, [@to - 1, @ending].min] # -1 sec: include only last unit day
+    end
 
     protected
 
+    # Base class method for the setup of the unit variables
     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, :format, 'to be a strftime format', @vars[:format]) unless @vars[:format].is_a?(String)
       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? && !max.utc? && min <= max \
-                   && (@utc_offset = min.utc_offset) == max.utc_offset
-
-      send :"setup_#{@unit}_vars", min, max
+      @starting, @ending = @vars[:period]
+      raise VariableError.new(self, :period, 'to be a an Array of min and max local Time instances', @vars[:period]) \
+            unless @starting.is_a?(Time) && @ending.is_a?(Time) && !@starting.utc? && !@ending.utc? && @starting <= @ending \
+                   && (@utc_offset = @starting.utc_offset) == @ending.utc_offset
     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
-
-    # Apply the strftime format to the time
-    # (overridden by the i18n extra when localization is required)
-    def localize(time, **opts)
+    # Apply the strftime format to the time (overridden by the i18n extra when localization is required)
+    def localize(time, opts)
       time.strftime(opts[:format])
     end
 
-    private
-
-    # Simple trick to snap the page into its ordered position,
-    # without actually reordering anything in the internal structure
-    def snap(page = @page)
+    # Simple trick to snap the page to its ordered start, without actually reordering anything in the internal structure
+    def snap(page)
       @order == :asc ? page - 1 : @pages - page
     end
 
@@ -137,23 +75,17 @@ class Pagy # :nodoc:
       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
+    class << self
+      # Create a subclass instance by unit name (internal use)
+      def create(unit, vars)
+        raise InternalError, "unit must be in #{UNITS.inspect}; got #{unit}" unless UNITS.include?(unit)
 
-    # 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)
+        name    = unit.to_s
+        name[0] = name[0].capitalize
+        Object.const_get("Pagy::Calendar::#{name}").new(vars)
+      end
     end
   end
+
+  Calendar::UNITS.each { |unit| require "pagy/calendar/#{unit}" }
 end

data/lib/pagy/countless.rb

@@ -30,7 +30,7 @@ class Pagy
 
     # Override the original series.
     # Return nil if :countless_minimal is enabled
-    def series(_size = @vars[:size])
+    def series(*)
       super unless @vars[:countless_minimal]
     end
   end

data/lib/pagy/extras/bootstrap.rb

@@ -8,13 +8,13 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module BootstrapExtra
     # Pagination for bootstrap: it returns the html with the series of links to the pages
-    def pagy_bootstrap_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_bootstrap_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="page-link" #{link_extra}))
 
       html = +%(<nav#{p_id} class="pagy-bootstrap-nav" aria-label="pager"><ul class="pagination">)
       html << pagy_bootstrap_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer
                   %(<li class="page-item">#{link.call item}</li>)
@@ -30,7 +30,7 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for bootstrap: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_bootstrap_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_bootstrap_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="page-link" #{link_extra}))
       tags = { 'before' => %(<ul class="pagination">#{pagy_bootstrap_prev_html pagy, link}),
@@ -40,7 +40,7 @@ class Pagy # :nodoc:
                'after'  => %(#{pagy_bootstrap_next_html pagy, link}</ul>) }
 
       %(<nav#{p_id} class="pagy-njs pagy-bootstrap-nav-js" aria-label="pager" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination for bootstrap: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/bulma.rb

@@ -8,14 +8,14 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module BulmaExtra
     # Pagination for Bulma: it returns the html with the series of links to the pages
-    def pagy_bulma_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_bulma_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<nav#{p_id} class="pagy-bulma-nav pagination is-centered" aria-label="pagination">)
       html << pagy_bulma_prev_next_html(pagy, link)
       html << %(<ul class="pagination-list">)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer
                   %(<li>#{link.call item, pagy.label_for(item), %(class="pagination-link" aria-label="goto page #{item}")}</li>)
@@ -30,7 +30,7 @@ class Pagy # :nodoc:
       html << %(</ul></nav>)
     end
 
-    def pagy_bulma_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_bulma_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => %(#{pagy_bulma_prev_next_html(pagy, link)}<ul class="pagination-list">),
@@ -43,7 +43,7 @@ class Pagy # :nodoc:
                'after'  => '</ul>' }
 
       %(<nav#{p_id} class="pagy-njs pagy-bulma-nav-js pagination is-centered" aria-label="pagination" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination for Bulma: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/calendar.rb

@@ -4,32 +4,71 @@
 require 'pagy/calendar'
 
 class Pagy # :nodoc:
-  # Paginate based on calendar periods (year month week day)
+  # Paginate based on calendar periods (year month week day) plus the regular pagination
   module CalendarExtra
     # Additions for the Backend module
     module Backend
+      CONF_KEYS = (Calendar::UNITS + %i[pagy active]).freeze
+
       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)]
+      # Take a collection and a conf Hash with keys in [:year, :quarter, :month: week, :day, :pagy: :active];
+      # The calendar is active by default, but it can be explicitly inactivated with `active: false`
+      # Return a hash with 3 items:
+      # 0. Array of pagy calendar unit objects
+      # 1. Pagy object
+      # 2. Array of results
+      def pagy_calendar(collection, conf)
+        unless conf.is_a?(Hash) && (conf.keys - CONF_KEYS).empty? && conf.all? { |k, v| v.is_a?(Hash) || k == :active }
+          raise ArgumentError, "keys must be in #{CONF_KEYS.inspect} and object values must be Hashes; got #{conf.inspect}"
+        end
+
+        conf[:pagy]          = {} unless conf[:pagy]  # use default Pagy object when omitted
+        calendar, collection = pagy_setup_calendar(collection, conf) unless conf.key?(:active) && !conf[:active]
+        pagy, result         = send(conf[:pagy][:backend] || :pagy, collection, conf[:pagy])  # use backend: :pagy when omitted
+        [calendar, pagy, result]
+      end
+
+      # Setup and return the calendar objects and the filtered collection
+      def pagy_setup_calendar(collection, conf)
+        units      = Calendar::UNITS & conf.keys # get the units in time length desc order
+        page_param = conf[:pagy][:page_param] || DEFAULT[:page_param]
+        units.each do |unit|  # set all the :page_param vars for later deletion
+          unit_page_param = :"#{unit}_#{page_param}"
+          conf[unit][:page_param] = unit_page_param
+          conf[unit][:page]       = params[unit_page_param]
+        end
+        calendar = {}
+        period   = pagy_calendar_period(collection)
+        units.each_with_index do |unit, index|
+          params_to_delete    = units[(index + 1), units.size].map { |sub| conf[sub][:page_param] } + [page_param]
+          conf[unit][:params] = lambda do |params|  # delete page_param from the sub-units
+                                  params_to_delete.each { |p| params.delete(p.to_s) } # Hash#except missing from 2.5 baseline
+                                  params
+                                end
+          conf[unit][:period] = period
+          calendar[unit]      = Calendar.send(:create, unit, conf[unit])
+          period              = calendar[unit].active_period # set the period for the next unit
+        end
+        [calendar, pagy_calendar_filter(collection, calendar[units.last].from, calendar[units.last].to)]
       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
+      # This method must be implemented by the application.
+      # It must return the the starting and ending local Time objects defining the calendar :period
+      def pagy_calendar_period(*)
+        # return_period_array_using(collection)
+        raise NoMethodError, 'the pagy_calendar_period method must be implemented by the application and must return ' \
+                             'the starting and ending local Time objects array defining the calendar :period'
       end
 
-      # This method should be implemented in the application and should return the records
-      # for the unit by selecting the records with Time from pagy.utc_from to pagy.utc_to
-      def pagy_calendar_get_items(_collection, _pagy)
-        # collection.your_own_method_to_get_the_items_with(pagy.utc_from, pagy.utc_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.utc_from to pagy.utc_to'
+      # This method must be implemented by the application.
+      # It receives the main collection and must return a filtered version of it.
+      # The filter logic must be equivalent to {storage_time >= from && storage_time < to}
+      def pagy_calendar_filter(*)
+        # return_filtered_collection_using(collection, from, to)
+        raise NoMethodError, 'the pagy_calendar_filter method must be implemented by the application and must return the ' \
+                             'collection filtered by a logic equivalent to '\
+                             '{storage_time >= from && storage_time < to}'
       end
     end
   end

data/lib/pagy/extras/foundation.rb

@@ -8,13 +8,13 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module FoundationExtra
     # Pagination for Foundation: it returns the html with the series of links to the pages
-    def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<nav#{p_id} class="pagy-foundation-nav" aria-label="Pagination"><ul class="pagination">)
       html << pagy_foundation_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).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">#{pagy.label_for(item)}</li>)                  # active page
@@ -27,7 +27,7 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for foundation: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_foundation_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_foundation_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => %(<ul class="pagination">#{pagy_foundation_prev_html pagy, link}),
@@ -37,7 +37,7 @@ class Pagy # :nodoc:
                'after'  => %(#{pagy_foundation_next_html pagy, link}</ul>) }
 
       %(<nav#{p_id} class="pagy-njs pagy-foundation-nav-js" aria-label="Pagination" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination for Foundation: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/frontend_helpers.rb

@@ -18,12 +18,11 @@ class Pagy # :nodoc:
       #       "350" => [1, 2, :gap, 17, 18, 19, "20", 21, 22, 23, :gap, 49, 50],
       #       "550" => [1, 2, 3, :gap, 16, 17, 18, 19, "20", 21, 22, 23, 24, :gap, 48, 49, 50] }
       # Notice: if :steps is false it will use the single {0 => @vars[:size]} size
-      def sequels(steps = nil)
-        steps ||= @vars[:steps] || { 0 => @vars[:size] }
+      def sequels(steps: @vars[:steps] || { 0 => @vars[:size] })
         raise VariableError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
 
         {}.tap do |sequels|
-          steps.each { |width, size| sequels[width.to_s] = series(size) }
+          steps.each { |width, step_size| sequels[width.to_s] = series(size: step_size) }
         end
       end
 

data/lib/pagy/extras/i18n.rb

@@ -13,7 +13,7 @@ class Pagy # :nodoc:
 
     # Calendar overriding
     module Calendar
-      def localize(time, **opts)
+      def localize(time, opts)
         ::I18n.l(time, **opts)
       end
     end

data/lib/pagy/extras/materialize.rb

@@ -8,13 +8,13 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module MaterializeExtra
     # Pagination for materialize: it returns the html with the series of links to the pages
-    def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<div#{p_id} class="pagy-materialize-nav pagination" role="navigation" aria-label="pager"><ul class="pagination">)
       html << pagy_materialize_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<li class="waves-effect">#{link.call item}</li>)                           # page link
                 when String  then %(<li class="active">#{link.call item}</li>)                                 # active page
@@ -27,7 +27,7 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for materialize: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_materialize_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_materialize_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
@@ -38,7 +38,7 @@ class Pagy # :nodoc:
                'after'  => %(#{pagy_materialize_next_html pagy, link}</ul>) }
 
       %(<div#{p_id} class="pagy-njs pagy-materialize-nav-js" role="navigation" aria-label="pager" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></div>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></div>)
     end
 
     # Javascript combo pagination for materialize: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/navs.rb

@@ -8,7 +8,7 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module NavsExtra
     # Javascript pagination: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => pagy_nav_prev_html(pagy, link),
@@ -18,7 +18,7 @@ class Pagy # :nodoc:
                'after'  => pagy_nav_next_html(pagy, link) }
 
       %(<nav#{p_id} class="pagy-njs pagy-nav-js pagination" aria-label="pager" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/overflow.rb

@@ -29,8 +29,8 @@ class Pagy # :nodoc:
         when :empty_page
           @offset = @items = @from = @to = 0           # vars relative to the actual page
           if defined?(Calendar) && 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)
+            edge = @order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but any time would do)
+            @from = @to = edge                         # set both to the edge utc time (a >=&&< query will get no records)
           end
           @prev = @last                                # prev relative to the actual page
           extend Series                                # special series for :empty_page
@@ -41,9 +41,9 @@ class Pagy # :nodoc:
 
       # Special series for empty page
       module Series
-        def series(size = @vars[:size])
+        def series(*)
           @page = @last                                # series for last page
-          super(size).tap do |s|                       # call original series
+          super.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
@@ -63,7 +63,7 @@ class Pagy # :nodoc:
         when :exception
           raise                                        # same as without the extra
         when :empty_page
-          @offset = @items = @from = @to = 0            # vars relative to the actual page
+          @offset = @items = @from = @to = 0           # vars relative to the actual page
           @vars[:size] = []                            # no page in the series
           self
         else

data/lib/pagy/extras/semantic.rb

@@ -8,13 +8,13 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module SemanticExtra
     # Pagination for semantic: it returns the html with the series of links to the pages
-    def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="item" #{link_extra}))
 
       html = +%(<div#{p_id} class="pagy-semantic-nav ui pagination menu">)
       html << pagy_semantic_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then link.call item
                 when String  then %(<a class="item active">#{pagy.label_for(item)}</a>)
@@ -27,7 +27,7 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for semantic: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_semantic_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_semantic_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="item" #{link_extra}))
       tags = { 'before' => pagy_semantic_prev_html(pagy, link),
@@ -37,7 +37,7 @@ class Pagy # :nodoc:
                'after'  => pagy_semantic_next_html(pagy, link) }
 
       %(<div#{p_id} class="pagy-njs pagy-semantic-nav-js ui pagination menu" role="navigation" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></div>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></div>)
     end
 
     # Combo pagination for semantic: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/uikit.rb

@@ -8,12 +8,12 @@ class Pagy # :nodoc:
   # The resulting code may not look very elegant, but produces the best benchmarks
   module UikitExtra
     # Pagination for uikit: it returns the html with the series of links to the pages
-    def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<ul#{p_id} class="pagy-uikit-nav uk-pagination uk-flex-center">#{pagy_uikit_prev_html pagy, link})
-      pagy.series.each do |item|
+      pagy.series(**vars).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>)
                 when String  then %(<li class="uk-active"><span>#{pagy.label_for(item)}</span></li>)
@@ -26,7 +26,7 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for uikit: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_uikit_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_uikit_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => pagy_uikit_prev_html(pagy, link),
@@ -36,7 +36,7 @@ class Pagy # :nodoc:
                'after'  => pagy_uikit_next_html(pagy, link) }
 
       %(<ul#{p_id} class="pagy-njs pagy-uikit-nav-js uk-pagination uk-flex-center" #{
-        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(steps)), pagy.label_sequels(sequels))}></ul>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></ul>)
     end
 
     # Javascript combo pagination for uikit: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/frontend.rb

@@ -15,7 +15,7 @@ class Pagy
     include UrlHelpers
 
     # Generic pagination: it returns the html with the series of links to the pages
-    def pagy_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id   = %( id="#{pagy_id}") if pagy_id
       link   = pagy_link_proc(pagy, link_extra: link_extra)
       p_prev = pagy.prev
@@ -27,7 +27,7 @@ class Pagy
               else
                 %(<span class="page prev disabled">#{pagy_t('pagy.nav.prev')}</span> )
               end
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).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> )
                 when String  then %(<span class="page active">#{pagy.label_for(item)}</span> )

data/lib/pagy/url_helpers.rb

@@ -23,7 +23,7 @@ class Pagy
     private
 
     # Transitional code to handle params deprecations. It will be removed in version 6.0
-    def pagy_deprecated_params(pagy, params)   # remove in 6.0
+    def pagy_deprecated_params(pagy, params)    # remove in 6.0
       if pagy.params.is_a?(Proc)                # new code
         pagy.params.call(params)
       elsif respond_to?(:pagy_massage_params)   # deprecated code

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.3.1'
+  VERSION = '5.6.0'
 
   # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root
@@ -44,7 +44,7 @@ class Pagy
   end
 
   # Return the array of page numbers and :gap items e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-  def series(size = @vars[:size])
+  def series(size: @vars[:size])
     return [] if size.empty?
     raise VariableError.new(self, :size, 'to contain 4 items >= 0', size) \
           unless size.is_a?(Array) && size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier

data/lib/templates/bootstrap_nav.html.erb

@@ -5,7 +5,7 @@
   The link variable is set to a proc that returns the link tag.
   Usage: link.call( page_number [, text [, extra_attributes_string ]])
 -%>
-<% link = pagy_link_proc(pagy, 'class="page-link"') -%>
+<% link = pagy_link_proc(pagy, link_extra: 'class="page-link"') -%>
 <%#                            -%><nav aria-label="pager"  class="pagy-bootstrap-nav" role="navigation">
 <%#                            -%>  <ul class="pagination">
 <% if pagy.prev                -%>    <li class="page-item prev"><%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"') %></li>

data/lib/templates/bootstrap_nav.html.haml

@@ -4,7 +4,7 @@
 -# The link variable is set to a proc that returns the link tag.
 -# Usage: link.call( page_number [, text [, extra_attributes_string ]])
 
-- link = pagy_link_proc(pagy, 'class="page-link"')
+- link = pagy_link_proc(pagy, link_extra: 'class="page-link"')
 
 %nav.pagy-bootstrap-nav{"aria-label" => "pager", :role => "navigation"}
 

data/lib/templates/bootstrap_nav.html.slim

@@ -4,7 +4,7 @@
 / The link variable is set to a proc that returns the link tag.
 / Usage: link.call( page_number [, text [, extra_attributes_string ]])
 
-- link = pagy_link_proc(pagy, 'class="page-link"')
+- link = pagy_link_proc(pagy, link_extra: 'class="page-link"')
 
 nav.pagy-bootstrap-nav role="navigation" aria-label="pager"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 5.3.1
+  version: 5.6.0
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-12 00:00:00.000000000 Z
+date: 2021-11-26 00:00:00.000000000 Z
 dependencies: []
 description: Agnostic pagination in plain ruby. It does it all. Better.
 email:
@@ -54,6 +54,12 @@ files:
 - lib/pagy.rb
 - lib/pagy/backend.rb
 - lib/pagy/calendar.rb
+- lib/pagy/calendar/day.rb
+- lib/pagy/calendar/month.rb
+- lib/pagy/calendar/month_mixin.rb
+- lib/pagy/calendar/quarter.rb
+- lib/pagy/calendar/week.rb
+- lib/pagy/calendar/year.rb
 - lib/pagy/console.rb
 - lib/pagy/countless.rb
 - lib/pagy/exceptions.rb
@@ -102,7 +108,8 @@ files:
 homepage: https://github.com/ddnexus/pagy
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths: