Merge branch 'dev'

.github/ISSUE_TEMPLATE/Code.yml

@@ -19,7 +19,7 @@ body:
     attributes:
       label: 👀 Before submitting...
       options:
-        - label: I upgraded to pagy version 8.5.0
+        - label: I upgraded to pagy version 8.6.0
           required: true
         - label: I searched through the [Documentation](https://ddnexus.github.io/pagy/)
           required: true

.github/latest_release_body.md

@@ -4,20 +4,14 @@
 - New `:max_pages` variable to limit the pagination regardless the actual count
 - Better frontend helpers
 - The `foundation`, `materialize`, `semantic` and `uikit` CSS extras have been discontinued and will be removed in v9 (See the [details](https://github.com/ddnexus/pagy/discussions/672#discussioncomment-9212328))
+- Deprecate the legacy nav bar, add features to the default faster nav bar series
 - See the [CHANGELOG](https://ddnexus.github.io/pagy/changelog) for possible breaking changes
 
-### Changes in 8.5.0
+### Changes in 8.6.0
 
 <!-- changes start -->
-- Improve pagy playground launcher
-- Refactor calendar class structure
-- Remove automatic skipping of bundle install in playground apps
-- Update ruby calendar test
-- Update cypress calendar test
-- Refactor calendar test environment to use activerecord
-- Add code for calendar counts
-- Remove redundant Warning
-- Convert calendar.ru to calendar_rails.ru
+- Add translated pluralized aria_label.nav for "ar" locale (close #577)
+- Deprecate the legacy bar. Insert first and last pages and gaps when needed into the simple bar
 <!-- changes end -->
 
 [CHANGELOG](https://ddnexus.github.io/pagy/changelog)

CHANGELOG.md

@@ -27,8 +27,15 @@ If you upgrade from version `< 8.0.0` see the following:
   - `pagy-module.js`: use `pagy.mjs`
   - `pagy-dev.js`: use the `pagy.min.js`with the `pagy.min.js.map`
   - `pagy-module.d.ts`: use `pagy.d.ts`
+- The Array type for the `:size` (e.g. `size: [1, 4, 4, 1]`) that generates the classic bar. Use the `:size` set to an integer 
+  with the `gaps: true` variable (which are the default since 8.4.6). If a legacy bar it will remain REALLY a requirement, add `require 'pagy/extras/size` to your `pagy.rb` initalizer for smooth upgrades. (see [size extra](https://ddnexus.github.io/pagy/docs/extras/size))
 <hr>
 
+## Version 8.6.0
+
+- Add translated pluralized aria_label.nav for "ar" locale (close #577)
+- Deprecate the legacy bar. Insert first and last pages and gaps when needed into the simple bar
+
 ## Version 8.5.0
 
 - Improve pagy playground launcher

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: gem
   specs:
-    pagy (8.5.0)
+    pagy (8.6.0)
 
 GEM
   remote: https://rubygems.org/

docs/api/countless.md

@@ -31,16 +31,7 @@ In this class the `:count` variable is always `nil`, hence some feature that dep
 The nav bar links after the current page cannot be fully displayed because a couple of items of the `:size` array depends on
 the `count`, so they have some limitations.
 
-Regardless the actual `:size` value:
-
-- `vars[:size][2]` is capped at 1 (we know only if the next page exists)
-- `vars[:size][3]` is set to 0 (we don't know the total pages)
-
-A few examples:
-
-- `[1,4,4,1]` would be treated like `[ 1,4,1,0]`
-- `[1,4,3,4]` would be treated like `[ 1,4,1,0]`
-- `[1,4,0,0]` would be treated like `[ 1,4,0,0]`
+Regardless the actual `:size` value we know only if the next page exists and we don't know the total pages
 
 The `series` method reflects on the above.
 

docs/api/javascript/navs.md

@@ -64,12 +64,12 @@ For example:
 
 ```ruby pagy.rb (initializer)
 # globally
-Pagy::DEFAULT[:steps] = { 0 => 5, 540 => [3, 5, 5, 3], 720 => [5, 7, 7, 5] }
+Pagy::DEFAULT[:steps] = { 0 => 5, 540 => 7, 720 => 9 }
 ```
 
 ```ruby Controller
 # or for a single instance
-pagy, records = pagy(collection, steps: { 0 => 5, 540 => [3, 5, 5, 3], 720 => [5, 7, 7, 5] })
+pagy, records = pagy(collection, steps: { 0 => 5, 540 => 7, 720 => 9 })
 
 # or use the :size as any static pagy*_nav
 pagy, records = pagy(collection, steps: false)
@@ -81,7 +81,7 @@ or pass it to the helper
 ```
 
 The above statement means that from `0` to `540` pixels width, Pagy will use the `5` size (originating a simple nav without gaps),
-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`
+from `540` to `720` it will use the `7` size and over `720` it will use the `9` size. (Read more about the `:size`
 variable in the [How to control the page links](/docs/how-to#control-the-page-links) section).
 
 !!!primary :steps must contain `0` width

docs/api/pagy.md

@@ -91,11 +91,10 @@ The nav helpers basically loop through this array and render the correct item by
 That is self-contained, simple and efficient.
 
 !!!primary
-This method returns an empty array if the passed `size` (i.e. the `:size` variable) is set to an empty `Array`. Useful to
-totally skip the generation of page links in the frontend.
+This method returns an empty array if the `:size` variable is set to `0`. Useful to totally skip the generation of page links in the frontend.
 
-It can also return a simpler array without gaps if the passed `:size` is a single positive `Integer`. It may be a faster and
-cleaner solution very useful in certain contexts (see the [Simple Nav](/docs/how-to.md#simple-nav))
+It can also return a simpler array without gaps if the passed `:size` is a single positive `Integer` and the `:ends` variable set to `false`.
+!!!
 
 ==- `label`
 
@@ -135,6 +134,7 @@ number `1`. For performance reasons, only the instance variables get validated.
 | `:count`         | The total count of the collection to paginate (mandatory argument)                                                                                                                    | `nil`   |
 | `:count_args`    | The arguments passed to the `collection.count`. You may want to set it to `[]` in ORMs different than ActiveRecord                                                                    | [:all]  |
 | `:cycle`         | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page                                                                         | `false` |
+| `:ends`          | Insert the first and last page into the series, plus the `:gap`s when needed. Ignored with `size < 7`.                                                                                | `7`     |
 | `:fragment`      | The arbitrary fragment string (including the "#") to add to the url. _(see [Customize the params](/docs/how-to.md#customize-the-params))_                                             | `nil`   |
 | `:items`         | The requested number of items for the page                                                                                                                                            | `20`    |
 | `:jsonapi`       | Enable `jsonapi` compliance of the pagy query params                                                                                                                                  | `false` |
@@ -144,7 +144,7 @@ number `1`. For performance reasons, only the instance variables get validated.
 | `:page_param`    | The name of the page param name used in the url. _(see [Customize the page param](/docs/how-to.md#customize-the-page-param))_                                                         | `:page` |
 | `:params`        | It can be a `Hash` of params to add to the URL, or a `Proc` that can edit/add/delete the request params _(see [Customize the params](/docs/how-to.md#customize-the-params))_          | `nil`   |
 | `:request_path`  | Allows overriding the `request.path` for pagination links. Pass the path only (not the absolute url). _(see [Pass the request path](/docs/how-to.md#pass-the-request-path))_          | `nil`   |
-| `:size`          | The size of the page links to show: can be an array of 4 items or the integer of the total page size. _(see also [Control the page links](/docs/how-to.md#control-the-page-links))_   | `7`     |
+| `:size`          | The size of the page links to show _(see also [Control the page links](/docs/how-to.md#control-the-page-links))_                                                                      | `7`     |
 
 !!!
 Extras may add and document their own variables
@@ -192,7 +192,7 @@ Which means:
 - there is always a `page` #`1` in the pagination, even if it's empty
 - `last` is always at least `1`
 - the `series` array contains always at least the page #`1`, which for a single page is also the current page, thus a string.
-  With `size: []` the `series` method returns `[]`
+  With `size: 0` the `series` method returns `[]`
 - `in`, `from` and `to` of an empty page are all `0`
 - `prev` and `next` of a single page (not necessary an empty one) are both `nil` (i.e. there is no other page)
 
@@ -206,9 +206,9 @@ constructor is not valid.
 
 ```ruby
 rescue Pagy::VariableError => e
-e.pagy #=> the pagy object that raised the exception
-e.variable #=> the offending variable symbol (e.g. :page)
-e.value #=> the value of the offending variable (e.g -3)
+  e.pagy     #=> the pagy object that raised the exception
+  e.variable #=> the offending variable symbol (e.g. :page)
+  e.value    #=> the value of the offending variable (e.g -3)
 end
 ```
 

docs/extras/pagy.md

@@ -109,7 +109,7 @@ supports navbar links (see also [Pagy::Countless](/docs/api/countless.md) for mo
 
 ### Navless/incremental
 
-If you don't need the navbar you can just set the `:size` variable to an empty value and the page links will be skipped from the
+If you don't need the navbar you can just set the `:size` variable to [0] and the page links will be skipped from the
 rendering. That works with `Pagy` and `Pagy:Countless` instances. All the `*nav` helpers will render only the `prev` and `next`
 links/buttons, allowing for a manual incremental pagination.
 

docs/extras/size.md

@@ -0,0 +1,70 @@
+---
+title: Size
+image: none
+categories:
+- Extra
+---
+
+# Size Extra
+
+Enable the Array type for the `:size` variable (e.g. `size: [1,4,4,1]`) that generates the legacy nav bar.
+
+!!!danger Use only if REALLY required!
+The behavior of the legacy nav bar was taken straight from WillPaginate and kaminari: it's ill-concieved and complicates the 
+experience of devs and users.
+
+The legacy bar grows in size from different ends depending on the current page position and its proximity to the start or end 
+pages. That changes during navigation are quite unexpected for both devs and users.
+
+Devs have a hard time predicting the real estate occupied by the bar in their layouts, and users have an UI that constantly 
+moves its elements around during navigation.
+
+!!!success
+Use the default pagy [fast nav](../how-to/#fast-nav) bar for a stable UI and a much better experience!
+!!!
+
+## Synopsis
+
+```ruby pagy.rb (initializer)
+require 'pagy/extras/size'
+```
+
+```ruby Controller (action)
+# generates a legacy bar  
+pagy, records = pagy(collection, size: [1, 4, 4, 1])
+pagy.series
+#=> [1, :gap, 6, 7, 8, 9, "10", 11, 12, 13, 14, :gap, 50]
+
+# the faster bar is still available if you use the pagy default
+pagy, records = pagy(collection)
+pagy.series
+#=> [1, :gap, 9, "10", 11, :gap, 50]
+
+# or explicitly using an integer
+pagy, records = pagy(collection, size: 9)
+pagy.series
+#=> [1, :gap, 8, 9, "10", 11, 12, :gap, 50]
+```
+
+##  Concept and usage
+
+Besides the regular integer value generating the fast bar, you can set the `:size` variable to an array of 4 integers in order to specify which and how many page links to show.
+
+For example: `[1,4,4,1]` means that you will get `1` initial page, `4` pages before the current page, `4` pages after the current page, and `1` final page.
+
+As usual you can set the `:size` variable as a global default by using the `Pagy::DEFAULT` hash or pass it directly to the 
+`pagy` method.
+
+The navigation links will contain the number of pages set in the variables:
+
+`size[0]`...`size[1]` current page `size[2]`...`size[3]` - e.g.:
+
+```ruby
+pagy, records = pagy(collection, size: [3, 4, 4, 3])
+pagy.series
+#=> [1, 2, 3, :gap, 6, 7, 8, 9, "10", 11, 12, 13, 14, :gap, 48, 49, 50]
+```
+
+As you can see by the result of the `series` method, you get 3 initial pages, 1 `:gap` (series interrupted), 4 pages before the current page, the current `:page` (which is a string), 4 pages after the current page, another `:gap` and 3 final pages.
+
+You can easily try different options (also asymmetrical) in a console by changing the `:size`. Just check the `series` array to see what it contains when used in combination with different core variables.

docs/how-to.md

@@ -44,14 +44,15 @@ See also a couple of extras that handle the `:items` in some special way:
 You can control the number and position of the page links in the navigation through the `:size` variable or override the
 `series` method.
 
-==- Simple nav
+==- Fast nav
 
-You can set the `:size` variable to a single positive Integer to represent the total number of page links rendered. The current
+You can set the `:size` variable to an Integer to represent the total number of bar slots rendered. The current
 page will be placed as centered as possible in the series.
 
 For example:
 
 ```ruby
+# size < 7
 pagy = Pagy.new(count: 1000, page: 10, size: 5)
 pagy.series
 #=> [8, 9, "10", 11, 12]
@@ -60,46 +61,48 @@ pagy.series
 #=> [1, "2", 3, 4, 5]
 pagy = Pagy.new(count: 1000, page: 99, size: 5)
 pagy.series
-#=> [96, 97, 98, "99", 100]
-```
-
-Setting the `:size` variable as a single integer has a few advantages over the classic way. It uses a simpler and faster
-algorithm, the series length is more constant, cleaner and less confusing to the user. On the other hand it does not allow the
-user to jump to the first or last page of a long series, which may or may not be a limitation. For example: with a navigation
-using `Pagy::Countless` or `Calendar` it is a clear advantage.
-
-==- Classic nav
-
-You can set the `:size` variable to an array of 4 integers in order to specify which and how many page links to show.
+#=> [96, 97, 98, "99", 100] 
 
-The default is `[1,4,4,1]`, which means that you will get `1` initial page, `4` pages before the current page, `4` pages after the
-current page, and `1` final page.
-
-As usual you can set the `:size` variable as a global default by using the `Pagy::DEFAULT` hash or pass it directly to the `pagy`
-method.
-
-The navigation links will contain the number of pages set in the variables:
-
-`size[0]`...`size[1]` current page `size[2]`...`size[3]` - e.g.:
+# size >= 7 (first, last and gap added)
+pagy = Pagy.new(count: 1000, page: 10, size: 7)
+pagy.series
+#=> [1, :gap 9, "10", 11, :gap, 100]
+pagy = Pagy.new(count: 1000, page: 2, size: 7)
+pagy.series
+#=> [1, "2", 3, 4, 5, :gap, 100]
+pagy = Pagy.new(count: 1000, page: 99, size: 7)
+pagy.series
+#=> [1, :gap, 96, 97, 98, "99", 100] 
 
-```ruby
-pagy = Pagy.new count: 1000, page: 10, size: [3, 4, 4, 3] # etc
+# size >= 7; ends: false (no ends added)
+pagy = Pagy.new(count: 1000, page: 10, size: 7, ends: false)
+pagy.series
+#=> [7, 8, 9, "10", 11, 12, 13]
+pagy = Pagy.new(count: 1000, page: 2, size: 7, ends: false)
 pagy.series
-#=> [1, 2, 3, :gap, 6, 7, 8, 9, "10", 11, 12, 13, 14, :gap, 48, 49, 50]
+#=> [1, "2", 3, 4, 5, 6, 7]
+pagy = Pagy.new(count: 1000, page: 99, size: 7, ends: false)
+pagy.series
+#=> [94, 95, 96, 97, 98, "99", 100]
 ```
 
-As you can see by the result of the `series` method, you get 3 initial pages, 1 `:gap` (series interrupted), 4 pages before the
-current page, the current `:page` (which is a string), 4 pages after the current page, another `:gap` and 3 final pages.
+Setting the `:size` variable as a single integer has quite a few advantages over the legacy way. It uses a simpler and faster 
+algorithm and the series length is more constant, it's cleaner and less confusing to the user. By default, if the size is at 
+least `7`, it will insert the first and last pages as first and last links in the bar, also adding the `:gap`s accordingly.
+
+If you want to remove the first, last and gaps slots and show only a series of contiguous pages, you can set the `:ends` 
+variable to `false`: hat is a clear advantage with nav bars using `Countless` or `Calendar`.
+
+==- Legacy nav
 
-You can easily try different options (also asymmetrical) in a console by changing the `:size`. Just check the `series` array to
-see what it contains when used in combination with different core variables.
+See the [size extra](extras/size.md)
 
 ==- Skip the page links
 
-If you want to skip the generation of the page links, just set the `:size` variable to an empty array:
+If you want to skip the generation of the page links, just set the `:size` variable to `0`:
 
 ```ruby
-pagy = Pagy.new count: 1000, size: [] # etc
+pagy = Pagy.new count: 1000, size: 0 # etc
 pagy.series
 #=> []
 ```
@@ -771,7 +774,7 @@ Here are some tips that will help choosing the best way to use Pagy, depending o
 
 ==- Consider the nav_js
 
-If you need the classic pagination bar with links and info, then you have a couple of choices, depending on your environment:
+If you need the pagination bar with links and info, then you have a couple of choices, depending on your environment:
 
 - Add the `oj` gem to your gemfile and use any `pagy*_nav_js` helper _(see [Javascript](api/javascript.md))_. That uses client
   side rendering and it is faster and lighter than using any `pagy*_nav` helper _(40x faster, 36x lighter and 1,410x more

docs/migration-guide.md

@@ -64,7 +64,8 @@ Kaminari.configure do |config|
 end
 
 Pagy::DEFAULT[:items] = 10
-Pagy::DEFAULT[:size]  = [5, 4, 4, 5]
+require 'pagy/extras/size'           # Provide legacy support of old navbars like the above
+Pagy::DEFAULT[:size]  = [5, 4, 4, 5] # Array parsed by the extra above
 ```
 
 Remove all the legacy settings of the old gem(s) and uncomment and edit the new settings in the `pagy.rb` initializer _(see