Merge branch 'dev'

CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## Version 4.4.0
+
+### Changes
+
+- Passing positional arguments (besides `@pagy`) to all the helpers is deprecated and it will be supported only until pagy 5.0
+- All the helpers accept more optional keyword arguments, for example:
+  - `pagy*_nav(@pagy, pagy_id: 'my-id', link-extra: '...')`
+  - `pagy*_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...', steps: {...})`
+  - `pagy*_combo_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...')`
+  - `pagy_items_selector_js(pagy, pagy_id: 'my-id', item_name: '...', i18n_key: '...', link_extra: '...')`
+  - `pagy_info(@pagy, pagy_id: 'my-id', item_name: '...', i18n_key: '...')`
+  - `pagy_prev_link(@pagy, text: '...', link_extra: '...')`
+  - `pagy_next_link(@pagy, text: '...', link_extra: '...')`
+  - `pagy_link_proc(@pagy, link_extra: '...')`
+  - `pagy_url_for(pagy, page, absolute: nil)` (notice the inverted page/pagy order with the legacy`pagy_url_for(page, pagy, url=nil)`)
+- deprecated `:anchor` variable in favor of `:fragment`
+- Refactoring of rake tasks, tests, items extra, javascript helpers
+- Gems and documentation updates and fixes
+- Added standalone extra
+
 ## Version 4.3.0
 
 ### Changes

Gemfile

@@ -13,8 +13,7 @@ gem 'rake-manifest'
 group :test do
   gem 'codecov', require:  false
   gem 'minitest'
-  gem 'minitest-reporters'
-  gem 'rubocop', '~> 1.12'
+  gem 'rubocop'
   gem 'rubocop-minitest'
   gem 'rubocop-packaging'
   gem 'rubocop-performance'
@@ -35,8 +34,3 @@ group :performance do
   gem 'kalibera'
   gem 'memory_profiler'
 end
-
-# group :ide_development do
-#   gem 'debase'
-#   gem 'ruby-debug-ide'
-# end

Gemfile.lock

@@ -1,32 +1,25 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    ansi (1.5.0)
     ast (2.4.2)
     benchmark-ips (2.8.4)
-    builder (3.2.4)
     codecov (0.5.1)
       simplecov (>= 0.15, < 0.22)
     concurrent-ruby (1.1.8)
     docile (1.3.5)
-    i18n (1.8.9)
+    i18n (1.8.10)
       concurrent-ruby (~> 1.0)
     kalibera (0.1.1)
       memoist (~> 0.11.0)
       rbzip2 (~> 0.2.0)
     memoist (0.11.0)
     memory_profiler (1.0.0)
     minitest (5.14.4)
-    minitest-reporters (1.4.3)
-      ansi
-      builder
-      minitest (>= 5.0)
-      ruby-progressbar
     multi_json (1.15.0)
     mustermann (1.1.1)
       ruby2_keywords (~> 0.0.1)
     nio4r (2.5.7)
-    oj (3.11.2)
+    oj (3.11.5)
     parallel (1.20.1)
     parser (3.0.1.0)
       ast (~> 2.4.1)
@@ -41,7 +34,7 @@ GEM
     rbzip2 (0.2.0)
     regexp_parser (2.1.1)
     rexml (3.2.5)
-    rubocop (1.12.1)
+    rubocop (1.13.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
@@ -52,12 +45,12 @@ GEM
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.4.1)
       parser (>= 2.7.1.5)
-    rubocop-minitest (0.10.3)
-      rubocop (>= 0.87, < 2.0)
+    rubocop-minitest (0.11.1)
+      rubocop (>= 0.90, < 2.0)
     rubocop-packaging (0.5.1)
       rubocop (>= 0.89, < 2.0)
-    rubocop-performance (1.10.1)
-      rubocop (>= 0.90.0, < 2.0)
+    rubocop-performance (1.11.0)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     rubocop-rake (0.5.1)
       rubocop
@@ -93,13 +86,12 @@ DEPENDENCIES
   kalibera
   memory_profiler
   minitest
-  minitest-reporters
   oj
   puma
   rack
   rake
   rake-manifest
-  rubocop (~> 1.12)
+  rubocop
   rubocop-minitest
   rubocop-packaging
   rubocop-performance
@@ -109,4 +101,4 @@ DEPENDENCIES
   sinatra-contrib
 
 BUNDLED WITH
-   2.2.3
+   2.2.15

README.md

@@ -19,6 +19,8 @@ Pagy is the ultimate pagination gem that outperforms the others in each and ever
 - Updating `pagy` from `3.0+` to `4.0+` requires a single renaming in your code, but only if it uses the `searchkick` or the `elasticsearch_rails` extras (see the [Changelog](CHANGELOG.md))
 - Added the docker development environment to ease contributions
 - Big code restyling following ruby 3.0 syntax and cops; the code is simpler, more readable and verbose with yet improved performance.
+- All the public helpers accept optional keyword arguments (see the [Changelog](CHANGELOG.md#version-440))
+- New [standalone extra](http://ddnexus.github.io/pagy/extras/standalone) to use pagy without any request object, nor Rack environment/gem, nor any defined `params` method, even in the irb/rails console without any app or config.
 
 ## Comparison with other gems
 
@@ -125,6 +127,7 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 - [i18n](http://ddnexus.github.io/pagy/extras/i18n): Use the `I18n` gem instead of the pagy-i18n implementation
 - [items](http://ddnexus.github.io/pagy/extras/items): Allow the client to request a custom number of items per page with an optional selector UI
 - [overflow](http://ddnexus.github.io/pagy/extras/overflow): Allow for easy handling of overflowing pages
+- [standalone](http://ddnexus.github.io/pagy/extras/standalone): Use pagy without any request object, nor Rack environment/gem, nor any defined `params` method, even in the irb/rails console without any app or config.
 - [support](http://ddnexus.github.io/pagy/extras/support): Extra support for features like: incremental, auto-incremental and infinite pagination
 - [trim](http://ddnexus.github.io/pagy/extras/trim): Remove the `page=1` param from the first page link
 

docs/_layouts/default.html

@@ -121,6 +121,7 @@ <h1 id="site-title">{{ site.title | default: site.github.repository_name }}
       <a href="{{ site.baseurl }}/extras/navs"><p class="indent1" {% if page.title == 'Navs' %}id="active"{% endif %} >Navs</p></a>
       <a href="{{ site.baseurl }}/extras/searchkick"><p class="indent1" {% if page.title == 'Searchkick' %}id="active"{% endif %} >Searchkick</p></a>
       <a href="{{ site.baseurl }}/extras/semantic"><p class="indent1" {% if page.title == 'Semantic' %}id="active"{% endif %} >Semantic</p></a>
+      <a href="{{ site.baseurl }}/extras/standalone"><p class="indent1" {% if page.title == 'Standalone' %}id="active"{% endif %} >Standalone</p></a>
       <a href="{{ site.baseurl }}/extras/support"><p class="indent1" {% if page.title == 'Support' %}id="active"{% endif %} >Support</p></a>
       <a href="{{ site.baseurl }}/extras/tailwind"><p class="indent1" {% if page.title == 'Tailwind' %}id="active"{% endif %} >Tailwind</p></a>
       <a href="{{ site.baseurl }}/extras/trim"><p class="indent1" {% if page.title == 'Trim' %}id="active"{% endif %} >Trim</p></a>

docs/api/frontend.md

@@ -22,8 +22,8 @@ end
 use some of its method in some view:
 
 ```erb
-<%== pagy_nav(@pagy) %>
-<%== pagy_info(@pagy) %>
+<%== pagy_nav(@pagy, ...) %>
+<%== pagy_info(@pagy, ...) %>
 ```
 
 ## Methods
@@ -32,43 +32,51 @@ All the methods in this module are prefixed with the `"pagy_"` string in order t
 
 Please, keep in mind that overriding any method is very easy with Pagy. Indeed you can do it right where you are using it: no need of monkey-patching or tricky gymmickry.
 
-### pagy_nav(pagy)
+### pagy_nav(pagy, ...)
 
 This method takes the Pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example:
 
 ```erb
-<%== pagy_nav(@pagy) %>
+<%== pagy_nav(@pagy, ...) %>
 ```
 
-The `nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.
+The method accepts also a couple of optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim string to the `a` tag (e.g. `'data-remote="true"'`)
+
+The `nav.*` templates produce the same output, and can be used as an easier (but slower) way to customize it.
 
 See also [Using templates](../how-to.md#using-templates).
 
-### pagy_info(pagy, item_name=nil)
+### pagy_info(pagy, pagy_id: ..., item_name: ..., i18n_key: ...)
 
 This method provides the info about the content of the current pagination. For example:
 
 ```erb
-<%== pagy_info(@pagy) %>
+<%== pagy_info(@pagy, ...) %>
 ```
 
 Will produce something like:
 
-Displaying items <b>476-500</b> of <b>1000</b> in total
-
-or, if you use the `:i18n_key` variable a custom/collection-specific output:
+<span>Displaying items <b>476-500</b> of <b>1000</b> in total</span>
 
-Displaying Products <b>476-500</b> of <b>1000</b> in total
+The method accepts also a few optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `span` tag wrapping the info
+- `:item_name` an already pluralized string that will be used in place of the default `item/items`
+- `:i18n_key` the key to lookup in a dictionary
 
-You can also overwrite the `item_name` entirely by passing an already pluralized string directly to the helper:
+Notice the `:i18n_key` can be passed also to the constructor or be a less useful global variable (i.e. `VARS[:i18n_key]`
 
 ```erb
-<%== pagy_info(@pagy, 'Widget'.pluralized(@pagy.count) %>
+<%== pagy_info(@pagy, item_name: 'Product'.pluralize(@pagy.count) %>
+<%== pagy_info(@pagy, i18n_key: 'activerecord.model.product' %>
 ```
 
+Displaying Products <b>476-500</b> of <b>1000</b> in total
+
 _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_
 
-### pagy_url_for(page, pagy)
+### pagy_url_for(pagy, page, absolute: nil)
 
 This method is called internally in order to produce the url of a page by passing it its number. For standard usage it works out of the box and you can just ignore it.
 
@@ -149,8 +157,14 @@ If you need to add some HTML attribute to the page links, you can pass some extr
     link.call(page_number, 'aria-label="my-label"')
     #=> <a href="...?page=2" data-remote="true" class="page-link" aria-label="my-label">2</a>
     ```
-**WARNING**: we use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
-Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated HTML attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first)
+
+#### CAVEATS
+
+We use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
+
+Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated HTML attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first).
+
+Specifically do not add a `class` attribute that will end up in the `pagy_bootstrap_nav_js`, `pagy_semantic_nav_js` and `pagy_semantic_combo_nav_js`, which define already their own.
 
 ### pagy_t(key, vars={})
 

docs/api/javascript.md

@@ -22,9 +22,11 @@ All the `pagy*_js` helpers produce/render their component on the client side. Th
 
 Load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file, and run `Pagy.init()` on window-load and eventually on [AJAX-load](#using-ajax).
 
-**CAVEATS**
-- If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it.
-- See also [Preventing crawlers to follow look-alike links](../how-to.md#preventing-crawlers-to-follow-look-alike-links)
+### CAVEATS
+
+If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it.
+
+See also [Preventing crawlers to follow look-alike links](../how-to.md#preventing-crawlers-to-follow-look-alike-links)
 
 ### Add the oj gem
 
@@ -85,7 +87,7 @@ import './pagy.js.erb'
 
 - You may want to use `turbolinks:load` if your app uses turbolinks despite webpacker
 - or you may want just `export { Pagy }` from the `pagy.js.erb` file and import and use it somewhere else.
-- You may want to expose the `Pagy` namespace, if you need it available elsewhere (e.g. in js.erb templates):
+- or you may want to expose the `Pagy` namespace, if you need it available elsewhere (e.g. in js.erb templates):
     ```js
     global.Pagy = Pagy
     ```
@@ -169,7 +171,7 @@ The `:steps` is an optional non-core variable used by the `pagy*_nav_js` navs. I
 
 You can set the `:steps` as a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width.
 
-As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance.
+As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance, or even pass it to the `pagy*_nav_js` helper as an optional keyword argument.
 
 For example:
 
@@ -182,7 +184,10 @@ pagy, records = pagy(collection, steps: { 0 => [2,3,3,2], 540 => [3,5,5,3], 720
 
 # or use the :size as any static pagy*_nav
 pagy, records = pagy(collection, steps: false )
-
+```
+```erb
+or pass it to the helper
+<%== pagy_nav_js(@pagy, steps: {...}) %> 
 ```
 
 The above statement means that from `0` to `540` pixels width, Pagy will use the `[2,3,3,2]` size, from `540` to `720` it will use the `[3,5,5,3]` size and over `720` it will use the `[5,7,7,5]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section).
@@ -250,21 +255,32 @@ require 'pagy/extras/uikit'
 Use the `pagy*_combo_nav_js` helpers in any view:
 
 ```erb
-<%== pagy_combo_nav_js(@pagy) %>
-<%== pagy_bootstrap_combo_nav_js(@pagy) %>
-<%== pagy_bulma_combo_nav_js(@pagy) %>
-<%== pagy_foundation_combo_nav_js(@pagy) %>
-<%== pagy_materialize_combo_nav_js(@pagy) %>
-<%== pagy_semantic_combo_nav_js(@pagy) %>
+<%== pagy_combo_nav_js(@pagy, ...) %>
+<%== pagy_bootstrap_combo_nav_js(@pagy, ...) %>
+<%== pagy_bulma_combo_nav_js(@pagy, ...) %>
+<%== pagy_foundation_combo_nav_js(@pagy, ...) %>
+<%== pagy_materialize_combo_nav_js(@pagy, ...) %>
+<%== pagy_semantic_combo_nav_js(@pagy, ...) %>
 ```
 
 ## Methods
 
-### *_nav_js(pagy, ...)
+### pagy*_nav_js(pagy, ...)
+
+The method accepts also a few optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim string to the `a` tag (e.g. `'data-remote="true"'`)
+- `:steps` the [:steps](#steps) variable
+
+**CAVEATS**: the `pagy_bootstrap_nav_js` and `pagy_semantic_nav_js` assign a class attribute to their links, so do not add anoter class attribute with the `:link_extra`. That would be illegal HTML and ignored by most browsers.
+
+### pagy*_combo_nav_js(pagy, ...)
 
-All `*_nav_js` methods can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id generation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `*_js` call in the same line for the same file.
+The method accepts also a couple of optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim string to the `a` tag (e.g. `'data-remote="true"'`)
 
-**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.
+**CAVEATS**: the `pagy_semantic_combo_nav_js` assigns a class attribute to its links, so do not add another class attribute with the `:link_extra`. That would be illegal HTML and ignored by most browsers.
 
 # Using AJAX
 

docs/api/pagy.md

@@ -81,15 +81,15 @@ They are all integers:
 
 ### Other Variables
 
-| Variable      | Description                                                                                                                                                                                      | Default            |
-|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------|
-| `:size`       | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]`        |
-| `:page_param` | the name of the page param name used in the url. _(see [Customizing the page param](../how-to.md#customizing-the-page-param))_                                                                   | `:page`            |
-| `:params`     | the arbitrary param hash to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_                                                                                | `{}`               |
-| `:anchor`     | the arbitrary anchor string (including the "#") to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_                                                         | `""`               |
-| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [Customizing the link attributes](../how-to.md#customizing-the-link-attributes))_    | `""`               |
-| `:i18n_key`   | the i18n key to lookup the `item_name` that gets interpolated in a few helper outputs _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_                                | `"pagy.item_name"` |
-| `:cycle`      | enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page                                                                                    | `false`            |
+| Variable       | Description                                                                                                                                                                                      | Default            |
+|:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------|
+| `:size`        | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]`        |
+| `:page_param`  | the name of the page param name used in the url. _(see [Customizing the page param](../how-to.md#customizing-the-page-param))_                                                                   | `:page`            |
+| `:params`      | the arbitrary param hash to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_                                                                                | `{}`               |
+| `:fragment`    | the arbitrary fragment string (including the "#") to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_                                                       | `""`               |
+| `:link_extra`  | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [Customizing the link attributes](../how-to.md#customizing-the-link-attributes))_    | `""`               |
+| `:i18n_key`    | the i18n key to lookup the `item_name` that gets interpolated in a few helper outputs _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_                                | `"pagy.item_name"` |
+| `:cycle`       | enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page                                                                                    | `false`            |
 
 There is no specific validation for non-instance variables.