concerns_on_rails 1.28.0 → 1.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f9aef0d5f95ffc23ef6213d5d95ea872a6146763d488a287a334db8be68b922
-  data.tar.gz: b364f4276149a31b1ce1f6efaf170435900f34188eb358035c10020567e8b51d
+  metadata.gz: 00337457f7ea35fd2e02bb74bcb4031208109536946b448706104a9e031bd9ea
+  data.tar.gz: 3bfc8749303d212e51d98d8dd7fa4323888e3d984444c768695d5c290df311a3
 SHA512:
-  metadata.gz: 025306bb013a418c8051db996ddd0fe6f2bf7ac7f657d22335639b5bcceecff8416e85c66ebde92a357656eeaba90f51a2993fab23232267af105e823cf28934
-  data.tar.gz: b0d98d45a2b189b43985e5d5548c3b905a161f2aa0df9022d251a2788b62524360bc002d2981e7e9801a10e4b0f7aa4a7b1d6b0ee5adb4298edeef89a07a8467
+  metadata.gz: 50ea50c59f6b15978fe3f1cc86f03266998249bd4b17dc84b36ff6a717e9a57d0efba37f2e5648c58009761aeb2198f14368b2c20715c0bc40c246c1e7b5ee25
+  data.tar.gz: f6b8c7784e26ac3f5c8f14217e07cbe6d846ecab216fad6c61fb192bf06a18aa4484d80efb32fd82d625c683d917d9fb8c9b88724adcf2a11878fb0ea6a1f7e9

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.1 (2026-09-07)
+
+One additive Paginatable option (#89): `pagination_meta` can now publish the
+page window a pagination bar needs — first, last and N pages either side of the
+current page — instead of leaving every client to compute it from
+`total_pages`. Opt-in, controller-only, no extra query, and existing responses
+are byte-for-byte unchanged. 1314 examples, 0 failures.
+
+### Added
+- **Controllers::Paginatable**: `paginate_by window: 3` adds a `pages:` key to
+  `pagination_meta` — the first page, the last page, and N pages either side of
+  the current one, with the Symbol `:gap` standing in for each run left out
+  (`[1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100]`) — enough to render a
+  `1 … 44 45 46 [47] 48 49 50 … 100` bar straight from the meta Hash. Opt-in:
+  without `window:` the key is absent entirely (not `nil`), so no existing
+  meta Hash or serialized body changes shape, and `meta.key?(:pages)` is a
+  clean probe. The window is arithmetic over the `total` already counted, so it
+  costs no extra query on either the memoized `paginated` path or the fresh
+  `pagination_meta` one. A jump of exactly two pages is filled with the page it
+  would have hidden (`1 2 3`, never the wider `1 … 3`), and a `?page=` past the
+  last page windows around the last page as `rel="prev"` already does.
+  `window:` is validated at declaration — a non-negative Integer, or
+  `nil`/`false` to disable; `0` yields first, current and last only. Headers
+  and `Link` rels are unchanged: `pages:` is body-only by design. (#89)
+
+### Internal
+- `set_pagination_headers` no longer splats the memoized meta Hash, which
+  raised `unknown keyword: :pages` once that Hash could carry the window; the
+  four header values are passed explicitly.
+- README's advertised example counts were stale (1,160 and 1,303) and now read
+  1,314.
+
 ## 1.28.0 (2026-09-06)
 
 Pagination is the theme: the four-PR Paginatable stack (#40, #45, #62, #83)

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early — with a ready-to-paste `rails generate migration` hint when it doesn't
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,160 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,314 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -158,7 +158,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.26"
+gem "concerns_on_rails", "~> 1.28"
 ```
 
 Or pull the latest from GitHub:
@@ -1494,6 +1494,41 @@ paginate_by style: :jsonapi                                        # ?page[numbe
 paginate_by page_param: %i[paging page], per_page_param: %i[paging per]   # any nested path
 ```
 
+**Page window for a pagination bar**
+
+`window:` adds a `pages:` key to `pagination_meta` — the first page, the last page, and N pages
+either side of the current one, with `:gap` standing in for the runs left out. It is opt-in:
+without `window:` the key is absent entirely. No extra query either way — it is arithmetic over
+the total already counted.
+
+```ruby
+paginate_by per_page: 10, window: 3
+
+pagination_meta
+# => { total: 1000, page: 47, per_page: 10, total_pages: 100,
+#      pages: [1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100] }
+```
+
+Render it straight into a `1 … 44 45 46 [47] 48 49 50 … 100` bar:
+
+```erb
+<% pagination_meta[:pages].each do |page| %>
+  <%= page == :gap ? "…" : link_to(page, url_for(page: page)) %>
+<% end %>
+```
+
+| Situation | `pages:` |
+|-----------|----------|
+| `?page=47` of 100 | `[1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100]` |
+| `?page=2` of 100 | `[1, 2, 3, 4, 5, :gap, 100]` — no leading gap once the window reaches page 1 |
+| `?page=6` of 100 | `[1, 2, 3, 4, 5, 6, 7, 8, 9, :gap, 100]` — a one-page gap is filled, never `1 … 3` |
+| 5 pages total | `[1, 2, 3, 4, 5]` — the window spans everything |
+| empty collection | key absent |
+| `window: 0` | `[1, :gap, 47, :gap, 100]` — first, current and last only |
+
+`?page=` past the last page windows around the last page (as `rel="prev"` already does), and
+`window:` must be a non-negative Integer or `nil`/`false` — validated at declaration.
+
 **Response headers**: `X-Total-Count`, `X-Page`, `X-Per-Page`, `X-Total-Pages`, and an RFC 8288 `Link`
 header with `first` / `prev` / `next` / `last` URLs rebuilt from the current request (other query params
 preserved; `prev`/`next` only when such a page exists; nothing for an empty collection) — the GitHub
@@ -2122,9 +2157,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,303 examples)
+bundle exec rspec                               # run the test suite (1,314 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.0.gem      # install locally
+gem install ./concerns_on_rails-1.28.1.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -41,6 +41,9 @@ module ConcernsOnRails
         class_attribute :paginatable_per_page, default: DEFAULT_PER_PAGE
         class_attribute :paginatable_max_per_page, default: DEFAULT_MAX_PER_PAGE
         class_attribute :paginatable_link_header, default: true
+        # Half-width of the page window in `pagination_meta[:pages]`; nil = no
+        # window, and no `pages:` key at all.
+        class_attribute :paginatable_window, default: nil
         # Where page / per_page are read from — a path of param names (`["page"]`,
         # or `["page", "number"]` for JSON:API's page[number]).
         class_attribute :paginatable_page_param, default: %w[page].freeze
@@ -55,10 +58,11 @@ module ConcernsOnRails
         # Example:
         #   paginate_by per_page: 50, max_per_page: 500, link_header: false
         def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE, link_header: true,
-                        page_param: nil, per_page_param: nil, style: :flat)
+                        page_param: nil, per_page_param: nil, style: :flat, window: nil)
           self.paginatable_per_page = per_page.to_i
           self.paginatable_max_per_page = max_per_page.to_i
           self.paginatable_link_header = link_header ? true : false
+          self.paginatable_window = paginatable_window!(window)
           defaults = paginatable_style_params!(style)
           self.paginatable_page_param = paginatable_param_path!(:page_param, page_param || defaults[0])
           self.paginatable_per_page_param = paginatable_param_path!(:per_page_param, per_page_param || defaults[1])
@@ -75,6 +79,15 @@ module ConcernsOnRails
           end
         end
 
+        # nil / false disable the window (no `pages:` key). `0` is meaningful:
+        # first, current and last only.
+        def paginatable_window!(value)
+          return nil if value.nil? || value == false
+          return value if value.is_a?(Integer) && !value.negative?
+
+          raise ArgumentError, "#{LABEL}: window: must be a non-negative Integer or nil (got #{value.inspect})"
+        end
+
         # A name or a non-empty path of names, normalized to Strings.
         def paginatable_param_path!(option, value)
           path = Array(value)
@@ -117,8 +130,9 @@ module ConcernsOnRails
             source.limit(per_page).offset(offset)
           end
 
-        @paginatable_meta = { total: total, page: page, per_page: per_page, total_pages: total_pages }
-        set_pagination_headers(**@paginatable_meta)
+        @paginatable_meta =
+          paginatable_windowed(total: total, page: page, per_page: per_page, total_pages: total_pages)
+        set_pagination_headers(total: total, page: page, per_page: per_page, total_pages: total_pages)
         set_pagination_links(page: page, total_pages: total_pages)
         records
       end
@@ -134,12 +148,12 @@ module ConcernsOnRails
 
         total = paginatable_meta_total(collection, total)
         per_page = pagination_per_page
-        {
+        paginatable_windowed(
           total: total,
           page: pagination_page,
           per_page: per_page,
           total_pages: per_page.positive? ? (total.to_f / per_page).ceil : 0
-        }
+        )
       end
 
       private
@@ -228,6 +242,39 @@ module ConcernsOnRails
         { path.first.to_sym => nested }
       end
 
+      # Adds `pages:` to a meta Hash when `window:` is declared, and leaves the
+      # Hash untouched otherwise — the key is absent, never nil, so
+      # `meta.key?(:pages)` is a clean opt-in probe.
+      def paginatable_windowed(meta)
+        pages = paginatable_page_window(meta[:page], meta[:total_pages])
+        pages ? meta.merge(pages: pages) : meta
+      end
+
+      # First, last, and `window` pages either side of the current page, with
+      # :gap standing in for the runs left out — [1, :gap, 46, 47, 48, :gap, 100].
+      # Pure arithmetic over the total already counted: no extra query. A page
+      # past the last one windows around the last page, as `prev` already does.
+      def paginatable_page_window(page, total_pages)
+        window = self.class.paginatable_window
+        return nil if window.nil? || total_pages < 1
+
+        current = page.clamp(1, total_pages)
+        from = [current - window, 1].max
+        to = [current + window, total_pages].min
+        paginatable_insert_gaps(([1, total_pages] + (from..to).to_a).uniq.sort)
+      end
+
+      # A jump of exactly two pages is filled with the page it would have
+      # hidden — "1 2 3", never the wider "1 … 3"; anything longer collapses
+      # into one :gap.
+      def paginatable_insert_gaps(numbers)
+        numbers.each_cons(2).with_object([numbers.first]) do |(previous, current), result|
+          result << (previous + 1) if current - previous == 2
+          result << :gap if current - previous > 2
+          result << current
+        end
+      end
+
       def set_pagination_headers(total:, page:, per_page:, total_pages:)
         return unless respond_to?(:response) && response
 

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.28.0".freeze
+  VERSION = "1.28.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.28.0
+  version: 1.28.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack