plutonium 0.65.0 → 0.67.0

data/docs/reference/ui/forms.md

@@ -4,7 +4,7 @@ Built on [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form). Overri
 
 ## 🚨 Critical
 
-- **`render_actions` is mandatory in custom `form_template`** — without it, the form has no submit button.
+- **`render_actions` is mandatory in custom `form_template`**: without it, the form has no submit button.
 - **Configure inputs in the definition, render them with `render_resource_field`** in the form template. Don't reimplement field widgets from scratch.
 - **Override via nested classes** (`class Form < Form; end`) inside the definition. Don't replace the root `Plutonium::UI::Form::Resource` class.
 
@@ -25,7 +25,7 @@ class PostDefinition < ResourceDefinition
   class Form < Form
     def form_template
       render_fields       # render every permitted field
-      render_actions      # submit buttons — REQUIRED
+      render_actions      # submit buttons, REQUIRED
     end
   end
 end
@@ -47,9 +47,9 @@ end
 
 ## Custom layouts
 
-### Sectioned form (declarative — preferred)
+### Sectioned form (declarative: preferred)
 
-Declare sections in the **definition** using `form_layout`. The form picks up the layout automatically — no `Form` subclass needed for common cases.
+Declare sections in the **definition** using `form_layout`. The form picks up the layout automatically, no `Form` subclass needed for common cases.
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -66,11 +66,11 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-This handles headings, collapsible panels, per-section column counts, and `condition:`-based visibility — all with no view code. See [Resource › Definition › Form layout](/reference/resource/definition#form-layout) for the full DSL reference, including `ungrouped`, `condition:`, `columns:`, and the "On interactions" note.
+This handles headings, collapsible panels, per-section column counts, and `condition:`-based visibility, all with no view code. See [Resource › Definition › Form layout](/reference/resource/definition#form-layout) for the full DSL reference, including `ungrouped`, `condition:`, `columns:`, and the "On interactions" note.
 
 ### Full control: override `render_fields`
 
-When the declarative DSL doesn't cover your use case — asymmetric multi-column layouts, embedding a panel widget between sections, etc. — override `render_fields` in a nested `Form` class:
+When the declarative DSL doesn't cover your use case (asymmetric multi-column layouts, embedding a panel widget between sections, etc.) override `render_fields` in a nested `Form` class:
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -109,7 +109,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-Prefer `form_layout` in the definition — it keeps layout config out of view code and works for interactions too.
+Prefer `form_layout` in the definition; it keeps layout config out of view code and works for interactions too.
 
 ### Two-column layout
 
@@ -137,7 +137,7 @@ end
 
 ## Field builder (`field(:foo).input_tag`)
 
-`render_resource_field` uses the input config from the definition. For ad-hoc rendering — when you want fine-grained control over a specific field — use `field(...)` directly:
+`render_resource_field` uses the input config from the definition. For ad-hoc rendering (when you want fine-grained control over a specific field) use `field(...) ` directly:
 
 ```ruby
 render field(:title).wrapped { |f| f.input_tag }                # wrapped: label + hint + errors
@@ -150,9 +150,9 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | Tag | Input |
 |---|---|
 | `input_tag` | text (auto-detected type) |
-| `string_tag`, `text_tag`, `number_tag`, `email_tag`, `password_tag`, `url_tag`, `tel_tag`, `hidden_tag` | standard HTML inputs |
-| `checkbox_tag`, `select_tag`, `radio_button_tag` | standard |
-| `toggle_tag` / `switch_tag` | switch-styled boolean (`as: :toggle` / `:switch`) — the **default** for boolean columns; same behavior as a checkbox. Use `checkbox_tag` (`as: :boolean`) for a plain checkbox. |
+| `string_tag`, `text_tag`, `number_tag`, `email_tag`, `password_tag`, `url_tag`, `hidden_tag` | standard HTML inputs |
+| `checkbox_tag`, `select_tag`, `radio_button_tag`, `collection_radio_buttons_tag`, `collection_checkboxes_tag` | standard |
+| `toggle_tag` / `switch_tag` | switch-styled boolean (`as: :toggle` / `:switch`), the **default** for boolean columns; same behavior as a checkbox. Use `checkbox_tag` (`as: :boolean`) for a plain checkbox. |
 
 ### Plutonium-enhanced tags
 
@@ -164,12 +164,17 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `phone_tag` / `int_tel_input_tag` | intl-tel-input phone field |
 | `currency_tag` | Money input (number field + optional unit prefix) |
 | `uppy_tag` / `file_tag` | Uppy file upload |
+| `binary_tag` | Plain file input whose bytes go into a `binary` column |
+| `rich_text_tag` | Action Text editor (Trix, or Lexxy once installed) |
+| `list_tag` | Chip input for array values |
+| `tags_tag` | Chip input for a no_fly_list `has_tags` context |
+| `rating_tag` | Star picker (radio buttons, no JS); an optional rating gets a Clear option |
 | `secure_association_tag` | Association with policy-checked options (inline `+` add, typeahead) |
 | `belongs_to_tag` / `has_many_tag` / `has_one_tag` | Association selects |
 | `key_value_store_tag` | Key/value pairs editor |
 
 ```ruby
-render field(:published_at).wrapped { |f| f.flatpickr_tag(min_date: Date.today, enable_time: true) }
+render field(:published_at).wrapped { |f| f.flatpickr_tag }
 
 render field(:avatar).wrapped do |f|
   f.uppy_tag(allowed_file_types: %w[.jpg .png], max_file_size: 5.megabytes)
@@ -180,8 +185,8 @@ end
 
 `as: :phone` renders an [intl-tel-input](https://github.com/jackocnr/intl-tel-input) field. Forward library options two ways:
 
-- `initial_country:` — a convenient shortcut for the library's `initialCountry` (ISO2, e.g. `"gh"`). This preselects a country so the widget doesn't show *"No country selected"* and a bare local number validates.
-- `intl_options:` — any other library option, using the library's own camelCase names. Merged over the shortcut, so it wins on conflict.
+- `initial_country:`: a convenient shortcut for the library's `initialCountry` (ISO2, e.g. `"gh"`). This preselects a country so the widget doesn't show *"No country selected"* and a bare local number validates.
+- `intl_options:`: any other library option, using the library's own camelCase names. Merged over the shortcut, so it wins on conflict.
 
 ```ruby
 input :phone, as: :phone, initial_country: "gh"
@@ -207,14 +212,14 @@ The field defaults to `strictMode: true`; override it via `intl_options: {strict
 ```ruby
 input :price, as: :currency               # unit from has_cents / config / i18n
 input :price, as: :currency, unit: "£"    # a literal symbol
-input :price, as: :currency, unit: false  # no prefix — a plain number input
+input :price, as: :currency, unit: false  # no prefix, a plain number input
 ```
 
 When nothing resolves (or `unit: false`), the prefix is omitted and it's an ordinary number input.
 
-**`has_cents` fields infer it automatically** — just like the display. A bare `input :price` on a `has_cents` attribute renders the currency input with the unit read off `has_cents`; no `as: :currency` needed. Use the explicit `as: :currency` for a non-`has_cents` decimal, or to override the unit.
+**`has_cents` fields infer it automatically**: just like the display. A bare `input :price` on a `has_cents` attribute renders the currency input with the unit read off `has_cents`; no `as: :currency` needed. Use the explicit `as: :currency` for a non-`has_cents` decimal, or to override the unit.
 
-In a **wizard** step the data snapshot has no `has_cents` reflection, so there's nothing to infer from — declare `as: :currency` and pass `unit:` explicitly (`input :price, as: :currency, unit: "$"`); the review summary reads it back and formats the value as currency.
+In a **wizard** step the data snapshot has no `has_cents` reflection, so there's nothing to infer from; declare `as: :currency` and pass `unit:` explicitly (`input :price, as: :currency, unit: "$"`); the review summary reads it back and formats the value as currency.
 
 ### Password & secret fields {#password-fields}
 
@@ -222,10 +227,10 @@ In a **wizard** step the data snapshot has no `has_cents` reflection, so there's
 
 | field state | result |
 |---|---|
-| untouched (sentinel) | kept — the stored secret is left unchanged |
+| untouched (sentinel) | kept, the stored secret is left unchanged |
 | edited to a new value, then failed re-render | comes back **blank + `required`** so the user re-types it (a submitted secret is never echoed back) |
-| cleared, then failed re-render | comes back blank, **not** `required` — the clear may be intentional, so it's allowed to stand |
-| emptied | explicit clear (clear-by-blank) — the `required` guard only prevents an *accidental* blank submit |
+| cleared, then failed re-render | comes back blank, **not** `required`; the clear may be intentional, so it's allowed to stand |
+| emptied | explicit clear (clear-by-blank), the `required` guard only prevents an *accidental* blank submit |
 | typed | set as the new value |
 
 The sentinel is guarded client-side by the `password-sentinel` Stimulus controller: the first edit (a keystroke, paste, or **backspace**) wipes the whole field, so a partial edit can't corrupt the sentinel into a literal new password. New records and interaction forms (set-password, reset-password) render an honest empty field.
@@ -237,33 +242,78 @@ The sentinel is guarded client-side by the `password-sentinel` Stimulus controll
 - ends with `_password`, `_digest`, `_hash`, `_token`, `_key`, or `_salt`;
 - contains `secret`.
 
-This is a naming convenience, **not** a security guarantee — tune it per field:
+The same names are masked everywhere the value would otherwise print: the show page, table cells, the wizard summary, and grid and kanban card slots all render `••••••••` instead of the value. A `field`/`display` `as:` overrides the heuristic on those surfaces too.
+
+This is a naming convenience, **not** a security guarantee, tune it per field:
 
 ```ruby
 # Opt OUT: render the value as a normal, readable text input
-field :api_token,   as: :string      # a token the admin needs to copy
+field :api_token,   as: :string      # a token the admin needs to copy (shown on the show page and cards too)
 field :content_hash, as: :string     # a checksum, not a secret
 field :public_key,  as: :string      # *_key matches, but a public key is not secret
 
 # Opt IN: mask a secret the heuristic still misses (e.g. no telltale name)
 field :recovery_phrase, as: :password
+field :pin, as: :secret                # alias of :password
 ```
 
 > [!WARNING]
 > The heuristic is name-based and best-effort. A secret column with an unconventional name (e.g. `recovery_phrase`, `pin`) still renders its value into the page unless you set `as: :password`. Audit secret-bearing columns explicitly.
 
+### Rich text (Action Text and Lexxy) {#rich-text-fields}
+
+A `has_rich_text` field renders Action Text's own editor tag, so it gets whichever editor the app has set up: Trix by default, or [Lexxy](https://lexxy.dev) once the `lexxy` gem is in the bundle (it takes over Action Text's helpers on Rails 8.0/8.1 and registers itself as the editor on 8.2). Lexxy needs Rails 8.0.2 or later. The editor's JavaScript and CSS come from the app's bundle, as Action Text's or Lexxy's install instructions describe. The show page renders the HTML through Action Text, which sanitizes it.
+
+### Lists and tags {#list-fields}
+
+`as: :list` edits an array value (a JSON or array column) as chips. Options go on `input`:
+
+```ruby
+field :nicknames, as: :list
+input :nicknames, suggestions: %w[Basin Tub], limit: 5   # addable: false allows only suggestions
+```
+
+Removing every chip saves an empty array.
+
+[no_fly_list](https://github.com/radioactive-labs/no_fly_list) `has_tags` contexts are detected automatically. Permit them by context name (`labels`, not `labels_list`) and they render as chips on the form, the show page and the table:
+
+```ruby
+class Article < ResourceRecord
+  include NoFlyList::TaggableRecord
+  has_tags :labels, scope: :organization            # per-tenant vocabulary
+  has_tags :topics, restrict_to_existing: true, limit: 3
+end
+
+# policy
+def permitted_attributes_for_create = %i[title labels topics]
+```
+
+- The input suggests tags that already exist in the record's tag scope.
+- `restrict_to_existing` only allows picking existing tags. Plutonium doesn't decide where that vocabulary is managed: create the tags however suits the app (register the tag model as a resource, seed them, or add them in an interaction).
+- `limit` caps how many tags can be chosen.
+- Add `filter :labels, with: :tags` for a table filter.
+- The table reads tags through the context's association, so preload it (`includes(:labels)`) to avoid a query per row.
+
+### Binary columns {#binary-fields}
+
+A `binary` column renders `binary_tag`: a plain file input. The uploaded file's bytes are written to the column, and the show page and table print its size (`Binary data (12 KB)`), never the bytes.
+
+- Saving without choosing a file keeps the stored bytes. There is no control to clear the column.
+- Browsers can't refill a file input, so after a failed validation the user has to choose the file again.
+- The whole file is read into memory and stored in the row. Use Active Storage (`has_one_attached` + `:uppy`) for anything that isn't small.
+
 ### Wrapped vs unwrapped
 
-- `wrapped` — includes label, hint, and error rendering. Use for normal form fields.
-- Bare tag — just the input element. Use when you're laying out custom wrappers.
-- `wrapped(class: "...")` — pass classes to the wrapper div.
+- `wrapped`: includes label, hint, and error rendering. Use for normal form fields.
+- Bare tag, just the input element. Use when you're laying out custom wrappers.
+- `wrapped(class: "...")`: pass classes to the wrapper div.
 
 ## Association inputs (`secure_association_tag`) {#association-inputs}
 
 Association inputs render with two affordances out of the box:
 
-- **Inline `+` add** — a button next to the select opens the target resource's `:new` action. Inherits the target's modal mode. If the parent form is already in a modal, the `+` opens a **stacked secondary modal** (see [Pages › Stacked modals](./pages#stacked-modals-secondary-frame)) so the in-progress form isn't lost — on success the secondary closes and the parent reloads.
-- **Typeahead** — server-side autocomplete is on by default. Uses the target's `search` block if defined; otherwise falls back to a `LIKE` on the input's `label_method:` column or the first match from `[name, title, label, slug, display_name, email]`. See [Resource › Query › Search](/reference/resource/query#search) for the typeahead fallback details.
+- **Inline `+` add**: a button next to the select opens the target resource's `:new` action. Inherits the target's modal mode. If the parent form is already in a modal, the `+` opens a **stacked secondary modal** (see [Pages › Stacked modals](./pages#stacked-modals-secondary-frame)) so the in-progress form isn't lost; on success the secondary closes and the parent reloads.
+- **Typeahead**: server-side autocomplete is on by default. Uses the target's `search` block if defined; otherwise falls back to a `LIKE` on the input's `label_method:` column or the first match from `[name, title, label, slug, display_name, email]`. See [Resource › Query › Search](/reference/resource/query#search) for the typeahead fallback details.
 
 ```ruby
 # Opt out of the + button
@@ -280,7 +330,7 @@ input :author, label_method: :email
 ```
 
 ::: tip Large association tables
-For large target tables, write an explicit `search` block on the target resource definition — the fallback's leading-wildcard `LIKE` can't use a b-tree index.
+For large target tables, write an explicit `search` block on the target resource definition; the fallback's leading-wildcard `LIKE` can't use a b-tree index.
 :::
 
 ## Submit buttons
@@ -291,7 +341,7 @@ Control the secondary button via the definition:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  submit_and_continue false   # nil (default — auto), true (always show), false (always hide)
+  submit_and_continue false   # nil (default, auto), true (always show), false (always hide)
 end
 ```
 
@@ -313,9 +363,9 @@ end
 
 These all live in the definition layer:
 
-- **Pre-submit / dynamic forms** — see [Resource › Definition › Dynamic forms](/reference/resource/definition#dynamic-forms-pre-submit)
-- **Nested inputs** (`nested_input :variants`) — see [Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs)
-- **Interaction forms** — interactions define their own `attribute` / `input` and inherit `Plutonium::UI::Form::Interaction`; see [Behavior › Interactions](/reference/behavior/interactions)
+- **Pre-submit / dynamic forms**: see [Resource › Definition › Dynamic forms](/reference/resource/definition#dynamic-forms-pre-submit)
+- **Nested inputs** (`nested_input :variants`), see [Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs)
+- **Interaction forms**: interactions define their own `attribute` / `input` and inherit `Plutonium::UI::Form::Interaction`; see [Behavior › Interactions](/reference/behavior/interactions)
 
 ## Theming
 
@@ -342,7 +392,7 @@ end
 ```
 
 ::: 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.
 :::
 
 ### Theme keys
@@ -384,9 +434,9 @@ end
 
 ## Related
 
-- [Pages](./pages) — `NewPage` / `EditPage` page hooks
-- [Components](./components) — building reusable Phlex components for forms
-- [Assets](./assets) — `.pu-*` classes, design tokens, dark mode
-- [Resource › Definition](/reference/resource/definition) — input configuration (`as:`, `hint:`, `condition:`, blocks)
-- [Behavior › Interactions](/reference/behavior/interactions) — interaction forms (`Plutonium::UI::Form::Interaction`)
-- [Tenancy › Nested resources](/reference/tenancy/nested-resources) — parent fields hidden by URL
+- [Pages](./pages): `NewPage` / `EditPage` page hooks
+- [Components](./components): building reusable Phlex components for forms
+- [Assets](./assets): `.pu-*` classes, design tokens, dark mode
+- [Resource › Definition](/reference/resource/definition): input configuration (`as:`, `hint:`, `condition:`, blocks)
+- [Behavior › Interactions](/reference/behavior/interactions): interaction forms (`Plutonium::UI::Form::Interaction`)
+- [Tenancy › Nested resources](/reference/tenancy/nested-resources): parent fields hidden by URL

data/docs/reference/ui/index.md

@@ -4,27 +4,29 @@ Plutonium uses [Phlex](https://www.phlex.fun/) for all view components and Tailw
 
 ## Sub-pages
 
-- [Pages](./pages) — `IndexPage`, `ShowPage`, `NewPage`, `EditPage`, render hooks, custom ERB views, context detection
-- [Forms](./forms) — `Form` class, field builder, association inputs (typeahead + inline add), themes
-- [Displays](./displays) — `Display` class, custom rendering, block-form displays
-- [Tables](./tables) — `Table` class, custom rendering, search/scopes bar
-- [Components](./components) — built-in component kit, custom Phlex components, `DynaFrameContent` pattern, modals & tabs
-- [Layouts](./layouts) — shell config, ejecting chrome, custom `ResourceLayout` class
-- [Assets](./assets) — Tailwind config, Stimulus controllers, design tokens, `.pu-*` component classes, Phlexi themes
+- [Pages](./pages): `IndexPage`, `ShowPage`, `NewPage`, `EditPage`, render hooks, custom ERB views, context detection
+- [Forms](./forms): `Form` class, field builder, association inputs (typeahead + inline add), themes
+- [Displays](./displays): `Display` class, custom rendering, block-form displays
+- [Tables](./tables): `Table` class, custom rendering, search/scopes bar
+- [Components](./components): built-in component kit, custom Phlex components, `DynaFrameContent` pattern, modals & tabs
+- [Layouts](./layouts): shell config, ejecting chrome, custom `ResourceLayout` class
+- [Assets](./assets): Tailwind config, Stimulus controllers, design tokens, `.pu-*` component classes, Phlexi themes
 
 ## 🚨 Critical (applies across all sub-pages)
 
 - **Override via nested classes in the definition.** `class ShowPage < ShowPage; end`, `class Form < Form; end`. Don't replace the entire view layer.
 - **Use render hooks, not `view_template`.** `render_before_content`, `render_after_content`, `render_before_toolbar`, etc. exist so you don't reimplement the whole page.
-- **All pages inherit `DynaFrameContent`** — turbo-frame requests render only the content. Don't fight it; modals and frame nav "just work".
-- **Custom components inherit `Plutonium::UI::Component::Base`** — gives you the component kit (`PageHeader`, `Panel`, `Block`), resource helpers, and the `helpers` proxy for Rails helpers.
-- **`render_actions` is mandatory in custom `form_template`** — without it, the form has no submit button.
-- **Always `registerControllers(application)`** in `app/javascript/controllers/index.js`. Without it, Plutonium's Stimulus controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
-- **Use `plutoniumTailwindConfig.merge`** when extending Tailwind theme — plain object merge drops Plutonium's defaults.
-- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **All pages inherit `DynaFrameContent`**: turbo-frame requests render only the content. Don't fight it; modals and frame nav "just work".
+- **Custom components inherit `Plutonium::UI::Component::Base`**: gives you the component kit (`PageHeader`, `Panel`, `Block`), resource helpers, and the `helpers` proxy for Rails helpers.
+- **`render_actions` is mandatory in custom `form_template`**: without it, the form has no submit button.
+- **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 Stimulus controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
+- **Use `plutoniumTailwindConfig.merge`** when extending Tailwind theme, plain object merge drops Plutonium's defaults.
+- **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. A hand-written `bg-warning-50 dark:bg-warning-950/30` pair duplicates that, drifts from the theme, and may not even exist in the prebuilt CSS.
+- **User-facing copy goes through `t(...)` with a locale key**, in components, pages, displays and definitions alike. See [i18n](/reference/i18n).
 - **Configure inputs in the definition; render them with `render_resource_field` in the form.** Don't reimplement field widgets from scratch.
 
 ## Related
 
-- [Resource › Definition](/reference/resource/definition) — field-level rendering (`field :foo, as: :markdown`, `display :status do |f| … end`)
-- [Behavior › Controllers](/reference/behavior/controllers) — controller render-context hooks (`present_parent?`, `submit_parent?`)
+- [Resource › Definition](/reference/resource/definition): field-level rendering (`field :foo, as: :markdown`, `display :status do |f| … end`)
+- [Behavior › Controllers](/reference/behavior/controllers): controller render-context hooks (`present_parent?`, `submit_parent?`)

data/docs/reference/ui/layouts.md

@@ -1,12 +1,12 @@
 # Layouts
 
-The overall page chrome — topbar, sidebar, footer, body wrapping. Plutonium ships three shells; you can eject the templates or write a custom `ResourceLayout` for total control.
+The overall page chrome, topbar, sidebar, footer, body wrapping. Plutonium ships three shells; you can eject the templates or write a custom `ResourceLayout` for total control.
 
 ## Shell
 
 ```ruby
 Plutonium.configure do |config|
-  config.shell = :modern     # default — topbar + icon rail
+  config.shell = :modern     # default, topbar + icon rail
   # config.shell = :plain    # topbar, no icon rail (rail-less app)
   # config.shell = :classic  # legacy header + sidebar (only when upgrading)
 end
@@ -20,9 +20,9 @@ If you're starting fresh, use `:modern`. `:classic` exists so apps upgrading fro
 
 The shell variant selects the page chrome:
 
-- `:modern` (default) — Topbar plus the desktop icon rail.
-- `:plain` — Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the surface is rail-less.
-- `:classic` — legacy Header/Sidebar (upgrade paths only).
+- `:modern` (default), Topbar plus the desktop icon rail.
+- `:plain`: Topbar but **no** icon rail. The Topbar is kept; only the rail is removed, so the surface is rail-less.
+- `:classic`: legacy Header/Sidebar (upgrade paths only).
 
 ### Resolving the shell (global → engine → controller)
 
@@ -32,7 +32,7 @@ The shell resolves across three layers, each overriding the one above it:
 # 1. Global default (config/initializers/plutonium.rb)
 Plutonium.configure { |config| config.shell = :modern }
 
-# 2. Per-engine — set it on a portal engine (lib/engine.rb)
+# 2. Per-engine: set it on a portal engine (lib/engine.rb)
 module CustomerPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
@@ -43,19 +43,19 @@ module CustomerPortal
   end
 end
 
-# 3. Per-controller — overrides the engine/global default for one controller (and subclasses)
+# 3. Per-controller: overrides the engine/global default for one controller (and subclasses)
 class DashboardController < ResourceController
   shell :modern   # opt this controller back into the rail
 end
 ```
 
-`shell` takes a plain symbol, so it's safe in the class body too — but the generated engine already has a `config.after_initialize` block (where `scope_to_entity` lives), so keeping it there is the consistent home.
+`shell` takes a plain symbol, so it's safe in the class body too, but the generated engine already has a `config.after_initialize` block (where `scope_to_entity` lives), so keeping it there is the consistent home.
 
 An unset engine/controller value (`nil`) falls through to the next layer. Read the resolved value with the `shell` helper (`controller.shell`).
 
-### `rail` — a controller-level rail toggle
+### `rail`: a controller-level rail toggle
 
-Alongside `shell`, any resource controller exposes a class-level `rail` DSL that flips just the icon rail without changing the shell. It's a `class_attribute`, so it's inherited — a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern:
+Alongside `shell`, any resource controller exposes a class-level `rail` DSL that flips just the icon rail without changing the shell. It's a `class_attribute`, so it's inherited; a portal opts its entire surface in or out by calling `rail false` (or `rail true`) once in its controller concern:
 
 ```ruby
 module CustomerPortal
@@ -68,15 +68,15 @@ module CustomerPortal
 end
 ```
 
-`rail nil` (the default) inherits the resolved shell — the rail shows when the resolved `shell == :modern`. Read the resolved value with the `rail?` predicate.
+`rail nil` (the default) inherits the resolved shell, the rail shows when the resolved `shell == :modern`. Read the resolved value with the `rail?` predicate.
 
 ### Stable CSS hooks
 
 Rail-less rendering exposes a few stable hooks for custom overrides:
 
-- `pu-topbar` — class on the Topbar nav.
-- `pu-sticky-footer` — class on the form sticky-footer div.
-- `html.pu-no-rail` — root class present whenever the current page is rail-less.
+- `pu-topbar`: class on the Topbar nav.
+- `pu-sticky-footer`: class on the form sticky-footer div.
+- `html.pu-no-rail`: root class present whenever the current page is rail-less.
 
 A built-in rule cancels the desktop rail inset on `.pu-topbar` and `.pu-sticky-footer` under `html.pu-no-rail`; target these hooks to layer your own CSS.
 
@@ -87,7 +87,7 @@ rails generate pu:eject:shell --dest=admin_portal
 rails generate pu:eject:layout
 ```
 
-`pu:eject:shell` copies `_resource_header.html.erb` and `_resource_sidebar.html.erb` into the portal's `app/views/plutonium/`. The eject is independent of `shell` — you can run it on either.
+`pu:eject:shell` copies `_resource_header.html.erb` and `_resource_sidebar.html.erb` into the portal's `app/views/plutonium/`. The eject is independent of `shell`; you can run it on either.
 
 `pu:eject:layout` copies `layouts/resource.html.erb` for layout-level edits.
 
@@ -111,7 +111,7 @@ The sidebar/icon-rail navigation is built with `Phlexi::Menu::Builder` in the ej
 
 ### Per-item link attributes
 
-Any extra options you pass to `item` are spread straight onto the rendered `<a>` — so a menu entry can opt into `target`, `rel`, `data-*`, `aria-*`, etc. Useful for items that open in their own tab or drive a Stimulus/Turbo behavior:
+Any extra options you pass to `item` are spread straight onto the rendered `<a>`, so a menu entry can opt into `target`, `rel`, `data-*`, `aria-*`, etc. Useful for items that open in their own tab or drive a Stimulus/Turbo behavior:
 
 ```ruby
 m.item "Inbox",
@@ -122,7 +122,7 @@ m.item "Inbox",
   data: {turbo_frame: "_top"}
 ```
 
-This works across both shells — the `:modern` icon-rail (leaf items, parent flyout triggers, and flyout children) and the `:classic` sidebar. Framework attributes always win on conflict: a custom `class:` is **merged** with the component's base classes, and on a parent trigger your `data:` / `aria:` merge with the flyout's own wiring (so you can't accidentally break the toggle). The `:active` key is reserved by Phlexi for [custom active-state logic](https://github.com/radioactive-labs/phlexi-menu) and is never emitted as an attribute.
+This works across both shells, the `:modern` icon-rail (leaf items, parent flyout triggers, and flyout children) and the `:classic` sidebar. Framework attributes always win on conflict: a custom `class:` is **merged** with the component's base classes, and on a parent trigger your `data:` / `aria:` merge with the flyout's own wiring (so you can't accidentally break the toggle). The `:active` key is reserved by Phlexi for [custom active-state logic](https://github.com/radioactive-labs/phlexi-menu) and is never emitted as an attribute.
 
 ## Custom layout class
 
@@ -190,7 +190,7 @@ See [Assets › Tailwind config](./assets#tailwind-config) for the full merge st
 
 ## Dark mode
 
-`selector` strategy — toggle by adding/removing `dark` on `<html>`. The bundled `color-mode` Stimulus controller handles toggling; Plutonium ships a switcher.
+`selector` strategy, toggle by adding/removing `dark` on `<html>`. The bundled `color-mode` Stimulus controller handles toggling; Plutonium ships a switcher.
 
 ```javascript
 // Manual toggle if needed
@@ -199,6 +199,6 @@ document.documentElement.classList.toggle('dark')
 
 ## Related
 
-- [Assets](./assets) — Tailwind config, design tokens, `.pu-*` classes
-- [Components](./components) — custom components used in layout hooks (`AnnouncementBanner`, etc.)
-- [Pages](./pages) — page-level hooks (a lighter alternative for per-page chrome)
+- [Assets](./assets): Tailwind config, design tokens, `.pu-*` classes
+- [Components](./components): custom components used in layout hooks (`AnnouncementBanner`, etc.)
+- [Pages](./pages): page-level hooks (a lighter alternative for per-page chrome)

data/docs/reference/ui/pages.md

@@ -32,12 +32,10 @@ end
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  index_page_title       "Blog Posts"
-  index_page_description "Manage all published articles"
-  show_page_title        "Article Details"
-  show_page_title        -> { current_record!.title }   # dynamic
-  new_page_title         "Create Post"
-  edit_page_title        -> { "Edit: #{current_record!.title}" }
+  index_page_title       t("blog.posts.index.title")         # lazy: resolved per request, in its locale
+  index_page_description t("blog.posts.index.description")
+  show_page_title        "Article Details"                   # a literal also works (fixed, untranslated)
+  new_page_title         t("blog.posts.new.title")
 
   breadcrumbs              true     # global default
   index_page_breadcrumbs   false    # per-page override
@@ -48,9 +46,11 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+The class-level `t` in a definition returns a lazy proc; calling `I18n.t` directly in the class body would resolve once, at load time. A title that depends on the record belongs in a `page_title` override on the nested page class (see the hooks example below), not in a lambda here: the setter's proc is called with no record context.
+
 ## Page hooks (preferred over `view_template`)
 
-Every page inherits these — use them instead of overriding `view_template` to preserve breadcrumbs, header, and DynaFrame behavior:
+Every page inherits these, use them instead of overriding `view_template` to preserve breadcrumbs, header, and DynaFrame behavior:
 
 | Hook | Position |
 |---|---|
@@ -68,12 +68,12 @@ class ShowPage < ShowPage
   private
 
   def page_title
-    "#{object.title} — #{object.author.name}"
+    "#{object.title}, #{object.author.name}"
   end
 
   def render_before_content
-    div(class: "alert alert-info") do
-      plain "This post has #{object.comments.count} comments"
+    div(class: "pu-alert pu-alert-info", role: "status") do
+      div(class: "pu-alert-message") { t("blog.posts.show.comment_count", count: object.comments.count) }
     end
   end
 
@@ -105,7 +105,7 @@ The default view simply renders the page class:
 <%= render current_definition.show_page_class.new %>
 ```
 
-Mix — keep the default and add chrome around it:
+Mix, keep the default and add chrome around it:
 
 ```erb
 <div class="announcement-banner">Special announcement</div>
@@ -125,7 +125,7 @@ Use to pin action strips, omit nav chrome, or swap layouts.
 
 ### Stacked modals (secondary frame)
 
-Association inputs include an inline `+` button. When the parent form is itself rendered in a modal, the `+` opens a **second stacked modal** in `Plutonium::REMOTE_MODAL_SECONDARY_FRAME` instead of replacing the primary modal. On successful create, the secondary closes and the primary frame reloads so the new record appears in the select — no developer wiring.
+Association inputs include an inline `+` button. When the parent form is itself rendered in a modal, the `+` opens a **second stacked modal** in `Plutonium::REMOTE_MODAL_SECONDARY_FRAME` instead of replacing the primary modal. On successful create, the secondary closes and the primary frame reloads so the new record appears in the select, no developer wiring.
 
 For custom flows: `helpers.turbo_stream_close_frame(frame_id)` and `helpers.turbo_stream_reload_frame(frame_id)` are available.
 
@@ -133,11 +133,11 @@ See [Forms › Association inputs](./forms#association-inputs).
 
 ## Modals & slideovers
 
-The framework's `:new` / `:edit` actions and any interactive action render inline inside a modal. Choose the chrome (and optional width) per-resource via the definition — interactive actions inherit the same default:
+The framework's `:new` / `:edit` actions and any interactive action render inline inside a modal. Choose the chrome (and optional width) per-resource via the definition, interactive actions inherit the same default:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover               # default — slide-in panel from the right
+  modal :slideover               # default, slide-in panel from the right
   # modal :centered              # centered dialog
   # modal :centered, size: :lg   # centered, wider container
   # modal false                  # full standalone pages (no modal)
@@ -148,7 +148,7 @@ end
 
 ## Tabs on the show page
 
-Show pages with `permitted_associations` (see [Behavior › Policy](/reference/behavior/policies#association-permissions)) render a tablist: **Details** tab first, then one tab per association. The active tab is reflected in the URL hash (`#products`, `#refund-requests`) so the page deep-links and the active state survives reload / back navigation. Tab rows scroll horizontally on narrow viewports — they don't wrap.
+Show pages with `permitted_associations` (see [Behavior › Policy](/reference/behavior/policies#association-permissions)) render a tablist: **Details** tab first, then one tab per association. The active tab is reflected in the URL hash (`#products`, `#refund-requests`) so the page deep-links and the active state survives reload / back navigation. Tab rows scroll horizontally on narrow viewports, they don't wrap.
 
 If the policy permits **no fields**, the empty Details tab is dropped and the first association tab leads instead.
 
@@ -169,7 +169,7 @@ end
 
 ## Available context
 
-Inside any page / form / display / Phlex component, the same set of helpers is available — model accessors, definition/policy methods, URL helpers, `current_user`. For the full list, see [Behavior › Controllers › Key methods](/reference/behavior/controllers#key-methods) — pages inherit the same surface.
+Inside any page / form / display / Phlex component, the same set of helpers is available (model accessors, definition/policy methods, URL helpers, `current_user`; for the full list, see [Behavior › Controllers › Key methods](/reference/behavior/controllers#key-methods)). Pages inherit the same surface.
 
 In Phlex components, Rails helpers are accessed via the `helpers` proxy:
 
@@ -184,9 +184,9 @@ end
 
 ## Related
 
-- [Forms](./forms) — Form class, field builder, themes
-- [Displays](./displays) — show-page Display class
-- [Tables](./tables) — index-page Table class
-- [Components](./components) — built-in component kit, custom Phlex components, DynaFrame
-- [Layouts](./layouts) — overall shell, eject, ResourceLayout
-- [Resource › Definition](/reference/resource/definition) — page titles, breadcrumbs, modal mode, metadata panel
+- [Forms](./forms): Form class, field builder, themes
+- [Displays](./displays): show-page Display class
+- [Tables](./tables): index-page Table class
+- [Components](./components): built-in component kit, custom Phlex components, DynaFrame
+- [Layouts](./layouts): overall shell, eject, ResourceLayout
+- [Resource › Definition](/reference/resource/definition): page titles, breadcrumbs, modal mode, metadata panel

data/docs/reference/ui/tables.md

@@ -52,11 +52,11 @@ class PostDefinition < ResourceDefinition
   column :status, align: :center
   column :amount, align: :end
 
-  # formatter — receives just the value
+  # formatter, receives just the value
   column :description, formatter: ->(value) { value&.truncate(30) }
   column :price,       formatter: ->(value) { "$%.2f" % value if value }
 
-  # block — receives the full record
+  # block, receives the full record
   column :full_name do |record|
     "#{record.first_name} #{record.last_name}"
   end
@@ -67,7 +67,7 @@ See [Resource › Definition › Column options](/reference/resource/definition#
 
 ## Grid view
 
-For card-based layouts as a switchable alternative to the table, use the built-in Grid view — declare `grid_fields` in the definition:
+For card-based layouts as a switchable alternative to the table, use the built-in Grid view, declare `grid_fields` in the definition:
 
 ```ruby
 class UserDefinition < ResourceDefinition
@@ -115,7 +115,7 @@ end
 
 ## Related
 
-- [Pages](./pages) — `IndexPage` render hooks (a lighter alternative for top/bottom chrome)
-- [Components](./components) — `PostCardComponent` and other reusable Phlex pieces
-- [Resource › Definition](/reference/resource/definition) — column configuration, grid view
-- [Resource › Query](/reference/resource/query) — search, filters, scopes, sort
+- [Pages](./pages): `IndexPage` render hooks (a lighter alternative for top/bottom chrome)
+- [Components](./components): `PostCardComponent` and other reusable Phlex pieces
+- [Resource › Definition](/reference/resource/definition): column configuration, grid view
+- [Resource › Query](/reference/resource/query): search, filters, scopes, sort