plutonium 0.64.0 → 0.65.0

data/docs/blog/introducing-plutonium-dashboards.md

@@ -0,0 +1,175 @@
+---
+title: "Introducing Plutonium dashboards: metric cards and charts for your Rails admin"
+titleTemplate: "Plutonium Blog"
+date: 2026-10-01
+description: Plutonium now ships dashboards. Declare metric, chart and free-form cards in one Ruby class, mount it with one routes line, and every card loads in its own turbo frame inside your portal's auth and tenancy.
+author: Stefan Froelich
+tags: [announcement, dashboards, charts]
+draft: true
+---
+
+# Introducing Plutonium dashboards: metric cards and charts for your Rails admin
+
+<BlogMeta />
+
+Every portal Plutonium generates opens on a Dashboard page that lists your resources with a record count each. Anything past that, the numbers and charts an admin actually opens the app to see, was yours to build: a controller action, some instance variables, a view. The next release ships it. A dashboard is a Ruby class of cards, mounted with one line in your routes.
+
+![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/blog/dashboards-overview.png)
+
+## What's in the box
+
+- A class-level DSL with three kinds of card: `metric` for headline numbers, `chart` for charts, `card` for anything else.
+- `register_dashboard`, which draws the routes and a controller that inherits your portal's authentication, tenant scoping and layout.
+- Lazy loading: every card is fetched in its own turbo frame, behind a skeleton.
+- A 12-column grid with a default width per kind of card, plus per-card refresh intervals, conditions, links and icons.
+- A `pu:dashboard` generator, and a Dashboards group in the portal sidebar.
+
+## Generate one
+
+```bash
+rails g pu:dashboard Sales --dest=admin_portal
+```
+
+This writes `packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb` and adds the registration to the portal's routes:
+
+```ruby
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"
+end
+```
+
+The page is served at `/admin/dashboards/sales`. Pass `--at=/` instead and the dashboard becomes the portal's root page, replacing the generated `root to: "dashboard#index"` (the old `DashboardController` and its view can then go).
+
+## Declare the cards
+
+```ruby
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", 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: 2.1, previous: 1.8}
+    end
+
+    chart(:orders_per_day, type: :area, span: 8) do
+      orders.pluck(:created_at).map(&:to_date).tally.sort.to_h
+    end
+
+    chart(:by_status, type: :donut, span: 4) { orders.group(:status).count }
+
+    card(:latest, span: :full) do
+      ul { latest_orders.each { |order| li { order.number } } }
+    end
+
+    private
+
+    def orders = authorized_resource_scope(Order)
+
+    def latest_orders = orders.order(created_at: :desc).limit(5)
+  end
+end
+```
+
+**Metrics.** The block returns a number, or a hash. Give it a `previous` value and the card computes the percentage change and shows it with a trend arrow. `format:` is `:number`, `:currency`, `:percentage`, `:human` (1.23 Million) or a proc. `positive: :down` says a falling number is the good direction, so the refund rate above, up from 1.8 to 2.1, is styled as bad news.
+
+**Charts.** The block returns [Chartkick data](https://chartkick.com/#data): a hash, an array of pairs, or an array of named series. `type:` is `:line`, `:area`, `:column`, `:bar`, `:pie`, `:donut` or `:scatter`, and every other option passes straight through to Chartkick.
+
+**Custom cards.** The block renders Phlex markup inside the card, for a recent-activity list, a call to action, or whatever the first two do not cover.
+
+**Layout.** The grid is 12 columns wide, so halves, thirds and quarters can share a dashboard. `span:` says how many a card takes. Left out, a metric takes 3 (four to a row) and a chart or custom card takes 6. Above, the area chart takes two thirds of its row and the donut the remaining third. Tablets drop to two columns and phones to one.
+
+Blocks run on the dashboard instance, so private methods are how cards share a query. `authorized_resource_scope(Order)` is the same policy scope your resource pages use: the dashboard counts what this user may see, in this tenant, without restating either rule.
+
+## Every card loads on its own
+
+The page response contains no query results. Each card renders as a lazy turbo frame holding a skeleton:
+
+```html
+<turbo-frame id="pu-dashboard-card-orders" src="/admin/dashboards/sales/cards/orders" loading="lazy">
+```
+
+The browser fetches each frame as it scrolls into view, and the card's block runs in that request. The page paints at once, the cheap cards fill in first, and one expensive aggregate delays itself and nothing else.
+
+![The same dashboard before its frames have loaded: every card is a grey skeleton except the Conversion metric, which is already showing 12.5%](/images/blog/dashboards-loading.png)
+
+The Conversion card in that screenshot is declared `lazy: false`, which makes it inline: its block runs in the page request and the finished card is part of the page response, with no frame, no skeleton and no second request. The price is that the page waits for it. Use it for a number cheap enough that a round trip costs more than the query, and leave everything else lazy. An inline card never refreshes, since there is no frame to reload.
+
+`refresh 60` on the dashboard reloads every lazy card once a minute. `refresh: 10` on a card overrides it, and `refresh: false` keeps an expensive card out of it. Reloads pause while the tab is hidden and catch up when it becomes visible again, so a dashboard left open overnight is not running your aggregates all night.
+
+## Who sees what
+
+A portal dashboard sits behind the portal's login like every other page. To restrict it further, override `authorize?`; a false answer is a 403 from the page and from every card URL.
+
+```ruby
+def authorize? = current_user.admin?
+```
+
+`condition:` hides a single card. Because a card is an endpoint, the condition guards the endpoint too: a hidden card responds 404, so it cannot be fetched by guessing its key.
+
+```ruby
+metric(:margin, format: :percentage, condition: -> { current_user.admin? }) { margin }
+```
+
+On an entity-scoped portal the page and card URLs carry the tenant segment (`/org/1/dashboards/team`) and `current_scoped_entity` is available in every block:
+
+```ruby
+class TeamDashboard < Plutonium::Dashboard::Base
+  metric(:members) { current_scoped_entity.memberships.count }
+end
+```
+
+## When a card breaks
+
+In development and test a card that raises, raises, and you fix the query. In production the card shows a short notice in place of its body and the rest of the dashboard is untouched.
+
+![A dashboard where the Revenue card shows a red "This card could not be loaded." notice while the metrics and the signups chart around it render normally](/images/blog/dashboards-card-error.png)
+
+The failure is written to the Rails log with the dashboard class, the card key and the top of the backtrace, and it is reported through `Rails.error`:
+
+```ruby
+Rails.error.report(
+  error,
+  handled: true,
+  source: "plutonium.dashboard",
+  context: {dashboard: "AdminPortal::SalesDashboard", card: "revenue"}
+)
+```
+
+Both happen because `Rails.error.report` notifies subscribers and writes nothing to the log. An app with no error tracker still gets a log line; an app with Sentry, Honeybadger or AppSignal subscribed gets a handled error it can group by card and alert on.
+
+## Charts without the bundle tax
+
+Charts render with [Chart.js](https://www.chartjs.org/) through Chartkick, which is a lot of JavaScript for an app where most pages are tables and forms. It ships as a separate bundle. A chart card carries the bundle's URL in a data attribute and the `chart` Stimulus controller injects the script the first time a chart connects, so pages without a chart never download it.
+
+Series colours come from the `--pu-chart-1` to `--pu-chart-8` design tokens and are re-read when the colour mode flips. Charts follow your theme in light and dark mode with no per-chart configuration.
+
+## In the sidebar
+
+Registered dashboards are grouped under a Dashboards item in the portal sidebar, with a link per dashboard. A dashboard mounted at the root is what the Home link opens, so it stays out of the group.
+
+![The portal's icon rail with the Dashboards item open, listing Overview and Content](/images/blog/dashboards-sidebar.png)
+
+If your portal has an ejected `_resource_sidebar.html.erb` from an earlier release, the [guide](/guides/dashboards#sidebar) has the block to add.
+
+## A note on URLs
+
+Every dashboard is drawn under a `dashboards/` segment. A portal's URL space already belongs to `register_resource`, and a dashboard at a bare `/admin/sales` is one `Sale` model away from a route collision that Rails resolves silently, by order. If you want the bare path anyway, `prefix: nil` turns the segment off for that mount.
+
+## Experimental, for now
+
+Dashboards ship marked experimental, like kanban, wizards and async interactions: fine to build on, but the DSL may still move before 1.0. If the API fights you, tell me. That feedback still changes things.
+
+## Where to go next
+
+- [Dashboards guide](/guides/dashboards): the worked example, every card option, layout and translations.
+- [Dashboard reference](/reference/dashboard/): the DSL, `register_dashboard` and the routes it draws, and the generator.

data/docs/blog/introducing-plutonium-i18n.md

@@ -0,0 +1,91 @@
+---
+title: "Introducing Plutonium i18n: every string translatable, the Rails way"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-17
+description: The text a framework renders has always been the framework's, not yours. Plutonium now routes every string it draws through a locale file, so translating the UI is a matter of YAML and nothing else.
+author: Stefan Froelich
+tags: [announcement, i18n, rails]
+draft: true
+---
+
+# Introducing Plutonium i18n: every string translatable, the Rails way
+
+<BlogMeta />
+
+You have always been able to translate your own app. Rails has shipped `I18n.t`, per-model attribute names and localized dates since long before you needed them. What you could not translate was the framework on top. The button that says "Create", the "Search..." in the filter box, the flash that a record was saved, the empty-state line, the sentence under the paginator: an admin framework ships those in English, baked into views you adopted the framework precisely so you would never open. Translating them meant forking them.
+
+Plutonium now routes every string it renders through a locale file, and resolves every label it derives from a key through the Rails i18n conventions you already know. Translating the UI is a matter of YAML. Nothing in a definition, a policy or a controller changes.
+
+## The strings come from YAML
+
+Plutonium's own text lives under `config/locales/en/*.yml`, in a `plutonium` namespace, loaded at the lowest precedence. Rails' normal load order does the rest: your app's `config/locales` beats a portal's, a portal's beats the gem's. To reword a fixed string, or translate it, copy its key into your own file:
+
+```yaml
+# config/locales/en.yml
+en:
+  plutonium:
+    boolean:
+      "true": "On"
+      "false": "Off"
+```
+
+That one move covers renaming "On" to "Active" in English and translating it to another language. There is no second mechanism to learn for the second case.
+
+## The labels you never wrote translate too
+
+The strings above are the easy half. The interesting half is the text a definition never spells out. An action, a scope, a filter, a kanban column, a field's placeholder: each one defaults to a humanized version of its key, and each has a convention key that a locale file can supply.
+
+```yaml
+en:
+  plutonium:
+    actions:
+      blogging/post:
+        publish: "Publish now"
+    scopes:
+      blogging/post:
+        drafts: "Drafts"
+    fields:
+      blogging/post:
+        title:
+          placeholder: "A short, descriptive title"
+          hint: "Shown in search results"
+```
+
+A field you never annotated is already translatable. You did not declare a placeholder to get one, and you do not declare a key to translate it: Plutonium looks it up by the model's `i18n_key`, the same way `human_attribute_name` walks ancestors, so a key on `blogging/post` also serves its STI subclasses. Model and attribute names flow from the standard Rails `activerecord` keys, which is why column headers, page titles and flashes come along the moment you provide them. Nothing is declared twice, and the exception, an explicit label you do want to spell out, gets a named place: the definition's own `t`, resolved per request in the right locale.
+
+## Switching locale is a Rails around_action
+
+Plutonium reads `I18n.locale` on every render and never sets it, so you switch the way you would in any Rails app. The dummy app's admin portal wires an `EN | ES` toggle into the top bar and remembers the choice per session:
+
+```ruby
+included do
+  around_action :switch_locale
+end
+
+def switch_locale(&)
+  session[:locale] = params[:locale] if params[:locale].present?
+  locale = session[:locale].to_s.to_sym
+  locale = I18n.default_locale unless I18n.available_locales.include?(locale)
+  I18n.with_locale(locale, &)
+end
+```
+
+Pick ES and the portal answers in Spanish: the heading, the search box, the filters and scopes, the column headers, the row and page actions, the status badges, the pager and the CRUD flashes. The heading translates because the definition sets it with the same lazy `t`, `index_page_title t("blog.index.title")`, that inputs and labels use. Two things stay English by design: the record data, because it is yours and not the framework's, and any label a definition hardcodes as a plain string, like the `column :user, label: "Author"` you can see in the shot sitting next to the translated `Autor`.
+
+![The dummy admin portal rendered in Spanish, with the EN | ES switch in the top bar](/images/blog/i18n-es-admin.png)
+
+## Even the parts that aren't Rails views
+
+Two surfaces never touch Rails' server-side `t`, and both come along.
+
+The Stimulus controllers bundled with the gem read their strings from a JSON blob the layout renders once per page in the current locale. Override a key in YAML and the bundled JavaScript's text changes with it, no rebuild. And pagination, which has its own dictionary, is translated by [Pagy](https://ddnexus.github.io/pagy/resources/i18n) in about thirty-five languages out of the box. Plutonium syncs Pagy's locale to `I18n.locale` on every render, so the same `around_action` that switched the chrome switched the pager, in the screenshot above, for free.
+
+## Ship a half-translated locale
+
+You do not have to finish a language before you use it. The dummy demo translates the blog-posts screen and leaves the rest of the app, the dates, and Rodauth's own flashes to fall back to English through `config.i18n.fallbacks`. That matters more than it sounds: the test environment turns on `raise_on_missing_translations`, so a page under a half-done locale would otherwise blow up on the first key you had not reached yet. With fallbacks on, a found-via-fallback string is not missing. Translate the screens your users live on first, ship it, and fill in the rest as you go.
+
+## Adding a language
+
+A full second locale is the usual Rails checklist: a [rails-i18n](https://github.com/svenfuchs/rails-i18n) locale for dates and numbers, a Pagy dictionary, `rodauth-i18n` if you use Rodauth, the `plutonium` namespace translated from the gem's English files, and your own models and attributes. Plutonium itself ships only English, and hands you the door to the rest.
+
+The [internationalization reference](/reference/i18n) has the full key catalogue and the exact resolution order for every slot.

data/docs/blog/introducing-plutonium.md

@@ -1,11 +1,10 @@
 ---
 title: "Introducing Plutonium: Rails conventions, past CRUD"
 titleTemplate: "Plutonium Blog"
-date: 2026-08-24
+date: 2026-08-22
 description: Rails made a bargain. Follow the conventions and the framework carries you. Plutonium makes the same bargain about the layer Rails deliberately left alone.
 author: Stefan Froelich
 tags: [announcement, rails, architecture]
-draft: true
 ---
 
 # Introducing Plutonium: Rails conventions, past CRUD
@@ -146,11 +145,11 @@ input :content, as: :markdown
 display :status, as: :badge, colors: {published: :accent, draft: :neutral}
 ```
 
-**Render it inline.** A display takes a block, or a proc that runs inside a Phlex context, so tag methods and Tailwind classes are available without defining a class:
+**Render it inline.** A display takes a block that runs inside a Phlex context, so tag methods and Tailwind classes are available without defining a class:
 
 ```ruby
-display :priority, as: :phlexi_render, with: ->(value, attrs) do
-  span(class: "pu-badge") { value.humanize }
+display :priority do |field|
+  span(class: "pu-badge") { field.value.to_s.humanize }
 end
 ```
 

data/docs/blog/whats-new-async-kanban-wizards.md

@@ -119,7 +119,7 @@ See [Wizards](/guides/wizards) for the full DSL, including per-step writes, resu
 
 ## The thing underneath the board
 
-Kanban did not invent its ordering. It uses the same fractional positioning that powers [drag-to-reorder](/reference/positioning) on ordinary index tables, card grids and nested association tables. `positioned_on` on the model says how positions are stored, `position_on` in the definition says the list is orderable, and a drop writes exactly one decimal, the midpoint between its two neighbours. No renumbering sweep across the table.
+Kanban did not invent its ordering. It uses the same fractional positioning that powers [drag-to-reorder](/reference/resource/positioning) on ordinary index tables, card grids and nested association tables. `positioned_on` on the model says how positions are stored, `position_on` in the definition says the list is orderable, and a drop writes exactly one decimal, the midpoint between its two neighbours. No renumbering sweep across the table.
 
 A board and a sortable table are the same feature wearing different clothes, which is why they share a vocabulary. Positioning itself is stable, not experimental.
 

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. 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
+```

data/docs/guides/index.md

@@ -27,6 +27,7 @@ aside: false
       { name: 'Search & filtering', link: '/plutonium-core/guides/search-filtering' },
       { name: 'Wizards', desc: 'Multi-step flows — onboarding, checkout, branching create.', link: '/plutonium-core/guides/wizards' },
       { name: 'Kanban boards', desc: 'Drag-and-drop board view — columns, moves, positioning, WIP limits.', link: '/plutonium-core/guides/kanban' },
+      { name: 'Dashboards', desc: 'Metric, chart and free-form cards, each loaded in its own lazy turbo frame.', link: '/plutonium-core/guides/dashboards' },
     ]},
     { 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' },

data/docs/guides/kanban.md

@@ -396,7 +396,7 @@ By default Plutonium uses decimal fractional positioning: cards always slot exac
 
 ### Position modes
 
-`position_on` is the same verb inside and outside `kanban do…end`. Declared on the **definition** it makes the resource's index table and card grid [drag-reorderable](/reference/positioning); declared inside the board it configures the board. A board that declares none **inherits the definition's** (falling back to `:position`, Mode A), so a resource that already reorders in its table needs nothing extra here. Declaration order in the class body doesn't matter — the board resolves this lazily.
+`position_on` is the same verb inside and outside `kanban do…end`. Declared on the **definition** it makes the resource's index table and card grid [drag-reorderable](/reference/resource/positioning); declared inside the board it configures the board. A board that declares none **inherits the definition's** (falling back to `:position`, Mode A), so a resource that already reorders in its table needs nothing extra here. Declaration order in the class body doesn't matter — the board resolves this lazily.
 
 ```ruby
 kanban do
@@ -424,7 +424,7 @@ kanban do
 end
 ```
 
-See [Positioning reference](/reference/kanban/positioning) for the full API and the rebalancing behavior when the decimal gap is exhausted, and [Positioning & drag-to-reorder](/reference/positioning) for the table/grid side of the same feature.
+See [Positioning reference](/reference/kanban/positioning) for the full API and the rebalancing behavior when the decimal gap is exhausted, and [Positioning & drag-to-reorder](/reference/resource/positioning) for the table/grid side of the same feature.
 
 ---