lcp 0.1.0

data/docs/guides/composite-pages.md

@@ -0,0 +1,1290 @@
+# Composite Pages Guide
+
+Composite pages display a record with multiple related zones — a detail header, tabbed sub-tables, an optional sidebar, and below-content areas. This guide walks through building a typical master-detail page.
+
+For the full attribute reference, see the [Pages Reference](../reference/pages.md#composite-pages-semantic-layout).
+
+## When to Use Composite Pages
+
+Use composite pages when a single record's show page needs to display related data from other models. Common examples:
+
+- Employee detail with tabs for leave requests, trainings, and evaluations
+- Company 360-degree view with contacts, deals, and activity feed
+- Order detail with line items, shipments, and payment history
+
+If you only need a standalone overview with KPI cards and widgets, use a [Dashboard](dashboards.md) instead (standalone page with `layout: grid`).
+
+## Quick Start
+
+### 1. Define the Models
+
+You need a primary model and one or more related models:
+
+```yaml
+# config/lcp_ruby/models/employee.yml
+model:
+  name: employee
+  fields:
+    - { name: name, type: string }
+    - { name: email, type: email }
+    - { name: department, type: string }
+    - { name: status, type: enum, enum_values: [active, inactive] }
+
+# config/lcp_ruby/models/leave_request.yml
+model:
+  name: leave_request
+  fields:
+    - { name: employee_id, type: integer }
+    - { name: start_date, type: date }
+    - { name: end_date, type: date }
+    - { name: status, type: enum, enum_values: [pending, approved, rejected] }
+    - { name: reason, type: string }
+  associations:
+    - { type: belongs_to, name: employee }
+
+# config/lcp_ruby/models/training.yml
+model:
+  name: training
+  fields:
+    - { name: employee_id, type: integer }
+    - { name: title, type: string }
+    - { name: status, type: enum, enum_values: [scheduled, completed, cancelled] }
+  associations:
+    - { type: belongs_to, name: employee }
+```
+
+### 2. Create Presenters for Each Zone
+
+Each zone in a composite page renders a presenter. The main zone typically uses a show presenter, while tab zones use index presenters:
+
+```yaml
+# config/lcp_ruby/presenters/employee_detail.yml
+presenter:
+  name: employee_detail
+  model: employee
+  slug: employees
+  show:
+    layout:
+      - section: Details
+        fields:
+          - { field: name }
+          - { field: email }
+          - { field: department }
+          - { field: status }
+  actions:
+    single:
+      - { name: edit, type: built_in }
+
+# config/lcp_ruby/presenters/leave_requests_index.yml
+presenter:
+  name: leave_requests_index
+  model: leave_request
+  index:
+    table_columns:
+      - { field: start_date }
+      - { field: end_date }
+      - { field: status }
+      - { field: reason }
+
+# config/lcp_ruby/presenters/trainings_index.yml
+presenter:
+  name: trainings_index
+  model: training
+  index:
+    table_columns:
+      - { field: title }
+      - { field: status }
+```
+
+### 3. Define the Composite Page
+
+Create a page YAML that combines the presenters into zones:
+
+```yaml
+# config/lcp_ruby/pages/employee_detail.yml
+page:
+  name: employee_detail
+  model: employee
+  slug: employees
+  zones:
+    - name: header
+      presenter: employee_detail
+      area: main
+
+    - name: leave_requests
+      presenter: leave_requests_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.leave_requests
+      scope_context:
+        employee_id: ":record.id"
+
+    - name: trainings
+      presenter: trainings_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.trainings
+      scope_context:
+        employee_id: ":record.id"
+```
+
+### 4. Set Up Permissions
+
+Each zone's presenter model needs permissions. If a role has no presenter access for a zone's model, that zone (and its tab) is hidden:
+
+```yaml
+# config/lcp_ruby/permissions/employee.yml
+permissions:
+  model: employee
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      presenters: all
+      fields:
+        readable: all
+        writable: all
+    viewer:
+      crud: [index, show]
+      presenters: all
+      fields:
+        readable: all
+
+# config/lcp_ruby/permissions/leave_request.yml
+permissions:
+  model: leave_request
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      presenters: all
+      fields:
+        readable: all
+        writable: all
+    viewer:
+      crud: [index, show]
+      presenters: all
+      fields:
+        readable: all
+
+# config/lcp_ruby/permissions/training.yml
+permissions:
+  model: training
+  roles:
+    admin:
+      crud: [index, show]
+      presenters: all
+      fields:
+        readable: all
+    viewer:
+      crud: [index]
+      presenters: []    # No presenter access -> training tab hidden for viewers
+      fields:
+        readable: all
+```
+
+In this example, users with the `viewer` role see the employee detail and leave requests tab, but the trainings tab is hidden because `presenters: []` denies presenter access.
+
+### 5. Add Translations (optional)
+
+```yaml
+# config/locales/en.yml
+en:
+  pages:
+    employee_detail:
+      tabs:
+        leave_requests: "Leave Requests"
+        trainings: "Trainings"
+```
+
+If translations are missing, tabs fall back to the humanized zone name (e.g., "Leave requests").
+
+## Areas
+
+Composite pages use **semantic layout** with four named areas:
+
+```
++---------------------------+----------+
+|         main              | sidebar  |
++---------------------------+----------+
+| tabs: [tab1] [tab2]                  |
+| +-----------------------------------+|
+| | active tab content                ||
+| +-----------------------------------+|
++---------------------------------------+
+| below                                 |
++---------------------------------------+
+```
+
+| Area | Description | Typical use |
+|------|-------------|-------------|
+| `main` | Primary record details | Show presenter (header section) |
+| `sidebar` | Side panel | Notes, quick stats, related links |
+| `tabs` | Tabbed content with tab bar | Related record tables (leave requests, trainings) |
+| `below` | Full-width area below tabs | Activity log, audit trail |
+
+Zones default to `area: main` if not specified.
+
+## scope_context
+
+The `scope_context` attribute scopes a zone's data query to the parent record. Without it, a tab would show all records from the model, not just those related to the current employee.
+
+Each key is a column name on the zone's model, and each value is a dynamic reference or static value:
+
+```yaml
+# Most common: scope by parent record ID
+scope_context:
+  employee_id: ":record.id"
+
+# Scope by a field on the parent record
+scope_context:
+  department_id: ":record.department_id"
+
+# Scope to the current user
+scope_context:
+  assigned_to_id: ":current_user.id"
+
+# Multiple conditions
+scope_context:
+  employee_id: ":record.id"
+  year: ":current_year"
+```
+
+**Available dynamic references:**
+
+| Reference | Resolves to |
+|-----------|-------------|
+| `:record.id` | Parent record's `id` |
+| `:record.<field>` | Field value from the parent record (single-level dot-path only) |
+| `:current_user` | The full `current_user` object (useful with `filter_*` interceptors) |
+| `:current_user.id` | Current user's `id` |
+| `:selection_id` | Selected record's `id` from `?selected=N` (master-detail only) |
+| `:current_year` | Current year (integer) |
+| `:current_date` | Today's date |
+
+Static values (without `:` prefix) pass through unchanged.
+
+**Dot-path depth:** Only single-level paths are supported (e.g., `:record.department_id`). Multi-level paths like `:record.department.company_id` raise an error.
+
+**Scope application:** For each `scope_context` key, the platform first checks if the zone's model defines a `filter_<key>` class method. If found, that method is called (both 2-arg `(scope, value)` and 3-arg `(scope, value, evaluator)` signatures are supported). Otherwise, a plain `where(key => value)` clause is applied. If neither a filter method nor a column exists, a warning is logged and the key is skipped.
+
+## Tab Navigation
+
+Tabs use **Turbo Frames** for fast, no-full-page-reload switching. Each tab's content is loaded from a dedicated zone endpoint:
+
+```
+GET /employees/123/zones/leave_requests   → leave requests tab content
+GET /employees/123/zones/trainings        → trainings tab content
+```
+
+The URL updates to `?tab=<zone_name>` via `history.replaceState` for bookmarkability:
+
+```
+/employees/123              → first tab active (leave_requests)
+/employees/123?tab=trainings → trainings tab active
+```
+
+Tab content is always loaded from the zone endpoint (including the initially active tab). Links inside the tab content (pagination, sort) stay within the Turbo Frame.
+
+### Zone Endpoint
+
+The zone endpoint (`GET /:slug/:id/zones/:zone_name`) renders a single zone's content as a `<turbo-frame>` fragment. It supports pagination and sorting:
+
+```
+/employees/123/zones/leave_requests?page=2
+/employees/123/zones/leave_requests?sort=start_date&direction=desc
+```
+
+### Reloading Zones from Dialogs
+
+After a dialog action, use `on_success: reload_zone` or `on_success: reload_zones` to refresh specific zones without reloading the entire page:
+
+```yaml
+actions:
+  single:
+    - name: add_leave
+      type: dialog
+      dialog:
+        page: leave_request_form
+        on_success: reload_zone
+        reload_zone: leave_requests
+```
+
+See the [Dialogs Guide](dialogs.md#zone-reload-after-dialog) for details.
+
+## Adding a Sidebar
+
+The sidebar area renders alongside the main content. Both presenter and widget zones work in the sidebar:
+
+```yaml
+page:
+  name: employee_detail
+  model: employee
+  slug: employees
+  zones:
+    - name: header
+      presenter: employee_detail
+      area: main
+
+    - name: leave_count
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: leave_request
+        aggregate: count
+        label_key: pages.employee_detail.sidebar.leave_count
+      scope_context:
+        employee_id: ":record.id"
+
+    - name: leave_requests
+      presenter: leave_requests_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.leave
+      scope_context:
+        employee_id: ":record.id"
+```
+
+The sidebar renders alongside the main area (2:1 column ratio by default). On screens narrower than 768px, it stacks below the main content.
+
+### Custom Main/Sidebar Proportions
+
+Use the `width` attribute (1–12) to control the column ratio:
+
+```yaml
+zones:
+  - name: header
+    presenter: employee_detail
+    area: main
+    width: 9         # 9 of 12 columns
+
+  - name: quick_stats
+    type: widget
+    area: sidebar
+    width: 3         # 3 of 12 columns
+    widget:
+      type: kpi_card
+      model: leave_request
+      aggregate: count
+    scope_context:
+      employee_id: ":record.id"
+```
+
+When both zones specify `width`, the layout uses `9fr 3fr` instead of the default `8fr 4fr`.
+
+## Zone Filtering
+
+Each zone can have its own search/filtering UI, configured via the `filters` attribute:
+
+| Value | Description |
+|-------|-------------|
+| `quick` | Quick search text input (default for tab zones) |
+| `full` | Quick search + full advanced filter pipeline (Ransack, custom filters, custom fields) |
+| `none` | No filtering (default for main, sidebar, below zones) |
+
+```yaml
+zones:
+  - name: leave_requests
+    presenter: leave_requests_index
+    area: tabs
+    label_key: pages.employee_detail.tabs.leave
+    scope_context:
+      employee_id: ":record.id"
+    filters: quick     # default for tabs — can be omitted
+
+  - name: trainings
+    presenter: trainings_index
+    area: tabs
+    label_key: pages.employee_detail.tabs.trainings
+    scope_context:
+      employee_id: ":record.id"
+    filters: full      # enable advanced filtering for this tab
+```
+
+The search form renders inside the zone's Turbo Frame, so filtering does not reload the page. The search query is preserved across pagination and sorting.
+
+**Widget zones** always use `filters: none` — setting a different value produces a validation error.
+
+## Record Click Behavior
+
+By default, clicking a row in a presenter zone table navigates to the record's show page. Use `record_click` to change this:
+
+```yaml
+zones:
+  - name: leave_requests
+    presenter: leave_requests_index
+    area: tabs
+    scope_context:
+      employee_id: ":record.id"
+    record_click: dialog     # open in modal without leaving the page
+
+  - name: audit_log
+    presenter: audit_entries
+    area: below
+    scope_context:
+      record_id: ":record.id"
+    record_click: none       # rows are not clickable
+```
+
+| Value | Behavior |
+|-------|----------|
+| `navigate` | Full-page navigation to record show page (default) |
+| `dialog` | Opens record show in a modal dialog — keeps user on the composite page |
+| `none` | No click action — rows are plain, not clickable |
+
+**`dialog` mode** is especially useful for tab zones on composite pages — users can view related record details without losing their place. The dialog renders the record's show sections in a read-only view.
+
+**Slug requirement:** Both `navigate` and `dialog` require the zone's presenter to have a routable slug. If no slug exists, rows degrade to non-clickable. A boot-time warning is produced in this case.
+
+## Default Scope
+
+The `default_scope` attribute applies a named scope to the zone's query before the `scope` attribute. Both are cumulative:
+
+```yaml
+zones:
+  - name: recent_active_tasks
+    presenter: tasks_index
+    area: tabs
+    scope_context:
+      employee_id: ":record.id"
+    default_scope: active    # applied first: only active records
+    scope: recent            # applied second: most recent of the active ones
+```
+
+This is useful when you want a base filter that always applies (e.g., `active`, `published`) while allowing the `scope` attribute to further narrow the dataset.
+
+## Conditional Zone Visibility
+
+Use `visible_when` to restrict zone visibility:
+
+```yaml
+zones:
+  - name: audit_log
+    presenter: audit_entries
+    area: below
+    scope_context:
+      record_id: ":record.id"
+    visible_when:
+      role: admin
+```
+
+This supports the same condition syntax as presenter `visible_when` — role shortcuts and full condition objects.
+
+## Claimed Presenters
+
+Presenters used as zones in a composite page are "claimed" — they do not get auto-generated pages. This prevents duplicate routes (e.g., `/leave-requests` would not exist separately since `leave_requests_index` is embedded in the employee detail page).
+
+If you need the presenter to also be accessible as a standalone page, create a separate page definition for it.
+
+## Index Presenter Override
+
+When a composite page owns a slug (e.g., `slug: companies`), both the index and show actions route through it. The main zone typically uses a show-only presenter with no index columns. To keep the index table working, specify `index_presenter:` — a separate presenter with index columns for the index action:
+
+```yaml
+page:
+  name: company_detail
+  model: company
+  slug: companies
+  index_presenter: company    # Used for GET /companies (index)
+  zones:
+    - name: company_header
+      presenter: company_show_zone   # Used for GET /companies/:id (show)
+      area: main
+    # ...sidebar, tabs, below zones...
+```
+
+The `index_presenter` must have `index.columns` defined and use the same model as the page. It is only used for the index action — show, edit, and other actions use the main zone presenter.
+
+## Form Zones
+
+A form zone embeds an edit form in the composite page's main area instead of a read-only show view. After successful save, the user stays on the same composite page.
+
+```yaml
+page:
+  name: order_detail
+  model: order
+  slug: orders
+  zones:
+    - name: order_form
+      presenter: order_edit
+      area: main
+      submit_redirect: self
+
+    - name: order_lines
+      presenter: order_lines_index
+      area: below
+      scope_context:
+        order_id: ":record.id"
+```
+
+The form zone's presenter must have `form.sections` defined. Users need both `show` and `update` permissions. On validation error, the entire composite page re-renders with the form showing errors while other zones (sidebar, tabs, below) remain intact.
+
+## Record Source Zones
+
+A `record_source` zone loads a single record by ID from a URL parameter. This is useful for dialog composite pages where a sidebar shows a related record.
+
+```yaml
+zones:
+  - name: source_item
+    presenter: inventory_item_show
+    area: sidebar
+    width: 4
+    record_source:
+      param: source_id      # loads from ?source_id=N
+```
+
+The zone renders the record's show sections. When the parameter is missing or the record is not found, the zone is hidden. `record_source` is mutually exclusive with `scope_context`.
+
+## Validation
+
+The configuration validator checks composite page definitions at boot:
+
+- `scope_context` keys must be valid columns on the zone's model (warning)
+- Dynamic references must use recognized formats (`:record.id`, `:record.<field>`, etc.) (warning)
+- `:record.<field>` references are validated against the page's primary model (warning)
+- Tab zones without `label_key` produce a warning (tabs fall back to humanized zone name, but explicit labels are recommended)
+- Main zone must not be an index presenter when tabs are present (error — prevents query parameter collisions)
+- Main zone presenter model should match the page's `model:` attribute (warning)
+- Max zones per page: warning >10, error >20 (auto-generated pages are exempt)
+- Zone `width` must be 1–12 when specified (error)
+- Zone `default_scope` must exist as a named scope on the zone's model (error)
+- Widget zones cannot have `filters` other than `none` (error)
+- `record_click` != `none` with no routable slug produces a warning
+- At most one form zone per page, must be in `main` area, presenter must have form sections (error)
+- `record_source` and `scope_context` are mutually exclusive (error, validated in `ZoneDefinition`)
+- `index_presenter` must reference an existing presenter with index columns and the same model (error)
+- `record_source` zone presenter should have a show layout (warning)
+- Unreachable presenters (no slug, not used in any zone, not dialog-only) produce a boot-time warning
+
+Run validation manually:
+
+```bash
+bundle exec rake lcp_ruby:validate
+```
+
+## Index-Level Composite Pages
+
+Index composite pages combine an index table (main area) with sidebar or below widget zones. They provide the same features as a standard index page — search, filtering, sorting, pagination — while adding contextual widgets like KPI cards alongside the table.
+
+```yaml
+page:
+  name: orders_overview
+  model: order
+  slug: orders
+  zones:
+    - name: orders_table
+      presenter: orders_index        # must have table_columns
+      area: main
+
+    - name: total_orders
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: count
+        label_key: lcp_ruby.orders.total
+
+    - name: revenue
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: sum
+        aggregate_field: amount
+        format: currency
+        label_key: lcp_ruby.orders.revenue
+
+    - name: help_text
+      type: widget
+      area: below
+      widget:
+        type: text
+        content_key: lcp_ruby.orders.help
+      visible_when:
+        role: admin
+```
+
+A page is detected as an index composite when its main zone presenter has `table_columns` defined.
+
+**Constraints:**
+- **No tab zones.** Index composites cannot have `area: tabs` zones because tabs use query parameters (`page`, `sort`, `qs`) that collide with the index table's parameters.
+- **No `:record.id` in `scope_context`.** Index composites render a list, not a single record. Use model-level scopes or `:current_user.id` instead.
+
+**Differences from dashboards:**
+
+| | Index Composite | Dashboard |
+|---|---|---|
+| **Layout** | `semantic` (main + sidebar/below) | `grid` (explicit CSS grid positions) |
+| **Model** | Model-bound — permissions, CRUD actions apply | Standalone — no model, widget-only |
+| **Main area** | Full index table with search, filters, pagination | No index — only widgets |
+| **URL** | `/orders` (model slug) | `/dashboard` (page slug) |
+
+## Master-Detail Pages
+
+A master-detail page puts a selectable list (or tree) in the left sidebar. Clicking a row loads its detail in the main area on the right, with tabs and widgets scoped to the selected record.
+
+### 1. Create Presenters
+
+You need a selection zone presenter (index columns for the sidebar list) and a detail zone presenter (show sections for the main area):
+
+```ruby
+# config/lcp_ruby/presenters/dept_list_zone.rb
+define_presenter :dept_list_zone do
+  model :department
+
+  index do
+    tree_view true            # render as collapsible tree (if model is a tree)
+    default_expanded "all"
+    column :name
+  end
+end
+
+# config/lcp_ruby/presenters/dept_detail_zone.rb
+define_presenter :dept_detail_zone do
+  model :department
+
+  show do
+    section "Details", columns: 2 do
+      field :name, renderer: :heading
+      field :code
+      field "parent.name", label: "Parent"
+    end
+  end
+end
+```
+
+### 2. Define the Page
+
+```yaml
+# config/lcp_ruby/pages/department_explorer.yml
+page:
+  name: department_explorer
+  model: department
+  slug: department-explorer
+  zones:
+    # Sidebar: selection list (left side)
+    - name: department_list
+      presenter: dept_list_zone
+      area: sidebar
+      width: 3                      # sidebar proportion (1-12)
+      selection: single             # enables click-to-select
+      record_click: none            # selection handles clicks, not navigation
+
+    # Main: selected record detail (right side)
+    - name: department_detail
+      presenter: dept_detail_zone
+      area: main
+      width: 9                      # main proportion (1-12)
+      record_source: selection      # loads from ?selected=N
+
+    # Tab: scoped to the selected department
+    - name: employees
+      presenter: dept_employees_zone
+      area: tabs
+      label_key: lcp_ruby.pages.dept_explorer.tabs.employees
+      scope_context:
+        department_id: ":selection_id"
+
+    # Below widget: scoped to the selected department
+    - name: employee_kpi
+      type: widget
+      area: below
+      widget:
+        type: kpi_card
+        model: employee
+        aggregate: count
+        label_key: lcp_ruby.pages.dept_explorer.employee_count
+      scope_context:
+        department_id: ":selection_id"
+```
+
+### How It Works
+
+1. **No selection** — sidebar shows all records, main area shows "Select a record to view details", tabs and widgets are hidden.
+2. **User clicks a row** — URL updates to `?selected=N`, page reloads. Sidebar highlights the selected row, main shows detail, tabs and widgets are scoped to the selection.
+3. **Clicking another row** — selection changes, everything updates.
+
+### Configuring the Sidebar
+
+**Fields:** Controlled by the selection zone presenter's `index` columns. Add/remove columns to change what appears in the sidebar list.
+
+**Width:** Use `width` on the sidebar and main zones. Values represent a fraction ratio (1–12 scale). For example, `width: 3` + `width: 9` gives a 1:3 sidebar-to-main ratio. `width: 4` + `width: 8` gives 1:2.
+
+**Tree vs. flat:** If the model is a tree and the presenter uses `tree_view: true`, the sidebar renders a collapsible tree hierarchy. Otherwise it renders a flat table.
+
+**Actions column:** Automatically hidden in the selection sidebar to save space.
+
+### Key Differences from Index Composites
+
+| | Index Composite | Master-Detail |
+|---|---|---|
+| **Sidebar** | Widget zones (KPIs, text) | Selection zone (clickable list/tree) |
+| **Main area** | Index table | Detail of selected record |
+| **Tabs** | Not supported | Supported, scoped to selection |
+| **URL** | `/orders` | `/departments?selected=N` |
+| **Layout** | Sidebar right | Sidebar left |
+
+## Composite Dialog Pages
+
+A composite dialog page renders multiple zones inside a modal — e.g., a transfer dialog with a form in the main area and an item preview in the sidebar.
+
+```yaml
+page:
+  name: transfer_dialog
+  model: inventory_transfer
+  dialog:
+    size: large
+  zones:
+    - name: transfer_form
+      presenter: transfer_form
+      area: main
+      width: 8
+
+    - name: source_item
+      presenter: item_show
+      area: sidebar
+      width: 4
+      record_source:
+        param: source_id
+```
+
+Unlike regular composite pages, all zones in a composite dialog are **rendered inline in a single response** — there is no lazy loading or Turbo Frame splitting. Tab zones (if any) are rendered as stacked sections, not as switchable tabs.
+
+**Constraints:**
+- At most one form zone per composite dialog (same rule as regular composites)
+- No `:record.id` in `scope_context` (dialog-only pages have no primary record)
+- Use `record_source` to load related records from URL params (e.g., `?source_id=42`)
+
+See the [Dialogs Guide](dialogs.md#composite-dialog-pages) for triggering actions and workflows.
+
+## Dialog Nesting
+
+Dialogs support **max 2 levels** of nesting. When a dialog action is triggered while a dialog is already open, a nested dialog opens on top of the primary dialog.
+
+**Example workflow:**
+1. User clicks "Edit Order" → primary dialog opens with order form
+2. Inside the order form, user clicks "Add Contact" → nested dialog opens on top
+3. User creates the contact, nested dialog closes → primary dialog stays open
+
+**On success behavior in nested dialogs:**
+
+| `on_success` | Behavior |
+|---|---|
+| `close` | Closes only the nested dialog |
+| `reload` | Re-fetches the primary dialog content |
+| `reload_zone` / `reload_zones` | Reloads zones on the page behind both dialogs |
+
+**Constraints:**
+- Maximum 2 levels. Attempting to open a 3rd dialog produces a console warning.
+- Nested dialogs use single-zone auto-pages (not composite dialogs).
+
+## Relationship to Dashboards
+
+Both dashboards and composite pages use the Pages infrastructure, but they serve different purposes:
+
+| | Dashboards | Composite Pages | Index Composites |
+|---|---|---|---|
+| **Layout** | `grid` | `semantic` | `semantic` |
+| **Model** | Standalone (no model) | Record-bound | Model-bound |
+| **Main area** | Widgets only | Show/form presenter | Index table |
+| **Zones** | Widgets + presenters | Presenters + widgets | Index + widgets |
+| **URL** | `/dashboard` | `/employees/123` | `/orders` |
+| **Tabs** | No | Yes | No |
+| **Filters** | No | Per zone | Index-level + no per-zone |
+
+## Global Parameters
+
+Global parameters add filter controls above the page content that apply to all zones at once. They are useful when multiple zones on a page share a common filter dimension (e.g., department, status, date range).
+
+**Restriction:** Parameters are only supported on **standalone pages** (dashboards) and **index composite pages**. Show-level composite pages (record detail with tabs) cannot use parameters because the record itself already scopes the zones.
+
+### Step 1: Define the Models
+
+For this example, we have an orders index page where users can filter by department and by status:
+
+```yaml
+# config/lcp_ruby/models/department.yml
+model:
+  name: department
+  fields:
+    - { name: name, type: string }
+
+# config/lcp_ruby/models/order.yml
+model:
+  name: order
+  fields:
+    - { name: department_id, type: integer }
+    - { name: amount, type: decimal }
+    - { name: status, type: enum, enum_values: [pending, confirmed, shipped, cancelled] }
+  associations:
+    - { type: belongs_to, name: department }
+  scopes:
+    - { name: active, where: { status: [pending, confirmed, shipped] } }
+    - { name: pending, where: { status: pending } }
+```
+
+### Step 2: Create the Presenter
+
+```yaml
+# config/lcp_ruby/presenters/orders_index.yml
+presenter:
+  name: orders_index
+  model: order
+  index:
+    table_columns:
+      - { field: department_id, input_type: association_select }
+      - { field: amount }
+      - { field: status }
+```
+
+### Step 3: Define the Page with Parameters
+
+```yaml
+# config/lcp_ruby/pages/orders_overview.yml
+page:
+  name: orders_overview
+  model: order
+  slug: orders
+  parameters:
+    - name: department
+      type: association_select
+      model: department
+      field: department_id
+
+    - name: status_scope
+      type: scope
+      scope: active
+      default: active
+      options:
+        - { value: active }
+        - { value: pending }
+  zones:
+    - name: orders_list
+      presenter: orders_index
+      area: main
+      width: 9
+
+    - name: order_count
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: count
+        label_key: lcp_ruby.orders.total
+      area: sidebar
+      width: 3
+
+    - name: revenue
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: sum
+        aggregate_field: amount
+        format: currency
+        label_key: lcp_ruby.orders.revenue
+      area: sidebar
+      width: 3
+```
+
+### How Parameters Work
+
+Each parameter definition creates a filter control rendered above the page content. When the user selects a value, the page reloads with the parameter as a query string (e.g., `?department=5&status_scope=pending`). The resolved parameter values are applied to **every zone** on the page — both the main index table and all sidebar/below widgets.
+
+**Parameter types:**
+
+| Type | Renders as | Applies as |
+|------|-----------|------------|
+| `association_select` | Select dropdown populated from the `model` | `WHERE field = value` on each zone's query |
+| `scope` | Select dropdown from the `options` list | Calls the named scope on each zone's model |
+| `enum_select` | Select dropdown from the field's enum values | `WHERE field = value` on each zone's query |
+| `date_range` | Two date inputs (from/to) | `WHERE field BETWEEN from AND to` on each zone's query |
+
+**Required attributes by type:**
+
+- `association_select` — `model` (source model for the dropdown) and `field` (FK column to filter on)
+- `scope` — `scope` (the named scope to call); optionally `options` (list of allowed scope names) and `default` (pre-selected value)
+- `enum_select` — `field` (the enum column to filter on)
+- `date_range` — `field` (the date/datetime column to filter on)
+
+**Scope dispatch:** For `association_select` and `enum_select`, the platform first checks if the zone's model defines a `filter_<field>` class method. If found, that method is called instead of a plain `WHERE` clause. This lets you customize filtering per model (e.g., filtering through a join table).
+
+### Step 4: Add Translations (optional)
+
+```yaml
+# config/locales/en.yml
+en:
+  lcp_ruby:
+    orders:
+      total: "Total Orders"
+      revenue: "Revenue"
+    pages:
+      orders_overview:
+        parameters:
+          department: "Department"
+          status_scope: "Status"
+```
+
+If `label_key` is set on the parameter definition, it takes priority. Otherwise, the parameter label falls back to the humanized name.
+
+## Embedding External Dashboards
+
+The embed widget renders an external dashboard (Metabase, Grafana, or a custom provider) inside an iframe within a page zone.
+
+### Step 1: Create a Provider Class
+
+If the built-in `Metabase` and `Grafana` providers do not cover your needs, create a custom provider by extending `LcpRuby::EmbedProviders::Base`:
+
+```ruby
+# app/embed_providers/power_bi_provider.rb
+class PowerBiProvider < LcpRuby::EmbedProviders::Base
+  attr_reader :site_url
+
+  def initialize(site_url:, workspace_id:)
+    @site_url = site_url.chomp("/")
+    @workspace_id = workspace_id
+  end
+
+  def embed_url(resource_type:, resource_id:, params: {}, user: nil)
+    path = case resource_type.to_s
+    when "report"
+      "/reportEmbed?reportId=#{resource_id}&groupId=#{@workspace_id}"
+    when "dashboard"
+      "/dashboardEmbed?dashboardId=#{resource_id}&groupId=#{@workspace_id}"
+    else
+      "/reportEmbed?reportId=#{resource_id}&groupId=#{@workspace_id}"
+    end
+
+    url = "#{@site_url}#{path}"
+
+    # Pass through any additional parameters
+    query_parts = params.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }
+    url += "&#{query_parts.join('&')}" if query_parts.any?
+    url
+  end
+end
+```
+
+The `site_url` reader is required — the platform uses it to derive CSP frame-src origins. The `embed_url` method receives the resource type, resource ID, optional params hash, and the current user (for signed or authenticated embeds).
+
+### Step 2: Register the Provider
+
+Register the provider instance in your Rails initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  # Built-in Metabase provider
+  config.register_embed_provider(
+    "metabase",
+    LcpRuby::EmbedProviders::Metabase.new(
+      site_url: ENV["METABASE_URL"],
+      secret_key: ENV["METABASE_SECRET_KEY"]
+    )
+  )
+
+  # Built-in Grafana provider
+  config.register_embed_provider(
+    "grafana",
+    LcpRuby::EmbedProviders::Grafana.new(
+      site_url: ENV["GRAFANA_URL"],
+      api_token: ENV["GRAFANA_TOKEN"]
+    )
+  )
+
+  # Custom provider
+  config.register_embed_provider(
+    "power_bi",
+    PowerBiProvider.new(
+      site_url: "https://app.powerbi.com",
+      workspace_id: ENV["POWERBI_WORKSPACE_ID"]
+    )
+  )
+end
+```
+
+The first argument is the provider name referenced in page YAML. You can register multiple providers.
+
+### Step 3: Define the Page with an Embed Zone
+
+```yaml
+# config/lcp_ruby/pages/analytics.yml
+page:
+  name: analytics
+  slug: analytics
+  layout: grid
+  zones:
+    - name: sales_dashboard
+      type: widget
+      widget:
+        type: embed
+        provider: metabase
+        resource_type: dashboard
+        resource_id: 42
+        height: "600px"
+        params:
+          date_filter: "past30days"
+      position: { row: 1, col: 1, width: 12, height: 3 }
+
+    - name: server_metrics
+      type: widget
+      widget:
+        type: embed
+        provider: grafana
+        resource_type: dashboard
+        resource_id: "abc123"
+        height: "400px"
+      position: { row: 4, col: 1, width: 6, height: 2 }
+```
+
+**Required widget attributes:** `provider` (registered provider name), `resource_type` (provider-specific, e.g., "dashboard", "question", "panel"), `resource_id` (the identifier in the external system). Optional: `height` (iframe height, defaults to "400px"), `params` (extra query parameters forwarded to the provider's `embed_url`).
+
+If the named provider is not registered, the zone logs a warning and is hidden gracefully.
+
+Embed zones work in both `grid` layout (dashboards) and `semantic` layout (composite page sidebar or below areas).
+
+### Step 4: Configure Content Security Policy
+
+Browsers block iframes from external origins by default. Use `LcpRuby.embed_csp_sources` to retrieve the list of origins derived from all registered providers, then add them to your CSP:
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy do |policy|
+  policy.frame_src :self, *LcpRuby.embed_csp_sources
+end
+```
+
+`embed_csp_sources` returns an array of origin strings (e.g., `["https://metabase.example.com", "https://grafana.example.com"]`) extracted from each provider's `site_url`. Non-standard ports are preserved. Duplicate origins are removed automatically.
+
+## Auto-Refresh with depends_on
+
+The `depends_on` attribute on a zone causes it to automatically refresh when records of a specified model are created, updated, or destroyed. This keeps sidebar KPI cards, list widgets, and presenter zones up to date without a full page reload.
+
+### Step 1: Define the Page with depends_on
+
+Consider a task management page where a KPI card in the sidebar shows the total task count. When a user creates or deletes a task from the main table, the KPI should update automatically:
+
+```yaml
+# config/lcp_ruby/pages/tasks_overview.yml
+page:
+  name: tasks_overview
+  model: do_task
+  slug: do-tasks
+  zones:
+    - name: tasks_list
+      presenter: do_tasks_index
+      area: main
+      width: 9
+
+    - name: task_count
+      type: widget
+      widget:
+        type: kpi_card
+        model: do_task
+        aggregate: count
+        label_key: lcp_ruby.tasks.total_count
+      area: sidebar
+      width: 3
+      depends_on: [do_task]
+```
+
+The `depends_on` attribute accepts an array of model names. When any of those models change, the zone re-renders with fresh data.
+
+### How It Works
+
+1. **Turbo Stream subscription.** When the page loads, it renders a `<turbo-stream-source>` tag for each unique model name referenced by any zone's `depends_on`. The tag subscribes to the ActionCable channel `lcp_model_<model_name>`.
+
+2. **Broadcast on change.** After every successful `create`, `update`, or `destroy` action in the `ResourcesController`, the controller calls `broadcast_refresh_to("lcp_model_<model_name>")`. This sends a Turbo Stream refresh signal to all subscribed clients.
+
+3. **Zone refresh.** The browser receives the broadcast and Turbo automatically refreshes the page. Since the zone content is rendered server-side, the KPI card (or list widget, or presenter zone) recalculates its data on the next render.
+
+### Step 2: Ensure ActionCable Is Available
+
+`depends_on` requires ActionCable and `turbo-rails`. In a standard Rails 7+ application these are included by default. Verify that your setup includes:
+
+- `gem "turbo-rails"` in your Gemfile
+- ActionCable configured (check `config/cable.yml`)
+- The Turbo JavaScript is loaded (typically via `importmap` or `jsbundling`)
+
+### Graceful Degradation
+
+If ActionCable is not available (e.g., the `ActionCable` constant is not defined), the Turbo Stream subscription tags are simply not rendered. The page works normally — zones display their data on load — but they will not auto-refresh when records change. Users would need to manually reload the page to see updated values.
+
+The `broadcast_model_change` method in the controller also degrades gracefully: if `Turbo::StreamsChannel` is not defined or the broadcast fails for any reason, the error is logged as a warning and the create/update/destroy action still completes successfully.
+
+### Constraints
+
+- **Text widget zones** cannot use `depends_on` (they render static i18n content, so refreshing them has no effect). The validator raises an error if you try.
+- `depends_on` works on **kpi_card**, **list**, **chart**, **embed**, and **presenter** zones.
+- The broadcast is page-global — all clients viewing any page that subscribes to the same model channel will receive the refresh. This is intentional: if two users are viewing the same orders overview, both see updates in real time.
+- Multiple model names are supported: `depends_on: [order, payment]` subscribes to both `lcp_model_order` and `lcp_model_payment` channels.
+
+### Example: Composite Show Page with Auto-Refreshing Tab Count
+
+You can also use `depends_on` on show-level composite pages. For example, an employee detail page where the sidebar shows a leave request count that updates when leave requests are added via a dialog:
+
+```yaml
+# config/lcp_ruby/pages/employee_detail.yml
+page:
+  name: employee_detail
+  model: employee
+  slug: employees
+  zones:
+    - name: header
+      presenter: employee_detail
+      area: main
+
+    - name: leave_count
+      type: widget
+      area: sidebar
+      widget:
+        type: kpi_card
+        model: leave_request
+        aggregate: count
+        label_key: pages.employee_detail.sidebar.leave_count
+      scope_context:
+        employee_id: ":record.id"
+      depends_on: [leave_request]
+
+    - name: leave_requests
+      presenter: leave_requests_index
+      area: tabs
+      label_key: pages.employee_detail.tabs.leave
+      scope_context:
+        employee_id: ":record.id"
+```
+
+When a leave request is created (from any page or dialog), the `leave_count` KPI widget refreshes automatically. The tab content is not subscribed to `depends_on` in this example — it updates through normal Turbo Frame navigation or zone reload after dialog actions.
+
+## DB-Stored Pages
+
+Page definitions can be stored in the database, allowing runtime creation and management of pages without editing YAML files. This is useful for letting administrators build custom dashboards or composite layouts through the platform's UI.
+
+### Step 1: Run the Generator
+
+```bash
+rails generate lcp_ruby:pages
+rails db:migrate
+```
+
+This creates the `page_config` model with the required database tables, a management presenter, and permissions.
+
+### Step 2: Enable DB Page Source
+
+Add the configuration to your initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.page_source = :model
+end
+```
+
+### Step 3: Manage Pages at /page-configs
+
+Start the server and navigate to `/page-configs`. The generated management UI provides a standard CRUD interface for page definitions.
+
+### Step 4: Create a Page Definition
+
+Create a new page config record. The `definition` field accepts JSON using the same structure as the YAML `page:` format:
+
+```json
+{
+  "name": "team_dashboard",
+  "slug": "team",
+  "model": "employee",
+  "zones": [
+    {
+      "name": "team_table",
+      "presenter": "employees_index",
+      "area": "main",
+      "width": 9
+    },
+    {
+      "name": "headcount",
+      "type": "widget",
+      "area": "sidebar",
+      "width": 3,
+      "widget": {
+        "type": "kpi_card",
+        "model": "employee",
+        "aggregate": "count",
+        "label_key": "lcp_ruby.team.headcount"
+      }
+    }
+  ]
+}
+```
+
+All page and zone attributes supported in YAML are also supported in the JSON definition — `scope_context`, `visible_when`, `filters`, `record_click`, `parameters`, `dialog`, `depends_on`, and so on.
+
+### Override Priority
+
+DB-stored pages take the highest priority:
+
+1. **DB pages** (active records from `page_config`) — highest priority
+2. **YAML pages** (`config/lcp_ruby/pages/*.yml`)
+3. **Auto-generated pages** (created for unclaimed presenters) — lowest priority
+
+If a DB page has the same `name` as a YAML page, the DB version wins. This lets administrators override static page definitions at runtime. Set `active: false` on a DB page to deactivate it and fall back to the YAML definition.
+
+DB-stored pages are validated with the same rules as YAML pages. Invalid definitions are logged as warnings and skipped at boot.
+
+## Custom Zones
+
+When a composite page zone needs content that no presenter or widget can produce (a Gantt chart, a map, a custom React component), use `type: custom` to delegate rendering to a host-app partial.
+
+### Step 1: Define the Custom Zone
+
+```yaml
+# config/lcp_ruby/pages/employee_detail.yml
+page:
+  name: employee_detail
+  model: employee
+  slug: employees
+  zones:
+    - name: header
+      presenter: employee_show
+      area: main
+    - name: project_timeline
+      type: custom
+      partial: "employees/gantt_chart"
+      area: tabs
+      label_key: lcp_ruby.pages.employee_detail.tabs.timeline
+      scope_context:
+        employee_id: ":record.id"
+    - name: quick_stats
+      type: custom
+      partial: "employees/stats_sidebar"
+      area: sidebar
+      eager: true
+```
+
+### Step 2: Create the Host-App Partial
+
+```erb
+<%# app/views/employees/gantt_chart.html.erb %>
+<div data-controller="gantt"
+     data-gantt-employee-id-value="<%= record.id %>">
+  Loading timeline...
+</div>
+```
+
+The partial receives these locals: `record`, `presenter`, `evaluator`, `zone`, `scope_context_values`, `scoped_records`, `selection_id`, `current_user`, `page_definition`, `params`.
+
+### Key Options
+
+- **`eager: true`** — Renders the zone inline during the initial page load instead of via a lazy Turbo Frame. Use for lightweight sidebar/below content or zones that need inline `<script>` execution.
+- **`apply_scope_context: false`** — Only passes `scope_context_values` (resolved hash) without building `scoped_records`. Use when the partial needs full control over its queries.
+- **`model: "note"`** — Specifies a different model for `scoped_records` (cross-model zones).
+
+### Turbo Frame Constraint
+
+Lazy-loaded custom zones (default `eager: false`) are rendered inside Turbo Frames. Turbo does not execute inline `<script>` tags in frame payloads. Use Stimulus controllers (`data-controller`) for JS initialization, or set `eager: true` for zones that require immediate script execution.
+
+See [Rendering Extension Points](rendering-extension-points.md) for the full comparison of custom render blocks vs. view slots.
+
+## What's Next
+
+- [Pages Reference](../reference/pages.md) — Full attribute reference for pages and zones
+- [Dashboards Guide](dashboards.md) — Standalone grid pages with KPI widgets
+- [Dialogs Guide](dialogs.md) — Modal dialog pages and composite dialogs
+- [View Groups Guide](view-groups.md) — Navigation menu and view switching