plutonium 0.58.1 → 0.60.0

data/docs/.vitepress/config.ts

@@ -131,6 +131,7 @@ export default defineConfig(withMermaid({
             { text: "Definition", link: "/reference/resource/definition" },
             { text: "Query", link: "/reference/resource/query" },
             { text: "Actions", link: "/reference/resource/actions" },
+            { text: "CSV Export", link: "/reference/resource/export" },
           ]
         },
         {

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/actions.md

@@ -360,6 +360,9 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+> **CSV export is not an action.** It's a built-in, policy-gated capability with its own
+> button — see [CSV Export](./export.md). Don't declare it with `action :export_csv`.
+
 ## Interaction responses
 
 ```ruby

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/resource/export.md

@@ -0,0 +1,94 @@
+# CSV Export
+
+Every resource ships with a streamed CSV export, **disabled by default**. It is *not* an
+[action](./actions.md) — it streams a file and opens in a new tab — so it is enabled
+through the policy rather than declared with `action :export_csv`. The route
+(`GET /<resources>/export_csv`) is auto-mounted on every resource; a split "Export"
+button appears on the index page once the policy permits it.
+
+## Enabling
+
+Override one policy method:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def export_csv? = true   # or `index?` to mirror list access
+end
+```
+
+`export_csv?` defaults to `false`, so export is strictly opt-in. While it returns false
+the button is hidden and the route returns `403`.
+
+## The two exports
+
+The control is a split button with two behaviours:
+
+| | Source | Filename |
+|---|---|---|
+| **Export** (primary) | The current view — selected scope + filters + search (the index's `?q`), **all** matching rows (not just the visible page) | `posts_<date>.csv` |
+| **Export all** (dropdown) | The entire authorized scope — ignores scope, filters, search, and default scope | `posts_all_<date>.csv` |
+
+"Export all" always exports everything the user is authorized to read, regardless of the
+current scope/filters.
+
+Both stream via `find_each`, so memory stays flat regardless of row count. `find_each`
+iterates in **primary-key order**, so the file does not preserve the index's current
+sort (filters/search/scope still apply to the primary export).
+
+## Columns
+
+The exported columns come from `permitted_attributes_for_export` on the policy (defaults
+to `permitted_attributes_for_index`), with the **primary key always prepended as the
+first column**.
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def export_csv? = true
+  def permitted_attributes_for_export = [:title, :author, :total, :created_at]
+end
+```
+
+The method is named `_export` (not `_export_csv`) on purpose, so a future export format
+could reuse the same column set.
+
+## Customizing a field's output
+
+The `export` definition DSL parallels `display` and `column`. The block receives the
+record and returns the cell value; `label:` overrides the header (default: the humanized
+attribute name).
+
+```ruby
+class PostDefinition < ResourceDefinition
+  export :author, label: "Author email", &->(post) { post.author.email }
+  export :total,                          &->(post) { post.total.format }
+end
+```
+
+The column *set* still comes from `permitted_attributes_for_export`; `export` only
+customizes how a listed column is rendered.
+
+## Value resolution
+
+For a column **without** an `export` block, the value is read straight off the record
+(`record.public_send(name)`):
+
+- **Scalars** (strings, numbers, booleans, dates) are written as-is.
+- **Associations** render as their display label — the same `display_name_of` the index
+  uses (e.g. `User #5`, or the record's `to_label`/`name`/`title` if defined) — never
+  `#<User:0x…>`. Add an `export` block to export a specific field instead (e.g. the email).
+- A name that is **neither** an `export` block **nor** a real method on the record renders
+  the placeholder `<<invalid column>>` rather than aborting the (already-streaming) download.
+  To export a computed or virtual column, give it an `export` block — a `label:`-only
+  `export` does **not** supply a value, so it too renders the placeholder.
+
+## Notes & limits
+
+- Exports run **synchronously** and hold the request (and a DB connection) while
+  streaming. A background job that emails a download link is intentionally out of scope
+  for now.
+- The export button opens in a new tab (`target="_blank"`), which also keeps Turbo from
+  intercepting the streamed download.
+- **CSV/formula injection** is neutralized: any cell whose value begins with `=`, `+`,
+  `-`, `@`, or a leading tab/CR is prefixed with a single quote so spreadsheet apps import
+  it as literal text instead of executing it as a formula.
+- `csv` is a runtime dependency of Plutonium (it is no longer a Ruby default gem on 3.4+).

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