plutonium 0.64.0 → 0.66.0

data/docs/reference/dashboard/dsl.md

@@ -0,0 +1,123 @@
+# Dashboard DSL Reference
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+A dashboard is a subclass of `Plutonium::Dashboard::Base`. Everything is declared at class level; an instance is built per request with the view context and is the receiver of every card block.
+
+## Presentation
+
+```ruby
+presents label: "Sales", description: "Orders and revenue", icon: Phlex::TablerIcons::ChartBar
+```
+
+| Key | Default |
+|---|---|
+| `label` | `plutonium.dashboards.<key>.label`, then the class name without `Dashboard` |
+| `description` | `plutonium.dashboards.<key>.description`, then nothing |
+| `icon` | `Phlex::TablerIcons::LayoutDashboard` (used in the sidebar) |
+
+`<key>` is `Class.i18n_key`: the class name underscored without the suffix (`AdminPortal::SalesDashboard` → `admin_portal/sales`). `label` and `description` accept the class-level lazy `t("...")`.
+
+## Board-level options
+
+### refresh(seconds)
+
+Default reload interval for every lazy card. `nil` (the default) disables it.
+
+### width(token)
+
+Page width, one of `:sm`, `:md`, `:lg`, `:xl`, `:full`. Default `:full`.
+
+## Cards
+
+```ruby
+metric(key, **options) { ... }
+chart(key, **options) { ... }
+card(key, **options) { ... }
+```
+
+Keys are unique per dashboard; a duplicate raises at class load. Cards render in declaration order.
+
+### Common options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `label:` | String, lazy `t` | convention, then key titleized | Title |
+| `description:` | String, lazy `t` | convention | Caption |
+| `icon:` | Phlex icon class | none | Shown beside the title |
+| `span:` | `1`..`12`, `:full` | metric `3`, chart `6`, card `6` | Columns of the 12-column grid. `:full` is `12`. On tablets (2 columns) a span of `6` or more takes the row; phones are one column |
+| `lazy:` | Boolean | `true` | `true`: own lazy turbo frame, block runs in a separate request. `false`: inline, block runs in the page request (adding its query time to every page load); no frame, never refreshes. When `config.consider_all_requests_local` is true (development and test), an inline card's exception fails the whole page. See the [guide](/guides/dashboards#lazy-and-inline-cards) |
+| `refresh:` | Integer seconds, or `false` | dashboard `refresh` | Reload interval; requires `lazy: true` (a number on a `lazy: false` card raises `ArgumentError`). `false` opts the card out of the dashboard's `refresh` |
+| `condition:` | Proc, Symbol | none | Hides the card and 404s its endpoint when false |
+| `href:` | String, Proc | none | Links the title |
+
+Procs (`condition:`, `href:`, the block) run on the dashboard instance with `instance_exec`; a one-argument proc receives the instance instead.
+
+### Locale conventions
+
+```
+plutonium.dashboards.<key>.cards.<card>.label
+plutonium.dashboards.<key>.cards.<card>.description
+plutonium.portals.<portal>.dashboards.<key>...
+```
+
+### metric
+
+The block returns a value or a hash.
+
+| Hash key | Meaning |
+|---|---|
+| `value` | The number or string. `nil` renders `plutonium.dashboard.metric.empty` |
+| `previous` | Computes `change` as a percentage from this value; a zero previous yields no percentage |
+| `change` | Numeric percentage points (`2.5` → `+2.5%`) or a string shown as-is |
+| `trend` | `:up`, `:down`, `:flat`; inferred from the sign of `change` |
+| `change_label` | Caption after the change |
+
+| Option | Values | Meaning |
+|---|---|---|
+| `format:` | `:number` (default), `:currency`, `:percentage`, `:human`, Proc | How `value` is rendered. A proc receives the value and runs on the dashboard |
+| `precision:` | Integer | Decimal places; defaults per format (2 for currency, 1 for percentage, 3 significant for human) |
+| `unit:` | String | Currency symbol for `:currency` |
+| `prefix:` / `suffix:` | String | Wrapped around the formatted value |
+| `positive:` | `:up` (default), `:down` | Which direction is good; drives the change colour |
+| `change_label:` | String | Same as the hash key |
+
+### chart
+
+The block returns Chartkick data: `{label => value}`, `[[label, value], ...]` or `[{name:, data:}, ...]`. `Date` and `Time` keys serialise as ISO strings and draw a time axis.
+
+| Option | Values | Meaning |
+|---|---|---|
+| `type:` | `:line` (default), `:area`, `:column`, `:bar`, `:pie`, `:donut`, `:scatter` | Chartkick chart class |
+| `height:` | CSS length | Drawing area height, default `"240px"` |
+| anything else | | Passed to Chartkick unchanged: `colors`, `stacked`, `min`, `max`, `prefix`, `suffix`, `thousands`, `decimal`, `xtitle`, `ytitle`, `legend`, `curve`, `points`, `discrete`, `download`, `library`, ... |
+
+The `chart` Stimulus controller merges these over Plutonium's defaults: series colours from `--pu-chart-1` to `--pu-chart-8`, axis text from `--pu-text-muted`, grid lines from `--pu-border`, and the empty-data message from `plutonium.js.charts.empty`. A colour-mode switch redraws every chart.
+
+### card
+
+No kind-specific options. The block is `instance_exec`ed in `Plutonium::UI::Dashboard::Custom`, a Phlex component: it emits markup directly, and any method the component does not define is forwarded to the dashboard instance.
+
+## Instance API
+
+| Method | Meaning |
+|---|---|
+| `authorize?` | Override to gate the page and every card. Default `true` |
+| `visible_cards` | Cards whose `condition:` passes |
+| `visible_card!(key)` | The card, or `Plutonium::Dashboard::UnknownCardError` (404) |
+| `refresh_for(card)` | The card's interval, else the dashboard's; `nil` for a card declared `refresh: false` |
+| `view_context` / `helpers` | The Rails view context |
+| `current_user`, `current_scoped_entity`, `scoped_to_entity?`, `params`, `request`, `controller`, `current_engine`, `resource_url_for`, `authorized_resource_scope`, `allowed_to?`, `policy_for`, `registered_resources`, `root_path` | Delegated to the view context |
+
+## Class API
+
+| Method | Meaning |
+|---|---|
+| `cards` | All declared cards, in order |
+| `find_card(key)` / `find_card!(key)` | Lookup by key |
+| `label`, `description`, `icon` | Resolved presentation |
+| `i18n_key`, `route_name` | `admin_portal/sales`, `sales` |
+
+Subclasses inherit the parent's cards and options by copy, so a portal-specific subclass can add cards without touching the parent.

data/docs/reference/dashboard/index.md

@@ -0,0 +1,35 @@
+# Dashboard Reference
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+Reference documentation for Plutonium dashboards: pages of metric, chart and free-form cards, each loaded in its own lazy turbo frame by default.
+
+## In this section
+
+| Page | What it covers |
+|------|---------------|
+| [DSL](/reference/dashboard/dsl) | `Plutonium::Dashboard::Base`, `presents`, `refresh`, `width`, and the `metric` / `chart` / `card` macros with every option |
+| [Registration](/reference/dashboard/registration) | `register_dashboard`, the routes it draws, the synthesized controller, the sidebar, and the `pu:dashboard` generator |
+
+## Quick start
+
+```ruby
+# packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", icon: Phlex::TablerIcons::ChartBar
+
+    metric(:orders) { {value: Order.this_month.count, previous: Order.last_month.count} }
+    chart(:revenue, type: :area, span: 8) { Order.group_by_day(:created_at).sum(:total) }
+  end
+end
+
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"
+end
+```
+
+See the [Dashboards guide](/guides/dashboards) for a full walkthrough.

data/docs/reference/dashboard/registration.md

@@ -0,0 +1,76 @@
+# Dashboard Registration
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+## register_dashboard
+
+```ruby
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::HomeDashboard, at: "/"       # the portal root
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"  # /admin/dashboards/sales
+  register_dashboard Reports::WeeklyDashboard, at: "reports/weekly", as: "weekly"
+end
+```
+
+| Argument | Meaning |
+|---|---|
+| `at:` | Path under the portal's `dashboards/` segment. `"/"` or `""` mounts at the engine root |
+| `prefix:` | Leading path segment, `"dashboards"` by default. `nil` draws the mount at the bare `at:` path (`/admin/sales`); a string swaps the segment (`prefix: "reports"` → `/admin/reports/sales`). Does not affect helper names |
+| `as:` | Route helper prefix. Defaults to `at:` with slashes replaced, or the class slug for a root mount |
+
+### Routes drawn
+
+```
+GET /dashboards/sales             → DashboardsController#show   sales_dashboard_path
+GET /dashboards/sales/cards/:card → DashboardsController#card   sales_dashboard_card_path
+```
+
+Every path is drawn under `dashboards/`, so a dashboard never shadows a `register_resource` route of the same name (`at: "sales"` next to a `Sale` resource). The route helpers carry no prefix.
+
+With `prefix: nil` nothing reserves the path, so keep `at:` clear of your resource routes yourself.
+
+A root mount draws `root` for the page and `/dashboards/<as>/cards/:card` for the cards (`/<as>/cards/:card` with `prefix: nil`). Replace the portal's generated `root to: "dashboard#index"` line with the registration; two root routes clash. The generated `DashboardController` and its view are then unrouted and can be deleted. The [guide](/guides/dashboards#replacing-the-portal-s-default-page) walks through it.
+
+On a `:path` entity-scoped portal the routes sit inside the scope segment and the helpers are prefixed (`organization_scoped_sales_dashboard_path`). URLs built by the framework thread the current tenant through; when building your own use `dashboard_path_for(SalesDashboard)`, available in controllers, views and components.
+
+### The controller
+
+`register_dashboard` synthesizes `<Portal>::DashboardsController < <Portal>::PlutoniumController` including `Plutonium::Dashboard::Controller` and the portal's `Concerns::Controller`, so it carries the portal's authentication, entity scoping and layout. On the main app it synthesizes a bare `::DashboardsController < ApplicationController`.
+
+Define the class yourself to take over; the synthesized one is only created when the constant is missing.
+
+```ruby
+module AdminPortal
+  class DashboardsController < PlutoniumController
+    include Plutonium::Dashboard::Controller
+
+    before_action { set_page_title("Reports") }
+  end
+end
+```
+
+The concern provides `show` and `card`, `current_dashboard`, `current_dashboard_class`, `authorize_dashboard!` and `dashboard_card_path(card)`.
+
+### The card endpoint
+
+`GET <mount>/cards/:card` runs `authorize?`, looks the key up among the dashboard's cards, checks its `condition:`, and renders the card inside `<turbo-frame id="pu-dashboard-card-<key>">`. Unknown or hidden cards respond 404 (`Plutonium::Dashboard::UnknownCardError`); a denied `authorize?` responds 403. A request without a `Turbo-Frame` header renders the card inside the full layout.
+
+## Sidebar
+
+`registered_dashboards` (a controller helper, also available in components) lists the dashboards mounted on the current engine, and `dashboard_path_for(klass)` builds each page path. The gem's `_resource_sidebar.html.erb` groups them under a Dashboards item (`plutonium.resource.nav.dashboards`) after the Home link (`plutonium.resource.nav.home`), skipping the one mounted at the root, which the Home link already opens.
+
+## Generator
+
+```bash
+rails g pu:dashboard Sales --dest=admin_portal            # /admin/dashboards/sales
+rails g pu:dashboard Home --dest=admin_portal --at=/      # portal root
+rails g pu:dashboard Reporting --dest=main_app --at=reports
+```
+
+Writes `app/dashboards/<portal>/<name>_dashboard.rb` in the package (or `app/dashboards/` for `main_app`) and adds the `register_dashboard` line to the routes. Idempotent.
+
+## Assets
+
+Chart cards load `plutonium-charts.js` (Chart.js and Chartkick) on demand; the file ships with the gem beside `plutonium.js` and is precompiled with it. `Plutonium.configuration.assets.charts_script` names the asset (`"plutonium-charts.min.js"` by default). When `PLUTONIUM_DEV` is set the file comes from the `src/build` manifest like the main bundle.

data/docs/reference/generators/lite.md

@@ -16,10 +16,10 @@ rails g pu:lite:tune
 
 It writes a `pragmas:` mapping:
 
-- `cache_size: -64000` — 64 MB page cache (the ~2 MB default is too small).
-- `temp_store: 2` — MEMORY; sorts and temp indexes stay off disk.
-- `mmap_size: 536870912` — 512 MB memory-mapped I/O.
-- `wal_autocheckpoint: 10000` — checkpoint roughly every 40 MB of WAL.
+- `cache_size: -64000`: 64 MB page cache (the ~2 MB default is too small).
+- `temp_store: 2`: MEMORY; sorts and temp indexes stay off disk.
+- `mmap_size: 536870912`: 512 MB memory-mapped I/O.
+- `wal_autocheckpoint: 10000`: checkpoint roughly every 40 MB of WAL.
 
 On Rails < 8.1 it also writes the baseline pragmas (`journal_mode: WAL`,
 `synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) that Rails 8.1+
@@ -30,7 +30,7 @@ constant-poll busy handler (`busy_handler_timeout`), which has better tail-laten
 than SQLite's internal exponential backoff. Setting a busy-timeout pragma would
 replace the better handler with the worse one, so this generator never emits it.
 
-The generator is idempotent — re-running it detects the existing pragmas and skips.
+The generator is idempotent: re-running it detects the existing pragmas and skips.
 It only ever touches the `default:` block, so a `pragmas:` mapping nested under
 another environment is left untouched.
 
@@ -47,7 +47,7 @@ rails g pu:lite:maintenance --schedule="every day at 4am"
 
 The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
 only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
-by default — edit `VACUUM_DBS` in the generated job to suit your app).
+by default; edit `VACUUM_DBS` in the generated job to suit your app).
 
 **Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
 to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
@@ -61,5 +61,5 @@ Databases listed in the job that don't exist in `config/database.yml` are skippe
 at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
 have run.
 
-If `solid_queue` is not installed, the job file is still created but not scheduled —
+If `solid_queue` is not installed, the job file is still created but not scheduled:
 add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/i18n.md

@@ -0,0 +1,262 @@
+# Internationalization
+
+Every string Plutonium renders comes from a locale file, and every label it derives from a key (an action, a scope, a filter, a kanban column, a wizard step, a field's placeholder) can be supplied by one. Nothing in a definition has to change for an app to translate its UI or reword the defaults.
+
+## Where the strings live
+
+Plutonium ships its own text under `config/locales/en/*.yml` in the gem, all under the `plutonium` namespace. Rails loads it at the lowest precedence:
+
+1. The host application's `config/locales` wins over everything.
+2. Package and portal engines' `config/locales`, which Rails loads automatically.
+3. The gem's defaults.
+
+So a portal can reword a Plutonium string for itself, and the app can override the portal.
+
+To change a fixed string, copy its key into your own locale file. The gem's locale files are the catalogue:
+
+```yaml
+# config/locales/en.yml
+en:
+  plutonium:
+    boolean:
+      "true": "On"
+      "false": "Off"
+```
+
+Pagination is the one surface with its own dictionary. The info sentence, the per-page sentence and the nav aria labels come from [Pagy's](https://ddnexus.github.io/pagy/resources/i18n) locale files, which cover about thirty-five languages. Override a Pagy key by adding a file to `Pagy::I18n.pathnames`, not through Rails I18n.
+
+## Switching locale
+
+Plutonium reads `I18n.locale` on every render and never sets it. Set the locale the way any Rails app does, typically an `around_action` in the portal's controller concern:
+
+```ruby
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :switch_locale
+      end
+
+      def switch_locale(&)
+        I18n.with_locale(current_user&.locale || I18n.default_locale, &)
+      end
+    end
+  end
+end
+```
+
+The Pagy locale is synced to `I18n.locale` on each pagination render, so the same switch covers pagination.
+
+## Models and attributes
+
+Model and attribute names follow the Rails convention and already drive every label, column header, page title and flash:
+
+```yaml
+en:
+  activerecord:
+    models:
+      blogging/post:
+        one: "Post"
+        other: "Posts"
+    attributes:
+      blogging/post:
+        title: "Title"
+        published_at: "Published"
+```
+
+The model key is `model_name.i18n_key`: `blogging/post` for `Blogging::Post`. When a model defines `one` and `other`, Plutonium uses them for the plural forms in page titles, empty states and pagination. Without them it falls back to English inflection.
+
+## Fields: placeholder, hint, description
+
+A definition never has to declare help text to make it translatable. When an input or display leaves a slot blank, Plutonium looks it up by convention:
+
+```yaml
+en:
+  plutonium:
+    fields:
+      blogging/post:
+        title:
+          placeholder: "A short, descriptive title"
+          hint: "Shown in search results"
+        body:
+          description: "Rendered as Markdown"
+```
+
+`placeholder` and `hint` apply to forms. `description` applies to displays. The lookup walks the model's ancestors like `human_attribute_name` does, so a key on `blogging/post` also serves an STI subclass.
+
+For each slot the resolution order is:
+
+1. An explicit option on `input` or `display`, then on `field`.
+2. `plutonium.portals.<portal>.fields.<model>.<attr>.<slot>` when rendering inside a portal.
+3. `plutonium.fields.<model>.<attr>.<slot>`.
+4. `helpers.placeholder.<model>.<attr>`, the Rails `form_with` convention, for placeholders only.
+5. Nothing.
+
+An explicit option can still be a translation. Use the definition's class-level `t`, which returns a lazy value resolved on every render in the request's locale:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  input :email, placeholder: t("forms.shared.email_placeholder")
+  input :quantity, hint: t("forms.stock.hint", count: 3)
+end
+```
+
+`t` is sugar over the proc form, which also works and has always been locale-safe:
+
+```ruby
+input :email, placeholder: -> { I18n.t("forms.shared.email_placeholder") }
+```
+
+Never call `I18n.t` directly in a class body. It runs once, at load time, in whatever locale happened to be active. Literal strings remain allowed and are used as they are.
+
+The page-title setters take the same values. Pass a literal to fix it, or the lazy `t` to translate it per request:
+
+```ruby
+index_page_title t("blog.index.title")
+index_page_description t("blog.index.description")
+```
+
+When a definition sets no title, the page falls back to the resource's translated model name.
+
+The setter's proc is called with no record context, so a title that depends on the record belongs in a `page_title` override on the nested page class (`class ShowPage < ShowPage`), where `object` is available.
+
+## Your own components and pages
+
+Text you add to the UI goes in a locale file too. Which `t` you call depends on where the code runs:
+
+| Where | Call |
+|---|---|
+| Components, pages, and nested `Form` / `Display` / `Table` classes (render hooks included) | `t("full.key", **opts)`, a protected method from `Plutonium::UI::Component::Behaviour` |
+| `display` / `input` / `column` blocks in a definition | `t("full.key")`, since the block runs inside the rendering component |
+| Definition class body (`label:`, `hint:`, `placeholder:`, page titles) | the class-level lazy `t("full.key")` above |
+| A bare Phlexi field component that does not include `Behaviour` | `Plutonium::Translation.t("full.key")` |
+
+All of them take full keys only. Use one key per sentence with `%{name}` placeholders rather than concatenating fragments around a value, and `count:` for plurals:
+
+```ruby
+def render_before_content
+  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
+```
+
+## Derived labels
+
+Actions, scopes, filters, kanban columns and wizard steps default to a humanized version of their key. Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
+
+```yaml
+en:
+  plutonium:
+    actions:
+      blogging/post:
+        publish: "Publish now"
+    scopes:
+      blogging/post:
+        drafts: "Drafts"
+    filters:
+      blogging/post:
+        author: "Written by"
+    kanban_columns:
+      blogging/post:
+        in_review: "In review"
+    wizard_steps:
+      onboarding_wizard:
+        billing: "Billing details"
+```
+
+The model segment is the resource's `model_name.i18n_key`. For wizard steps it is the wizard's `model_name.i18n_key`.
+
+Enum values shown as badges, and the value pills of a select filter, resolve the way Rails resolves enum attribute values, with a Plutonium key as an alternative:
+
+```yaml
+en:
+  activerecord:
+    attributes:
+      blogging/post:
+        status/draft: "Draft"
+        status/published: "Live"
+  plutonium:
+    values:
+      blogging/post:
+        status:
+          archived: "Archived"
+```
+
+## Portals
+
+Every convention key has a portal-scoped variant under `plutonium.portals.<portal>`, where `<portal>` is the package namespace (`admin_portal`). It wins over the global key while rendering inside that portal, and the main app has no portal segment.
+
+Portal packages are Rails engines, so their `config/locales` directory loads automatically. The portal generator scaffolds `packages/<portal>/config/locales/en.yml` with the prefix in place:
+
+```yaml
+# packages/admin_portal/config/locales/en.yml
+en:
+  plutonium:
+    portals:
+      admin_portal:
+        fields:
+          blogging/post:
+            title:
+              placeholder: "Internal working title"
+        actions:
+          blogging/post:
+            publish: "Publish to site"
+```
+
+Feature packages get the same file for their models' names, attributes and field text. Keys without the portal prefix apply everywhere, and load order settles conflicts: the app's files beat a package's, and a package's beat the gem's.
+
+Locale keys vary by portal, never by tenant. Tenant-specific wording is a custom I18n backend concern and is out of scope.
+
+## JavaScript
+
+The Stimulus controllers bundled with the gem read their strings from a JSON blob the layout renders once per page, in the current locale:
+
+```html
+<meta name="pu-i18n" content="{&quot;clipboard&quot;:{&quot;copied&quot;:&quot;Copied!&quot;},...}">
+```
+
+The blob is the `plutonium.js` subtree of the locale merged over the default locale, so overriding a key in YAML changes the bundled JavaScript's text without rebuilding it, and a partially translated locale falls back per key. Host code can read the same blob:
+
+```js
+window.Plutonium.t("plutonium.js.turbo_confirm.confirm")
+window.Plutonium.t("plutonium.js.attachment_input.delete_all", { count: 3 })
+```
+
+Third-party widgets keep their own locale mechanisms. The blob carries optional pass-through settings under `plutonium.js.libraries`:
+
+| Key | Passed to |
+|---|---|
+| `slim_select` | Slim Select `settings` (`placeholderText`, `searchText`, `searchPlaceholder`, `searchingText`) |
+| `flatpickr.locale` | flatpickr's `locale` option. Loading the matching `l10n` bundle is the host's job. |
+| `uppy.strings` | Uppy `locale.strings` |
+| `intl_tel_input` | intl-tel-input `i18n` |
+
+## Auth
+
+Rodauth's own text (labels, buttons, flashes, email subjects) is translated by the [rodauth-i18n](https://github.com/janko/rodauth-i18n) gem, which Plutonium's Rodauth views pick up unchanged because they render through Rodauth's configuration methods. The mailer templates the Rodauth generator copies into your app are plain ERB and are yours to translate.
+
+## Testing
+
+Turn on missing-translation errors in the test environment so a rendered component with a missing key fails instead of printing its key:
+
+```ruby
+# config/environments/test.rb
+config.i18n.raise_on_missing_translations = true
+```
+
+Convention lookups are exempt. They probe with `default: nil` and render nothing when a key is absent, which is the intended behaviour, so they never raise.
+
+## Adding a language
+
+For a second locale, provide:
+
+1. A [rails-i18n](https://github.com/svenfuchs/rails-i18n) locale for Rails' own strings, dates and numbers.
+2. A Pagy dictionary for pagination, which Pagy ships for most languages.
+3. `rodauth-i18n` if you use Rodauth.
+4. A `plutonium` namespace translated from the gem's `config/locales/en/*.yml`.
+5. Your models, attributes and field text under the keys above.
+
+Plutonium itself ships only `en`.

data/docs/reference/index.md

@@ -7,14 +7,16 @@ aside: false
 <SectionLanding
   eyebrow="Reference"
   title="Every API, in one place."
-  lede="The full surface area of Plutonium — controllers, policies, definitions, fields, interactions, generators."
+  lede="The full surface area of Plutonium: controllers, policies, definitions, fields, interactions, generators."
   mode="categorized"
   :rail="[
     { group: 'App', items: [
       { name: 'Overview', link: '/plutonium-core/reference/app/' },
+      { name: 'Configuration', link: '/plutonium-core/reference/configuration' },
       { name: 'Packages', link: '/plutonium-core/reference/app/packages' },
       { name: 'Portals', link: '/plutonium-core/reference/app/portals' },
       { name: 'Generators', link: '/plutonium-core/reference/app/generators' },
+      { name: 'Lite (SQLite) generators', link: '/plutonium-core/reference/generators/lite' },
     ]},
     { group: 'Resource', items: [
       { name: 'Overview', link: '/plutonium-core/reference/resource/' },
@@ -22,13 +24,15 @@ aside: false
       { name: 'Definition', link: '/plutonium-core/reference/resource/definition' },
       { name: 'Query', link: '/plutonium-core/reference/resource/query' },
       { name: 'Actions', link: '/plutonium-core/reference/resource/actions' },
-      { name: 'Positioning', link: '/plutonium-core/reference/positioning' },
+      { name: 'Positioning', link: '/plutonium-core/reference/resource/positioning' },
+      { name: 'CSV Export', link: '/plutonium-core/reference/resource/export' },
     ]},
     { group: 'Behavior', items: [
       { name: 'Overview', link: '/plutonium-core/reference/behavior/' },
       { name: 'Controllers', link: '/plutonium-core/reference/behavior/controllers' },
       { name: 'Policies', link: '/plutonium-core/reference/behavior/policies' },
       { name: 'Interactions', link: '/plutonium-core/reference/behavior/interactions' },
+      { name: 'Async interactions', link: '/plutonium-core/reference/behavior/async-interactions' },
     ]},
     { group: 'UI', items: [
       { name: 'Overview', link: '/plutonium-core/reference/ui/' },
@@ -65,6 +69,11 @@ aside: false
       { name: 'Positioning', link: '/plutonium-core/reference/kanban/positioning' },
       { name: 'Authorization', link: '/plutonium-core/reference/kanban/authorization' },
     ]},
+    { group: 'Dashboard', items: [
+      { name: 'Overview', link: '/plutonium-core/reference/dashboard/' },
+      { name: 'DSL', link: '/plutonium-core/reference/dashboard/dsl' },
+      { name: 'Registration', link: '/plutonium-core/reference/dashboard/registration' },
+    ]},
     { group: 'Testing', items: [
       { name: 'Overview', link: '/plutonium-core/reference/testing/' },
     ]},

data/docs/reference/kanban/authorization.md

@@ -5,7 +5,7 @@
 Every drag-and-drop move is authorized through the `kanban_move?` method on the resource's policy. The default implementation delegates to `update?`:
 
 ```ruby
-# Plutonium::Resource::Policy — built-in default
+# Plutonium::Resource::Policy (built-in default)
 def kanban_move?
   update?
 end
@@ -29,7 +29,7 @@ end
 
 ## Gating a specific transition (`from` / `to` context)
 
-`kanban_move?` is the **single** authorization for every move — plain moves and `enter_interaction:` columns alike. To gate a *specific* transition, read the source and destination columns from the authorization context. They are exposed as the optional `kanban_from` / `kanban_to` policy readers (the `Plutonium::Kanban::Column` objects), and are `nil` for every non-move authorization:
+`kanban_move?` is the **single** authorization for every move (plain moves and `enter_interaction:` columns alike). To gate a *specific* transition, read the source and destination columns from the authorization context. They are exposed as the optional `kanban_from` / `kanban_to` policy readers (the `Plutonium::Kanban::Column` objects), and are `nil` for every non-move authorization:
 
 ```ruby
 class DealPolicy < ResourcePolicy
@@ -42,28 +42,28 @@ class DealPolicy < ResourcePolicy
 end
 ```
 
-Rules take no positional arguments in ActionPolicy — the columns arrive via context, which the controller supplies on the `kanban_move?` check (`context: { kanban_from:, kanban_to: }`). This replaces per-column policy methods: an `enter_interaction:` column is authorized by `kanban_move?` too, so there is no separate `mark_lost?`-style predicate to define.
+Rules take no positional arguments in ActionPolicy; the columns arrive via context, which the controller supplies on the `kanban_move?` check (`context: { kanban_from:, kanban_to: }`). This replaces per-column policy methods: an `enter_interaction:` column is authorized by `kanban_move?` too, so there is no separate `mark_lost?`-style predicate to define.
 
 Both `kanban_from` and `kanban_to` are **trustworthy** to authorize on. `to` is where the card ends up; and although `from_column` arrives from the client, the move handler **verifies the record actually resides in the claimed source column** before it proceeds (a mismatch snaps the drag back), so a spoofed or stale `from` can never drive a move past a `kanban_from`-based rule.
 
 ## Read-only board
 
-When `kanban_move?` returns `false` for the current user, the board is rendered read-only. Cards are displayed but dragging is disabled — no drag handles appear and the Stimulus controller does not register drop zones.
+When `kanban_move?` returns `false` for the current user, the board is rendered read-only. Cards are displayed but dragging is disabled: no drag handles appear and the Stimulus controller does not register drop zones.
 
 ## Authorization flow on a move
 
 When a card is dropped, the server:
 
 1. Finds the record within the current authorized scope (the same policy `relation_scope` used by the index action).
-2. Calls `authorize_current!(record, to: :kanban_move?, context: { kanban_from:, kanban_to: })` — the single authorization for the move (an `enter_interaction:` column rides on this same check, with no policy method of its own). A `false` result halts the action with HTTP 403.
-3. Verifies the record actually resides in the claimed source column (`from_column` is client-supplied). A mismatch responds 422 and snaps the card back — this is what makes `kanban_from` safe to authorize on.
-4. Validates the drop against the destination column's `accepts:` policy and `locked:` flag. A rejected drop responds with HTTP 422 and re-renders the source column (the Stimulus controller snaps the card back).
+2. Calls `authorize_current!(record, to: :kanban_move?, context: { kanban_from:, kanban_to: })`: the single authorization for the move (an `enter_interaction:` column rides on this same check, with no policy method of its own). A `false` result halts the action with HTTP 403.
+3. Verifies the record actually resides in the claimed source column (`from_column` is client-supplied). A mismatch responds 422 and snaps the card back; this is what makes `kanban_from` safe to authorize on.
+4. Validates the drop against the destination column's `accepts:` policy and the source column's `locked:` flag (a locked column lets no card leave). A rejected drop responds with HTTP 422 and re-renders the source column (the Stimulus controller snaps the card back).
 5. Enforces the destination column's `wip:` limit (cross-column moves only). Exceeding the WIP cap also responds 422.
-6. Calls `on_enter` and repositions the record inside a transaction.
+6. Calls the source column's `on_exit`, then the destination's `on_enter`, and repositions the record, all inside a transaction.
 
 ## No permitted attributes for moves
 
-Kanban moves do **not** pass through `permitted_attributes_for_update` / `permitted_attributes_for_kanban_move`. The `on_enter` callback is author code that runs with full model access — it is the responsibility of the `on_enter` implementation to assign only the attributes appropriate for a column transition. This is intentional: the callback is trusted Ruby, not user-supplied form data.
+Kanban moves do **not** pass through `permitted_attributes_for_update` / `permitted_attributes_for_kanban_move`. The `on_enter` callback is author code that runs with full model access; it is the responsibility of the `on_enter` implementation to assign only the attributes appropriate for a column transition. This is intentional: the callback is trusted Ruby, not user-supplied form data.
 
 ## Column-level drop policies