plutonium 0.59.0 → 0.60.0

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/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
+```
+
+### Referencing an unknown field raises
+
+A `section` that lists a field key that is not a known attribute of the model raises `ArgumentError` at render time — this catches typos early.
+
+### 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