plutonium 0.62.2 → 0.63.0

data/docs/reference/resource/actions.md

@@ -11,7 +11,8 @@ Custom buttons that go beyond standard CRUD — publish, archive, import, send i
 - **For interactive actions, visibility is inferred from the interaction's attributes.** Don't declare `record_action: true` / `bulk_action: true` etc. by hand unless you're opting OUT.
 - **Bulk action authorization is per-record.** If any selected record fails the policy check, the entire request is rejected.
 - **Always pass `as:`** on custom routes — without it, `resource_url_for` can't generate URLs (critical for nested resources).
-- **Prefer interactive actions over hand-written controller routes.** Anything with business logic belongs in an interaction.
+- **Prefer interactive actions over hand-written controller routes.** Anything a user triggers from a page belongs behind an interaction.
+- **An interaction is the button, not the operation.** Logic may start in `execute`; once a job or an API also needs it, it moves to the model — see [Behavior › Interactions](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ## Action visibility flags
 
@@ -21,6 +22,7 @@ Custom buttons that go beyond standard CRUD — publish, archive, import, send i
 | `record_action: true` | Show page — for actions on a single record (Edit, Archive, Delete) |
 | `collection_record_action: true` | Per-row in the index table — for quick actions (Edit, Show) |
 | `bulk_action: true` | Bulk-actions toolbar (shown when records are selected) |
+| `hidden: true` | **Nowhere.** Suppresses all four surfaces at once, while keeping the route and policy live — see [Hidden actions](#hidden-actions) |
 
 ### Inferred visibility (interactive actions)
 
@@ -64,6 +66,9 @@ action :name,
   # Conditional visibility — display-only proc, NOT authorization (see below)
   condition: -> { params[:beta] == "1" },
 
+  # Never render, anywhere — route + policy stay live (see below)
+  hidden: true,
+
   # Grouping
   category: :primary,                    # :primary, :secondary, :danger
   position: 50,                          # display order (lower = first)
@@ -74,9 +79,34 @@ action :name,
   return_to:    "/custom/path",
   route_options: {action: :foo},
   modal: :slideover,                     # :slideover / :centered — overrides the definition's modal mode
-  size:  :lg                             # :sm / :md / :lg / :xl / :auto / :full — overrides the definition's modal size
+  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full — overrides the definition's modal size
+
+  # HTML attributes (see below)
+  link:   {target: "_blank", rel: "noopener"},  # merged onto the action's <a> renderings
+  button: {data: {analytics: "archive"}}        # merged onto the button_to <form> (non-GET)
 ```
 
+### HTML attributes — `link:` / `button:`
+
+Two per-element attribute bags, deep-merged over the framework's own attributes at render time — **the author wins on every key**, recursively through nested `data`:
+
+- **`link:`** applies to every `<a>` rendered for the action: the toolbar link (GET), dropdown items (**any** HTTP method — dropdown items are always anchors, submitting via `data-turbo-method`), bulk-action links, kanban column action links, and the grid/kanban card's hidden show link (for `:show`).
+- **`button:`** applies to the `button_to` **`<form>`** element of the non-GET toolbar rendering (the form wrapper, not the inner `<button>`).
+
+```ruby
+action :documentation,
+  route_options: {url: "https://docs.example.com"},
+  resource_action: true,
+  link: {target: "_blank", rel: "noopener noreferrer", data: {analytics: "docs"}}
+```
+
+Because the author wins, you can override anything — `turbo_frame`, `class`, `data-*` — at your own risk. Two things to know:
+
+- `class:` **replaces** the framework's classes (no token append) — a bare `link: {class: "mt-2"}` removes the button styling entirely.
+- Pass `data:` as a **hash**. The merge only recurses when both sides are hashes, so a scalar `data:` replaces the framework's data wholesale (dropping `turbo_confirm`/`turbo_frame`).
+
+Both bags round-trip through [`with(...)`](#deriving-variants-action-with), so `defined_actions[:edit].with(link: {target: "_blank"})` works in `customize_actions`.
+
 ### Deriving variants — `Action#with(...)`
 
 Action records are frozen value objects. Inside `customize_actions`, derive a copy with overrides:
@@ -87,7 +117,7 @@ def customize_actions
 end
 ```
 
-## Conditional visibility — `condition:`
+## Conditional visibility — `condition:` {#conditional-visibility}
 
 Like the `condition:` proc on [inputs/displays/columns](/reference/resource/definition), an action can be **defined but only rendered when a runtime proc is truthy**. It's purely a toggle on whether the **button is shown** — the action (and its route) stays fully live either way.
 
@@ -139,6 +169,48 @@ end
 `condition: -> { object.draft? }` is fine for **showing/hiding** a per-record button. But if the rule is about **who may run it** ("only while draft *and* nobody else has it locked"), put it in the policy — `def publish? = record.draft?` is also evaluated per record (per row), and unlike `condition:` it actually gates execution.
 :::
 
+## Hidden actions — `hidden: true` {#hidden-actions}
+
+An action declared `hidden: true` renders in **no** toolbar, row dropdown, card, or bulk bar — regardless of its visibility flags, the policy, or `condition:`. Everything else about it stays live:
+
+- the **route** is mounted;
+- the **policy predicate** (`def name?`) is defined and enforced;
+- for `interaction:`-based actions, the **form and permitted-params machinery** work exactly as they do for a visible action.
+
+```ruby
+action :reposition, hidden: true
+```
+
+The use case is an endpoint reached by **something other than a button** — a drag gesture, a custom Stimulus controller, a client-side widget you wrote yourself. The framework uses it for exactly that: [`position_on`](/reference/positioning) expands to `action :reposition, hidden: true`, and the kanban board's drop endpoint is declared the same way.
+
+### `hidden:` vs `condition: -> { false }`
+
+Both suppress the button, so pick by intent:
+
+| | `hidden: true` | `condition: -> { false }` |
+|---|---|---|
+| Decided | at **class-load**, once | at **render time**, per row/request |
+| Costs | nothing — the surfaces filter it out before any policy or condition runs | a proc evaluation per rendering |
+| Says | "this is never a button" | "this is a button, just not right now" |
+
+Use `hidden:` for an action that is *structurally* not a button. Use `condition:` when visibility genuinely depends on the record, the user, or the request.
+
+::: danger `hidden:` is a display gate, NOT an authorization boundary
+This is the same trap as [`condition:`](#conditional-visibility), and it bears repeating because "hidden" reads more absolute than it is. A hidden action has a **live route**: anyone who can construct the URL can call it.
+
+```ruby
+# 🚫 WRONG — hiding the button does not stop the request.
+action :purge_all, interaction: PurgeInteraction, hidden: true
+
+# ✅ RIGHT — authorization belongs in the policy.
+class WidgetPolicy < ResourcePolicy
+  def purge_all? = current_user.admin?
+end
+```
+
+**Rule of thumb, unchanged:** "who may run this" → **policy**. "does a button belong here" → `hidden:` / `condition:`.
+:::
+
 ## Simple actions (navigation)
 
 Link to an existing route. The target route MUST exist.
@@ -176,6 +248,8 @@ For anything with business logic, use an **interactive action** instead.
 
 Run an [Interaction](/reference/behavior/interactions) — automatically renders a form if the interaction declares attributes beyond `:resource`/`:resources`, otherwise executes immediately with a confirmation.
 
+The interactions below call named model methods (`archive!`, `invite!`) rather than doing the work inline. That's not mandatory for a one-off — the trigger to extract is the second caller, since an interaction can only be built with a `view_context`. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+
 ```ruby
 class PostDefinition < Plutonium::Resource::Definition
   action :publish, interaction: PublishInteraction
@@ -233,7 +307,7 @@ class InviteUserInteraction < Plutonium::Resource::Interaction
   validates :role,  presence: true
 
   def execute
-    UserInvite.create!(company: resource, email: email, role: role)
+    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)
@@ -299,6 +373,25 @@ end
 action :import, interaction: ImportInteraction
 ```
 
+## Running the work in the background
+
+An interactive action executes inside the request. When that is too slow — a bulk action over thousands of records, or a single call to something slow — replace `execute` with `async` and the interaction dispatches a persisted, resumable run instead:
+
+```ruby
+class BulkArchiveInteraction < ResourceInteraction
+  attribute :resources
+
+  async do
+    on_failure :continue
+    def perform_on(record) = record.archive!
+  end
+end
+```
+
+Nothing else about the action changes: same `action` declaration, same policy method, same form. The user is returned where they were, and that index shows a banner linking to the run's progress page.
+
+See [Async Interactions](/reference/behavior/async-interactions) for failure policies, file attributes, and what happens when a run crashes mid-batch.
+
 ## Immediate vs form
 
 | Interaction shape | Behavior |

data/docs/reference/resource/definition.md

@@ -42,8 +42,8 @@ end
 
 # packages/admin_portal/app/definitions/admin_portal/post_definition.rb (per-portal)
 class AdminPortal::PostDefinition < ::PostDefinition
-  input :internal_notes, as: :text     # admins see this; customers don't
   scope :pending_review
+  input :internal_notes, hint: "Not shown to the author"
 end
 ```
 
@@ -200,6 +200,39 @@ field   :debug_info,       condition: -> { Rails.env.development? }
 `condition:` is for UI logic ("show this when published"). For "who can see this", use the policy's `permitted_attributes_for_*` — see [Behavior › Policy](/reference/behavior/policies).
 :::
 
+## Options that vary per render
+
+Any option may be a **proc**, resolved on every render rather than frozen when the class loads. This holds across the whole form DSL — `field`, `input`, `section`/`ungrouped`, `structured_input` and nested inputs. Arity says **whether you want the form**:
+
+```ruby
+input :tier,  as: :select, choices: ->(form) { form.object.account.available_tiers }
+input :notes, placeholder: -> { "Updated #{Time.current.year}" }
+```
+
+- **`-> { … }`** is called as-is, keeping whatever it closed over — it means what it reads like where you wrote it. Nothing rebinds `self`. That is what lets an option declared inside an interaction's `customize_inputs` reach the interaction, private helpers included: `choices: -> { reviewer_choices }`.
+- **`->(form) { … }`** is handed the form, so `object` (the record being edited), `params` and view helpers are reachable. Use it whenever the value depends on what is being rendered.
+
+The rule holds on wizard steps too — but there a zero-argument proc closes over an internal field recorder, so options must take the form and read the run off it: `->(form) { form.wizard.anchor.tiers }`. See [Wizard DSL › Runtime input options](/reference/wizard/dsl#runtime-input-options).
+
+### `condition:` is not an option
+
+`condition:` follows a different rule, and it is worth knowing why rather than memorising it as an exception. The two are different kinds of thing:
+
+| | asks | so it | receiver |
+|---|---|---|---|
+| an **option** (`choices:`, `label:`, `collapsed:`, …) | "what value should this have?" | may or may not care about the render — so it means what it reads like where you wrote it, and takes `form` when it does care | its own closure, or the form |
+| **`condition:`** | "should this render *here, now*?" | is a question about the render context by definition — there is no useful reading of it that ignores that context | always the thing doing the rendering |
+
+So `condition:` always runs **against** its context and reads it with no argument — and "its context" is whatever is rendering: the form for a field, section or nested input; the component for a `column` or `display`; the **wizard** for a step's `condition:` (evaluated in the runner to decide which steps exist, before any form is built); a condition context for an action or scope.
+
+```ruby
+input   :notes,     condition: -> { object.published? }        # form
+display :audit_log, condition: -> { current_user.admin? }      # display component
+step    :billing,   condition: -> { data.plan.tier == "pro" }  # wizard, no form exists yet
+```
+
+That is why it cannot take a `form` argument the way an option does: in several of those places there is no form.
+
 ## Dynamic forms (`pre_submit`)
 
 A field with `pre_submit: true` triggers a server re-render on change, re-evaluating `condition:` procs. Use for cascading or context-dependent forms.
@@ -260,16 +293,16 @@ input :birth_date do |f|
 end
 ```
 
-### `phlexi_tag` for declarative custom display
+### `phlexi_render` for declarative custom display
 
-`with:` takes either a Phlex component class OR a proc whose body is **rendered inside a Phlex context** — HTML tag methods (`span`, `div`, `a`) and Tailwind classes are first-class. The proc receives `(value, attrs)`.
+`as: :phlexi_render` (or its shorthand `as: :phlexi`). `with:` takes either a Phlex component class OR a proc whose body is **rendered inside a Phlex context** — HTML tag methods (`span`, `div`, `a`) and Tailwind classes are first-class. The proc receives `(value, attrs)`.
 
 ```ruby
 # Component — preferred for anything reusable
-display :status, as: :phlexi_tag, with: StatusBadgeComponent
+display :status, as: :phlexi_render, with: StatusBadgeComponent
 
 # Inline proc — `span` here is a Phlex tag method, not a Rails helper
-display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+display :priority, as: :phlexi_render, with: ->(value, attrs) {
   case value
   when 'high'   then span(class: "badge badge-danger")  { "High" }
   when 'medium' then span(class: "badge badge-warning") { "Medium" }
@@ -282,11 +315,27 @@ See [UI › Components](/reference/ui/components) for writing reusable Phlex com
 
 ### Custom component class
 
+`as:` takes a **field component** — Plutonium constructs it as
+`YourComponent.new(field, **attributes)`, so it subclasses
+`Phlexi::Form::Components::Base` (inputs) or `Phlexi::Display::Components::Base`
+(displays) and reads the value off `field`:
+
 ```ruby
 input   :color_picker, as: ColorPickerComponent
 display :chart,        as: ChartComponent
 ```
 
+A component with its own constructor (e.g. `PostCardComponent.new(post:)`) is not
+an `as:` candidate — it would raise `ArgumentError`. Build it in a block instead:
+
+```ruby
+display :card do |field|
+  PostCardComponent.new(post: field.object)
+end
+```
+
+See [UI › Components › Field components](/reference/ui/components#field-components).
+
 ## Column options
 
 ```ruby
@@ -511,15 +560,26 @@ Groups a set of fields under an optional heading.
 | `columns:` | Positive Integer. Overrides the section grid column count (e.g. `columns: 2`). Omit to use the form's default responsive grid. Must be a positive Integer — any other value raises. (Literal only — not dynamic.) |
 | `condition:` | Lambda evaluated in the form instance context — same semantics as `input ..., condition:`. `object`, `current_user`, helpers etc. are all available. A falsey result hides the entire section and withholds its fields (they do not spill into `ungrouped`). |
 
-Every option except `columns:` may be either a literal **or a proc** resolved at render time in the same form instance context as `condition:` (so `object`, `current_user`, `params`, helpers are all available). This makes the layout record-aware — e.g. collapse a section by default only for existing records:
+Every option except `columns:` may be either a literal **or a proc** resolved at render time, following the same arity rule as every other option ([Options that vary per render](#options-that-vary-per-render)): take a `form` argument to read the render context. This makes the layout record-aware — e.g. collapse a section by default only for existing records:
 
 ```ruby
 section :advanced, :seo_title, :notes,
   collapsible: true,
-  collapsed: -> { object.persisted? },          # open for new, collapsed for edits
-  label: -> { object.new_record? ? "Set up" : "Advanced" }
+  collapsed: ->(form) { form.object.persisted? },          # open for new, collapsed for edits
+  label: ->(form) { form.object.new_record? ? "Set up" : "Advanced" }
 ```
 
+::: warning Breaking change in 0.63
+Section options previously took a **zero-argument** proc evaluated against the form (`collapsed: -> { object.persisted? }`). They now follow the same rule as every other option, where a zero-argument proc keeps its own binding — and a `form_layout` block is evaluated against the layout builder, so `object` there is a `NameError`.
+
+```ruby
+- collapsed: -> { object.persisted? }
++ collapsed: ->(form) { form.object.persisted? }
+```
+
+It fails loudly, never silently. `condition:` is unchanged — it is still evaluated against the form and still reads `object` with no argument.
+:::
+
 A section that resolves to **zero fields** — every declared field filtered out by the permitted set, or no field assigned — renders nothing at all (no heading, no grid). This keeps forms clean when fewer attributes are permitted than declared (notably `+ New`, where the create policy often permits a subset). The check is purely "are there fields to render"; it does **not** evaluate per-field `condition:` procs (those run later, at field render). So if you want a whole section to appear only under some state, gate it with the section's own `condition:` rather than relying on every field inside it being hidden:
 
 ```ruby
@@ -584,7 +644,7 @@ A `section` only renders the fields that are actually in the form's permitted se
 
 `form_layout` is also available on `Plutonium::Interaction::Base`. The same DSL groups the interaction's `attribute` declarations into sections. Interaction forms (`Plutonium::UI::Form::Interaction`) pick up the layout automatically — no extra wiring needed.
 
-Dynamic options and `condition:` work here too, with one difference: in an interaction form `object` is the **interaction instance** (not a record). For a record action, the record is `object.resource` — so e.g. `collapsed: -> { object.resource.archived? }`.
+Dynamic options and `condition:` work here too, with one difference: on an interaction form the form's `object` is the **interaction instance** (not a record). For a record action, the record is `object.resource` — so e.g. `collapsed: ->(form) { form.object.resource.archived? }`, and `condition: -> { object.resource.archived? }` (which is form-evaluated, so it needs no argument).
 
 ```ruby
 class PublishPostInteraction < Plutonium::Interaction::Base
@@ -602,6 +662,116 @@ class PublishPostInteraction < Plutonium::Interaction::Base
 end
 ```
 
+## Display layout
+
+The show page's counterpart to [`form_layout`](#form-layout). Same DSL and the same resolution rules — first-section-wins ownership, unlisted permitted fields collected into `ungrouped`, absent fields skipped, zero-field sections dropped entirely — applied to the show page instead of the form.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  display_layout do
+    section :profile, :name, :author, label: "Profile", description: "Identity and owner"
+    section :presentation, :cover, :body,
+      collapsible: true,
+      condition: -> { object.published? }
+    ungrouped label: "Other details"
+  end
+end
+```
+
+With no `display_layout` declared the show page renders unchanged as a single card holding one responsive grid — fully backwards-compatible.
+
+### Independent of `form_layout`
+
+The two are separate registries. A resource may declare either, both, or neither, and grouping its form one way has no effect on its show page. Both inherit to subclasses and are replaced as a unit when re-declared.
+
+### No `columns:`
+
+Unlike `form_layout`, `display_layout` **raises** on `columns:`:
+
+```ruby
+display_layout do
+  section :a, :x, columns: 2   # ArgumentError
+end
+```
+
+Every display section renders into the same responsive grid. Field width is a per-field concern, set the same way inside a section as outside one:
+
+```ruby
+display :body, wrapper: {class: "col-span-2"}
+```
+
+Raising rather than ignoring the option means a `form_layout` block copied across fails immediately, instead of silently having no effect.
+
+### Section options
+
+`label:`, `description:`, `collapsible:`, `collapsed:`, `condition:` — the same set as [`section(key, *fields, **opts)`](#section-key-fields-opts) minus `columns:`. A collapsible display section behaves exactly as a form one does, `collapsed:` included.
+
+Every option except `condition:` may be a proc, resolved at render under the same arity rule the form uses — a zero-arity proc keeps its own binding, a one-arity proc is handed the display:
+
+```ruby
+section :audit, :created_at, collapsible: true, collapsed: ->(display) { display.object.active? }
+```
+
+`condition:` is evaluated separately and against the display, where `object` is the record.
+
+### Rendering
+
+Each section renders as its own card, stacked by a `sections_wrapper` container — so a sectioned show page has **no single outer card**. Fields declared via [`metadata`](#metadata-panel-show-page) are excluded from the sections and render in the metadata panel instead. Section chrome is themeable; see [UI › Displays › Theming](/reference/ui/displays#theming).
+
+## Page width
+
+Detail-style pages — the show page and resource forms — are constrained to a readable column by default. Inputs and values stretch to their container, so at full content width they become ~1200px-wide text boxes: past a comfortable measure, and a long eye-travel between a label and the value beside it.
+
+Index and table pages are deliberately **not** affected; a table wants every pixel.
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure { |config| config.default_page_width = :md }
+
+class PostDefinition < ResourceDefinition
+  page_width :lg          # this resource's form AND show page
+end
+```
+
+### Sizes
+
+`:sm` `:md` `:lg` `:xl` `:full`. `:full` opts out of any constraint. An unknown value raises `ArgumentError` at declaration rather than silently rendering at some other width.
+
+::: warning Size tokens are relative to their surface
+These are the same token *names* [modal sizes](#modals) use, but **not the same widths**. Each surface has its own scale, because the surfaces aren't comparable — a "small page" is reasonably larger than a "small dialog":
+
+| Token | Page width | Centered modal | Slideover |
+|---|---|---|---|
+| `:sm` | 672px | 448px | 400px |
+| `:md` | 896px | 576px | 480px |
+| `:lg` | 1152px | 672px | 640px |
+| `:xl` | 1280px | 896px | 800px |
+| `:full` | unconstrained | 95vw | 95vw |
+
+Modals additionally support `:auto` (hug the content); a page has nothing to hug, so it does not.
+:::
+
+### Per-surface overrides
+
+`form_width` and `display_width` override `page_width` for one surface only:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  page_width    :lg
+  display_width :full     # the show page runs full width; the form stays :lg
+end
+```
+
+Resolution, most specific first: the surface-specific setting → `page_width` → `Plutonium.configuration.default_page_width`. An explicit `:full` is a real choice and is honoured, not treated as "unset".
+
+All three inherit to subclasses, so a portal-specific definition keeps its parent's width unless it says otherwise.
+
+### Scope
+
+- **Modals are unaffected** — a dialog sizes itself via `modal_size`.
+- **Interactions** (`Plutonium::Interaction::Base`) support the same settings, for interactive actions rendered as standalone pages.
+- **Wizards are configured separately**, via `Plutonium.configuration.wizards.width`. It defaults to `default_page_width`, so a wizard step carrying a `form_layout` renders those sections at the same width the identical sections get on a resource form.
+
 ## File uploads
 
 ```ruby
@@ -684,6 +854,8 @@ class PostDefinition < ResourceDefinition
   #   :centered              — centered dialog
   #   false                  — full standalone pages (no modal)
   # size: optional, one of :sm, :md (default), :lg, :xl, :auto, :full
+  #       (widths are per-surface — see Page width; a slideover's :md is 480px,
+  #        a centered dialog's is 576px, a page's is 896px)
   modal :centered, size: :lg
 end
 ```

data/docs/reference/tenancy/invites.md

@@ -161,7 +161,7 @@ configure do
   login_redirect "/welcome"
 
   after_login do
-    session[:after_welcome_redirect] = session.delete(:login_redirect)
+    session[:after_welcome_redirect] = session.delete(login_redirect_session_key)
   end
 end
 ```

data/docs/reference/tenancy/nested-resources.md

@@ -45,6 +45,40 @@ For `has_one`:
 - Only one record can exist per parent.
 - Forms don't show the parent field (determined by URL).
 
+## Declaring which associations get routes
+
+By default every `has_many` and `has_one` whose child is a registered resource gets
+a nested route. Name the ones you want and the rest are not drawn:
+
+```ruby
+register_resource ::Company, associations: %i[properties company_profile]
+```
+
+`associations: []` draws none. Naming an association that is not a `has_many` or
+`has_one`, or whose child is not registered in that portal, fails the boot rather
+than quietly drawing one route fewer.
+
+To make declaring them the rule rather than the exception, flip the default so that
+a resource naming none gets none:
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.nested_association_routes = :declared   # default: :detected
+end
+```
+
+The mode only decides what silence means. `associations:` works the same either way,
+and top-level routes are untouched by both.
+
+Two things to know before turning it on:
+
+- It applies to every portal at once, and every resource that names nothing loses its
+  nested routes. On an existing app, expect to add `associations:` in several places.
+- A policy's `permitted_associations` renders a panel on the show page that links to
+  the nested route. An association permitted there but omitted here leaves that panel
+  pointing at a route that does not exist. The two lists have to agree.
+
 ## Automatic behavior on nested routes
 
 When the controller is hit via a nested route, Plutonium automatically:
@@ -53,7 +87,8 @@ When the controller is hit via a nested route, Plutonium automatically:
 2. **Scopes queries** via the parent association:
    - `has_many` → `parent.send(parent_association)` (e.g. `company.properties`)
    - `has_one` → `relation.where(foreign_key => parent.id)` with limit
-3. **Assigns the parent** on create (injected into `resource_params`).
+3. **Assigns the parent** on create (injected into `resource_params`), building the
+   record on the parent's association so a scoped association supplies its defaults.
 4. **Hides the parent field** in forms and displays (already determined by URL).
 
 You don't add hidden parent fields or filter queries manually.
@@ -62,11 +97,13 @@ You don't add hidden parent fields or filter queries manually.
 
 ```ruby
 current_parent              # parent record (e.g. Company instance)
+current_parent_class        # parent class (e.g. Company)
 current_nested_association  # association name (e.g. :properties)
-parent_route_param          # URL param (e.g. :company_id)
 parent_input_param          # form param / association name (e.g. :company)
 ```
 
+Each nested route carries the key of its own registration, so the parent class and association are **read from the route** rather than reconstructed from the URL. That is what lets a resource registered `singular: true` act as a parent at all — it contributes no id parameter, so there is nothing in the path to infer from.
+
 ## Parent vs entity scoping
 
 When a parent is present, **parent scoping wins**: `default_relation_scope` scopes via the parent association, NOT `entity_scope`. The parent was already authorized and entity-scoped during its own authorization — double-scoping is redundant.
@@ -163,6 +200,27 @@ resource_params
 
 No hidden parent fields needed in forms.
 
+### Scoped associations
+
+The record is built on the parent's association (`company.properties.new`), so an
+association that carries a scope contributes its equality conditions as defaults:
+
+```ruby
+class Company < ResourceRecord
+  has_many :published_properties, -> { where(published: true) },
+    class_name: "Property"
+end
+```
+
+Creating through `/companies/123/nested_published_properties` sets `published: true`.
+It has to: the index honours the same scope, so a record created without it is
+filtered out of the list it was created from.
+
+Only equality conditions become attributes. A scope like
+`-> { where("expires_at > ?", Time.current) }` cannot supply one, so an association
+scoped that way still creates records its own index will not list. Prefer an
+equality scope for any association you expose as a nested route.
+
 ## Presentation hooks
 
 Control whether the parent field appears in views/forms:

data/docs/reference/ui/assets.md

@@ -240,6 +240,10 @@ Plutonium uses a comprehensive CSS custom-property system for consistent, themea
 }
 ```
 
+::: warning Mirror every `:root` override in `.dark`
+Your stylesheet loads after Plutonium's, and `:root` and `.dark` have equal specificity — so a token you override in `:root` beats Plutonium's `.dark` value even when dark mode is active. Any color token you customize in `:root` without re-asserting in `.dark` ships your light value into dark mode, where it's typically unreadable (e.g. a translucent dark `--pu-text-subtle` becomes invisible on a dark surface).
+:::
+
 ### Using tokens in templates
 
 ```erb

data/docs/reference/ui/components.md

@@ -101,20 +101,27 @@ class PostCardComponent < Plutonium::UI::Component::Base
 end
 ```
 
-::: tip Always inherit `Plutonium::UI::Component::Base`
+::: tip Inherit `Plutonium::UI::Component::Base`
 It gives you:
 - The component kit (`PageHeader`, `Panel`, `Block`, …)
 - Resource helpers (`resource_url_for`, `current_user`, `current_record!`, `current_definition`)
 - A `helpers` proxy for Rails helpers (`helpers.link_to`, `helpers.number_to_currency`)
 - Token / class helpers (`tokens`, `classes`)
+
+A **field** component (one you pass to `as:`) inherits its Phlexi base instead —
+`include Plutonium::UI::Component::Behaviour` there to get the same helpers.
 :::
 
 ### Use in a definition
 
+A component like `PostCardComponent` above has its own constructor, so it reaches
+a field through the **block form** — you build it yourself:
+
 ```ruby
 class PostDefinition < ResourceDefinition
-  display :card, as: PostCardComponent       # custom display component
-  input   :color, as: ColorPickerComponent   # custom input component
+  display :card do |field|
+    PostCardComponent.new(post: field.object)
+  end
 
   display :metrics do |field|
     MetricsChartComponent.new(data: field.value)
@@ -122,6 +129,52 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+`as: SomeComponent` is the other route, and it expects a **field component** —
+Plutonium instantiates it with the field builder, not with your keyword
+arguments. See [field components](#field-components) below.
+
+::: warning `as:` does not take a keyword-argument component
+`display :card, as: PostCardComponent` raises `ArgumentError: wrong number of
+arguments` — the component is constructed as `PostCardComponent.new(field,
+**attributes)`. Use the block form for those.
+:::
+
+### Field components
+
+A field component subclasses the Phlexi component base for its surface and reads
+everything off `field` (`field.value`, `field.object`, `field.dom`, plus
+`attributes` — the themed id/name/class Plutonium already computed):
+
+```ruby
+# app/components/color_picker_component.rb
+class ColorPickerComponent < Phlexi::Form::Components::Base
+  include Phlexi::Form::Components::Concerns::HandlesInput  # name/id/value plumbing
+
+  def view_template
+    input(**attributes, type: "color", value: field.value)
+  end
+end
+
+# app/components/chart_component.rb
+class ChartComponent < Phlexi::Display::Components::Base
+  include Plutonium::UI::Component::Behaviour  # optional: kit + resource helpers
+
+  def view_template
+    div(class: "h-40", data: {controller: "chart", chart_series_value: field.value.to_json})
+  end
+end
+```
+
+```ruby
+class PostDefinition < ResourceDefinition
+  input   :color, as: ColorPickerComponent   # custom input component
+  display :chart, as: ChartComponent         # custom display component
+end
+```
+
+An `as:` component works in every surface that renders the field — form, show
+page, index column, filter panel and wizard summary alike.
+
 ### Use in a page / form / display
 
 ```ruby
@@ -213,6 +266,6 @@ Inside any custom component, the same set of helpers as pages/forms/displays —
 ## Related
 
 - [Pages](./pages) — `render_*` hooks call your components
-- [Forms](./forms) — using custom input components via `as: MyComponent`
+- [Forms](./forms) — the built-in input tags and their `as:` aliases
 - [Displays](./displays) — using custom display components
 - [Assets](./assets) — design tokens (`var(--pu-*)`) and `.pu-*` component classes