pagy 5.6.2 → 5.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a24ac286e97d1aacd7603d7ada3791006120004bf56c027320c4184b9488fc7
-  data.tar.gz: 63a018d758c2ffff334de22fc8fdd433cdffe74030ba46ca5c3cf5dc8a563a9c
+  metadata.gz: 39e1594de6e9b2ca3919cf666e3b7735c96656447d78c39ce0a4aaf85a737487
+  data.tar.gz: ec8e032be1fe73b5890c1fc42c05d81c397015b468120a8cd97dcdd2bf88fcfa
 SHA512:
-  metadata.gz: f5fd0f9dd9c8c8a151ea026e7e749ba6446fec53baf4bd9af276f8059f062d50d54b0d500e46762f5f4df8a3f89af475f4b07c7d8633f8194ee3da5d33d2b104
-  data.tar.gz: cd09f6222ce1d6db7c92984c9382d080d386ea862f66b3b7104721ea6cc6fc5e788714ce2aa623517c6ad9f17c6c95fd52fdcbcf2ba9a017c1485b262ce86405
+  metadata.gz: 3df6ce4c03f578555b88c34691be3c667c1aaf2d4712382ebb1ddf905ad5f2f545987ce61270aa0a57705f1cfbe592ffbc649afb5c1137e8f69552388750e198
+  data.tar.gz: c40c023541aaf714d0bfaa0fbaa4034edcb81d2d8b627a05f4e696d9eaa165f5f1aff7596497c9b4ccb9bf19773b65bb1aa79c7ba19765f3c993eab9e260e864

data/lib/config/pagy.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.6.2)
+# Pagy initializer file (5.6.6)
 # Customize only what you really need and notice that the core 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
 

data/lib/javascripts/pagy.js

@@ -2,10 +2,10 @@
 
 // This code should be OK also with very old browsers
 
-// Container of the whole pagy stuff
+// Container for the whole pagy stuff
 function Pagy(){}
 
-Pagy.version = '5.6.2'
+Pagy.version = '5.6.6'
 
 // Used by the waitForMe function
 Pagy.delay = 100
@@ -54,6 +54,7 @@ Pagy.nav =
             else if (typeof(item) === 'string') { html += fill(tags.active, item, label) }
           }
           html += tags.after
+          this.innerHTML = ''
           this.insertAdjacentHTML('afterbegin', html)
           lastWidth = width
         }

data/lib/pagy/backend.rb

@@ -8,7 +8,7 @@ class Pagy
   module Backend
     private
 
-    # Return Pagy object and items
+    # Return Pagy object and paginated items/results
     def pagy(collection, vars = {})
       pagy = Pagy.new(pagy_get_vars(collection, vars))
       [pagy, pagy_get_items(collection, pagy)]

data/lib/pagy/calendar/day.rb

@@ -22,7 +22,7 @@ class Pagy # :nodoc:
 
       # Starting time for the page
       def starting_time_for(page)
-        @initial + (snap(page) * DAY)
+        @initial + (offset_units_for(page) * DAY)
       end
     end
   end

data/lib/pagy/calendar/month_mixin.rb

@@ -13,8 +13,8 @@ class Pagy
       def setup_unit_vars
         super
         @months  = self.class::MONTHS  # number of months in the unit
-        @initial = new_time(@starting.year, starting_month_including(@starting.month))
-        @final   = add_months_to(new_time(@ending.year, starting_month_including(@ending.month)), @months)
+        @initial = unit_starting_time_for(@starting)
+        @final   = add_months_to(unit_starting_time_for(@ending), @months)
         @pages   = @last = (months_in(@final) - months_in(@initial)) / @months
         @from    = starting_time_for(@page)
         @to      = add_months_to(@from, @months)
@@ -22,16 +22,18 @@ class Pagy
 
       # Starting time for the page
       def starting_time_for(page)
-        add_months_to(@initial, snap(page) * @months)
-      end
-
-      # Starting month of the unit including the passed month
-      def starting_month_including(month)
-        (@months * ((month - 1) / @months)) + 1  # remove 1 month for 0-11 calculations and add it back for 1-12 conversion
+        add_months_to(@initial, offset_units_for(page) * @months)
       end
 
       private
 
+      # Unit starting time for time
+      def unit_starting_time_for(time)
+        # remove 1 month for 0-11 calculations and add it back for 1-12 conversion
+        starting_month = (@months * ((time.month - 1) / @months)) + 1
+        new_time(time.year, starting_month)
+      end
+
       # Number of months in time
       def months_in(time)
         (time.year * 12) + time.month

data/lib/pagy/calendar/week.rb

@@ -15,8 +15,8 @@ class Pagy # :nodoc:
       def setup_unit_vars
         setup_vars(offset: 0)
         super
-        @initial = week_start(@starting)
-        @final   = week_start(@ending) + WEEK
+        @initial = unit_starting_time_for(@starting)
+        @final   = unit_starting_time_for(@ending) + WEEK
         @pages   = @last = (@final - @initial).to_i / WEEK
         @from    = starting_time_for(@page)
         @to      = @from + WEEK
@@ -24,15 +24,15 @@ class Pagy # :nodoc:
 
       # Starting time for the page
       def starting_time_for(page)
-        @initial + (snap(page) * WEEK)
+        @initial + (offset_units_for(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)
+      # Unit starting time for time
+      def unit_starting_time_for(time)
+        starting_time = time - (((time.wday - @offset) * DAY) % WEEK)
+        new_time(starting_time.year, starting_time.month, starting_time.day)
       end
     end
   end

data/lib/pagy/calendar/year.rb

@@ -22,7 +22,7 @@ class Pagy # :nodoc:
 
       # Starting time for the page
       def starting_time_for(page)
-        new_time(@initial.year + snap(page))
+        new_time(@initial.year + offset_units_for(page))
       end
     end
   end

data/lib/pagy/calendar.rb

@@ -39,14 +39,9 @@ class Pagy # :nodoc:
       localize(starting_time_for(page.to_i), opts)  # page could be a string
     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
+    # Base class method for the setup of the unit variables (subclasses must implement it and call super)
     def setup_unit_vars
       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) \
@@ -63,8 +58,9 @@ class Pagy # :nodoc:
       time.strftime(opts[:format])
     end
 
-    # Simple trick to snap the page to its ordered start, without actually reordering anything in the internal structure
-    def snap(page)
+    # Number of units to offset from the @initial time, in order to get the ordered starting time for the page.
+    # Used in starting_time_for(page) with a logic equivalent to: @initial + (offset_units_for(page) * unit_time_length)
+    def offset_units_for(page)
       @order == :asc ? page - 1 : @pages - page
     end
 
@@ -73,6 +69,11 @@ class Pagy # :nodoc:
       Time.new(year, month, day, 0, 0, 0, @utc_offset)
     end
 
+    # Period of the active page (used internally for nested units)
+    def active_period
+      [[@starting, @from].max, [@to - 1, @ending].min] # -1 sec: include only last unit day
+    end
+
     class << self
       # Create a subclass instance by unit name (internal use)
       def create(unit, vars)
@@ -84,6 +85,6 @@ class Pagy # :nodoc:
       end
     end
   end
-
+  # Require the subclass files in UNITS (no custom unit at this point yet)
   Calendar::UNITS.each { |unit| require "pagy/calendar/#{unit}" }
 end

data/lib/pagy/extras/arel.rb

@@ -6,11 +6,13 @@ class Pagy # :nodoc:
   module ArelExtra
     private
 
+    # Return Pagy object and paginated collection/results
     def pagy_arel(collection, vars = {})
       pagy = Pagy.new(pagy_arel_get_vars(collection, vars))
       [pagy, pagy_get_items(collection, pagy)]
     end
 
+    # Sub-method called only by #pagy_arel: here for easy customization of variables by overriding
     def pagy_arel_get_vars(collection, vars)
       pagy_set_items_from_params(vars) if defined?(ItemsExtra)
       vars[:count] ||= pagy_arel_count(collection)
@@ -18,6 +20,7 @@ class Pagy # :nodoc:
       vars
     end
 
+    # Count using Arel when grouping
     def pagy_arel_count(collection)
       if collection.group_values.empty?
         # COUNT(*)

data/lib/pagy/extras/array.rb

@@ -6,7 +6,7 @@ class Pagy # :nodoc:
   module ArrayExtra
     private
 
-    # Return Pagy object and items
+    # Return Pagy object and paginated items
     def pagy_array(array, vars = {})
       pagy = Pagy.new(pagy_array_get_vars(array, vars))
       [pagy, array[pagy.offset, pagy.items]]

data/lib/pagy/extras/calendar.rb

@@ -4,7 +4,7 @@
 require 'pagy/calendar'
 
 class Pagy # :nodoc:
-  # Paginate based on calendar periods (year month week day) plus the regular pagination
+  # Add pagination filtering by calendar unit (:year, :quarter, :month, :week, :day) to the regular pagination
   module CalendarExtra
     # Additions for the Backend module
     module Backend
@@ -12,12 +12,7 @@ class Pagy # :nodoc:
 
       private
 
-      # 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
+      # Take a collection and a conf Hash with keys in CONF_KEYS and return an array with 3 items: [calendar, pagy, 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}"
@@ -25,50 +20,45 @@ class Pagy # :nodoc:
 
         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]
+        pagy, results        = send(conf[:pagy][:backend] || :pagy, collection, conf[:pagy])  # use backend: :pagy when omitted
+        [calendar, pagy, results]
       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
+        units = Calendar::UNITS & conf.keys # get the units in time length desc order
+        raise ArgumentError, 'no calendar unit found in pagy_calendar configuration' if units.empty?
+
         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}"
+          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)
+        last_obj = nil
         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_to_delete.each { |p| params.delete(p.to_s) } # Hash#except missing from ruby 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
+          conf[unit][:period] = last_obj&.send(:active_period) || pagy_calendar_period(collection)
+          calendar[unit]      = last_obj = Calendar.send(:create, unit, conf[unit])
         end
-        [calendar, pagy_calendar_filter(collection, calendar[units.last].from, calendar[units.last].to)]
+        [calendar, pagy_calendar_filter(collection, last_obj.from, last_obj.to)]
       end
 
-      # This method must be implemented by the application.
-      # It must return the the starting and ending local Time objects defining the calendar :period
+      # This method must be implemented by the application
       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'
+        raise NoMethodError, 'the pagy_calendar_period method must be implemented by the application ' \
+                             '(see https://ddnexus.github.io/pagy/extras/calendar#pagy_calendar_periodcollection)'
       end
 
-      # 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}
+      # This method must be implemented by the application
       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}'
+        raise NoMethodError, 'the pagy_calendar_filter method must be implemented by the application ' \
+                             '(see https://ddnexus.github.io/pagy/extras/calendar#pagy_calendar_filtercollection-from-to)'
       end
     end
   end

data/lib/pagy/extras/frontend_helpers.rb

@@ -18,7 +18,7 @@ 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: @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|

data/lib/pagy/extras/gearbox.rb

@@ -28,11 +28,11 @@ class Pagy # :nodoc:
       @pages = @last = (if @count > (sum = gearbox_items.sum)
                           [((@count - sum).to_f / gearbox_items.last).ceil, 1].max + gearbox_items.count
                         else
-                          pages    = 0
-                          reminder = @count
-                          while reminder.positive?
-                            pages    += 1
-                            reminder -= gearbox_items[pages - 1]
+                          pages     = 0
+                          remainder = @count
+                          while remainder.positive?
+                            pages     += 1
+                            remainder -= gearbox_items[pages - 1]
                           end
                           [pages, 1].max
                         end)

data/lib/pagy/extras/i18n.rb

@@ -4,14 +4,14 @@
 class Pagy # :nodoc:
   # Use ::I18n gem
   module I18nExtra
-    # Frontend overriding
+    # Frontend overriding for translation
     module Frontend
       def pagy_t(key, **opts)
         ::I18n.t(key, **opts)
       end
     end
 
-    # Calendar overriding
+    # Calendar overriding for localization (see also the block in the calendar section of the config/pagy.rb initializer)
     module Calendar
       def localize(time, opts)
         ::I18n.l(time, **opts)

data/lib/pagy/frontend.rb

@@ -77,7 +77,7 @@ class Pagy
     # 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 = {})
-      Pagy::I18n.t(@pagy_locale ||= nil, key, opts)
+      Pagy::I18n.translate(@pagy_locale ||= nil, key, opts)
     end
   end
 end

data/lib/pagy/i18n.rb

@@ -153,11 +153,12 @@ class Pagy
     end
 
     # Translate and pluralize the key with the locale DATA
-    def t(locale, key, opts = {})
+    def translate(locale, key, opts = {})
       data, pluralize = DATA[locale]
       translation = data[key] || (opts[:count] && data[key += ".#{pluralize.call(opts[:count])}"]) \
                       or return %([translation missing: "#{key}"])
       translation.gsub(/%{[^}]+?}/) { |match| opts[:"#{match[2..-2]}"] || match }
     end
+    alias t translate
   end
 end

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.6.2'
+  VERSION = '5.6.6'
 
   # 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
@@ -59,11 +59,11 @@ class Pagy
     series          = []
     start           = 1
     if (left_gap_end - left_gap_start).positive?
-      series.push(*start..(left_gap_start - 1), :gap)
+      series.push(*start...left_gap_start, :gap)
       start = left_gap_end + 1
     end
     if (right_gap_end - right_gap_start).positive?
-      series.push(*start..(right_gap_start - 1), :gap)
+      series.push(*start...right_gap_start, :gap)
       start = right_gap_end + 1
     end
     series.push(*start..@last)
@@ -76,6 +76,7 @@ class Pagy
     page.to_s
   end
 
+  # Allow the customization of the output (overridden by the calendar extra)
   def label
     @page.to_s
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 5.6.2
+  version: 5.6.6
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-29 00:00:00.000000000 Z
+date: 2021-12-09 00:00:00.000000000 Z
 dependencies: []
 description: Agnostic pagination in plain ruby. It does it all. Better.
 email:
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.32
 signing_key: 
 specification_version: 4
 summary: The kick-ass pagination ruby gem