plutonium 0.62.2 → 0.63.0

data/docs/reference/ui/displays.md

@@ -13,13 +13,15 @@ class PostDefinition < ResourceDefinition
         p(class: "mt-2 opacity-90") { object.excerpt }
       end
 
-      Block do
-        fields_wrapper do
-          render_resource_field :author
-          render_resource_field :published_at
-        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
+      # the border and shadow.
+      fields_wrapper do
+        render_resource_field :author
+        render_resource_field :published_at
       end
 
+      # `Block` is the card primitive: use it for your own content.
       Block do
         div(class: "prose max-w-none") { raw object.content }
       end
@@ -51,8 +53,8 @@ class PostDefinition < ResourceDefinition
     StatusBadgeComponent.new(value: field.value, class: field.dom.css_class)
   end
 
-  # phlexi_tag — proc whose body is rendered inside a Phlex context
-  display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+  # 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" }
@@ -60,7 +62,9 @@ class PostDefinition < ResourceDefinition
     end
   }
 
-  # Custom component class
+  # 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
 end
 ```
@@ -101,7 +105,7 @@ class PostDefinition < ResourceDefinition
     class Theme < Plutonium::UI::Display::Theme
       def self.theme
         super.merge(
-          fields_wrapper: "grid grid-cols-3 gap-8",
+          fields_inner:   "pu-card-body grid grid-cols-3 gap-8",
           label:          "text-sm font-bold text-[var(--pu-text-muted)] mb-1",
           string:         "text-lg text-[var(--pu-text)]",
           markdown:       "prose dark:prose-invert max-w-none"
@@ -114,7 +118,13 @@ end
 
 ### Theme keys
 
-`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`.
+`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.
+:::
+
+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.)
 

data/docs/reference/ui/index.md

@@ -6,7 +6,7 @@ Plutonium uses [Phlex](https://www.phlex.fun/) for all view components and Tailw
 
 - [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, `phlexi_tag`
+- [Displays](./displays) — `Display` class, custom rendering, `phlexi_render`
 - [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

data/docs/reference/wizard/dsl.md

@@ -30,6 +30,7 @@ For task-oriented walkthroughs, start with the [Wizards guide](/guides/wizards).
 | `one_time` | Retain the completed row at the `concurrency_key` (blocks restart, gate-able). **Requires a `concurrency_key`.** Omit → row deleted on completion (repeatable). See [One-time wizards](/reference/wizard/one-time). |
 | `completed do \|wizard\| … end` | Custom body for the "already completed" page a finished **one-time** wizard shows when re-opened (replaces the default confirmation). See [`completed`](#completed) below and [One-time wizards](/reference/wizard/one-time#re-opening-a-completed-wizard). |
 | `encrypt_data` | Encrypt the staged `data` column at rest using ActiveRecord's encryption keys (off by default), for flows that stage PII. Requires `active_record.encryption` keys — see [Storage & config](/reference/wizard/storage-config#encryption). |
+| `width <size>` | Width of this wizard's step pages: `:sm` `:md` `:lg` `:xl` `:full`. Unset inherits `config.wizards.width` (default `:md`). Deliberately independent of `config.default_page_width` — see [Storage & config](/reference/wizard/storage-config). |
 | `anonymous` | Opt into **guest (unauthenticated) access** — the wizard runs pre-login (auth is required otherwise). The guest's identity is a server-minted run-id in the Rails session; it crosses the auth boundary only at its terminal `execute`. Mount it `public: true` (the default for `anonymous`). **Mutually exclusive with `concurrency_key`/`one_time`** — a guest is already session-keyed and repeatable, so declaring both raises (whichever is declared last). See [Authentication](/reference/wizard/anchoring-resume#authentication). |
 
 ```ruby
@@ -83,6 +84,36 @@ A step's block is the same field DSL used on definitions and interactions:
 
 See [plutonium-resource › Definition](/reference/resource/definition) for the full field/input/layout vocabulary.
 
+#### Runtime input options
+
+A step's fields are fixed when the class loads, so a **proc** is how an option depends on the run. Proc-valued field/input options are resolved on every render, and the proc **takes the form** — `form.wizard` is the run, `form.object` is that step's staged data:
+
+```ruby
+step :plan do
+  attribute :tier
+  input :tier, as: :select, choices: ->(form) { form.wizard.anchor.available_tiers }
+end
+```
+
+`form.wizard` is the same object `execute` and a step's `condition:` run against, so `anchor`, `data`, `persisted` and `current_user` are all reachable through it.
+
+It is also how a custom component receives per-run configuration:
+
+```ruby
+input :answers, as: MyManifestComponent, config: ->(form) { form.wizard.anchor.manifest }
+```
+
+::: warning Take the argument
+A **zero-argument** proc here will not work. It keeps its own binding — the same rule as [everywhere else](/reference/resource/definition#options-that-vary-per-render) — and a step block is `instance_exec`'d against an internal field recorder when the class loads, so `-> { anchor.available_tiers }` looks `anchor` up on that recorder and raises `NameError`.
+
+That is deliberate: it is the same trade a `form_layout` section option makes, and it means an `input` line keeps its meaning when moved between a definition and a step. Nothing silently swaps `self`.
+:::
+
+Two limits worth knowing:
+
+- The **field set** is still fixed at class load. A proc varies an option, not which fields exist. To collect a shape known only at runtime, declare one `structured_input` and let a custom component render the inner controls. For bespoke markup, pass a block to `input` instead — it renders in the form's context with the field yielded.
+- `condition:` is **not** resolved this way, because it is not an option — it asks "should this render here, now?", so it always runs *against* the thing doing the rendering and reads it with no argument. A *step's* `condition:` runs against the **wizard** (it is evaluated in the runner to decide which steps exist, before any form is built — which is exactly why it can't be handed a form); a *field's* runs against the **form**, where `object` is that step's staged data. See [Definition › `condition:` is not an option](/reference/resource/definition#condition-is-not-an-option).
+
 ### `using:` a model
 
 `using:` imports field declarations from an ActiveRecord model so a step needn't re-declare them. It is a **step option**, not a block method (avoids Ruby's `Module#using` refinements clash), and it targets a **model only**.
@@ -313,6 +344,8 @@ Available inside steps, `condition:`, `on_submit`, `on_rollback`, and `execute`:
 | `anchor` | The record the wizard was launched against. Raises `NotAnchoredError` if the wizard isn't `anchored`. |
 | `persisted[:step_key]` | Record(s) a per-step `on_submit` registered via `persist`. Lazily rehydrated on first access (located from stored GlobalIDs the first time you read the key, memoized thereafter). |
 
+A **proc-valued field/input option** on a step reaches the same accessors through `form.wizard` — see [Runtime input options](#runtime-input-options).
+
 ## Outcome helpers
 
 | Helper | Use |

data/docs/reference/wizard/storage-config.md

@@ -13,6 +13,7 @@ Plutonium.configure do |config|
   config.wizards.cleanup_after = 14.days   # global default idle TTL for the sweep
   config.wizards.encrypt_data = true       # encrypt every wizard's data at rest (needs AR encryption keys)
   config.wizards.attachment_backend = nil  # server-side attachment staging backend (nil = auto-detect)
+  config.wizards.width = :md               # step page width; independent of config.default_page_width
 end
 ```