plutonium 0.64.0 → 0.66.0

data/docs/guides/custom-actions.md

@@ -1,6 +1,6 @@
 # Custom Actions
 
-Add buttons beyond CRUD — Publish, Archive, Import, Send invitation, Bulk-update, etc.
+Add buttons beyond CRUD: Publish, Archive, Import, Send invitation, Bulk-update, etc.
 
 ## Goal
 
@@ -10,17 +10,17 @@ A button appears in the right place (show page / table row / index header / bulk
 
 | Flavor | Use for |
 |---|---|
-| **Simple action** — navigate to a URL | Linking to external docs, jumping to a custom page that does its own thing |
-| **Interactive action** — run an interaction class | Anything that *does* something (the common case) |
+| **Simple action**: navigate to a URL | Linking to external docs, jumping to a custom page that does its own thing |
+| **Interactive action**: run an interaction class | Anything that *does* something (the common case) |
 
-Prefer interactive actions. They handle authorization, form rendering, modal chrome, success/failure messaging, and automatic redirects — all for free.
+Prefer interactive actions. They handle authorization, form rendering, modal chrome, success/failure messaging, and automatic redirects, all for free.
 
-## Quick recipe — interactive action
+## Quick recipe: interactive action
 
 ### 1. Write the interaction
 
 ```ruby
-# app/models/post.rb — what publishing actually means
+# app/models/post.rb: what publishing actually means
 class Post < ApplicationRecord
   def publish!(on: Time.current)
     update!(published: true, published_at: on)
@@ -29,7 +29,7 @@ end
 ```
 
 ```ruby
-# app/interactions/publish_post_interaction.rb — the button in front of it
+# app/interactions/publish_post_interaction.rb: the button in front of it
 class PublishPostInteraction < ResourceInteraction
   presents label: "Publish",
            icon:  Phlex::TablerIcons::Send,
@@ -51,7 +51,7 @@ Plutonium doesn't rescue it automatically. Always rescue when using `create!` /
 :::
 
 ::: tip Why `publish!` is on the model
-An interaction can only be built with a `view_context` — it's a presentation object. A two-line `update!` inline in `execute` is fine while the button is the only caller; the moment a scheduled-publishing job wants the same behaviour it has to duplicate it or fake a view context. Full rule: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+An interaction can only be built with a `view_context`; it's a presentation object. A two-line `update!` inline in `execute` is fine while the button is the only caller; the moment a scheduled-publishing job wants the same behaviour it has to duplicate it or fake a view context. Full rule: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 :::
 
 ### 2. Register it in the definition
@@ -62,7 +62,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-Action visibility (record / bulk / resource) is **inferred** from the interaction's attributes — no need to declare `record_action: true`. See [Inferred visibility](#inferred-visibility) below.
+Action visibility (record / bulk / resource) is **inferred** from the interaction's attributes; no need to declare `record_action: true`. See [Inferred visibility](#inferred-visibility) below.
 
 ### 3. Add a policy method
 
@@ -88,7 +88,7 @@ For `interaction:`-based actions, visibility flags are inferred from the interac
 | `attribute :resources` (plural) | `bulk_action: true` → bulk toolbar |
 | neither | `resource_action: true` → index page header |
 
-User-supplied flags can only **opt OUT** of inferred ones. Don't try to "broaden" — the interaction's attribute shape is semantic:
+User-supplied flags can only **opt OUT** of inferred ones. Don't try to "broaden"; the interaction's attribute shape is semantic:
 
 ```ruby
 # Hide from per-row menu, keep on show page
@@ -127,7 +127,7 @@ class Company::InviteUserInteraction < ResourceInteraction
 end
 ```
 
-`Company#invite!` creates the row *and* sends the mail. Both are things a seat-provisioning job needs to do without a browser anywhere in sight — see the [full worked example](/reference/behavior/interactions#complete-example).
+`Company#invite!` creates the row *and* sends the mail. Both are things a seat-provisioning job needs to do without a browser anywhere in sight, see the [full worked example](/reference/behavior/interactions#complete-example).
 
 ## Bulk actions
 
@@ -146,7 +146,7 @@ class BulkArchiveInteraction < ResourceInteraction
 end
 ```
 
-Policy — checked **per record** (fails the whole request if any record is unauthorized):
+Policy: checked **per record** (fails the whole request if any record is unauthorized):
 
 ```ruby
 def bulk_archive?
@@ -181,13 +181,13 @@ class BulkArchiveInteraction < ResourceInteraction
 end
 ```
 
-Nothing else about the action changes — the definition, the policy method and the form are the same. Only the work moves.
+Nothing else about the action changes: the definition, the policy method and the form are the same. Only the work moves.
 
 Three things worth knowing:
 
 - **The block is the run's class body, not `execute`.** The work runs later, in a job with no controller, so it cannot close over anything in the interaction. Its inputs arrive through `options`.
 - **The user is sent back where they were**, and the index they land on shows a banner for the run with a link to its progress page.
-- **Permissions are re-checked per record, at perform time** — not replayed from dispatch. A permission revoked while the run is working stops applying to the rest of it.
+- **Permissions are re-checked per record, at perform time**: not replayed from dispatch. A permission revoked while the run is working stops applying to the rest of it.
 
 Full detail, including file attributes, failure policies and resuming a crashed run: [Async Interactions](/reference/behavior/async-interactions).
 
@@ -212,8 +212,8 @@ end
 
 ## Immediate vs form
 
-- **Immediate** — interaction has only `:resource` / `:resources` (no extra inputs). Browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom message"` or `confirmation: false` on the action.
-- **Form** — interaction has additional `attribute` / `input`. Renders modal form first; no auto-confirmation (the form is the confirmation).
+- **Immediate**: interaction has only `:resource` / `:resources` (no extra inputs). Browser confirmation (`"#{label}?"`, e.g. `"Archive?"`), then runs. Override with `confirmation: "Custom message"` or `confirmation: false` on the action.
+- **Form**: interaction has additional `attribute` / `input`. Renders modal form first; no auto-confirmation (the form is the confirmation).
 
 ## Action options
 
@@ -231,10 +231,10 @@ action :name,
 
   # Behavior
   confirmation: "Are you sure?",
-  modal: :slideover,                     # :slideover / :centered — overrides definition's modal mode
-  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
+  modal: :slideover,                     # :slideover / :centered, overrides definition's modal mode
+  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full, overrides definition's modal size
 
-  # HTML attributes — author wins over the framework's on every key
+  # HTML attributes: author wins over the framework's on every key
   link:   {target: "_blank", rel: "noopener"},  # every <a> rendering (toolbar GET link, dropdown items, bulk links, card show link)
   button: {data: {analytics: "archive"}}        # the button_to <form> wrapper (non-GET toolbar rendering)
 ```
@@ -283,7 +283,7 @@ Every resource gets `:archive` automatically.
 
 ## Where the logic goes
 
-Interactions are presentation objects — they need a `view_context` to exist at all. So the reflex to reach for when an operation grows:
+Interactions are presentation objects: they need a `view_context` to exist at all. So the reflex to reach for when an operation grows:
 
 ```ruby
 # 🚫 Three interactions, three view contexts, none of it callable from a job
@@ -300,22 +300,22 @@ def execute
 end
 ```
 
-Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a rake task also does — and neither has a view context to hand.
+Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a rake task also does, and neither has a view context to hand.
 
-The rule isn't "never put logic in an interaction". A single-caller operation can stay inline in `execute`; don't pre-extract. **The second caller is the trigger** — and the destination is the model, Rails-style, not a new service layer. Chaining three interactions is usually the tell that you already crossed it. Full explanation: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+The rule isn't "never put logic in an interaction". A single-caller operation can stay inline in `execute`; don't pre-extract. **The second caller is the trigger**, and the destination is the model, Rails-style, not a new service layer. Chaining three interactions is usually the tell that you already crossed it. Full explanation: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ## Common issues
 
-- **Action button missing** — check the policy method (`def my_action?`). Undefined returns `false`.
-- **`ActiveRecord::RecordInvalid` crashes the action** — not rescued automatically. Wrap with `rescue`, return `failed(e.record.errors)`.
-- **Bulk action fails on some records** — that's by design. Bulk policy is checked per-record; if any fails, the whole request is rejected. Either fix authorization or pre-filter the selection.
-- **Confirmation prompt shows when you don't want one** — pass `confirmation: false` on the action.
-- **The action times out on a large selection** — the work is running inside the request. Move it to a background run with `async`, above.
+- **Action button missing**: check the policy method (`def my_action?`). Undefined returns `false`.
+- **`ActiveRecord::RecordInvalid` crashes the action**: not rescued automatically. Wrap with `rescue`, return `failed(e.record.errors)`.
+- **Bulk action fails on some records**: that's by design. Bulk policy is checked per-record; if any fails, the whole request is rejected. Either fix authorization or pre-filter the selection.
+- **Confirmation prompt shows when you don't want one**: pass `confirmation: false` on the action.
+- **The action times out on a large selection**: the work is running inside the request. Move it to a background run with `async`, above.
 
 ## Related
 
-- [Reference › Resource › Actions](/reference/resource/actions) — full action options and bulk patterns
-- [Reference › Behavior › Interactions](/reference/behavior/interactions) — interaction class anatomy
-- [Reference › Behavior › Async Interactions](/reference/behavior/async-interactions) — `async`, progress pages, resuming a crashed run
-- [Reference › Behavior › Policies](/reference/behavior/policies) — `def <action>?` methods
-- [Authorization](./authorization) — policy patterns
+- [Reference › Resource › Actions](/reference/resource/actions): full action options and bulk patterns
+- [Reference › Behavior › Interactions](/reference/behavior/interactions): interaction class anatomy
+- [Reference › Behavior › Async Interactions](/reference/behavior/async-interactions): `async`, progress pages, resuming a crashed run
+- [Reference › Behavior › Policies](/reference/behavior/policies): `def <action>?` methods
+- [Authorization](./authorization): policy patterns

data/docs/guides/customizing-ui.md

@@ -1,6 +1,6 @@
 # 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.
+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.
 
@@ -17,7 +17,7 @@ class PostDefinition < ResourceDefinition
 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.
+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.
 
@@ -29,15 +29,17 @@ Most page customization is "I want to add something before/after this section."
 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"
+      div(class: "pu-alert pu-alert-info", role: "status") do
+        div(class: "pu-alert-message") { t("blog.posts.show.comment_count", count: object.comments.count) }
       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.
+`pu-alert pu-alert-<success|warning|danger|info>` is the same banner the flash messages use, so it already has its dark-mode colors. The text comes from a locale key; see [i18n](/reference/i18n#your-own-components-and-pages).
+
+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.
 
@@ -56,7 +58,7 @@ class Form < Form
       render_resource_field :published_at
       render_resource_field :category
     end
-    render_actions   # REQUIRED — without this, no submit button
+    render_actions   # REQUIRED: without this, no submit button
   end
 
   private
@@ -126,14 +128,14 @@ class PostCardComponent < Plutonium::UI::Component::Base
     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" }
+      a(href: resource_url_for(@post), class: "pu-btn pu-btn-sm pu-btn-ghost") { t("blog.posts.card.read_more") }
     end
   end
 end
 ```
 
 Use it directly in a page, or wire it as a field in the definition. A component
-with its own constructor takes the block form — you build it, so you decide what
+with its own constructor takes the block form: you build it, so you decide what
 it receives:
 
 ```ruby
@@ -143,13 +145,13 @@ end
 ```
 
 `as: SomeComponent` is for a *field* component, which Plutonium constructs with
-the field builder (`Phlexi::Form::Components::Base` / `Phlexi::Display::Components::Base`) — see the reference below.
+the field builder (`Phlexi::Form::Components::Base` / `Phlexi::Display::Components::Base`); see the reference below.
 
 → 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:
+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
@@ -173,7 +175,7 @@ By default `:new`, `:edit`, and every interactive action render in a slideover p
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover               # default — slide-in from the right
+  modal :slideover               # default: slide-in from the right
   # modal :centered              # centered dialog
   # modal :centered, size: :lg   # centered, wider container
   # modal false                  # full standalone page
@@ -184,7 +186,7 @@ end
 
 ## Layouts and the shell
 
-The layout is the chrome around every resource page — topbar, sidebar, flash region, scripts. Two ways to customize it:
+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
@@ -199,24 +201,24 @@ For programmatic overrides, subclass `Plutonium::UI::Layout::ResourceLayout` and
 
 ## 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:
+Plutonium ships with a Tailwind config, design tokens, and a set of Stimulus controllers. Out of the box the app serves the gem's prebuilt `plutonium.css` and `plutonium.min.js`, so app-side Tailwind classes, a new brand palette, token overrides and your own Stimulus controllers need your own bundles first. Run the generator rather than wiring the pipeline by hand:
 
 ```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:
+This installs the npm packages, creates a `tailwind.config.js` that extends Plutonium's defaults via `plutoniumTailwindConfig.merge`, imports Plutonium's CSS, registers its Stimulus controllers, and points `config.assets.stylesheet` / `config.assets.script` at your `application` bundles. It needs `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` to exist (an app created with `-j esbuild -c tailwind` plus Stimulus). 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.
+- Extend the palette under `theme.extend.colors` (always inside `plutoniumTailwindConfig.merge`: a plain spread drops Plutonium's defaults), then rebuild the CSS.
+- Use `.pu-btn`, `.pu-card`, `.pu-input`, `.pu-table`, `.pu-alert`, `.pu-badge`, 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.
+- Register your own Stimulus controllers alongside Plutonium's. Your `application.js` now replaces the gem's bundle, so `registerControllers(application)` (added by the generator) must stay, 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:
+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
@@ -237,7 +239,7 @@ Keep that line and wrap it to add chrome without giving up the generated page:
 <%= 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.
+Or replace the line entirely for full control. ERB views always win over the Phlex page class when both exist for the same action, so reach for this only when Phlex hooks + overrides genuinely can't do the job.
 
 ## When to reach for what
 
@@ -249,18 +251,19 @@ Or replace the line entirely for full control. ERB views always win over the Phl
 | 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) |
+| Change brand color | Tailwind `primary` palette via `plutoniumTailwindConfig.merge`, then rebuild. See [Theming](/guides/theming) |
+| Change surfaces, borders or radius | Design tokens (mirrored in `.dark`). 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).
+- **Don't override `view_template` in pages** when a render hook fits, or 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.
+- **Once the app serves its own JS bundle, `registerControllers(application)`** must be in `app/javascript/controllers/index.js` (`pu:core:assets` adds it). 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.
+- **Style with `.pu-*` classes first, `var(--pu-*)` tokens second, raw palette pairs last.** The classes and tokens switch with dark mode; a hand-written `gray-X/dark:gray-Y` pair needs its own dark twin and won't follow a rebrand.
 
 ## Related
 
-- [Theming](/guides/theming) — design tokens, brand colors.
-- [Reference › UI](/reference/ui/) — the full surface area for every override above.
+- [Theming](/guides/theming): design tokens, brand colors.
+- [Reference › UI](/reference/ui/): the full surface area for every override above.

data/docs/guides/dashboards.md

@@ -0,0 +1,300 @@
+# Dashboards
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+A dashboard is a page of cards: headline numbers, charts and free-form panels, declared in one Ruby class and mounted with a single routes line. By default every card loads in its own lazy turbo frame, so the page paints immediately and each card's queries run in a separate request as it scrolls into view.
+
+![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/guides/dashboard-overview.png)
+
+## What you get
+
+- A `Plutonium::Dashboard::Base` subclass with a class-level DSL: `metric`, `chart` and `card`.
+- `register_dashboard` in a portal's routes draws the page, the per-card endpoint and a synthesized controller that inherits the portal's auth, tenant scoping and layout.
+- Metric cards format numbers (delimited, currency, percentage, human) and show a change indicator against a previous value.
+- Chart cards render with [Chart.js](https://www.chartjs.org/) through [Chartkick](https://chartkick.com/), using Plutonium's design tokens in light and dark mode. The chart bundle loads on demand, so pages without a chart never download it.
+- Cards sit on a 12-column grid with a sensible default width per kind, and can refresh themselves on an interval, link somewhere, and hide behind a condition.
+- Registered dashboards appear in the portal sidebar.
+
+## Worked example
+
+### 1. Generate the dashboard
+
+```bash
+rails g pu:dashboard Sales --dest=admin_portal
+```
+
+This writes `packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb` and adds `register_dashboard AdminPortal::SalesDashboard, at: "sales"` to the portal's routes. Pass `--at=/` to make the dashboard the portal's root page instead; see [Replacing the portal's default page](#replacing-the-portal-s-default-page).
+
+### 2. Declare the cards
+
+```ruby
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", description: "Orders and revenue at a glance",
+      icon: Phlex::TablerIcons::ChartBar
+
+    refresh 60
+
+    metric(:orders, icon: Phlex::TablerIcons::ShoppingCart,
+      href: -> { resource_url_for(Order, parent: nil) }) do
+      {value: orders.where(created_at: 30.days.ago..).count,
+       previous: orders.where(created_at: 60.days.ago...30.days.ago).count,
+       change_label: "vs. previous 30 days"}
+    end
+
+    metric(:revenue, format: :currency) { orders.sum(:total) }
+
+    metric(:refund_rate, format: :percentage, precision: 1, positive: :down) do
+      {value: refund_rate, previous: previous_refund_rate}
+    end
+
+    metric(:customers, format: :human) { Customer.count }
+
+    chart(:revenue_by_day, type: :area, span: 8) do
+      orders.group_by_day(:created_at, last: 30).sum(:total)
+    end
+
+    chart(:by_channel, type: :donut, span: 4) do
+      orders.group(:channel).count
+    end
+
+    card(:latest, span: :full) do
+      ul(class: "divide-y divide-[var(--pu-border-muted)]") do
+        latest_orders.each do |order|
+          li(class: "py-2 flex justify-between") do
+            span { order.number }
+            span(class: "text-[var(--pu-text-muted)]") { helpers.number_to_currency(order.total) }
+          end
+        end
+      end
+    end
+
+    private
+
+    def orders = authorized_resource_scope(Order)
+    def latest_orders = orders.order(created_at: :desc).limit(5)
+    def refund_rate = 100.0 * orders.refunded.count / [orders.count, 1].max
+    def previous_refund_rate = 1.8
+  end
+end
+```
+
+`group_by_day` comes from the [groupdate](https://github.com/ankane/groupdate) gem, which pairs well with chart cards but is not required.
+
+### 3. Visit it
+
+![The dashboard before its frames have loaded: every card is a skeleton except the inline Conversion metric](/images/guides/dashboard-loading.png)
+
+The page is at `/admin/dashboards/sales`. Each card is a `<turbo-frame src="/admin/dashboards/sales/cards/<key>" loading="lazy">` holding a skeleton until its response lands. Every mount sits under `dashboards/`, so `at: "sales"` never collides with a `Sale` resource registered on the same portal. Pass `prefix: nil` to mount at the bare path (`/admin/sales`), or a string to use another segment (`prefix: "reports"`).
+
+## Replacing the portal's default page
+
+Every generated portal opens on `root to: "dashboard#index"`, a `DashboardController` and a view that lists the registered resources. To make a dashboard the portal's root page instead, mount it at `/`:
+
+```bash
+rails g pu:dashboard Home --dest=admin_portal --at=/
+```
+
+The generator writes `AdminPortal::HomeDashboard` and replaces the `root to:` line with `register_dashboard AdminPortal::HomeDashboard, at: "/"`. The page is served at the portal root (`/admin`), its cards at `/admin/dashboards/home/cards/<key>`, and the sidebar's Home link keeps pointing at it. A root-mounted dashboard is the Home link, so it is left out of the Dashboards group.
+
+The generator does not delete the old `DashboardController` or its `dashboard/index.html.erb`; nothing routes to them any more, so remove them yourself:
+
+```bash
+rm packages/admin_portal/app/controllers/admin_portal/dashboard_controller.rb
+rm packages/admin_portal/app/views/admin_portal/dashboard/index.html.erb
+```
+
+The same registration by hand, for an existing portal:
+
+```ruby
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::HomeDashboard, at: "/"   # in place of root to: "dashboard#index"
+  # ...
+end
+```
+
+Only one root per portal: keep either the `root to:` line or the `at: "/"` registration, never both.
+
+## Cards
+
+All three kinds share the same options:
+
+| Option | Meaning |
+|---|---|
+| `label:` | Card title. Defaults to a locale convention, then the key titleized. |
+| `description:` | Caption under the title. |
+| `icon:` | A `Phlex::TablerIcons::*` class shown beside the title. |
+| `span:` | Columns of the 12-column grid to span: `1` to `12`, or `:full`. Defaults to `3` for a metric and `6` for a chart or a custom card. See [Layout](#layout). |
+| `lazy:` | `true` (default) loads the card in its own turbo frame; `false` renders it inline with the page. See [Lazy and inline cards](#lazy-and-inline-cards). |
+| `refresh:` | Seconds between automatic reloads of the card's frame. Needs `lazy: true`. `false` opts the card out of the dashboard's `refresh`. |
+| `condition:` | A proc or a symbol naming a dashboard method. When false the card is left out of the page and its endpoint responds 404. |
+| `href:` | A path, or a proc returning one, that links the title. |
+
+Blocks run on the dashboard instance, which exposes `current_user`, `current_scoped_entity`, `params`, `authorized_resource_scope`, `resource_url_for`, `allowed_to?`, `helpers` (the view context) and the dashboard's own private methods. A one-argument block receives the dashboard instead.
+
+### Metric
+
+The block returns a value, or a hash with a change:
+
+```ruby
+metric(:signups) { User.count }                                       # just the number
+metric(:mrr, format: :currency) { {value: 12_400, previous: 11_000} } # +12.7%
+metric(:latency, suffix: " ms") { {value: 182, change: "-14 ms", trend: :down} }
+metric(:churn, format: :percentage, positive: :down) { {value: 1.2, previous: 1.0} }
+```
+
+| Key | Meaning |
+|---|---|
+| `value` | The number (or string) to show. `nil` renders an em dash. |
+| `previous` | Computes the percentage change from this value. |
+| `change` | A number in percentage points (`2.5` renders `+2.5%`) or a string shown verbatim. |
+| `trend` | `:up`, `:down` or `:flat`. Inferred from the sign of `change` when omitted. |
+| `change_label` | Caption after the change, such as "vs. last month". Also a card option. |
+
+Metric options: `format:` (`:number`, `:currency`, `:percentage`, `:human`, or a proc receiving the value), `precision:`, `unit:` (currency symbol), `prefix:`, `suffix:`, `positive:` (`:up` by default; `:down` when a falling number is good) and `change_label:`.
+
+### Chart
+
+The block returns [Chartkick data](https://chartkick.com/#data): a `{label => value}` hash, an array of pairs, or an array of `{name:, data:}` series. Date and time keys become a time axis.
+
+```ruby
+chart(:signups, type: :line) { User.group_by_day(:created_at, last: 30).count }
+chart(:plans, type: :pie) { Subscription.group(:plan).count }
+chart(:traffic, type: :column, stacked: true) do
+  [{name: "Web", data: web_by_week}, {name: "Mobile", data: mobile_by_week}]
+end
+```
+
+`type:` is one of `:line`, `:area`, `:column`, `:bar`, `:pie`, `:donut` or `:scatter`; `height:` sets the drawing area (default `"240px"`). Every other option (`colors:`, `stacked:`, `min:`, `max:`, `prefix:`, `suffix:`, `xtitle:`, `ytitle:`, `legend:`, `curve:`, `points:`, `library:`, ...) is passed straight through to Chartkick. Series colours default to the `--pu-chart-1` to `--pu-chart-8` design tokens.
+
+### Custom
+
+The block renders Phlex markup inside the card body. It is evaluated in the card component, so `div`, `ul`, `render` and the rest are available, and any method it calls that the component lacks is forwarded to the dashboard.
+
+```ruby
+card(:onboarding, description: "Where new tenants are") do
+  Plutonium::Wizard.in_progress_for(view_context).each do |entry|
+    a(href: entry.resume_url, class: "block py-1") { entry.label }
+  end
+end
+```
+
+## Layout
+
+The grid is 12 columns wide on large screens, so halves, thirds and quarters all divide evenly and can share a dashboard. `span:` says how many of the 12 a card takes. Left out, a metric takes `3` (four to a row) and a chart or a custom card takes `6` (two to a row).
+
+```ruby
+metric(:orders) { orders.count }                          # 3 of 12: four to a row
+metric(:revenue, span: 6, format: :currency) { revenue }  # a headline number, half the row
+chart(:revenue_by_day, type: :area, span: 8) { by_day }   # two thirds
+chart(:by_channel, type: :donut, span: 4) { by_channel }  # the remaining third
+card(:latest, span: :full) { render_latest }              # the whole row (same as 12)
+```
+
+Cards fill rows in declaration order and wrap when the next card does not fit. Tablets get two columns: a card with a span of `6` or more takes the full row, anything narrower takes one column. Phones get a single column.
+
+`width` sets the page width with the same tokens as resource pages (`:sm` to `:full`) and defaults to `:full`.
+
+## Lazy and inline cards
+
+Every card is lazy unless you say otherwise. `lazy: false` makes it inline: rendered with the page instead of fetched after it.
+
+| | `lazy: true` (default) | `lazy: false` (inline) |
+|---|---|---|
+| Where the block runs | In its own request to `<mount>/cards/<key>`, when the frame scrolls into view | In the page request, before the page is sent |
+| What the page response holds | A `<turbo-frame loading="lazy">` with a skeleton | The finished card; no frame, no skeleton, no second request |
+| Cost | One extra request per card; the page itself never waits | The page waits for the block, so every inline card adds its query time to the page |
+| `refresh` | Reloads on the card's or the dashboard's interval | Never refreshes. A number raises `ArgumentError`; the dashboard's `refresh` skips it |
+| `condition:` false | Left out of the page, block never runs, endpoint is 404 | The same |
+| Raises in production | Notice in place of the body, logged and reported | The same; the rest of the page still renders |
+| Raises in development and test | That card's frame request fails; the page and the other cards are fine | The whole page raises, because the card is part of the page |
+
+Make a card inline when its value is cheap (a cached number, an indexed count) and sits at the top of the page, where a skeleton flash and an extra request cost more than the query. Leave everything else lazy: one slow inline card delays the whole page, which is the problem lazy cards exist to solve.
+
+## Refreshing
+
+`refresh 60` on the dashboard reloads every lazy card once a minute; `refresh: 10` on a card overrides it, and `refresh: false` keeps a card out of it (an expensive chart that does not need to be live). Reloads pause while the tab is hidden and catch up when it becomes visible. A chart re-renders in place when its data changes.
+
+## Authorization
+
+A portal dashboard sits behind the portal's authentication like every other page. To restrict it further, override `authorize?`; a false answer is a 403 on the page and on every card endpoint:
+
+```ruby
+def authorize? = current_user.admin?
+```
+
+Use `condition:` to hide an individual card. The condition gates the card's endpoint as well, so a hidden card cannot be fetched by URL. An inline card behaves the same way.
+
+## Errors
+
+When `config.consider_all_requests_local` is off (production), a card whose block raises renders a short notice in its place, and the rest of the dashboard is unaffected. The failure is written to the Rails log and reported through `Rails.error` with `source: "plutonium.dashboard"` and a `context` naming the dashboard class and the card key, so an error tracker subscribed to `Rails.error` (Sentry, Honeybadger, AppSignal) receives it. In development and test the error is raised so it is visible.
+
+![A dashboard where the Revenue card shows a "This card could not be loaded." notice while the cards around it render normally](/images/guides/dashboard-card-error.png)
+
+An inline card renders under the same guard, so in production it shows the same notice. In development and test its error is the page's error: the whole dashboard raises, where a lazy card fails only its own frame. [Lazy and inline cards](#lazy-and-inline-cards) has the full comparison.
+
+## Multi-tenancy
+
+On an entity-scoped portal the page and card URLs carry the tenant segment, and `current_scoped_entity` is available in every block:
+
+```ruby
+class TeamDashboard < Plutonium::Dashboard::Base
+  metric(:members) { current_scoped_entity.memberships.count }
+end
+```
+
+## Sidebar
+
+Dashboards registered with `register_dashboard` are grouped in the portal sidebar under a **Dashboards** item, after the Home link, with one child link per dashboard. A dashboard mounted at the root is what the Home link opens, so it is left out of the group; with nothing else registered the group is not rendered. ![The icon rail with the Dashboards item open, listing the Overview and Content dashboards](/images/guides/dashboard-sidebar.png)
+
+Portals generated before this feature carry an ejected `_resource_sidebar.html.erb`; add the block from the gem's partial to list dashboards there:
+
+```erb
+dashboards = registered_dashboards.reject { |dashboard| dashboard_path_for(dashboard) == root_path }
+if dashboards.any?
+  m.item t("plutonium.resource.nav.dashboards"), icon: Phlex::TablerIcons::LayoutDashboard do |n|
+    dashboards.each do |dashboard|
+      n.item dashboard.label, url: dashboard_path_for(dashboard), icon: dashboard.icon
+    end
+  end
+end
+```
+
+The labels are the `plutonium.resource.nav.home` and `plutonium.resource.nav.dashboards` locale keys.
+
+## Translations
+
+Titles resolve by convention, layered per portal like every other derived label:
+
+```yaml
+en:
+  plutonium:
+    dashboards:
+      admin_portal/sales:
+        label: "Ventes"
+        description: "Commandes et chiffre d'affaires"
+        cards:
+          orders:
+            label: "Commandes"
+```
+
+The dashboard key is the class name underscored without the `Dashboard` suffix. See the [i18n reference](/reference/i18n).
+
+## Customizing the page
+
+The page is `Plutonium::UI::Page::Dashboard`, a `Page::Base` with the usual `render_before_*` and `render_after_*` hooks. To take it over, define `<Portal>::DashboardsController` yourself, include `Plutonium::Dashboard::Controller`, and override `show`:
+
+```ruby
+module AdminPortal
+  class DashboardsController < PlutoniumController
+    include Plutonium::Dashboard::Controller
+
+    def show
+      authorize_dashboard!
+      render CustomDashboardPage.new(dashboard: current_dashboard)
+    end
+  end
+end
+```