WIP: Update docs

docs/api/backend.md

@@ -66,7 +66,7 @@ Get the count from the collection, considering also the `:count_args` variable.
 
 ==- `pagy_get_page(vars)`
 
-Get the `page` from the param ,looking at the `:page_param` variable. See also [Customize the page_param](/docs/how-to.md#customize-the-page-param).
+Get the `page` from the param, looking at the `:page_sym` variable. See also [Customize the page_sym](/docs/how-to.md#customize-the-page-param).
 
 ==- `pagy_get_items(collection, pagy)`
 

docs/api/console.md

@@ -26,7 +26,7 @@ pagy_extras :array, :metadata, ...
 
 ### then you can use it like inside an app
 pagy, items = pagy_array((1..1000).to_a, page: 3)
-=> [#<Pagy:0x00007f59d9cd7190 @count=1000, @from=41, @in=20, @last=50, @limit=20, @next=4, @offset=40, @outset=0, @page=3, @prev=2, @to=60, @vars={:count_args=>[:all], :ends=>true, :limit=>20, :outset=>0, :page=>3, :page_param=>:page, :size=>7, :url=>"http://www.example.com/subdir", :metadata=>[:scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url, :count, :page, :limit, :vars, :pages, :last, :in, :from, :to, :prev, :next, :series], :count=>1000}>, [41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60]]
+=> [#<Pagy:0x00007f59d9cd7190 @count=1000, @from=41, @in=20, @last=50, @limit=20, @next=4, @offset=40, @outset=0, @page=3, @prev=2, @to=60, @vars={:count_args=>[:all], :ends=>true, :limit=>20, :outset=>0, :page=>3, :page_sym=>:page, :size=>7, :url=>"http://www.example.com/subdir", :metadata=>[:scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url, :count, :page, :limit, :vars, :pages, :last, :in, :from, :to, :prev, :next, :series], :count=>1000}>, [41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60]]
 
 pagy_nav(pagy)
 => "<nav class=\"pagy nav\" aria-label=\"Pages\"><a href=\"http://www.example.com/subdir?page=2\" aria-label=\"Previous\">&lt;</a><a href=\"http://www.example.com/subdir?page=1\">1</a><a href=\"http://www.example.com/subdir?page=2\">2</a><a role=\"link\" aria-disabled=\"true\" aria-current=\"page\" class=\"current\">3</a><a href=\"http://www.example.com/subdir?page=4\">4</a><a href=\"http://www.example.com/subdir?page=5\">5</a><a role=\"link\" aria-disabled=\"true\" class=\"gap\">&hellip;</a><a href=\"http://www.example.com/subdir?page=50\">50</a><a href=\"http://www.example.com/subdir?page=4\" aria-label=\"Next\">&gt;</a></nav>"
@@ -48,7 +48,7 @@ pagy_metadata(pagy)
                      :size       => 7,
                      :cycle      => false,
                      :count_args => [:all],
-                     :page_param => :page,
+                     :page_sym   => :page,
                      :url        => "http://www.example.com/subdir",
                      :metadata   => [:scaffold_url,
                                      :first_url,

docs/api/javascript/setup.md

@@ -6,33 +6,32 @@ order: 4
 
 # Javascript Setup
 
-!!!info Notice
-A javascript setup is required only for the `pagy*_js` helpers. Just using something like `anchor_string: 'data-remote="true"'` in any instances works out of the box with any helper and without this setup.
+!!!info Notice 
+
+A javascript setup is required only for the `pagy*_js` helpers and the `pagy*_nav` for `Pagy::KeysetForUI` 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.
 !!!
 
-!!!primary
-We don't publish a `npm` package, because it would not support automatic sync with the gem version.
+!!!primary We don't publish a `npm` package, because it would not support automatic sync with the gem version.
 !!!
 
-!!!success
-Add the `oj` gem to your gemfile for faster performance.
+!!!success Add the `oj` gem to your gemfile for faster performance.
 !!!
 
 ### How does it work?
 
-All the `pagy*_js` helpers render their component on the client side. The helper methods render just a minimal HTML tag that
-contains a `data-pagy` attribute.
+All the `pagy*_js` helpers, and the `pagy*_nav` for `Pagy::KeysetForUI` instances, render or complete their component on the
+client side. The helper methods render 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()
-`](#3-initialize-pagy) function that will take care of converting the the `data-pagy` attribute data and make it work
-in the browser.
+`](#3-initialize-pagy) function that will take care of converting the `data-pagy` attribute data and make it work in the browser.
 
 ### 1. Pick a Javascript File
 
 +++ `pagy.mjs`
 
-!!! success
-Your app uses modern build tools
+!!! success Your app uses modern build tools
 !!!
 
 * ES6 module to use with webpacker, esbuild, parcel, etc.
@@ -50,30 +49,42 @@ types_path = Pagy.root.join('javascripts', 'pagy.d.ts')
 ```
 
 +++ `pagy.min.js`
-!!! success
-Your app needs standard script or old browser compatibility
+!!! success Your app needs standard script or old browser compatibility
 !!!
 
 * It's an [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) file meant to be loaded as is, directly in your
   production pages and without any further processing
-* Minified (~2k) and polyfilled to work also with quite old browsers
+* Minified (~3k)
 
 [!file](/gem/javascripts/pagy.min.js)
 
 ```ruby 
 script_path = Pagy.root.join('javascripts', 'pagy.min.js')
 ```
 
-+++ `pagy.min.js.map`
++++ `pagy.js`
+!!! success Developer version: plain Javascript to use for debugging with its `pagy.js.map`
+!!!
 
-!!! success
-You need to debug the javascript helpers while using the `pagy.min.js` file
+* It's an [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) file meant to be loaded as is, directly in your
+  production pages and without any further processing
+* Minified (~2k) and polyfilled to work also with quite old browsers
+
+[!file](/gem/javascripts/pagy.js)
+
+```ruby 
+script_path = Pagy.root.join('javascripts', 'pagy.js')
+```
+
++++ `pagy.js.map`
+
+!!! success You need to debug the javascript helpers while using the `pagy.js` file
 !!!
 
-[!file](/gem/javascripts/pagy.min.js.map)
+[!file](/gem/javascripts/pagy.js.map)
 
 ```ruby 
-script_path = Pagy.root.join('javascripts', 'pagy.min.js.map')
+script_path = Pagy.root.join('javascripts', 'pagy.js.map')
 ```
 
 +++
@@ -86,14 +97,14 @@ Depending on your environment you have a few ways of configuring your app:
 
 In older versions of Rails, you can configure the app to look into the installed pagy gem javascript files:
 
-+++ Sprockets
++++ Propshaft
 
 ```ruby pagy.rb (initializer)
-Rails.application.config.assets.paths << Pagy.root.join('javascripts') # uncomment.
+Rails.application.config.assets.paths << Pagy.root.join('javascripts')
 ```
 
-```js manifest.js (or "application.js" for old sprocket sprockets):
-//= require pagy
+```erb application.html.erb
+<%= javascript_include_tag "pagy" %>
 ```
 
 +++ Importmaps
@@ -110,14 +121,14 @@ Rails.application.config.assets.paths << Pagy.root.join('javascripts') #uncommen
 pin 'pagy'
 ```
 
-+++ Propshaft
++++ Sprockets
 
 ```ruby pagy.rb (initializer)
-Rails.application.config.assets.paths << Pagy.root.join('javascripts')
+Rails.application.config.assets.paths << Pagy.root.join('javascripts') # uncomment.
 ```
 
-```erb application.html.erb
-<%= javascript_include_tag "pagy" %>
+```js manifest.js (or "application.js" for old sprocket sprockets):
+//= require pagy
 ```
 
 +++
@@ -127,9 +138,10 @@ Rails.application.config.assets.paths << Pagy.root.join('javascripts')
 In order to bundle the `pagy.mjs` your builder has to find it either with a link or local copy, or by looking into the pagy
 javascript path:
 
-+++ Generic
-You can create a symlink or a copy of the `pagy.mjs` file (available in the pagy gem) into an app compiled dir and use it as
-a regular app file. That way any builder will pick it up. For example:
++++ Generic 
+
+You can create a symlink or a copy of the `pagy.mjs` file (available in the pagy gem) into an app compiled dir and use
+it as a regular app file. That way any builder will pick it up. For example:
 
 ```ruby config/initializers/pagy.rb
 # Create/refresh the `app/javascript/pagy.mjs` symlink/copy every time 
@@ -140,6 +152,7 @@ unless Rails.env.production?
 ```
 
 +++ esbuild
+
 Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
 
 ```json package.json
@@ -149,6 +162,7 @@ Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
 ```
 
 +++ Webpack
+
 Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
 
 ```json package.json
@@ -192,11 +206,12 @@ export default class extends Controller {
 
 ```erb View
 <div data-controller="pagy-initializer">
-  <%== pagy_nav_js(@pagy) %>
+<%== pagy_nav_js(@pagy) %>
 </div>
 ```
 
 +++ jsbundling-rails
+
 Import and use the pagy module:
 
 ```js app/javascript/application.js
@@ -239,6 +254,7 @@ If Javascript is disabled in the client browser, certain helpers will be useless
 !!!
 
 !!!danger Overriding `*_js` helpers is not recommended
-The `pagy*_js` helpers are tightly coupled with the javascript code, so any partial overriding on one side, would be quite fragile
-and might break in a next release.
+
+The `pagy*_js` helpers are tightly coupled with the javascript code, so any
+partial overriding on one side, would be quite fragile and might break in a next release.
 !!!