plutonium 0.64.0 → 0.65.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6abf981b5e375a2c576de8bfe5fe6448b115753356b6c91f1c3b0ae946e66935
-  data.tar.gz: b519f55b96e20f592baab81b34a633de562dcd8060dbe2bf65cbff7342ae76dd
+  metadata.gz: '008433e7fc21f308028d5d047ddfa2c01c26efe13258f8af39ca99b7b72f0e0d'
+  data.tar.gz: d3c4ecbec9fd85ee133c4e0bd4b28fcf4fcc66ee632e0b5ea84d277fa00316a1
 SHA512:
-  metadata.gz: cbf194184d5d16439031b3802f5fc7b05b7f22b24a2075cac2d03a5e6869160f5332ea6cc4d83d3a580169db7405266435e5f9b7f4f1b42befd334a93a470f53
-  data.tar.gz: ec740ece535648156d103872cb0362347b6b2f2823d425aa0b94134f336a32355c807f767d05a673f173670fb1efd572c42240542b48b44f0ab5dc8b23ed63cc
+  metadata.gz: cc40c769d7dc3b30e2f5a2cd88aeb07d41c52bb37f1e28fb6946c88705d1dfb04adf19c19cdbc2889d4356f722a4d5705b4f0b3e1142ba3b58dbe9c9cbb8f30e
+  data.tar.gz: 0a772b07eee9784de0012559814134515a3fb228f9b9bf51a75b94f4161a5b05d913434a24cbb7991fdc0722f415a69b87f725990603ed7557af5b1afdd0205b

data/.claude/skills/plutonium/SKILL.md

@@ -53,7 +53,7 @@ Not "defaults someone picked for you" — **computed from existing declarations*
 ### 4. Climb the escape-hatch ladder only as far as the problem requires
 
 1. **Change an option** — `input :content, as: :markdown`
-2. **Render inline** — `display :priority, as: :phlexi_render, with: ->(value, attrs) do … end`
+2. **Render inline** — `display :priority do |f| … end` (a block, `instance_exec`ed in Phlex, emits markup directly and gives you `f.object`)
 3. **Write a component** — a *field* component (subclasses the Phlexi base) plugs into `as:`; anything with its own constructor goes through a block (`display :card do |field| … end`)
 4. **Implement a hook** — controller hooks instead of reopening `create`/`update`; page `render_before_*` / `render_after_*` instead of `view_template`
 5. **Replace the page** — `view_template` on the nested class, or an ERB view at the controller path (ERB wins when both exist)
@@ -85,6 +85,7 @@ This is the global "look before you leap"; each targeted skill carries its own A
 | **[[plutonium-async-interactions]]** | Async interactions — `async`, the Run STI model, failure policies (`halt`/`continue`/`transactional`), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), scheduling `ReapJob` |
 | **[[plutonium-ui]]** | Page classes, forms, displays, tables, custom Phlex components, layouts, modals & tabs, Tailwind config, Stimulus, design tokens, `.pu-*` classes, Phlexi themes |
 | **[[plutonium-kanban]]** | `kanban do…end` DSL in a Definition — columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy, quick-add, static vs dynamic boards |
+| **[[plutonium-dashboard]]** | Dashboards — `Plutonium::Dashboard::Base`, `metric` / `chart` / `card`, `register_dashboard`, lazy turbo-frame cards, `refresh`, `condition:`, `authorize?`, `pu:dashboard` |
 | **[[plutonium-auth]]** | Rodauth install, account types (basic / admin / SaaS), profile resource, security section |
 | **[[plutonium-tenancy]]** | Entity scoping (`associated_with`, `default_relation_scope`, three model shapes), nested resources, invites |
 | **[[plutonium-testing]]** | `pu:test:install`, `pu:test:scaffold`, `ResourceCrud`/`ResourcePolicy`/`ResourceDefinition`/`ResourceModel`/`NestedResource`/`PortalAccess`/`ResourceInteraction`, `AuthHelpers` |
@@ -122,6 +123,7 @@ Add when relevant:
 | Configure parent/child nested routes, custom parent resolution | **[[plutonium-tenancy]]** |
 | Set up user invitations or entity membership | **[[plutonium-tenancy]]** |
 | Build or customize a kanban board view — `kanban do…end`, columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy | **[[plutonium-kanban]]** |
+| Build a dashboard, KPI overview or chart page — `pu:dashboard`, `metric` / `chart` / `card`, `register_dashboard`, refresh, per-card conditions | **[[plutonium-dashboard]]** |
 | Build a custom page (override `ShowPage`/`IndexPage`/`NewPage`/`EditPage`), custom form, custom display, custom table, custom Phlex component | **[[plutonium-ui]]** |
 | Configure Tailwind, register Stimulus controllers, edit design tokens, theme forms/displays/tables, write a custom layout | **[[plutonium-ui]]** |
 | Install Rodauth, set up accounts, configure login flow, add the profile resource | **[[plutonium-auth]]** |
@@ -169,6 +171,7 @@ Every Plutonium generator is discoverable via `rails g pu:<tab>`. Always pass `-
 | `pu:eject:shell` | Eject topbar/sidebar partials | `plutonium-ui` |
 | `pu:test:install` | Install `Plutonium::Testing` scaffolding | `plutonium-testing` |
 | `pu:test:scaffold NAME --portals=...` | Scaffold integration tests | `plutonium-testing` |
+| `pu:dashboard NAME --dest=PORTAL [--at=/]` | Dashboard class + `register_dashboard` route | `plutonium-dashboard` |
 | `pu:skills:sync` | Sync Plutonium Claude skills into the project | (this skill) |
 
 ## Unattended execution

data/.claude/skills/plutonium-app/SKILL.md

@@ -263,6 +263,16 @@ end
 
 This is loaded from `config/application.rb`. Migrations from all packages are picked up by `rails db:migrate` automatically.
 
+## Locale files
+
+Packages and portals are Rails engines, so `packages/<name>/config/locales/*.yml` loads automatically, ahead of the app's own `config/locales` (app wins, then packages, then the gem's defaults). Both generators scaffold `config/locales/en.yml`.
+
+- Feature package: model/attribute names (`activerecord.models`, `activerecord.attributes`) and field text (`plutonium.fields.<model>.<attr>.{placeholder,hint,description}`).
+- Portal: portal-specific wording under `plutonium.portals.<portal_namespace>.…` (same tree as the global keys: `fields`, `actions`, `scopes`, `filters`, `kanban_columns`, `values`). Wins over the global key only inside that portal.
+- Any of Plutonium's own strings (`plutonium.*` in the gem's `config/locales/en/*.yml`) can be overridden from either place. Pagination text comes from Pagy's dictionaries instead.
+
+Switch locale with a normal Rails `around_action` in the portal's controller concern; Plutonium reads `I18n.locale` and never sets it. See `docs/reference/i18n.md`.
+
 ## When to use which
 
 **Feature packages** — domain logic that:
@@ -475,6 +485,10 @@ Use the `--singular` flag on `pu:res:conn`:
 rails g pu:res:conn Profile --dest=customer_portal --singular
 ```
 
+## Dashboards
+
+`register_dashboard SomeDashboard, at: "overview"` mounts a `Plutonium::Dashboard::Base` subclass (metric / chart / free-form cards, each in its own lazy turbo frame) on the portal at `/dashboards/overview`; `at: "/"` (generator: `--at=/`) makes it the portal root in place of `root to: "dashboard#index"`; delete the generated `DashboardController` and view afterwards. Generate one with `rails g pu:dashboard Overview --dest=<portal>`. See [[plutonium-dashboard]].
+
 ## Custom member / collection routes
 
 ```ruby

data/.claude/skills/plutonium-dashboard/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: plutonium-dashboard
+description: Use BEFORE building a dashboard, KPI page, metrics overview or chart page in a Plutonium app — Plutonium::Dashboard::Base, the metric / chart / card DSL, register_dashboard, lazy turbo-frame cards, refresh, conditions, authorize?, and the pu:dashboard generator. The single source for "how do I add a dashboard with metric cards and charts".
+---
+
+# Plutonium Dashboards
+
+A dashboard is a class of cards (`metric`, `chart`, `card`) mounted in a portal with one routes line. Every card loads in its own lazy turbo frame, so the page paints at once and each card's queries run in a separate request. Charts render with Chart.js through Chartkick, styled by Plutonium's design tokens.
+
+For resources and their definitions see [[plutonium-resource]]; for portals and routes see [[plutonium-app]]; for custom Phlex markup inside a card see [[plutonium-ui]].
+
+## 🚨 Critical (read first)
+
+- **Experimental.** The DSL and behavior may change in a future release, the same status as [[plutonium-wizard]], [[plutonium-kanban]] and [[plutonium-async-interactions]]. Fine to build on; expect to follow the changelog.
+- **Generate, don't hand-write:** `rails g pu:dashboard Sales --dest=admin_portal` writes the class AND the `register_dashboard` line.
+- **Replacing the portal's default page:** `rails g pu:dashboard Home --dest=admin_portal --at=/` mounts it at the portal root and replaces the generated `root to: "dashboard#index"` line (two roots clash). It does NOT delete the generated `DashboardController` + `dashboard/index.html.erb`; delete them, nothing routes there any more. The sidebar Home link then opens the dashboard, and it is left out of the Dashboards group.
+- **Dashboards live in `app/dashboards/`** (`packages/<portal>/app/dashboards/<portal>/` in a package). Class name ends in `Dashboard`; the label drops the suffix.
+- **Card blocks run on the dashboard instance**, not the controller: use `current_user`, `current_scoped_entity`, `authorized_resource_scope(Model)`, `resource_url_for`, `helpers`, and the dashboard's own private methods. Scope queries with `authorized_resource_scope`, never `Model.all`, on a multi-tenant portal.
+- **Root-qualify packaged models inside a portal dashboard.** Within `module AdminPortal`, `Blogging::Post` resolves to the portal's own `AdminPortal::Blogging` controller namespace and raises `NameError`; write `::Blogging::Post`.
+- **`metric` and `chart` blocks return data; `card` blocks render Phlex markup.** A `card` block is `instance_exec`ed in a Phlex component: `div`, `ul`, `render` work, and unknown methods forward to the dashboard.
+- **`condition:` gates the card endpoint too** (404 when false), unlike a field `condition:`. Page-level access is `authorize?` on the dashboard (403).
+- **`refresh:` needs `lazy: true`** (the default). It reloads the frame; an inline card has no frame. `refresh: false` opts a lazy card out of the dashboard's `refresh`.
+- **Chart options other than `type:` / `height:` pass straight to Chartkick.** Unknown metric options raise.
+- **Ejected sidebars don't list dashboards automatically.** Portals generated before this feature have their own `_resource_sidebar.html.erb`; add the `registered_dashboards` block (below), which groups them under a "Dashboards" parent after the Home link (`plutonium.resource.nav.home`).
+
+## Minimal dashboard
+
+```ruby
+# packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", description: "Orders and revenue", icon: Phlex::TablerIcons::ChartBar
+    refresh 60       # seconds, every lazy card (default off)
+
+    metric(:orders, icon: Phlex::TablerIcons::ShoppingCart, href: -> { resource_url_for(Order, parent: nil) }) do
+      {value: orders.where(created_at: 30.days.ago..).count,
+       previous: orders.where(created_at: 60.days.ago...30.days.ago).count,
+       change_label: "vs. previous 30 days"}
+    end
+    metric(:revenue, format: :currency) { orders.sum(:total) }
+    metric(:refund_rate, format: :percentage, precision: 1, positive: :down) { {value: 2.1, previous: 1.8} }
+
+    chart(:revenue_by_day, type: :area, span: 8) { orders.group_by_day(:created_at, last: 30).sum(:total) }
+    chart(:by_channel, type: :donut, span: 4) { orders.group(:channel).count }
+
+    card(:latest, span: :full) do
+      ul { latest_orders.each { |o| li { o.number } } }
+    end
+
+    def authorize? = current_user.admin?   # optional; default true
+
+    private
+
+    def orders = authorized_resource_scope(Order)
+    def latest_orders = orders.order(created_at: :desc).limit(5)
+  end
+end
+
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"   # GET /admin/dashboards/sales, /admin/dashboards/sales/cards/:card
+end
+```
+
+## Card options (all kinds)
+
+| Option | Meaning |
+|---|---|
+| `label:` / `description:` | Text; default from `plutonium.dashboards.<key>.cards.<card>.label`, then the key titleized |
+| `icon:` | `Phlex::TablerIcons::*` class |
+| `span:` | `1`..`12` of a 12-column grid, or `:full` (= 12). Default: metric `3`, chart `6`, card `6`. There is no `columns` macro. Tablet: span >= 6 takes the row, else one of two columns |
+| `lazy:` | `true` (own turbo frame, default) / `false` (inline) |
+| `refresh:` | seconds, overrides the dashboard's; `false` opts this card out of the dashboard's `refresh` |
+| `condition:` | proc (on the instance) or symbol (dashboard method); false hides + 404s |
+| `href:` | path or proc; links the title |
+
+## metric
+
+Return a value, or a hash: `value` (required), `previous` (computes % change), `change` (numeric percentage points or a verbatim string), `trend` (`:up`/`:down`/`:flat`, inferred), `change_label`.
+
+Options: `format:` (`:number` default, `:currency`, `:percentage`, `:human`, or `->(v) { ... }`), `precision:`, `unit:` (currency symbol), `prefix:`, `suffix:`, `positive:` (`:up` default, `:down` when falling is good), `change_label:`.
+
+## chart
+
+Return Chartkick data: `{label => value}`, `[[label, value], ...]`, or `[{name:, data:}, ...]`. Date/Time keys draw a time axis. `groupdate` (`group_by_day` etc.) is the natural companion; it is not a dependency.
+
+`type:` `:line` (default), `:area`, `:column`, `:bar`, `:pie`, `:donut`, `:scatter`. `height:` default `"240px"`. Everything else (`colors:`, `stacked:`, `min:`, `max:`, `suffix:`, `xtitle:`, `legend:`, `library:` ...) goes to Chartkick. Colours default to `--pu-chart-1..8`; charts redraw on colour-mode change.
+
+## card
+
+```ruby
+card(:onboarding, span: 4) do
+  Plutonium::Wizard.in_progress_for(view_context).each do |entry|
+    a(href: entry.resume_url, class: "block py-1") { entry.label }
+  end
+end
+```
+
+## Registration
+
+```ruby
+register_dashboard HomeDashboard, at: "/"                       # root: replaces `root to: "dashboard#index"`
+register_dashboard SalesDashboard, at: "sales"                  # /dashboards/sales, sales_dashboard_path
+register_dashboard Reports::WeeklyDashboard, at: "reports/weekly", as: "weekly"
+```
+
+- Synthesizes `<Portal>::DashboardsController < <Portal>::PlutoniumController` (auth, tenancy, layout inherited). Define that class yourself, including `Plutonium::Dashboard::Controller`, to customize.
+- Entity-scoped portals: URLs carry the scope segment; use `dashboard_path_for(Klass)` rather than a hand-built helper.
+- Every non-root mount is drawn under `dashboards/` (`at: "sales"` → `/admin/dashboards/sales`), so it cannot collide with a resource route. Helper names carry no prefix. `prefix: nil` mounts at the bare path (`/admin/sales`, keeping it clear of resource routes is then on you); `prefix: "reports"` swaps the segment.
+- Lazy vs inline: see the table below.
+- Errors in a card: raised in development/test. In production the card is replaced by a notice, and the error is logged and reported via `Rails.error` (`source: "plutonium.dashboard"`, `context: {dashboard:, card:}`).
+
+## Lazy vs inline (`lazy: false`)
+
+| | `lazy: true` (default) | `lazy: false` (inline) |
+|---|---|---|
+| Where the block runs | In its own request to `<mount>/cards/<key>`, when the frame scrolls into view | In the page request, before the page is sent |
+| What the page response holds | A `<turbo-frame loading="lazy">` with a skeleton | The finished card; no frame, no skeleton, no second request |
+| Cost | One extra request per card; the page itself never waits | The page waits for the block, so every inline card adds its query time to the page |
+| `refresh` | Reloads on the card's or the dashboard's interval | Never refreshes. A number raises `ArgumentError`; the dashboard's `refresh` skips it |
+| `condition:` false | Left out of the page, block never runs, endpoint is 404 | The same |
+| Raises in production | Notice in place of the body, logged and reported | The same; the rest of the page still renders |
+| Raises in development and test | That card's frame request fails; the page and the other cards are fine | The whole page raises, because the card is part of the page |
+
+Default to lazy. Use `lazy: false` only for a cheap value (cached number, indexed count) near the top of the page; one slow inline card delays the whole page.
+
+## Sidebar (ejected partial)
+
+```erb
+dashboards = registered_dashboards.reject { |dashboard| dashboard_path_for(dashboard) == root_path }
+if dashboards.any?
+  m.item t("plutonium.resource.nav.dashboards"), icon: Phlex::TablerIcons::LayoutDashboard do |n|
+    dashboards.each do |dashboard|
+      n.item dashboard.label, url: dashboard_path_for(dashboard), icon: dashboard.icon
+    end
+  end
+end
+```
+
+## Translations
+
+```yaml
+en:
+  plutonium:
+    dashboards:
+      admin_portal/sales:            # Class.i18n_key
+        label: "Sales"
+        cards:
+          orders: { label: "Orders", description: "Last 30 days" }
+```
+
+Portal override: `plutonium.portals.<portal>.dashboards...`.
+
+## Testing
+
+Integration-test the page (`get "/admin/dashboards/sales"`, expect one `<turbo-frame ... loading="lazy">` per card) and each card endpoint with the frame header: `get "/admin/dashboards/sales/cards/orders", headers: {"Turbo-Frame" => "pu-dashboard-card-orders"}`. Hidden cards are `:not_found`; a denied `authorize?` is `:forbidden`.
+
+## Full docs
+
+- Guide: `/guides/dashboards`
+- Reference: `/reference/dashboard/dsl`, `/reference/dashboard/registration`

data/.claude/skills/plutonium-resource/SKILL.md

@@ -495,7 +495,7 @@ end
 |--------|-----------|----------|
 | `field` | Forms + Show + Table | Universal type override |
 | `input` | Forms only | Form-specific options |
-| `display` | Show page only | Display-specific options |
+| `display` | Show page, and the table unless a `column` renders | Display-specific options |
 | `column` | Table only | Table-specific options |
 
 ```ruby
@@ -507,6 +507,17 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+⚠️ **A component option (`colors:`, `unit:`, `true_label:`, `formatter:`, …) must be declared on the surface that renders it (`input`, `display`, or `column`), not on `field`.** A component reads its attributes from the surface declaration. Options on `field` go to the Phlexi field builder instead, which consumes the field-level keys (`:label`, `:description`/`:hint`, `:placeholder`) and ignores the rest. So `field :status, as: :badge, colors: {...}` renders a badge everywhere but silently ignores `colors:` and falls back to auto-coloring. `field` is still the right place for the shared `as:` type and for label/description/placeholder.
+
+Where to put a component option:
+
+- **`display` covers show AND index.** With no `column` declared, the table column inherits the display's `as:` and attributes, so `display :status, as: :badge, colors: {...}` alone colors the badge on both the show page and the table.
+- **A `column` that renders, renders alone.** A `column` with an `as:`, a component attribute, or a block replaces the display for the table: its own `as:` and attributes only, even when the type matches. A `column` that only sets `align:`, `label:` or `condition:` keeps the display's rendering, so `column :status, align: :center` under `display :status, as: :badge, colors: {...}` is still a colored badge.
+- **`align:` and `label:` can live on `field`.** They configure the column header, not the cell, so `field :amount, align: :end` works and never leaks into a component.
+- Use `input` for the form.
+
+The field-level help keys (`:label`, `:description`, `:hint`, `:placeholder`) are always stripped before a component sees them, so they never leak as HTML attributes wherever you put them. Other unknown keys are not stripped: a stray option on a surface whose component does not consume it still renders as a raw HTML attribute.
+
 ## Separation of Concerns
 
 | Layer | Purpose | Example |
@@ -592,6 +603,13 @@ input :team_members do |f|
 end
 ```
 
+⚠️ **Don't bind a form field to a bare association name for a multi-select** (say `input :tags` / permit `:tags`). This is by design: param extraction excludes association writers (`submitted_resource_params` keeps a key only when `reflect_on_association(k).nil?`) because `tags=` expects model instances, not param strings, so a bare `tags` param is dropped rather than mis-assigned. Bind to a non-association writer instead:
+
+- `input :tag_ids` uses Rails' collection-ids setter. Permit `:tag_ids`; values are plain ids. Simplest for a scoped checkbox list.
+- `input :tags, as: :secure_association` is the native picker. It sets input_param `tag_sgids`, scopes via `choices:` (or the target policy), and validates submitted SGIDs by decoded model-id.
+
+⚠️ Do **not** hand-roll `collection_checkboxes_tag(choices: [[label, record.to_sgid.to_s]])`. SGIDs are non-deterministic (`to_sgid` embeds a timestamp), the component re-derives `choices` at submit and intersects the posted value against the freshly-minted SGIDs, so it never matches and the value is dropped. Use stable ids in custom checkboxes, or `secure_association` (which validates by model-id).
+
 ## Conditional Rendering
 
 ```ruby
@@ -602,6 +620,8 @@ field :debug_info, condition: -> { Rails.env.development? }
 
 Use `condition` for UI state; use the policy for authorization.
 
+A surface's own `condition:` wins; otherwise the surface falls back to the `field` condition. So a `field` condition runs on the form, the show page AND the table. **The table has no `object`**, so a `field` condition must not reference the record: `-> { object.published? }` works on the form and show page and raises on the index. Keep a `field` condition to context that exists everywhere (`Rails.env`, a feature flag, `current_user`) and put record checks on `input`/`display`/`column`.
+
 ## Options That Vary Per Render
 
 Any option may be a **proc**, resolved on every render rather than frozen at class load. Holds across the whole form DSL — `field`, `input`, `section`/`ungrouped`, `structured_input`, nested inputs. Arity says **whether you want the form**:
@@ -626,6 +646,38 @@ step    :billing,   condition: -> { data.plan.tier == "pro" }  # the wizard —
 
 It cannot take a `form` argument the way an option does: for a `column`/`display`, a step, or an action there is no form.
 
+## Internationalization (labels, placeholders, hints)
+
+**Never hard-code display text a locale file can supply.** Labels come from `activerecord.attributes.<model>.<attr>` already. Placeholders, hints and descriptions are looked up by convention when the definition leaves them blank, so the translatable default is to declare nothing:
+
+```yaml
+en:
+  plutonium:
+    fields:
+      blogging/post:
+        title: { placeholder: "A short, descriptive title", hint: "Shown in search" }
+        body:  { description: "Rendered as Markdown" }
+    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" } }
+    values:         { blogging/post: { status: { archived: "Archived" } } }   # or activerecord.attributes.<model>.status/archived
+```
+
+Resolution for every slot: explicit option → `plutonium.portals.<portal>.…` → `plutonium.…` → (placeholder only) `helpers.placeholder.<model>.<attr>` → nothing. For actions, an interaction's explicit `presents label:` counts as declared (beats the convention); its class-name default does not. The model segment is `model_name.i18n_key` (`blogging/post`), walked up STI ancestors.
+
+When an explicit value must be translated, use the definition's class-level `t`, which is lazy (resolved per render, in the request locale):
+
+```ruby
+input  :email,   placeholder: t("forms.shared.email_placeholder")
+action :publish, label: t("plutonium.actions.blogging/post.publish")
+```
+
+🚨 Never `I18n.t(...)` in a class body: it freezes the string in whatever locale was active at load. Use `t(...)` or a `-> { I18n.t(...) }` proc.
+
+Full reference: `docs/reference/i18n.md`.
+
 ## Dynamic Forms (`pre_submit`)
 
 A `pre_submit: true` field triggers a server re-render on change, re-evaluating `condition:` procs. Use for cascading or context-dependent forms.
@@ -684,22 +736,30 @@ input :birth_date do |f|
 end
 ```
 
-**`phlexi_render` for declarative custom display.** The `with:` option takes either a Phlex component class, or a proc whose body is **rendered inside a Phlex context** — so HTML tags (`span`, `div`, `a`, …) and Tailwind classes are first-class. The proc receives `(value, attrs)` where `value` is the field value and `attrs` are wrapper attributes.
+**Custom display: use the block form.** `display :x do |f| … end` is `instance_exec`ed in the display component's Phlex context (`render instance_exec(f, &block)`), so you emit markup directly, it runs **once** (no per-item loop), and `f.object` is the real record:
 
 ```ruby
-# Component class — preferred for anything reusable
-display :status, as: :phlexi_render, with: StatusBadgeComponent
+# Inline markup. span/div are Phlex tag methods here.
+display :priority do |f|
+  variant = {"high" => "danger", "medium" => "warning"}.fetch(f.value.to_s, "info")
+  span(class: "pu-badge pu-badge-#{variant}") { f.value.to_s.humanize }
+end
 
-# Inline Phlex proc — `span` here is a Phlex tag method, not Ruby/Rails
-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" }
+# Reaches the record, renders once even for a has_many
+display :tags do |f|
+  div(class: "flex flex-wrap gap-1.5") do
+    f.object.tags.each { |t| span(class: "pu-badge") { t.name } }
   end
-}
+end
+
+# Reusable markup: hand the block a component
+display :card do |f|
+  PostCardComponent.new(post: f.object)
+end
 ```
 
+> ⚠️ **`as: :phlexi_render, with:` is deprecated. Use the block form above.** It emits a deprecation warning and will be removed. It was strictly worse than the block form: the `with:` proc is `.call`ed with `self` set to the definition (so `span`/`div` in its body raise, and it must instead *return* a component or proc), its `value` arrives stringified (`DisplaysValue#normalize_value` runs `to_s`, so it never reaches the record), and for a `has_many`/`multiple?` field it fires once per element. The deprecation covers only the `as: :phlexi_render` display option. The internal `phlexi_render` helper is unaffected.
+
 See [[plutonium-ui]] for writing custom Phlex components.
 
 **Custom component classes** (Phlex components — see [[plutonium-ui]]). `as:` takes a **field component**, constructed as `YourComponent.new(field, **attributes)` — subclass `Phlexi::Form::Components::Base` (inputs) or `Phlexi::Display::Components::Base` (displays) and read the value off `field`:
@@ -732,6 +792,26 @@ column :full_name do |record|
 end
 ```
 
+**A `column` block runs in a Phlex context** (like a `display` block), so it can emit `span`/`div` directly, or return a String or a component. The block receives the record.
+
+```ruby
+column :status do |record|             # emit markup directly
+  span(class: "pu-badge") { record.status.humanize }
+end
+
+column :full_name do |record|          # or return a String, rendered as text
+  "#{record.first_name} #{record.last_name}"
+end
+
+column :card do |record|               # or return a component
+  StatusBadgeComponent.new(value: record.status)
+end
+
+column :status, as: :badge, colors: {...}   # or just declare the type, no block
+```
+
+Inside the block `self` is the table page (the same as a `display` block, where `self` is the show page): `current_user`, `helpers` and `resource_definition` work, methods defined on the definition class do not, so reach through the record you are passed. A block that emits markup must end with a tag call (or `nil`), because Phlex renders the return value too; a number or other scalar return renders as text. Most of the time you need no column block at all, because `display :x, as: …` already flows to the table column (type and attributes). Declare it once on `display` and reach for `column` only to override per-table.
+
 ## Nested Inputs
 
 Inline forms for associated records. Requires `accepts_nested_attributes_for` on the model.
@@ -926,14 +1006,14 @@ end
 - **Options**: `label:`, `description:`, `collapsible:`, `collapsed:`, `columns:` (positive Integer, literal only), `condition:`. Every option except `columns:` may be a **proc**, resolved at render under the same arity rule as any other option — take a `form` argument to read the render context.
 - ⚠️ **Breaking in 0.63**: section options used to take a zero-arg proc run *against* the form. They now follow the shared rule, and a `form_layout` block is evaluated against the layout builder, so a bare `object` is a `NameError`. Migrate `collapsed: -> { object.persisted? }` → `collapsed: ->(form) { form.object.persisted? }`. `condition:` is unchanged (still form-evaluated, still reads `object` with no argument).
 - **Absent fields are skipped.** A key the section lists that isn't in the permitted set (policy, per-action, scoping, nesting, or a typo) is silently dropped — never an error. The same layout serves a richly-permitted `edit` and a minimal `new`.
-- **🚨 Zero-field sections drop entirely** — no heading, no grid. So `+ New` (fewer permitted attributes) won't sprout empty headings. This checks *field presence only*; per-field `condition:` runs later, so to hide a whole section by state, gate it with the **section's own `condition:`**, not by hiding every field inside it.
+- **🚨 Zero-field sections drop entirely** — no heading, no grid. So `+ New` (fewer permitted attributes) won't sprout empty headings. A section whose fields are **all** hidden by their own `condition:` on this render drops too (the hidden fields are still recorded on the form). A section's own `condition:` hides it as a unit regardless of its fields.
 - **Works on interactions too** (`Plutonium::Interaction::Base`) — groups `attribute` declarations. There `object` is the interaction instance; for record actions the record is `object.resource`.
 
 Full DSL reference: [Resource › Definition › Form layout](/reference/resource/definition#form-layout).
 
 ## Display Layout (`display_layout`)
 
-The show page's counterpart to `form_layout`. Same DSL, same resolution (first-section-wins, unlisted permitted fields fall into `ungrouped`, absent fields skipped, zero-field sections dropped) — applied to the show page's fields instead of the form's.
+The show page's counterpart to `form_layout`. Same DSL, same resolution (first-section-wins, unlisted permitted fields fall into `ungrouped`, absent fields skipped, zero-field and all-condition-hidden sections dropped) — applied to the show page's fields instead of the form's.
 
 ```ruby
 class PostDefinition < ResourceDefinition
@@ -1138,7 +1218,7 @@ action :reposition, hidden: true # route + policy predicate, no button
 - **`scope:` is the model author's job.** A globally positioned model rendered under a parent still reorders correctly per parent — but a rebalance renumbers every row in the table, not just that parent's.
 - Native HTML5 drag doesn't fire on **touch** devices (same limitation as kanban). Keyboard works: focus the grip, <kbd>↑</kbd>/<kbd>↓</kbd>.
 
-Full reference: `docs/reference/positioning.md`. Kanban specifics: `docs/reference/kanban/positioning.md`.
+Full reference: `docs/reference/resource/positioning.md`. Kanban specifics: `docs/reference/kanban/positioning.md`.
 
 ---
 

data/.claude/skills/plutonium-ui/SKILL.md

@@ -500,7 +500,7 @@ The URL template is built off `current_page_path` (not `request.path`) so a post
 
 **Accessibility.** Focus the grip and use <kbd>↑</kbd>/<kbd>↓</kbd> — deliberately linear even on a wrapped grid, since one position attribute stores a 1-D order. Focus is restored onto the same record's grip after a stream replaces the collection. ⚠️ Native HTML5 drag does **not** fire on touch devices (inherited from kanban); there is no automatic fallback.
 
-Components: `lib/plutonium/ui/table/components/drag_handle.rb`, `lib/plutonium/ui/component/positionable.rb`, `src/js/controllers/positioned_controller.js`. Reference: `docs/reference/positioning.md`.
+Components: `lib/plutonium/ui/table/components/drag_handle.rb`, `lib/plutonium/ui/component/positionable.rb`, `src/js/controllers/positioned_controller.js`. Reference: `docs/reference/resource/positioning.md`.
 
 ---
 
@@ -548,6 +548,21 @@ Avatar(src: avatar_url)           # bare image, no subject/fallback
 
 🚨 Ejected shells: `Avatar` only shows a Navii avatar when `NavUser` is passed `record:`. The gem's `_resource_header.html.erb` passes `record: (current_user if current_user.respond_to?(:id))`; portals that **ejected** the header before this must re-eject (`rails g pu:eject:shell --dest=<portal>`) or add the `record:` line, otherwise they keep the icon fallback. Pass a record only — a String `current_user` (e.g. a guest) would otherwise be seeded as a literal identity.
 
+## Translating component text
+
+Every `Plutonium::UI::Component::Base` subclass (pages included) has a protected `t(key, **opts)` that reads Rails I18n with a full key; components that subclass Phlexi classes call `Plutonium::Translation.t`. Put new user-facing text in a locale file, never a literal:
+
+```ruby
+def view_template
+  button { t("my_app.cards.expand") }
+  span { t("my_app.cards.more", count: hidden_count) }   # one:/other: in YAML
+end
+```
+
+Rules: one key per sentence with `%{name}` placeholders (never concatenate fragments around a value), `count:` for plurals, no `.downcase`/`.pluralize` on translated nouns. The gem's own keys live under `plutonium.*` in its `config/locales/en/*.yml` and any can be overridden from the app.
+
+Stimulus controllers bundled with Plutonium read `plutonium.js.*` from a `<meta name="pu-i18n">` JSON blob the layout renders; host JS can call `window.Plutonium.t("plutonium.js.turbo_confirm.confirm")`. Library locales (Slim Select, flatpickr, Uppy, intl-tel-input) pass through `plutonium.js.libraries.*`. See `docs/reference/i18n.md`.
+
 ## Custom Phlex components
 
 ```ruby
@@ -759,6 +774,8 @@ rails generate pu:core:assets
 
 This installs npm packages, creates `tailwind.config.js` extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers, and points the Plutonium config at your asset files.
 
+Packages install with the app's package manager, detected from the lockfile (`bun.lock`/`bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `package-lock.json` → npm, `yarn.lock` → yarn), else the first of bun, yarn, pnpm, npm on PATH. A yarn app stays yarn even with bun installed. Do not run `yarn add` by hand in a bun app: that leaves two lockfiles. Yarn 2+ needs `nodeLinker: node-modules` in `.yarnrc.yml` (the generator writes it); Tailwind's PostCSS plugin does not load under Plug'n'Play.
+
 ## Tailwind config (generated)
 
 ```javascript
@@ -1120,6 +1137,10 @@ end
 - **Tokens are CSS variables, not Tailwind keys** — `bg-[var(--pu-surface)]`, not `bg-pu-surface`.
 - **`render_actions` is mandatory in custom `form_template`** — otherwise no submit button.
 - **Dropdowns (`resource-drop-down`) teleport their menu to `<body>` while open.** popper's `fixed` strategy alone is still clipped by a transformed + `overflow:hidden` ancestor (e.g. grid cards, app shells), so the controller reparents the open menu to `<body>` and restores it on close. Don't rely on the menu being a DOM child of its trigger while open.
+- **`DisplaysValue` components stringify the value and loop per item.** `render_value` receives `normalize_value(value)`, which is `value.to_s`, and for a `field.multiple?` (has_many) field it is called once per element (`field.value.each`). So a custom component that inherits `DisplaysValue` only ever sees the stringified value, per item, never the record. When you need `f.object` or whole-collection rendering, use the block-form display (`display :x do |f| … end`), which is `instance_exec`ed in Phlex once and can emit markup directly.
+- **Blocks run in a Phlex context on every surface.** A `display`, `input`, or `column` block emits `span`/`div` directly, or returns a String or a component. All three are `instance_exec`ed by the resource page rendering them (`self` is the page, not the definition): `display`/`input` blocks receive the field `f`, a `column` block receives the record. Phlex renders the return value too, so a block that emits markup must end with a tag call or `nil`. Most columns need no block at all, because `display :x, as: …` already flows to the table column.
+- **A component reads its attributes from the surface declaration, not from `field`.** Options on `field` go to the Phlexi field builder, which consumes the field-level keys (`:label`, `:description` for displays, `:hint` for forms, `:placeholder`) and ignores the rest. Component options (`colors:`, `unit:`, …) belong on `input`/`display`/`column`. The four field-level help keys are stripped on every surface (the union), so a form key on a display or vice versa is dropped rather than leaked. Any *other* unknown key on a surface whose component does not consume it still renders as a raw HTML attribute, so keep each option on a surface whose component uses it. The table inherits the display's `as:` and attributes unless a `column` declares its own rendering (an `as:`, a component attribute, or a block); a `column` that only sets the header keys (`align:`, `label:`, `condition:`) keeps the display's rendering. `align:` and `label:` may also be declared on `field`.
+- **`as: :phlexi_render, with:` is deprecated** (see [[plutonium-resource]] › Custom Rendering). Use a block-form display. This covers only the display option; the internal `phlexi_render` helper (`Component::Behaviour`) stays.
 
 ---
 

data/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.65.0] - 2026-10-02
+
+### Bug Fixes
+
+- Stop the nav overflowing, and let crushed tables scroll ([#111](https://github.com/radioactive-labs/plutonium-core/issues/111))
+- Cover auto-detected attachments in attachment_input_keys ([#114](https://github.com/radioactive-labs/plutonium-core/issues/114))
+- Keep the current view when clearing filters from the slideover ([#115](https://github.com/radioactive-labs/plutonium-core/issues/115))
+- Inherit width in subclasses and wrap long stepper labels ([#116](https://github.com/radioactive-labs/plutonium-core/issues/116))
+- Apply association filter's scope: option to dropdown and typeahead ([#151](https://github.com/radioactive-labs/plutonium-core/issues/151))
+- Guard #draw against nil engine for unconventional engine names ([#138](https://github.com/radioactive-labs/plutonium-core/issues/138))
+- Raise ArgumentError correctly in authorized_resource_scope ([#140](https://github.com/radioactive-labs/plutonium-core/issues/140))
+- Rescue FloatDomainError in has_cents setters ([#147](https://github.com/radioactive-labs/plutonium-core/issues/147))
+- Honour field condition: on forms by reading before stripping ([#149](https://github.com/radioactive-labs/plutonium-core/issues/149))
+- Preserve sort and scope when applying filters ([#145](https://github.com/radioactive-labs/plutonium-core/issues/145))
+- Neutralize full-width formula characters in CSV export ([#144](https://github.com/radioactive-labs/plutonium-core/issues/144))
+- Strip leading dot from extension fallback in attachment thumbnails ([#143](https://github.com/radioactive-labs/plutonium-core/issues/143))
+- Reject SGIDs whose model class has been removed ([#142](https://github.com/radioactive-labs/plutonium-core/issues/142))
+- Require Stimulus entrypoint alongside Tailwind ([#141](https://github.com/radioactive-labs/plutonium-core/issues/141))
+- Raise ::ActionPolicy::Unauthorized on denied wizard entry ([#148](https://github.com/radioactive-labs/plutonium-core/issues/148))
+- Raise NotImplementedError instead of returning non-existent EntityMembership ([#150](https://github.com/radioactive-labs/plutonium-core/issues/150))
+- Apply association filter's scope: option to filter pill labels ([#155](https://github.com/radioactive-labs/plutonium-core/issues/155))
+- Prevent duplicate memberships via locked state re-check ([#139](https://github.com/radioactive-labs/plutonium-core/issues/139))
+- Keep .env.test.local git-ignored in dotenv generator ([#146](https://github.com/radioactive-labs/plutonium-core/issues/146))
+- JSON-encode Array/Hash direct-upload values for Stimulus ([#121](https://github.com/radioactive-labs/plutonium-core/issues/121))
+- Float slim-select dropdown above modal instead of clipping it ([#157](https://github.com/radioactive-labs/plutonium-core/issues/157))
+- Validate async file inputs by declaration, not value shape ([#169](https://github.com/radioactive-labs/plutonium-core/issues/169))
+- Use sqlserver JDBC subadapter for SQL Server on JRuby ([#168](https://github.com/radioactive-labs/plutonium-core/issues/168))
+- Install assets with the app's package manager, not yarn 1 ([#170](https://github.com/radioactive-labs/plutonium-core/issues/170))
+- Npm install in docker-compose, document jsbundling detection accurately ([#172](https://github.com/radioactive-labs/plutonium-core/issues/172))
+- Drop sections whose fields are all condition-hidden, and leave hidden inputs out of wizard review ([#173](https://github.com/radioactive-labs/plutonium-core/issues/173))
+
+### Documentation
+
+- Publish the introduction post ([#108](https://github.com/radioactive-labs/plutonium-core/issues/108))
+- Per-post og cards, mobile search fix, complete configuration reference ([#109](https://github.com/radioactive-labs/plutonium-core/issues/109))
+- Add the four unreachable pages to the landing rail ([#110](https://github.com/radioactive-labs/plutonium-core/issues/110))
+- Note that width inherits to subclasses ([#120](https://github.com/radioactive-labs/plutonium-core/issues/120))
+- Note reserved filter names in query reference ([#156](https://github.com/radioactive-labs/plutonium-core/issues/156))
+
+### Features
+
+- Reject filters named after reserved query controls ([#153](https://github.com/radioactive-labs/plutonium-core/issues/153))
+- [**breaking**] Render column blocks in a Phlex context and layer header-only columns on the display ([#161](https://github.com/radioactive-labs/plutonium-core/issues/161))
+- Make every Plutonium string and derived label translatable ([#162](https://github.com/radioactive-labs/plutonium-core/issues/162))
+- Declarative dashboards with metric/chart/card DSL and pu:dashboard generator ([#163](https://github.com/radioactive-labs/plutonium-core/issues/163))
+
+### Miscellaneous Tasks
+
+- Remove dead rabl config and template-handler block ([#117](https://github.com/radioactive-labs/plutonium-core/issues/117))
+- Remove dead commented-out actions ([#118](https://github.com/radioactive-labs/plutonium-core/issues/118))
+- Remove dead PlutoniumGenerators::Installer module and Config concern ([#119](https://github.com/radioactive-labs/plutonium-core/issues/119))
+- Remove commented-out create_presenter/create_query_object scaffold methods and orphaned templates ([#165](https://github.com/radioactive-labs/plutonium-core/issues/165))
+- Remove unused Serializer concern and commented-out appname helpers ([#164](https://github.com/radioactive-labs/plutonium-core/issues/164))
+- Remove dead pu:field:input generator ([#160](https://github.com/radioactive-labs/plutonium-core/issues/160))
+- Remove dead turbo-rails monkey patches initializer ([#159](https://github.com/radioactive-labs/plutonium-core/issues/159))
+- Remove dead FieldImporter::Spec#validate method ([#158](https://github.com/radioactive-labs/plutonium-core/issues/158))
+- Remove unused invoke_options helper ([#166](https://github.com/radioactive-labs/plutonium-core/issues/166))
+- Update claude.md
+
 ## [0.64.0] - 2026-08-22
 
 ### Miscellaneous Tasks