plutonium 0.61.0 → 0.62.0

data/docs/reference/kanban/dsl.md

@@ -90,7 +90,7 @@ Plutonium still orders column cards by `sort_order` (the first argument); your b
 position_on false
 ```
 
-No ordering is applied. Cards render in the relation's natural order. On drop, only `on_drop` fires (if set); the position attribute is never touched.
+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.
 
 ---
 
@@ -165,6 +165,8 @@ Overrides the slot layout for every kanban card on this board, using the same sl
 
 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
@@ -177,12 +179,12 @@ kanban do
     label: "To Do",
     color: :blue,
     scope: -> { where(status: "todo") },
-    on_drop: ->(r) { r.update!(status: "todo") },
+    on_enter: ->(r) { r.update!(status: "todo") },
     role: :backlog
 
   column :done,
     scope: -> { where(status: "done") },
-    on_drop: :mark_done!,
+    on_enter: :mark_done!,
     accepts: [:doing],
     role: :done do
     action :archive_all, interaction: ArchiveTasksInteraction, on: :all
@@ -197,23 +199,60 @@ end
 | `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_drop:` | 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_drop` returns the controller saves it automatically. |
-| `role:` | `:backlog`, `:done` | `nil` | Applies a preset (see below) |
+| `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`, Array, or Proc | `true` | Drop policy. `true` accepts any source column. `false` rejects all drops (display-only column). An Array of column key symbols accepts only those sources. A 1-arg Proc `->(record) { … }` is evaluated **per-card on the server** at drop time (via `accepts_record?`) and returns a boolean — e.g. `->(task) { task.status == "doing" }`. The client-side drag hint treats a Proc column as permissive (`data-kanban-accepts="all"`) since the browser can't run the Proc; the server enforces it precisely on every move |
+| `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
@@ -230,7 +269,7 @@ kanban do
         label: status.name,
         color: status.color_symbol,
         scope: -> { where(status_id: status.id) },
-        on_drop: ->(r) { r.update!(status_id: status.id) }
+        on_enter: ->(r) { r.update!(status_id: status.id) }
       )
     end
   end
@@ -256,6 +295,8 @@ class TaskDefinition < ResourceDefinition
   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:`.
 :::
 
 ---
@@ -267,7 +308,7 @@ Declare actions inside a column `do…end` block:
 ```ruby
 column :done,
   scope: -> { where(status: "done") },
-  on_drop: :mark_done! do
+  on_enter: :mark_done! do
 
   action :archive_all,
     interaction: ArchiveTasksInteraction,

data/docs/reference/kanban/index.md

@@ -20,17 +20,17 @@ class TaskDefinition < ResourceDefinition
 
     column :todo,
       scope:   -> { where(status: "todo") },
-      on_drop: ->(r) { r.update!(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") },
       role: :backlog
 
     column :doing,
       scope:   -> { where(status: "doing") },
-      on_drop: ->(r) { r.update!(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") },
       wip: 3
 
     column :done,
       scope:   -> { where(status: "done") },
-      on_drop: :mark_done!,
+      on_enter: :mark_done!,
       accepts: [:doing],
       role: :done
   end

data/docs/reference/kanban/positioning.md

@@ -140,7 +140,7 @@ kanban do
 end
 ```
 
-No ordering is applied (relation is returned unchanged). On drop, `on_drop` still fires; the position attribute is never touched. Cards render in the relation's default order.
+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.
 
 ---
 

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

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`:
 

data/docs/reference/ui/forms.md

@@ -162,6 +162,7 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `slim_select_tag` | Slim Select (enhanced dropdown) |
 | `flatpickr_tag` | Flatpickr date/time picker |
 | `phone_tag` / `int_tel_input_tag` | intl-tel-input phone field |
+| `currency_tag` | Money input (number field + optional unit prefix) |
 | `uppy_tag` / `file_tag` | Uppy file upload |
 | `secure_association_tag` | Association with policy-checked options (inline `+` add, typeahead) |
 | `belongs_to_tag` / `has_many_tag` / `has_one_tag` | Association selects |
@@ -175,6 +176,46 @@ render field(:avatar).wrapped do |f|
 end
 ```
 
+### Phone fields (intl-tel-input) {#phone-fields}
+
+`as: :phone` renders an [intl-tel-input](https://github.com/jackocnr/intl-tel-input) field. Forward library options two ways:
+
+- `initial_country:` — a convenient shortcut for the library's `initialCountry` (ISO2, e.g. `"gh"`). This preselects a country so the widget doesn't show *"No country selected"* and a bare local number validates.
+- `intl_options:` — any other library option, using the library's own camelCase names. Merged over the shortcut, so it wins on conflict.
+
+```ruby
+input :phone, as: :phone, initial_country: "gh"
+input :phone, as: :phone, intl_options: {separateDialCode: true, strictMode: false}
+```
+
+When a field sets no country, it falls back to `Plutonium.configuration.default_phone_country` (an ISO2 code, or `nil` to leave it to the library):
+
+```ruby
+Plutonium.configure do |config|
+  config.default_phone_country = "gh"
+end
+```
+
+The field defaults to `strictMode: true`; override it via `intl_options: {strictMode: false}`.
+
+### Currency fields {#currency-fields}
+
+`as: :currency` renders a number input (`inputmode="decimal"`, `step="0.01"`) with an **optional** currency-unit prefix overlaid at its left edge. The unit resolves by the **same** chain as the currency *display* ([`Currency.resolve_unit`](../resource/model#has-cents)), so the form, show page, index, and wizard summary all show the same symbol:
+
+**explicit `unit:` → the record's `has_cents` unit → `config.default_currency_unit` → the i18n `number.currency.format.unit`.**
+
+```ruby
+input :price, as: :currency               # unit from has_cents / config / i18n
+input :price, as: :currency, unit: "£"    # a literal symbol
+input :price, as: :currency, unit: false  # no prefix — a plain number input
+```
+
+When nothing resolves (or `unit: false`), the prefix is omitted and it's an ordinary number input.
+
+**`has_cents` fields infer it automatically** — just like the display. A bare `input :price` on a `has_cents` attribute renders the currency input with the unit read off `has_cents`; no `as: :currency` needed. Use the explicit `as: :currency` for a non-`has_cents` decimal, or to override the unit.
+
+In a **wizard** step the data snapshot has no `has_cents` reflection, so there's nothing to infer from — declare `as: :currency` and pass `unit:` explicitly (`input :price, as: :currency, unit: "$"`); the review summary reads it back and formats the value as currency.
+
 ### Password & secret fields {#password-fields}
 
 `password_tag` renders a masking input that **never emits the stored value** into the DOM. A stored secret renders a fixed sentinel (masking both the value and its length); on submit:

data/docs/reference/wizard/dsl.md

@@ -204,6 +204,11 @@ What it renders depends on completion state and the `summary:` / block options:
 | `summary:` | Show the auto-summary of completed steps (default `true`). When `false`, the complete-state body is your block — or the built-in "ready to complete" panel if there's no block. The summary always renders in the incomplete state. |
 | `header:` | Show the step-header section (the label plus the "check everything over" prompt, which only appears when the summary is shown) above the body (default `true`). `false` drops it for a chromeless finish. |
 
+The auto-summary renders each field through the display pipeline, honoring the input's declared `as:`/`label:`:
+
+- a **choice input** (`select`/`radio_buttons` with `choices:`) resolves the stored value back to its label (`"pro"` → `"Pro"`) using the same choice mapper the form uses, so the recap matches what the user picked;
+- an **`as: :currency`** input formats the value as currency (`"1500.5"` → `"$1,500.50"`) rather than echoing a bare decimal — pass `unit:` on the input (the data snapshot has no `has_cents` reflection to infer it from).
+
 ```ruby
 review label: "Review & submit"                       # auto-summary + gated finish