pagy 43.4.3 → 43.5.0

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

@@ -3,7 +3,6 @@
 class Pagy
   protected
 
-  # Label for any page. Allow the customization of the output
   def page_label(page, **options)
     return page.to_s unless calendar?
 
@@ -11,8 +10,8 @@ class Pagy
     localize(starting_time_for(page.to_i), **options)  # page could be a string
   end
 
-  # Return a performance optimized lambda to generate the anchor tag
-  # Benchmarked on a 20 link nav: it is ~22x faster and uses ~18x less memory than rails' link_to
+  # Return a performance optimized lambda to generate the anchor tag.
+  # Benchmarked on a 20 link nav: it is ~22x faster and uses ~18x less memory than rails' link_to.
   def a_lambda(anchor_string: @options[:anchor_string], **)
     left, right = %(<a href="#{compose_page_url(PAGE_TOKEN, **)}"#{
                     %( #{anchor_string}) if anchor_string}).split(PAGE_TOKEN, 2)

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

@@ -3,7 +3,6 @@
 require 'json'
 require_relative '../../../modules/b64'
 
-# Relegate internal functions. Make overriding navs easier.
 class Pagy
   private
 

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

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
-# Relegate internal functions. Make overriding navs easier.
 class Pagy
   private
 
-  # Compose the aria label attribute for the nav
   def nav_aria_label_attribute(aria_label: nil)
     aria_label ||= I18n.translate('pagy.aria_label.nav', count: @last)
     %(aria-label="#{aria_label}")

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

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

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

@@ -4,11 +4,10 @@ require_relative 'nav_aria_label_attribute'
 require_relative 'data_pagy_attribute'
 require_relative 'a_lambda' # inherited use
 
-# Relegate internal functions. Make overriding navs easier.
 class Pagy
   private
 
-  # Build the input_nav_js tag, with the specific inner html for the style
+  # Common input_nav_js logic
   def wrap_input_nav_js(html, nav_classes, id: nil, aria_label: nil, **)
     %(<nav#{%( id="#{id}") if id} class="#{nav_classes}" #{
       nav_aria_label_attribute(aria_label:)} #{

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

@@ -5,11 +5,10 @@ require_relative 'nav_aria_label_attribute'
 require_relative 'data_pagy_attribute'
 require_relative 'a_lambda' # inherited use
 
-# Relegate internal functions. Make overriding navs easier.
 class Pagy
   private
 
-  # Build the nav tag, with the specific inner html for the style
+  # Common series_nav logic
   def wrap_series_nav(html, nav_classes, id: nil, aria_label: nil, **)
     data = %( #{data_pagy_attribute(:k, @update)}) if keynav?
 

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

@@ -9,7 +9,7 @@ require_relative 'a_lambda' # inherited use
 class Pagy
   private
 
-  # Return the reverse sorted array of widths, series, and labels generated from the :steps hash
+  # The reverse-sorted array of widths, series, and labels generated from the :steps hash.
   # If :steps is false it will use the single {0 => @options[:slots]} length
   def sequels(steps: @options[:steps] || { 0 => @options[:slots] || SERIES_SLOTS }, **)
     raise OptionError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
@@ -18,7 +18,7 @@ class Pagy
     [widths, series, page_labels(series)]
   end
 
-  # Support for the Calendar API
+  # Support the Calendar API
   def page_labels(series)
     return unless calendar?
 
@@ -27,7 +27,7 @@ class Pagy
     end
   end
 
-  # Build the nav_js tag, with the specific tokens for the style
+  # Common series_nav_js logic
   def wrap_series_nav_js(tokens, nav_classes, id: nil, aria_label: nil, **)
     sequels     = sequels(**)
     nav_classes = "pagy-rjs #{nav_classes}" if sequels[0].size > 1

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Generate the hash of the pagination links
   def urls_hash(**)
     template = compose_page_url(PAGE_TOKEN, **)
 

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

@@ -4,7 +4,7 @@ class Pagy
   module CalendarPaginator
     module_function
 
-    # Take a collection and a configuration Hash and return an array with 3 items: [calendar, pagy, results]
+    # Take a collection and a config Hash and return [calendar, pagy, results]
     def paginate(context, collection, config)
       context.instance_eval do
         allowed_options = Calendar::UNITS + %i[offset disabled request]

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

@@ -6,7 +6,6 @@ class Pagy
   module CountishPaginator
     module_function
 
-    # Return the Offset::Countish instance and records
     def paginate(collection, options)
       options[:page] ||= options[:request].resolve_page(force_integer: false)
 

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

@@ -4,7 +4,6 @@ class Pagy
   module CountlessPaginator
     module_function
 
-    # Return the Offset::Countless instance and records
     def paginate(collection, options)
       options[:page] ||= options[:request].resolve_page(force_integer: false) # accept nil and strings
 

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

@@ -6,7 +6,6 @@ class Pagy
   module ElasticsearchRailsPaginator
     module_function
 
-    # Paginate from the search object
     def paginate(search, options)
       if search.is_a?(Search::Arguments)  # Active mode
 
@@ -33,7 +32,7 @@ class Pagy
       end
     end
 
-    # Get from and size params from the response object, supporting different versions of ElasticsearchRails
+    # Support different versions of ElasticsearchRails
     def pagination_params_from(response_object)
       definition = response_object.search.definition
       definition = definition.to_hash if definition.respond_to?(:to_hash)
@@ -45,7 +44,7 @@ class Pagy
       [from, size]
     end
 
-    # Get the count from the response object, supporting different versions of ElasticsearchRails
+    # Support different versions of ElasticsearchRails
     def total_count_from(response_object)
       total = response_object.instance_eval do
                 respond_to?(:response) ? response['hits']['total'] : raw_response['hits']['total']

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

@@ -6,8 +6,6 @@ class Pagy
   module KeynavJsPaginator
     module_function
 
-    # Return the Pagy::Keyset::Keynav instance and paginated records.
-    # Fall back to :countless if the :page has no client data.
     def paginate(set, options)
       page = options[:request].resolve_page(force_integer: false) # allow nil
 

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

@@ -4,7 +4,6 @@ class Pagy
   module KeysetPaginator
     module_function
 
-    # Return Pagy::Keyset instance and paginated records
     def paginate(set, options)
       options[:page] ||= options[:request].resolve_page(force_integer: false) # allow nil
       options[:limit]  = options[:request].resolve_limit

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

@@ -6,7 +6,6 @@ class Pagy
   module MeilisearchPaginator
     module_function
 
-    # Paginate from the search object
     def paginate(search, options)
       if search.is_a?(Search::Arguments) # Active mode
 

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

@@ -29,7 +29,7 @@ class Pagy
                            end
 
                options[:root_key]  = 'page' if options[:jsonapi] # enforce 'page' root_key for JSON:API
-               options[:request] ||= request                     # user set request or self.request
+               options[:request] ||= request                     # custom request Hash or self.request
                options[:request]   = Request.new(options)        # Pagy::Request
 
                Pagy.const_get(paginators[paginator]).paginate(*arguments)

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

@@ -6,7 +6,6 @@ class Pagy
   module OffsetPaginator
     module_function
 
-    # Return the Pagy::Offset instance and results
     def paginate(collection, options)
       options[:page]  ||= options[:request].resolve_page
       options[:limit]   = options[:request].resolve_limit

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

@@ -6,7 +6,6 @@ class Pagy
   module SearchkickPaginator
     module_function
 
-    # Paginate from the search object
     def paginate(search, options)
       if search.is_a?(Search::Arguments) # Active mode
 

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

@@ -6,7 +6,6 @@ class Pagy
   module TypesenseRailsPaginator
     module_function
 
-    # Paginate from the search object
     def paginate(search, options)
       if search.is_a?(Search::Arguments) # Active mode
 

data/lib/pagy.rb

@@ -7,10 +7,9 @@ require_relative 'pagy/modules/abilities/linkable'
 require_relative 'pagy/modules/abilities/configurable'
 require_relative 'pagy/toolbox/helpers/loaders'
 
-# Top superclass: it defines only what's common to all the subclasses
-# noinspection RubyMismatchedArgumentType
+# Top superclass
 class Pagy
-  VERSION     = '43.4.3'
+  VERSION     = '43.5.0'
   ROOT        = Pathname.new(__dir__).parent.freeze
   DEFAULT     = { limit: 20, limit_key: 'limit', page_key: 'page' }.freeze
   PAGE_TOKEN  = EscapedValue.new('P ')
@@ -34,12 +33,6 @@ class Pagy
 
   OPTIONS = {} # rubocop:disable Style/MutableConstant
 
-  def self.options
-    OPTIONS.tap do
-      warn "[PAGY] 'Pagy.options' is deprecated: use 'Pagy::OPTIONS directly'"
-    end
-  end
-
   extend Configurable
   include Linkable
   include HelperLoader
@@ -48,7 +41,7 @@ class Pagy
 
   protected
 
-  # Define the hierarchical identity methods, overridden by the respective classes
+  # Instance identity methods, overridden by the respective classes
   def offset?    = false
   def countless? = false
   def calendar?  = false
@@ -56,7 +49,7 @@ class Pagy
   def keyset?    = false
   def keynav?    = false
 
-  # Validates and assign the passed options: they must be present and value.to_i must be >= min
+  # Validate presence and min value of options
   def assign_and_check(name_min)
     name_min.each do |name, min|
       value = @options[name]
@@ -71,11 +64,6 @@ class Pagy
 
   # Merge all the DEFAULT constants of the class hierarchy with the options
   def assign_options(**options)
-    if options.key?(:max_pages)
-      warn "[PAGY] the ':max_pages' option is deprecated: " \
-           'use https://ddnexus.github.io/pagy/guides/how-to/#paginate-only-max-records instead.'
-    end
-
     @request = options.delete(:request) # internal object
     default  = {}
     current  = self.class
@@ -95,3 +83,5 @@ class Pagy
     include NumericHelperLoader
   end
 end
+
+require_relative ENV['PAGY_NEXT'] == 'true' ? 'pagy/next' : 'pagy/deprecated'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 43.4.3
+  version: 43.5.0
 platform: ruby
 authors:
 - Domizio Demichelis
@@ -98,6 +98,7 @@ files:
 - lib/pagy/classes/request.rb
 - lib/pagy/cli.rb
 - lib/pagy/console.rb
+- lib/pagy/deprecated.rb
 - lib/pagy/modules/abilities/configurable.rb
 - lib/pagy/modules/abilities/countable.rb
 - lib/pagy/modules/abilities/linkable.rb
@@ -115,6 +116,7 @@ files:
 - lib/pagy/modules/i18n/p11n/polish.rb
 - lib/pagy/modules/i18n/p11n/west_slavic.rb
 - lib/pagy/modules/searcher.rb
+- lib/pagy/next.rb
 - lib/pagy/tasks/sync.rb
 - lib/pagy/toolbox/helpers/anchor_tags.rb
 - lib/pagy/toolbox/helpers/bootstrap/input_nav_js.rb
@@ -191,7 +193,6 @@ files:
 - locales/zh-CN.yml
 - locales/zh-HK.yml
 - locales/zh-TW.yml
-- sig/pagy.rbs
 - stylesheets/pagy-tailwind.css
 - stylesheets/pagy.css
 homepage: https://github.com/ddnexus/pagy
@@ -211,14 +212,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: "Pagy \U0001F438 The Leaping Gem!"
 test_files: []

data/sig/pagy.rbs

@@ -1,315 +0,0 @@
-# sig/pagy.rbs
-
-class Pagy
-  VERSION: String
-  ROOT:    Pathname
-  OPTIONS: options
-
-  # @deprecated Use `Pagy::OPTIONS` instead
-  def self.options: () -> options
-
-  # @deprecated Use `sync(:javascript, ...)` instead
-  def self.sync_javascript: (String destination, *String targets) -> void
-
-  def self.sync: (Symbol resource, String destination, *String targets) -> void
-  def self.dev_tools: (?wand_scale: Integer) -> String
-  def self.translate_with_the_slower_i18n_gem!: () -> void
-
-  class Offset < Pagy
-    attr_reader offset:   Integer
-    attr_reader count:    Integer
-    attr_reader from:     Integer
-    attr_reader to:       Integer
-    attr_reader previous: Integer?
-    attr_reader next:     Integer?
-    attr_reader last:     Integer
-
-    alias pages last
-  end
-
-  class Countish < Offset
-  end
-  class Countless < Offset
-    attr_reader last: Integer?
-  end
-  class Keyset < Pagy
-    class ActiveRecord < Keyset
-    end
-    class Sequel < Keyset
-    end
-    class Keynav < Keyset
-      class ActiveRecord < Keyset
-      end
-      class Sequel < Keyset
-      end
-    end
-
-    attr_reader records: Array[untyped]
-  end
-
-  class Calendar < ::Hash[Symbol, Calendar::Unit]
-    def self.localize_with_rails_i18n_gem: (*Symbol locales) -> void
-
-    def showtime: () -> ActiveSupport::TimeWithZone
-    def url_at: (ActiveSupport::TimeWithZone time, **url_opts) -> String
-
-    class Unit < Pagy
-      attr_reader order: Symbol
-      attr_reader from: ActiveSupport::TimeWithZone
-      attr_reader to: ActiveSupport::TimeWithZone
-      attr_reader previous: Integer?
-      attr_reader last: Integer
-      alias pages last
-    end
-
-    class Year < Unit
-    end
-    class Quarter < Unit
-    end
-    class Month < Unit
-    end
-    class Week < Unit
-    end
-    class Day < Unit
-    end
-  end
-
-  class SearchBase < Offset
-  end
-
-  class ElasticsearchRails < SearchBase
-  end
-
-  class Meilisearch < SearchBase
-  end
-
-  class Searchkick < SearchBase
-  end
-
-  class TypesenseRails < SearchBase
-  end
-
-  module Search
-    class Arguments < Array[untyped]
-    end
-
-    def pagy_search: (*untyped arguments, untyped) -> Search::Arguments
-  end
-
-  class Method
-    interface _Collection
-      def offset: (Integer offset) -> _Collection
-      def limit:  (Integer limit)  -> _Collection
-    end
-
-
-    type collection = _Collection | Array[untyped]
-
-    def pagy: (:offset,    collection collection, **offset_opts options)    -> [Offset,    collection]
-            | (:countless, collection collection, **countless_opts options) -> [Countless, collection]
-            | (:countish,  collection collection, **countish_opts options)  -> [Countish,  collection]
-
-            | (:keyset,    ::ActiveRecord::Relation[untyped] set, **keyset_opts options) -> [Keyset::ActiveRecord, Array[::ActiveRecord::Base[untyped]]]
-            | (:keyset,    ::Sequel::Dataset[untyped] set,        **keyset_opts options) -> [Keyset::Sequel, Array[::Sequel::Model[untyped]]]
-
-            | (:keynav_js, ::ActiveRecord::Relation[untyped] set, **keyset_opts options) -> [Keyset::Keynav::ActiveRecord, Array[::ActiveRecord::Base[untyped]]]
-            | (:keynav_js, ::Sequel::Dataset[untyped] set,        **keyset_opts options) -> [Keyset::Keynav::Sequel, Array[::Sequel::Model[untyped]]]
-
-            | (:calendar, _Collection collection, **calendar_config) -> [Calendar, Offset, _Collection]
-
-            | (:elasticsearch_rails, Search::Arguments, **search_opts options) -> [ElasticsearchRails, untyped]
-            | (:elasticsearch_rails, untyped search, **search_opts options)    -> ElasticsearchRails
-
-            | (:meilisearch, Search::Arguments, **search_opts options) -> [Meilisearch, untyped]
-            | (:meilisearch, untyped search, **search_opts options)    -> Meilisearch
-
-            | (:searchkick, Search::Arguments, **search_opts options) -> [Searchkick, untyped]
-            | (:searchkick, untyped search, **search_opts options)    -> Searchkick
-
-            | (:typesense_rails, Search::Arguments, **search_opts options) -> [TypesenseRails, untyped]
-            | (:typesense_rails, untyped search, **search_opts options)    -> TypesenseRails
-  end
-
-  # Helper methods
-  def data_hash: (**data_opts) -> pagy_data_hash
-  def headers_hash: (**headers_opts) -> Hash[String, String]
-  def urls_hash: (**url_opts) -> Hash[Symbol, String]
-
-  def page_url: (:first | :current | :page | :previous | :next | :last | Integer page, **url_opts) -> String
-  def next_tag: (String? text, **anchor_tags_opts) -> String
-
-  module NumericHelpers
-    def series_nav:    (?Symbol? style, **series_nav_opts) -> String
-    def series_nav_js: (?Symbol? style, **series_nav_js_opts) -> String
-    def input_nav_js:  (?Symbol? style, **nav_opts) -> String
-
-    def previous_tag: (String? text, **anchor_tags_opts) -> String
-    def limit_tag_js: (?id: String?, ?item_name: String?, **url_opts) -> String
-    def info_tag:     (?id: String?, ?item_name: String?) -> String
-  end
-
-  ##### OPTIONS #####
-
-  type url_opts = {
-    ?fragment:  String,
-    ?absolute:  bool,
-    ?path:      String,
-    ?querify:   Proc,
-    ?jsonapi:   bool,
-    ?root_key:  String,
-    ?page_key:  String,
-    ?limit_key: String,
-  }
-
-  ##### Paginator Options #####
-
-  type paginator_opts = url_opts & {
-    ?page:             Integer,
-    ?limit:            Integer,
-    ?max_pages:        Integer,
-    ?client_max_limit: Integer,
-    ?request:          _RackRequest | request_hash
-  }
-
-  type offset_opts = paginator_opts & {
-    ?count:             Integer,
-    ?count_over:        bool,
-    ?raise_range_error: bool
-  }
-
-  type countish_opts = offset_opts & {
-    ?ttl:   Integer,
-    ?epoch: Integer
-  }
-
-  type countless_opts = offset_opts & {
-    ?headless: bool
-  }
-
-  type unit_opts = paginator_opts & {
-    ?slots:    Integer,
-    ?compact:  bool,
-    ?format:   String,
-    ?order:    Symbol
-  }
-
-  type calendar_config = {
-    ?year:     unit_opts,
-    ?quarter:  unit_opts,
-    ?month:    unit_opts,
-    ?week:     unit_opts,
-    ?day:      unit_opts,
-    ?offset:   offset_opts,
-    ?disabled: bool
-  }
-
-  type keyset_opts = paginator_opts & {
-    ?keyset:           Hash[untyped, untyped],
-    ?tuple_comparison: bool,
-    ?pre_serialize:    Proc
-  }
-
-  type search_opts = {
-    ?search_method: Symbol
-  }
-
-  ##### Helper Options #####
-
-  ### data_hash ###
-  type pagy_data_key = :url_template | :first_url | :previous_url | :current_url
-                     | :page_url | :next_url | :last_url | :count | :page
-                     | :limit | :last | :in | :from | :to | :previous
-                     | :next | :options | Symbol
-
-  # The return structure with optional keys (marked with ?)
-  type pagy_data_hash = {
-    ?url_template: String,
-    ?first_url:    String,
-    ?previous_url: String,
-    ?current_url:  String,
-    ?page_url:     String,
-    ?next_url:     String,
-    ?last_url:     String,
-    ?count:        Integer,
-    ?page:         Integer,
-    ?limit:        Integer,
-    ?last:         Integer,
-    ?in:           Integer,
-    ?from:         Integer,
-    ?to:           Integer,
-    ?previous:     Integer,
-    ?next:         Integer,
-    ?options:      options
-  } & Hash[Symbol, untyped] # Intersection allows for 'send' method results
-
-  type data_opts = url_opts & {
-    ?data_keys: Array[pagy_data_key]
-  }
-
-  type headers_opts = url_opts & {
-    ?headers_map: Hash[Symbol, String]
-  }
-
-  ##### NumericUI Options #####
-  type anchor_tags_opts = url_opts & {
-    ?text:       String,
-    ?aria_label: String
-  }
-
-  type nav_opts = url_opts & {
-    ?id:            String,
-    ?aria_label:    String,
-    ?item_name:     String,
-    ?style:         :pagy | :bootstrap | :bulma,
-    ?anchor_string: String
-  }
-
-  type series_nav_opts = nav_opts & {
-    ?slots:   Integer,
-    ?compact: bool,
-  }
-
-  type series_nav_js_opts = series_nav_opts & {
-    ?steps: Hash[Integer, Integer]
-  }
-
-  type options = url_opts & paginator_opts & offset_opts & countish_opts & countless_opts &
-                 unit_opts & keyset_opts & search_opts &
-                 anchor_tags_opts & nav_opts & data_opts & headers_opts & nav_opts & series_nav_opts & series_nav_js_opts
-
-  ##### REQUEST #####
-
-  interface _RackRequest
-    def base_url: () -> String
-    def path:     () -> String
-    def GET:      () -> Hash[String, untyped]
-    def POST:     () -> Hash[String, untyped]
-    def cookies:  () -> Hash[String, String]
-  end
-
-  type request_hash = {
-    base_url: String,
-    path:     String,
-    params:   Hash[String, untyped],
-    ?cookie:  String
-  }
-end
-
-module ActiveRecord
-  class Base[T]
-  end
-  class Relation[T]
-  end
-end
-
-module ActiveSupport
-  class TimeWithZone
-  end
-end
-
-module Sequel
-  class Dataset[T]
-  end
-  class Model[T]
-  end
-end