concerns_on_rails 1.28.0 → 1.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f9aef0d5f95ffc23ef6213d5d95ea872a6146763d488a287a334db8be68b922
-  data.tar.gz: b364f4276149a31b1ce1f6efaf170435900f34188eb358035c10020567e8b51d
+  metadata.gz: b0a05169c98ce90531027509dbbdd4f00722678e2cfe246a5692484d9a12a111
+  data.tar.gz: 10d2cebdced9beed7b677b18a0b8c85dc82d1125672ada2f5c5f12b995fa1933
 SHA512:
-  metadata.gz: 025306bb013a418c8051db996ddd0fe6f2bf7ac7f657d22335639b5bcceecff8416e85c66ebde92a357656eeaba90f51a2993fab23232267af105e823cf28934
-  data.tar.gz: b0d98d45a2b189b43985e5d5548c3b905a161f2aa0df9022d251a2788b62524360bc002d2981e7e9801a10e4b0f7aa4a7b1d6b0ee5adb4298edeef89a07a8467
+  metadata.gz: 756646b2232fa428250bf502fbb7ce87a44bf39830d9ae4810e50482315394fa1aa0b0e1ed47fb9a4b87d677d11507adfb7e14206f0b27119235060c74f1513b
+  data.tar.gz: '08b14db3a23711b0531447c773b2d831ec37fcf8c2b84fa59b4f203c7375923297e3a9dd93597b6e0091f18e677752be0dca67b913a4a3b1dd61fb042b417fad'

data/CHANGELOG.md

@@ -1,5 +1,93 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.2 (2026-09-11)
+
+Six merged enhancement PRs from the September loop (#42, #84, #59 via #90, #80,
+#81, #82), all additive and column-free: ErrorHandleable rescues 14 exceptions
+instead of 3 and instruments every handled error, CursorPaginatable cursors can
+be HMAC-signed, Sortable applies a drag-and-drop order in one UPDATE, Sluggable
+gains slug candidates / word-boundary truncation / forced regeneration, and
+Sequenceable can defer numbering until an invoice is finalized. No new
+migrations or runtime dependencies. 1360 examples, 0 failures.
+
+### Added
+- **Controllers::ErrorHandleable**: the exception map grows from 3 to 14 —
+  `ActiveModel::ValidationError`, `RecordNotSaved`, `RecordNotDestroyed` (422),
+  `StaleObjectError`, `RecordNotUnique`, `InvalidForeignKey` (409),
+  `UnpermittedParameters`, `BadRequest`, `ParseError` (400),
+  `InvalidAuthenticityToken` (422) and `UnknownFormat` (406). Statuses follow
+  Rails' `rescue_responses`; database/parser-level errors render generic
+  messages so SQL, schema names and request input never leak. New
+  `handle_errors only:/except:` macro trims the map without touching a host
+  `rescue_from`; `error_handleable_keys` lists the active keys. (#42)
+- **Controllers::ErrorHandleable**: every handled error instruments
+  `handled_error.concerns_on_rails` (controller, action, code, status, message,
+  exception) via the public `on_handled_error(key, error, status:, message:)`
+  override point — report some codes to the error tracker, let the rest stay
+  quiet. (#84)
+- **Controllers::CursorPaginatable**: `cursor_paginate_by … signed: true` (or a
+  String key / callable) appends a URL-safe HMAC-SHA256 to every cursor and
+  rejects tampered, mis-signed or unsigned tokens with the usual 400, so
+  clients can no longer hand-craft page positions. Unsigned stays the default.
+  (#59, merged via #90)
+- **Sortable (model)**: `Model.reposition!(ids, missing: :append | :raise)`
+  applies a drag-and-drop id order as positions in one `UPDATE … CASE` inside
+  the current relation (unlisted rows appended or raised, foreign/duplicate ids
+  rejected, String ids cast, `:desc` lists inverted). Returns the count. (#80)
+- **Sluggable**: `candidates:` (friendly_id slug candidates tried in order
+  before the uuid fallback; regeneration still keyed to the primary field),
+  `max_length:` (word-boundary truncation, suffix appended after) and
+  `regenerate_slug!` (rebuild from the current source even over a
+  hand-assigned slug). (#81)
+- **Sequenceable**: `assign: :manual` defers numbering until `assign_<field>!`
+  (idempotent — `true` when assigned, `false` when already numbered; `save!`s
+  persisted records, leaves new ones for the caller's save), plus
+  `<field>_assigned?` and a `pending_<field>` scope. Numbering then follows
+  finalization order; `reset:` periods still come from `created_at`. (#82)
+
+### Notes
+Apps that include ErrorHandleable now get 11 more exceptions rescued into JSON
+4xx responses. One that relied on, say, `StaleObjectError` propagating to its
+error tracker should add `handle_errors except: :stale_object` (or `only:` the
+original trio) — or override `on_handled_error` to report the codes it cares
+about. Exceptions are registered by name, so a class a given Rails version
+lacks is simply never matched. Turning on `signed:` invalidates in-flight
+unsigned cursors (there is no mixed mode by design), so clients restart from
+the first page. `reposition!` writes positions with `update_all` and therefore
+bypasses acts_as_list's per-row callbacks by design.
+
+## 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,360 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:
@@ -275,6 +275,10 @@ sluggable_by :title, reserved_words: %w[new edit admin]
 
 # Let Model.find accept a slug directly (not just the id)
 sluggable_by :title, finders: true
+sluggable_by :title, candidates: [:title, %i[title city]]   # try "title", then "title-city", then friendly_id's uuid suffix on the first candidate
+sluggable_by :title, max_length: 60                        # truncate at a word boundary (uniqueness suffix added after)
+
+page.regenerate_slug!   # rebuild from the current source — even over a hand-assigned slug
 Post.find("hello-world")   # resolves by slug
 ```
 
@@ -282,6 +286,9 @@ Post.find("hello-world")   # resolves by slug
 - Schema must have a `slug` column (string).
 - `history: true` requires a `friendly_id_slugs` table — generate with `rails generate friendly_id` or add a manual migration.
 - `scope: :col` requires `col` to exist in the same table.
+- `candidates:` takes friendly_id's shapes — a Symbol/String method, a Proc, or an Array of those joined with `-` — tried in order until one is free (all taken → the first candidate plus a uuid); the slug still regenerates only when the **primary** field changes (a candidate-only change doesn't churn the URL), and a NULL slug backfills through the candidates.
+- `max_length:` truncates each candidate at the last `-` inside the limit (a single long word is hard-cut); friendly_id's conflict suffix is appended afterwards, so a colliding slug may exceed the limit — unlike friendly_id's own `slug_limit`, which squeezes the uuid inside it.
+- `regenerate_slug!` is the escape hatch for the explicit-slug rule: it forces regeneration and saves (`save!`), keeping uniqueness handling.
 - Falls back to `to_s` if the configured source field doesn't respond.
 - Uses friendly_id's `:slugged` (+ optionally `:history`, `:scoped`) strategies under the hood.
 
@@ -301,6 +308,10 @@ end
 Task.create!(name: "A")
 Task.create!(name: "B")
 Task.last.move_higher
+
+# Save a drag-and-drop order in ONE UPDATE (CASE id WHEN …): the ids' order becomes their positions
+Task.reposition!(params[:ids])                    # => 12 — rows not listed are pushed after, in their current order
+Task.where(list_id: 1).reposition!(ids, missing: :raise)   # scoped; a partial list is an error
 ```
 
 **Configuration**
@@ -314,8 +325,8 @@ sortable_by :position, add_new_at: :top          # new rows insert at the top (a
 ```
 
 **Notes**
-- The configured field must exist as a column.
-- Direction values other than `:asc` / `:desc` silently fall back to `:asc`.
+- The configured field must exist as a column; a direction other than `:asc` / `:desc` raises at declaration.
+- `reposition!` runs inside the current relation (`Task.where(list_id: 1)` — the same set acts_as_list's `scope:` would use), rejects ids outside it and duplicates before writing anything, coerces String ids from params, and on a descending list gives the first id the highest value. It bypasses acts_as_list callbacks by design (one `update_all`, no per-row shifting).
 
 ---
 
@@ -854,6 +865,7 @@ Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without cre
 | `scope:`             | `nil`       | Column (or array of columns) the counter is scoped to — e.g. one sequence per `account_id`. |
 | `reset:`             | `:never`    | `:never` / `:year` / `:month` / `:day` — restart numbering each period (needs `created_at`). |
 | `template:`          | `nil`       | `->(seq, record) { ... }` full custom formatter; overrides `prefix` / `padding` / period. |
+| `assign:`            | `:create`   | `:create` numbers every record in `before_create`; `:manual` leaves the column NULL until `assign_<field>!` is called — for invoices that get their number when finalized, not when drafted. |
 
 **Default format**
 
@@ -870,10 +882,14 @@ Invoice.next_sequence(account_id: 1)   # => 4  (peek the next value, without cre
 |-----------------------------------|---------------------------------------------------------------------------------------|
 | `formatted_<field>`               | The formatted string — the persisted `into:` value when set, otherwise computed.      |
 | `Model.next_<field>(scope_attrs)` | Peek the next integer for a scope without creating a record.                           |
+| `assign_<field>!`                 | Number the record now (`assign: :manual`, or any row still blank): next value + `into:` string, `save!`d when persisted, left for your save when new. `true` when assigned, `false` when already numbered. |
+| `<field>_assigned?`               | Whether the record has its number.                                                    |
+| `Model.pending_<field>`           | Scope: rows still awaiting a number (`WHERE <field> IS NULL`).                          |
 
 **Notes**
 - The next value is `MAX(<field>) + 1` within the scope (and period), so numbering is dense and ordered — not random.
 - Caller-supplied values are respected: `Invoice.create!(sequence: 100)` is not overwritten (and its `into:` string is still formatted from `100`).
+- With `assign: :manual`, numbering follows **assignment** order (the first invoice finalized is #1, whenever it was drafted); with `reset:` the period is still taken from the row's `created_at`, exactly as on create.
 - Generation reads `MAX` then inserts, so two concurrent inserts can race. It's **best-effort** — add a **scoped unique index** on `<field>` (and on `into:`) for a real guarantee, the same way you would for any `MAX`-based numbering.
 - `reset:` requires a `created_at` column; the period is taken from each row's creation time.
 - For fixed-width display (`00042`), make the `into:` column a **string** — integer columns drop leading zeros.
@@ -1494,6 +1510,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
@@ -1530,7 +1581,7 @@ end
 
 **Notes**
 - The primary key is always appended as a tiebreaker, so duplicate values never skip or repeat rows; ordering columns are chosen **in code** (never from params) and should be `NOT NULL` (a NULL boundary value raises rather than silently dropping rows).
-- Cursors are opaque, table/order-pinned tokens — a malformed, cross-endpoint, or stale-config cursor renders a 400 (`invalid_cursor`; override `render_invalid_cursor` to customize, delegates to Respondable's `render_error` when present). They are **not signed**: a client can mint different boundary values, but values are cast through the model's attribute types and bound by Arel (no injection) and the relation's own scoping still applies — treat a cursor as a page position, never an authorization boundary.
+- Cursors are opaque, table/order-pinned tokens — a malformed, cross-endpoint, or stale-config cursor renders a 400 (`invalid_cursor`; override `render_invalid_cursor` to customize, delegates to Respondable's `render_error` when present). Unsigned by default: a client can mint different boundary values, but values are cast through the model's attribute types and bound by Arel (no injection) and the relation's own scoping still applies — treat a cursor as a page position, never an authorization boundary. **`signed: true`** (or a String key, or a callable for rotating keys) appends a URL-safe HMAC-SHA256 to every cursor and rejects tampered or unsigned tokens with the same 400, so clients can no longer hand-craft positions at all; `true` uses `Rails.application.secret_key_base`. Turning it on invalidates in-flight cursors (clients restart from page one).
 - `cursor_paginated` uses `reorder` (replaces any `default_scope` ORDER BY) and returns a loaded Array. Don't wrap it with the controller Sortable's `sorted` — pass `order:` per call instead.
 - Forward-only by default — `bidirectional: true` (macro or per call) adds prev cursors and `X-Has-Prev`/`X-Prev-Cursor`; direction is pinned in the token, so prev tokens replayed on forward-only endpoints 400 and old direction-less tokens stay valid. `order_presets: { newest: {...}, top: {...} }` (+ `default_preset:`, `order_param:`) lets clients pick a **named** ordering from an allow-list. `predicate: :auto` upgrades the keyset WHERE to a row-value tuple `(a, b, id) > (x, y, z)` on PostgreSQL/MySQL/SQLite when directions are uniform — composite-index friendly — falling back to the portable OR-expansion (`:row`/`:or` force a strategy).
 - Use Paginatable when you need page numbers and totals.
@@ -1646,22 +1697,42 @@ end
 
 ## 🛟 ErrorHandleable
 
-Install `rescue_from` handlers for the three most common controller exceptions and render them as the same JSON envelope used by Respondable.
+Install `rescue_from` handlers for the controller exceptions a JSON API meets in practice and render them as the same JSON envelope used by Respondable.
 
 ```ruby
 class Api::BaseController < ApplicationController
   include ConcernsOnRails::Controllers::Respondable       # recommended
   include ConcernsOnRails::Controllers::ErrorHandleable
+
+  handle_errors except: :stale_object                     # optional — let some propagate
 end
 ```
 
 **Handled exceptions**
 
-| Exception                              | Status | `code`                |
-|----------------------------------------|--------|-----------------------|
-| `ActiveRecord::RecordNotFound`         | 404    | `"not_found"`         |
-| `ActionController::ParameterMissing`   | 400    | `"parameter_missing"` |
-| `ActiveRecord::RecordInvalid`          | 422    | `"record_invalid"`    |
+| Key (= `code`)               | Exception                                      | Status | `details`                    |
+|------------------------------|------------------------------------------------|--------|------------------------------|
+| `not_found`                  | `ActiveRecord::RecordNotFound`                 | 404    | —                            |
+| `parameter_missing`          | `ActionController::ParameterMissing`           | 400    | —                            |
+| `record_invalid`             | `ActiveRecord::RecordInvalid`                  | 422    | `errors.full_messages`       |
+| `validation_error`           | `ActiveModel::ValidationError`                 | 422    | `model.errors.full_messages` |
+| `record_not_saved`           | `ActiveRecord::RecordNotSaved`                 | 422    | record errors, if any        |
+| `record_not_destroyed`       | `ActiveRecord::RecordNotDestroyed`             | 422    | record errors, if any        |
+| `stale_object`               | `ActiveRecord::StaleObjectError`               | 409    | —                            |
+| `record_not_unique`          | `ActiveRecord::RecordNotUnique`                | 409    | —                            |
+| `foreign_key_violation`      | `ActiveRecord::InvalidForeignKey`              | 409    | —                            |
+| `unpermitted_parameters`     | `ActionController::UnpermittedParameters`      | 400    | the parameter names          |
+| `invalid_authenticity_token` | `ActionController::InvalidAuthenticityToken`   | 422    | —                            |
+| `bad_request`                | `ActionController::BadRequest`                 | 400    | —                            |
+| `parse_error`                | `ActionDispatch::Http::Parameters::ParseError` | 400    | —                            |
+| `unknown_format`             | `ActionController::UnknownFormat`              | 406    | —                            |
+
+Statuses follow Rails' own `rescue_responses` wherever Rails has an opinion; the two database-constraint
+races Rails leaves as 500s (`RecordNotUnique`, `InvalidForeignKey`) get the REST-conventional 409. Messages
+for database- and parser-level errors are deliberately generic (`"Resource already exists"`,
+`"Malformed request body"`, …): the raw messages carry SQL fragments, table/column names, model class
+names or the offending input, none of which belongs in an API response. `details` is present only when
+there is something to list.
 
 Response shape (matches `Respondable#render_error`):
 
@@ -1683,8 +1754,32 @@ class Api::BaseController < ApplicationController
 end
 ```
 
+**Trimming the map**
+
+```ruby
+handle_errors except: :stale_object                               # let optimistic-lock conflicts reach the error tracker
+handle_errors except: %i[record_not_unique foreign_key_violation]  # calls accumulate
+handle_errors only: %i[not_found parameter_missing record_invalid] # just the original trio
+```
+
+`handle_errors` removes only the concern's own registrations (matched on exception *and* handler), so a
+`rescue_from` you declared yourself for the same exception is untouched, and it never re-adds — your later
+declarations keep precedence. Unknown keys raise `ArgumentError` listing the valid ones;
+`error_handleable_keys` returns the keys still active on a controller.
+
+**Reporting** — every handled error instruments `handled_error.concerns_on_rails` (`controller`, `action`, `code`, `status`, `message`, `exception`, `exception_class`) via the public `on_handled_error(key, error, status:, message:)` override point, so the 409s reach your error tracker while the 404s stay quiet:
+
+```ruby
+def on_handled_error(key, error, **)
+  Sentry.capture_exception(error) if %i[record_not_unique foreign_key_violation stale_object].include?(key)
+  super   # keep the event
+end
+```
+
 **Notes**
 - When `Respondable` is also included, the handlers delegate to `render_error` so the envelope shape stays in one place. Otherwise they render the same envelope inline.
+- Exceptions are registered by name (string), so a class your Rails version lacks is simply never matched.
+- `ActionController::UnpermittedParameters` is only raised with `config.action_controller.action_on_unpermitted_parameters = :raise`.
 - `RecordInvalid.details` are populated from `error.record.errors.full_messages`.
 
 ---
@@ -2122,9 +2217,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,360 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.2.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/cursor_paginatable.rb

@@ -3,6 +3,8 @@ require "concerns_on_rails/support/error_envelope"
 require "concerns_on_rails/support/scalar_param"
 require "json"
 require "concerns_on_rails/support/link_header"
+require "openssl"
+require "active_support/security_utils"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
 module ConcernsOnRails
@@ -143,6 +145,9 @@ module ConcernsOnRails
         class_attribute :cursor_paginatable_bidirectional, default: false
         class_attribute :cursor_paginatable_predicate, default: :auto
         class_attribute :cursor_paginatable_link_header, default: true
+        # false (unsigned), true (Rails.application.secret_key_base), a String
+        # key, or a callable returning the key — see cursor_paginate_by.
+        class_attribute :cursor_paginatable_signed, default: false
 
         # Real controllers (anything with ActiveSupport::Rescuable) get the 400
         # handlers automatically; bare objects let the errors propagate.
@@ -163,7 +168,7 @@ module ConcernsOnRails
         # max_per_page: 0 (or negative) disables the per_page cap.
         def cursor_paginate_by(order: nil, order_presets: nil, default_preset: nil, order_param: :order,
                                per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE,
-                               bidirectional: false, predicate: :auto, link_header: true)
+                               bidirectional: false, predicate: :auto, link_header: true, signed: false)
           self.cursor_paginatable_order = order && CursorPaginatable.normalize_order!(order)
           self.cursor_paginatable_order_presets = order_presets && CursorPaginatable.normalize_presets!(order_presets)
           self.cursor_paginatable_default_preset =
@@ -174,9 +179,19 @@ module ConcernsOnRails
           self.cursor_paginatable_bidirectional = bidirectional ? true : false
           self.cursor_paginatable_predicate = CursorPaginatable.validate_predicate!(predicate)
           self.cursor_paginatable_link_header = link_header ? true : false
+          self.cursor_paginatable_signed = CursorPaginatable.validate_signed!(signed)
         end
       end
 
+      # `signed:` — false, true (the app's secret_key_base), a non-blank String,
+      # or a callable (resolved per request, so keys can rotate).
+      def self.validate_signed!(signed)
+        return signed if [true, false].include?(signed) || signed.respond_to?(:call)
+        return signed if signed.is_a?(String) && !signed.strip.empty?
+
+        raise ArgumentError, "#{name}: signed: must be true, false, a String or a callable"
+      end
+
       # Run the keyset query (limit + 1 to detect has_more), set the standard
       # response headers, and return the page as a loaded Array (laziness is
       # impossible here: has_more detection materializes limit + 1 rows).
@@ -339,7 +354,55 @@ module ConcernsOnRails
           "d" => direction,
           "v" => pairs.map { |col, _dir| serialize_cursor_value(cursor_boundary_value!(record, col)) }
         }
-        cursor_base64_encode(JSON.generate(payload))
+        token = cursor_base64_encode(JSON.generate(payload))
+        cursor_signing_key ? "#{token}.#{cursor_signature(token)}" : token
+      end
+
+      # Signed cursors are `<url-safe base64 payload>.<hex HMAC-SHA256>` — the
+      # dot never appears in the payload alphabet, so the split is unambiguous
+      # and the whole token stays URL-safe. Verification is constant-time and
+      # happens BEFORE the payload is parsed; an unsigned or mis-signed token
+      # on a signed endpoint is rejected (fail closed). Turning signing on
+      # therefore invalidates in-flight cursors: clients restart from page one.
+      def cursor_signature(payload_token)
+        OpenSSL::HMAC.hexdigest("SHA256", cursor_signing_key, payload_token)
+      end
+
+      # nil when unsigned; the key otherwise. `true` reads
+      # Rails.application.secret_key_base (raising a setup hint outside Rails).
+      def cursor_signing_key
+        configured = self.class.cursor_paginatable_signed
+        return nil if configured == false || configured.nil?
+        return cursor_rails_secret_key_base if configured == true
+
+        key = configured.respond_to?(:call) ? configured.call : configured
+        raise ArgumentError, "#{self.class.name}: signed: resolved to a blank key" if key.to_s.strip.empty?
+
+        key.to_s
+      end
+
+      def cursor_rails_secret_key_base
+        app = defined?(Rails) && Rails.respond_to?(:application) ? Rails.application : nil
+        key = app.respond_to?(:secret_key_base) ? app.secret_key_base : nil
+        return key.to_s unless key.to_s.strip.empty?
+
+        raise ArgumentError,
+              "ConcernsOnRails::Controllers::CursorPaginatable: signed: true needs Rails.application.secret_key_base; " \
+              "outside a Rails app pass signed: -> { ... } (a callable returning the key) or a String."
+      end
+
+      # Splits and verifies a signed token, returning the payload half; raises
+      # InvalidCursor when the endpoint is signed and the token is not (or its
+      # signature does not match).
+      def verify_cursor_signature!(raw)
+        return raw unless cursor_signing_key
+
+        payload, signature, extra = raw.split(".", 3)
+        valid = extra.nil? && !payload.to_s.empty? && signature.to_s.match?(/\A[0-9a-f]{64}\z/) &&
+                ActiveSupport::SecurityUtils.secure_compare(signature, cursor_signature(payload))
+        raise InvalidCursor, "Invalid pagination cursor." unless valid
+
+        payload
       end
 
       # A NULL boundary value would emit `col > NULL` — never TRUE in SQL
@@ -375,7 +438,7 @@ module ConcernsOnRails
       def decode_cursor(raw, pairs, model, bidirectional:)
         return nil if raw.nil? || raw.to_s.strip.empty?
 
-        payload = parse_cursor_payload(raw.to_s)
+        payload = parse_cursor_payload(verify_cursor_signature!(raw.to_s))
         raise InvalidCursor, "Invalid pagination cursor." unless payload
 
         verify_cursor_scope!(payload, pairs, model)

data/lib/concerns_on_rails/controllers/error_handleable.rb

@@ -3,18 +3,38 @@ require "concerns_on_rails/support/error_envelope"
 
 module ConcernsOnRails
   module Controllers
-    # Installs `rescue_from` handlers for the three most common controller
-    # exceptions and renders them as the JSON error envelope used by Respondable.
+    # Installs `rescue_from` handlers for the controller exceptions a JSON API
+    # meets in practice and renders each as the error envelope Respondable uses.
     #
     #   class Api::BaseController < ApplicationController
     #     include ConcernsOnRails::Controllers::Respondable      # optional, but recommended
     #     include ConcernsOnRails::Controllers::ErrorHandleable
+    #
+    #     handle_errors except: :stale_object    # optional: let some propagate
     #   end
     #
-    # Handled:
-    #   * ActiveRecord::RecordNotFound          → 404 not_found
-    #   * ActionController::ParameterMissing    → 400 parameter_missing
-    #   * ActiveRecord::RecordInvalid           → 422 record_invalid (with field errors)
+    # Handled (key → exception → status):
+    #   * :not_found                  ActiveRecord::RecordNotFound                 404
+    #   * :parameter_missing          ActionController::ParameterMissing           400
+    #   * :record_invalid             ActiveRecord::RecordInvalid                  422 (+ field errors)
+    #   * :validation_error           ActiveModel::ValidationError                 422 (+ field errors)
+    #   * :record_not_saved           ActiveRecord::RecordNotSaved                 422 (+ field errors, if any)
+    #   * :record_not_destroyed       ActiveRecord::RecordNotDestroyed             422 (+ field errors, if any)
+    #   * :stale_object               ActiveRecord::StaleObjectError               409
+    #   * :record_not_unique          ActiveRecord::RecordNotUnique                409
+    #   * :foreign_key_violation      ActiveRecord::InvalidForeignKey              409
+    #   * :unpermitted_parameters     ActionController::UnpermittedParameters      400 (+ the param names)
+    #   * :invalid_authenticity_token ActionController::InvalidAuthenticityToken   422
+    #   * :bad_request                ActionController::BadRequest                 400
+    #   * :parse_error                ActionDispatch::Http::Parameters::ParseError 400
+    #   * :unknown_format             ActionController::UnknownFormat              406
+    #
+    # Statuses follow Rails' own `rescue_responses` wherever Rails has an
+    # opinion; the two database-constraint races Rails leaves as 500s
+    # (RecordNotUnique, InvalidForeignKey) get the REST-conventional 409.
+    # Messages for database- and parser-level errors are deliberately generic:
+    # the raw messages carry SQL fragments, table/column names, model class
+    # names or the offending input, none of which belongs in an API response.
     #
     # If Respondable is also included on the controller, the handlers delegate
     # to `render_error` so the envelope shape stays in one place. Otherwise the
@@ -22,53 +42,234 @@ module ConcernsOnRails
     #
     # Each handler is a public instance method, so subclasses can override the
     # message wording or response shape without re-declaring the `rescue_from`.
+    #
+    # Every handled error instruments `handled_error.concerns_on_rails`
+    # (controller, action, code, status, message, exception) through the public
+    # `on_handled_error(key, error, status:, message:)` override point — the
+    # place to report the 409s to Sentry while letting the 404s pass quietly.
     module ErrorHandleable
       extend ActiveSupport::Concern
 
+      LABEL = "ConcernsOnRails::Controllers::ErrorHandleable".freeze
+
+      # The envelope `code` is the key; the status is what the handler renders.
+      # Exception names are strings so registration never forces a constant to
+      # load (and a name absent from the host's Rails version is simply never
+      # matched — `rescue_from` safe_constantizes at rescue time).
+      HANDLERS = {
+        not_found: { exception: "ActiveRecord::RecordNotFound",
+                     handler: :handle_record_not_found, status: :not_found },
+        parameter_missing: { exception: "ActionController::ParameterMissing",
+                             handler: :handle_parameter_missing, status: :bad_request },
+        record_invalid: { exception: "ActiveRecord::RecordInvalid",
+                          handler: :handle_record_invalid, status: :unprocessable_entity },
+        validation_error: { exception: "ActiveModel::ValidationError",
+                            handler: :handle_validation_error, status: :unprocessable_entity },
+        record_not_saved: { exception: "ActiveRecord::RecordNotSaved",
+                            handler: :handle_record_not_saved, status: :unprocessable_entity },
+        record_not_destroyed: { exception: "ActiveRecord::RecordNotDestroyed",
+                                handler: :handle_record_not_destroyed, status: :unprocessable_entity },
+        stale_object: { exception: "ActiveRecord::StaleObjectError",
+                        handler: :handle_stale_object, status: :conflict },
+        record_not_unique: { exception: "ActiveRecord::RecordNotUnique",
+                             handler: :handle_record_not_unique, status: :conflict },
+        foreign_key_violation: { exception: "ActiveRecord::InvalidForeignKey",
+                                 handler: :handle_invalid_foreign_key, status: :conflict },
+        unpermitted_parameters: { exception: "ActionController::UnpermittedParameters",
+                                  handler: :handle_unpermitted_parameters, status: :bad_request },
+        invalid_authenticity_token: { exception: "ActionController::InvalidAuthenticityToken",
+                                      handler: :handle_invalid_authenticity_token, status: :unprocessable_entity },
+        bad_request: { exception: "ActionController::BadRequest",
+                       handler: :handle_bad_request, status: :bad_request },
+        parse_error: { exception: "ActionDispatch::Http::Parameters::ParseError",
+                       handler: :handle_parse_error, status: :bad_request },
+        unknown_format: { exception: "ActionController::UnknownFormat",
+                          handler: :handle_unknown_format, status: :not_acceptable }
+      }.freeze
+
       included do
-        rescue_from "ActiveRecord::RecordNotFound",       with: :handle_record_not_found
-        rescue_from "ActionController::ParameterMissing", with: :handle_parameter_missing
-        rescue_from "ActiveRecord::RecordInvalid",        with: :handle_record_invalid
+        # The keys still handled on this controller (trimmed by `handle_errors`).
+        class_attribute :error_handleable_keys, instance_accessor: false, default: HANDLERS.keys
+
+        HANDLERS.each_value do |spec|
+          rescue_from spec[:exception], with: spec[:handler]
+        end
+      end
+
+      class_methods do
+        # Trim the default map: `only:` keeps just those keys, `except:` drops
+        # them. Accepts a symbol or a list; calls accumulate. Removes only the
+        # concern's OWN registrations (matched on exception name AND handler
+        # method), so a `rescue_from` the host declared for the same exception
+        # is untouched — and nothing is ever re-added, so the host's later
+        # declarations keep their precedence. Returns the keys still active.
+        #
+        #   handle_errors except: :stale_object                 # let lock conflicts reach the error tracker
+        #   handle_errors only: %i[not_found parameter_missing record_invalid]
+        def handle_errors(only: nil, except: nil)
+          keep = error_handleable_selection(only: only, except: except)
+          dropped = HANDLERS.filter_map { |key, spec| [spec[:exception], spec[:handler]] unless keep.include?(key) }
+          self.rescue_handlers = rescue_handlers.reject { |entry| dropped.include?(entry) }
+          self.error_handleable_keys = error_handleable_keys & keep
+        end
+
+        # Validates only:/except: and returns the HANDLERS keys to keep.
+        def error_handleable_selection(only:, except:)
+          raise ArgumentError, "#{LABEL}: pass only: or except:, not both" if only && except
+
+          keys = error_handleable_known_keys(Array(only || except))
+          only ? keys : HANDLERS.keys - keys
+        end
+
+        def error_handleable_known_keys(list)
+          keys = list.map(&:to_sym)
+          unknown = keys - HANDLERS.keys
+          return keys if unknown.empty?
+
+          raise ArgumentError,
+                "#{LABEL}: unknown handler key(s) #{unknown.map(&:inspect).join(', ')} — " \
+                "valid keys: #{HANDLERS.keys.map(&:inspect).join(', ')}"
+        end
+        private :error_handleable_selection, :error_handleable_known_keys
+      end
+
+      # Called before each handled error is rendered. Default: instrument
+      # `handled_error.concerns_on_rails` with the controller path, action, the
+      # envelope code (the HANDLERS key), status, rendered message, and the
+      # exception (nil when a handler is called directly rather than rescued).
+      # Override to report selectively — call super to keep the event, and
+      # rescue inside your override if the reporter itself can fail.
+      def on_handled_error(key, error, status:, message:)
+        ActiveSupport::Notifications.instrument(
+          "handled_error.concerns_on_rails",
+          controller: error_handleable_controller_name, action: error_handleable_action_name,
+          code: key, status: status, message: message, exception: error, exception_class: error&.class&.name
+        )
+      end
+
+      # Remember the exception being rescued so the render funnel can hand it to
+      # `on_handled_error` — the handlers themselves only pass a message along.
+      # Rescuable's `rescue_with_handler(exception, object:, visited_exceptions:)`
+      # is what ActionController's rescue path calls.
+      def rescue_with_handler(exception, **)
+        @error_handleable_exception = exception
+        super
+      ensure
+        @error_handleable_exception = nil
       end
 
       def handle_record_not_found(_error)
         # Use a generic message: the raw RecordNotFound message leaks the model
         # class name and the queried attribute/value to API clients. Subclasses
         # can override this method to surface detail in non-production envs.
-        render_error_envelope(
-          message: "Resource not found",
-          code: "not_found",
-          status: :not_found
-        )
+        render_handled_error(:not_found, message: "Resource not found")
       end
 
       def handle_parameter_missing(error)
-        render_error_envelope(
-          message: "Parameter missing: #{error.param}",
-          code: "parameter_missing",
-          status: :bad_request
-        )
+        render_handled_error(:parameter_missing, message: "Parameter missing: #{error.param}")
       end
 
       def handle_record_invalid(error)
-        record = error.respond_to?(:record) ? error.record : nil
-        details = record.respond_to?(:errors) ? record.errors.full_messages : nil
-
-        render_error_envelope(
-          message: error.message,
-          code: "record_invalid",
-          status: :unprocessable_entity,
-          errors: details
-        )
+        render_handled_error(:record_invalid, message: error.message, errors: record_error_details(error))
+      end
+
+      # `validate!` on a plain ActiveModel::Model (form objects, service inputs).
+      def handle_validation_error(error)
+        model = error.respond_to?(:model) ? error.model : nil
+        render_handled_error(:validation_error, message: error.message, errors: error_messages_of(model))
+      end
+
+      # `save!` refused by a callback abort (`throw :abort`) — the record may or
+      # may not carry errors, so details are attached only when it does.
+      def handle_record_not_saved(error)
+        render_handled_error(:record_not_saved, message: error.message, errors: record_error_details(error))
+      end
+
+      def handle_record_not_destroyed(error)
+        render_handled_error(:record_not_destroyed, message: error.message, errors: record_error_details(error))
+      end
+
+      # Optimistic locking (`lock_version`) lost the race. The raw message names
+      # the model class; the client only needs to know to reload and retry.
+      def handle_stale_object(_error)
+        render_handled_error(:stale_object, message: "Resource was modified by another request; reload and retry")
+      end
+
+      # A unique index caught what a uniqueness validation raced past. The raw
+      # message is the adapter's SQL error — table and column included.
+      def handle_record_not_unique(_error)
+        render_handled_error(:record_not_unique, message: "Resource already exists")
+      end
+
+      def handle_invalid_foreign_key(_error)
+        render_handled_error(:foreign_key_violation, message: "Resource is referenced by other records")
+      end
+
+      # Only raised with `config.action_controller.action_on_unpermitted_parameters = :raise`.
+      def handle_unpermitted_parameters(error)
+        names = error.respond_to?(:params) ? Array(error.params).map(&:to_s) : []
+        render_handled_error(:unpermitted_parameters,
+                             message: "Unpermitted parameters: #{names.join(', ')}",
+                             errors: names.empty? ? nil : names)
+      end
+
+      def handle_invalid_authenticity_token(_error)
+        render_handled_error(:invalid_authenticity_token, message: "Invalid authenticity token")
+      end
+
+      # Malformed query string / form body (bad %-encoding, invalid UTF-8). The
+      # raw message echoes the offending input — never reflect it back.
+      def handle_bad_request(_error)
+        render_handled_error(:bad_request, message: "Bad request")
+      end
+
+      # Unparseable JSON/XML request body. The raw message carries the parser's
+      # excerpt of the body.
+      def handle_parse_error(_error)
+        render_handled_error(:parse_error, message: "Malformed request body")
+      end
+
+      # `respond_to` had no block for the requested format.
+      def handle_unknown_format(_error)
+        render_handled_error(:unknown_format, message: "Requested format is not supported")
       end
 
       private
 
+      # Renders the envelope for a HANDLERS key: code = key, status from the table.
+      def render_handled_error(key, message:, errors: nil)
+        status = HANDLERS.fetch(key)[:status]
+        on_handled_error(key, @error_handleable_exception, status: status, message: message)
+        render_error_envelope(message: message, code: key.to_s, status: status, errors: errors)
+      end
+
+      def error_handleable_controller_name
+        respond_to?(:controller_path) ? controller_path : self.class.name
+      end
+
+      def error_handleable_action_name
+        respond_to?(:action_name) ? action_name.to_s : nil
+      end
+
+      # Kept for subclasses that call it from a handler override.
       def render_error_envelope(message:, code:, status:, errors: nil)
         ConcernsOnRails::Support::ErrorEnvelope.render(
           self, message: message, code: code, status: status, details: errors
         )
       end
+
+      def record_error_details(error)
+        error_messages_of(error.respond_to?(:record) ? error.record : nil)
+      end
+
+      # `errors.full_messages` when the object has any, else nil so the
+      # envelope omits `details` rather than emitting an empty array.
+      def error_messages_of(object)
+        return nil unless object.respond_to?(:errors)
+
+        messages = object.errors.full_messages
+        messages.empty? ? nil : messages
+      end
     end
   end
 end

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/models/sequenceable.rb

@@ -33,6 +33,7 @@ module ConcernsOnRails
       extend ActiveSupport::Concern
 
       RESET_PERIODS = %i[never year month day].freeze
+      ASSIGN_MODES = %i[create manual].freeze
       NAME = "ConcernsOnRails::Models::Sequenceable".freeze
 
       included do
@@ -54,26 +55,29 @@ module ConcernsOnRails
         #   scope:     column or array of columns the counter is scoped to (default nil)
         #   reset:     :never (default) | :year | :month | :day — restart per period (needs created_at)
         #   template:  ->(seq, record) { ... } full custom formatter; overrides prefix/padding/period
+        #   assign:    :create (default) numbers every record in before_create; :manual leaves the
+        #              column NULL until `assign_<field>!` — invoices numbered when finalized
         def sequenceable_by(field = :sequence, into: nil, prefix: "", padding: 0,
-                            separator: "-", start_at: 1, scope: nil, reset: :never, template: nil)
+                            separator: "-", start_at: 1, scope: nil, reset: :never, template: nil, assign: :create)
           field      = field.to_sym
           into       = into&.to_sym
           reset      = reset.to_sym
+          assign     = assign.to_sym
           scope_cols = Array(scope).map(&:to_sym)
 
           ensure_columns!(NAME, field, types: :integer)
           ensure_columns!(NAME, into, types: :string) if into
           ensure_columns!(NAME, *scope_cols) unless scope_cols.empty?
           ensure_columns!(NAME, :created_at, types: :datetime) unless reset == :never
-          validate_sequenceable_options!(reset, template)
+          validate_sequenceable_options!(reset, template, assign)
 
           self.sequenceable_config = sequenceable_config.merge(
             field => { into: into, prefix: prefix.to_s, padding: padding.to_i,
                        separator: separator.to_s, start_at: start_at.to_i,
-                       scope: scope_cols, reset: reset, template: template }
+                       scope: scope_cols, reset: reset, template: template, assign: assign }
           )
 
-          before_create -> { assign_sequenceable_value(field) }
+          before_create -> { assign_sequenceable_value(field) } if assign == :create
           define_sequenceable_methods(field)
         end
       end
@@ -93,13 +97,21 @@ module ConcernsOnRails
           define_singleton_method("next_#{field}") do |scope_attrs = {}|
             sequence_base_value(field, nil, scope_attrs)
           end
+
+          # On-demand numbering (the only way under assign: :manual), a
+          # predicate, and the "still awaiting a number" scope.
+          define_method("assign_#{field}!") { sequenceable_assign!(field) }
+          define_method("#{field}_assigned?") { self[field].present? }
+          scope "pending_#{field}", -> { where(field => nil) }
         end
 
-        def validate_sequenceable_options!(reset, template)
+        def validate_sequenceable_options!(reset, template, assign = :create)
           unless RESET_PERIODS.include?(reset)
             raise ArgumentError, "#{NAME}: unknown reset '#{reset}'. Valid values: #{RESET_PERIODS.join(', ')}"
           end
-
+          unless ASSIGN_MODES.include?(assign)
+            raise ArgumentError, "#{NAME}: unknown assign ':#{assign}'. Valid values: #{ASSIGN_MODES.join(', ')}"
+          end
           return if template.nil? || template.respond_to?(:call)
 
           raise ArgumentError, "#{NAME}: template must be callable (respond to #call)"
@@ -124,6 +136,19 @@ module ConcernsOnRails
         self[cfg[:into]] = self.class.send(:format_sequence, field, self[field], self)
       end
 
+      # Number the record now: the next value for its scope/period plus the
+      # into: string, save!d when the record is persisted and left for the
+      # caller's save when new. false (nothing rewritten) when already
+      # numbered, so a "finalize" action can be retried safely.
+      def sequenceable_assign!(field)
+        return false if self[field].present?
+
+        assign_sequenceable_value(field)
+        save! unless new_record?
+        true
+      end
+      private :sequenceable_assign!
+
       # Pin the row inside the period its number is drawn from: with reset:
       # enabled the period is computed from "now" during before_create, but
       # created_at is stamped later, at INSERT time — across a year/month/day

data/lib/concerns_on_rails/models/sluggable.rb

@@ -17,10 +17,16 @@ module ConcernsOnRails
       extend ActiveSupport::Concern
 
       # instance methods
+      LABEL = "ConcernsOnRails::Models::Sluggable".freeze
+
       included do
         # declare class attributes and set default values
         class_attribute :sluggable_field, instance_accessor: false
         self.sluggable_field ||= :name
+        # `candidates:` — friendly_id slug candidates tried in order before the
+        # uuid fallback; `max_length:` — word-boundary truncation of the slug.
+        class_attribute :sluggable_candidates, instance_accessor: false, default: nil
+        class_attribute :sluggable_max_length, instance_accessor: false, default: nil
 
         extend FriendlyId
 
@@ -32,6 +38,8 @@ module ConcernsOnRails
         # we must override should_generate_new_friendly_id? to support update slug
         # if we don't override this method, friendly_id will not generate the new slug when update
         define_method :should_generate_new_friendly_id? do
+          return true if @sluggable_force_regenerate # regenerate_slug!
+
           field = self.class.sluggable_field
           slug_column = self.class.friendly_id_config.slug_column
 
@@ -49,6 +57,21 @@ module ConcernsOnRails
 
           source_changed || slug_missing
         end
+
+        # Defined on the class (like the method above) so it sits ABOVE
+        # FriendlyId::Slugged in the ancestor chain — a module-level override
+        # here would be shadowed by friendly_id's own. Truncates each candidate
+        # at a word (separator) boundary; the uniqueness suffix friendly_id
+        # appends on a conflict is added AFTER, on purpose — friendly_id's own
+        # `slug_limit` hard-cuts characters and squeezes the uuid inside the
+        # limit, which is rarely what a URL wants.
+        define_method :normalize_friendly_id do |value|
+          normalized = super(value)
+          limit = self.class.sluggable_max_length
+          return normalized unless limit && normalized.respond_to?(:truncate)
+
+          normalized.truncate(limit, omission: "", separator: friendly_id_config.sequence_separator)
+        end
       end
 
       # class methods
@@ -65,8 +88,13 @@ module ConcernsOnRails
         #   sluggable_by :title, scope: :account_id       # slugs unique per scope column
         #   sluggable_by :title, reserved_words: %w[new]  # block these slugs (a UUID is appended instead)
         #   sluggable_by :title, finders: true            # Model.find accepts a slug directly
-        def sluggable_by(field, history: false, scope: nil, reserved_words: nil, finders: false)
+        #   sluggable_by :title, candidates: [:title, %i[title city]]   # try "title", then "title-city", then a uuid
+        #   sluggable_by :title, max_length: 60                        # truncate at a word boundary
+        def sluggable_by(field, history: false, scope: nil, reserved_words: nil, finders: false,
+                         candidates: nil, max_length: nil)
           self.sluggable_field = field.to_sym
+          self.sluggable_candidates = sluggable_validate_candidates!(candidates)
+          self.sluggable_max_length = sluggable_validate_max_length!(max_length)
           # Validate the slug column too (a missing one used to fail at first save
           # with an opaque friendly_id error); an association scope: is exempt.
           scope_column = scope && reflect_on_association(scope.to_sym) ? nil : scope
@@ -81,6 +109,28 @@ module ConcernsOnRails
 
         private
 
+        # friendly_id's candidate shapes: a Symbol/String (method), a Proc, or an
+        # Array of those (joined with the separator).
+        def sluggable_validate_candidates!(candidates)
+          return nil if candidates.nil?
+          unless candidates.is_a?(Array) && candidates.any?
+            raise ArgumentError,
+                  "#{LABEL}: candidates: must be an Array of Symbols/Procs/Arrays (got #{candidates.inspect})"
+          end
+
+          candidates
+        end
+
+        def sluggable_validate_max_length!(max_length)
+          return nil if max_length.nil?
+          unless max_length.is_a?(Integer) && max_length.positive?
+            raise ArgumentError,
+                  "#{LABEL}: max_length: must be a positive Integer (got #{max_length.inspect})"
+          end
+
+          max_length
+        end
+
         # Re-runs friendly_id with the extra modules. friendly_id merges config
         # across calls, so this layers :history / :scoped / :finders / :reserved onto :slugged.
         def reconfigure_friendly_id(history:, scope:, reserved_words: nil, finders: false)
@@ -109,9 +159,22 @@ module ConcernsOnRails
       # Example:
       #   record.slug_source
       def slug_source
+        candidates = self.class.sluggable_candidates
+        return candidates if candidates
+
         field = self.class.sluggable_field
         respond_to?(field) ? send(field) : to_s
       end
+
+      # Rebuild the slug from the current source (candidates included) and
+      # save — even over a slug that was assigned by hand, which a normal save
+      # deliberately leaves alone. Conflicts still get friendly_id's suffix.
+      def regenerate_slug!
+        @sluggable_force_regenerate = true
+        save!
+      ensure
+        @sluggable_force_regenerate = false
+      end
     end
   end
 end

data/lib/concerns_on_rails/models/sortable.rb

@@ -49,6 +49,9 @@ module ConcernsOnRails
       # Example: Task.sortable_by(priority: :asc)
       # A real module (not `class_methods do`) so the helpers aren't constrained
       # by Metrics/BlockLength (the Stateable precedent).
+      LABEL = "ConcernsOnRails::Models::Sortable".freeze
+      MISSING_MODES = %i[append raise].freeze
+
       module ClassMethods
         include ConcernsOnRails::Support::ColumnGuard
 
@@ -83,8 +86,70 @@ module ConcernsOnRails
           acts_as_list(list_options)
         end
 
+        # Apply an explicit id order as positions — the "save this drag-and-drop
+        # order" operation acts_as_list lacks — in ONE UPDATE (`SET position =
+        # CASE id WHEN … END`) inside the current relation, in a transaction.
+        # Rows in the relation but not in `ids` are pushed after them in their
+        # current order (`missing: :append`) or make the call raise
+        # (`missing: :raise`); ids outside the relation, duplicates and an
+        # unknown `missing:` raise before anything is written. The first id gets
+        # the top position; on a :desc list it gets the highest value instead.
+        # Returns the number of rows updated. Bypasses acts_as_list callbacks by
+        # design (no per-row shifting).
+        def reposition!(ids, missing: :append)
+          unless MISSING_MODES.include?(missing)
+            raise ArgumentError,
+                  "#{LABEL}: missing: must be :append or :raise (got #{missing.inspect})"
+          end
+
+          ordered = sortable_reposition_order(sortable_cast_ids(ids), missing)
+          return 0 if ordered.empty?
+
+          node = Arel::Nodes::Case.new(arel_table[primary_key])
+          sortable_positions_for(ordered).each { |id, position| node.when(id).then(position) }
+          transaction { unscoped.where(primary_key => ordered).update_all(sortable_field => node) }
+        end
+
         private
 
+        # Params arrive as Strings; compare on the primary key's own type.
+        def sortable_cast_ids(ids)
+          type = type_for_attribute(primary_key)
+          Array(ids).map { |id| type.cast(id.respond_to?(:id) ? id.id : id) }
+        end
+
+        # The relation's members in the requested order, validated: no
+        # duplicates, nothing foreign, and the unlisted rest appended (or raised).
+        def sortable_reposition_order(ids, missing)
+          duplicates = ids.tally.select { |_id, n| n > 1 }.keys
+          raise ArgumentError, "#{LABEL}: duplicate id(s) #{duplicates.join(', ')} in ids" if duplicates.any?
+
+          current = all.reorder(sortable_field => sortable_direction, primary_key => :asc).pluck(primary_key)
+          unknown = ids - current
+          raise ArgumentError, "#{LABEL}: id(s) #{unknown.join(', ')} are not in this relation" if unknown.any?
+
+          rest = current - ids
+          if rest.any? && missing == :raise
+            raise ArgumentError,
+                  "#{LABEL}: #{rest.size} record(s) in this relation are missing from ids (pass missing: :append to push them after)"
+          end
+
+          ids + rest
+        end
+
+        # [[id, position], ...] from the top of the list; reversed for :desc so
+        # the first id sorts first.
+        def sortable_positions_for(ordered)
+          top = sortable_top_of_list
+          positions = Array.new(ordered.size) { |index| top + index }
+          positions.reverse! if sortable_direction == :desc
+          ordered.zip(positions)
+        end
+
+        def sortable_top_of_list
+          method_defined?(:acts_as_list_top) ? new.acts_as_list_top : 1
+        end
+
         def resolve_sortable_config(field_config, field_options)
           if field_config.nil? && field_options.any?
             # `sortable_by position: :desc` — the trailing keywords ARE the config.

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.28.0".freeze
+  VERSION = "1.28.2".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.2
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack