plutonium 0.69.0 → 0.70.0

data/config/locales/en/ui.yml

@@ -66,6 +66,9 @@ en:
         result_count:
           one: "%{count} result"
           other: "%{count} results"
+        result_count_capped: "%{count}+ results"
+        capped_count: "%{count}+"
+        page_range: "Displaying %{item_name} %{from}-%{to}"
         selected_count: "%{count} selected"
         clear_selection: "Clear selection"
         no_bulk_actions: "No bulk actions available"

data/docs/blog/introducing-plutonium-dashboards.md

@@ -13,7 +13,7 @@ tags: [announcement, dashboards, charts]
 
 Every portal Plutonium generates opens on a Dashboard page that lists your resources with a record count each. Anything past that, the numbers and charts an admin actually opens the app to see, was yours to build: a controller action, some instance variables, a view. Plutonium 0.65 ships it. A dashboard is a Ruby class of cards, mounted with one line in your routes.
 
-![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/blog/dashboards-overview.png)
+![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/guides/dashboard-overview.png)
 
 ## What's in the box
 
@@ -99,7 +99,7 @@ The page response contains no query results. Each card renders as a lazy turbo f
 
 The browser fetches each frame as it scrolls into view, and the card's block runs in that request. The page paints at once, the cheap cards fill in first, and one expensive aggregate delays itself and nothing else.
 
-![The same dashboard before its frames have loaded: every card is a grey skeleton except the Conversion metric, which is already showing 12.5%](/images/blog/dashboards-loading.png)
+![The same dashboard before its frames have loaded: every card is a grey skeleton except the Conversion metric, which is already showing 12.5%](/images/guides/dashboard-loading.png)
 
 The Conversion card in that screenshot is declared `lazy: false`, which makes it inline: its block runs in the page request and the finished card is part of the page response, with no frame, no skeleton and no second request. The price is that the page waits for it. Use it for a number cheap enough that a round trip costs more than the query, and leave everything else lazy. An inline card never refreshes, since there is no frame to reload, and in development and test an exception in its block fails the whole page rather than one frame.
 
@@ -131,7 +131,7 @@ end
 
 In development and test a card that raises, raises, and you fix the query. In production the card shows a short notice in place of its body and the rest of the dashboard is untouched.
 
-![A dashboard where the Revenue card shows a red "This card could not be loaded." notice while the metrics and the signups chart around it render normally](/images/blog/dashboards-card-error.png)
+![A dashboard where the Revenue card shows a red "This card could not be loaded." notice while the metrics and the signups chart around it render normally](/images/guides/dashboard-card-error.png)
 
 The failure is written to the Rails log with the dashboard class, the card key and the top of the backtrace, and it is reported through `Rails.error`:
 
@@ -156,7 +156,7 @@ Series colours come from the `--pu-chart-1` to `--pu-chart-8` design tokens and
 
 Registered dashboards are grouped under a Dashboards item in the portal sidebar, with a link per dashboard. A dashboard mounted at the root is what the Home link opens, so it stays out of the group.
 
-![The portal's icon rail with the Dashboards item open, listing Overview and Content](/images/blog/dashboards-sidebar.png)
+![The portal's icon rail with the Dashboards item open, listing Overview and Content](/images/guides/dashboard-sidebar.png)
 
 If your portal has an ejected `_resource_sidebar.html.erb` from an earlier release, the [guide](/guides/dashboards#sidebar) has the block to add.
 

data/docs/blog/the-slowest-query-is-the-count.md

@@ -0,0 +1,109 @@
+---
+title: "Plutonium pagination: when the slowest query in your Rails admin is the count"
+titleTemplate: "Plutonium Blog"
+date: 2026-10-26
+description: An index page over fourteen million rows runs two queries, and an index only fixes one of them. Plutonium 0.70 lets a resource cap its COUNT(*) or skip it entirely.
+author: Stefan Froelich
+tags: [pagination, performance, postgres]
+---
+
+# Plutonium pagination: when the slowest query in your Rails admin is the count
+
+<BlogMeta />
+
+An admin index page in a production Plutonium app started returning 500s. The table behind it had about fourteen million rows, Postgres was cancelling the request at its 15 second statement timeout, and the page had never been slow before the table got big.
+
+The obvious culprit was real. The page sorts by `created_at` and the column had no index, so every load was a parallel sequential scan followed by a sort. Add the index and that query drops to milliseconds, because Postgres can walk the index backwards and stop after twenty rows.
+
+But an index page runs two queries, and the index only fixes one of them.
+
+## The second query
+
+Before Plutonium fetches the page of records, it counts them. The count feeds three things on the page: the footer ("Displaying Transactions 1-20 of 13742118 in total"), the result count above the table, and the numbered page links, which need to know where the last page is.
+
+```sql
+SELECT COUNT(*) FROM "transactions"
+```
+
+Rails strips the `ORDER BY` from a count, so the new index on `created_at` is no help here. And `COUNT(*)` on Postgres cannot read a stored total: rows carry their own visibility information, so the only way to know how many rows this transaction can see is to look at all of them. The best case is an index-only scan over the smallest index, which is still one entry per row. Fourteen million rows means seconds of work, on every page load, every filter change, and every click on "next".
+
+The total is also the least useful number on the page. Nobody reads "13742118" and does anything differently than they would with "more than ten thousand".
+
+## Cap it
+
+Plutonium 0.70 adds a `pagination` setting to the definition:
+
+```ruby
+class TransactionDefinition < ResourceDefinition
+  pagination count: 10_000
+end
+```
+
+With a cap, the count runs over a subquery with a `LIMIT`:
+
+```sql
+SELECT COUNT(*) FROM (SELECT 1 AS one FROM "transactions" LIMIT 10001) AS subquery_for_count
+```
+
+Postgres stops after 10,001 rows instead of fourteen million. The extra row is how Plutonium knows the total went past the cap: below it, the page shows the exact number; past it, the total reads "10000+".
+
+![A posts index capped at 100: the result count reads "100+ results", the footer reads "Displaying Posts 1-20 of 100+ in total", and the pager links pages 1 through 5](/images/blog/pagination-capped.png)
+
+The pager links pages up to the one holding row 10,000, and stops there. That is deliberate. A deep `OFFSET` has the same problem as the count, since the database reads and discards every skipped row, so page 500,000 of a transaction log was never a page anyone should be able to request.
+
+## Or skip it
+
+Some lists do not need a total at all. An audit log is read from the top, and the useful navigation is "older":
+
+```ruby
+class AuditLogDefinition < ResourceDefinition
+  pagination count: false
+end
+```
+
+No count query runs. The page fetches one more row than it shows, and that extra row decides whether there is a next page. The footer drops the "of N", and the pager offers previous, next, and the pages visited so far.
+
+![A countless pager on page 4: the footer reads "Displaying Posts 61-80" with no total, and the pager shows pages 1 through 5](/images/blog/pagination-countless.png)
+
+A list that fits on one page still shows its total, because the rows on the page are the whole set.
+
+## What a cap does not fix
+
+A capped count is cheap when lots of rows match, because the subquery fills its 10,001 slots quickly. It is no cheaper when few rows match.
+
+Say a "Pending" tab matches 400 rows and `status` has no index. The capped subquery still scans the whole table looking for a 10,001st row that does not exist, so it costs about what the full count did. The page query has the same problem: walking the `created_at` index backwards for twenty pending rows means stepping over every non-pending row on the way.
+
+The fix for that tab is an index on the filtered column, a partial one if a single value is the hot path. The cap removes the cost of counting rows you were never going to look at. It cannot remove the cost of finding the ones you are.
+
+## Deciding per request
+
+The definition sets a resource's default. When the right answer depends on the request, override `pagination_count` in the controller. It returns the same values the definition takes:
+
+```ruby
+class TransactionsController < ResourceController
+  private
+
+  def pagination_count
+    current_query_object.active_filter_descriptions.empty? ? false : 10_000
+  end
+end
+```
+
+Here the unfiltered list skips the count entirely, and a filtered one gets a capped total.
+
+## Defaults
+
+Nothing changes unless you ask. The global default is an exact count, set in the initializer alongside the rest of Plutonium's configuration:
+
+```ruby
+Plutonium.configure do |config|
+  config.pagination = {count: :exact}
+end
+```
+
+The "N+" wording and the countless range sentence are translation keys, so a localized app can override them like any other string.
+
+## Where to go next
+
+- [Definition › Pagination count](/reference/resource/definition#pagination-count): every value, the SQL each one runs, and the controller override.
+- [Performance](/guides/performance#counting-large-tables): counting large tables, alongside eager loading and the search fallback.

data/docs/guides/performance.md

@@ -91,6 +91,20 @@ It works without per-model configuration. Before adding it:
 
 [`ar_lazy_preload`](https://github.com/DmitryTsepelev/ar_lazy_preload) takes the same idea from the other end, preloading lazily on first access, with `ArLazyPreload.config.auto_preload = true` for automatic behaviour everywhere. Its docs warn that enabling it on an existing app can surface edge cases.
 
+## Counting large tables
+
+Each index page load counts the matching rows to show the total and link the last page. That `COUNT(*)` reads every matching row, and on a table with millions of rows it can take longer than the page of records it sits next to. An index on the sort column does not help it.
+
+Cap the count, or drop it, on the resources that need it:
+
+```ruby
+class TransactionDefinition < ResourceDefinition
+  pagination count: 10_000   # "10000+" past the cap
+end
+```
+
+A capped count is cheap when the filter matches many rows. A filter that matches few rows still scans for them, so index the columns your scopes and filters use. See [Definition › Pagination count](/reference/resource/definition#pagination-count).
+
 ## Work that does not belong in a request at all
 
 Eager loading fixes a page whose queries are wasteful. It does nothing for one that is simply doing too much work: archiving thousands of records, building a report, waiting on a third party.

data/docs/reference/configuration.md

@@ -59,6 +59,7 @@ Passing a version older than the earliest available raises rather than silently
 | Option | Default | Description |
 |--------|---------|-------------|
 | `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. The field set comes from the policy, so it is known before the collection loads. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
+| `pagination` | `{count: :exact}` | How index pages count their records. `count: :exact` runs a full `COUNT(*)`, an Integer counts at most that many rows (the total then reads "10000+"), `false` runs no count and shows previous/next only. Keys left out keep their defaults. Override per resource with `pagination`, see [Definition › Pagination count](./resource/definition#pagination-count). |
 | `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is a registered resource. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. Any other value raises `ArgumentError` rather than drawing the wrong route table for a typo. See [Nested resources](./tenancy/nested-resources#declaring-which-associations-get-routes). |
 | `default_currency_unit` | `nil` | Symbol used when rendering a currency value with no unit set on `has_cents` or the display. `nil` falls back to the i18n `number.currency.format.unit` when the locale defines one, otherwise no symbol. Set a literal like `"£"`, or `false` (or `""`) for no symbol application-wide. See [`has_cents`](./resource/model#has-cents) and [Currency fields](./ui/forms#currency-fields). |
 | `default_phone_country` | `nil` | Default country (ISO2, e.g. `"gh"`) for `as: :phone` inputs that set no `initial_country:`. `nil` leaves it to intl-tel-input, with no country preselected. Stored verbatim; `config.normalized_default_phone_country` returns it downcased, so `"GH"` and `"gh"` are interchangeable. See [Phone fields](./ui/forms#phone-fields). |

data/docs/reference/i18n.md

@@ -23,7 +23,7 @@ en:
       "false": "Off"
 ```
 
-Pagination is the one surface with its own dictionary. The info sentence, the per-page sentence and the nav aria labels come from [Pagy's](https://ddnexus.github.io/pagy/resources/i18n) locale files, which cover about thirty-five languages. Override a Pagy key by adding a file to `Pagy::I18n.pathnames`, not through Rails I18n.
+Pagination is the one surface with its own dictionary. The info sentence, the per-page sentence and the nav aria labels come from [Pagy's](https://ddnexus.github.io/pagy/resources/i18n) locale files, which cover about thirty-five languages. Override a Pagy key by adding a file to `Pagy::I18n.pathnames`, not through Rails I18n. The capped total (`plutonium.ui.table.capped_count`, "%{count}+") and the countless range sentence (`plutonium.ui.table.page_range`) are Plutonium keys, overridden through Rails I18n like any other.
 
 ## Switching locale
 

data/docs/reference/resource/definition.md

@@ -855,6 +855,41 @@ All three inherit to subclasses, so a portal-specific definition keeps its paren
 - **Interactions** (`Plutonium::Interaction::Base`) support the same settings, for interactive actions rendered as standalone pages.
 - **Wizards are configured separately**, via `Plutonium.configuration.wizards.width`. It defaults to `:md` independently of `default_page_width`, so widening resource pages leaves wizard steps where they are. Set both if you want them to match.
 
+## Pagination count
+
+The index page shows its total ("Displaying Posts 1-20 of 13,742 in total") and links every page, which takes a `COUNT(*)` on each load. On a table with millions of rows that count can take seconds. `pagination` sets how much counting a resource does:
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure { |config| config.pagination = {count: :exact} }   # the default
+
+class TransactionDefinition < ResourceDefinition
+  pagination count: 10_000
+end
+```
+
+| `count:` | Query | Total shown | Page links |
+|---|---|---|---|
+| `:exact` | `SELECT COUNT(*) FROM ...` | the exact total | every page |
+| an Integer | `SELECT COUNT(*) FROM (SELECT 1 FROM ... LIMIT 10001)` | exact up to the cap, then "10000+" | up to the page holding row 10,000 |
+| `false` | none: fetches one extra row to tell whether a next page exists | the page's range only, without "of N" | previous/next, plus the pages visited so far |
+
+A cap makes the count cheap when many rows match, because the subquery stops after `cap + 1` of them. It does not help a filter that matches few rows: the database still scans until it has found them all, so give that filter's column an index.
+
+Any other value raises `ArgumentError` at declaration. The setting inherits to subclasses, so a portal-specific definition keeps its parent's choice unless it sets its own.
+
+To choose per request, for example no count only while no filter is applied, override `pagination_count` in the controller. It returns the same values:
+
+```ruby
+class TransactionsController < ResourceController
+  private
+
+  def pagination_count
+    current_query_object.active_filter_descriptions.empty? ? false : 10_000
+  end
+end
+```
+
 ## File uploads
 
 ```ruby

data/docs/reference/ui/layouts.md

@@ -109,6 +109,19 @@ The sidebar/icon-rail navigation is built with `Phlexi::Menu::Builder` in the ej
     ) %>
 ```
 
+### Links pinned above the footer
+
+`footer_menu:` takes a second `Phlexi::Menu::Builder` whose items render between the scrolling nav and the pin button, so they stay in view however long the nav gets. Items render the same way as the main menu's:
+
+```erb
+<%= render Plutonium::UI::Layout::IconRail.new(
+      menu: main_menu,
+      footer_menu: Phlexi::Menu::Builder.new do |m|
+        m.item "Settings", url: settings_path, icon: Phlex::TablerIcons::Settings
+      end
+    ) %>
+```
+
 ### Per-item link attributes
 
 Any extra options you pass to `item` are spread straight onto the rendered `<a>`, so a menu entry can opt into `target`, `rel`, `data-*`, `aria-*`, etc. Useful for items that open in their own tab or drive a Stimulus/Turbo behavior:

data/gemfiles/rails_7.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.68.0)
+    plutonium (0.69.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -608,10 +608,10 @@ CHECKSUMS
   phlex-tabler_icons (0.3.0) sha256=67d80cc09c619646cff171a620fa805cb49543625c3586a947cd752d44d2858e
   phlexi-display (0.2.0) sha256=73e22d01e7204a3b94dcb21432477982bfa5162926c11bacd7d48930114236de
   phlexi-field (0.2.0) sha256=ecb509cc2c0e0559f52651cac8d5dd2fca4bda3878cb7343ea7b298c760e7bca
-  phlexi-form (0.14.4)
+  phlexi-form (0.14.4) sha256=f5409274dd8441789612d6bf06c9f905a1bc6e2b802620de794905cf4b9ad59b
   phlexi-menu (0.4.1) sha256=f6eeb1eb9597caadeee33a53f1520b3613a6ac616cf1e395e9d734a412895fb2
   phlexi-table (0.2.0) sha256=73bee135adbe73fcdb6fdd2672444373556dd9e6bba61e7b5b20ca8b7a1f822c
-  plutonium (0.68.0)
+  plutonium (0.69.0)
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85

data/gemfiles/rails_8.0.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.68.0)
+    plutonium (0.69.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)

data/gemfiles/rails_8.1.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.68.0)
+    plutonium (0.69.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)

data/lib/plutonium/configuration.rb

@@ -79,6 +79,22 @@ module Plutonium
     #   off globally here, or per controller via `auto_eager_load_collections?`.
     attr_accessor :auto_eager_load_collections
 
+    # @return [Hash] index-page pagination defaults. Definitions override per
+    #   resource with `pagination count: ...`.
+    #
+    #   `count:` is what the index pays to know its total:
+    #   - `:exact` (default): a full COUNT(*) on every page load
+    #   - an Integer: count at most that many rows; past it the total reads
+    #     "N+" and pages beyond the cap are out of range
+    #   - `false`: no COUNT query; previous/next navigation only
+    #
+    #   Keys left out keep their defaults.
+    attr_reader :pagination
+
+    def pagination=(value)
+      @pagination = Plutonium::Pagination::DEFAULTS.merge(Plutonium::Pagination.validate!(value)).freeze
+    end
+
     # @return [String, nil] the default country (ISO2 code, e.g. "gh") for phone
     #   (`as: :phone`) inputs that don't set their own `initial_country:`. `nil`
     #   (default) leaves it to the intl-tel-input library (no country preselected).
@@ -156,6 +172,7 @@ module Plutonium
       @navii_host_url = "https://api.navii.dev"
       @auto_eager_load_collections = true
       @default_page_width = :md
+      @pagination = {count: :exact}.freeze
       @nested_association_routes = :detected
     end
 

data/lib/plutonium/definition/base.rb

@@ -179,6 +179,28 @@ module Plutonium
         self.show_in_config = value
       end
 
+      # pagination — how the index page counts its records. Overrides
+      # `Plutonium.configuration.pagination` key by key, and inherits to
+      # subclasses like the other definition settings.
+      #
+      #   pagination count: 10_000   # count at most 10,000 rows, then "10000+"
+      #   pagination count: false    # no COUNT query; previous/next only
+      #   pagination count: :exact   # full COUNT(*) (the global default)
+      #
+      # See Plutonium::Pagination for the accepted values.
+      inheritable_config_attr :pagination
+
+      def self.pagination(**options)
+        return pagination_config if options.empty?
+
+        self.pagination_config = (pagination_config || {}).merge(Plutonium::Pagination.validate!(options)).freeze
+      end
+
+      # The global pagination settings with this definition's overrides applied.
+      def resolved_pagination
+        Plutonium.configuration.pagination.merge(self.class.pagination_config || {})
+      end
+
       # The model this definition describes — the inverse of the
       # `"#{resource_class}Definition"` lookup controllers do
       # (Plutonium::Resource::Controller#resource_definition).

data/lib/plutonium/pagination.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # Index-page pagination options, shared by the global setting
+  # (`config.pagination`) and the per-resource definition DSL (`pagination`).
+  #
+  # `count:` decides what the index pays to know its total:
+  #
+  #   :exact  - a full COUNT(*) on every page load (the default)
+  #   Integer - count at most this many rows, then show "N+"
+  #   false   - no COUNT query at all; prev/next navigation only
+  module Pagination
+    OPTIONS = %i[count].freeze
+    DEFAULTS = {count: :exact}.freeze
+
+    # Validates a partial options hash and returns it frozen. An unknown key or
+    # count value raises at declaration, not on the first page load.
+    def self.validate!(options)
+      raise ArgumentError, "pagination options must be a Hash, got #{options.inspect}" unless options.is_a?(Hash)
+
+      unknown = options.keys - OPTIONS
+      raise ArgumentError, "unknown pagination option(s) #{unknown.inspect}, expected #{OPTIONS.inspect}" if unknown.any?
+
+      if options.key?(:count)
+        count = options[:count]
+        valid = count == :exact || count == false || (count.is_a?(Integer) && count.positive?)
+        unless valid
+          raise ArgumentError, "pagination count must be :exact, false, or a positive Integer, got #{count.inspect}"
+        end
+      end
+
+      options.dup.freeze
+    end
+  end
+end

data/lib/plutonium/resource/controllers/crud_actions/index_action.rb

@@ -22,7 +22,33 @@ module Plutonium
             # eager-loading at the point of use also leaves an app's own
             # `filtered_resource_collection` override unaffected.
             collection = auto_eager_load(filtered_resource_collection, presentable_attributes_for(action))
-            @pagy, @resource_records = pagy(:offset, collection, request: pagy_request_context)
+            @pagy, @resource_records = paginate_collection(collection)
+          end
+
+          # How the index counts its records: `:exact`, an Integer cap, or
+          # `false` for no count. Read from the definition (falling back to
+          # `Plutonium.configuration.pagination`); override in a controller to
+          # decide per request.
+          def pagination_count
+            current_definition.resolved_pagination[:count]
+          end
+
+          def paginate_collection(collection)
+            case (cap = pagination_count)
+            when :exact
+              pagy(:offset, collection, request: pagy_request_context)
+            when false
+              pagy(:countless, collection, request: pagy_request_context)
+            else
+              # COUNT(*) over a LIMIT subquery stops after cap + 1 matching
+              # rows. The extra row is how we know the total went past the cap.
+              # Pagy gets the cap itself as the count, so the last page is the
+              # one holding row `cap`.
+              count = collection.limit(cap + 1).count(:all)
+              count = count.size if count.is_a?(Hash) # grouped relation
+              capped = count > cap
+              pagy(:offset, collection, count: [count, cap].min, count_capped: capped, request: pagy_request_context)
+            end
           end
 
           # What Pagy builds its page URLs from. Pagy accepts either the real