plutonium 0.62.2 → 0.63.0

data/docs/reference/behavior/interactions.md

@@ -1,6 +1,6 @@
 # Interaction
 
-Encapsulate business logic into testable, reusable units. Registered as [actions](/reference/resource/actions) in definitions and executed by the controller. Built on ActiveModel attributes + validations.
+The entry point from a Plutonium page into an operation. An interaction declares the inputs, renders as a button and a form, is gated by a policy, and returns an outcome the controller turns into a flash message and a redirect. Built on ActiveModel attributes + validations.
 
 ## 🚨 Critical
 
@@ -9,6 +9,80 @@ Encapsulate business logic into testable, reusable units. Registered as [actions
 - **Redirect is automatic on success** — only use `with_redirect_response` for a *different* destination.
 - **Bulk actions use `attribute :resources` (plural).** Policy authorization is checked per record — if any fails, the whole request fails.
 - **The shape of the action (record / bulk / resource) is inferred from the interaction's attributes.** See [Resource › Actions](/reference/resource/actions#inferred-visibility-interactive-actions).
+- **An interaction is a presentation object.** Logic may *start* in `execute`; the **second caller** — a job, an API controller, a rake task, the console — is the signal to move it to the model. See [below](#what-an-interaction-is-for).
+
+## What an interaction is for {#what-an-interaction-is-for}
+
+An interaction is a **presentation object**. It exists so Plutonium can render a button, check a policy, bind a form, and turn the result into a message and a redirect. That is the whole job:
+
+| An interaction owns | An interaction does not own |
+|---|---|
+| The button — `presents label:` / `icon:` | *Who* may click it. That's the [policy](./policies). |
+| The form — `attribute` + `input` declarations | — |
+| **Input shape** validation: present? parses? right type? | **Business invariants** — they must hold for every caller, so they belong on the model |
+| The user-facing outcome — `succeed` / `failed`, messages, redirect | The domain operation itself, once more than one caller needs it |
+
+### Logic may start in `execute`
+
+A one-off operation with exactly one caller is perfectly fine written inline. Don't pre-extract a service object for a two-line `update!` — that's YAGNI, and Plutonium deliberately ships no service layer to put it in. The rule below is a **refactoring trigger**, not a prohibition.
+
+### The second caller is the trigger to extract
+
+The moment a background job, an API controller, a rake task, the console, or another interaction needs the same behaviour, move it to the model.
+
+The deadline is *the second caller* — and not "as soon as it looks like business logic" — because of one line in the base class:
+
+```ruby
+def initialize(view_context:, **attributes)
+```
+
+`view_context:` is required. So a caller that isn't a Plutonium page has exactly two options: duplicate the logic, or manufacture a `view_context` it has no business owning. **`view_context` is the tell.** If reaching some behaviour would force a caller to conjure one, that behaviour is on the wrong side of the boundary.
+
+### The destination is the model
+
+Rails convention: fat models. Give the operation a name in domain language and hang it off the record.
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  def publish!(on: Time.current)
+    update!(published: true, published_at: on)
+  end
+end
+```
+
+```ruby
+# the interaction presents it
+def execute
+  resource.publish!(on: publish_date)
+  succeed(resource).with_message("Post published!")
+rescue ActiveRecord::RecordInvalid => e
+  failed(e.record.errors)
+end
+```
+
+Name it for the domain (`publish!`, `archive!`, `register!`), not for the persistence (`update_published_at`) — the point is that a scheduler job can now call `post.publish!` and read as if it meant it. And resist inventing a `PublishPostService`: the model is the destination, not a new layer.
+
+### Worked counter-example — chained interactions
+
+```ruby
+# 🚫 Every link demands a view_context that has nothing to do with the work
+CreateUserInteraction.call(view_context:, **user_params)
+  .and_then { |user| SendWelcomeEmail.call(view_context:, user:) }
+  .and_then { |user| LogActivity.call(view_context:, user:) }
+```
+
+Sending a welcome email and writing an audit row are precisely what a signup API endpoint, a seeds script, or a console session also has to do — none of which has a `view_context`. Modelled as interactions, they are unreachable from anywhere but a Plutonium page.
+
+```ruby
+# ✅ The model owns registering a user; the interaction presents it
+def execute
+  user = User.register!(**attributes)   # welcome email + audit row live in here
+  succeed(user).with_message("Welcome aboard!")
+end
+```
+
+Chaining three interactions is usually the signal that you have one model method wearing three presentation costumes. `and_then` is real API and stays [documented below](#chaining) — just don't reach for it to sequence business operations.
 
 ## Structure
 
@@ -33,7 +107,7 @@ class PublishPostInteraction < ResourceInteraction
   private
 
   def execute
-    resource.update!(published_at: publish_date)
+    resource.publish!(on: publish_date)   # Post#publish! — see above
     succeed(resource).with_message("Post published!")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -41,6 +115,8 @@ class PublishPostInteraction < ResourceInteraction
 end
 ```
 
+Note the division: the interaction declares the input, validates that a date was supplied, and phrases the flash. `Post#publish!` decides what publishing a post *means* — so the scheduled-publishing job can call it too.
+
 ## Attributes
 
 ActiveModel-style:
@@ -123,22 +199,33 @@ def execute
 end
 ```
 
-### Chaining
+### Chaining {#chaining}
 
-`and_then` chains interactions. On failure, the chain short-circuits and returns the failure immediately.
+`and_then` composes `Outcome`s. On a `Success` it yields **the value** (not the outcome) and returns whatever the block returns; on a `Failure` it short-circuits, returning the failure untouched.
 
 ```ruby
 def execute
-  CreateUserInteraction.call(view_context:, **user_params)
-    .and_then { |r| SendWelcomeEmail.call(view_context:, user: r.value) }
-    .and_then { |r| LogActivity.call(view_context:, user: r.value) }
-    .with_message("User created and welcomed!")
+  unlocked_resource.and_then do |post|
+    post.publish!(on: publish_date)
+    succeed(post).with_message("Post published!")
+  end
+end
+
+private
+
+# a guard expressed as an Outcome, so the failure carries its own message
+def unlocked_resource
+  resource.locked? ? failed("This post is locked") : succeed(resource)
 end
 ```
 
+::: warning Don't use `and_then` to sequence business operations
+A chain of three interactions is a chain of three things that each demand a `view_context`, none of which a job or an API controller can supply. That's one model method wearing three costumes — see [Worked counter-example](#what-an-interaction-is-for). `and_then` earns its keep composing outcomes *within* one interaction, or in a test.
+:::
+
 ## Validations
 
-Standard ActiveModel. Run automatically before `execute`:
+Standard ActiveModel. Run automatically before `execute`; if they fail, `execute` never runs.
 
 ```ruby
 validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
@@ -153,6 +240,23 @@ def custom_check
 end
 ```
 
+### Which validation goes where
+
+Interactions have validations and so do models, and they are not competing — they answer different questions:
+
+| | Interaction validation | Model validation |
+|---|---|---|
+| Asks | "Can I read this input?" — present, parses, right type, plausible format | "Is this record legal?" — invariants that hold no matter who is calling |
+| Exists to | render a form error next to the field | protect the data from every caller, including the ones with no form |
+| Runs | before `execute`, without ever touching the model | inside `save!` / `update!` — i.e. inside your model method |
+
+Both surface to the user, but **not identically**, and the difference should inform where you put a rule:
+
+- An **interaction** validation attaches to a declared attribute. The re-rendered modal shows it inline against that input, and again in the summary at the top of the form.
+- `failed(record.errors)` flattens `ActiveModel::Errors` into **full messages on `:base`** (`Array(errors)` calls `errors.to_a`, which is `full_messages`). Those land in the form's error summary only — never against a field — and they're phrased with the *model's* attribute names, which need not match your inputs.
+
+So it is fine, and often right, to *duplicate* a cheap invariant as an interaction validation purely for the better error placement, while the model keeps the authoritative copy. What must not happen is the model-side copy going missing: the moment a job calls `post.publish!`, the interaction's validations are not in the picture at all.
+
 ## Accessing context
 
 `current_user` is provided by the base class (`view_context.controller.helpers.current_user`):
@@ -164,6 +268,8 @@ def execute
 end
 ```
 
+This one is *correctly* inline. "Who clicked the button" is context the presentation layer holds and nothing else does — `current_user` is read straight off the `view_context`. A job has no answer for it, so there is no second caller to extract for.
+
 ## Interaction types
 
 | Attribute pattern | Action type | Where it shows up |
@@ -179,7 +285,7 @@ class ArchiveInteraction < Plutonium::Resource::Interaction
   attribute :resource
 
   def execute
-    resource.update!(archived: true)
+    resource.archive!
     succeed(resource).with_message("Archived")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -200,6 +306,8 @@ class BulkArchiveInteraction < Plutonium::Resource::Interaction
 end
 ```
 
+`update_all` stays inline on purpose: it's a single-statement SQL update whose *whole point* is skipping per-record model machinery. If archiving means more than setting a column — callbacks, an audit row, a webhook — this is the wrong shape; call `resources.each(&:archive!)` and let the model own it.
+
 Per-record authorization details in [Resource › Actions › Bulk action](/reference/resource/actions#bulk-action).
 
 ### Resource action (no record)
@@ -219,7 +327,11 @@ end
 
 ## Calling interactions directly
 
-The controller handles this for interactive actions. But you can call them manually too — useful in tests, jobs, and rake tasks.
+The controller handles this for interactive actions. You can also call one by hand — chiefly in **tests**, where you're exercising the interaction itself.
+
+::: tip Needing this in a job or a rake task is the signal to refactor
+Both entry points require `view_context:`, and a job doesn't have one. If you find yourself reaching for a stub to satisfy it, you don't want the interaction — you want the model method it wraps. See [What an interaction is for](#what-an-interaction-is-for).
+:::
 
 ### Class method
 
@@ -240,7 +352,7 @@ interaction = PublishPost.new(view_context: view_context, resource: post)
 outcome = interaction.call
 ```
 
-The `view_context:` argument is required — interactions use it to access controller helpers and the current user.
+The `view_context:` argument is required — interactions use it to access controller helpers and the current user. It is also the boundary marker: everything reachable *only* through an interaction is reachable only from a page.
 
 ## Immediate vs form
 
@@ -276,7 +388,26 @@ The same URL serves GET (form/confirmation) and POST (commit) — the HTTP verb
 
 ## Complete example
 
+Inviting a user is a textbook second-caller case — a seats-provisioning job, an admin rake task and a signup API all need to send the same invitation. So the operation lives on `Company`, and the interaction is the button in front of it.
+
 ```ruby
+# app/models/company.rb
+class Company < ApplicationRecord
+  has_many :user_invites
+
+  # Everything inviting means: the row, the mail, the audit trail.
+  def invite!(email:, role:, by:)
+    user_invites.create!(email: email, role: role, invited_by: by).tap do |invite|
+      UserInviteMailer.invitation(invite).deliver_later
+    end
+  end
+
+  def pending_invite_for?(email) = user_invites.exists?(email: email, state: :pending)
+end
+```
+
+```ruby
+# app/interactions/company/invite_user_interaction.rb
 class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   presents label: "Invite User",
            icon:  Phlex::TablerIcons::UserPlus
@@ -288,28 +419,26 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
   input :email
   input :role, as: :select, choices: -> { UserInvite.roles.keys }
 
+  # Input shape — is this a readable email, is this a role that exists?
   validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
   validates :role,  presence: true, inclusion: {in: UserInvite.roles.keys}
-  validate :not_already_invited
+  validate  :not_already_invited
 
   private
 
   def execute
-    invite = UserInvite.create!(
-      company: resource, email: email, role: role,
-      invited_by: current_user
-    )
-    UserInviteMailer.invitation(invite).deliver_later
+    resource.invite!(email: email, role: role, by: current_user)
     succeed(resource).with_message("Invitation sent to #{email}")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
   end
 
+  # Deliberately duplicated. `UserInvite` enforces uniqueness for real (a job
+  # calling `company.invite!` must hit it too); this copy exists only so the
+  # message lands on the :email field instead of in the base error summary.
   def not_already_invited
-    return unless email.present?
-    if UserInvite.exists?(company: resource, email: email, state: :pending)
-      errors.add(:email, "already has a pending invitation")
-    end
+    return if email.blank?
+    errors.add(:email, "already has a pending invitation") if resource.pending_invite_for?(email)
   end
 end
 ```
@@ -335,6 +464,7 @@ See [Testing](/reference/testing/) for Plutonium's built-in testing helpers —
 
 ## Related
 
+- [Async Interactions](./async-interactions) — `async` a persisted run instead of running `execute` inline
 - [Resource › Actions](/reference/resource/actions) — registering interactions, inferred visibility, immediate vs form
 - [Policies](./policies) — `def <action>?` authorization methods
 - [Controllers](./controllers) — `resource_url_for(..., interaction: …)` URL generation

data/docs/reference/configuration.md

@@ -9,6 +9,7 @@ Plutonium.configure do |config|
 
   # config.shell = :modern
   # config.navii_host_url = "https://api.navii.dev"
+  # config.auto_eager_load_collections = true
 
   config.assets.logo       = "plutonium.png"
   config.assets.favicon    = "plutonium.ico"
@@ -37,6 +38,10 @@ Loads the baseline defaults for a given framework version. Call this first; late
 | `enable_hotreload` | `true` in `development` env | Hot-reload Plutonium components on change. |
 | `shell` | `:modern` | Chrome style: `:modern` (topbar + icon rail), `:plain` (topbar, no icon rail), or `:classic` (legacy header + sidebar, only for upgrades). See [Layouts](./ui/layouts). |
 | `navii_host_url` | `"https://api.navii.dev"` | Host of the [Navii](https://navii.dev) avatar service used by [`Avatar`](./ui/components#avatar). The component appends `/avatar/:seed`. Repoint to self-host or proxy. |
+| `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
+| `default_page_width` | `:md` | Width of detail-style pages — the show page and resource forms. One of `:sm :md :lg :xl :full` (`:full` = unconstrained). Index and table pages are unaffected. Override per-resource with `page_width` / `form_width` / `display_width`; see [Definition › Page width](./resource/definition#page-width). |
+| `wizards.width` | `:md` | Default width of wizard step pages. **Independent of `default_page_width`** — a wizard is a self-contained flow, so widening resource pages leaves wizards alone. Override per wizard with `width`. Same size tokens. |
+| `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is registered. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. See [Nested resources › Declaring which associations get routes](./tenancy/nested-resources#declaring-which-associations-get-routes). |
 | `assets.logo` | `"plutonium.png"` | Brand logo asset. See [Assets](./ui/assets). |
 | `assets.favicon` | `"plutonium.ico"` | Favicon asset. |
 | `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. |

data/docs/reference/index.md

@@ -22,6 +22,7 @@ aside: false
       { name: 'Definition', link: '/plutonium-core/reference/resource/definition' },
       { name: 'Query', link: '/plutonium-core/reference/resource/query' },
       { name: 'Actions', link: '/plutonium-core/reference/resource/actions' },
+      { name: 'Positioning', link: '/plutonium-core/reference/positioning' },
     ]},
     { group: 'Behavior', items: [
       { name: 'Overview', link: '/plutonium-core/reference/behavior/' },

data/docs/reference/kanban/dsl.md

@@ -49,18 +49,20 @@ Default: `nil` (unlimited).
 
 Controls how card positions are persisted after a drag-and-drop. Three modes:
 
-#### Mode A — delegate to `Plutonium::Positioning` (default)
+**Inherited from the definition.** `position_on` is the same verb outside `kanban do…end`, where it makes the resource's [table and grid drag-reorderable](/reference/positioning). A board with no `position_on` of its own uses the **definition's**, falling back to the historic default (`:position`, Mode A). Declaring it inside the board overrides that. Resolution is lazy, so declaration order in the class body does not matter.
+
+#### Mode A — delegate to `Plutonium::Positioning::Model` (default)
 
 ```ruby
 # Default: uses :position attribute
-# (no explicit call needed if the model includes Plutonium::Positioning)
+# (no explicit call needed if the model includes Plutonium::Positioning::Model)
 
 # Custom attribute name:
 position_on :sort_order
 ```
 
 Requires the model to:
-1. `include Plutonium::Positioning`
+1. `include Plutonium::Positioning::Model`
 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)
 
@@ -70,7 +72,8 @@ On drop, calls `record.reposition!(prev_record:, next_record:)` which computes t
 
 ```ruby
 position_on :sort_order do |move|
-  # move is a Plutonium::Kanban::Positioning::Move value object:
+  # move is a Plutonium::Positioning::Move value object
+  # (also reachable as Plutonium::Kanban::Positioning::Move):
   #   move.record  — the dropped ActiveRecord record
   #   move.column  — destination column key (Symbol)
   #   move.prev    — record immediately before the insertion slot, or nil

data/docs/reference/kanban/index.md

@@ -7,7 +7,7 @@ Reference documentation for the Plutonium kanban board feature.
 | 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 |
+| [Positioning](/reference/kanban/positioning) | `Plutonium::Positioning::Model` 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

data/docs/reference/kanban/positioning.md

@@ -1,14 +1,18 @@
 # Kanban Positioning
 
+::: tip Positioning is not kanban-only
+The model concern, the arithmetic and the `position_on` modes on this page are shared with **table and grid drag-to-reorder** — see [Positioning & drag-to-reorder](/reference/positioning) for the index-surface half of the feature (the grip, the `reposition` endpoint, `reposition?`, and board inheritance).
+:::
+
 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
+## `Plutonium::Positioning::Model` concern
 
 Include this concern in any model you want to position:
 
 ```ruby
 class Task < ApplicationRecord
-  include Plutonium::Positioning
+  include Plutonium::Positioning::Model
 
   positioned_on :position, scope: :status
 end
@@ -103,6 +107,22 @@ Task.backfill_positions!(order: :created_at)
 
 The `position_on` call inside `kanban do…end` controls how Plutonium persists positions after a drag-and-drop. Three modes are available:
 
+::: tip A board inherits the definition's `position_on`
+`position_on` is the **same verb** at both levels. A board resolves its strategy as: its own `position_on`, else the **definition's**, else the historic default (`:position`, Mode A). So a resource whose definition already declares `position_on` for its table and grid needs nothing inside `kanban do…end` — the board picks up the same attribute and the same mode.
+
+Resolution is lazy, so a `kanban do…end` written **above** `position_on` in the class body still sees it.
+
+```ruby
+class TaskDefinition < Plutonium::Resource::Definition
+  position_on :sort_order       # table, grid AND board
+
+  kanban do
+    position_on :board_rank     # …unless the board overrides it
+  end
+end
+```
+:::
+
 ### Mode A — delegate (default)
 
 ```ruby
@@ -113,7 +133,7 @@ kanban do
 end
 ```
 
-On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`. Requires the model to include `Plutonium::Positioning` and call `positioned_on`.
+On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`. Requires the model to include `Plutonium::Positioning::Model` and call `positioned_on`.
 
 ### Mode B — BYO block
 
@@ -130,7 +150,9 @@ kanban do
 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.
+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::Positioning::Move` argument (still reachable under its original name, `Plutonium::Kanban::Positioning::Move`) — it is NOT `instance_exec`'d, so `self` is the proc's original binding.
+
+On a table or grid the same block runs with `move.column` set to `nil`, since those surfaces have no columns. See [Mode B](/reference/positioning#mode-b) for a worked `acts_as_list` example.
 
 ### Mode C — disabled