WIP: Super refactoring

.rubocop.yml

@@ -69,7 +69,7 @@ Style/LambdaCall:
   Enabled: false
 
 
-# cannot inline the disabling in the file because rubocop complains anyway
+# Cannot inline the disabling in the file because rubocop complains anyway
 Style/RedundantInitialize:
   Exclude:
     - test/mock_helpers/arel.rb
@@ -78,7 +78,9 @@ Style/RedundantInitialize:
 Style/StringConcatenation:
   Enabled: false
 
-# these cops are disabled only in the test files in order to
+Style/Documentation:
+  Enabled: false
+# These cops are disabled only in the test files in order to
 # allow to copy and paste the failed output for test reconciliation
 Style/StringLiterals:
   Enabled: true

Gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: gem
   specs:
     pagy (9.3.3)
+      json
 
 GEM
   remote: https://rubygems.org/
@@ -154,7 +155,7 @@ GEM
     mustermann (3.0.3)
       ruby2_keywords (~> 0.0.1)
     mutex_m (0.3.0)
-    net-imap (0.5.4)
+    net-imap (0.5.5)
       date
       net-protocol
     net-pop (0.1.2)
@@ -203,7 +204,8 @@ GEM
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
       rack (>= 3.0.0, < 4)
-    rack-session (2.0.0)
+    rack-session (2.1.0)
+      base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rack-test (2.2.0)
       rack (>= 1.3)
@@ -271,7 +273,7 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-packaging (0.5.2)
       rubocop (>= 1.33, < 2.0)
-    rubocop-performance (1.23.0)
+    rubocop-performance (1.23.1)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
@@ -315,7 +317,8 @@ GEM
     unicode-emoji (4.0.4)
     uri (1.0.2)
     useragent (0.16.11)
-    websocket-driver (0.7.6)
+    websocket-driver (0.7.7)
+      base64
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     zeitwerk (2.7.1)

docs/api/javascript/setup.md

@@ -8,7 +8,7 @@ order: 4
 
 !!!info Notice
 
-A javascript setup is required only for the `pagy*_js` helpers and the `pagy*_nav` for `Pagy::KeysetForUI` instances. Just using
+A javascript setup is required only for the `pagy*_js` helpers and the `pagy*_nav` for `Pagy::Keyset::Augmented` instances. Just using
 something like `anchor_string: 'data-remote="true"'` in any instances, works out of the box with any helper and without this
 setup.
 !!!
@@ -21,7 +21,7 @@ setup.
 
 ### How does it work?
 
-All the `pagy*_js` helpers, and the `pagy*_nav` for `Pagy::KeysetForUI` instances, complete their component on the
+All the `pagy*_js` helpers, and the `pagy*_nav` for `Pagy::Keyset::Augmented` instances, complete their component on the
 client side. The helper methods serves just a minimal HTML tag that contains a `data-pagy` attribute.
 
 Your app should [serve or bundle](#2-configure) a small [javascript file](#1-pick-a-javascript-file) and [run the `Pagy.init()

docs/api/keyset.md

@@ -227,7 +227,7 @@ which naturally ends with the end of the `set`, so it doesn't have any `cutoff`
 - A `cutoff` identifies a "cutoff value", for a `page` in the `set`. It is not a record nor a reference to it.
 - Its value is derived from the `keyset attributes values` array of the last record of the `page`, converted to JSON, and encoded
   as a Base64 URL-safe string, for easy use in URLs.
-  - `Pagy::Keyset` embeds it in the request URL; `Pagy::KeysetForUI` caches it on the client `sessionStorage`.
+  - `Pagy::Keyset` embeds it in the request URL; `Pagy::Keyset::Augmented` caches it on the client `sessionStorage`.
 - All the `page`s but the last, end with the `cutoff`.
 - All the `page`s but the first, begin AFTER the `cutoff` of the previous `page`.
 

docs/api/keyset_for_ui.md

@@ -1,11 +1,11 @@
 ---
-title: Pagy::KeysetForUI
+title: Pagy::Keyset::Augmented
 category:
   - Feature
   - Class
 ---
 
-# Pagy::KeysetForUI
+# Pagy::Keyset::Augmented
 
 A [Pagy::Keyset](keyset.md) subclass supporting `pagy_*nav` and other Frontend helpers.
 
@@ -17,7 +17,7 @@ A [Pagy::Keyset](keyset.md) subclass supporting `pagy_*nav` and other Frontend h
 The regular `Pagy::Keyset` uses the fastest technique for SQL pagination, but it cannot work with any Frontend helper because they
 require a pagy object with numeric variables.
 
-That's why we created `Pagy::KeysetForUI`: it uses the fast keyset pagination AND supports `pagy_*navs` and other Frontend
+That's why we created `Pagy::Keyset::Augmented`: it uses the fast keyset pagination AND supports `pagy_*navs` and other Frontend
 helpers.
 
 !!!
@@ -45,7 +45,7 @@ The Keyset pagination for UI adds the numeric variables (`page`, `last`, `prev`,
 usage with most Frontend helpers. It does so by transparently exchanging data back and forth with the client, that stores the
 state of the pagination.
 
-You can use a `Pagy::KeysetForUI` object as you would with a standard `Pagy` (offset countless) object. You need just a different
+You can use a `Pagy::Keyset::Augmented` object as you would with a standard `Pagy` (offset countless) object. You need just a different
 setup and you will get a lot more performance.
 
 ==- In-depth: Understanding the data exchange
@@ -182,24 +182,24 @@ user by:
 
 ## ORMs
 
-`Pagy::KeysetForUI` implements the subclasses for `ActiveRecord::Relation` and `Sequel::Dataset` sets and instantiate them
+`Pagy::Keyset::Augmented` implements the subclasses for `ActiveRecord::Relation` and `Sequel::Dataset` sets and instantiate them
 internally:
 
 ```ruby
-Pagy::KeysetForUI.new(active_record_set)
-#=> #<Pagy::KeysetForUI::ActiveRecord:0x00000001066215e0>
+Pagy::Keyset::Augmented.new(active_record_set)
+#=> #<Pagy::Keyset::Augmented::ActiveRecord:0x00000001066215e0>
 
-Pagy::KeysetForUI.new(sequel_set)
-#=> #<Pagy::KeysetForUI::Sequel:0x00000001066545e0>
+Pagy::Keyset::Augmented.new(sequel_set)
+#=> #<Pagy::Keyset::Augmented::Sequel:0x00000001066545e0>
 ```
 
 ## Methods
 
-==- `Pagy::KeysetForUI.new(set, **vars)`
+==- `Pagy::Keyset::Augmented.new(set, **vars)`
 
 The constructor takes the `set`, and an optional hash of [variables](#variables). It returns a
-`Pagy::KeysetForUI::ActiveRecord` or
-`Pagy::KeysetForUI::Sequel` object (depending on the `set` class).
+`Pagy::Keyset::Augmented::ActiveRecord` or
+`Pagy::Keyset::Augmented::Sequel` object (depending on the `set` class).
 
 ==- `records`
 

docs/extras/keyset_for_ui.md

@@ -17,7 +17,7 @@ and other Frontend helpers.
 
 ## Overview
 
-This is a wrapper around the [Pagy::KeysetForUI API](/docs/api/keyset_for_ui.md). Please refer to the following resources:
+This is a wrapper around the [Pagy::Keyset::Augmented API](/docs/api/keyset_for_ui.md). Please refer to the following resources:
 
 [!ref Keyset For UI: Documentation](/docs/api/keyset_for_ui.md)
 

docs/extras/limit.md

@@ -102,9 +102,9 @@ The `limit` extra adds the `pagy_limit_selector_js` helper to the `Pagy::Fronten
 
 ==- `pagy_limit_selector_js(pagy, **vars)`
 
-!!!warning Not for KeysetForUI instances!
+!!!warning Not for Keyset::Augmented instances!
 
-This helper doesn't make sense, and doesn't work with `Pagy::KeysetForUI` instances.
+This helper doesn't make sense, and doesn't work with `Pagy::Keyset::Augmented` instances.
 !!!
 
 This helper provides a limit selector UI, which allows the user to select any arbitrary limit per page (below the `:limit_max`

gem/apps/keyset.ru

@@ -40,7 +40,7 @@ Pagy::DEFAULT.freeze
 # Sinatra setup
 require 'sinatra/base'
 # Sinatra application
-class PagyKeyset < Sinatra::Base
+class PagyKeysetAugmented < Sinatra::Base
   include Pagy::Backend
   # Root route/action
   get '/' do

gem/apps/keyset_for_ui.ru → gem/apps/keyset_augmented.ru

@@ -10,8 +10,8 @@
 #    bundle exec pagy -h
 #
 # DEV USAGE
-#    bundle exec pagy clone keyset_for_ui
-#    bundle exec pagy ./keyset_for_ui.ru
+#    bundle exec pagy clone keyet_augmented
+#    bundle exec pagy ./keyset_augmented.ru
 #
 # URL
 #    http://0.0.0.0:8000
@@ -31,16 +31,14 @@ gemfile(ENV['PAGY_INSTALL_BUNDLE'] == 'true') do
 end
 
 # Pagy initializer
-require 'pagy/extras/keyset_for_ui'
 require 'pagy/extras/limit'
-require 'pagy/extras/pagy'
 Pagy::DEFAULT[:limit] = 4
 Pagy::DEFAULT.freeze
 
 # Sinatra setup
 require 'sinatra/base'
 # Sinatra application
-class PagyKeyset < Sinatra::Base
+class PagyKeysetAugmented < Sinatra::Base
   include Pagy::Backend
 
   get('/javascripts/:file') do
@@ -58,7 +56,7 @@ class PagyKeyset < Sinatra::Base
     Time.zone = 'UTC'
 
     @order = { animal: :asc, name: :asc, birthdate: :desc, id: :asc }
-    @pagy, @pets = pagy_keyset_for_ui(Pet.order(@order))
+    @pagy, @pets = pagy_keyset_augmented_js(Pet.order(@order))
     @ids = @pets.pluck(:id)
     erb :main
   end
@@ -78,7 +76,7 @@ class PagyKeyset < Sinatra::Base
       <html lang="en">
       <html>
       <head>
-         <title>Pagy Keyset For UI App</title>
+         <title>Pagy Keyset Augmented App</title>
         <script src="javascripts/pagy.js"></script>
          <script>
           window.addEventListener("load", Pagy.init);
@@ -113,9 +111,9 @@ class PagyKeyset < Sinatra::Base
   template :main do
     <<~ERB
       <div class="content">
-        <h1>Pagy Keyset For UI App</h1>
+        <h1>Pagy Keyset Augmented App</h1>
         <p>Self-contained, standalone app usable to easily reproduce any Keyset For UI related pagy issue
-        with ActiveRecord sets. Notice that Keyset For UI works also with Sequel sets</p>
+        with ActiveRecord sets. Notice that Keyset Augmented works also with Sequel sets</p>
         <p>Please, report the following versions in any new issue.</p>
         <h2>Versions</h2>
         <ul>
@@ -248,4 +246,4 @@ data.each_line(chomp: true) do |pet|
 end
 Pet.insert_all(pets)
 
-run PagyKeyset
+run PagyKeysetAugmented

gem/apps/keyset_sequel.ru

@@ -41,7 +41,7 @@ Pagy::DEFAULT.freeze
 require 'sinatra/base'
 require 'logger'
 # Sinatra application
-class PagyKeyset < Sinatra::Base
+class PagyKeysetAugmented < Sinatra::Base
   include Pagy::Backend
   # Root route/action
   get '/' do
@@ -216,4 +216,4 @@ data.each_line(chomp: true) do |pet|
   dataset.insert(name:, animal:, birthdate:)
 end
 
-run PagyKeyset
+run PagyKeysetAugmented

gem/config/pagy.rb

@@ -8,7 +8,7 @@
 # Pagy Variables
 # See https://ddnexus.github.io/pagy/docs/api/pagy#variables
 # You can set any pagy variable as a Pagy::DEFAULT. They can also be overridden per instance by just passing them to
-# Pagy.new|Pagy::Countless.new|Pagy::Calendar::*.new or any of the #pagy* controller methods
+# Pagy::Offset.new|Pagy::Offset::Countless.new|Pagy::Offset::Calendar::*.new or any of the #pagy* controller methods
 # Here are the few that make more sense as DEFAULTs:
 # Pagy::DEFAULT[:limit]      = 20      # default
 # Pagy::DEFAULT[:size]       = 7       # default
@@ -43,19 +43,19 @@
 # See https://ddnexus.github.io/pagy/docs/extras/calendar
 # require 'pagy/extras/calendar'
 # Default for each calendar unit class in IRB:
-# >> Pagy::Calendar::Year::DEFAULT
-# >> Pagy::Calendar::Quarter::DEFAULT
-# >> Pagy::Calendar::Month::DEFAULT
-# >> Pagy::Calendar::Week::DEFAULT
-# >> Pagy::Calendar::Day::DEFAULT
+# >> Pagy::Offset::Calendar::Year::DEFAULT
+# >> Pagy::Offset::Calendar::Quarter::DEFAULT
+# >> Pagy::Offset::Calendar::Month::DEFAULT
+# >> Pagy::Offset::Calendar::Week::DEFAULT
+# >> Pagy::Offset::Calendar::Day::DEFAULT
 #
 # Uncomment the following lines, 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
+# Pagy::Offset::Calendar.prepend LocalizePagyCalendar
 
 # Countless extra: Paginate without any count, saving one query per rendering
 # See https://ddnexus.github.io/pagy/docs/extras/countless