plutonium 0.61.0 → 0.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f8adf3a1153ed95a357bf90ab145279c7f7b72540c6f160c8f52f859ed14e4e
-  data.tar.gz: 96f58112aff1ffd9a21311c169169c31efe61c16470c65f1805b9860e987baca
+  metadata.gz: 62c3179e6fc69beaae9e39a5892a478bd41c546fcf0fb580dea6a4aa9680e296
+  data.tar.gz: 94c2ce8570a323536961196170f8cb7187efe724834485edfd210a783147cbe8
 SHA512:
-  metadata.gz: 3cec89b62845ecb9177e21bb7307c18f182056ce01164f657b07b2dd5e165c041aa0172b7f22b967061170b3a39398834b2966c8d62ba333e279ce0ff8ee0f8d
-  data.tar.gz: d8369fec9bd3e3ce5951248e03ee065c6dd9e31fa05bccd9ab7bc49abb69a0586a1b94adbcf5c0bec11b0dc8269927daa8ca41ad62ef7d6f20d045cc02004ca8
+  metadata.gz: 0b9dc172a16b74c0f313606cefe964a661842aacd63c21df3ed3cb9ca20179439d2f302b53658305a375ee2b752aacf056244eb0a6875e2a31e20276b8055a2c
+  data.tar.gz: e1f47b1429392d82253f27e8268309e129d33e5d62716b04c669c13e24cc4e3b34d74728d154189c116124319c7155911e49000be008ea72a2bbdd64fecc3dbd

data/.claude/skills/plutonium-kanban/SKILL.md

@@ -14,8 +14,11 @@ For field-level rendering on cards (card_fields slots), see [[plutonium-resource
 - **`kanban do…end` in the Definition auto-enables `:kanban`** in `defined_index_views` — exactly like `grid_fields` enables `:grid`. You do not need to call `index_views :kanban` separately unless you want to remove the table view.
 - **The model needs `include Plutonium::Positioning`** (and a decimal `position` column + `positioned_on` call) for drag ordering to work. Without it, cards render unordered and moves raise an error. Use `position_on false` to explicitly opt out.
 - **Static column actions are auto-registered** as interactive resource actions at class-load time. Dynamic boards (`columns do…end`) cannot introspect their columns at load time — declare any column-action interactions separately with top-level `action` calls.
-- **Moves bypass `permitted_attributes_for_update`** — the `on_drop` callback runs with full model access. Gate the move itself with `kanban_move?` in the policy.
+- **Moves bypass `permitted_attributes_for_update`** — the `on_enter` callback runs with full model access. Gate the move itself with `kanban_move?` in the policy.
 - **Quick-add (`add: true`) only appears when `create?` is true** in the policy.
+- **Same-column drops = positioning only** — a reorder within a column fires neither `on_exit`, `on_enter`, nor an `enter_interaction`; they represent *leaving*/*entering* a column, so only cross-column drops trigger them.
+- **`on_exit:` is the source-side hook** — fired when a card LEAVES a column (before the destination's `on_enter`, in the same transaction). Use it for source-tied side effects (stop a timer, release a slot) the destination can't own. It fires only on drag-moves via `kanban_move`, NOT on destroy/programmatic changes/quick-add — for those, use an ActiveRecord callback.
+- **Use `on_enter:` / `enter_interaction:`, NOT `on_drop:` / `drop_interaction:`.** The old names were renamed. They still exist as deprecated aliases but **raise in development/test** (and only warn-and-map in production), so a definition using them fails your test suite. Always write the new names.
 
 ---
 
@@ -56,15 +59,15 @@ class TaskDefinition < ResourceDefinition
   kanban do
     column :todo,
       scope:   -> { where(status: "todo") },
-      on_drop: ->(r) { r.update!(status: "todo") }
+      on_enter: ->(r) { r.update!(status: "todo") }
 
     column :doing,
       scope:   -> { where(status: "doing") },
-      on_drop: ->(r) { r.update!(status: "doing") }
+      on_enter: ->(r) { r.update!(status: "doing") }
 
     column :done,
       scope:   -> { where(status: "done") },
-      on_drop: :mark_done!     # Symbol → record.mark_done!
+      on_enter: :mark_done!     # Symbol → record.mark_done!
   end
 end
 ```
@@ -104,7 +107,7 @@ card_fields header: :title, meta: [:status, :priority], footer: :due_at
 
 - **Mode A (default)** — delegates to `record.reposition!(prev_record:, next_record:)` from `Plutonium::Positioning`. Requires the model concern and a decimal column.
 - **Mode B (block)** — you write the persistence. Plutonium still orders by the attribute; the block only persists the new value. Block receives a `Plutonium::Kanban::Positioning::Move` (fields: `record`, `column`, `prev`, `next`, `index`).
-- **Mode C (`false`)** — no ordering, no repositioning. `on_drop` still fires.
+- **Mode C (`false`)** — no ordering, no repositioning. `on_enter` still fires.
 
 ### `realtime`
 
@@ -135,6 +138,8 @@ end
 
 Evaluates the block at request time with the view context as `self` (`current_user`, `params`, `current_scoped_entity`, helpers all available). The block must return an Array of `Plutonium::Kanban::Column` objects — `column` is a DSL method only available outside the `columns` block. Declare any column-action interactions as top-level definition `action` calls — the block is not introspectable at class-load time.
 
+> **`enter_interaction:` is NOT supported on dynamic boards.** Its hidden action is registered from the static column list at class-load time, which a `columns do…end` board doesn't have, and the key is column-scoped/internal so there's no manual-registration escape hatch (unlike column actions). A drop into such a column is rejected with a snap-back — it does not crash. Use a static board if you need `enter_interaction:`.
+
 ```ruby
 kanban do
   columns do
@@ -144,7 +149,7 @@ kanban do
         :"team_#{team.id}",
         label:   team.name,
         scope:   -> { where(team_id: team.id) },
-        on_drop: ->(r) { r.update!(team_id: team.id) }
+        on_enter: ->(r) { r.update!(team_id: team.id) }
       )
     end
   end
@@ -161,12 +166,14 @@ column :key,
   color:     :green,           # Tailwind-mapped color hint
   wip:       3,                # max cross-column moves into this column
   scope:     -> { where(…) },  # 0-arg lambda or Symbol (sent to relation)
-  on_drop:   ->(r) { … },      # 1-arg lambda or Symbol → record.method!
+  on_enter:   ->(r) { … },      # 1-arg lambda or Symbol → record.method! (card ENTERS)
+  on_exit:    ->(r) { … },      # 1-arg lambda or Symbol → runs when a card LEAVES this column
+  enter_interaction: MarkLostInteraction, # record-scoped interaction run on cross-column drop (see below)
   collapsed: true,             # starts collapsed (Stimulus persists toggle to localStorage)
   add:       true,             # show "+ Add" button (requires create?)
-  accepts:   true,             # true (default), false, Array of source keys, or 1-arg Proc
+  accepts:   true,             # true (default), false, or Array of source keys (Proc raises)
   locked:    false,            # reject all incoming drops (server-enforced)
-  role:      :backlog          # :backlog or :done (see presets below)
+  role:      :backlog          # :backlog, :done or :lost (see presets below)
 ```
 
 ### Column role presets
@@ -175,31 +182,76 @@ column :key,
 |---|---|
 | `:backlog` | `add: true` |
 | `:done` | `color: :green`, `collapsed: true` |
+| `:lost` | `color: :red`, `collapsed: true` |
+
+`:done` and `:lost` are the two terminal roles — collapsed by default, colour
+signalling the outcome (`:done` = positive close, `:lost` = negative close). The
+natural pair for won/lost pipelines (leads, deals, tickets).
 
 Explicit options override the preset (e.g. `role: :done, collapsed: false`).
 
 ### `accepts:`
 
-Controls which source columns may drop cards here:
+Structural drop topology — which **source columns** may drop cards here:
 
 - `true` (default) — any source allowed
 - `false` — column is a drop target but refuses everything (snap-back)
 - `Array` — list of source column keys allowed: `accepts: [:doing]`
-- `Proc` (1-arg) — per-card predicate: `accepts: ->(record) { record.state == "doing" }`
 
-Checked server-side. Client-side visual hints read `data-kanban-accepts`.
+Checked server-side; client-side visual hints read `data-kanban-accepts` (so the drag UI can grey out disallowed sources). **No Proc form** — a `Proc` raises `ArgumentError`. Record- or user-conditional rules belong in `kanban_move?`, which sees the record and the `from`/`to` columns (see Authorization below).
 
-### `on_drop:`
+### `on_enter:`
 
 Runs inside a transaction after authorization and before repositioning. Receives the record for lambda form:
 
 ```ruby
-on_drop: ->(r) { r.update!(status: "done") }   # update! directly
-on_drop: ->(r) { r.status = "done" }            # attribute assignment — saved automatically
-on_drop: :mark_done!                            # dispatched as record.mark_done!
+on_enter: ->(r) { r.update!(status: "done") }   # update! directly
+on_enter: ->(r) { r.status = "done" }            # attribute assignment — saved automatically
+on_enter: :mark_done!                            # dispatched as record.mark_done!
 ```
 
-If `on_drop` only assigns attributes without calling `save!`/`update!`, the controller calls `record.save!` automatically when the record has unsaved changes after `on_drop` returns.
+If `on_enter` only assigns attributes without calling `save!`/`update!`, the controller calls `record.save!` automatically when the record has unsaved changes after `on_enter` returns.
+
+### `on_exit:`
+
+The source-side counterpart to `on_enter:`. Runs on the column a card **leaves** during a cross-column move, **before** the destination's `on_enter`, in the same transaction (so it sees the pre-move state and rolls back if the move fails). Same Symbol/Proc dispatch and auto-save behaviour as `on_enter`.
+
+```ruby
+column :doing,
+  scope:    -> { where(status: "doing") },
+  on_enter: ->(r) { r.start_timer! },   # entering Doing
+  on_exit:  ->(r) { r.stop_timer! }     # leaving Doing (wherever it goes)
+```
+
+Use it for side effects tied to the column being **left** — the destination's `on_enter` doesn't know where a card came from, so source concerns (stop a timer, release a WIP/lock, un-assign) belong here.
+
+⚠️ It fires **only** on a drag-move through `kanban_move` — not on `destroy`, a programmatic `status` change elsewhere, or quick-add. For "whenever this leaves, no matter how", use an ActiveRecord callback. Skipped on same-column reorders.
+
+### `enter_interaction:`
+
+Run an input-collecting interaction when a card is dropped **into** this column from another column — for entries that need more than a membership flip (a reason, a mail, an audit entry).
+
+```ruby
+column :lost, scope: -> { where(status: "lost") }, enter_interaction: MarkLostInteraction
+
+class MarkLostInteraction < ResourceInteraction
+  attribute :resource                       # MUST be record-scoped (singular), not :resources
+  attribute :reason, :string
+  input :reason
+  validates :reason, presence: true
+  def execute
+    resource.update!(status: "lost", lost_reason: reason)
+    succeed(resource).with_message("Marked as lost")   # message → toast
+  end
+end
+```
+
+- **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. No button on show/table/grid; reachable only by dropping. **No policy method of its own** — authorized by `kanban_move?` (see Authorization).
+- **Move flow:** cross-column drop opens the interaction's form as a modal; on submit `on_enter` + interaction + repositioning commit in **one atomic transaction**. Validation failure rolls it all back (membership write included) and re-renders the modal with errors — nothing persists. Put side-effects on `deliver_later` so a rollback sends no stray mail.
+- **Same-column reorder = positioning only** — neither `on_enter` nor the interaction fires (both = *entering* a column).
+- **Quick-add (`+ Add`)** applies `on_enter` + positioning post-create; the interaction is not involved.
+- **Author contract:** with both present, `on_enter` owns the membership attribute (`status`) and the interaction owns extras. If the interaction also writes membership it must set the **same** value (idempotent). With no `on_enter`, the interaction owns everything (like `:lost`).
+- **Limitation:** custom success *responses* (`with_redirect_response`, `with_file_response`, …) are NOT honored on the drop path — board re-renders + modal closes. Use `.with_message` for feedback.
 
 ### Column actions
 
@@ -242,24 +294,37 @@ end
 
 When `kanban_move?` returns `false`, the board renders read-only — no drag handles, no drop zones.
 
+**`kanban_move?` is the ONLY move authorization** — plain moves and `enter_interaction:` columns alike (the interaction has no policy method of its own). To gate a *specific* transition, read the destination (and source) column from the authorization context via the optional `kanban_to` / `kanban_from` policy readers (the `Column` objects; `nil` for every non-move check):
+
+```ruby
+def kanban_move?
+  return user.manager? if kanban_to&.key == :closed_won
+  super
+end
+```
+
+Rules take no positional args in ActionPolicy — the columns arrive as declared optional context (`authorize :kanban_from/:kanban_to, optional: true` on the base policy), supplied by the controller on the move check.
+
 ### Move authorization flow
 
 1. Record loaded via current `relation_scope` (same as index).
-2. `kanban_move?` checked — HTTP 403 on failure.
+2. `kanban_move?` checked (with `kanban_from`/`kanban_to` in context) — HTTP 403 on failure. This is the sole authorization; an `enter_interaction` rides on it.
 3. Column `accepts:` / `locked:` checked — HTTP 422 + card snap-back on failure.
 4. `wip:` limit checked for cross-column moves — HTTP 422 on failure.
-5. `on_drop` fires + record repositioned, all in a transaction.
+5. `on_enter` fires + record repositioned, all in a transaction.
 
 On a 422 rejection (steps 3–4) the response re-renders the source column (snap-back) **and** appends a dismissable warning toast naming the reason (e.g. `“Pending” is at its WIP limit (5).`) to the board's `#kanban-flash` region — so the snap-back is never silent. The toast renders the shared `plutonium/toast` partial directly (not via `flash`), so a stale undisplayed flash can't leak into the turbo-stream response.
 
 ### No permitted-attributes gate
 
-Moves do not pass through `permitted_attributes_for_update`. `on_drop` is trusted author code; it is responsible for assigning only the appropriate attributes.
+Moves do not pass through `permitted_attributes_for_update`. `on_enter` is trusted author code; it is responsible for assigning only the appropriate attributes.
 
 ### Quick-add
 
 The `+ Add` button (column `add: true`) only renders when the policy's `create?` is true. The opened form is the standard new-resource form.
 
+The record is created normally, **then** the column's `on_enter` + positioning are applied to the **saved** record (it lands in the clicked column, appended to the bottom) — `on_enter` runs against a real record, exactly as on a drag. **Your grouping column must have a default** (DB or model), because `on_enter` runs after save; a `NOT NULL` grouping column with no default fails quick-add create. A raising `on_enter` keeps the created record in its default column and toasts the error (the create is not rolled back).
+
 ---
 
 ## Worked example (full)
@@ -272,18 +337,18 @@ 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                    # add: true
 
     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!,
-      accepts: ->(task) { task.status == "doing" },
+      on_enter: :mark_done!,
+      accepts: [:doing],                # only cards coming from :doing
       role:    :done do                 # color: :green, collapsed: true
       action :archive_all,
         interaction: ArchiveTasksInteraction,

data/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.62.0] - 2026-07-04
+
+### Bug Fixes
+
+- Run input-less column actions directly instead of an empty modal
+- Don't call signed_id on an unsaved ActiveStorage blob in uppy
+- Active_shrine downstream fixes — mime-types gem + resource param double-read
+- Stop the board blanking on search/filter/scope
+- Size currency input padding to its unit prefix
+- Preserve collapse + horizontal scroll across moves and refresh
+- Give the body a base text color so unstyled text stays visible
+- Give modal dialogs a base text color so unstyled text stays visible
+
+### Features
+
+- AI agent on-ramp — llms.txt, /ai quickstart, crawlable skills
+- Type-aware kanban meta badges + has_cents currency unit
+- Expose intl-tel-input options + default_phone_country config
+- Currency input + currency/choice-aware wizard review summary
+- Add :lost terminal column role
+- Keep the board fresh + scrolled across writes and actions
+- [**breaking**] Drop interactions, immediate drops, on_exit + on_drop→on_enter rename ([#67](https://github.com/radioactive-labs/plutonium-core/issues/67))
+
+### Refactoring
+
+- Server-read collapse cookie + stable frame placeholders
+
 ## [0.61.0] - 2026-06-30
 
 ### Bug Fixes