lcp 0.1.0

data/docs/reference/presenter-dsl.md

@@ -0,0 +1,1719 @@
+# Presenter DSL Reference
+
+File: `config/lcp_ruby/presenters/<name>.rb`
+
+The Presenter DSL is a Ruby alternative to [YAML presenter definitions](presenters.md). It produces the same internal representation (`PresenterDefinition`) and feeds through the same pipeline — the DSL builder outputs a hash identical to parsed YAML, which is then processed by `PresenterDefinition.from_hash`.
+
+DSL files live alongside YAML files in `config/lcp_ruby/presenters/`. A project can mix both formats, but each presenter name must be unique across all files (defining the same presenter in both `.yml` and `.rb` raises `MetadataError`).
+
+## Entry Point
+
+```ruby
+LcpRuby.define_presenter :presenter_name do
+  # DSL calls here
+end
+```
+
+In DSL files loaded by the engine, use `define_presenter` without the `LcpRuby.` prefix:
+
+```ruby
+# config/lcp_ruby/presenters/deal.rb
+define_presenter :deal do
+  model :deal
+  label "Deals"
+  slug "deals"
+  # ...
+end
+```
+
+## Presenter Metadata
+
+### `model`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | symbol or string |
+
+The model this presenter displays. Must match a defined model name.
+
+```ruby
+model :deal
+```
+
+### `label`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `name.humanize` |
+| **Type** | string |
+
+Human-readable name displayed in page headings and navigation.
+
+```ruby
+label "Deals"
+```
+
+### `slug`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+URL slug for routing. When set, the presenter is routable at `/<slug>`.
+
+```ruby
+slug "deals"
+```
+
+### `icon`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Icon identifier for navigation and UI elements.
+
+```ruby
+icon "dollar-sign"
+```
+
+### `menu_position`
+
+> **Deprecated.** Write `config/lcp_ruby/menu.yml` for explicit menu placement — the entity generator's `--menu=...` flag makes this a one-line addition at scaffold time. `menu_position` still works in v1 and emits a one-time info-level log when used; it will be removed in a future release. See [Presenters Reference — `menu_position`](presenters.md#menu_position).
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | integer |
+
+Position hint for the auto-created view group when this is the only presenter on the model. Lifts the auto-VG out of the alphabetical 900+index tier into a configurator-controlled position. Ignored when an explicit view group YAML covers the model. See [Presenters Reference — `menu_position`](presenters.md#menu_position) for the full semantics.
+
+```ruby
+menu_position 10
+```
+
+### `default`
+
+| | |
+|---|---|
+| **Required** | no (required when the model has multiple routable presenters and any column/field uses `link: true` without a per-link `link_presenter:` override) |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Marks this presenter as the canonical link target for its model. When another presenter has `link: true` / `link_to: :show` to a record of this model, the link resolves to the presenter marked `default true`. Exactly one presenter per model may be marked default — the validator rejects duplicates at boot. See [Presenters Reference — Multiple presenters per model](presenters.md#multiple-presenters-per-model) for the full pattern.
+
+```ruby
+default true
+# `default` (no arg) is equivalent to `default true`
+```
+
+### `read_only`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Marks the presenter as read-only (no create/edit/destroy actions).
+
+```ruby
+read_only true
+```
+
+### `embeddable`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+Whether the presenter can be embedded inside another presenter's view.
+
+```ruby
+embeddable true
+```
+
+### `redirect_after`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | keyword arguments |
+
+Controls where the user is redirected after create or update. Each key maps to a target page. Valid targets: `:index`, `:show`, `:edit`, `:new`. Default for both is `:show`.
+
+```ruby
+redirect_after create: :index, update: :index
+```
+
+### `empty_value`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string |
+
+Overrides the placeholder text for nil/blank field values in this presenter. Takes precedence over the global config and i18n key.
+
+```ruby
+empty_value "N/A"
+```
+
+### `record_alias`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | DSL method (name, **opts) |
+
+Defines a named URL segment that resolves to a specific record dynamically. Multiple aliases can be defined per presenter. See the [YAML reference](presenters.md#record_aliases) for full semantics.
+
+```ruby
+# current_user strategy — /preferences/me resolves via belongs_to FK
+record_alias :me, resolve: :current_user, field: :user
+
+# current_user on self — presenter model IS the user model (same table);
+# omit `field:` so /my-settings/me resolves to current_user's own row.
+record_alias :me, resolve: :current_user
+
+# scope strategy — /issues/last resolves via named scope
+record_alias :last, resolve: :scope, scope: :latest
+
+# field_on_user strategy — /teams/my resolves via current_user.team_id
+record_alias :my, resolve: :field_on_user, user_field: :team_id
+```
+
+**Full example:**
+
+```ruby
+define_presenter :my_preferences do
+  model :user_preference
+  slug "preferences"
+
+  record_alias :me, resolve: :current_user, field: :user
+
+  show do
+    section do
+      field :theme
+      field :language
+    end
+  end
+
+  form do
+    section do
+      field :theme
+      field :language
+    end
+  end
+end
+```
+
+## Index Configuration
+
+The `index` block configures the list/table view.
+
+```ruby
+index do
+  description "Manage all deals in your pipeline."
+  default_view :table
+  views_available :table, :tiles
+  default_sort :created_at, :desc
+  per_page 25
+  column :title, width: "30%", link_to: :show, sortable: true
+  column :stage, width: "20%", renderer: :badge, sortable: true
+end
+```
+
+### Index Methods
+
+#### `render_with(partial)`
+
+Replaces the entire index content area with a custom host-app partial. The search/sort/scope pipeline still runs — the partial receives the processed `records`. When set, `layout` is ignored.
+
+```ruby
+index do
+  render_with "analytics/dashboard"
+end
+```
+
+YAML equivalent: `index: { render_with: "analytics/dashboard" }`
+
+#### `description(text)`
+
+Descriptive text displayed below the page heading on the index view.
+
+```ruby
+description "Browse and filter all deals in your pipeline."
+```
+
+#### `default_view(value)`
+
+Default view mode. Common values: `:table`, `:tiles`.
+
+#### `views_available(*values)`
+
+Available view modes the user can switch between.
+
+```ruby
+views_available :table, :tiles
+```
+
+#### `default_sort(field, direction)`
+
+Default sort column and direction (`:asc` or `:desc`).
+
+```ruby
+default_sort :created_at, :desc
+```
+
+#### `reorderable(value)`
+
+Enables drag-and-drop reordering of records in the index table. The model must have a [`positioning`](models.md#positioning) configuration.
+
+```ruby
+index do
+  reorderable true
+  column :name, link_to: :show
+  column :position, sortable: true
+end
+```
+
+When `reorderable true` is set and no explicit `default_sort` is given, the engine auto-applies `default_sort <position_field>, :asc`. See [Presenters Reference — reorderable](presenters.md#reorderable) for full details.
+
+#### `per_page(value)`
+
+Number of records per page. Default: 25.
+
+#### `row_click(value)`
+
+Sets the behavior when a user clicks a table row.
+
+```ruby
+row_click :show   # clicking a row navigates to the show page
+```
+
+#### `empty_message(value)`
+
+Message displayed when the index table has no records.
+
+```ruby
+empty_message "No deals found. Create your first deal to get started."
+```
+
+#### `actions_position(value)`
+
+Controls how row-level actions are displayed.
+
+| Value | Description |
+|-------|-------------|
+| `:inline` | Actions are rendered as inline buttons (default) |
+| `:dropdown` | Actions appear in a dropdown menu |
+
+```ruby
+actions_position :dropdown
+```
+
+#### `includes(*associations)`
+
+Manually specify associations to preload for display. See [Eager Loading](eager-loading.md).
+
+```ruby
+index do
+  includes :company, :contact
+end
+```
+
+#### `eager_load(*associations)`
+
+Manually specify associations to eager load via LEFT JOIN. See [Eager Loading](eager-loading.md).
+
+```ruby
+index do
+  eager_load :company
+end
+```
+
+#### `layout(value)`
+
+Sets the index page layout mode: `:table` (default), `:tiles`, or `:tree`.
+
+```ruby
+index do
+  layout :tiles
+end
+```
+
+#### `tile(&block)`
+
+Tile-layout-specific grid configuration. Card zone rendering uses the sibling [`card`](#cardblock) block.
+
+```ruby
+index do
+  layout :tiles
+  tile { columns 4 }
+  card do
+    title_field :name
+    # … see card(&block) below
+  end
+end
+```
+
+| DSL method | Description |
+|---|---|
+| `columns(n)` | Number of grid columns (responsive breakpoints override at narrow widths) |
+
+#### `card(&block)`
+
+Per-record card interior shared across card-based layouts (tiles, kanban, future). Title becomes a link when index-level [`row_click`](#row_click) is set.
+
+```ruby
+index do
+  layout :tiles
+  row_click :show
+
+  card do
+    title_field :name
+    subtitle_field :status, renderer: :badge, options: { color_map: { active: :green } }
+    description_field :description, max_lines: 3
+
+    image_field :cover_image, alt: :cover_alt
+    avatar_field "owner.avatar"
+    color_field :priority, map: { critical: :danger, high: :warning, normal: :muted }
+
+    actions :dropdown
+    render_with "my_app/cards/deal"   # optional full-body override
+
+    field :price, label: "Price", renderer: :currency, options: { currency: "EUR" }
+    field "company.name", label: "Company"
+    field :total, partial: "my_app/cells/kpi"   # custom partial cell (parity with table columns)
+  end
+end
+```
+
+| DSL method | Notes |
+|---|---|
+| `title_field(name)` | Required for any card-based layout |
+| `subtitle_field(name, renderer:, options:)` | Optional renderer + options |
+| `description_field(name, max_lines:)` | Plain text, line-clamped via CSS |
+| `image_field(name, alt:)` | Banner image; `alt:` is field name for alt text (falls back to title_field value) |
+| `avatar_field(name, alt:)` | Small circular avatar; alt defaults to "" (decorative) |
+| `color_field(name, map:)` | Accent color from value via whitelist palette tokens (`success`, `danger`, `warning`, `info`, `muted`, `primary`). Raw values never reach CSS. |
+| `actions(:dropdown \| :inline \| :none)` | How per-card actions are rendered |
+| `render_with(path)` | Host-app partial path that overrides the entire card body |
+| `field(name, label:, renderer:, options:, partial:)` | Label-value entry; `partial:` overrides `renderer:` |
+
+#### `sort_field(field, label: nil)`
+
+Adds a field to the sort dropdown.
+
+```ruby
+index do
+  sort_field :name, label: "Name"
+  sort_field :price, label: "Price"
+end
+```
+
+#### `per_page_options(*values)`
+
+Selectable page sizes shown in a dropdown near pagination.
+
+```ruby
+index do
+  per_page 25
+  per_page_options 10, 25, 50, 100
+end
+```
+
+#### `show_record_count(value = true)`
+
+Shows or hides the record count text in the pagination footer. Default `true`.
+
+```ruby
+index do
+  show_record_count false   # hide "Showing X-Y of Z records"
+end
+```
+
+#### `pagination_ends(value = true)`
+
+Shows "First" and "Last" page links in the pagination footer. Per-presenter override of the global [`LcpRuby.configuration.pagination_ends`](engine-configuration.md#pagination_ends). Default `false`.
+
+```ruby
+index do
+  pagination_ends true   # show First/Last links
+end
+```
+
+#### `summary(&block)`
+
+Configures the summary bar with aggregate values.
+
+```ruby
+index do
+  summary do
+    enabled true
+    field :price, function: :sum, label: "Total Revenue"
+    field :price, function: :avg, label: "Average Price"
+  end
+end
+```
+
+#### `item_class(classes, when:)`
+
+Adds a conditional CSS class rule for index rows/cards. All matching rules accumulate.
+
+```ruby
+index do
+  item_class "lcp-row-muted lcp-row-strikethrough",
+             when: { field: :status, operator: :eq, value: "done" }
+  item_class "lcp-row-danger",
+             when: { field: :status, operator: :eq, value: "overdue" }
+  item_class "lcp-row-bold",
+             when: { field: :priority, operator: :eq, value: "critical" }
+end
+```
+
+See [Presenters Reference — item_classes](presenters.md#item_classes) for built-in utility classes and detailed attribute reference.
+
+#### `column(field_name, **options)`
+
+Adds a table column.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `width:` | string | Column width (e.g., `"30%"`) |
+| `label:` | string | Custom column header label (e.g., `"Company"` for a `"company.name"` dot-path field) |
+| `link_to:` | symbol | **Legacy.** Always links the cell to the **current row's** show page, regardless of the column field. Kept for backward compatibility. Prefer `link: true` below for new configurations |
+| `link:` | boolean | Wrap the cell value in a link. Auto-detects the target: dot-path (e.g. `"manager.display_name"`) links to the last belongs_to record in the chain; a plain belongs_to field name links to that record; a scalar field links to the current row (same as legacy `link_to: :show`). Use `link_through:` to override |
+| `link_through:` | symbol | Name of a `belongs_to` association on this model to follow for the link target. Implies `link: true`. Use when the displayed field's name doesn't match the linked entity (e.g. a precomputed label). Incompatible with `link_to: :show` |
+| `link_presenter:` | string/symbol | Override the target presenter slug for this link. Use when the linked model has multiple presenters and you want a non-default one. Falls back to the model's `default true` presenter. See [Presenters Reference — Multiple presenters per model](presenters.md#multiple-presenters-per-model) |
+| `sortable:` | boolean | Whether column is sortable |
+| `renderer:` | symbol | Renderer for the field value (`:badge`, `:currency`, `:relative_date`, etc.). Alternatively, use `partial:` to render with a custom view partial |
+| `options:` | hash | Additional renderer configuration (e.g., `{ color_map: { ... } }`) |
+| `hidden_on:` | symbol or array | Responsive breakpoints to hide the column on (e.g., `:mobile`, `[:mobile, :tablet]`) |
+| `pinned:` | symbol | Pin the column to `:left` or `:right` side of the table |
+| `summary:` | symbol | Summary function for the column footer (e.g., `:sum`, `:avg`, `:count`) |
+| `aggregate:` | symbol or hash | (Grouped mode only) Aggregate function. Short form: `:count`. Full form: `{ function: :sum, field: :amount }`. Add `distinct: true` for `AGG(DISTINCT field)` |
+| `group_field:` | symbol or string | (Grouped mode only) References the original `group_by` field when the column name differs (e.g., `column :month, group_field: :issued_at`) |
+| `sort_strategy:` | symbol | Enum columns only. `:definition_order` (default for enums) sorts by position in enum values list. `:value` sorts alphabetically. Applies to grouped and non-grouped views |
+| `display_in_index:` | boolean | Per-column opt-in for fields whose type carries `default_index_visible: false` (`:text`, `:rich_text`, `:attachment`, `:json`, `:array`, `:file`). Without this kwarg the configuration validator emits a row-unfriendly-column warning suggesting either an explicit `renderer:` or this opt-in. Has no runtime effect — purely a validator-silencer. See [`docs/reference/types.md`](types.md#default_index_visible) |
+
+### Grouped Query Mode
+
+Setting `query_mode :grouped` switches the index from per-record to per-group query. The controller builds `SELECT group_cols, AGG() FROM table GROUP BY group_cols` instead of `SELECT * FROM table`.
+
+```ruby
+index do
+  query_mode :grouped
+  group_by [:category]
+  default_sort :feature_count, :desc
+  row_click :filter, target: "features"
+
+  column :category, sortable: true, renderer: :badge
+  column :feature_count, aggregate: :count, sortable: true
+end
+```
+
+#### `query_mode(value)`
+
+Set to `:grouped` to enable grouped query mode.
+
+#### `group_by(fields)`
+
+Fields to GROUP BY. Accepts simple field names and hash entries for date truncation:
+
+```ruby
+group_by [:stage, :region]
+group_by [{ field: :issued_at, period: :month }]
+```
+
+Valid periods: `:year`, `:quarter`, `:month`, `:week`, `:day`.
+
+#### `having(&block)`
+
+Post-aggregation filter (SQL HAVING). The block returns a condition hash or array:
+
+```ruby
+having { { field: :product_count, operator: :gte, value: 5 } }
+```
+
+Operators: `:eq`, `:neq`, `:gt`, `:gte`, `:lt`, `:lte`.
+
+#### `limit(value)`
+
+Maximum number of group rows. Disables Kaminari pagination when set.
+
+```ruby
+limit 10
+```
+
+#### `row_click(:filter, target: "slug")`
+
+Clicking a group row navigates to the target presenter's index with auto-generated Ransack filter params from the group column values:
+
+```ruby
+row_click :filter, target: "features"
+```
+
+#### Grouped Query Example
+
+```ruby
+define_presenter :deals_pipeline do
+  model :deal
+  slug "deals-pipeline"
+
+  index do
+    query_mode :grouped
+    group_by [:stage, :region]
+    default_sort :total_value, :desc
+    having { { field: :deal_count, operator: :gte, value: 3 } }
+    limit 20
+    row_click :filter, target: "deals"
+
+    column :stage, sortable: true, renderer: :badge
+    column :region, sortable: true
+    column :deal_count, aggregate: :count, sortable: true
+    column :total_value, aggregate: { function: :sum, field: :value },
+           renderer: :currency, sortable: true
+    column :avg_value, aggregate: { function: :avg, field: :value },
+           renderer: :currency
+    column :unique_owners, aggregate: { function: :count, distinct: true, field: :owner_id }
+  end
+end
+```
+
+## Show Configuration
+
+The `show` block configures the detail view.
+
+```ruby
+show do
+  description "View deal details and related contacts."
+
+  section "Deal Information", columns: 2 do
+    field :title, renderer: :heading
+    field :stage, renderer: :badge
+    field :value, renderer: :currency
+  end
+
+  association_list "Contacts", association: :contacts
+end
+```
+
+### Show Methods
+
+#### `description(text)`
+
+Descriptive text displayed below the page heading on the show view.
+
+```ruby
+description "View deal details and related contacts."
+```
+
+#### `render_with(partial)`
+
+Replaces the entire show content area with a custom host-app partial. Ignored in dialog and composite page contexts.
+
+```ruby
+show do
+  render_with "products/custom_show"
+end
+```
+
+YAML equivalent: `show: { render_with: "products/custom_show" }`
+
+#### `copy_url(value)`
+
+Controls whether the "Copy link" toolbar button is shown on the show page. Default: `true`. Set to `false` to hide it.
+
+```ruby
+show do
+  copy_url false
+  # ...
+end
+```
+
+#### `includes(*associations)` / `eager_load(*associations)`
+
+Same as index. Manually specify associations to preload for the show page. Auto-detection handles `association_list` sections automatically. See [Eager Loading](eager-loading.md).
+
+#### `custom_section(title, partial:, visible_when: nil)`
+
+Creates a section whose content is rendered by a host-app partial. The `fields:` key is not used — the partial owns all content inside the section wrapper.
+
+```ruby
+show do
+  custom_section "Location", partial: "employees/location_map"
+
+  custom_section "Map",
+    partial: "employees/map_embed",
+    visible_when: { field: :latitude, operator: :present }
+end
+```
+
+YAML equivalent: `show: { layout: [{ section: "Location", type: custom, partial: "employees/location_map" }] }`
+
+#### `section(title, columns: 1, description: nil, responsive: nil, visible_when: nil, disable_when: nil, &block)`
+
+Creates a section with fields. The `columns:` option controls the layout grid. The `description:` option adds explanatory text below the section heading. The `responsive:` option controls how the section adapts to different screen sizes. The `visible_when:` and `disable_when:` options control server-side conditional rendering — hidden sections are not rendered in the DOM.
+
+```ruby
+show do
+  section "Deal Information", columns: 2, description: "Key metrics for this deal", responsive: { mobile: 1 } do
+    field :title, renderer: :heading
+    field :stage, renderer: :badge
+  end
+
+  section "Metrics",
+    visible_when: { field: :stage, operator: :not_eq, value: "lead" } do
+    field :priority
+    field :progress
+  end
+end
+```
+
+#### `association_list(title, association:, display_template: nil, link: nil, link_through: nil, sort: nil, limit: nil, empty_message: nil, scope: nil, visible_when: nil, disable_when: nil)`
+
+Renders a list of associated records with optional display templates, links, sorting, and limits. The `association:` must match a `has_many` association on the model.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `association:` | symbol | The `has_many` association name (required) |
+| `display_template:` | symbol or string | Name of the display template defined on the target model (e.g., `:default`) |
+| `link:` | boolean | Wrap each record in a link to its show page |
+| `link_through:` | symbol | Follow this `belongs_to` association on the target model to resolve the link target (implies `link: true`) |
+| `link_presenter:` | string/symbol | Override the target presenter slug. Use when the linked model has multiple presenters. Falls back to the model's `default true` presenter |
+| `sort:` | hash | Sort associated records by field and direction (e.g., `{ last_name: :asc }`) |
+| `limit:` | integer | Maximum number of records to display |
+| `empty_message:` | string | Message shown when there are no associated records |
+| `scope:` | symbol | Named scope to apply on the association before rendering |
+
+```ruby
+# Basic
+association_list "Deals", association: :deals
+
+# With all options
+association_list "Contacts", association: :contacts,
+  display_template: :default, link: true,
+  sort: { last_name: :asc }, limit: 10,
+  empty_message: "No contacts yet.",
+  scope: :active
+
+# Link through a join model to the real entity
+association_list "Members", association: :group_memberships,
+  link_through: :employee
+```
+
+When `display_template:` references a display template defined on the target model (see [Models Reference — Display Templates](models.md#display-templates)), each record is rendered with the template's structured layout (title, subtitle, icon, badge). Without `display_template:`, records fall back to plain `to_label` text.
+
+When `link_through:` is set, each record links to the related record reached by following the named `belongs_to` association on the target model. This is useful for join/bridge models where the meaningful entity is on the other side of the association. The association must be a non-polymorphic `belongs_to`. If the related record is `nil` or soft-deleted, the item renders without a link.
+
+### Section Fields (Show)
+
+Inside a show `section` block, use `field` to add display fields:
+
+```ruby
+field :name, renderer: :heading
+field :status, renderer: :badge
+field :description, renderer: :rich_text
+field :budget, renderer: :currency
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `renderer:` | symbol | Renderer for the field value. Alternatively, use `partial:` to render with a custom view partial |
+| `label:` | string | Custom field label (e.g., `"Company"` for a `"company.name"` dot-path field) |
+| `copyable:` | boolean | Adds a copy-to-clipboard icon next to the field value |
+| `col_span:` | integer | Number of grid columns this field spans |
+| `hidden_on:` | symbol or array | Responsive breakpoints to hide the field on |
+| `link:` | boolean | Wrap the field value in a link to the associated record. Auto-detects the target from a dot-path (e.g. `"manager.display_name"` links to the manager, `"manager.organizational_unit.name"` links to that org unit) or from a plain `belongs_to` field name (`field :manager`). Incompatible with link-emitting renderers (`email_link`, `url_link`, `attachment_link`, `markdown`, `rich_text`, …) |
+| `link_through:` | symbol | Name of a `belongs_to` association on this model to follow for the link target. Implies `link: true`. Use when the displayed field's name doesn't correspond to the linked entity (e.g. a precomputed virtual column / custom field label) |
+| `link_presenter:` | string/symbol | Override the target presenter slug for this link. Use when the linked model has multiple presenters. Falls back to the model's `default true` presenter |
+| `options:` | hash | Additional renderer configuration |
+
+## Form Configuration
+
+The `form` block configures create and edit forms.
+
+```ruby
+form do
+  description "Enter the deal details below."
+
+  section "Deal Details", columns: 2 do
+    field :title, placeholder: "Deal title...", autofocus: true
+    field :stage, input_type: :select
+    field :value, input_type: :number
+    field :company_id, input_type: :association_select
+  end
+end
+```
+
+### Form Methods
+
+#### `description(text)`
+
+Descriptive text displayed at the top of the form, below error messages.
+
+```ruby
+description "Fill in the deal details. Required fields are marked with *."
+```
+
+#### `includes(*associations)` / `eager_load(*associations)`
+
+Same as index. Manually specify associations to preload for the form. Auto-detection handles `nested_fields` sections automatically. See [Eager Loading](eager-loading.md).
+
+#### `custom_section(title, partial:, visible_when: nil, additional_permitted_params: nil)`
+
+Creates a form section whose content is rendered by a host-app partial. The partial receives the `form` builder local for rendering inputs.
+
+```ruby
+form do
+  custom_section "Variants",
+    partial: "products/variants_editor",
+    additional_permitted_params: ["variants_json", { "address" => ["street", "city", "zip"] }]
+end
+```
+
+YAML equivalent: `form: { sections: [{ title: "Variants", type: custom, partial: "products/variants_editor", additional_permitted_params: [...] }] }`
+
+#### `layout(value)`
+
+Sets the overall form layout mode.
+
+| Value | Description |
+|-------|-------------|
+| `:flat` | All sections rendered sequentially (default) |
+| `:tabs` | Each section rendered as a tab |
+
+```ruby
+form do
+  layout :tabs
+
+  section "Basic Info" do
+    field :title
+  end
+
+  section "Details" do
+    field :description
+  end
+end
+```
+
+#### `section(title = nil, key: nil, columns: 1, description: nil, collapsible: false, collapsed: false, responsive: nil, visible_when: nil, disable_when: nil, &block)`
+
+Creates a form section. Multiple sections create visual groupings. At least one of `title` or `key:` must be given.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `key:` | string | Explicit i18n lookup key. See [Section titles & i18n](#section-titles--i18n) below. |
+| `columns:` | integer | Number of layout columns (default: 1) |
+| `description:` | string | Explanatory text displayed below the section heading |
+| `collapsible:` | boolean | Whether the section can be collapsed/expanded by the user |
+| `collapsed:` | boolean | Whether the section starts in collapsed state (requires `collapsible: true`) |
+| `responsive:` | hash | Responsive column overrides (e.g., `{ mobile: 1 }`) |
+| `visible_when:` | hash | Condition hash for section visibility |
+| `disable_when:` | hash | Condition hash for section disabling |
+
+```ruby
+form do
+  section "Primary", columns: 2, responsive: { mobile: 1 } do
+    field :title
+    field :stage, input_type: :select
+  end
+
+  section "Notes", collapsible: true, collapsed: true do
+    field :description, input_type: :textarea
+  end
+end
+```
+
+##### Section titles & i18n
+
+Section titles are looked up in i18n under `lcp_ruby.presenters.<presenter>.sections.<key>`. There are two conventions:
+
+**Default (English literal as key source).** Without `key:`, the literal title is parameterized to derive the lookup key — `section "List Details"` → looks up `…sections.list_details`. The literal is also the fallback when the i18n entry is missing. **Recommended for new code:** keep the literal in English, then translate via locale files. Non-English literals "work" but they leak into the en locale via the fallback path, mixing structure and text.
+
+```ruby
+section "List Details" do
+  field :title
+end
+```
+
+```yaml
+# config/locales/cs.yml
+cs:
+  lcp_ruby:
+    presenters:
+      project:
+        sections:
+          list_details: "Detaily seznamu"
+```
+
+**Explicit key (`key:` keyword).** Pass `key:` to decouple the i18n lookup from the literal — useful when the configurator wants the structure (DSL) free of any human-readable text:
+
+```ruby
+section key: "list_details" do                # i18n key only
+  field :title
+end
+
+# or paired with a literal that acts as the en fallback:
+section "List Details", key: "list_details" do
+  field :title
+end
+```
+
+When `key:` is set, lookup is `…sections.<key>` verbatim; fallback when missing is the literal title (if given) or a humanized key.
+
+The same `key:` keyword is supported by `custom_section`, `json_items_list`, `association_list`, `nested_fields`, and the `section` inside `nested_fields` blocks.
+
+#### `nested_fields(title, association: nil, json_field: nil, target_model: nil, **options, &block)`
+
+Adds a nested form section for editing a list of structured items inline. Items can come from three data sources:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `association:` | symbol | has_many association name (mutually exclusive with `json_field:`) |
+| `json_field:` | symbol | JSON column name for storing items as array of hashes (mutually exclusive with `association:`) |
+| `target_model:` | symbol | Virtual model name defining item structure and validations (only with `json_field:`) |
+| `allow_add:` | boolean | Show an "Add" button (default: `true`) |
+| `allow_remove:` | boolean | Show a "Remove" button on each row (default: `true`) |
+| `min:` | integer | Minimum number of items |
+| `max:` | integer | Maximum number of items |
+| `add_label:` | string | Custom label for the "Add" button |
+| `empty_message:` | string | Message shown when there are no items |
+| `columns:` | integer | Number of layout columns for each row |
+| `sortable:` | boolean or string | Enable drag-and-drop reordering. `true` uses `position` field, or pass a string for a custom field name |
+| `visible_when:` | hash | Condition hash for nested section visibility |
+| `disable_when:` | hash | Condition hash for nested section disabling |
+
+Exactly one of `association:` or `json_field:` is required.
+
+**Association source (has_many):**
+
+```ruby
+nested_fields "Items", association: :todo_items,
+  allow_add: true, allow_remove: true,
+  max: 50, add_label: "Add Item", columns: 2 do
+    field :title, placeholder: "Item title..."
+    field :completed, input_type: :checkbox
+    field :due_date, input_type: :date_picker
+end
+```
+
+**JSON field source (inline definitions):**
+
+When using `json_field:` without `target_model:`, declare field types and labels inline:
+
+```ruby
+nested_fields "Workflow Steps", json_field: :steps,
+  sortable: true, allow_add: true, allow_remove: true, columns: 2 do
+    field :name, type: :string, label: "Step Name"
+    field :action_type, type: :string, input_type: :select,
+      input_options: { values: %w[review approve notify] }
+    field :timeout_days, type: :integer, label: "Timeout (days)",
+      visible_when: { field: :action_type, operator: :eq, value: "review" }
+end
+```
+
+**JSON field source (model-backed):**
+
+When `target_model:` is specified, field metadata (type, label, validations) comes from a virtual model:
+
+```ruby
+nested_fields "Addresses", json_field: :addresses, target_model: :address,
+  allow_add: true, allow_remove: true, columns: 2 do
+    field :street
+    field :city
+    field :zip
+    field :country
+end
+```
+
+**Sub-sections in nested rows:**
+
+Use `section` blocks (instead of `field` calls) to group fields within each row. You cannot mix `field` and `section` in the same block:
+
+```ruby
+nested_fields "Addresses", json_field: :addresses, target_model: :address,
+  allow_add: true, allow_remove: true do
+    section "Location", columns: 2 do
+      field :street
+      field :city
+      field :zip
+      field :country
+    end
+    section "Additional", collapsible: true, collapsed: true do
+      field :notes
+      field :is_primary, input_type: :boolean
+    end
+end
+```
+
+Sub-sections support `columns:`, `collapsible:`, `collapsed:`, `visible_when:`, and `disable_when:`.
+
+**With sortable (drag-and-drop reordering):**
+
+```ruby
+nested_fields "Items", association: :todo_items,
+  sortable: true, add_label: "Add Item" do
+    field :title
+    field :completed, input_type: :checkbox
+end
+```
+
+Set `sortable: true` to use the default `position` field, or `sortable: "sort_order"` for a custom field name. The position field is hidden from the visible form and auto-permitted in the controller.
+
+### Form Fields (Section Builder)
+
+Inside a form `section` or `nested_fields` block:
+
+```ruby
+field :title, placeholder: "Enter title...", autofocus: true
+field :stage, input_type: :select
+field :budget, input_type: :number, prefix: "$"
+field :start_date, input_type: :date_picker
+field :company_id, input_type: :association_select
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `input_type:` | symbol | Input widget (`:select`, `:number`, `:text`, `:date_picker`, `:association_select`) |
+| `placeholder:` | string | Placeholder text |
+| `autofocus:` | boolean | Auto-focus on page load |
+| `prefix:` | string | Input prefix (e.g., `"$"`) |
+| `suffix:` | string | Input suffix (e.g., `"kg"`) |
+| `col_span:` | integer | Number of grid columns this field spans (e.g., `2` for a full-width field in a 2-column section) |
+| `hint:` | string | Help text displayed below the input |
+| `readonly:` | boolean | Render the field as read-only |
+| `visible_when:` | hash | Condition hash for conditional visibility. Field-value: `{ field: :status, operator: :eq, value: "active" }`. Service: `{ service: :persisted_check }`. See [Conditional Rendering](../guides/conditional-rendering.md). |
+| `disable_when:` | hash | Condition hash for conditional disabling. Same syntax as `visible_when`. When condition is true, field is visually disabled but values are still submitted. |
+| `default:` | any | Default value for the form input (overrides the model-level default for this form) |
+| `input_options:` | hash | Additional options passed to the input widget (see below) |
+| `options:` | hash | Renderer configuration (e.g., formatting for read-only rendering) |
+| `hidden_on:` | symbol or array | Responsive breakpoints to hide the field on |
+
+#### `input_options` for Select Fields
+
+**Enum select** — role-based value filtering:
+
+```ruby
+field :stage, input_type: :select,
+  input_options: {
+    include_blank: false,
+    exclude_values: { viewer: ["lead"] },
+    include_values: { intern: ["active", "inactive"] }
+  }
+```
+
+**Association select** — scope, sort, label, grouping:
+
+```ruby
+field :company_id, input_type: :association_select,
+  input_options: {
+    scope: :active,
+    sort: { name: :asc },
+    label_method: :full_name,
+    include_blank: "-- Choose company --",
+    group_by: :industry
+  }
+```
+
+**Dependent (cascading) select** — child select filtered by parent:
+
+```ruby
+field :company_id, input_type: :association_select,
+  input_options: { sort: { name: :asc } }
+
+field :contact_id, input_type: :association_select,
+  input_options: {
+    depends_on: { field: :company_id, foreign_key: :company_id },
+    sort: { last_name: :asc },
+    label_method: :full_name
+  }
+```
+
+**Role-based scope** — different scopes per user role:
+
+```ruby
+field :company_id, input_type: :association_select,
+  input_options: {
+    scope_by_role: { admin: :all, editor: :active_companies, viewer: :my_companies }
+  }
+```
+
+**Multi select** — for `has_many :through` associations:
+
+```ruby
+field :tag_ids, input_type: :multi_select,
+  input_options: { association: :tags, sort: { name: :asc }, max: 5 }
+```
+
+**File upload** — for attachment fields:
+
+```ruby
+field :avatar, input_options: { preview: true, drag_drop: true }
+field :documents, input_options: { preview: true, drag_drop: true, direct_upload: true }
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `preview` | boolean | `false` | Show preview of current file (image thumbnail or filename) |
+| `drag_drop` | boolean | `false` | Enable drag-and-drop upload zone |
+| `direct_upload` | boolean | `false` | Use Active Storage direct upload |
+
+Attachment fields auto-resolve to `input_type: :file_upload`. The drop zone text adapts automatically: "Drop file here" for single attachments, "Drop files here" for multiple.
+
+**Attachment renderers** — for show pages:
+
+```ruby
+section "Photos" do
+  field :avatar, renderer: :attachment_preview, options: { variant: "medium" }
+end
+
+section "Documents" do
+  field :files, renderer: :attachment_list
+end
+
+section "Contract" do
+  field :contract, renderer: :attachment_link
+end
+```
+
+| Renderer | Description |
+|----------|-------------|
+| `:attachment_preview` | Image preview with optional variant, download link for non-images |
+| `:attachment_list` | List of download links with filenames and file sizes |
+| `:attachment_link` | Single download link with filename |
+
+For the complete list of `input_options` keys per input type, see [Presenters Reference — Input Options](presenters.md#input-options).
+
+#### `divider(label: nil)`
+
+Adds a horizontal divider pseudo-field inside a section. Useful for visually separating groups of related fields.
+
+```ruby
+form do
+  section "Contact Details", columns: 2 do
+    field :first_name
+    field :last_name
+    divider label: "Address"
+    field :street, col_span: 2
+    field :city
+    field :zip_code
+  end
+end
+```
+
+#### `info(text)`
+
+Adds an informational text block inside a section. Renders as a styled callout spanning the full width of the grid. Use this to provide contextual help or explanations within a form or show section.
+
+```ruby
+form do
+  section "Pricing", columns: 2 do
+    info "Prices are in USD. Tax is calculated automatically at checkout."
+    field :price, input_type: :number, prefix: "$"
+    field :tax_rate, input_type: :number, suffix: "%"
+  end
+end
+```
+
+Both `divider` and `info` are available in `section` blocks for both `show` and `form` views.
+
+## Search Configuration
+
+The `search` block configures search and filtering.
+
+```ruby
+search do
+  searchable_fields :title, :description
+  placeholder "Search projects..."
+  filter :all, label: "All", default: true
+  filter :active, label: "Active", scope: :active
+  filter :recent, label: "Recent", scope: :recent
+end
+```
+
+To disable search entirely, use the keyword argument form:
+
+```ruby
+search enabled: false
+```
+
+### Search Methods
+
+#### `enabled(value)`
+
+Whether search is enabled. Default: `true`.
+
+#### `searchable_fields(*fields)`
+
+Fields to search against when the user types a query.
+
+```ruby
+searchable_fields :title, :description, :email
+```
+
+#### `placeholder(value)`
+
+Placeholder text for the search input.
+
+#### `auto_search(value = true)`
+
+Enables auto-submit on the search form. When `true`, the form submits automatically as the user types after a debounce delay.
+
+```ruby
+search do
+  auto_search true
+end
+```
+
+#### `debounce_ms(value)`
+
+Sets the debounce delay in milliseconds before auto-submit triggers. Default: `300`.
+
+```ruby
+debounce_ms 300
+```
+
+#### `min_query_length(value)`
+
+Minimum number of characters before auto-submit triggers. Empty input (length 0) always triggers to clear the search. Default: `2`.
+
+```ruby
+min_query_length 2
+```
+
+#### `filter(name, label:, default: false, scope: nil)`
+
+Adds a predefined filter tab.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `name` | symbol | Filter identifier |
+| `label:` | string | Display text |
+| `default:` | boolean | Whether this filter is selected by default |
+| `scope:` | symbol | Model scope to apply (must be defined in the model) |
+
+#### `parameter(name, type:, field: nil, **opts)`
+
+Adds a typed filter control to the search toolbar. See [Presenters Reference — Search Parameters](presenters.md#search-parameters) for all attributes.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `name` | symbol | Parameter identifier |
+| `type:` | symbol | Control type: `:enum_select`, `:association_select`, `:boolean_select`, `:number_range`, `:date_range` |
+| `field:` | symbol | Model field name to filter by |
+
+Additional keyword options: `model:`, `options:`, `label_key:`, `label_method:`, `include_blank:`, `visible_when:`, `search:`, `min_query_length:`, `per_page:`, `col_span:`.
+
+```ruby
+search do
+  columns 2
+  searchable_fields :name, :email
+
+  parameter :status, type: :enum_select, field: :status
+  parameter :department, type: :association_select, field: :department_id,
+            label_method: :full_name, include_blank: "Any department"
+  parameter :active, type: :boolean_select, field: :active
+  parameter :salary_range, type: :number_range, field: :salary
+  parameter :hired, type: :date_range, field: :hired_at
+  parameter :tenant, type: :association_select, model: :tenant, field: :tenant_id,
+            visible_when: { role: :admin }
+end
+```
+
+#### `columns(value)`
+
+Sets the number of grid columns for the search parameter layout. Default: `1` (single column, one parameter per row). Labels are displayed inline beside controls.
+
+#### `responsive(value)`
+
+Sets responsive column overrides per breakpoint.
+
+```ruby
+search do
+  columns 3
+  responsive mobile: { columns: 1 }, tablet: { columns: 2 }
+end
+```
+
+#### `advanced_filter { ... }`
+
+Configures the visual filter builder. See [Presenters Reference — Advanced Filter](presenters.md#advanced-filter-attributes) for all options.
+
+```ruby
+search do
+  advanced_filter do
+    enabled true
+    max_conditions 20
+    allow_or_groups true
+    query_language true
+    filterable_fields :title, :status, :price, "department.name"
+    field_options :status, operators: %i[eq not_eq in not_in]
+
+    preset :expensive,
+      label: "Expensive items",
+      conditions: [
+        { field: "price", operator: "gteq", value: "100" }
+      ]
+
+    saved_filters do
+      enabled true
+      display :inline
+      max_visible_pinned 5
+    end
+  end
+end
+```
+
+##### `saved_filters { ... }`
+
+Nested inside `advanced_filter`, enables user-persistent named filters.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `enabled(value)` | boolean | Enable saved filters (default: `false`) |
+| `display(value)` | symbol | Display mode: `:inline`, `:dropdown`, `:sidebar` (default: `:inline`) |
+| `max_visible_pinned(value)` | integer | Max pinned filters shown directly (default: `3`) |
+
+See [Presenters Reference — Saved Filter Attributes](presenters.md#saved-filter-attributes) for full details.
+
+## Export Configuration
+
+Enables data export from the presenter. See [Export Reference](export.md) for full details.
+
+```ruby
+export formats: [:csv, :xlsx], max_records: 5000, save_history: true
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `formats:` | array | `[:csv]` | Available formats: `:csv`, `:xlsx` |
+| `max_records:` | integer | `10000` | Safety limit for export size |
+| `save_history:` | boolean | `false` | Log exports to `export_log` model |
+| `fields:` | array | all readable | Field ceiling for the picker |
+| `csv_delimiter:` | string | `","` | CSV column separator |
+
+## Import Configuration
+
+Enables data import for the presenter. See [Import Reference](import.md) for full details.
+
+```ruby
+import formats: [:csv, :xlsx], max_rows: 5000,
+  nested_associations: [:employee_profile],
+  nested_blank_strategy: "skip",
+  parsing: { date_format: ["%d.%m.%Y", "%Y-%m-%d"] }
+```
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| `formats:` | array | `[:csv]` | Accepted formats: `:csv`, `:xlsx` |
+| `max_rows:` | integer | `10000` | Safety limit for import size |
+| `max_file_size:` | integer | `10485760` | Maximum file size in bytes |
+| `csv_delimiter:` | string | `","` | CSV column separator |
+| `csv_encoding:` | string | `"auto"` | CSV encoding detection |
+| `parsing:` | hash | `{}` | Type coercion options |
+| `nested_associations:` | array | `nil` (all) | Whitelist of `has_one` associations for import |
+| `nested_blank_strategy:` | string | `"null"` | `"null"` (set to nil) or `"skip"` (omit blank fields) |
+
+## Actions
+
+Actions are defined at the top level of the presenter (not inside a block).
+
+```ruby
+action :create, type: :built_in, on: :collection, label: "New Deal", icon: "plus"
+action :show,   type: :built_in, on: :single, icon: "eye"
+action :edit,   type: :built_in, on: :single, icon: "pencil"
+action :destroy, type: :built_in, on: :single, icon: "trash", confirm: true, style: :danger
+```
+
+### Action Arguments
+
+| Argument | Required | Type | Description |
+|----------|----------|------|-------------|
+| `name` | yes | symbol | Action identifier |
+| `type:` | yes | symbol | `:built_in` or `:custom` |
+| `on:` | yes | symbol | `:collection`, `:single`, or `:batch` |
+
+### Action Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label:` | string | Button/link text |
+| `icon:` | string | Icon identifier |
+| `confirm:` | boolean | Show confirmation dialog |
+| `confirm_message:` | string | Custom confirmation message |
+| `style:` | symbol | Visual style (e.g., `:danger`) |
+| `visible_when:` | hash | Condition for visibility (see below) |
+| `disable_when:` | hash | Condition for disabling the action (see [Conditional Rendering](../guides/conditional-rendering.md)) |
+| `batch:` | boolean or hash | Single actions only. `true` auto-derives a batch action; a Hash merges batch-specific overrides (e.g., `batch: { select_all_filter: false }`). See [Batch Actions Guide](../guides/batch-actions.md#auto-derived-batch-actions). |
+
+### Batch-Specific Options (for `on: :batch` or `batch:` hash overrides)
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `min_selection:` | integer | Minimum records that must be selected |
+| `max_selection:` | integer | Maximum records that can be selected |
+| `max_batch_records:` | integer | Server-side limit on records affected |
+| `result_log:` | boolean | Enable per-record result tracking |
+| `select_all_filter:` | boolean | Allow "select all matching filter" mode |
+| `execution:` | symbol | `:inline`, `:background`, or `:auto` |
+| `background_threshold:` | integer | Threshold for `:auto` mode |
+| `strategy:` | symbol | Batch strategy |
+| `fields:` | array | Fields for batch update |
+
+### `visible_when` Conditions
+
+Custom actions can be conditionally visible based on record field values:
+
+```ruby
+action :close_won, type: :custom, on: :single,
+  label: "Close as Won", icon: "check-circle",
+  confirm: true, confirm_message: "Mark this deal as won?",
+  visible_when: { field: :stage, operator: :not_in, value: [:closed_won, :closed_lost] }
+```
+
+See [Condition Operators](condition-operators.md) for available operators.
+
+### Form Actions
+
+Form actions define submit buttons on create/edit forms. Use `form_action` instead of `action` — context is implicit (`on: :form`).
+
+```ruby
+form_action :save, type: :built_in, style: :primary, redirect: :show
+form_action :save_and_new, label: "Save & New", style: :secondary,
+  redirect: :new, only_on: :create
+form_action :save_and_stay, label: "Save & Continue", style: :secondary,
+  redirect: :edit, only_on: :update
+form_action :cancel, type: :built_in, style: :secondary
+```
+
+### Form Action Arguments
+
+| Argument | Required | Type | Description |
+|----------|----------|------|-------------|
+| `name` | yes | symbol | Action identifier |
+
+### Form Action Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type:` | symbol | `:built_in` for `save`/`cancel`. Omit for custom form actions. |
+| `label:` | string | Button text |
+| `icon:` | string | Icon identifier |
+| `style:` | symbol | `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:outline` |
+| `redirect:` | symbol or hash | `:show`, `:edit`, `:new`, `:index`. Hash: `{ association: :order, action: :show }` or `{ presenter: "line_items", action: :new, defaults: { order_id: { field_ref: :id } } }`. Ignored in dialog context. |
+| `set_fields:` | hash | Fields to set before save (same syntax as workflow `set_fields`) |
+| `only_on:` | symbol | `:create` or `:update` — filter by form context |
+| `only_roles:` | array | Roles that see this button |
+| `except_roles:` | array | Roles excluded from seeing this button |
+| `confirm:` | boolean | Show confirmation dialog |
+| `confirm_message:` | string | Custom confirmation text |
+| `visible_when:` | hash | Condition for visibility |
+| `disable_when:` | hash | Condition for disabled state |
+| `dialog_behavior:` | symbol | `:close`, `:reset`, `:reload` (dialog context only) |
+| `pipeline:` | array | Ordered operation sequence in a single transaction. Steps: `:save`, `{ transition: :name }`, `{ action: :name }`. |
+| `transition:` | symbol | Sugar for `pipeline: [:save, { transition: :name }]`. Cannot combine with `pipeline:` or `action:`. |
+| `action:` | symbol | Sugar for `pipeline: [:save, { action: :name }]`. Cannot combine with `pipeline:` or `transition:`. |
+| `position:` | symbol | `:inline` (default) or `:dropdown` (forced into overflow menu). |
+
+### Form Action Example
+
+```ruby
+define_presenter :article_editor do
+  model :article
+  slug "article-editor"
+
+  form do
+    section "Content" do
+      field :title
+      field :body, input_type: :rich_text_editor
+      field :status
+    end
+  end
+
+  form_action :save_draft, label: "Save Draft", style: :secondary, redirect: :edit
+  form_action :save_and_publish, label: "Publish", style: :primary, icon: "globe",
+    set_fields: { status: "published", published_at: { date: :now } },
+    confirm: true, redirect: :show,
+    visible_when: { field: :status, operator: :not_eq, value: "published" }
+  form_action :cancel, type: :built_in, style: :secondary
+end
+```
+
+### Pipeline Example
+
+Pipeline form actions compose multiple operations (save, workflow transition, custom action) in a single transaction:
+
+```ruby
+define_presenter :purchase_order_editor do
+  model :purchase_order
+  slug "po-editor"
+
+  form do
+    section "PO Details" do
+      field :title
+      field :amount, input_type: :number, prefix: "$"
+      field :status
+    end
+  end
+
+  # Simple save (default pipeline: [:save])
+  form_action :save_draft, label: "Save Draft", style: :secondary, redirect: :edit
+
+  # Sugar: transition: expands to pipeline: [:save, { transition: :submit }]
+  form_action :save_and_submit, label: "Save & Submit", style: :primary, icon: "send",
+    transition: :submit, confirm: true,
+    confirm_message: "Submit for approval?",
+    visible_when: { field: :status, operator: :eq, value: "draft" },
+    redirect: :show
+
+  # Explicit pipeline: save + transition + custom action
+  form_action :save_submit_and_notify, label: "Submit & Notify", style: :primary,
+    pipeline: [:save, { transition: :submit }, { action: :notify_approvers }],
+    confirm: true, redirect: :show
+
+  form_action :cancel, type: :built_in, style: :secondary
+end
+```
+
+When no `form_action` is defined, the platform renders default Save and Cancel buttons. See the [Action Buttons & Pipelines Guide](../guides/action-buttons.md) for the full walkthrough, and the [Form Actions Reference](presenters.md#form-actions) for the attribute table.
+
+## Navigation
+
+```ruby
+navigation menu: :main, position: 3
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `menu:` | symbol | Menu group (e.g., `:main`, `:public`) |
+| `position:` | integer | Sort order within the menu (optional) |
+
+## Inheritance
+
+Presenters can inherit from other presenters using the `inherits:` option. This copies the parent's configuration and lets the child override specific sections.
+
+```ruby
+# config/lcp_ruby/presenters/deal_pipeline.rb
+define_presenter :deal_pipeline, inherits: :deal do
+  label "Deal Pipeline"
+  slug "pipeline"
+  icon "bar-chart"
+  read_only true
+
+  index do
+    default_view :table
+    per_page 50
+    column :title, link_to: :show, sortable: true
+    column :stage, renderer: :badge, sortable: true
+  end
+
+  search enabled: false
+
+  action :show, type: :built_in, on: :single, icon: "eye"
+
+  navigation menu: :main, position: 4
+end
+```
+
+### Inheritance Semantics
+
+- **Section-level replace**: If a child defines `index`, `show`, `form`, `search`, `actions`, or `navigation`, the child's version completely replaces the parent's. There is no deep merge.
+- **Unset sections are inherited**: If the child does not define a section, the parent's version is used as-is.
+- **Top-level attributes**: `name`, `label`, `slug`, `icon`, `read_only`, `embeddable` are always taken from the child when defined. The `model` is inherited from the parent unless the child overrides it.
+- **Parent must exist**: The parent presenter must be defined in a DSL file in the same directory. Referencing a nonexistent parent raises `MetadataError`.
+- **No circular inheritance**: Circular chains (A inherits B, B inherits A) are detected and raise `MetadataError`.
+
+Inheritance is purely a DSL convenience — the result is always a flat hash identical to what you could write in YAML with full duplication.
+
+## Advanced Field Paths
+
+### Dot-Notation (Association Traversal)
+
+Use string field names with dot-notation to traverse associations:
+
+```ruby
+index do
+  column "company.name", sortable: true            # belongs_to
+  column "company.industry", renderer: :badge        # with renderer
+  column "contacts.full_name", renderer: :collection # has_many
+end
+
+show do
+  section "Details" do
+    field "company.name"
+    field "company.industry", renderer: :badge
+    field "contacts.full_name", renderer: :collection,
+      options: { limit: 5, separator: " | " }
+  end
+end
+```
+
+### Template Syntax
+
+Use `{field}` syntax in string field names:
+
+```ruby
+index do
+  column "{first_name} {last_name}"
+  column "{company.name}: {title}"
+end
+```
+
+### Collection Renderer
+
+The `collection` renderer renders arrays from has_many dot-paths:
+
+```ruby
+index do
+  column "contacts.full_name", renderer: :collection,
+    options: { limit: 3, overflow: "...", separator: ", " }
+end
+```
+
+### Custom Renderers
+
+Reference custom renderers (from `app/renderers/`) by name:
+
+```ruby
+index do
+  column :stage, renderer: :conditional_badge,
+    options: { rules: [...] }
+end
+```
+
+## DSL vs YAML Equivalence
+
+| DSL | YAML Equivalent |
+|-----|----------------|
+| `model :deal` | `model: deal` |
+| `label "Deals"` | `label: "Deals"` |
+| `slug "deals"` | `slug: deals` |
+| `read_only true` | `read_only: true` |
+| `index do ... end` | `index: { ... }` |
+| `includes :company` | `index: { includes: [company] }` |
+| `eager_load :company` | `index: { eager_load: [company] }` |
+| `reorderable true` | `index: { reorderable: true }` |
+| `column :title, sortable: true` | `table_columns: [{ field: title, sortable: true }]` |
+| `row_click :show` | `index: { row_click: show }` |
+| `empty_message "No records."` | `index: { empty_message: "No records." }` |
+| `actions_position :inline` | `index: { actions_position: inline }` |
+| `show do section "Info", responsive: {...} do ... end end` | `show: { layout: [{ section: "Info", responsive: {...}, ... }] }` |
+| `show do section "X", visible_when: { field: :f, operator: :eq, value: "v" } do ... end end` | `show: { layout: [{ section: "X", visible_when: { field: f, operator: eq, value: v }, ... }] }` |
+| `association_list "X", association: :y` | `{ section: "X", type: association_list, association: y }` |
+| `association_list "X", association: :y, display_template: :default, link: true, sort: { name: :asc }, limit: 5, empty_message: "None.", scope: :active` | `{ section: "X", type: association_list, association: y, display_template: default, link: true, sort: { name: asc }, limit: 5, empty_message: "None.", scope: active }` |
+| `association_list "X", association: :y, link_through: :z` | `{ section: "X", type: association_list, association: y, link_through: z }` |
+| `form do layout :tabs end` | `form: { layout: tabs }` |
+| `form do section "Details", collapsible: true do ... end end` | `form: { sections: [{ title: "Details", collapsible: true, ... }] }` |
+| `nested_fields "Items", association: :items do ... end` | `form: { sections: [{ type: nested_fields, title: "Items", association: items, ... }] }` |
+| `nested_fields "Steps", json_field: :steps do ... end` | `form: { sections: [{ type: nested_fields, title: "Steps", json_field: steps, ... }] }` |
+| `nested_fields "Addr", json_field: :addresses, target_model: :address do ... end` | `form: { sections: [{ type: nested_fields, title: "Addr", json_field: addresses, target_model: address, ... }] }` |
+| `divider label: "Address"` | `fields: [{ type: divider, label: "Address" }]` |
+| `field :x, col_span: 2, hint: "Help"` | `fields: [{ field: x, col_span: 2, hint: "Help" }]` |
+| `field :x, visible_when: { field: :status, operator: :eq, value: "active" }` | `fields: [{ field: x, visible_when: { field: status, operator: eq, value: active } }]` |
+| `field :x, disable_when: { field: :status, operator: :blank }` | `fields: [{ field: x, disable_when: { field: status, operator: blank } }]` |
+| `index do render_with "x/y" end` | `index: { render_with: "x/y" }` |
+| `show do render_with "x/y" end` | `show: { render_with: "x/y" }` |
+| `show do custom_section "X", partial: "x/y" end` | `show: { layout: [{ section: "X", type: custom, partial: "x/y" }] }` |
+| `form do custom_section "X", partial: "x/y", additional_permitted_params: ["z"] end` | `form: { sections: [{ title: "X", type: custom, partial: "x/y", additional_permitted_params: [z] }] }` |
+| `search do ... end` | `search: { ... }` |
+| `search enabled: false` | `search: { enabled: false }` |
+| `action :show, type: :built_in, on: :single` | `actions: { single: [{ name: show, type: built_in }] }` |
+| `navigation menu: :main, position: 1` | `navigation: { menu: main, position: 1 }` |
+
+For the full YAML attribute reference, see [Presenters Reference](presenters.md).
+
+## Complete Example
+
+A deal management presenter demonstrating all DSL features:
+
+```ruby
+# config/lcp_ruby/presenters/deal.rb
+define_presenter :deal do
+  model :deal
+  label "Deals"
+  slug "deals"
+  icon "dollar-sign"
+
+  index do
+    default_view :table
+    default_sort :created_at, :desc
+    per_page 25
+    row_click :show
+    empty_message "No deals yet. Create your first deal to get started."
+    actions_position :dropdown
+    column :title, width: "30%", link_to: :show, sortable: true, pinned: :left
+    column :stage, width: "20%", renderer: :badge, sortable: true,
+      options: { color_map: { lead: "blue", closed_won: "green", closed_lost: "red" } }
+    column :value, width: "20%", renderer: :currency, sortable: true,
+      summary: :sum, hidden_on: :mobile
+  end
+
+  show do
+    section "Deal Information", columns: 2, responsive: { mobile: 1 } do
+      field :title, renderer: :heading, col_span: 2
+      field :stage, renderer: :badge
+      field :value, renderer: :currency
+    end
+  end
+
+  form do
+    layout :tabs
+
+    section "Deal Details", columns: 2, responsive: { mobile: 1 } do
+      field :title, placeholder: "Deal title...", autofocus: true,
+        hint: "A short descriptive name for the deal"
+      field :stage, input_type: :select
+      field :value, input_type: :number, prefix: "$", col_span: 1
+      field :company_id, input_type: :association_select
+      field :contact_id, input_type: :association_select
+    end
+
+    section "Additional Info", collapsible: true, collapsed: true do
+      field :description, input_type: :textarea, col_span: 2
+      divider label: "Internal"
+      field :notes, input_type: :textarea, readonly: true,
+        visible_when: { field: :stage, operator: :not_eq, value: "lead" }
+    end
+
+    nested_fields "Line Items", association: :line_items,
+      allow_add: true, allow_remove: true,
+      max: 20, add_label: "Add Line Item",
+      empty_message: "No line items.", columns: 3 do
+        field :product_name, placeholder: "Product..."
+        field :quantity, input_type: :number, default: 1
+        field :unit_price, input_type: :number, prefix: "$"
+    end
+  end
+
+  search do
+    searchable_fields :title
+    placeholder "Search deals..."
+    filter :all, label: "All", default: true
+    filter :open, label: "Open", scope: :open_deals
+    filter :won, label: "Won", scope: :won
+    filter :lost, label: "Lost", scope: :lost
+  end
+
+  action :create, type: :built_in, on: :collection, label: "New Deal", icon: "plus"
+  action :show,   type: :built_in, on: :single, icon: "eye"
+  action :edit,   type: :built_in, on: :single, icon: "pencil"
+  action :close_won, type: :custom, on: :single,
+    label: "Close as Won", icon: "check-circle",
+    confirm: true, confirm_message: "Mark this deal as won?",
+    visible_when: { field: :stage, operator: :not_in, value: [:closed_won, :closed_lost] }
+  action :destroy, type: :built_in, on: :single, icon: "trash", confirm: true, style: :danger
+
+  navigation menu: :main, position: 3
+end
+```
+
+Source: `lib/lcp_ruby/dsl/presenter_builder.rb`, `lib/lcp_ruby/dsl/dsl_loader.rb`