plutonium 0.60.5 → 0.62.0

data/docs/reference/kanban/dsl.md

@@ -0,0 +1,334 @@
+# Kanban DSL Reference
+
+::: warning Experimental
+Kanban boards are experimental — the DSL and behavior may change in a future release.
+:::
+
+Complete reference for the `kanban do…end` block declared inside a resource Definition.
+
+## Entry point
+
+```ruby
+class PostDefinition < ResourceDefinition
+  kanban do
+    # board-level options + column declarations
+  end
+end
+```
+
+Calling `kanban` automatically adds `:kanban` to `defined_index_views`. To set it as the default view:
+
+```ruby
+default_index_view :kanban
+```
+
+To make it the only view:
+
+```ruby
+index_views :kanban
+kanban do ... end
+```
+
+---
+
+## Board-level options
+
+### `per_column(n)`
+
+```ruby
+per_column 25
+```
+
+Maximum cards rendered per column. When the column total exceeds `n`, a `+N more` footer appears. Column actions with `on: :all` still operate against the full column set; `on: :visible` is capped to the rendered subset.
+
+Default: `nil` (unlimited).
+
+---
+
+### `position_on`
+
+Controls how card positions are persisted after a drag-and-drop. Three modes:
+
+#### Mode A — delegate to `Plutonium::Positioning` (default)
+
+```ruby
+# Default: uses :position attribute
+# (no explicit call needed if the model includes Plutonium::Positioning)
+
+# Custom attribute name:
+position_on :sort_order
+```
+
+Requires the model to:
+1. `include Plutonium::Positioning`
+2. Call `positioned_on :position, scope: :grouping_attribute`
+3. Have a `decimal` column for the position attribute — add it with the `t.position` migration helper (a tuned `decimal(16,8)`) — see [Positioning › Migration](/reference/kanban/positioning#migration)
+
+On drop, calls `record.reposition!(prev_record:, next_record:)` which computes the decimal midpoint and updates the record.
+
+#### Mode B — BYO block
+
+```ruby
+position_on :sort_order do |move|
+  # move is a Plutonium::Kanban::Positioning::Move value object:
+  #   move.record  — the dropped ActiveRecord record
+  #   move.column  — destination column key (Symbol)
+  #   move.prev    — record immediately before the insertion slot, or nil
+  #   move.next    — record immediately after the insertion slot, or nil
+  #   move.index   — 0-based insertion index within the destination column
+  move.record.update!(sort_order: compute_position(move.prev, move.next))
+end
+```
+
+The block is evaluated via `call` (not `instance_exec`) — it is a plain Ruby proc/lambda.
+
+Plutonium still orders column cards by `sort_order` (the first argument); your block is responsible only for persisting the new value.
+
+#### Mode C — disabled
+
+```ruby
+position_on false
+```
+
+No ordering is applied. Cards render in the relation's natural order. On drop, only `on_enter` fires (if set); the position attribute is never touched.
+
+---
+
+### `realtime(v = true)` {#realtime}
+
+```ruby
+realtime true
+```
+
+Enables ActionCable broadcasting after every successful move. After a drop, Plutonium pushes the refreshed column frames to all viewers subscribed to this board's stream.
+
+**Stream name format:**
+
+```
+["kanban", "<tenant_gid_or_global>", "<ResourceClass.name>"]
+```
+
+- Tenant-scoped portals use the entity's Global ID parameter as the second segment.
+- Portals without entity scoping use the literal string `"global"`.
+
+Two viewers share a stream only if they have the same resource class **and** the same scoped entity — cross-tenant leakage is impossible by construction.
+
+Requires `turbo-rails` + ActionCable (gems), a cable adapter in `config/cable.yml` (Redis/Solid Cable in multi-process production), ActionCable mounted at `/cable`, **and** an ActionCable client loaded in your app's JavaScript. Plutonium's bundle ships `@hotwired/turbo` only — without `@hotwired/turbo-rails` (or `@rails/actioncable`) in your pack, the `<turbo-cable-stream-source>` never connects and other viewers won't update. Server-side broadcasting works regardless; this is purely the client subscription. See the [guide's Realtime setup](/guides/kanban#setup-required-for-realtime-to-actually-update-other-viewers).
+
+Default: `false`.
+
+---
+
+### `lazy(v = true)`
+
+```ruby
+lazy false   # eager-load all columns on initial page request
+```
+
+When `true` (the default), each column is a Turbo Frame that loads its card list on demand (lazy loading). The frame loads when it enters the viewport.
+
+When `false`, all column frames are loaded in the initial page request (one HTTP request per column).
+
+---
+
+### `show_in(mode)` {#show_in}
+
+```ruby
+show_in :modal   # open a card's show page in a centered modal dialog
+show_in :page    # navigate the whole page to the show route
+```
+
+Overrides — **for this board** — where clicking a card opens the record's show page:
+
+- `:modal` — the card's show link targets the layout's `remote_modal` frame, so the show page renders in a **centered** dialog. (Show is always centered — deliberately not the definition's `modal_mode`, which styles `new`/`edit`.)
+- `:page` — the card's show link targets `_top`, navigating the whole page to the show route.
+
+When `show_in` is **not** set on the board, the board inherits the definition's [`show_in`](/reference/resource/definition#show_in) (which itself defaults to `:page`). So to open cards in a modal you can set it on the board, or once on the definition (which also covers the table and grid views).
+
+Either mode escapes the column's lazy turbo-frame — `:page` replaces the whole page, and the `remote_modal` frame lives in the layout (resolved document-wide), so it opens outside the column. No per-card configuration is needed; the show page detects the modal frame (`in_modal?`) and wraps its details in the centered modal chrome. From inside the modal, an expand icon (or ⌘/Ctrl-click on the card) opens the full page in a new tab.
+
+An unknown mode raises `ArgumentError`.
+
+---
+
+### `card_fields(**slots)`
+
+```ruby
+card_fields(
+  header: :title,
+  subheader: :assignee,
+  meta: [:due_date, :priority]
+)
+```
+
+Overrides the slot layout for every kanban card on this board, using the same slot names as `grid_fields` (`:image`, `:header`, `:subheader`, `:body`, `:meta`, `:footer`). The kanban card renderer resolves its slots as `card_fields || definition.grid_fields`, so a board-level `card_fields` takes precedence over the resource's `grid_fields`.
+
+When `card_fields` is not set, cards fall back to the resource definition's `grid_fields`. If neither is declared, the card renders the default header-only layout.
+
+The `meta` slot renders each field as a colored badge, and formats values by type before badging: a `has_cents` field renders as currency, a `belongs_to` association renders as its label (not an object inspect), and everything else is humanized — with status-like enums (`active`, `pending`, `published`…) resolving to a semantic color. The badge color is deterministic per value, so a given status is the same color on every card.
+
+---
+
+## Static columns
+
+Declare columns at class-load time:
+
+```ruby
+kanban do
+  column :todo,
+    label: "To Do",
+    color: :blue,
+    scope: -> { where(status: "todo") },
+    on_enter: ->(r) { r.update!(status: "todo") },
+    role: :backlog
+
+  column :done,
+    scope: -> { where(status: "done") },
+    on_enter: :mark_done!,
+    accepts: [:doing],
+    role: :done do
+    action :archive_all, interaction: ArchiveTasksInteraction, on: :all
+  end
+end
+```
+
+### Column options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label:` | String | `key.to_s.titleize` | Column header label |
+| `color:` | Symbol or String | `nil` | Header color dot. Named colors: `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`. Raw CSS string also accepted |
+| `scope:` | Symbol or Proc | `nil` | Relation filter for this column. **Symbol** → `relation.public_send(sym)` (named AR scope). **Proc** → 0-arg lambda called via `instance_exec` on the relation, e.g. `-> { where(status: "todo") }` |
+| `on_enter:` | Symbol or Proc | `nil` | Fired when a card is dropped into this column. **Symbol** → `record.public_send(sym)`. **Proc** → 1-arg lambda `->(record) { … }` where `self` inside the block is the view context (giving access to `current_user`, helpers, etc.). The callback may assign attributes in memory (`r.status = :done`) or call `update!` directly; if the record has unsaved changes after `on_enter` returns the controller saves it automatically. |
+| `on_exit:` | Symbol or Proc | `nil` | The source-side counterpart to `on_enter:`, fired when a card **leaves** this column on a cross-column move. Same dispatch (**Symbol** → `record.public_send`; **Proc** → 1-arg lambda, `self` = view context). Runs **before** the destination's `on_enter`, inside the same move transaction, so it sees the pre-move state and rolls back if the move fails. Use it for source-tied side effects the destination can't own (stop a timer, release a slot). Fires only on a drag-move through `kanban_move` — not on destroy, a programmatic status change, or quick-add. Skipped on same-column reorders. |
+| `enter_interaction:` | Class | `nil` | A **record-scoped** interaction class (declares `attribute :resource`) run when a card is dropped **into** this column from another column. Opens the interaction's form as a modal to collect input, then commits `on_enter` + the interaction + repositioning atomically. Auto-registered as a hidden record action under a column-scoped key (`:<column>_enter_interaction`), authorized by `kanban_move?` (no policy method of its own). See [enter_interaction](#drop-interaction) below |
+| `role:` | `:backlog`, `:done`, `:lost` | `nil` | Applies a preset (see below) |
+| `collapsed:` | Boolean | `false` | Column starts collapsed (a thin strip with the label rotated). The Stimulus controller persists the toggled state to `localStorage` (key: `pu-kanban:<path>:<column-key>:collapsed`) so the user preference survives page reloads; this DSL value sets the server-rendered initial state only. |
+| `add:` | Boolean | `false` | Show a `+ Add` quick-add button |
+| `accepts:` | `true`, `false`, or Array | `true` | Drop policy — **structural topology only**. `true` accepts any source column. `false` rejects all drops (display-only column). An Array of column key symbols accepts only those sources. This is client-hintable: the value is emitted as `data-kanban-accepts` so the drag UI greys out disallowed source columns before the drop. **Record- or user-conditional rules do not belong here** — put them in `kanban_move?`, which sees the record and the `from`/`to` columns (see [Authorization](./authorization)). Passing a `Proc` raises `ArgumentError`. |
+| `locked:` | Boolean | `false` | Prevent dragging cards **out of** this column |
+| `wip:` | Integer | `nil` | WIP limit. Reject cross-column drops when `dest_count + 1 > wip`. Has no effect on same-column reordering |
+
+::: warning Renamed: `on_drop:` → `on_enter:`, `drop_interaction:` → `enter_interaction:`
+The older `on_drop:` and `drop_interaction:` option names have been **renamed** to `on_enter:` and `enter_interaction:` (a card *entering* a column is the event, independent of how it got there).
+
+The old names are **deprecated aliases**:
+- In **development and test** they raise an `ArgumentError` so the rename is caught before release.
+- In **deployed environments** (production, staging) they log a deprecation warning and map onto the new option, so an in-flight deployment keeps working across the upgrade.
+
+If both the old and new name are given, the new one wins. Update your definitions to `on_enter:` / `enter_interaction:` at your earliest convenience — a future release will drop the aliases entirely.
+:::
+
+### Role presets
+
+| Role | Equivalent options |
+|------|--------------------|
+| `:backlog` | `add: true` |
+| `:done` | `color: :green, collapsed: true` |
+| `:lost` | `color: :red, collapsed: true` |
+
+`:done` and `:lost` are the two terminal roles — both collapsed by default, the
+colour signalling the outcome (`:done` = positive close, `:lost` = negative
+close). Use them as the won/lost pair in pipelines (leads, deals, tickets).
+
+Explicitly passed options override the preset. Unknown role values raise `ArgumentError`.
+
+### `enter_interaction:` {#drop-interaction}
+
+```ruby
+column :lost,
+  scope: -> { where(status: "lost") },
+  enter_interaction: MarkLostInteraction
+```
+
+Runs an authorization-aware, input-collecting interaction when a card is dropped **into** this column from another column.
+
+- **Must be a record-scoped interaction** — the class declares `attribute :resource` (singular) and acts on the one dropped card. A `resources`-plural (bulk) interaction is not valid here; that shape is for [column actions](#column-actions).
+- **Auto-registered as a hidden record action** under a column-scoped key (`:lost` → `:lost_enter_interaction`) — unique by construction, so two columns can reuse the same interaction class without colliding. Hidden = it does not render as an action button on the show page, table rows, or grid cards; it is reachable only by a drop.
+- **Authorized by `kanban_move?` alone** — the interaction has **no policy method of its own**. The move (and therefore the interaction) is gated by the single `kanban_move?` predicate, which can gate this specific transition via its `to` column context (e.g. `def kanban_move? = kanban_to&.key == :lost ? user.manager? : super`). See [Authorization](./authorization).
+- **Move flow only.** Dropping cross-column opens the interaction's form as a modal; on submit `on_enter` + the interaction + repositioning commit in **one atomic transaction**. Validation failure rolls the whole transaction back (membership write included) and re-renders the modal with errors — nothing persists. Same-column reorders run positioning only (neither `on_enter` nor the interaction fires).
+- **Quick-add (`+ Add`)** applies `on_enter` + positioning **post-create** — the record is created first (needs a grouping-column default), then `on_enter` places it in the column; the `enter_interaction` is not involved.
+- **Author contract** — when a column declares both, `on_enter` owns the membership attribute (e.g. `status`) and the interaction owns the extras (reason, mail, audit). If the interaction also writes the membership attribute it must set the same value `on_enter` does (idempotent). With no `on_enter`, the interaction owns everything.
+- **Success response limitation** — the interaction's success **message** (`.with_message`) surfaces as a toast, but a custom success *response* (`with_redirect_response`, `with_file_response`, …) is **not** honored on the drop path; the board just re-renders and closes the modal.
+
+See the [guide's Interaction on drop section](/guides/kanban#interaction-on-drop) for a full worked example.
+
+---
+
+## Dynamic columns
+
+Use `columns do…end` when the column list depends on the current request:
+
+```ruby
+kanban do
+  columns do
+    # `self` is the view context — current_user, params, and helpers all work.
+    current_user.visible_statuses.map do |status|
+      Plutonium::Kanban::Column.new(
+        :"status_#{status.id}",
+        label: status.name,
+        color: status.color_symbol,
+        scope: -> { where(status_id: status.id) },
+        on_enter: ->(r) { r.update!(status_id: status.id) }
+      )
+    end
+  end
+end
+```
+
+The block is evaluated at request time. You can mix static pre-declared columns with a dynamic block: if both are present, the `columns` block takes precedence (the board is considered dynamic).
+
+::: warning Column action registration for dynamic boards
+Column actions declared inside a `columns do…end` block **cannot be auto-registered** at class-load time. Register the interaction as a top-level definition `action` as well:
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  action :archive_column_tasks, interaction: ArchiveTasksInteraction
+
+  kanban do
+    columns do
+      build_status_columns.each do |col|
+        col.action :archive_column_tasks, interaction: ArchiveTasksInteraction, on: :all
+        col
+      end
+    end
+  end
+end
+```
+
+**`enter_interaction:` is not supported on dynamic boards.** Unlike a column action, its hidden action can't be registered manually — the key is column-scoped and internal — and the static registration pass has no columns to see. A drop into a dynamic column that declares `enter_interaction:` is rejected with a snap-back (it does not crash). Use a static board when a column needs an `enter_interaction:`.
+:::
+
+---
+
+## Column actions
+
+Declare actions inside a column `do…end` block:
+
+```ruby
+column :done,
+  scope: -> { where(status: "done") },
+  on_enter: :mark_done! do
+
+  action :archive_all,
+    interaction: ArchiveTasksInteraction,
+    on: :all,
+    label: "Archive all",
+    icon: Phlex::TablerIcons::Archive,
+    confirmation: "Archive all done tasks?"
+end
+```
+
+### Action options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `interaction:` | Class | Yes | An interaction class. Must have `attribute :resources` (plural) — it runs as a bulk action |
+| `on:` | `:all` or `:visible` | No (default `:all`) | `:all` passes IDs of all column cards (ignoring `per_column`). `:visible` passes only the rendered, capped subset |
+| `label:` | String | No | Button text. Defaults to `key.to_s.humanize` |
+| `icon:` | Phlex icon class | No | Icon rendered before the label |
+| `confirmation:` | String | No | Browser `confirm()` message shown before the action fires |
+
+Column actions are rendered as small buttons in the column header. They open the standard interactive-action modal with full authorization, form rendering, and success/failure handling.
+
+**Auto-registration:** For static columns, the `kanban` DSL automatically calls `action(key, interaction:, …)` at definition class-load time so the bulk route resolves. For dynamic `columns do…end` boards you must register the interaction manually (see warning above).

data/docs/reference/kanban/index.md

@@ -0,0 +1,40 @@
+# Kanban Reference
+
+Reference documentation for the Plutonium kanban board feature.
+
+## In this section
+
+| Page | What it covers |
+|------|---------------|
+| [DSL](/reference/kanban/dsl) | Complete `kanban do…end` DSL — board options, columns, column actions, static vs. dynamic, lazy loading, realtime |
+| [Positioning](/reference/kanban/positioning) | `Plutonium::Positioning` concern, `positioned_on`, `position_on` modes, `reposition!`, rebalancing |
+| [Authorization](/reference/kanban/authorization) | `kanban_move?` policy predicate, read-only fallback, separating move rights from edit rights |
+
+## Quick start
+
+```ruby
+# app/definitions/task_definition.rb
+class TaskDefinition < ResourceDefinition
+  kanban do
+    per_column 25
+
+    column :todo,
+      scope:   -> { where(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") },
+      role: :backlog
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") },
+      wip: 3
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_enter: :mark_done!,
+      accepts: [:doing],
+      role: :done
+  end
+end
+```
+
+See the [Kanban guide](/guides/kanban) for a full walkthrough including model setup and migrations.

data/docs/reference/kanban/positioning.md

@@ -0,0 +1,162 @@
+# Kanban Positioning
+
+Plutonium uses **decimal fractional positioning** for kanban card ordering. A drop writes a single decimal position (the midpoint between its neighbors), so the common case touches exactly one row — no bulk renumbering. The one exception is rare **rebalancing**: when the same slot has been subdivided ~20 times and the gap between two neighbors shrinks below `1e-6`, Plutonium renumbers that one scope group back to clean integers before inserting (see [Gap exhaustion](#rebalancing)).
+
+## `Plutonium::Positioning` concern
+
+Include this concern in any model you want to position:
+
+```ruby
+class Task < ApplicationRecord
+  include Plutonium::Positioning
+
+  positioned_on :position, scope: :status
+end
+```
+
+### `positioned_on(column = :position, scope: nil)`
+
+Configures positional ordering for the model.
+
+| Argument | Description |
+|----------|-------------|
+| `column` | The `decimal` database column that stores positions. Default: `:position` |
+| `scope:` | Group positions by this attribute. Records with different scope values are ordered independently. `nil` = single global ordering across all rows |
+
+After calling `positioned_on`, the model gets:
+- A `before_create` callback that assigns the next position in the scope group (appends to end).
+- A `reposition!(prev_record:, next_record:)` instance method.
+- A `backfill_positions!(order: :created_at)` class method.
+
+### Migration
+
+Use the **`t.position`** helper — it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't get the scale wrong:
+
+```ruby
+create_table :tasks do |t|
+  t.string :status, null: false, default: "todo"
+  t.position                 # decimal :position, precision: 16, scale: 8
+  t.timestamps
+end
+add_index :tasks, [:status, :position]   # match your scope attribute
+```
+
+Adding the column to an existing table works the same way in a `change_table` block:
+
+```ruby
+class AddPositionToTasks < ActiveRecord::Migration[8.1]
+  def change
+    change_table(:tasks) { |t| t.position }
+    add_index :tasks, [:status, :position]
+  end
+end
+```
+
+`t.position` accepts a custom column name and any `column` options:
+
+```ruby
+t.position :sort_order               # custom name
+t.position :position, index: true    # also add a single-column index
+t.position :position, scale: 10      # override precision/scale
+```
+
+::: tip Why the helper picks `scale: 8`
+If you write the column by hand, give it at least **two more decimal places than `EPSILON` (`1e-6`)** — i.e. `scale: 8` or higher. Rebalancing triggers when a gap drops below `1e-6`, so a column that can store smaller values still has room to write the final midpoint cleanly. A `scale: 6` column has no headroom: the last subdivision before a rebalance can round to a neighbor and momentarily collide. `t.position` defaults to `scale: 8`, which is safe.
+:::
+
+---
+
+## `reposition!(prev_record:, next_record:)`
+
+Moves a record so it sits between `prev_record` and `next_record` in its scope group. Pass `nil` for an end to prepend or append.
+
+```ruby
+task.reposition!(prev_record: card_a, next_record: card_b)
+task.reposition!(prev_record: nil, next_record: first_card)  # prepend
+task.reposition!(prev_record: last_card, next_record: nil)   # append
+```
+
+**Arithmetic:**
+- Both nil → `0.0` (first item in empty group)
+- Only `prev_record` → `prev.position + 1` (append)
+- Only `next_record` → `next.position - 1` (prepend)
+- Both present → `(prev.position + next.position) / 2.0` (midpoint)
+
+### Gap exhaustion (rebalancing) {#rebalancing}
+
+Each midpoint insert into the *same* slot halves the gap (`1.0 → 0.5 → 0.25 → …`), so after roughly 20 consecutive insertions the gap drops below `EPSILON` (`1e-6`). At that point `reposition!` rebalances **only that scope group** — renumbering every row in the group to fresh integers (`1.0, 2.0, 3.0, …`) in current-position order, inside a transaction — then reloads the two neighbors and writes the new midpoint. Other scope groups are untouched. End moves (a `nil` neighbor) never rebalance: they always have integer room via `prev ± 1`.
+
+---
+
+## `backfill_positions!(order: :created_at)`
+
+Numbers all existing rows per scope group as `1.0, 2.0, 3.0, …` sorted by `order`. Safe to run on an empty table. Use this in a migration or seed task to initialize positions on existing data:
+
+```ruby
+# In a migration after adding the column:
+Task.backfill_positions!(order: :created_at)
+```
+
+---
+
+## `position_on` DSL modes
+
+The `position_on` call inside `kanban do…end` controls how Plutonium persists positions after a drag-and-drop. Three modes are available:
+
+### Mode A — delegate (default)
+
+```ruby
+kanban do
+  # Implicit: position_on :position
+  # Explicit with custom attribute:
+  position_on :sort_order
+end
+```
+
+On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`. Requires the model to include `Plutonium::Positioning` and call `positioned_on`.
+
+### Mode B — BYO block
+
+```ruby
+kanban do
+  position_on :sort_order do |move|
+    # move.record — the dropped record
+    # move.column — destination column key (Symbol)
+    # move.prev   — record immediately before the slot (or nil)
+    # move.next   — record immediately after the slot (or nil)
+    # move.index  — 0-based insertion index within the destination column
+    move.record.update!(sort_order: my_position(move.prev, move.next))
+  end
+end
+```
+
+Plutonium orders the column by `sort_order` for display; your block is responsible only for persisting the new value. The block is called with a single `Plutonium::Kanban::Positioning::Move` argument — it is NOT `instance_exec`'d, so `self` is the proc's original binding.
+
+### Mode C — disabled
+
+```ruby
+kanban do
+  position_on false
+end
+```
+
+No ordering is applied (relation is returned unchanged). On drop, `on_exit`/`on_enter` still fire; the position attribute is never touched. Cards render in the relation's default order.
+
+---
+
+## Pure math helpers
+
+Available as module-level methods without an AR instance:
+
+```ruby
+Plutonium::Positioning.position_between(1.0, 3.0)    # => 2.0
+Plutonium::Positioning.position_between(nil, 5.0)    # => 4.0  (prepend)
+Plutonium::Positioning.position_between(5.0, nil)    # => 6.0  (append)
+Plutonium::Positioning.position_between(nil, nil)    # => 0.0  (first item)
+
+Plutonium::Positioning.gap_exhausted?(1.0, 1.0)      # => true
+Plutonium::Positioning.gap_exhausted?(1.0, 3.0)      # => false
+Plutonium::Positioning.gap_exhausted?(nil, 5.0)      # => false
+```
+
+`EPSILON = 1e-6` is the minimum gap before `gap_exhausted?` returns `true`.

data/docs/reference/resource/definition.md

@@ -121,7 +121,7 @@ These render automatically — declare an `as:` only to override or pass options
 |---|---|---|
 | `boolean` | Yes/No pill (`:boolean`) | green "Yes" / neutral "No"; override with `true_label:` / `false_label:` |
 | `enum` | status badge (`:badge`) | known statuses auto-colored; unknown values get a stable decorative color; override per-value with `colors:` |
-| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals, **no symbol** unless you pass `unit:` (a literal `"£"` or a Symbol read off the record) |
+| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals; symbol from `unit:` on `has_cents` (model-wide) or per-display, else `config.default_currency_unit` / the i18n default (see below) |
 
 ```ruby
 display :status, as: :badge, colors: {archived: :neutral, vip: :accent}
@@ -129,6 +129,15 @@ display :price,  as: :currency, unit: "£"
 display :active, as: :boolean, true_label: "Live", false_label: "Off"
 ```
 
+**Currency symbol.** The `unit:` can be set on the model's `has_cents` declaration
+(`has_cents :price_cents, unit: "£"`, or `unit: :currency_symbol` to read a method
+off the record for per-row currencies). That model-level unit is used everywhere the
+value renders as currency — the show page, tables, **and grid/kanban cards**. A
+per-display `unit:` overrides it for that one display; `unit: false` explicitly
+renders no symbol. When neither is set, currency falls back to
+`Plutonium.configuration.default_currency_unit` (default: the i18n
+`number.currency.format.unit` if the locale defines it — `$` in `en` — else no symbol).
+
 ## Field options
 
 ```ruby
@@ -681,6 +690,22 @@ end
 
 `modal:` is the default for framework `:new`/`:edit` *and* every interactive action on this definition. Per-action `modal:` / `size:` overrides win — see [Actions](./actions).
 
+### `show_in` {#show_in}
+
+```ruby
+class PostDefinition < ResourceDefinition
+  show_in :modal   # open the show page in a centered modal from table & grid links
+  # show_in :page  # (default) full-page navigation to the show route
+end
+```
+
+Controls how the **show page** opens when a record is clicked in the table or grid (and serves as the default for a [kanban board](/reference/kanban/dsl#show_in), which can override it per-board):
+
+- `:page` (default) — full-page navigation to the show route.
+- `:modal` — the show page opens in a **centered** dialog. This is deliberately independent of `modal:`/`modal_mode` above (which styles `:new`/`:edit`) — show is always centered, never a slideover. From inside the modal an expand icon opens the full page in a new tab; ⌘/Ctrl-click (or middle-click) on the row/card does the same directly.
+
+An unknown mode raises `ArgumentError`.
+
 ## Metadata panel (show page)
 
 A right-side aside on the show page rendering label/value rows. Keeps the main card focused on substance; chrome (timestamps, ownership, system flags) lives in the aside.

data/docs/reference/resource/model.md

@@ -97,6 +97,9 @@ class Product < ResourceRecord
   has_cents :cost_cents, name: :wholesale   # custom accessor name
   has_cents :tax_cents, rate: 1000          # 3 decimal places (e.g. for fractional currencies)
   has_cents :amount_yen, rate: 1            # currencies with no subunit (JPY)
+  has_cents :gbp_cents, unit: "£"           # currency symbol used wherever this renders as currency
+  has_cents :multi_cents, unit: :currency_symbol  # per-row: reads record.currency_symbol
+  has_cents :points_cents, unit: false      # explicitly no symbol (skips the default)
 end
 
 product = Product.new
@@ -109,6 +112,29 @@ product.price = 10.999
 product.price_cents  # => 1099
 ```
 
+**Currency symbol (`unit:`)** — a `String` is used verbatim (`unit: "£"`); a `Symbol`
+names a method read off the record for per-row currencies (`unit: :currency_symbol`
+→ `record.currency_symbol`); `false` explicitly renders no symbol. This unit is picked
+up automatically anywhere the value renders as currency — show pages, tables, and
+grid/kanban cards — so you configure it once on the model. A per-display
+`display :price, as: :currency, unit: …` overrides it for that display.
+
+A `has_cents` field also **infers the currency input** on forms: a bare `input :price`
+renders the [currency input](../ui/forms#currency-fields) (number field + unit prefix),
+no `as: :currency` needed — matching the display side.
+
+Resolution is `display unit → has_cents unit → config default`, where `nil` means
+"not set, keep looking" and `false` means "stop, no symbol". When nothing is set, it
+falls back to `Plutonium.configuration.default_currency_unit`, which itself defaults
+to the i18n `number.currency.format.unit` *if the locale defines it* (`$` in `en`),
+else no symbol:
+
+```ruby
+Plutonium.configure do |config|
+  config.default_currency_unit = "£"   # app-wide default; false for no symbol; nil → i18n-if-set
+end
+```
+
 ::: danger Use the virtual accessor in policies and definitions
 Reference `:price`, NOT `:price_cents`: