plutonium 0.64.0 → 0.66.0

data/docs/reference/testing/index.md

@@ -1,13 +1,13 @@
 # Testing Reference
 
-`Plutonium::Testing` provides scaffolded integration tests that assert a resource × portal pairing — CRUD, policy matrix, definition smoke tests, model concerns (associated_with, SGID, has_cents), nested-resource scope boundaries, cross-portal access, and interaction outcomes. All optional, all opt-in.
+`Plutonium::Testing` provides scaffolded integration tests that assert a resource × portal pairing: CRUD, policy matrix, definition smoke tests, model concerns (associated_with, SGID, has_cents), nested-resource scope boundaries, cross-portal access, and interaction outcomes. All optional, all opt-in.
 
 ## 🚨 Critical
 
 - **Use the generators.** `pu:test:install` once per app, then `pu:test:scaffold ResourceClass --portals=...` per resource × portal. Hand-written test files drift from conventions.
-- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs — it's never autoloaded, never present in production.
+- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs; it's never autoloaded, never present in production.
 - **One file per (resource × portal).** Same model in admin and org portals = two test files. Each portal has different auth, scoping, and allowed actions.
-- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs — your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
+- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs: your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
 
 ## Quick start
 
@@ -88,6 +88,11 @@ class AdminPortal::BloggingPostsTest < ActionDispatch::IntegrationTest
 end
 ```
 
+**`valid_update_params` is also the assertion.** After the PATCH, the update test runs `assert_equal value, record.reload.public_send(attr)` for every key, so:
+
+- Use values that read back identically. Enums go in as strings (`status: "published"`): the enum reader returns a String, so `:published` fails.
+- Keep association SGIDs out of it. The loop only skips values starting with `gid://`, and `to_sgid.to_s` is a signed token, so the token gets compared to the associated record. Test reassigning an association in its own `test` block that PATCHes the SGID and asserts `record.reload.user == other_user`. `valid_create_params` has no such check, so SGIDs are fine there.
+
 ### `Plutonium::Testing::ResourcePolicy`
 
 Asserts the `permit?` matrix across action × role and verifies `relation_scope` returns an `ActiveRecord::Relation`.
@@ -133,18 +138,31 @@ Outcome-assertion helpers for `Plutonium::Resource::Interaction` subclasses.
 
 - `assert_interaction_success(klass, **input)` → returns the success outcome
 - `assert_interaction_failure(klass, **input)` → returns the failure outcome
-- `interaction_view_context` (overridable) → defaults to a mock view context
+- `interaction_view_context` (overridable) → the view context both helpers pass in (a mock by default); override it only when the interaction reads from the view context
+
+Use the helpers for both outcomes; they build the interaction and call it for you.
 
 ```ruby
-test "RebuildSearchInteraction succeeds" do
-  outcome = assert_interaction_success(RebuildSearchInteraction, since: 1.day.ago)
-  assert_equal 42, outcome.value[:rebuilt_count]
+test "PublishProduct moves a draft to active" do
+  product = create_product!(status: :draft)
+  assert_interaction_success(Catalog::PublishProduct, resource: product)
+  assert product.reload.active?
+end
+
+test "PublishProduct fails for a product that isn't a draft" do
+  product = create_product!(status: :active)
+  assert_interaction_failure(Catalog::PublishProduct, resource: product)
+  assert product.reload.active?   # state unchanged
 end
 ```
 
+The failure outcome carries no validation errors (they live on the interaction instance), so assert the unchanged state rather than building the interaction by hand to read `errors`.
+
+`ResourceInteraction` includes neither the DSL nor `AuthHelpers`. A file scaffolded with only `--concerns=interaction` still has the template's `resource_tests_for` and `login_as(@account)`, which raise `NoMethodError`: delete both (the helpers need no portal and no login).
+
 ### `Plutonium::Testing::ResourceModel`
 
-Tests `associated_with` scope, SGID routing, and `has_cents` accessors — gated by DSL flags.
+Tests `associated_with` scope, SGID routing, and `has_cents` accessors, gated by DSL flags.
 
 **Stubs:**
 
@@ -167,13 +185,77 @@ Asserts CRUD under a parent + scope-boundary tests (sibling tenants invisible).
 
 **Stubs:**
 
-- `parent_record!` → current tenant
+- `parent_record!` → current tenant (called several times per test, so return the same record each time, e.g. `@org`)
 - `other_parent_record!` → sibling tenant
 - `create_resource!(parent:)` → persisted record under given parent
 
+The concern builds its URLs as `"#{current_path_prefix}/#{parent.id}/#{collection}"`, so it expects the bare portal mount as the prefix and inserts the parent id itself.
+
+#### Entity-scoped portals: CRUD + tenant isolation
+
+In a portal that calls `scope_to_entity Model, strategy: :path` (e.g. `/org/:id/...`), "records from another tenant aren't reachable" is the `NestedResource` concern with the entity as the parent. The resolved prefix there is the bare mount (`/org`), and the two concerns need different prefixes and different `create_resource!` signatures:
+
+| | `ResourceCrud` | `NestedResource` |
+|---|---|---|
+| URL built | `prefix/collection` | `prefix/parent.id/collection` |
+| Prefix needed | `/org/#{@org.to_param}` (override `current_path_prefix`) | `/org` (the resolved default) |
+| Calls | `create_resource!` | `create_resource!(parent:)` |
+
+One class can't satisfy both, so split the scaffolded file into two classes:
+
+```bash
+rails g pu:test:scaffold Catalog::Variant --portals=org --concerns=crud,nested --parent=organization
+```
+
+```ruby
+class OrgPortal::CatalogVariantTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::ResourceCrud
+
+  resource_tests_for Catalog::Variant, portal: :org
+
+  setup do
+    @org = create_organization!
+    @user = create_user!
+    create_membership!(organization: @org, user: @user)
+    @product = create_product!(user: @user, organization: @org)
+    login_as(@user)                       # :org logs in through /users/login
+  end
+
+  def current_path_prefix = "/org/#{@org.to_param}"
+  def create_resource! = create_variant!(product: @product)
+  def valid_create_params = {name: "Red", sku: "RED-1", stock_count: 5, product: @product.to_sgid.to_s}
+  def valid_update_params = {name: "Red / Large"}
+end
+
+class OrgPortal::CatalogVariantNestedTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::NestedResource
+
+  resource_tests_for Catalog::Variant, portal: :org, parent: :organization
+
+  setup do
+    @org = create_organization!
+    @other_org = create_organization!
+    @user = create_user!
+    create_membership!(organization: @org, user: @user)
+    login_as(@user)
+  end
+
+  def parent_record! = @org
+  def other_parent_record! = @other_org
+
+  def create_resource!(parent:)
+    create_variant!(product: create_product!(organization: parent))
+  end
+end
+```
+
+`create_resource!(parent:)` must create under `parent`, not always under `@org`: the isolation test passes `other_parent_record!` and expects a 404 (or redirect) for that record.
+
 ### `Plutonium::Testing::PortalAccess`
 
-Cross-portal access boundaries. Uses its own DSL — NOT `resource_tests_for`.
+Cross-portal access boundaries. Uses its own DSL (NOT `resource_tests_for`).
 
 ```ruby
 class PortalAccessTest < ActionDispatch::IntegrationTest
@@ -210,7 +292,16 @@ Generates one test per (role × portal). Allowed = `200 | 302`; blocked = `302 |
 
 ## Auth helpers
 
-`Plutonium::Testing::AuthHelpers` is included transitively by every concern.
+`login_as` and friends come from `Plutonium::Testing::AuthHelpers`, which only some concerns pull in. The default portal comes from the DSL (`resource_tests_for`), which is a separate include:
+
+| Concern | `login_as` available | Bare `login_as(account)` works |
+|---|---|---|
+| `ResourceCrud`, `NestedResource` | yes | yes (portal from `resource_tests_for`) |
+| `PortalAccess` | yes | no: pass `portal:` every time |
+| `ResourcePolicy`, `ResourceDefinition`, `ResourceModel` | no | no |
+| `ResourceInteraction` | no | no |
+
+A hand-written integration test that only includes the app's own helpers (e.g. an `IntegrationTestHelper`) has no `login_as` at all. Add `include Plutonium::Testing::AuthHelpers` (and `require "plutonium/testing"` if `test_helper.rb` doesn't) and pass `portal:` explicitly. Likewise, delete the scaffold's `login_as(@account)` from a file whose concerns don't provide it.
 
 ```ruby
 login_as(account)                       # uses portal from the DSL
@@ -255,16 +346,18 @@ rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --de
 |---|---|---|
 | `--portals=admin,org` | required | Emit one file per portal |
 | `--concerns=...` | `crud,policy,definition` | Concerns to include (`crud`, `policy`, `definition`, `nested`, `model`, `interaction`, `portal_access`) |
-| `--parent=organization` | | Wires `NestedResource` parent |
+| `--parent=organization` | | Adds `parent:` to `resource_tests_for` and, only together with `nested` in `--concerns`, the `parent_record!`/`other_parent_record!` stubs |
 | `--dest=main_app\|<package>` | `main_app` | Output destination |
 
 Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
 
+`--parent` alone does not add the `NestedResource` include; pass `--concerns=crud,nested --parent=organization`. The template is one class with every requested include, a `setup` that calls `login_as(@account)`, and a no-argument `create_resource!`. Treat it as a starting point: drop `login_as`/`resource_tests_for` where the concerns don't provide them (see [Auth helpers](#auth-helpers)), and split `crud` and `nested` into two classes for [entity-scoped portals](#entity-scoped-portals-crud-tenant-isolation).
+
 ## Customization & escape hatches
 
 - **Skip individual tests:** `resource_tests_for Klass, portal: :admin, skip: %i[destroy]`
 - **Restrict action set:** `resource_tests_for Klass, portal: :admin, actions: %i[index show]`
-- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix — they coexist.
+- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix; they coexist.
 - **Non-Rodauth auth:** override `sign_in_for_tests`. See [AuthHelpers](#auth-helpers).
 - **Custom path prefix:** `path_prefix: "/v2/admin"` overrides portal resolution.
 
@@ -273,15 +366,16 @@ Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
 - **Forgotten stubs raise `NotImplementedError`** with the stub name. Look for the missing method in your test class.
 - **Portal mismatch:** `:admin` portal expects `AdminPortal::Engine` constant. If your portal is named differently, pass `path_prefix:` explicitly.
 - **Tenant leakage in stubs:** `create_resource!` for an org portal must return a record bound to the test's `@org`. Otherwise scope filtering tests pass for the wrong reason.
-- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to — otherwise even allowed roles will see `false`.
-- **Nested resources need `parent: :foo`** in the DSL AND a real parent record from `parent_record!`. Without both, path interpolation fails.
-- **`PortalAccess` doesn't use `resource_tests_for`** — use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to; otherwise even allowed roles will see `false`.
+- **Nested paths come from `parent_record!.id`**, so it must return a real, persisted tenant the logged-in account belongs to. `parent: :foo` in the DSL documents the relationship; the concern doesn't read it.
+- **Entity-scoped CRUD hitting `/org/<collection>`** (404 or routing error): a `:path` portal resolves to the bare mount, so override `current_path_prefix` to include the tenant. Don't do this in a `NestedResource` class, which adds the id itself.
+- **`PortalAccess` doesn't use `resource_tests_for`**: use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
 
 ## Related
 
-- [Behavior › Policy](/reference/behavior/policies) — the policy methods `ResourcePolicy` verifies
-- [Behavior › Interaction](/reference/behavior/interactions) — interaction outcomes asserted by `ResourceInteraction`
-- [Resource › Definition](/reference/resource/definition) — definition props the smoke test introspects
-- [Tenancy](/reference/tenancy/) — parent scoping (`NestedResource`), entity strategies (drive auth/scoping)
-- [Auth](/reference/auth/) — Rodauth setup behind the default `sign_in_for_tests`
-- [Guides › Testing](/guides/testing) — task-oriented walkthrough
+- [Behavior › Policy](/reference/behavior/policies): the policy methods `ResourcePolicy` verifies
+- [Behavior › Interaction](/reference/behavior/interactions): interaction outcomes asserted by `ResourceInteraction`
+- [Resource › Definition](/reference/resource/definition): definition props the smoke test introspects
+- [Tenancy](/reference/tenancy/): parent scoping (`NestedResource`), entity strategies (drive auth/scoping)
+- [Auth](/reference/auth/): Rodauth setup behind the default `sign_in_for_tests`
+- [Guides › Testing](/guides/testing): task-oriented walkthrough

data/docs/reference/ui/assets.md

@@ -4,11 +4,12 @@ TailwindCSS 4 + Stimulus toolchain. CSS design tokens for theming, `.pu-*` compo
 
 ## 🚨 Critical
 
-- **Always register Stimulus controllers** — `registerControllers(application)` is required. Without it, Plutonium's controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
-- **Use `plutoniumTailwindConfig.merge`** when overriding the theme — plain object spread drops Plutonium's defaults.
-- **Tokens are CSS variables**, not Tailwind keys — `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
-- **Dark mode uses `selector`** strategy — toggle `dark` on `<html>`. The bundled `color-mode` controller does this.
-- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **Custom CSS, brand colors, or your own Stimulus controllers need `pu:core:assets` first.** Out of the box the app serves the gem's prebuilt `plutonium.css` / `plutonium.min.js`; the generator switches it to your own bundles. Don't hand-write the Tailwind/PostCSS pipeline.
+- **Once the app owns its JS bundle, `registerControllers(application)`** must be in `app/javascript/controllers/index.js` (`pu:core:assets` adds it). Your bundle replaces the gem's, so without it Plutonium's controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
+- **Use `plutoniumTailwindConfig.merge`** when overriding the theme, plain object spread drops Plutonium's defaults.
+- **Tokens are CSS variables**, not Tailwind keys, `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
+- **Dark mode uses `selector`** strategy, toggle `dark` on `<html>`. The bundled `color-mode` controller does this.
+- **Style with `.pu-*` classes first, `var(--pu-*)` tokens second, raw palette pairs last.** Banners, badges, cards and buttons all have a `.pu-*` class that carries its own `.dark` rule. See [Component classes](#component-classes-pu).
 
 ## Asset configuration
 
@@ -30,13 +31,27 @@ end
 rails generate pu:core:assets
 ```
 
-This:
+Until this runs, the app serves the gem's prebuilt assets (`config.assets.stylesheet` defaults to `plutonium.css`, `script` to `plutonium.min.js`). Those are compiled from the gem's own sources, so app-side Tailwind classes, a new `primary` palette, token overrides and custom Stimulus controllers have nowhere to go. The generator:
 
-1. Installs npm packages (`@radioactive-labs/plutonium`, TailwindCSS plugins).
-2. Creates `tailwind.config.js` extending Plutonium's config.
-3. Imports Plutonium CSS into `application.tailwind.css`.
-4. Registers Plutonium's Stimulus controllers.
-5. Updates Plutonium config to point at your asset files.
+1. Installs `@radioactive-labs/plutonium` (pinned to the gem version), Tailwind 4 and the PostCSS plugins.
+2. Writes `tailwind.config.js` (through `plutoniumTailwindConfig.merge`) and `postcss.config.js`.
+3. Prepends `@import "gem:plutonium/src/css/plutonium.css";` to `application.tailwind.css` and adds `@config` after `@import "tailwindcss";`.
+4. Appends `registerControllers(application)` to `app/javascript/controllers/index.js`.
+5. Sets `config.assets.stylesheet = "application"` and `config.assets.script = "application"`, and writes the `build` / `build:css` scripts in `package.json`.
+
+Step 5 is why `registerControllers` is not optional: the gem's `plutonium.min.js` calls it itself, and your `application.js` replaces that bundle.
+
+### Prerequisites
+
+The generator aborts unless `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` exist, i.e. an app created with `-j esbuild -c tailwind` plus Stimulus. For an app without them, install the bundlers first (`bin/rails javascript:install:esbuild`, `css:install:tailwind`, `stimulus:install` from jsbundling-rails, cssbundling-rails and stimulus-rails), then run the generator. Don't hand-write `tailwind.config.js` / `postcss.config.js` instead: the generated ones resolve the gem path (`bundle show plutonium`) and load its `postcss-gem-import.cjs` so the `gem:` import works.
+
+### Package managers
+
+The generator installs with the package manager `rails javascript:build` will use. The lockfile decides: `bun.lock` or `bun.lockb` means bun, `pnpm-lock.yaml` pnpm, `package-lock.json` npm, `yarn.lock` yarn. With no lockfile, `bun.config.js` means bun, and otherwise the first of bun, yarn, pnpm or npm found on PATH wins (yarn if none is). That is why `rails new -j esbuild` on a machine with bun installed produces a bun app. When the app's jsbundling-rails provides `Jsbundling::PackageManager` (its `main` branch, not yet in a release as of 1.3.1), the generator defers to it instead; that detector ignores `yarn.lock` and picks by PATH. Every package goes through one `add` with versions inline (`tailwindcss@latest`, `@radioactive-labs/plutonium@^<gem version>`), which yarn 1, yarn 2+, bun, npm and pnpm all understand.
+
+Yarn 2+ apps get `nodeLinker: node-modules` written to `.yarnrc.yml` if no linker is set. Tailwind's PostCSS plugin does not load under Plug'n'Play.
+
+`pu:core:update` and `pu:docker:install` use the same detection, so the Dockerfile installs bun, yarn 1, or yarn 2+ via corepack to match the app.
 
 ## Tailwind config
 
@@ -78,6 +93,8 @@ theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
 })
 ```
 
+These are Tailwind palette colors, compiled into the CSS at build time (`.pu-btn-primary` is `@apply bg-primary-600 ...`; `--pu-input-focus-ring` is `theme(colors.primary.500)`). Recoloring `primary` therefore means the `merge` above plus a rebuild, not a `--pu-*` override.
+
 ### Default color palette
 
 | Color | Usage |
@@ -120,15 +137,15 @@ application.register("custom", CustomController)
 
 ### Bundled controllers
 
-- `color-mode` — dark/light mode toggle
-- `form` — form handling (pre-submit, etc.)
-- `nested-resource-form-fields` — nested form management
-- `slim-select` — enhanced select boxes
-- `flatpickr` — date/time pickers
-- `easymde` — markdown editor
+- `color-mode`: dark/light mode toggle
+- `form`: form handling (pre-submit, etc.)
+- `nested-resource-form-fields`: nested form management
+- `slim-select`: enhanced select boxes
+- `flatpickr`: date/time pickers
+- `easymde`: markdown editor
 - Various internal UI controllers
 
-### Custom Stimulus controller — standard pattern
+### Custom Stimulus controller: standard pattern
 
 ```javascript
 // app/javascript/controllers/custom_controller.js
@@ -241,9 +258,13 @@ Plutonium uses a comprehensive CSS custom-property system for consistent, themea
 ```
 
 ::: warning Mirror every `:root` override in `.dark`
-Your stylesheet loads after Plutonium's, and `:root` and `.dark` have equal specificity — so a token you override in `:root` beats Plutonium's `.dark` value even when dark mode is active. Any color token you customize in `:root` without re-asserting in `.dark` ships your light value into dark mode, where it's typically unreadable (e.g. a translucent dark `--pu-text-subtle` becomes invisible on a dark surface).
+Your stylesheet loads after Plutonium's, and `:root` and `.dark` have equal specificity, so a token you override in `:root` beats Plutonium's `.dark` value even when dark mode is active. Any color token you customize in `:root` without re-asserting in `.dark` ships your light value into dark mode, where it's typically unreadable (e.g. a translucent dark `--pu-text-subtle` becomes invisible on a dark surface).
+
+That includes the shadows: `src/css/tokens.css` redefines `--pu-shadow-sm/md/lg` (and every surface, text, border, table, input, card and chart token) under `.dark`, so a tinted light shadow left out of your `.dark` block replaces the dark one.
 :::
 
+Put dark values in a `.dark { ... }` block, not `@media (prefers-color-scheme: dark)`. Dark mode is the `dark` class on `<html>` (set by the `color-mode` controller), so a media query ignores the user's toggle. Overrides need the app's own stylesheet after the Plutonium import (`pu:core:assets`); never edit the gem's `tokens.css` / `components.css`.
+
 ### Using tokens in templates
 
 ```erb
@@ -271,7 +292,11 @@ end
 
 ## Component classes (`.pu-*`)
 
-Ready-to-use styled components in `src/css/components.css`. **Prefer these over hardcoded `gray-X/dark:gray-Y` pairs** — they auto-switch with dark mode.
+Ready-to-use styled components in `src/css/components.css`. **Prefer these over hardcoded `gray-X/dark:gray-Y` (or `warning-50 dark:warning-950`) pairs.** In order of preference:
+
+1. **A `.pu-*` class** (`pu-alert-warning`, `pu-badge-warning`, `pu-card`, `pu-btn-soft-danger`). Each ships with its own `.dark` rule and is always in the CSS, because `components.css` is part of `plutonium.css` whether the app uses the prebuilt file or imports it.
+2. **A `var(--pu-*)` token** (`text-[var(--pu-text-muted)]`, `border-[var(--pu-border)]`) for layout around them. The token switches value under `.dark` and follows any theme override.
+3. **Raw palette utilities** only for what neither covers. On the prebuilt `plutonium.css` they exist only if the gem's own sources happen to use them (its Tailwind `content` scans the gem, not your app); with your own build they compile, but each needs a hand-picked `dark:` twin that won't follow a rebrand.
 
 ### Buttons
 
@@ -310,6 +335,21 @@ Ready-to-use styled components in `src/css/components.css`. **Prefer these over
 
 Rendered automatically by the `:badge` display (enums) and `:boolean` display (Yes/No pills). See [Displays](./displays#built-in-display-components).
 
+### Alerts (inline banners)
+
+```
+.pu-alert / -success / -warning / -danger / -info
+.pu-alert-message / .pu-alert-close
+```
+
+```ruby
+div(class: "pu-alert pu-alert-warning", role: "alert") do
+  div(class: "pu-alert-message") { t("blog.posts.flagged_comments", count: flagged) }
+end
+```
+
+The same banner the flash messages use (`app/views/plutonium/_flash_alerts.html.erb`), so it already has its dark-mode colors.
+
 ### Cards, panels, tables, toolbars, empty states
 
 ```
@@ -400,12 +440,12 @@ end
 **Theme keys:** `wrapper`, `base`, `header`, `header_cell`, `body_row`, `body_cell`, `sort_icon`.
 
 ::: warning Always `super.merge(...)`
-Don't replace the theme wholesale. Plutonium's defaults handle invalid states, focus rings, and dark mode — `super.merge` keeps them.
+Don't replace the theme wholesale. Plutonium's defaults handle invalid states, focus rings, and dark mode, `super.merge` keeps them.
 :::
 
 ## Gotchas
 
-- **Stimulus controllers register silently fails.** If `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error — just no behavior.
+- **Stimulus controllers register silently fails.** Once `config.assets.script` points at the app's JS, if `registerControllers(application)` isn't called the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error: just no behavior.
 - **`plutoniumTailwindConfig.merge` is mandatory.** Plain spread drops defaults silently.
 - **Tokens are CSS variables, not Tailwind keys.** Use `bg-[var(--pu-surface)]`, not `bg-pu-surface`.
 - **Dark mode is `selector`, not `class`.** Toggle via `document.documentElement.classList.toggle('dark')`.
@@ -413,6 +453,6 @@ Don't replace the theme wholesale. Plutonium's defaults handle invalid states, f
 
 ## Related
 
-- [Forms › Theming](./forms#theming) — Form theme keys + override pattern
-- [Components](./components) — `tokens` and `classes` helpers for conditional class composition
-- [Layouts](./layouts) — fonts, dark-mode toggle, body attributes
+- [Forms › Theming](./forms#theming): Form theme keys + override pattern
+- [Components](./components): `tokens` and `classes` helpers for conditional class composition
+- [Layouts](./layouts): fonts, dark-mode toggle, body attributes

data/docs/reference/ui/components.md

@@ -22,13 +22,13 @@ TablePagination(pagy)
 Breadcrumbs()
 ```
 
-These are shorthand for `render Plutonium::UI::PageHeader.new(...)` etc. — they work because every component class is exposed as a method on `Plutonium::UI::Component::Base`.
+These are shorthand for `render Plutonium::UI::PageHeader.new(...)` etc.; they work because every component class is exposed as a method on `Plutonium::UI::Component::Base`.
 
 ## Avatar
 
 `Plutonium::UI::Avatar` renders a profile image for a subject. It resolves an optional image source and falls back to a deterministic avatar from the hosted [Navii](https://navii.dev) service, then to a generic user icon when there's nothing to show.
 
-![Avatar — Navii fallback across sizes, deterministic faces for string subjects, explicit image src, and the icon fallback](/images/components/avatar.png)
+![Avatar, Navii fallback across sizes, deterministic faces for string subjects, explicit image src, and the icon fallback](/images/components/avatar.png)
 
 ```ruby
 Avatar(user)                      # Navii fallback seeded from the record
@@ -45,7 +45,7 @@ Avatar(src: "https://.../p.png")  # a bare image, no subject/fallback
 | `src:`    | `nil`   | The image. A **Symbol** names a method on the subject (`:avatar` → `subject.avatar`); otherwise an ActiveStorage attachment, [active_shrine](https://github.com/radioactive-labs/active_shrine)/Shrine uploader, or URL string. |
 | `size:`   | `:md`   | Semantic `:xs 24 / :sm 32 / :md 40 / :lg 48 / :xl 64`, or a raw Integer (px). |
 | `alt:`    | derived | Defaults to the String subject, or the record's display name. |
-| `class:`  | —       | Merged over the default `rounded-full` classes. |
+| `class:`  | - | Merged over the default `rounded-full` classes. |
 
 ### How the source resolves
 
@@ -58,7 +58,7 @@ Avatar(src: "https://.../p.png")  # a bare image, no subject/fallback
 When `src` is absent or unattached, a Navii avatar is rendered from the subject; with no subject either, a generic user icon is shown.
 
 ::: tip Symbol `src` is a contract
-`Avatar(user, src: :avatar)` calls `user.avatar` — the subject **must** respond to it (a `NoMethodError` is raised otherwise). Use a Symbol `src` only with a record subject, not a value that might be a plain string (e.g. a guest `current_user`).
+`Avatar(user, src: :avatar)` calls `user.avatar`, the subject **must** respond to it (a `NoMethodError` is raised otherwise). Use a Symbol `src` only with a record subject, not a value that might be a plain string (e.g. a guest `current_user`).
 :::
 
 ### Privacy
@@ -94,7 +94,7 @@ class PostCardComponent < Plutonium::UI::Component::Base
         span(class: "text-sm text-[var(--pu-text-subtle)]") {
           @post.published_at&.strftime("%B %d, %Y")
         }
-        a(href: resource_url_for(@post), class: "text-primary-600") { "Read more" }
+        a(href: resource_url_for(@post), class: "text-primary-600") { t("blog.posts.card.read_more") }
       end
     end
   end
@@ -104,18 +104,18 @@ end
 ::: tip Inherit `Plutonium::UI::Component::Base`
 It gives you:
 - The component kit (`PageHeader`, `Panel`, `Block`, …)
-- Resource helpers (`resource_url_for`, `current_user`, `current_record!`, `current_definition`)
+- Resource helpers (`resource_url_for`, `current_user`, `resource_record!`, `current_definition`)
 - A `helpers` proxy for Rails helpers (`helpers.link_to`, `helpers.number_to_currency`)
 - Token / class helpers (`tokens`, `classes`)
 
-A **field** component (one you pass to `as:`) inherits its Phlexi base instead —
+A **field** component (one you pass to `as:`) inherits its Phlexi base instead:
 `include Plutonium::UI::Component::Behaviour` there to get the same helpers.
 :::
 
 ### Use in a definition
 
 A component like `PostCardComponent` above has its own constructor, so it reaches
-a field through the **block form** — you build it yourself:
+a field through the **block form**, you build it yourself:
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -129,13 +129,13 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-`as: SomeComponent` is the other route, and it expects a **field component** —
+`as: SomeComponent` is the other route, and it expects a **field component**.
 Plutonium instantiates it with the field builder, not with your keyword
 arguments. See [field components](#field-components) below.
 
 ::: warning `as:` does not take a keyword-argument component
 `display :card, as: PostCardComponent` raises `ArgumentError: wrong number of
-arguments` — the component is constructed as `PostCardComponent.new(field,
+arguments`; the component is constructed as `PostCardComponent.new(field,
 **attributes)`. Use the block form for those.
 :::
 
@@ -143,7 +143,7 @@ arguments` — the component is constructed as `PostCardComponent.new(field,
 
 A field component subclasses the Phlexi component base for its surface and reads
 everything off `field` (`field.value`, `field.object`, `field.dom`, plus
-`attributes` — the themed id/name/class Plutonium already computed):
+`attributes`, the themed id/name/class Plutonium already computed):
 
 ```ruby
 # app/components/color_picker_component.rb
@@ -172,7 +172,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-An `as:` component works in every surface that renders the field — form, show
+An `as:` component works in every surface that renders the field: form, show
 page, index column, filter panel and wizard summary alike.
 
 ### Use in a page / form / display
@@ -187,7 +187,7 @@ end
 
 ## `DynaFrameContent` pattern
 
-Enables frame-aware rendering — regular requests get the full page (header + content + footer); turbo-frame requests get only the content inside the frame.
+Enables frame-aware rendering, regular requests get the full page (header + content + footer); turbo-frame requests get only the content inside the frame.
 
 ```ruby
 def view_template(&block)
@@ -205,7 +205,7 @@ All pages inherit this automatically. Modals and frame navigation work without s
 
 Rarely. Use it when writing a custom non-resource page that needs the same frame-aware rendering as the built-in pages.
 
-For typical custom pages, just inherit `Plutonium::UI::Page::Base` and override hooks like `render_content` — the DynaFrame wrapping happens in `view_template` automatically.
+For typical custom pages, just inherit `Plutonium::UI::Page::Base` and override hooks like `render_content`, the DynaFrame wrapping happens in `view_template` automatically.
 
 ## Conditional class helpers
 
@@ -257,15 +257,15 @@ class MyComponent < Plutonium::UI::Component::Base
 end
 ```
 
-The `helpers` proxy gives you everything `ApplicationController#helpers` exposes — including any custom helpers in `app/helpers/`.
+The `helpers` proxy gives you everything `ApplicationController#helpers` exposes, including any custom helpers in `app/helpers/`.
 
 ## Available context
 
-Inside any custom component, the same set of helpers as pages/forms/displays — see [Pages › Available context](./pages#available-context).
+Inside any custom component, the same set of helpers as pages/forms/displays, see [Pages › Available context](./pages#available-context).
 
 ## Related
 
-- [Pages](./pages) — `render_*` hooks call your components
-- [Forms](./forms) — the built-in input tags and their `as:` aliases
-- [Displays](./displays) — using custom display components
-- [Assets](./assets) — design tokens (`var(--pu-*)`) and `.pu-*` component classes
+- [Pages](./pages): `render_*` hooks call your components
+- [Forms](./forms): the built-in input tags and their `as:` aliases
+- [Displays](./displays): using custom display components
+- [Assets](./assets): design tokens (`var(--pu-*)`) and `.pu-*` component classes

data/docs/reference/ui/displays.md

@@ -14,7 +14,7 @@ class PostDefinition < ResourceDefinition
       end
 
       # `fields_wrapper` is ALREADY a card (it renders a Block internally),
-      # so do not wrap it in another one — that stacks two cards and doubles
+      # so do not wrap it in another one, that stacks two cards and doubles
       # the border and shadow.
       fields_wrapper do
         render_resource_field :author
@@ -38,7 +38,7 @@ end
 |---|---|
 | `render_fields` | All permitted fields |
 | `render_resource_field(name)` | One field |
-| `render_associations` | Association tabs (driven by `permitted_associations` — see [Behavior › Policy](/reference/behavior/policies#association-permissions)) |
+| `render_associations` | Association tabs (driven by `permitted_associations`, see [Behavior › Policy](/reference/behavior/policies#association-permissions)) |
 | `object` | The record |
 | `resource_fields`, `resource_associations` | Permitted lists |
 
@@ -48,21 +48,18 @@ For per-field custom rendering, prefer declaring it in the **definition** rather
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # Block — returns any Phlex component
+  # Block, returns any Phlex component
   display :status do |field|
     StatusBadgeComponent.new(value: field.value, class: field.dom.css_class)
   end
 
-  # phlexi_render — proc whose body is rendered inside a Phlex context
-  display :priority, as: :phlexi_render, with: ->(value, attrs) {
-    case value
-    when 'high'   then span(class: "badge badge-danger")  { "High" }
-    when 'medium' then span(class: "badge badge-warning") { "Medium" }
-    else span(class: "badge badge-info") { "Low" }
-    end
-  }
+  # Block that emits markup directly (evaluated in the display's Phlex context)
+  display :priority do |field|
+    variant = {"high" => "danger", "medium" => "warning"}.fetch(field.value.to_s, "info")
+    span(class: "pu-badge pu-badge-#{variant}") { field.value.to_s.humanize }
+  end
 
-  # Field component class — built as ChartComponent.new(field, **attributes),
+  # Field component class, built as ChartComponent.new(field, **attributes),
   # so it subclasses Phlexi::Display::Components::Base and reads `field`.
   # (A component with its own constructor uses the block form above.)
   display :chart, as: ChartComponent
@@ -73,14 +70,14 @@ See [Resource › Definition › Custom rendering](/reference/resource/definitio
 
 ## Built-in display components
 
-Some types render with richer components automatically — you only declare an `as:` to override or pass options.
+Some types render with richer components automatically; you only declare an `as:` to override or pass options.
 
 | `as:` | Renders | Auto-inferred for | Options |
 |-------|---------|-------------------|---------|
 | `:boolean` | green "Yes" / neutral "No" pill | `boolean` columns | `true_label:`, `false_label:` |
 | `:badge` | colored status pill | `enum` columns | `colors:` (per-value override) |
 | `:currency` | delimited, 2-decimal money | `has_cents` decimal accessors | `unit:`, `options:` |
-| `:color` | swatch + value | — | — |
+| `:color` | swatch + value | - | - |
 
 ```ruby
 class OrderDefinition < ResourceDefinition
@@ -93,7 +90,7 @@ end
 
 **Badge colors.** Known statuses (`active`, `pending`, `failed`, …) are auto-colored by meaning. Unknown values get a stable decorative color (same value → same color). Override per-value with `colors:`; valid variants: `:neutral`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:accent`.
 
-**Currency.** No symbol is shown unless you pass `unit:` — a literal string (`"£"`) or a Symbol read off the record for per-row currencies. `has_cents` decimal accessors infer `:currency` automatically (still symbol-less until you set `unit:`).
+**Currency.** No symbol is shown unless you pass `unit:`, a literal string (`"£"`) or a Symbol read off the record for per-row currencies. `has_cents` decimal accessors infer `:currency` automatically (still symbol-less until you set `unit:`).
 
 ## Theming
 
@@ -121,20 +118,20 @@ end
 `fields_wrapper`, `fields_inner`, `sections_wrapper`, `section_grid`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`, plus the shared section-chrome keys (`section_wrapper`, `section_header`, `section_summary`, `section_accent`, `section_heading`, `section_description`, `section_caret`, `section_body`).
 
 ::: warning `fields_wrapper` is the card, `fields_inner` is the grid
-`fields_wrapper` is merged into a `Plutonium::UI::Block`, which supplies `pu-card` itself — grid classes put there style the card, not the fields. Override **`fields_inner`** for the unsectioned grid, and **`section_grid`** for the grid inside a [`display_layout`](/reference/resource/definition#display-layout) section.
+`fields_wrapper` is merged into a `Plutonium::UI::Block`, which supplies `pu-card` itself, grid classes put there style the card, not the fields. Override **`fields_inner`** for the unsectioned grid, and **`section_grid`** for the grid inside a [`display_layout`](/reference/resource/definition#display-layout) section.
 :::
 
 Section chrome comes from `Plutonium::UI::Component::Section::DEFAULT_THEME`, merged into **both** `Form::Theme` and `Display::Theme`, so form sections and show-page sections read identically by default while staying independently overridable.
 
-(`boolean` and `badge` apply their pill variant in the component, so their theme value stays empty — restyle the pills via the `.pu-badge*` classes instead.)
+(`boolean` and `badge` apply their pill variant in the component, so their theme value stays empty; restyle the pills via the `.pu-badge*` classes instead.)
 
 ## Metadata panel
 
-A right-side aside on the show page. Configured at the definition level, not the Display class — see [Resource › Definition › Metadata panel](/reference/resource/definition#metadata-panel-show-page).
+A right-side aside on the show page. Configured at the definition level, not the Display class, see [Resource › Definition › Metadata panel](/reference/resource/definition#metadata-panel-show-page).
 
 ## Related
 
-- [Pages](./pages) — `ShowPage` render hooks (often a lighter alternative to overriding `Display`)
-- [Components](./components) — building reusable Phlex display components
-- [Resource › Definition](/reference/resource/definition) — field-level display configuration (`as:`, `condition:`, blocks)
-- [Behavior › Policy](/reference/behavior/policies) — `permitted_associations` drives the show-page tablist
+- [Pages](./pages): `ShowPage` render hooks (often a lighter alternative to overriding `Display`)
+- [Components](./components): building reusable Phlex display components
+- [Resource › Definition](/reference/resource/definition): field-level display configuration (`as:`, `condition:`, blocks)
+- [Behavior › Policy](/reference/behavior/policies): `permitted_associations` drives the show-page tablist