plutonium 0.51.0 → 0.52.0

data/docs/guides/customizing-ui.md

@@ -0,0 +1,258 @@
+# Customizing the UI
+
+Plutonium's UI is built on Phlex, Tailwind 4, and Stimulus. Almost everything you see — pages, forms, displays, tables, components, layouts, even the design tokens — is open for override. This guide is the map. Each section shows the smallest useful example for one kind of customization, then points to the reference for the full surface.
+
+When you're not sure where to start, read this top to bottom. When you know what you need, jump to the right section and follow the link to reference.
+
+## The override pattern
+
+Customization in Plutonium is overrides via **nested classes inside the definition**, never replacement of the root class. The pattern looks the same everywhere:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class ShowPage < ShowPage; end   # override show page
+  class Form     < Form;     end   # override form
+  class Table    < Table;    end   # override index table
+  class Display  < Display;  end   # override show display
+end
+```
+
+Each nested class inherits from Plutonium's defaults and lets you override only the methods you care about. Don't reimplement the whole layer — use the render hooks below.
+
+→ See [Reference › UI › Pages](/reference/ui/pages) for the full hook list.
+
+## Adding chrome to a page
+
+Most page customization is "I want to add something before/after this section." Use the render hooks; don't override `view_template`.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class ShowPage < ShowPage
+    def render_before_content
+      div(class: "pu-card pu-card-body") do
+        plain "This post has #{object.comments.count} comments"
+      end
+    end
+  end
+end
+```
+
+Hooks exist around the header, breadcrumbs, page header, toolbar, content, and footer — pick the one closest to where you want the thing to appear.
+
+→ See [Reference › UI › Pages](/reference/ui/pages) › Page hooks.
+
+## Customizing a form layout
+
+The default form renders every permitted field in a single grid. To group fields into sections or columns, override `form_template`:
+
+```ruby
+class Form < Form
+  def form_template
+    section("Basic") do
+      render_resource_field :title
+      render_resource_field :slug
+    end
+    section("Publishing") do
+      render_resource_field :published_at
+      render_resource_field :category
+    end
+    render_actions   # REQUIRED — without this, no submit button
+  end
+
+  private
+
+  def section(title, &)
+    div(class: "mb-8") do
+      h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { title }
+      fields_wrapper(&)
+    end
+  end
+end
+```
+
+→ See [Reference › UI › Forms](/reference/ui/forms) for `render_resource_field`, field tags (`flatpickr_tag`, `easymde_tag`, `uppy_tag`, etc.), and Phlexi themes.
+
+## Customizing a display
+
+The show page renders a `Display` for the record. Override `display_template` to add hero blocks, group fields, or interleave custom panels:
+
+```ruby
+class Display < Display
+  def display_template
+    div(class: "pu-card pu-card-body mb-4") do
+      h1 { object.title }
+      p(class: "text-[var(--pu-text-muted)]") { object.excerpt }
+    end
+    Block { fields_wrapper { render_fields } }
+    render_associations if present_associations?
+  end
+end
+```
+
+→ See [Reference › UI › Displays](/reference/ui/displays).
+
+## Replacing a table with a grid
+
+By default the index page renders a `Table`. To use cards instead, override `view_template` on the nested `Table`:
+
+```ruby
+class Table < Table
+  def view_template
+    render_toolbar
+    render_scopes_pills
+    if collection.empty?
+      render_empty_card
+    else
+      div(class: "grid grid-cols-3 gap-4") do
+        collection.each { |post| render PostCardComponent.new(post:) }
+      end
+    end
+    render_footer
+  end
+end
+```
+
+→ See [Reference › UI › Tables](/reference/ui/tables).
+
+## Writing a custom Phlex component
+
+When you need a piece of UI that's reused across pages, write a Phlex component. Inherit from `Plutonium::UI::Component::Base` and you get the component kit (`PageHeader`, `Panel`, `Block`), resource URL helpers, and a `helpers` proxy for Rails helpers.
+
+```ruby
+class PostCardComponent < Plutonium::UI::Component::Base
+  def initialize(post:) = @post = post
+
+  def view_template
+    div(class: "pu-card pu-card-body") do
+      h3(class: "font-bold text-[var(--pu-text)]") { @post.title }
+      p(class: "text-[var(--pu-text-muted)] mt-2") { @post.excerpt }
+      a(href: resource_url_for(@post), class: "pu-btn pu-btn-sm pu-btn-ghost") { "Read more" }
+    end
+  end
+end
+```
+
+Use it directly in a page, or wire it as a field in the definition:
+
+```ruby
+display :card, as: PostCardComponent
+```
+
+→ See [Reference › UI › Components](/reference/ui/components).
+
+## Phlexi themes (recolor without rewriting)
+
+If all you want is to recolor or restyle the form/display/table, write a `Theme` class instead of overriding the template. Always `super.merge(...)` — never replace wholesale:
+
+```ruby
+class Form < Form
+  class Theme < Plutonium::UI::Form::Theme
+    def self.theme
+      super.merge(
+        base:           "bg-[var(--pu-card-bg)] shadow-md rounded-lg p-6",
+        fields_wrapper: "grid grid-cols-2 gap-6",
+        label:          "block mb-2 text-base font-bold",
+      )
+    end
+  end
+end
+```
+
+→ See [Reference › UI › Forms](/reference/ui/forms) › Theme keys, [Reference › UI › Displays](/reference/ui/displays) › Theme, [Reference › UI › Tables](/reference/ui/tables) › Theme.
+
+## Modals and slideovers
+
+By default `:new` and `:edit` render in a slideover panel. Switch to a centered modal or a full standalone page from the definition:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  modal :slideover    # default — slide-in from the right
+  # modal :centered   # centered dialog
+  # modal false       # full standalone page
+end
+```
+
+→ See [Reference › Resource › Actions](/reference/resource/actions) for per-action `modal:` options on interactive actions.
+
+## Layouts and the shell
+
+The layout is the chrome around every resource page — topbar, sidebar, flash region, scripts. Two ways to customize it:
+
+```bash
+# Per-portal: eject the shell partials and edit them directly
+rails generate pu:eject:shell --dest=admin_portal
+# Or eject the whole layout
+rails generate pu:eject:layout
+```
+
+For programmatic overrides, subclass `Plutonium::UI::Layout::ResourceLayout` and use its render hooks (`render_before_main`, `render_body_scripts`, etc.).
+
+→ See [Reference › UI › Layouts](/reference/ui/layouts) and [Theming](/guides/theming) for design tokens.
+
+## Tailwind, Stimulus, and assets
+
+Plutonium ships with a Tailwind config, design tokens, and a set of Stimulus controllers. To plug into them in your app:
+
+```bash
+rails generate pu:core:assets
+```
+
+This installs the npm packages, creates a `tailwind.config.js` that extends Plutonium's defaults via `plutoniumTailwindConfig.merge`, imports Plutonium's CSS, and registers its Stimulus controllers. After that, you can:
+
+- Extend the palette under `theme.extend.colors` (always inside `plutoniumTailwindConfig.merge` — a plain spread drops Plutonium's defaults).
+- Use `.pu-btn`, `.pu-card`, `.pu-input`, `.pu-table`, etc. instead of hand-rolling Tailwind chains.
+- Reference design tokens directly: `bg-[var(--pu-surface)]`, `text-[var(--pu-text-muted)]`, `border-[var(--pu-border)]`. These auto-switch with dark mode.
+- Register your own Stimulus controllers alongside Plutonium's — `registerControllers(application)` is mandatory or the entire interactive layer is dead.
+
+→ See [Reference › UI › Assets](/reference/ui/assets) for the full toolchain, the `.pu-*` class catalog, and design-token reference.
+
+## ERB views (escape hatch)
+
+When the Phlex page class is the wrong tool — you want to keep an existing ERB layout, you're integrating with a designer's HTML, or you just want to surround the generated page with custom markup — drop an ERB view at the controller path:
+
+```
+app/views/posts/show.html.erb
+packages/admin_portal/app/views/admin_portal/posts/show.html.erb
+```
+
+The default page renders the Phlex page class in one line:
+
+```erb
+<%= render current_definition.show_page_class.new %>
+```
+
+Keep that line and wrap it to add chrome without giving up the generated page:
+
+```erb
+<div class="announcement-banner">Special announcement</div>
+<%= render current_definition.show_page_class.new %>
+<%= render partial: "related" %>
+```
+
+Or replace the line entirely for full control. ERB views always win over the Phlex page class when both exist for the same action — reach for this only when Phlex hooks + overrides genuinely can't do the job.
+
+## When to reach for what
+
+| You want to… | Use |
+|---|---|
+| Add a banner above the show page | Page hook (`render_before_content`) |
+| Group form fields into sections | Custom `form_template` |
+| Render the index as cards | Custom `Table#view_template` |
+| Reuse a UI block across pages | Custom Phlex component |
+| Recolor without changing structure | Phlexi `Theme` class |
+| Swap the topbar or sidebar | `pu:eject:shell` or custom layout class |
+| Change brand color or radius | Design tokens — see [Theming](/guides/theming) |
+| Add a custom JS interaction | Stimulus controller registered alongside Plutonium's |
+
+## Gotchas
+
+- **Don't override `view_template` in pages** when a render hook fits — you lose breadcrumbs, header, and DynaFrame (turbo-frame) behavior.
+- **`render_actions` is mandatory** when you write a custom `form_template` — otherwise the form has no submit button.
+- **Always `registerControllers(application)`** in `app/javascript/controllers/index.js`. Without it, every Plutonium-shipped Stimulus controller is dead (color mode, slim-select, flatpickr, easymde, form pre-submit).
+- **Use `plutoniumTailwindConfig.merge`** when extending the Tailwind theme. A plain object spread drops Plutonium's defaults.
+- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+
+## Related
+
+- [Theming](/guides/theming) — design tokens, brand colors.
+- [Reference › UI](/reference/ui/) — the full surface area for every override above.

data/docs/guides/index.md

@@ -1,32 +1,49 @@
-# Guides
-
-Task-oriented walkthroughs. Each guide shows you how to accomplish a specific task, step-by-step, with links to [Reference](/reference/) for the concepts.
-
-## I want to…
-
-| Task | Guide |
-|---|---|
-| Add a new model to my app | [Adding resources](./adding-resources) |
-| Organize code across multiple teams | [Creating packages](./creating-packages) |
-| Protect pages with login | [Authentication](./authentication) |
-| Control who can edit what | [Authorization](./authorization) |
-| Add a "Publish" button | [Custom actions](./custom-actions) |
-| Show comments under posts | [Nested resources](./nested-resources) |
-| Separate data by company | [Multi-tenancy](./multi-tenancy) |
-| Add search to a list | [Search and filtering](./search-filtering) |
-| Invite users to an organization | [User invites](./user-invites) |
-| Add a profile / account-settings page | [User profile](./user-profile) |
-| Customize colors, branding, styles | [Theming](./theming) |
-| Write tests for resources | [Testing](./testing) |
-| Fix a confusing error | [Troubleshooting](./troubleshooting) |
-
-## Guides vs Reference
-
-- **Guides** = "how do I do X?" — step-by-step, opinionated, narrative.
-- **[Reference](/reference/)** = "what does X do?" — exhaustive option lookup, concept catalog.
-
-When a guide says "see Reference › Foo", it's pointing to the catalog page for the full option/method/DSL list.
-
-## New to Plutonium?
-
-Start with the [Tutorial](/getting-started/tutorial/) — an 8-step walkthrough that builds a blog with auth, authorization, custom actions, nested resources, and a customer portal.
+---
+layout: page
+sidebar: false
+aside: false
+---
+
+<SectionLanding
+  eyebrow="Guides"
+  title="How to do the things Plutonium apps do."
+  lede="Task-oriented walkthroughs for the parts of the framework you reach for most."
+  mode="categorized"
+  :rail="[
+    { group: 'Setup & Resources', items: [
+      { name: 'Adding resources', link: '/plutonium-core/guides/adding-resources' },
+      { name: 'Creating packages', link: '/plutonium-core/guides/creating-packages' },
+    ]},
+    { group: 'Auth', items: [
+      { name: 'Authentication', link: '/plutonium-core/guides/authentication' },
+      { name: 'Authorization', link: '/plutonium-core/guides/authorization' },
+      { name: 'User profile', link: '/plutonium-core/guides/user-profile' },
+      { name: 'User invites', link: '/plutonium-core/guides/user-invites' },
+    ]},
+    { group: 'Features', items: [
+      { name: 'Custom actions', link: '/plutonium-core/guides/custom-actions' },
+      { name: 'Nested resources', link: '/plutonium-core/guides/nested-resources' },
+      { name: 'Multi-tenancy', link: '/plutonium-core/guides/multi-tenancy' },
+      { name: 'Search & filtering', link: '/plutonium-core/guides/search-filtering' },
+    ]},
+    { group: 'Customization', items: [
+      { name: 'Customizing the UI', desc: 'A map of the override surface — pages, forms, displays, tables, components, layouts.', link: '/plutonium-core/guides/customizing-ui' },
+      { name: 'Theming', desc: 'Design tokens and brand colors.', link: '/plutonium-core/guides/theming' },
+    ]},
+    { group: 'Quality', items: [
+      { name: 'Testing', link: '/plutonium-core/guides/testing' },
+      { name: 'Troubleshooting', link: '/plutonium-core/guides/troubleshooting' },
+    ]},
+  ]"
+  :sidebar="[
+    { heading: 'New to Plutonium?', items: [
+      { label: 'Start with the tutorial', href: '/plutonium-core/getting-started/tutorial/' },
+    ]},
+    { heading: 'Looking for APIs?', items: [
+      { label: 'Browse the reference', href: '/plutonium-core/reference/' },
+    ]},
+    { heading: 'Need help?', items: [
+      { label: 'GitHub Discussions', href: 'https://github.com/radioactive-labs/plutonium-core/discussions' },
+    ]},
+  ]"
+/>

data/docs/guides/multi-tenancy.md

@@ -8,10 +8,18 @@ Each tenant sees only their own records. Queries are filtered, forms inject the
 
 ## 🚨 Critical
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!` at runtime. Always call `default_relation_scope(relation)` explicitly — not `super`.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins triggers `verify_default_relation_scope_applied!` at runtime. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super` to a parent policy (e.g., a package base) that calls it.
 - **Always declare an association path from the model to the entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, fix the **model**, not the policy.
 - **Compound uniqueness scoped to the tenant FK.** `validates :code, uniqueness: {scope: :organization_id}` — without this, uniqueness leaks across tenants.
 
+After login, users with memberships in multiple entities land on a workspace selector:
+
+![Workspace selector after login](/images/guides/multi-tenancy-welcome.png)
+
+Picking one lands them on the entity-scoped dashboard — note the entity slug in the URL:
+
+![Tenant-scoped dashboard](/images/guides/multi-tenancy-dashboard.png)
+
 ## Quickest path: `pu:saas:setup`
 
 ```bash
@@ -179,7 +187,7 @@ relation_scope do |relation|
 end
 ```
 
-🚨 `default_relation_scope(relation)` must be called explicitly — not `super`. Bypassing it raises at runtime.
+🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise the runtime verification raises. Calling it explicitly here is safest; `super` works only if the parent policy also calls it.
 
 ## Cross-tenant operations — super-admin portal
 

data/docs/guides/nested-resources.md

@@ -43,6 +43,8 @@ end
 
 This adds a "Properties" tab on the Company show page that loads the nested collection. See [Reference › Behavior › Policies › Association permissions](/reference/behavior/policies#association-permissions).
 
+![Parent show page with nested-association tab](/images/guides/nested-resources-tab.png)
+
 ### 4. Visit the URL
 
 ```
@@ -180,6 +182,73 @@ Plutonium supports **one level of nesting only**:
 
 For deeper hierarchies, use top-level routes plus association tabs on the show page (`permitted_associations`).
 
+## Nested inputs (sub-records inside a parent form)
+
+A different feature with a confusingly similar name. **Nested *resources*** (above) give you separate URLs for the child collection. **Nested *inputs*** let you edit child records inline inside the parent's form — a single submit creates/updates/deletes them in one go, backed by Rails' `accepts_nested_attributes_for`.
+
+Use nested inputs when the children are conceptually part of the parent (line items on an order, variants on a product, contact methods on a person) and don't deserve their own page.
+
+### Setup
+
+```ruby
+# Model
+class Post < ResourceRecord
+  has_many :comments
+  accepts_nested_attributes_for :comments, allow_destroy: true, reject_if: :all_blank
+end
+
+# Definition
+class PostDefinition < ResourceDefinition
+  nested_input :comments do |definition|
+    definition.input :body, as: :text
+  end
+end
+
+# Policy — list the association name (NOT `comments_attributes`)
+class PostPolicy < ResourcePolicy
+  def permitted_attributes_for_create
+    [:title, :body, :comments]
+  end
+end
+```
+
+::: warning Permit the association, not the strong-params shape
+List `:comments` in `permitted_attributes_for_*` — Plutonium translates it to `comments_attributes: [...]` for you. If you write the raw hash, the form renders the field name as a literal label instead of the nested editor.
+:::
+
+### Result
+
+![Inline nested-input editor with Add Comment button](/images/guides/nested-inputs.png)
+
+Each existing child renders as its own sub-form. A `Delete` checkbox appears when `allow_destroy: true`; the `+ Add` button appends a blank row.
+
+### Sourcing fields from an existing definition
+
+If the child already has its own `Definition` and you want to reuse its inputs:
+
+```ruby
+nested_input :comments, using: CommentDefinition, fields: %i[author body]
+```
+
+### Limits
+
+```ruby
+nested_input :variants, limit: 5      # cap the number of children
+nested_input :profile,  macro: :has_one   # singular sub-form, no Add button
+```
+
+### Nested *inputs* vs nested *resources*
+
+| | Nested inputs (`nested_input :comments`) | Nested resources (this guide's main topic) |
+|---|---|---|
+| URL | None — inline in parent form | `/posts/:id/nested_comments` |
+| Submit | One — saves parent + children together | Independent CRUD per child |
+| Discoverability | Always visible in parent form | Tab on parent show page (with `permitted_associations`) |
+| Best for | Tightly-owned children (line items, variants) | Children users browse on their own (orders, posts) |
+| Backing | `accepts_nested_attributes_for` | Plutonium's nested controller routing |
+
+You can use both on the same association — they're not mutually exclusive.
+
 ## Inline `+` add on the parent form
 
 When a form has an association select (e.g. picking the company on a Property form), the inline `+` button next to the select opens the parent's `:new` action. If the parent form is already in a modal, the `+` opens a **stacked secondary modal** so the in-progress form isn't lost. See [Reference › UI › Forms › Association inputs](/reference/ui/forms#association-inputs).

data/docs/guides/search-filtering.md

@@ -11,6 +11,8 @@ Users can:
 - Click scope buttons (top-of-list quick filters) for common queries like "Published" or "My posts".
 - Click column headers to sort.
 
+![Search box, scope tabs, filter button, sortable columns](/images/guides/search-filtering-index.png)
+
 ## The four pieces
 
 | DSL | Purpose |
@@ -141,6 +143,10 @@ end
 filter :price, with: PriceRangeFilter
 ```
 
+Clicking **Filter** opens a slideover with one input per declared filter:
+
+![Filter slideover](/images/guides/search-filtering-panel.png)
+
 ## Scopes (quick-filter buttons)
 
 ```ruby

data/docs/guides/testing.md

@@ -101,7 +101,11 @@ current_account                       # uses portal from DSL
 with_portal(:org) { ... }            # scoped portal switch
 ```
 
-### Non-Rodauth auth
+::: info Default Rodauth login expects password `"password123"`
+`login_as` posts to `/<account_table>/login` with `password: "password123"` by default. Either create test accounts with that password (e.g. in fixtures or factories), or override the auth flow via `sign_in_for_tests` below.
+:::
+
+### Non-Rodauth auth (or skipping Rodauth in tests)
 
 Define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use):
 

data/docs/guides/theming.md

@@ -48,6 +48,19 @@ end
 
 Logo / favicon resolved from `app/assets/images/`.
 
+Default palette is turquoise on the left; swapping `primary` to indigo gives every `.pu-btn-primary`, focus ring, and selected-row highlight the new colour without touching any markup:
+
+<div style="display:grid;grid-template-columns:1fr 1fr;gap:12px;">
+  <figure>
+    <img src="/images/guides/theming-before.png" alt="Default turquoise palette" />
+    <figcaption><em>Default (turquoise)</em></figcaption>
+  </figure>
+  <figure>
+    <img src="/images/guides/theming-after.png" alt="Indigo palette via tailwind override" />
+    <figcaption><em>After indigo override</em></figcaption>
+  </figure>
+</div>
+
 ## Step 3: Customize colors via Tailwind
 
 ```javascript

data/docs/guides/user-invites.md

@@ -30,8 +30,7 @@ Or with custom models:
 rails g pu:invites:install \
   --entity-model=Organization \
   --user-model=Customer \
-  --membership-model=OrganizationCustomer \
-  --roles=member,manager,admin
+  --membership-model=OrganizationCustomer
 ```
 
 | Option | Default | Description |
@@ -39,11 +38,14 @@ rails g pu:invites:install \
 | `--entity-model=NAME` | `Entity` | Entity model |
 | `--user-model=NAME` | `User` | User model |
 | `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name |
-| `--membership-model=NAME` | `EntityUser` | Membership join model |
-| `--roles` | `member,admin` | Comma-separated roles |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist) |
 | `--rodauth=NAME` | `user` | Rodauth configuration for signup |
 | `--enforce-domain` | `false` | Require email domain to match entity |
 
+::: info Roles come from the membership model
+`pu:invites:install` reads the role list from the membership model's `enum :role` — it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
+:::
+
 ### 2. Migrate
 
 ```bash
@@ -94,6 +96,10 @@ Token-based URL: `https://app.example.com/invitations/abc123...`
 
 ### 3. User accepts
 
+Clicking the link lands on the invitation page:
+
+![Invitation landing page](/images/guides/user-invites-landing.png)
+
 **Existing user:** clicks link → logs in (or already logged in) → email validated → membership created.
 
 **New user:** clicks link → "Create Account" → signs up with the invited email → membership created.

data/docs/guides/user-profile.md

@@ -12,6 +12,14 @@ A `/profile` URL that shows the user's personal fields plus a "Security" section
 - **Profile needs `pu:profile:conn` to be visible** — without it, no `/profile` route, no `profile_url` helper.
 - **Every user needs a profile row.** Add an `after_create :create_profile!` callback to the user model. Without it, `current_user.profile` is nil.
 
+The show page renders the user's fields, then the **Security Settings** block with Rodauth-backed actions:
+
+![User profile show page with SecuritySection](/images/guides/user-profile-show.png)
+
+Editing produces a regular Plutonium form — same form generator the rest of your resources use:
+
+![User profile edit form](/images/guides/user-profile-edit.png)
+
 ## Quick path
 
 ```bash