plutonium 0.59.0 → 0.60.1

data/docs/reference/auth/accounts.md

@@ -80,6 +80,13 @@ rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
 enum :role, super_admin: 0, admin: 1
 ```
 
+**Invite + resend.** The admin resource gets two actions:
+
+- **Invite** — invite a new admin by email; Rodauth sends a verification link and the invitee sets their own password through the verify flow.
+- **Resend invitation** — re-send the verification email. Only shown for admins who haven't verified yet.
+
+This uses Rodauth account verification, separate from the [Tenancy › Invites](/reference/tenancy/invites) system.
+
 Rake task for direct admin creation (generated alongside the account — namespace is `rodauth`, task name is the account name):
 
 ```bash

data/docs/reference/configuration.md

@@ -35,7 +35,7 @@ Loads the baseline defaults for a given framework version. Call this first; late
 | `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. You rarely set this in an app — see [Development mode](#development-mode). |
 | `cache_discovery` | `true` outside `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
 | `enable_hotreload` | `true` in `development` env | Hot-reload Plutonium components on change. |
-| `shell` | `:modern` | Chrome style: `:modern` (topbar + icon rail) or `:classic` (legacy header + sidebar, only for upgrades). See [Layouts](./ui/layouts). |
+| `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. |
 | `assets.logo` | `"plutonium.png"` | Brand logo asset. See [Assets](./ui/assets). |
 | `assets.favicon` | `"plutonium.ico"` | Favicon asset. |

data/docs/reference/resource/definition.md

@@ -459,6 +459,135 @@ validate do
 end
 ```
 
+## Form layout
+
+Declare a declarative layout for forms without changing per-field configuration. Sections are evaluated against the policy-filtered field list at render time, so a field filtered out by the policy is simply skipped.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  form_layout do
+    section :identity, :title, :slug,
+      label: "Post identity", description: "Visible URL and title"
+
+    section :content, :body, :excerpt,
+      collapsible: true, columns: 1
+
+    section :publishing, :published_at, :category,
+      collapsible: true, collapsed: true,
+      condition: -> { current_user.publisher? }
+
+    ungrouped label: "Other details"
+  end
+end
+```
+
+### `form_layout` block
+
+The block is evaluated once and stored on the class. Re-declaring `form_layout` in a subclass replaces the parent layout as a unit; per-field `input` config inherits normally.
+
+With no `form_layout` declared the form renders unchanged as a single responsive grid — fully backwards-compatible.
+
+### `section(key, *fields, **opts)`
+
+Groups a set of fields under an optional heading.
+
+| Argument | Description |
+|---|---|
+| `key` | Symbol. `:ungrouped` is reserved — use the `ungrouped` macro instead (raises `ArgumentError` otherwise). |
+| `*fields` | Ordered field keys to place in this section. |
+| `label:` | Section heading. Defaults to `key.to_s.humanize` (e.g. `:shipping_address` → `"Shipping address"`). |
+| `description:` | Optional help line rendered below the heading. |
+| `collapsible:` | Boolean (default `false`). Wraps the section in a native `<details>/<summary>` (no JS). |
+| `collapsed:` | Boolean (default `false`). Initial collapsed state when `collapsible: true`. |
+| `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:
+
+```ruby
+section :advanced, :seo_title, :notes,
+  collapsible: true,
+  collapsed: -> { object.persisted? },          # open for new, collapsed for edits
+  label: -> { object.new_record? ? "Set up" : "Advanced" }
+```
+
+Empty sections (all fields filtered by the policy, or none assigned) are **not** hidden automatically. Use `condition:` to hide a section conditionally.
+
+### `ungrouped(**opts)`
+
+A macro (not a `section` call) that configures the implicit bucket collecting every permitted field not claimed by any `section`. Takes **no field list** — its fields are computed at render time.
+
+- Accepts the same options as `section`: `label:`, `description:`, `collapsible:`, `collapsed:`, `columns:`, `condition:`.
+- **Position** — where you call `ungrouped` in the block is where leftovers appear. Omit it entirely and leftovers render **last**, after every declared section, with no heading. (Declaring `ungrouped` at the very end is therefore equivalent to omitting it, except that the explicit form lets you add a `label:` and other options.)
+- Declaring `ungrouped` more than once in a single `form_layout` raises `ArgumentError`.
+
+```ruby
+form_layout do
+  section :advanced, :seo_title, :seo_description, collapsible: true
+  ungrouped label: "Core fields"   # leftovers rendered here, with a heading
+end
+
+# To float leftovers ABOVE your sections, declare `ungrouped` first:
+form_layout do
+  ungrouped label: "Core fields"
+  section :advanced, :seo_title, :seo_description, collapsible: true
+end
+```
+
+### Layout references keys; config stays on `input`
+
+`form_layout` and `section` carry section-level options only. All per-field rendering config — `as:`, the field's own `label:`, `choices:`, per-field `condition:`, `pre_submit:`, blocks — remains on the `input` declaration. Layout never duplicates field config.
+
+This includes a field's **column span**. In a section with `columns:`, fields flow into single grid cells by default; a field that declares its own span via `wrapper: {class: "col-span-..."}` keeps it — a field-level span always wins, so you can opt one field back to full width inside a multi-column section:
+
+```ruby
+input :notes, wrapper: {class: "col-span-full"}   # spans the whole row...
+
+form_layout do
+  section :details, :first_name, :last_name, :notes, columns: 2  # ...even here
+end
+```
+
+```ruby
+class ArticleDefinition < ResourceDefinition
+  # per-field config on input — untouched by form_layout
+  input :body, as: :markdown
+  input :published_at, hint: "Leave blank to save as draft"
+  input :visibility, as: :select, choices: %w[public private unlisted]
+
+  form_layout do
+    section :writing, :title, :body, :excerpt, label: "Content"
+    section :meta, :published_at, :visibility, :tags, label: "Publishing settings"
+  end
+end
+```
+
+### Fields not in the permitted set are skipped
+
+A `section` only renders the fields that are actually in the form's permitted set for the current request. A key it lists that isn't there — a typo, or a field excluded by policy, per-action `permitted_attributes`, entity scoping, or nesting — is **silently dropped**, never an error. This lets a single `form_layout` reference conditionally-permitted fields without crashing the form in the contexts where they're filtered out.
+
+### On interactions
+
+`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? }`.
+
+```ruby
+class PublishPostInteraction < Plutonium::Interaction::Base
+  attribute :publish_at, :datetime
+  attribute :notify_subscribers, :boolean, default: false
+  attribute :notify_message, :string
+
+  form_layout do
+    section :timing, :publish_at, label: "When to publish"
+    section :notifications, :notify_subscribers, :notify_message,
+      label: "Subscriber notifications",
+      collapsible: true,
+      condition: -> { object.has_subscribers? }
+  end
+end
+```
+
 ## File uploads
 
 ```ruby

data/docs/reference/ui/forms.md

@@ -47,40 +47,70 @@ end
 
 ## Custom layouts
 
-### Sectioned form
+### Sectioned form (declarative — preferred)
+
+Declare sections in the **definition** using `form_layout`. The form picks up the layout automatically — no `Form` subclass needed for common cases.
 
 ```ruby
-class Form < Form
-  def form_template
-    section("Basic Information") do
-      render_resource_field :title
-      render_resource_field :slug
-    end
+class PostDefinition < ResourceDefinition
+  form_layout do
+    section :basics, :title, :slug,
+      label: "Basic information"
 
-    section("Content") do
-      render_resource_field :content
-      render_resource_field :excerpt
-    end
+    section :content, :body, :excerpt,
+      label: "Content", columns: 1
+
+    section :publishing, :published_at, :category,
+      label: "Publishing", collapsible: true, collapsed: true
+  end
+end
+```
+
+This handles headings, collapsible panels, per-section column counts, and `condition:`-based visibility — all with no view code. See [Resource › Definition › Form layout](/reference/resource/definition#form-layout) for the full DSL reference, including `ungrouped`, `condition:`, `columns:`, and the "On interactions" note.
 
-    section("Publishing") do
-      render_resource_field :published_at
-      render_resource_field :category
+### Full control: override `render_fields`
+
+When the declarative DSL doesn't cover your use case — asymmetric multi-column layouts, embedding a panel widget between sections, etc. — override `render_fields` in a nested `Form` class:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    def form_template
+      render_fields   # replaced below
+      render_actions
     end
 
-    render_actions
-  end
+    def render_fields
+      div(class: "mb-8") do
+        h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { "Basic Information" }
+        fields_wrapper do
+          render_resource_field :title
+          render_resource_field :slug
+        end
+      end
 
-  private
+      div(class: "mb-8") do
+        h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { "Content" }
+        fields_wrapper do
+          render_resource_field :content
+          render_resource_field :excerpt
+        end
+      end
 
-  def section(title, &)
-    div(class: "mb-8") do
-      h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { title }
-      fields_wrapper(&)
+      div(class: "mb-8") do
+        h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { "Publishing" }
+        fields_wrapper do
+          render_resource_field :published_at
+          render_resource_field :category
+        end
+      end
     end
   end
 end
 ```
 
+Prefer `form_layout` in the definition — it keeps layout config out of view code and works for interactions too.
+
 ### Two-column layout
 
 ```ruby

data/docs/reference/ui/layouts.md

@@ -1,12 +1,13 @@
 # Layouts
 
-The overall page chrome — topbar, sidebar, footer, body wrapping. Plutonium ships two shells; you can eject the templates or write a custom `ResourceLayout` for total control.
+The overall page chrome — topbar, sidebar, footer, body wrapping. Plutonium ships three shells; you can eject the templates or write a custom `ResourceLayout` for total control.
 
 ## Shell
 
 ```ruby
 Plutonium.configure do |config|
   config.shell = :modern     # default — topbar + icon rail
+  # config.shell = :plain    # topbar, no icon rail (rail-less app)
   # config.shell = :classic  # legacy header + sidebar (only when upgrading)
 end
 ```
@@ -15,6 +16,41 @@ end
 If you're starting fresh, use `:modern`. `:classic` exists so apps upgrading from pre-`:modern` versions can preserve their chrome while migrating.
 :::
 
+## Shell variants & the icon rail
+
+`config.shell` selects the chrome for the whole app:
+
+- `:modern` (default) — Topbar plus the desktop icon rail.
+- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the whole app is rail-less.
+- `:classic` — legacy Header/Sidebar (upgrade paths only).
+
+### Per-controller / per-portal override
+
+Any Plutonium resource controller exposes a class-level `rail` DSL that overrides the shell default. It's a `class_attribute`, so it's inherited: a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern.
+
+```ruby
+module CustomerPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      included { rail false }  # entire portal rail-less
+    end
+  end
+end
+```
+
+`rail nil` (the default) inherits the shell default — the rail shows when `config.shell == :modern`. Read the resolved value with the `rail?` predicate.
+
+### Stable CSS hooks
+
+Rail-less rendering exposes a few stable hooks for custom overrides:
+
+- `pu-topbar` — class on the Topbar nav.
+- `pu-sticky-footer` — class on the form sticky-footer div.
+- `html.pu-no-rail` — root class present whenever the current page is rail-less.
+
+A built-in rule cancels the desktop rail inset on `.pu-topbar` and `.pu-sticky-footer` under `html.pu-no-rail`; target these hooks to layer your own CSS.
+
 ## Eject the chrome for per-portal customization
 
 ```bash