plutonium 0.49.0 → 0.50.0

data/app/views/plutonium/_flash.html.erb

@@ -1 +1 @@
-<%= render "flash_toasts" %>
+<%= render "plutonium/flash_toasts" %>

data/app/views/plutonium/_resource_header.html.erb

@@ -1,9 +1,9 @@
-<%= render Plutonium::UI::Layout::Header.new do |header| %>
-  <% header.with_brand_logo do %>
-    <%= resource_logo_tag(classname: "h-10 rounded-md") %>
+<%= render Plutonium::UI::Layout::Topbar.new do |bar| %>
+  <% bar.with_action do %>
+    <%= render Plutonium::UI::ColorModeSelector.new %>
   <% end %>
 
-  <% header.with_action do %>
+  <% bar.with_action do %>
     <%=
       render Plutonium::UI::NavUser.new(
         name: nil,

data/app/views/plutonium/_resource_sidebar.html.erb

@@ -1,10 +1,6 @@
-<%= render Plutonium::UI::Layout::Sidebar.new do %>
-  <%=
-    render Plutonium::UI::SidebarMenu.new(
-      Phlexi::Menu::Builder.new do |m|
-        m.item "Dashboard",
-          url: root_path,
-          icon: Phlex::TablerIcons::Home
+<%= render Plutonium::UI::Layout::IconRail.new(
+      menu: Phlexi::Menu::Builder.new do |m|
+        m.item "Dashboard", url: root_path, icon: Phlex::TablerIcons::Home
 
         m.item "Resources", icon: Phlex::TablerIcons::GridDots do |n|
           registered_resources.each do |resource|
@@ -12,6 +8,10 @@
           end
         end
       end
-    )
-  %>
+    ) do |rail| %>
+  <% if respond_to?(:resource_logo_tag) %>
+    <% rail.with_brand do %>
+      <%= resource_logo_tag(classname: "h-8 w-8 rounded-md") %>
+    <% end %>
+  <% end %>
 <% end %>

data/app/views/resource/_resource_grid.html.erb

@@ -0,0 +1 @@
+<%= render build_grid_collection %>

data/config/brakeman.ignore

@@ -120,13 +120,13 @@
     {
       "warning_type": "Dangerous Eval",
       "warning_code": 13,
-      "fingerprint": "a14cf69ee743ba0aa405725f018c186d6fdfa3f3f57a381613de1b2048621170",
+      "fingerprint": "e5f68f8342a094ffd2124c1650428135e0549da39950158725414bfca0bb8f1e",
       "check_name": "Evaluation",
       "message": "Dynamic string evaluated as code",
       "file": "lib/plutonium/auth/rodauth.rb",
       "line": 6,
       "link": "https://brakemanscanner.org/docs/warning_types/dangerous_eval/",
-      "code": "Module.new.module_eval(\"          extend ActiveSupport::Concern\\n\\n          included do\\n            helper_method :current_user\\n            helper_method :logout_url\\n          end\\n\\n          private\\n\\n          def rodauth(name = :#{name})\\n            instance = super(name)\\n            instance.url_options = default_url_options.presence\\n            instance\\n          end\\n\\n          def current_user\\n            rodauth.rails_account\\n          end\\n\\n          def logout_url\\n            rodauth.logout_path\\n          end\\n\\n          define_singleton_method(:to_s) { \\\"Plutonium::Auth::Rodauth(:#{name})\\\" }\\n          define_singleton_method(:inspect) { \\\"Plutonium::Auth::Rodauth(:#{name})\\\" }\\n\", \"lib/plutonium/auth/rodauth.rb\", 7)",
+      "code": "Module.new.module_eval(\"...\", \"lib/plutonium/auth/rodauth.rb\", 7)",
       "render_path": null,
       "location": {
         "type": "method",
@@ -233,6 +233,29 @@
         89
       ],
       "note": "False positive: 'key' is the filter attribute name from definition code, not user input. User input (query) is parameterized."
+    },
+    {
+      "warning_type": "Redirect",
+      "warning_code": 18,
+      "fingerprint": "ce92f474802c81eb79c01577415a82ef604bddcb8072b68c5508260b2b0b7469",
+      "check_name": "Redirect",
+      "message": "Possible unprotected redirect",
+      "file": "lib/plutonium/invites/controller.rb",
+      "line": 76,
+      "link": "https://brakemanscanner.org/docs/warning_types/redirect/",
+      "code": "redirect_to(invitation_path_for(params[:token]), :alert => \"Please sign in to accept this invitation\")",
+      "render_path": null,
+      "location": {
+        "type": "method",
+        "class": "Plutonium::Invites::Controller",
+        "method": "accept"
+      },
+      "user_input": "params[:token]",
+      "confidence": "Weak",
+      "cwe_id": [
+        601
+      ],
+      "note": "False positive: params[:token] is interpolated into a route helper as a single path segment, not used as the redirect URL itself. The destination is a server-controlled named route."
     }
   ],
   "brakeman_version": "7.1.1"

data/docs/guides/user-invites.md

@@ -48,6 +48,7 @@ rails g pu:invites:install \
 |--------|---------|-------------|
 | `--entity-model` | Entity | Entity model for scoping invites |
 | `--user-model` | User | User account model |
+| `--invite-model` | `<EntityModel><UserModel>Invite` | Invite class name. Omit for single-flow apps; set per-invocation to run the generator more than once for distinct flows. |
 | `--membership-model` | EntityUser | Join model for memberships |
 | `--roles` | member,admin | Available invitation roles |
 | `--rodauth` | user | Rodauth configuration name |
@@ -489,6 +490,69 @@ invite.expired?
 invite.cancelled?
 ```
 
+## Multiple invite flows in one app
+
+Some apps invite users to several distinct kinds of entity — for example, customers joining organizations and funders joining projects. Run `pu:invites:install` once per flow; each invocation produces independent migrations, models, policies, definitions, mailers, controllers, view templates, and route helpers.
+
+### Default-derivation rule
+
+When you omit `--invite-model`, the generator derives the class name as `<EntityModel><UserModel>Invite`. With the defaults (`--entity-model=Organization --user-model=User`) the generated class is `Invites::OrganizationUserInvite` — there is no literal `UserInvite` default. Single-flow apps never need to pass `--invite-model`.
+
+Multi-flow apps either:
+
+- Run the generator more than once with the **same** entity/user but different `--invite-model` values (rare), or
+- Run with **different** `--entity-model` / `--user-model` pairs (common). Different derivations make `--invite-model` unnecessary; pass it only when you want a custom class name.
+
+```bash
+rails g pu:invites:install \
+  --entity-model=FunderOrganization \
+  --user-model=SpenderAccount \
+  --invite-model=FunderInvite
+
+rails g pu:invites:install \
+  --entity-model=Project \
+  --user-model=Member \
+  --invite-model=ProjectInvite
+```
+
+After the second invocation you'll have, for example, `Invites::FunderInvite` on table `funder_invites` with controller `Invites::FunderInvitationsController` mounted at `/funder_invitations/:token`, alongside `Invites::ProjectInvite` on `project_invites` mounted at `/project_invitations/:token`. Route helpers are prefixed (`funder_invitation_path`, `project_invitation_path`).
+
+### How the welcome flow finds pending invites
+
+The shared `Invites::WelcomeController` keeps a running list of invite classes. Each install run injects its class into the array, preserving order:
+
+```ruby
+# packages/invites/app/controllers/invites/welcome_controller.rb
+def invite_classes
+  [::Invites::FunderInvite, ::Invites::ProjectInvite]
+end
+```
+
+After login, `Plutonium::Invites::PendingInviteCheck#pending_invite` iterates `invite_classes` and returns the first valid pending invite for the cookie-stored token (first-match wins). Plug a third-party invite class in by overriding `invite_classes` directly:
+
+```ruby
+class WelcomeController < ApplicationController
+  include Plutonium::Invites::PendingInviteCheck
+
+  def invite_classes
+    [::Invites::FunderInvite, ::Invites::ProjectInvite, ::Foreign::ApiInvite]
+  end
+end
+```
+
+### Per-flow controller overrides
+
+The install generator emits an `invitation_path_for` override on each invitations controller so post-login redirects target the correct prefixed route:
+
+```ruby
+# packages/invites/app/controllers/invites/funder_invitations_controller.rb
+def invitation_path_for(token)
+  funder_invitation_path(token: token)
+end
+```
+
+You won't normally edit this — but it's worth knowing the hook exists, because that's how multi-flow controllers stay independent from the shared `Plutonium::Invites::Controller` concern.
+
 ## Next Steps
 
 - [Authentication](/guides/authentication) - Set up Rodauth

data/docs/reference/definition/actions.md

@@ -98,7 +98,20 @@ action :name,
   confirmation: "Are you sure?",   # Confirmation dialog
   turbo_frame: "_top",             # Turbo frame target
   return_to: "/custom/path",       # Override return URL
-  route_options: {action: :foo}    # Route configuration
+  route_options: {action: :foo},   # Route configuration
+
+  # Dialog chrome (for interactive actions with a form)
+  modal: :slideover                # :centered (default) or :slideover
+```
+
+### `Action#with(...)`
+
+Action records are frozen value objects. To derive a variant — typically inside `customize_actions` — call `existing.with(...)` for a new copy with overrides applied:
+
+```ruby
+def customize_actions
+  defined_actions[:edit] = defined_actions[:edit].with(turbo_frame: "_top")
+end
 ```
 
 ## Route Options

data/docs/reference/definition/index.md

@@ -164,11 +164,69 @@ class PostDefinition < Plutonium::Resource::Definition
   # true = always show
   # false = always hide
   submit_and_continue false
+
+  # How `:new` / `:edit` render. Default is :slideover.
+  #   :slideover — slide-in panel from the right (default)
+  #   :centered  — centered modal dialog
+  #   false      — full standalone pages (no modal)
+  modal :centered
 end
 ```
 
 Singular resources (e.g., `resource :profile` routes or `has_one` nested) auto-hide the secondary submit button since creating "another" doesn't make sense.
 
+The `modal` setting only retargets the framework-provided `:new` / `:edit` actions. Custom interactive actions render in their own dialog whose chrome is set on the action via the per-action `modal:` option (`:centered` default, or `:slideover`) — see [Actions](./actions#action-options).
+
+## Show Page Metadata Panel
+
+The `metadata` DSL declares a list of fields that render in a right-side aside on the show page as label/value rows, leaving the main card focused on the record's substance.
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  metadata :author, :state, :created_at, :updated_at
+end
+```
+
+- **Opt-in.** Without a `metadata` call, the show page renders full-width with no aside.
+- **Policy-aware.** Fields are intersected with the policy's permitted attributes. The panel auto-hides when nothing is permitted.
+- **Deduplicated.** Fields listed in `metadata` are removed from the main card so values aren't shown twice.
+- **Responsive.** Side-by-side at `lg+`, stacked single-column below.
+
+Field formatting (label, `as:`, blocks) is shared with the main card — declare once via `field` / `display` and the metadata panel inherits it.
+
+## Index Views (Table & Grid)
+
+Resources can opt into a card-based **Grid** view alongside the default **Table** view. The user can switch between them via the toolbar; the choice is persisted per-resource via cookie.
+
+```ruby
+class UserDefinition < Plutonium::Resource::Definition
+  views :table, :grid       # enable both
+  default_view :grid        # initial view if no cookie
+
+  grid_fields(
+    image:     :avatar,     # ActiveStorage attachment, Shrine, or URL string
+    header:    :name,       # falls back to record.to_label
+    subheader: :email,
+    body:      :bio,
+    meta:      [:role, :status],   # rendered as small pills
+    footer:    :last_seen_at       # falls back to :created_at
+  )
+
+  grid_layout :media        # :compact (default) or :media
+  grid_columns 3            # pin to 3 cols on lg+; default is 1/2/3/4 responsive
+end
+```
+
+| Method | Purpose |
+|--------|---------|
+| `views :table, :grid` | Which views are available. Default `[:table]`. |
+| `default_view :grid` | Initial view when no cookie. Falls back to first declared view. |
+| `grid_fields(...)` | Maps card slots to fields. **Implicitly enables `:grid`** if not already declared. |
+| `grid_layout :media` | `:compact` (image left of content) or `:media` (full-width image on top). |
+| `grid_columns 3` | Override responsive column count on `lg+`. Default is 1 / 2 / 3 / 4 at sm/md/lg/xl. |
+
+Grid slots — `:image`, `:header`, `:subheader`, `:body`, `:meta`, `:footer` — are all optional. `:meta` accepts an array; the rest are single fields. Slots that point at fields not permitted by the user's policy collapse silently.
+
 ## Custom Page Classes
 
 Override default page components:

data/docs/reference/views/index.md

@@ -338,6 +338,49 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+## Page Chrome (Shell)
+
+`Plutonium.configuration.shell` controls the layout shipped above the resource pages. The default is **`:modern`** (topbar + icon rail) — leave it alone unless you're upgrading from a pre-`:modern` version and want to keep the legacy header + sidebar:
+
+```ruby
+Plutonium.configure do |config|
+  config.shell = :classic
+end
+```
+
+To customize the shipped chrome per-portal, eject the templates:
+
+```bash
+rails generate pu:eject:shell --dest=admin_portal
+```
+
+This copies `_resource_header.html.erb` and `_resource_sidebar.html.erb` into the portal's `app/views/plutonium/`.
+
+## Modal & Slideover Forms
+
+Framework-provided `:new` / `:edit` actions render inline inside a modal. Choose the chrome per-resource via [`modal`](/reference/definition/#form-configuration) on the definition (`:slideover` default, `:centered`, or `false`).
+
+Custom interactive actions render in their own dialog. Each action carries its own [`modal:` option](/reference/definition/actions#action-options) (`:centered` default, or `:slideover`).
+
+### Detecting Render Context
+
+In custom Page / Form components:
+
+| Helper | True when |
+|--------|-----------|
+| `in_frame?` | Request is targeting a turbo-frame |
+| `in_modal?` | Request is rendering inside a modal/slideover |
+
+Use them to pin action strips, omit nav chrome, or swap layouts.
+
+## Tabs & URL Hash
+
+Show pages with associations render the **Details** tab first followed by one tab per permitted association. The active tab is reflected in the URL hash (`#products`, `#refund-requests`) so the page deep-links and the active state survives reloads / back navigation. Tab rows scroll horizontally on narrow viewports rather than wrapping.
+
+## Show Page Metadata Panel
+
+The [`metadata` DSL](/reference/definition/#show-page-metadata-panel) on the definition opts a resource into a right-side aside that renders selected fields as label/value rows alongside the main details. The aside collapses to a single-column stack below the `lg` breakpoint and disappears entirely when no listed field is permitted by policy.
+
 ## Layout Customization
 
 ### Custom Layout Class