pagy 5.7.5 → 8.6.2

data/lib/pagy/extras/foundation.rb

@@ -1,88 +1,93 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/foundation
 # frozen_string_literal: true
 
-require 'pagy/extras/frontend_helpers'
+warn '[PAGY WARNING] The foundation extra has been discontinued and it will be removed in v9 ' \
+     '(https://github.com/ddnexus/pagy/discussions/672#discussioncomment-9212328)'
+
+require_relative 'js_tools'
 
 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
     # 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: '', **vars)
-      p_id = %( id="#{pagy_id}") if pagy_id
-      link = pagy_link_proc(pagy, link_extra: link_extra)
+    def pagy_foundation_nav(pagy, id: nil, aria_label: nil, **vars)
+      id = %( id="#{id}") if id
+      a  = pagy_anchor(pagy)
 
-      html = +%(<nav#{p_id} class="pagy-foundation-nav" aria-label="Pagination"><ul class="pagination">)
-      html << pagy_foundation_prev_html(pagy, link)
+      html = +%(<nav#{id} class="pagy-foundation-nav" #{
+                  nav_aria_label(pagy, aria_label:)}><ul class="pagination"> #{
+                  foundation_prev_html(pagy, a)})
       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
-                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}"
+                when Integer
+                  %(<li>#{a.(item)}</li>)
+                when String
+                  %(<li class="current" role="link" aria-current="page" aria-disabled="true">#{pagy.label_for(item)}</li>)
+                when :gap
+                  %(<li class="ellipsis gap"></li>)
+                else
+                  raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
-      html << pagy_foundation_next_html(pagy, link)
-      html << %(</ul></nav>)
+      html << %(#{foundation_next_html(pagy, a)}</ul></nav>)
     end
 
-    # Javascript pagination for foundation: it returns a nav and a JSON tag used by the pagy.js file
-    def pagy_foundation_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
+    # Javascript pagination for foundation: it returns a nav with a data-pagy attribute used by the pagy.js file
+    def pagy_foundation_nav_js(pagy, id: nil, aria_label: nil, **vars)
       sequels = pagy.sequels(**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}),
-               'link'   => %(<li>#{link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER)}</li>),
-               'active' => %(<li class="current">#{LABEL_PLACEHOLDER}</li>),
-               'gap'    => %(<li class="ellipsis gap" aria-hidden="true"></li>),
-               'after'  => %(#{pagy_foundation_next_html pagy, link}</ul>) }
+      id      = %( id="#{id}") if id
+      a       = pagy_anchor(pagy)
+      tokens  = { 'before'  => %(<ul class="pagination">#{foundation_prev_html pagy, a}),
+                  'a'       => %(<li>#{a.(PAGE_TOKEN, LABEL_TOKEN)}</li>),
+                  'current' => %(<li class="current" role="link" aria-current="page" aria-disabled="true">#{LABEL_TOKEN}</li>),
+                  'gap'     => %(<li class="ellipsis gap"></li>),
+                  'after'   => %(#{foundation_next_html pagy, a}</ul>) }
 
-      %(<nav#{p_id} class="#{'pagy-rjs ' if sequels.size > 1}pagy-foundation-nav-js" aria-label="Pagination" #{
-        pagy_json_attr(pagy, :nav, tags, sequels, pagy.label_sequels(sequels))}></nav>)
+      %(<nav#{id} class="#{'pagy-rjs ' if sequels.size > 1}pagy-foundation-nav-js" #{
+          nav_aria_label(pagy, aria_label:)} #{
+          pagy_data(pagy, :nav, tokens, sequels, pagy.label_sequels(sequels))
+        }></nav>)
     end
 
-    # Javascript combo pagination for Foundation: it returns a nav and a JSON tag used by the pagy.js file
-    def pagy_foundation_combo_nav_js(pagy, pagy_id: nil, link_extra: '')
-      p_id    = %( id="#{pagy_id}") if pagy_id
-      link    = pagy_link_proc(pagy, link_extra: link_extra)
-      p_page  = pagy.page
-      p_pages = pagy.pages
-      input   = %(<input class="input-group-field cell shrink" type="number" min="1" max="#{
-                    p_pages}" value="#{p_page}" style="width: #{
-                    p_pages.to_s.length + 1}rem; padding: 0 0.3rem; margin: 0 0.3rem;">)
+    # Javascript combo pagination for Foundation: it returns a nav with a data-pagy attribute used by the pagy.js file
+    def pagy_foundation_combo_nav_js(pagy, id: nil, aria_label: nil)
+      id    = %( id="#{id}") if id
+      a     = pagy_anchor(pagy)
+      pages = pagy.pages
+
+      page_input = %(<input name="page" type="number" min="1" max="#{pages}" value="#{pagy.page}" aria-current="page" ) <<
+                   %(style="text-align: center; width: #{pages.to_s.length + 1}rem; ) <<
+                   %(height: 1.5rem; padding: .5rem; margin: 0 .4rem; font-size: .875rem;" class="current">#{JSTools::A_TAG})
 
-      %(<nav#{p_id} class="pagy-foundation-combo-nav-js" aria-label="Pagination"><div class="input-group" #{
-          pagy_json_attr pagy, :combo, pagy_marked_link(link)}>#{
-          if (p_prev  = pagy.prev)
-            link.call p_prev, pagy_t('pagy.nav.prev'),
-                      'style="margin-bottom: 0" aria-label="previous" class="prev button primary"'
-          else
-            %(<a style="margin-bottom: 0" class="prev button primary disabled" href="#">#{pagy_t 'pagy.nav.prev'}</a>)
-          end
-        }<span class="input-group-label">#{pagy_t 'pagy.combo_nav_js', page_input: input, count: p_page, pages: p_pages}</span>#{
-          if (p_next  = pagy.next)
-            link.call p_next, pagy_t('pagy.nav.next'), 'style="margin-bottom: 0" aria-label="next" class="next button primary"'
-          else
-            %(<a style="margin-bottom: 0" class="next button primary disabled" href="#">#{pagy_t 'pagy.nav.next'}</a>)
-          end
-        }</div></nav>)
+      %(<nav#{id} class="pagy-foundation-combo-nav-js" #{
+          nav_aria_label(pagy, aria_label:)} #{
+          pagy_data(pagy, :combo, pagy_url_for(pagy, PAGE_TOKEN))
+        }><ul class="pagination">#{
+          foundation_prev_html(pagy, a)
+        }<li style="padding: 0 .3rem"><label style="display: flex; align-items: center; white-space: nowrap">#{
+          pagy_t('pagy.combo_nav_js', page_input:, pages:)
+        }</label></li>#{
+          foundation_next_html(pagy, a)
+        }</ul></nav>)
     end
 
     private
 
-    def pagy_foundation_prev_html(pagy, link)
+    def foundation_prev_html(pagy, a)
       if (p_prev = pagy.prev)
-        %(<li class="prev">#{link.call p_prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"'}</li>)
+        %(<li class="prev">#{a.(p_prev, pagy_t('pagy.prev'), aria_label: pagy_t('pagy.aria_label.prev'))}</li>)
       else
-        %(<li class="prev disabled">#{pagy_t 'pagy.nav.prev'}</li>)
+        %(<li class="prev disabled" role="link" aria-disabled="true" aria-label="#{
+            pagy_t('pagy.aria_label.prev')}">#{pagy_t('pagy.prev')}</li>)
       end
     end
 
-    def pagy_foundation_next_html(pagy, link)
+    def foundation_next_html(pagy, a)
       if (p_next = pagy.next)
-        %(<li class="next">#{link.call p_next, pagy_t('pagy.nav.next'), 'aria-label="next"'}</li>)
+        %(<li class="next">#{a.(p_next, pagy_t('pagy.next'), aria_label: pagy_t('pagy.aria_label.next'))}</li>)
       else
-        %(<li class="next disabled">#{pagy_t 'pagy.nav.next'}</li>)
+        %(<li class="next disabled" role="link" aria-disabled="true" aria-label="#{
+             pagy_t('pagy.aria_label.next')}">#{pagy_t('pagy.next')}</li>)
       end
     end
   end

data/lib/pagy/extras/gearbox.rb

@@ -1,4 +1,4 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/gearbox
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/gearbox
 # frozen_string_literal: true
 
 class Pagy # :nodoc:
@@ -12,30 +12,43 @@ class Pagy # :nodoc:
     def setup_items_var
       return super if !@vars[:gearbox_extra] || @vars[:items_extra]
 
-      gearbox_items = @vars[:gearbox_items]
-      raise VariableError.new(self, :gearbox_items, 'to be an Array of positives', gearbox_items) \
-            unless gearbox_items.is_a?(Array) && gearbox_items.all? { |num| num.positive? rescue false } # rubocop:disable Style/RescueModifier
+      gears = @vars[:gearbox_items]
+      raise VariableError.new(self, :gearbox_items, 'to be an Array of positives', gears) \
+            unless gears.is_a?(Array) && gears.all? { |num| num.positive? rescue false } # rubocop:disable Style/RescueModifier
 
-      @items = gearbox_items[@page - 1] || gearbox_items.last
+      @items = gears[@page - 1] || gears.last
     end
 
-    # Setup @pages and @last based on the :gearbox_items variable
-    def setup_pages_var
+    # Setup @offset based on the :gearbox_items variable
+    def setup_offset_var
       return super if !@vars[:gearbox_extra] || @vars[:items_extra]
 
-      gearbox_items = @vars[:gearbox_items]
+      gears   = @vars[:gearbox_items]
+      @offset = if @page <= gears.count
+                  gears[0, @page - 1].sum
+                else
+                  gears.sum + (gears.last * (@page - gears.count - 1))
+                end + @outset
+    end
+
+    # Setup Pagy @last based on the :gearbox_items variable and @count
+    def setup_last_var
+      return super if !@vars[:gearbox_extra] || @vars[:items_extra]
+
+      gears = @vars[:gearbox_items]
       # This algorithm is thousands of times faster than the one in the geared_pagination gem
-      @pages = @last = (if @count > (sum = gearbox_items.sum)
-                          [((@count - sum).to_f / gearbox_items.last).ceil, 1].max + gearbox_items.count
-                        else
-                          pages     = 0
-                          remainder = @count
-                          while remainder.positive?
-                            pages     += 1
-                            remainder -= gearbox_items[pages - 1]
-                          end
-                          [pages, 1].max
-                        end)
+      @last = (if count > (sum = gears.sum)
+                 [((count - sum).to_f / gears.last).ceil, 1].max + gears.count
+               else
+                 pages     = 0
+                 remainder = count
+                 while remainder.positive?
+                   pages     += 1
+                   remainder -= gears[pages - 1]
+                 end
+                 [pages, 1].max
+               end)
+      @last = vars[:max_pages] if vars[:max_pages] && @last > vars[:max_pages]
     end
   end
   prepend GearboxExtra

data/lib/pagy/extras/headers.rb

@@ -1,13 +1,13 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/headers
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/headers
 # frozen_string_literal: true
 
-require 'pagy/url_helpers'
+require_relative '../url_helpers'
 
 class Pagy # :nodoc:
-  DEFAULT[:headers] = { page:  'Current-Page',
-                        items: 'Page-Items',
-                        count: 'Total-Count',
-                        pages: 'Total-Pages' }
+  DEFAULT[:headers] = { page:  'current-page',
+                        items: 'page-items',
+                        count: 'total-count',
+                        pages: 'total-pages' }
   # Add specialized backend methods to add pagination response headers
   module HeadersExtra
     include UrlHelpers
@@ -22,7 +22,7 @@ class Pagy # :nodoc:
     # Generate a hash of RFC-8288 compliant http headers
     def pagy_headers(pagy)
       pagy_headers_hash(pagy).tap do |hash|
-        hash['Link'] = hash['Link'].map { |rel, link| %(<#{link}>; rel="#{rel}") }.join(', ')
+        hash['link'] = hash['link'].map { |rel, link| %(<#{link}>; rel="#{rel}") }.join(', ')
       end
     end
 
@@ -31,12 +31,12 @@ class Pagy # :nodoc:
       countless             = defined?(Countless) && pagy.is_a?(Countless)
       rel                   = { 'first' => 1, 'prev' => pagy.prev, 'next' => pagy.next }
       rel['last']           = pagy.last unless countless
-      url_str               = pagy_url_for(pagy, PAGE_PLACEHOLDER, absolute: true)
-      link                  = rel.map do |r, num| # filter_map if ruby >=2.7
+      url_str               = pagy_url_for(pagy, PAGE_TOKEN, absolute: true)
+      link                  = rel.filter_map do |r, num|
                                 next unless num # rubocop:disable Layout/EmptyLineAfterGuardClause
-                                [r, url_str.sub(PAGE_PLACEHOLDER, num.to_s)]
+                                [r, url_str.sub(PAGE_TOKEN, num.to_s)]
                               end.compact.to_h
-      hash                  = { 'Link' => link }
+      hash                  = { 'link' => link }
       headers               = pagy.vars[:headers]
       hash[headers[:page]]  = pagy.page.to_s if headers[:page]
       if headers[:items] && !(defined?(Calendar) && pagy.is_a?(Calendar))  # items is not for Calendar

data/lib/pagy/extras/i18n.rb

@@ -1,25 +1,25 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/i18n
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/i18n
 # frozen_string_literal: true
 
 class Pagy # :nodoc:
   # Use ::I18n gem
   module I18nExtra
     # Frontend overriding for translation
-    module Frontend
+    module FrontendOverride
       def pagy_t(key, **opts)
         ::I18n.t(key, **opts)
       end
     end
+    Frontend.prepend I18nExtra::FrontendOverride
 
     # Calendar overriding for localization (see also the block in the calendar section of the config/pagy.rb initializer)
-    module Calendar
+    module CalendarOverride
       def localize(time, opts)
         ::I18n.l(time, **opts)
       end
     end
   end
-  Frontend.prepend I18nExtra::Frontend
-  Calendar.prepend I18nExtra::Calendar if defined?(Calendar)
+  Calendar::Unit.prepend I18nExtra::CalendarOverride if defined?(Calendar::Unit)
 
   # Add the pagy locales to the I18n.load_path
   ::I18n.load_path += Dir[Pagy.root.join('locales', '*.yml')]

data/lib/pagy/extras/items.rb

@@ -1,7 +1,7 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/items
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/items
 # frozen_string_literal: true
 
-require 'pagy/extras/frontend_helpers'
+require_relative 'js_tools'
 
 class Pagy # :nodoc:
   DEFAULT[:items_param] = :items
@@ -11,44 +11,54 @@ class Pagy # :nodoc:
   # 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
+    module BackendAddOn
       private
 
       # Set the items variable considering the params and other pagy variables
       def pagy_set_items_from_params(vars)
         return if vars[:items]                                                             # :items explicitly set
         return unless vars.key?(:items_extra) ? vars[:items_extra] : DEFAULT[:items_extra] # :items_extra is false
-        return unless (items = params[vars[:items_param] || DEFAULT[:items_param]])        # no items from request params
+        return unless (items_count = pagy_get_items_size(vars))                            # no items from request params
 
-        vars[:items] = [items.to_i, vars.key?(:max_items) ? vars[:max_items] : DEFAULT[:max_items]].compact.min
+        vars[:items] = [items_count.to_i, vars.key?(:max_items) ? vars[:max_items] : DEFAULT[:max_items]].compact.min
+      end
+
+      # Get the items count from the params
+      # Overridable by the jsonapi extra
+      def pagy_get_items_size(vars)
+        params[vars[:items_param] || DEFAULT[:items_param]]
       end
     end
+    Backend.prepend ItemsExtra::BackendAddOn
 
     # Additions for the Frontend module
-    module Frontend
-      ITEMS_PLACEHOLDER = '__pagy_items__'
+    module FrontendAddOn
+      ITEMS_TOKEN = '__pagy_items__'
 
       # Return the items selector HTML. For example "Show [20] items per page"
-      def pagy_items_selector_js(pagy, pagy_id: nil, item_name: nil, i18n_key: nil, link_extra: '')
+      def pagy_items_selector_js(pagy, id: nil, item_name: nil)
         return '' unless pagy.vars[:items_extra]
 
-        p_id           = %( id="#{pagy_id}") if pagy_id
-        p_vars         = pagy.vars
-        p_items        = p_vars[:items]
-        p_vars[:items] = ITEMS_PLACEHOLDER
-        link           = pagy_marked_link(pagy_link_proc(pagy, link_extra: link_extra))
-        p_vars[:items] = p_items # restore the items
-
-        html  = +%(<span#{p_id} class="pagy-items-selector-js" #{pagy_json_attr pagy, :selector, pagy.from, link}>)
-        input = %(<input type="number" min="1" max="#{p_vars[:max_items]}" value="#{
-                    p_items}" style="padding: 0; text-align: center; width: #{p_items.to_s.length + 1}rem;">)
-        html << pagy_t('pagy.items_selector_js', item_name: item_name || pagy_t(i18n_key || p_vars[:i18n_key], count: p_items),
-                                                 items_input: input,
-                                                 count: p_items)
-        html << %(</span>)
+        id           = %( id="#{id}") if id
+        vars         = pagy.vars
+        items        = vars[:items]
+        vars[:items] = ITEMS_TOKEN
+        url_token    = pagy_url_for(pagy, PAGE_TOKEN)
+        vars[:items] = items # restore the items
+
+        items_input = %(<input name="items" type="number" min="1" max="#{vars[:max_items]}" value="#{
+                          items}" style="padding: 0; text-align: center; width: #{items.to_s.length + 1}rem;">#{JSTools::A_TAG})
+
+        %(<span#{id} class="pagy items-selector-js" #{
+            pagy_data(pagy, :selector, pagy.from, url_token)
+          }><label>#{
+            pagy_t('pagy.items_selector_js',
+                   item_name: item_name || pagy_t('pagy.item_name', count: items),
+                   items_input:,
+                   count: items)
+          }</label></span>)
       end
     end
+    Frontend.prepend ItemsExtra::FrontendAddOn
   end
-  Backend.prepend ItemsExtra::Backend
-  Frontend.prepend ItemsExtra::Frontend
 end

data/lib/pagy/extras/{frontend_helpers.rb → js_tools.rb}

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
-require 'digest'
-
 class Pagy # :nodoc:
   DEFAULT[:steps] = false # default false will use {0 => @vars[:size]}
 
   # Private module documented in the main classes
-  module FrontendHelpers
+  module JSTools
+    # Dummy tag for input helpers: needed because Turbo does not intercept window.location changes
+    A_TAG = '<a href="#" style="display: none;">#</a>'
+
     # Additions for the Pagy class
-    module Pagy
+    module PagyAddOn
       # `Pagy` instance method used by the `pagy*_nav_js` helpers.
       # It returns the sequels of width/series generated from the :steps hash
       # Example:
-      # >> pagy = Pagy.new(count:1000, page: 20, steps: {0 => [1,2,2,1], 350 => [2,3,3,2], 550 => [3,4,4,3]})
+      # >> pagy = Pagy.new(count:1000, page: 20, steps: {0 => 5, 350 => 7, 550 => 9})
       # >> pagy.sequels
-      # #=> { "0"   => [1, :gap, 18, 19, "20", 21, 22, :gap, 50],
-      #       "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] }
+      # #=> { "0"   => [18, 19, "20", 21, 22],
+      #       "350" => [1, :gap, 19, "20", 21, :gap, 50],
+      #       "550" => [1 :gap, 18, 19, "20", 21, 22, :gap, 50] }
       # Notice: if :steps is false it will use the single {0 => @vars[:size]} size
       def sequels(steps: @vars[:steps] || { 0 => @vars[:size] }, **_)
         raise VariableError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
@@ -29,9 +30,10 @@ class Pagy # :nodoc:
       # Support for the Calendar API
       def label_sequels(*); end
     end
+    Pagy.prepend PagyAddOn
 
     # Additions for Calendar class
-    module Calendar
+    module CalendarOverride
       def label_sequels(sequels = self.sequels)
         {}.tap do |label_sequels|
           sequels.each do |width, series|
@@ -40,31 +42,29 @@ class Pagy # :nodoc:
         end
       end
     end
+    Calendar::Unit.prepend CalendarOverride if defined?(Calendar::Unit)
 
     # Additions for the Frontend
-    module Frontend
+    module FrontendAddOn
       if defined?(Oj)
-        # Return a script tag with the JSON-serialized args generated with the faster oj gem
-        def pagy_json_attr(pagy, *args)
+        # Return a data tag with the base64 encoded JSON-serialized args generated with the faster oj gem
+        # Base64 encoded JSON is smaller than HTML escaped JSON
+        def pagy_data(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
-          %(data-pagy-json="#{Oj.dump(args, mode: :strict).gsub('"', '&quot;')}")
+          strict_base64_encoded = [Oj.dump(args, mode: :strict)].pack('m0')
+          %(data-pagy="#{strict_base64_encoded}")
         end
       else
         require 'json'
-        # Return a script tag with the JSON-serialized args generated with the slower to_json
-        def pagy_json_attr(pagy, *args)
+        # Return a data tag with the base64 encoded JSON-serialized args generated with the slower to_json
+        # Base64 encoded JSON is smaller than HTML escaped JSON
+        def pagy_data(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
-          %(data-pagy-json="#{args.to_json.gsub('"', '&quot;')}")
+          strict_base64_encoded = [args.to_json].pack('m0')
+          %(data-pagy="#{strict_base64_encoded}")
         end
       end
-
-      # Return the marked link to used by pagy.js
-      def pagy_marked_link(link)
-        link.call PAGE_PLACEHOLDER, '', 'style="display: none;"'
-      end
     end
+    Frontend.prepend FrontendAddOn
   end
-  prepend FrontendHelpers::Pagy
-  Calendar.prepend FrontendHelpers::Calendar if defined?(Calendar)
-  Frontend.prepend FrontendHelpers::Frontend
 end

data/lib/pagy/extras/jsonapi.rb

@@ -0,0 +1,79 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/jsonapi
+# frozen_string_literal: true
+
+require_relative '../url_helpers'
+
+class Pagy # :nodoc:
+  DEFAULT[:jsonapi] = true
+
+  # Add a specialized backend method compliant with JSON:API
+  module JsonApiExtra
+    # JsonApi :page param error
+    class ReservedParamError < StandardError
+      # Inform about the actual value
+      def initialize(value)
+        super("expected reserved :page param to be nil or Hash-like; got #{value.inspect}")
+      end
+    end
+
+    # Module overriding Backend
+    module BackendOverride
+      private
+
+      include UrlHelpers
+
+      # Return the jsonapi links
+      def pagy_jsonapi_links(pagy, **opts)
+        { first: pagy_url_for(pagy, 1,         **opts),
+          last:  pagy_url_for(pagy, pagy.last, **opts),
+          prev:  pagy.prev ? pagy_url_for(pagy, pagy.prev, **opts) : nil,
+          next:  pagy.next ? pagy_url_for(pagy, pagy.next, **opts) : nil }
+      end
+
+      # Should skip the jsonapi
+      def pagy_skip_jsonapi?(vars)
+        return true if vars[:jsonapi] == false || (vars[:jsonapi].nil? && DEFAULT[:jsonapi] == false)
+        # check the reserved :page param
+        raise ReservedParamError, params[:page] unless params[:page].respond_to?(:fetch) || params[:page].nil?
+      end
+
+      # Override the Backend method
+      def pagy_get_page(vars)
+        return super if pagy_skip_jsonapi?(vars)
+        return 1 if params[:page].nil?
+
+        [params[:page][vars[:page_param] || DEFAULT[:page_param]].to_i, 1].max
+      end
+    end
+    Backend.prepend BackendOverride
+
+    # Module overriding ItemsExtra
+    module ItemsExtraOverride
+      private
+
+      # Override the ItemsExtra::Backend method
+      def pagy_get_items_size(vars)
+        return super if pagy_skip_jsonapi?(vars)
+        return if params[:page].nil?
+
+        params[:page][vars[:items_param] || DEFAULT[:items_param]]
+      end
+    end
+    # :nocov:
+    ItemsExtra::BackendAddOn.prepend ItemsExtraOverride if defined?(ItemsExtra::BackendAddOn)
+    # :nocov:
+
+    # Module overriding UrlHelper
+    module UrlHelperOverride
+      # Override UrlHelper method
+      def pagy_set_query_params(page, vars, params)
+        return super unless vars[:jsonapi]
+
+        params['page'] ||= {}
+        params['page'][vars[:page_param].to_s]  = page
+        params['page'][vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
+      end
+    end
+    UrlHelpers.prepend UrlHelperOverride
+  end
+end