plutonium 0.65.0 → 0.66.0

data/docs/reference/resource/positioning.md

@@ -1,6 +1,6 @@
 # Positioning & Drag-to-Reorder
 
-Manual ordering for a resource: a decimal `position` column on the model, a `position_on` line in the definition, and Plutonium renders a drag grip on the index **table** and the **card grid** — and on any **nested association table** of the same resource.
+Manual ordering for a resource: a decimal `position` column on the model, a `position_on` line in the definition, and Plutonium renders a drag grip on the index **table** and the **card grid**, and on any **nested association table** of the same resource.
 
 Ordering is **fractional**. A drop writes one decimal (the midpoint between its two neighbours), so the common case updates exactly one row. No `UPDATE … SET position = position + 1` sweep across the table.
 
@@ -8,12 +8,12 @@ The same machinery drives the [kanban board](/reference/kanban/), which is why a
 
 ## 🚨 Critical
 
-- **The concern is `Plutonium::Positioning::Model`, not `Plutonium::Positioning`.** This changed — see [the upgrade note](#upgrading-from-include-plutonium-positioning) before you touch anything.
+- **The concern is `Plutonium::Positioning::Model`, not `Plutonium::Positioning`.** This changed, see [the upgrade note](#upgrading-from-include-plutonium-positioning) before you touch anything.
 - **`position_on` silently sets `default_sort`** when your definition hasn't declared one. See [the warning](#what-position-on-expands-to).
 - **The model owns storage; the definition owns the UI.** `positioned_on` (model) says *how positions are stored*. `position_on` (definition) says *this list is orderable*. Never restate the column or the scope in the definition.
 - **Dragging is offered only while the collection is sorted ascending by the position attribute.** Under any other sort the grip renders as a link back to that sort, and the server rejects the drop outright.
-- **`reposition?` on the policy gates the drop.** It defaults to `update?`. Override it to let someone reorder without granting full edit access — or to forbid reordering while still allowing edits.
-- **Prefer [Mode A](#mode-a-delegate) — the framework-owned write.** A block ([Mode B](#mode-b)) is a supported escape hatch for models already ordered by a positioning gem, but it hands you semantics Mode A handles for you. Already on `acts_as_list`? [Migrating](#migrating-off-a-positioning-gem) is a column change, two lines on the model, and a backfill.
+- **`reposition?` on the policy gates the drop.** It defaults to `update?`. Override it to let someone reorder without granting full edit access, or to forbid reordering while still allowing edits.
+- **Prefer [Mode A](#mode-a-delegate): the framework-owned write.** A block ([Mode B](#mode-b)) is a supported escape hatch for models already ordered by a positioning gem, but it hands you semantics Mode A handles for you. Already on `acts_as_list`? [Migrating](#migrating-off-a-positioning-gem) is a column change, two lines on the model, and a backfill.
 
 ## Two verbs, one feature {#two-verbs-one-feature}
 
@@ -24,7 +24,7 @@ There are exactly two, and the split is deliberate:
 | `positioned_on :column, scope: :attr` | the **model** | *How are positions stored?* Which column, and what groups rows into independent orderings. |
 | `position_on` | the **definition** (and inside `kanban do…end`) | *Is this list orderable, and who writes the new position?* |
 
-The definition-layer verb is `position_on` on both a definition and a kanban board — the **same** verb, not a third one. A board with no `position_on` of its own inherits the definition's. So the framework's whole positioning vocabulary is two words, and you learn the board by learning the table.
+The definition-layer verb is `position_on` on both a definition and a kanban board, the **same** verb, not a third one. A board with no `position_on` of its own inherits the definition's. So the framework's whole positioning vocabulary is two words, and you learn the board by learning the table.
 
 ```ruby
 class Task < ApplicationRecord
@@ -43,7 +43,7 @@ That second line names neither the column nor the scope. It reads them off the m
 
 ## Quick start
 
-**1. Migration** — use the `t.position` helper. It emits a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so the scale can't be too small to rebalance cleanly. It works in `create_table` and `change_table` alike:
+**1. Migration.** Use the `t.position` helper. It emits a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so the scale can't be too small to rebalance cleanly. It works in `create_table` and `change_table` alike:
 
 ```ruby
 create_table :tasks do |t|
@@ -61,7 +61,7 @@ t.position index: true             # also add a single-column index
 t.position scale: 10               # override precision/scale
 ```
 
-**2. Model** — include the concern and declare the column:
+**2. Model.** Include the concern and declare the column:
 
 ```ruby
 class Task < ApplicationRecord
@@ -72,7 +72,7 @@ class Task < ApplicationRecord
 end
 ```
 
-**3. Definition** — one line:
+**3. Definition.** One line:
 
 ```ruby
 class TaskDefinition < Plutonium::Resource::Definition
@@ -90,11 +90,11 @@ That's it. The index table and the card grid now render a drag grip, `POST /task
 
 ---
 
-## The model layer — `Plutonium::Positioning::Model`
+## The model layer: `Plutonium::Positioning::Model`
 
 ### Upgrading from `include Plutonium::Positioning` {#upgrading-from-include-plutonium-positioning}
 
-::: danger Breaking change — the concern moved down a level
+::: danger Breaking change: the concern moved down a level
 `Plutonium::Positioning` is now a **pure namespace**. The ActiveRecord concern is `Plutonium::Positioning::Model`.
 
 ```ruby
@@ -105,9 +105,9 @@ include Plutonium::Positioning
 include Plutonium::Positioning::Model
 ```
 
-`positioned_on`, `reposition!` and `backfill_positions!` are unchanged — only the `include` line moves.
+`positioned_on`, `reposition!` and `backfill_positions!` are unchanged; only the `include` line moves.
 
-**Why it had to change.** Every constant nested inside an included module joins the including class's constant lookup. While the concern *was* `Plutonium::Positioning`, a bare `Config` written anywhere inside a positioned model resolved to `Plutonium::Positioning::Config` instead of the application's own `::Config` — silently, with no error, in a class the app author never suspected. Splitting the namespace from the mixin stops the leak: `Model` nests nothing.
+**Why it had to change.** Every constant nested inside an included module joins the including class's constant lookup. While the concern *was* `Plutonium::Positioning`, a bare `Config` written anywhere inside a positioned model resolved to `Plutonium::Positioning::Config` instead of the application's own `::Config`, silently and with no error, in a class the app author never suspected. Splitting the namespace from the mixin stops the leak: `Model` nests nothing.
 :::
 
 ### `positioned_on(column = :position, scope: nil)`
@@ -124,7 +124,7 @@ After the call the model gains:
 - `backfill_positions!(order: :created_at)` on the class.
 
 ::: warning Including the concern is not enough
-`include Plutonium::Positioning::Model` without a `positioned_on` call installs no `before_create` hook — every row is created with a `NULL` position and the list orders arbitrarily. `position_on` in the definition raises at class-load rather than let that ship.
+`include Plutonium::Positioning::Model` without a `positioned_on` call installs no `before_create` hook: every row is created with a `NULL` position and the list orders arbitrarily. `position_on` in the definition raises at class-load rather than let that ship.
 :::
 
 ### `reposition!(prev_record:, next_record:)`
@@ -139,22 +139,22 @@ task.reposition!(prev_record: last, next_record: nil)   # append
 
 It returns a `Plutonium::Positioning::Result`, whose **`rebalanced?`** tells the caller whether rows *other than this one* moved. That is the signal the drop endpoint uses to decide between "204, nothing to repaint" and "here is the whole collection back".
 
-The arithmetic, the `EPSILON = 1e-6` rebalance threshold, and the pure `Plutonium::Positioning.position_between` / `.gap_exhausted?` helpers are documented in full under [Kanban › Positioning](/reference/kanban/positioning) — the model layer is shared, so there is one description of it and both surfaces point at it.
+The arithmetic, the `EPSILON = 1e-6` rebalance threshold, and the pure `Plutonium::Positioning.position_between` / `.gap_exhausted?` helpers are documented in full under [Kanban › Positioning](/reference/kanban/positioning); the model layer is shared, so there is one description of it and both surfaces point at it.
 
 ---
 
-## The definition layer — `position_on`
+## The definition layer: `position_on`
 
 ### Four forms
 
 ```ruby
-position_on                       # Mode A — follow the model's column  ← use this
-position_on :sort_order           # Mode A — must MATCH the model's column
-position_on(:rank) { |move| … }   # Mode B — another gem owns the write (escape hatch)
-position_on false                 # Mode C — ordering off
+position_on                       # Mode A: follow the model's column  ← use this
+position_on :sort_order           # Mode A: must MATCH the model's column
+position_on(:rank) { |move| … }   # Mode B: another gem owns the write (escape hatch)
+position_on false                 # Mode C: ordering off
 ```
 
-[Mode A](#mode-a-delegate) is the one to reach for: the framework owns the write, and the bare form cannot disagree with the model. [Mode B](#mode-b) exists for models already ordered by a positioning gem — it is supported and tested, but it hands you semantics Mode A handles, so prefer [migrating off the gem](#migrating-off-a-positioning-gem) where you can.
+[Mode A](#mode-a-delegate) is the one to reach for: the framework owns the write, and the bare form cannot disagree with the model. [Mode B](#mode-b) exists for models already ordered by a positioning gem; it is supported and tested, but it hands you semantics Mode A handles, so prefer [migrating off the gem](#migrating-off-a-positioning-gem) where you can.
 
 ### What `position_on` expands to {#what-position-on-expands-to}
 
@@ -169,9 +169,9 @@ action :reposition, hidden: true      # route + policy predicate, no button
 The `sort` registration is load-bearing rather than a convenience: dragging is only permitted while the list is in ascending position order, so without a permitted sort there would be **no way back out** of the disabled state.
 
 ::: warning `position_on` claims `default_sort`
-If your definition has not declared a `default_sort`, `position_on` sets it to `<attribute>, :asc` — replacing the framework default of `id, :desc`. A resource that used to list newest-first will list in position order after you add this line.
+If your definition has not declared a `default_sort`, `position_on` sets it to `<attribute>, :asc`, replacing the framework default of `id, :desc`. A resource that used to list newest-first will list in position order after you add this line.
 
-That is almost always what you want (a hand-ordered list that ignores its own order is useless), but it is a change you did not write. To keep a different default, just declare one — **in either order**, above or below `position_on`:
+That is almost always what you want (a hand-ordered list that ignores its own order is useless), but it is a change you did not write. To keep a different default, just declare one, **in either order**, above or below `position_on`:
 
 ```ruby
 class TaskDefinition < Plutonium::Resource::Definition
@@ -180,7 +180,7 @@ class TaskDefinition < Plutonium::Resource::Definition
 end
 ```
 
-`position_on` only claims `default_sort` while nobody has declared one, so an explicit declaration always wins regardless of where it sits in the class body. Note the consequence: with a foreign default sort, the list opens **not draggable** — the grip renders as a link that applies the position sort.
+`position_on` only claims `default_sort` while nobody has declared one, so an explicit declaration always wins regardless of where it sits in the class body. Note the consequence: with a foreign default sort, the list opens **not draggable**: the grip renders as a link that applies the position sort.
 
 "Explicit" is by declaration, not by value: `default_sort :id, :desc` wins too, even though it names the same field and direction as the framework default. Writing it means you chose it.
 
@@ -192,7 +192,7 @@ class ResourceDefinition < Plutonium::Resource::Definition
 end
 
 class TaskDefinition < ResourceDefinition
-  position_on                       # inherits :created_at — NOT draggable on open
+  position_on                       # inherits :created_at: NOT draggable on open
 end
 ```
 
@@ -206,7 +206,7 @@ end
 ```
 :::
 
-### Mode A — delegate (the default) {#mode-a-delegate}
+### Mode A: delegate (the default) {#mode-a-delegate}
 
 The framework owns the write. On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`.
 
@@ -220,12 +220,12 @@ Mode A validates the model **at class-load**, with errors that name the fix:
 | Situation | Result |
 |---|---|
 | Model does not `include Plutonium::Positioning::Model` | `ArgumentError` pointing at the concern, and at Mode B as the escape hatch |
-| Model includes it but never calls `positioned_on` | `ArgumentError` — no `before_create`, so every row would sort arbitrarily |
-| `position_on :rank` while the model says `positioned_on :position` | `ArgumentError` — the list would be *ordered* by one column while `reposition!` *wrote* another, so dragging would appear to do nothing |
+| Model includes it but never calls `positioned_on` | `ArgumentError`: no `before_create`, so every row would sort arbitrarily |
+| `position_on :rank` while the model says `positioned_on :position` | `ArgumentError`, the list would be *ordered* by one column while `reposition!` *wrote* another, so dragging would appear to do nothing |
 
 That last one is why the bare form is the recommended one: it cannot disagree with the model.
 
-### Mode B — bring your own positioning gem {#mode-b}
+### Mode B: bring your own positioning gem {#mode-b}
 
 ::: tip Reach for Mode A first
 Mode A is one word in the definition. The *correct* `acts_as_list` block further down this page is fifteen lines of rank arithmetic, and writing it means already knowing three things neither library's README tells you:
@@ -234,12 +234,12 @@ Mode A is one word in the definition. The *correct* `acts_as_list` block further
 - **removing a record shifts its neighbours' ranks by one**, in a direction that depends on whether the record started above or below them;
 - **a blank `move.prev` means "nothing above me *on screen*"**, not "top of the list".
 
-These docs got two of those three wrong for a while — in the very section written to explain the first. That is the honest case for preferring Mode A. Not that Mode B is broken: it is supported, it is [tested against the real gem](#why-move-index-cannot-be-the-anchor), and the recipe below is correct. But its correctness lives in arithmetic you own and have to keep owning, and Mode A's does not.
+These docs got two of those three wrong for a while, in the very section written to explain the first. That is the honest case for preferring Mode A. Not that Mode B is broken: it is supported, it is [tested against the real gem](#why-move-index-cannot-be-the-anchor), and the recipe below is correct. But its correctness lives in arithmetic you own and have to keep owning, and Mode A's does not.
 
 Choosing today? Choose Mode A. Already on a positioning gem? [Migrating](#migrating-off-a-positioning-gem) is a column change, two lines on the model, and a backfill.
 :::
 
-Give `position_on` a block and Plutonium stops writing positions. It still **orders** the collection by the attribute you name, still renders the grip, still routes and authorizes the drop — but the block persists the new value.
+Give `position_on` a block and Plutonium stops writing positions. It still **orders** the collection by the attribute you name, still renders the grip, still routes and authorizes the drop, but the block persists the new value.
 
 The block receives a single `Plutonium::Positioning::Move`:
 
@@ -248,10 +248,10 @@ The block receives a single `Plutonium::Positioning::Move`:
 | `move.record` | the dropped record |
 | `move.prev` | the record immediately **before** the slot **on the client's page**, or `nil` |
 | `move.next` | the record immediately **after** the slot **on the client's page**, or `nil` |
-| `move.index` | 0-based insertion index among the other rows **on that page** — see [why it cannot be your anchor](#why-move-index-cannot-be-the-anchor) |
-| `move.column` | the destination kanban column key — `nil` on tables and grids, which have no columns |
+| `move.index` | 0-based insertion index among the other rows **on that page**: see [why it cannot be your anchor](#why-move-index-cannot-be-the-anchor) |
+| `move.column` | the destination kanban column key: `nil` on tables and grids, which have no columns |
 
-It is called with `call`, not `instance_exec` — `self` inside the block is wherever you wrote it.
+It is called with `call`, not `instance_exec`; `self` inside the block is wherever you wrote it.
 
 #### What the framework stops doing {#mode-b-handover}
 
@@ -259,11 +259,11 @@ A block is an opaque write. Plutonium cannot know what it touched, or against wh
 
 | | Mode A | Mode B |
 |---|---|---|
-| **Hidden boundary neighbours** | resolved server-side before the write, so a drop at the edge of a page anchors to the real row the client couldn't see | not resolved — `resolve_position_boundaries` returns early unless the config delegates. The block gets the client's viewport verbatim, `nil` and all |
+| **Hidden boundary neighbours** | resolved server-side before the write, so a drop at the edge of a page anchors to the real row the client couldn't see | not resolved, `resolve_position_boundaries` returns early unless the config delegates. The block gets the client's viewport verbatim, `nil` and all |
 | **Drop under a foreign sort** | rejected `422` before any write | not checked server-side. Only the client-side gate applies; the block owns its own notion of neighbours |
 | **Response** | `204` when nothing else moved | always `200` + a turbo-stream of the collection |
 
-That last row is not a missing optimisation. Gems in this space routinely renumber the entire group on every move — `acts_as_list` does exactly that — so the client's optimistic DOM is stale by definition. A repaint per drop is the only way the two are guaranteed to agree.
+That last row is not a missing optimisation. Gems in this space routinely renumber the entire group on every move (`acts_as_list` does exactly that), so the client's optimistic DOM is stale by definition. A repaint per drop is the only way the two are guaranteed to agree.
 
 The first two rows are the ones to weigh before choosing Mode B: they are the semantics you are taking on, and the worked example below is what taking them on looks like.
 
@@ -271,7 +271,7 @@ The first two rows are the ones to weigh before choosing Mode B: they are the se
 
 If nothing external depends on the gem's contiguous integer ranks, moving to Mode A is a column change, two lines on the model, and a backfill.
 
-**1. Change the column.** `acts_as_list` stores contiguous integers; Plutonium stores fractional decimals, and `t.position` emits `decimal(16, 8)` for exactly that reason — a whole-number column would round every midpoint straight back onto a neighbour. `t.position` *adds* a column, so an existing one wants `change_column`:
+**1. Change the column.** `acts_as_list` stores contiguous integers; Plutonium stores fractional decimals, and `t.position` emits `decimal(16, 8)` for exactly that reason: a whole-number column would round every midpoint straight back onto a neighbour. `t.position` *adds* a column, so an existing one wants `change_column`:
 
 ```ruby
 class ChangeTaskPositionToDecimal < ActiveRecord::Migration[8.0]
@@ -281,7 +281,9 @@ class ChangeTaskPositionToDecimal < ActiveRecord::Migration[8.0]
 end
 ```
 
-**2. Swap the macro on the model.** Note that `scope:` takes a bare Symbol here — the [Array-form trap](#worked-example-acts-as-list) goes away with the gem:
+Match the `ActiveRecord::Migration[...]` version to your app's existing migrations (or generate the file with `rails g migration`) rather than copying `[8.0]`.
+
+**2. Swap the macro on the model.** Note that `scope:` takes a bare Symbol here: the [Array-form trap](#worked-example-acts-as-list) goes away with the gem:
 
 ```ruby
 class Task < ApplicationRecord
@@ -299,18 +301,18 @@ end
 Task.backfill_positions!(order: :position)
 ```
 
-Then drop the block from the definition — a bare `position_on` is the whole of Mode A.
+Then drop the block from the definition; a bare `position_on` is the whole of Mode A.
 
 ::: warning `backfill_positions!` is a one-shot
-It loads the table, groups it in Ruby, and writes every row with `update_column` — no callbacks, no validations, no `updated_at`. That is what you want for a backfill and not what you want in a request. Run it from a migration or a `rails runner`, once.
+It loads the table, groups it in Ruby, and writes every row with `update_column`: no callbacks, no validations, no `updated_at`. That is what you want for a backfill and not what you want in a request. Run it from a migration or a `rails runner`, once.
 :::
 
 #### Worked example: staying on `acts_as_list` {#worked-example-acts-as-list}
 
-For when the gem is not yours to remove — another codepath calls `move_higher`, a report reads the integer ranks, or the migration simply isn't due yet. This block is correct and stays correct; it is just longer than the one word above.
+For when the gem is not yours to remove: another codepath calls `move_higher`, a report reads the integer ranks, or the migration simply isn't due yet. This block is correct and stays correct; it is just longer than the one word above.
 
 ::: danger Anchor off the neighbours, never off `move.index`
-`insert_at(move.index + 1)` is the obvious block to write and it is **wrong on any list that paginates or filters** — which, since Plutonium paginates every index at 20 rows by default, means wrong on any list with 21 rows in it. The numbers are in [Why `move.index` cannot be the anchor](#why-move-index-cannot-be-the-anchor). Use the block below.
+`insert_at(move.index + 1)` is the obvious block to write and it is **wrong on any list that paginates or filters**, which, since Plutonium paginates every index at 20 rows by default, means wrong on any list with 21 rows in it. The numbers are in [Why `move.index` cannot be the anchor](#why-move-index-cannot-be-the-anchor). Use the block below.
 :::
 
 ```ruby
@@ -326,7 +328,7 @@ class Task < ApplicationRecord
 end
 
 class TaskDefinition < Plutonium::Resource::Definition
-  # No Plutonium::Positioning::Model, no positioned_on — acts_as_list owns
+  # No Plutonium::Positioning::Model, no positioned_on: acts_as_list owns
   # both the column and the write. Plutonium only orders, routes and authorizes.
   position_on :position do |move|
     record = move.record
@@ -334,7 +336,7 @@ class TaskDefinition < Plutonium::Resource::Definition
     target =
       if move.prev
         # Land immediately after prev. When the record currently sits ABOVE
-        # prev, removing it shifts prev up one — so prev's own rank is already
+        # prev, removing it shifts prev up one: so prev's own rank is already
         # the slot the record should occupy.
         (record.position > move.prev.position) ? move.prev.position + 1 : move.prev.position
       elsif move.next
@@ -351,19 +353,19 @@ class TaskDefinition < Plutonium::Resource::Definition
 end
 ```
 
-`insert_at(n)` in `acts_as_list` means "end up at rank `n` after the move", and every rank in the expression above is a **real** rank read off a neighbour record — never a viewport offset. `default_sort :position, :asc` is registered for you, which is exactly the order `acts_as_list` maintains.
+`insert_at(n)` in `acts_as_list` means "end up at rank `n` after the move", and every rank in the expression above is a **real** rank read off a neighbour record, never a viewport offset. `default_sort :position, :asc` is registered for you, which is exactly the order `acts_as_list` maintains.
 
 Both the `elsif move.next` branch and the `else 1` are load-bearing. A blank `prev` means "nothing above me **on my screen**"; falling straight through to rank 1 sends the row to the top of the whole list, past every row the page or the filter hid.
 
 ::: tip `insert_at` swallows a failed save
-`insert_at` calls `save`, not `save!`, so a record that fails validation mid-move silently no-ops — the drop answers `200` and the streamed collection shows the row back where it started. Use `insert_at!` if you would rather the endpoint surface the errors as a `422` with a toast — the validation-failure row of [the response table](#the-endpoint).
+`insert_at` calls `save`, not `save!`, so a record that fails validation mid-move silently no-ops; the drop answers `200` and the streamed collection shows the row back where it started. Use `insert_at!` if you would rather the endpoint surface the errors as a `422` with a toast, the validation-failure row of [the response table](#the-endpoint).
 :::
 
 #### Why `move.index` cannot be the anchor {#why-move-index-cannot-be-the-anchor}
 
-Plutonium hands a Mode B block the client's neighbours **verbatim** — it does not look up the rows pagination or a filter hid, the way Mode A does. So `move.index` is a claim about the **viewport**, while `insert_at` addresses the **whole scope group**. The two only agree on an unfiltered page 1.
+Plutonium hands a Mode B block the client's neighbours **verbatim**; it does not look up the rows pagination or a filter hid, the way Mode A does. So `move.index` is a claim about the **viewport**, while `insert_at` addresses the **whole scope group**. The two only agree on an unfiltered page 1.
 
-These are measured, not reasoned — `test/plutonium/resource/controllers/position_actions_acts_as_list_test.rb` drives each one through `POST <member>/reposition` against the real gem:
+These are measured, not reasoned: `test/plutonium/resource/controllers/position_actions_acts_as_list_test.rb` drives each one through `POST <member>/reposition` against the real gem:
 
 | List | Gesture | `insert_at(move.index + 1)` | Anchored off neighbours |
 |---|---|---|---|
@@ -372,15 +374,15 @@ These are measured, not reasoned — `test/plutonium/resource/controllers/positi
 | 10 rows, filter shows ranks 1 and 10 | drag rank 1 below the filtered row at rank 10 (`to_index: 1`) | `insert_at(2)` → the row moves **one slot**, staying at the top | rank **10**, below the hidden rows |
 | 10 rows, filter shows ranks 5 and 10 | drag rank 10 above the filtered row at rank 5 (`prev_id` blank, `to_index: 0`) | `insert_at(1)` → **rank 1**, above four rows the filter hid | rank **5**, immediately above the row it was dropped on |
 
-Mode A has none of this to think about: it resolves hidden boundary neighbours server-side before the write (see [Nested resources & scope groups](#nested-resources-scope-groups)). Mode B is a real escape hatch and the block above is a correct one — the price of the hatch is simply that the semantics are yours. If nothing outside the gem depends on those integer ranks, [the migration](#migrating-off-a-positioning-gem) hands them back.
+Mode A has none of this to think about: it resolves hidden boundary neighbours server-side before the write (see [Nested resources & scope groups](#nested-resources-scope-groups)). Mode B is a real escape hatch and the block above is a correct one; the price of the hatch is simply that the semantics are yours. If nothing outside the gem depends on those integer ranks, [the migration](#migrating-off-a-positioning-gem) hands them back.
 
-### Mode C — disabled
+### Mode C: disabled
 
 ```ruby
 position_on false
 ```
 
-No ordering is applied (the relation passes through unchanged), no `sort`/`default_sort` is registered, no `reposition` action is created, and the endpoint answers **404**. Useful to switch a resource's ordering off in one portal while another keeps it — see [portal overrides](/reference/resource/definition).
+No ordering is applied (the relation passes through unchanged), no `sort`/`default_sort` is registered, no `reposition` action is created, and the endpoint answers **404**. Useful to switch a resource's ordering off in one portal while another keeps it; see [portal overrides](/reference/resource/definition).
 
 ### Kanban boards inherit the definition's `position_on`
 
@@ -407,7 +409,7 @@ class TaskDefinition < Plutonium::Resource::Definition
 end
 ```
 
-Resolution is **lazy**, so declaration order in the class body does not matter — a `kanban do…end` written above `position_on` still picks it up.
+Resolution is **lazy**, so declaration order in the class body does not matter, a `kanban do…end` written above `position_on` still picks it up.
 
 ---
 
@@ -415,14 +417,14 @@ Resolution is **lazy**, so declaration order in the class body does not matter
 
 A drop says "put me between these two rows". That only describes a position when the **visual order is the stored order**. Under a title sort the neighbours say nothing; under a *descending* position sort they say the opposite of what the write would assume.
 
-So the grip is live only when the collection is sorted **ascending, by the position attribute, and by nothing else** — whether that comes from the default sort or from the user clicking the column header. Both halves of the feature enforce the same rule from the same predicate:
+So the grip is live only when the collection is sorted **ascending, by the position attribute, and by nothing else**, whether that comes from the default sort or from the user clicking the column header. Both halves of the feature enforce the same rule from the same predicate:
 
-- **Client** — the Stimulus controller is not even attached under a foreign sort. There is nothing to drag against.
-- **Server** — a Mode A drop arriving under a foreign sort is rejected with `422` **before any write**, and the collection is streamed back with a toast. (Mode B has no server-side sort check: the block owns its own notion of neighbours, so only the client-side gate applies.)
+- **Client**: the Stimulus controller is not even attached under a foreign sort. There is nothing to drag against.
+- **Server**: a Mode A drop arriving under a foreign sort is rejected with `422` **before any write**, and the collection is streamed back with a toast. (Mode B has no server-side sort check: the block owns its own notion of neighbours, so only the client-side gate applies.)
 
 ### The disabled grip is the way out of the disabled state
 
-Under a foreign sort the grip does not disappear — it renders as a **link that applies the ascending position sort**. Hiding it would leave the user with no hint that the list is reorderable at all, and no way to make it so. This is precisely why `position_on` registers `sort <attribute>`.
+Under a foreign sort the grip does not disappear; it renders as a **link that applies the ascending position sort**. Hiding it would leave the user with no hint that the list is reorderable at all, and no way to make it so. This is precisely why `position_on` registers `sort <attribute>`.
 
 Per record, the grip is also gated on `reposition?`: a row this viewer may not reorder renders exactly as it did before, with no grip at all. Offering an affordance that can only ever answer `403` is worse than offering none.
 
@@ -439,20 +441,20 @@ Per record, the grip is also gated on `reposition?`: a row this viewer may not r
 
 On a table the grip sits *inside* the first cell, pulled left into padding the cell already had, so the cell's content does not shift by a pixel whether the grip is there or not. It appears on hover, and on keyboard focus.
 
-::: details Why only the grip is draggable on a table — but the whole card is on a board
+::: details Why only the grip is draggable on a table, but the whole card is on a board
 Two concrete costs of making a `<tr>` draggable, both silent regressions on an ordinary data table:
 
 1. **`draggable="true"` disables text selection inside the element** in every major browser. On a data table that quietly removes the ability to select and copy a cell value.
 2. **`row_click_controller` makes the whole row the Show affordance.** A draggable row fights it: a drag that starts and ends in place still fires a click, and the user is navigated away instead of left where they were.
 
-Neither applies to a kanban card — it has no cell text to select and no row-click behaviour — so the board keeps whole-card dragging, which is the better gesture where you can afford it. The inconsistency is deliberate.
+Neither applies to a kanban card: it has no cell text to select and no row-click behaviour, so the board keeps whole-card dragging, which is the better gesture where you can afford it. The inconsistency is deliberate.
 
 A **grid** card gets a grip rather than whole-card dragging, because unlike a kanban card it *does* carry a row-click show affordance: reason 2 applies to it exactly as it does to a table row.
 :::
 
 ---
 
-## The endpoint — `POST <member>/reposition` {#the-endpoint}
+## The endpoint: `POST <member>/reposition` {#the-endpoint}
 
 Mounted on every resource (like the kanban move routes). Resources that declare no `position_on` answer `404`.
 
@@ -461,19 +463,19 @@ POST /tasks/42/reposition?<the collection's own query string>
      prev_id=41&next_id=43&to_index=2
 ```
 
-The trailing query string is load-bearing, not decoration: it is the index's own query — search, filters, scope, sort, page, view — and it is what lets the endpoint re-render **exactly the page the user is looking at** through the ordinary index pipeline. Page 3 of a filtered list comes back as page 3 of that filtered list.
+The trailing query string is load-bearing, not decoration: it is the index's own query (search, filters, scope, sort, page, view), and it is what lets the endpoint re-render **exactly the page the user is looking at** through the ordinary index pipeline. Page 3 of a filtered list comes back as page 3 of that filtered list.
 
 The client moves the row **optimistically**, so the response is deliberately quiet in the common case:
 
 | Outcome | Response |
 |---|---|
-| Clean Mode A drop, both neighbours resolved | `204 No Content` — nothing repaints |
+| Clean Mode A drop, both neighbours resolved | `204 No Content`: nothing repaints |
 | `reposition!` had to rebalance the group | `200` + turbo-stream of the collection |
-| A neighbour did not resolve, or belongs to another positioning group, but the other one anchored the drop | `200` + stream — the record **did** move, so there is nothing to explain |
-| Both neighbours rejected | `200` + stream, **no write** — plus a toast when the cause was a foreign group rather than transient drift |
+| A neighbour did not resolve, or belongs to another positioning group, but the other one anchored the drop | `200` + stream, the record **did** move, so there is nothing to explain |
+| Both neighbours rejected | `200` + stream, **no write**: plus a toast when the cause was a foreign group rather than transient drift |
 | Mode B (opaque block write) | `200` + stream |
 | `reposition?` denied | `403` + stream + toast (the row snaps back) |
-| `index?` denied | `403`, **no body** — you may not see the list, so the refusal must not carry it to you |
+| `index?` denied | `403`, **no body**: you may not see the list, so the refusal must not carry it to you |
 | Mode A drop under a foreign sort | `422` + stream + toast, **no write** |
 | Validation failure, or the record was destroyed meanwhile | `422` + stream + toast |
 | No `position_on`, Mode C, or the kanban view is selected | `404` |
@@ -489,7 +491,7 @@ end
 
 Two checks run, in this order:
 
-1. **`index?` on the resource class.** You must be able to *see* a list to reorder it — without this, a policy with `index? == false` but `update? == true` would be handed the whole listing by the reconciliation render.
+1. **`index?` on the resource class.** You must be able to *see* a list to reorder it; without this, a policy with `index? == false` but `update? == true` would be handed the whole listing by the reconciliation render.
 2. **`reposition?` on the record.**
 
 The same `reposition?` decides whether the grip renders at all, per row.
@@ -514,12 +516,12 @@ Each product's variants are numbered independently. A rebalance touches one prod
 **Positioned globally, rendered nested:**
 
 ```ruby
-positioned_on :position          # scope: nil — one ordering across the whole table
+positioned_on :position          # scope: nil: one ordering across the whole table
 ```
 
-Reordering within one parent still works correctly. Positions interleave across parents (product A holds `1.0, 3.0, 5.0` while product B holds `2.0, 4.0`), but because the list is ordered *by position*, the relative order inside A is exactly what the user sees and drags. And when a drop lands at the top or bottom of the visible page, the server looks up the real boundary neighbour in the model's group rather than taking `nil` at face value — which is what stops a bottom-of-page drop writing a position that duplicates a row the client could not see.
+Reordering within one parent still works correctly. Positions interleave across parents (product A holds `1.0, 3.0, 5.0` while product B holds `2.0, 4.0`), but because the list is ordered *by position*, the relative order inside A is exactly what the user sees and drags. And when a drop lands at the top or bottom of the visible page, the server looks up the real boundary neighbour in the model's group rather than taking `nil` at face value, which is what stops a bottom-of-page drop writing a position that duplicates a row the client could not see.
 
-The one thing that leaks is a **rebalance**: gap exhaustion renumbers the whole *model-level* group, which with `scope: nil` is every row in the table, including other parents'. Positions stay in the same relative order, so nothing visibly moves — but far more rows are written than the user's gesture suggests. If a resource is normally viewed per-parent, scope it per-parent.
+The one thing that leaks is a **rebalance**: gap exhaustion renumbers the whole *model-level* group, which with `scope: nil` is every row in the table, including other parents'. Positions stay in the same relative order, so nothing visibly moves, but far more rows are written than the user's gesture suggests. If a resource is normally viewed per-parent, scope it per-parent.
 
 ::: tip A neighbour from another group is drift, not an anchor
 When the model *is* scoped, the endpoint rejects a neighbour id that resolves to a row in a **different** scope group and reconciles instead. This is not exotic: a `scope: :status` resource lists several groups in one table, with independent and freely interleaved numberings, so anchoring off a neighbour from another group would fling the record to an arbitrary point in its own.
@@ -529,12 +531,12 @@ When the model *is* scoped, the endpoint rejects a neighbour id that resolves to
 
 ## Hidden actions
 
-`position_on` registers `action :reposition, hidden: true`. The flag is general — see [Actions › Hidden actions](/reference/resource/actions#hidden-actions).
+`position_on` registers `action :reposition, hidden: true`. The flag is general; see [Actions › Hidden actions](/reference/resource/actions#hidden-actions).
 
 A hidden action has a live route, a policy predicate, and (if interactive) the full form/params machinery. It simply renders in **no** toolbar, row dropdown, card, or bulk bar. It is how the framework exposes an endpoint reachable by a gesture rather than a button.
 
 ::: danger `hidden: true` is a display gate, NOT an authorization boundary
-The route is live. Anyone who can construct the URL can `POST` to it. Authorization lives in the policy — `def reposition?` — and runs whether or not anything rendered.
+The route is live. Anyone who can construct the URL can `POST` to it. Authorization lives in the policy (`def reposition?`) and runs whether or not anything rendered.
 :::
 
 ---
@@ -548,22 +550,22 @@ The route is live. Anyone who can construct the URL can `POST` to it. Authorizat
 | <kbd>↑</kbd> | move the row/card one slot earlier |
 | <kbd>↓</kbd> | move it one slot later |
 
-Focus travels with the row — including across a rebalance, where the whole collection is replaced and focus is restored onto the same record's new grip.
+Focus travels with the row, including across a rebalance, where the whole collection is replaced and focus is restored onto the same record's new grip.
 
 Arrow navigation is deliberately **linear on a grid too**: <kbd>↑</kbd> means the previous *card* in reading order, not the card one line above. A single position attribute stores a one-dimensional order, and two-dimensional navigation could not express the in-between slots at all.
 
 ::: warning Drag does not work on touch devices
 The drag gesture uses **native HTML5 drag-and-drop**, which browsers do not fire from touch input. This limitation is inherited from the kanban board and applies identically here. Touch users cannot drag to reorder.
 
-There is no automatic fallback. If touch reordering matters for your resource, expose an explicit ordering path — a "move up"/"move down" pair of [record actions](/reference/resource/actions), or a numeric position field on the edit form.
+There is no automatic fallback. If touch reordering matters for your resource, expose an explicit ordering path: a "move up"/"move down" pair of [record actions](/reference/resource/actions), or a numeric position field on the edit form.
 :::
 
 ---
 
 ## Related
 
-- [Kanban › Positioning](/reference/kanban/positioning) — the shared model API in full: arithmetic, `EPSILON`, rebalancing, `backfill_positions!`, the pure helpers
-- [Kanban › DSL](/reference/kanban/dsl) — `position_on` inside `kanban do…end`
-- [Actions](/reference/resource/actions) — `hidden:`, `condition:`, and the policy rule
-- [Query](/reference/resource/query) — `sort`, `default_sort`
-- [Nested resources](/reference/tenancy/nested-resources) — nested association tables
+- [Kanban › Positioning](/reference/kanban/positioning): the shared model API in full: arithmetic, `EPSILON`, rebalancing, `backfill_positions!`, the pure helpers
+- [Kanban › DSL](/reference/kanban/dsl): `position_on` inside `kanban do…end`
+- [Actions](/reference/resource/actions): `hidden:`, `condition:`, and the policy rule
+- [Query](/reference/resource/query): `sort`, `default_sort`
+- [Nested resources](/reference/tenancy/nested-resources): nested association tables

data/docs/reference/resource/query.md

@@ -68,10 +68,10 @@ end
 
 ### Search powers typeahead too
 
-The same `search` block drives **typeahead lookups** on association inputs that target this resource — when you write `input :author, …` for an association, the dropdown's autocomplete calls the target resource's `search` block.
+The same `search` block drives **typeahead lookups** on association inputs that target this resource: when you write `input :author, …` for an association, the dropdown's autocomplete calls the target resource's `search` block.
 
 ::: tip Typeahead fallback when there's no search block
-A resource without a `search` block still gets typeahead — the framework runs a case-insensitive `LIKE` against the first column that exists, in priority order:
+A resource without a `search` block still gets typeahead: the framework runs a case-insensitive `LIKE` against the first column that exists, in priority order:
 
 1. The input's `label_method:` option, if it names a real column on the model.
 2. Otherwise the first match from `[name, title, label, slug, display_name, email]`.
@@ -84,7 +84,7 @@ For large tables, write an explicit `search` block backed by a trigram or full-t
 
 Six built-in filter types. Use the shorthand symbol or the full class name.
 
-`search`, `scope`, `sort_fields`, and `sort_directions` are reserved filter names — they're built-in controls in the `q[<name>]` namespace, so `filter :scope` raises `ArgumentError`.
+`search`, `scope`, `sort_fields`, and `sort_directions` are reserved filter names; they're built-in controls in the `q[<name>]` namespace, so `filter :scope` raises `ArgumentError`.
 
 | Type | Symbol | Params in URL | Options |
 |---|---|---|---|
@@ -191,7 +191,7 @@ class PostDefinition < ResourceDefinition
   scope :published    # uses Post.published
   scope :draft        # uses Post.draft
 
-  # Inline scope — block runs with the scope as argument
+  # Inline scope: block runs with the scope as argument
   scope(:recent)   { |s| s.where('created_at > ?', 1.week.ago) }
   scope(:this_month) { |s| s.where(created_at: Time.current.all_month) }
 end
@@ -216,9 +216,9 @@ When a default is set:
 - The default scope button is highlighted (not "All").
 - Clicking "All" shows the unscoped collection.
 
-### Conditional visibility — `condition:`
+### Conditional visibility: `condition:`
 
-Like `condition:` on [actions](./actions), a scope can be **defined but only render its button when a runtime proc is truthy**. The scope (and its URL) stays live either way — `condition:` only toggles the button.
+Like `condition:` on [actions](./actions), a scope can be **defined but only render its button when a runtime proc is truthy**. The scope (and its URL) stays live either way; `condition:` only toggles the button.
 
 ```ruby
 scope :admin_only,   condition: -> { current_user.admin? }
@@ -228,7 +228,7 @@ scope :beta_feature, condition: -> { params[:beta] == "1" }
 scope :internal, condition: -> { false }
 ```
 
-The proc is evaluated against the view context so `current_user`, `params`, `request`, and `allowed_to?` are all available directly. There is no `object`/`record` — scopes have no single-record context.
+The proc is evaluated against the view context so `current_user`, `params`, `request`, and `allowed_to?` are all available directly. There is no `object`/`record`; scopes have no single-record context.
 
 ::: danger `condition:` is NOT authorization
 A hidden scope button still has a **live URL** anyone can navigate to. `condition:` decides whether the *button renders*, not whether the *records are accessible*.
@@ -316,12 +316,12 @@ scope :this_month
 - **Add indexes** for filtered and sorted columns.
 - **Use `.distinct`** when joining associations in search to avoid duplicate rows.
 - **Prefer scopes over filters** for queries used often (faster, no input parsing).
-- **`pg_search` / FTS** for complex search — write an explicit `search` block.
-- **`LIKE '%q%'` can't use a b-tree index** — the typeahead fallback and naive search blocks get slow on large tables. Plan a trigram or full-text index when scaling.
+- **`pg_search` / FTS** for complex search: write an explicit `search` block.
+- **`LIKE '%q%'` can't use a b-tree index**: the typeahead fallback and naive search blocks get slow on large tables. Plan a trigram or full-text index when scaling.
 
 ## Related
 
-- [Definition](./definition) — field/input/display configuration
-- [Actions](./actions) — custom and bulk actions
-- [Behavior › Policy](/reference/behavior/policies) — `relation_scope` (filters records to what the user can see)
-- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — multi-tenant filtering
+- [Definition](./definition): field/input/display configuration
+- [Actions](./actions): custom and bulk actions
+- [Behavior › Policy](/reference/behavior/policies): `relation_scope` (filters records to what the user can see)
+- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping): multi-tenant filtering