lcp 0.1.0

data/docs/reference/view-groups.md

@@ -0,0 +1,347 @@
+# View Groups Reference
+
+File: `config/lcp_ruby/views/<name>.yml`
+
+View groups organize one or more pages for the same model into a navigable unit. They control the navigation menu (which entries appear, in what order) and provide a view switcher when multiple pages exist for the same model (e.g., "Detailed" vs. "Short" views of deals).
+
+See the [View Groups Guide](../guides/view-groups.md) for practical examples.
+
+## YAML Schema
+
+```yaml
+view_group:
+  name: <group_name>
+  model: <model_name>
+  primary: <page_name>
+  public: false
+  navigation:
+    menu: main
+    position: 3
+  breadcrumb:
+    relation: <association_name>
+  views:
+    - page: <page_name>
+      label: "Detailed"
+      icon: maximize
+    - page: <page_name>
+      label: "Short"
+      icon: list
+```
+
+## Top-Level Attributes
+
+### `name`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | filename without extension |
+| **Type** | string |
+
+Unique identifier for the view group. If omitted, the YAML filename is used (e.g., `deals.yml` becomes `deals`).
+
+### `model`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Name of the [model](models.md) this view group covers. Must match a model's `name` attribute. Multiple view groups can reference the same model (e.g., a "Deals" group and a "Pipeline" group both referencing the `deal` model).
+
+### `primary`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Name of the primary page in this group. The primary page is used as the representative entry in the navigation menu (its label, slug, and icon are shown). Must be one of the pages listed in `views`.
+
+### `public`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `false` |
+| **Type** | boolean |
+
+When `true`, this view group allows unauthenticated access. Requests to pages in a public view group bypass the `authenticate_user!` check — an anonymous user object with empty roles is used instead. This is useful for public-facing pages like landing pages or public directories.
+
+```yaml
+view_group:
+  name: public_catalog
+  model: product
+  primary: product_catalog
+  public: true
+  navigation: false
+  views:
+    - page: product_catalog
+```
+
+### `navigation`
+
+Controls the position of this view group in the navigation menu, or disables navigation entirely.
+
+**As a hash** (default):
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `menu` | string | Menu group name (e.g., `main`) |
+| `position` | integer | Sort order within the menu. Lower numbers appear first |
+| `auto_append` | boolean | When `false`, the view group is **not** auto-appended to top_menu when missing from `menu.yml`. The view group remains routable and can be referenced explicitly in `menu.yml`. Defaults to `true`. |
+
+**As `false`**:
+
+```yaml
+navigation: false
+```
+
+Setting `navigation: false` excludes this view group from auto-generated navigation and from auto-append in `:auto` menu mode. The view group still works for routing and view switching — it just does not appear in any menu.
+
+Use this for view groups that should be accessible via direct URL but not shown in navigation (e.g., audit logs, embedded views, detail pages linked from other pages).
+
+The `navigable?` method on `ViewGroupDefinition` returns `false` when `navigation` is set to `false`.
+
+#### `navigation: { auto_append: false }` vs `navigation: false`
+
+These two opt-outs have different semantics:
+
+| | `navigation: false` | `navigation: { auto_append: false }` |
+|---|---|---|
+| In `navigable?` | `false` (not navigable at all) | `true` (navigable) |
+| Auto-append into top_menu | skipped | skipped |
+| Explicit reference in `menu.yml` | technically allowed but unusual | **the intended way** to surface the item |
+| Routable via slug | yes | yes |
+
+Use `auto_append: false` for **infrastructure view groups** (audit logs, job executions, permission configs, etc.) that should not leak into top navigation by default — the configurator references them explicitly in `menu.yml` when they want them visible. The `lcp_ruby:auditing`, `lcp_ruby:background_jobs`, `lcp_ruby:gapfree_sequences`, `lcp_ruby:workflow_audit_log`, `lcp_ruby:batch_operations`, `lcp_ruby:permission_source`, `lcp_ruby:pages`, `lcp_ruby:workflow_definition`, and `lcp_ruby:role_model` generators all emit `auto_append: false` on their view groups.
+
+Use `navigation: false` for view groups that are **never** part of navigation but routable — e.g., dialog presenters, detail pages reached only via links from another page.
+
+See [Menu Reference](menu.md) for details on the configurable menu system.
+
+### `breadcrumb`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `nil` (default breadcrumb: `Home > Current View`) |
+| **Type** | `Hash` or `false` |
+
+Controls breadcrumb navigation for this view group. Breadcrumbs provide hierarchical context like `Home > Companies > Acme Inc > Deals > Big Deal`.
+
+| Value | Behavior |
+|-------|----------|
+| omitted | Default breadcrumb: `Home > {View Label}` (plus record/action crumbs) |
+| `{ relation: <name> }` | Adds parent breadcrumbs by following the named belongs_to association |
+| `false` | Disables breadcrumbs entirely for this view group |
+
+The `relation` value must match a `belongs_to` association name on the model. The engine automatically resolves the parent's view group to generate the correct links and labels. Polymorphic associations are supported — the engine reads `{relation}_type` to determine the parent model dynamically.
+
+If the FK is nullable and the parent record is `nil`, the parent breadcrumb level is skipped. The chain recurses up to 5 levels when parent view groups also define `breadcrumb.relation`. When crossing into a self-referential tree (e.g., employee → department → parent department), the list crumb appears once at the top of the chain, producing `Home > Departments > Engineering > DevOps > Employees > Eva` without duplicates.
+
+The "Home" crumb links to `"/"` by default. Override via `config.breadcrumb_home_path` (see [Engine Configuration](engine-configuration.md#breadcrumb_home_path)).
+
+```yaml
+# Deals breadcrumb shows: Home > Companies > {company name} > Deals > {deal title}
+breadcrumb:
+  relation: company
+
+# Disable breadcrumbs
+breadcrumb: false
+```
+
+### `switcher`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | `auto` (auto-detect from presenter configs) |
+| **Type** | `false`, `"auto"`, or array of strings |
+
+Controls where the view switcher appears when a view group has multiple views. By default, the switcher uses auto-detection — it compares presenter configurations and only shows the switcher on pages where the presenters actually differ.
+
+| Value | Behavior |
+|-------|----------|
+| *(omitted)* or `auto` | Auto-detect: compare presenter configs, show switcher only where they differ |
+| `[index]` | Switcher only on index page |
+| `[show]` | Switcher only on show page |
+| `[form]` | Switcher only on edit/new pages |
+| `[index, show]` | Switcher on index and show pages |
+| `[index, show, form]` | Switcher on all pages (forces display, skips auto-detection) |
+| `false` | No switcher anywhere, even with multiple views |
+
+**Auto-detection** compares `index_config`, `show_config`, and `form_config` across all presenters in the group. If all presenters have identical configuration for a given page type, the switcher is hidden on that page. This means presenters that differ only on `show` will not display a pointless switcher on `index`.
+
+```yaml
+# Auto-detection (default — no switcher key needed)
+view_group:
+  model: recipe
+  primary: recipes
+  views:
+    - page: recipes
+      label: "Structured"
+    - page: recipes_raw
+      label: "Raw JSON"
+
+# Explicit: only show switcher on show pages
+view_group:
+  model: recipe
+  primary: recipes
+  switcher: [show]
+  views:
+    - page: recipes
+    - page: recipes_raw
+
+# Disable switcher entirely
+view_group:
+  model: recipe
+  primary: recipes
+  switcher: false
+  views:
+    - page: recipes
+    - page: recipes_raw
+```
+
+### `views`
+
+| | |
+|---|---|
+| **Required** | yes (at least one) |
+| **Type** | array of view objects |
+
+List of pages in this group. Each view is rendered as a tab in the view switcher.
+
+#### View Attributes
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page` | string | yes | Page name. Must match a page's `name` attribute |
+| `label` | string | no | Display label in the view switcher. Falls back to the page name |
+| `icon` | string | no | Icon name displayed in the view switcher tab |
+
+## Auto-Creation Behavior
+
+You do not need to create a view group for every model. When a model has exactly one presenter and no explicit view group, the engine auto-creates a view group at load time:
+
+- **Name**: `<model_name>` (matches the model name — single canonical form, no suffix)
+- **Primary**: the single page (auto-created from the presenter)
+- **Navigation**: position assigned in the 900+ tier (auto-VGs land after explicit ones)
+- **Views**: one entry with the page's label
+
+This means single-presenter models appear in the navigation menu without any view group YAML. Define an explicit view group when you need to:
+
+- Control the navigation position
+- Group multiple pages with a view switcher
+- Override the default menu placement
+
+Auto-creation is skipped when:
+
+- An explicit view group already references the model (via `model:`)
+- The model has more than one presenter (you must define view groups explicitly to avoid ambiguity)
+
+If a user-defined view group happens to share the auto-VG name without also covering the model (so the skip rule above wouldn't fire), the loader raises `MetadataError` eagerly — silent overwrite is avoided.
+
+### Referencing auto-created view groups in `menu.yml`
+
+Reference the auto-VG by the model name:
+
+```yaml
+# menu.yml
+top_menu:
+  - view_group: announcement      # auto-created VG for the `announcement` model
+```
+
+Genuine misses raise `MetadataError` at boot with a `did_you_mean` hint suggesting the closest available view group name.
+
+## Validation Rules
+
+The configuration validator checks:
+
+- Referenced model exists
+- All referenced pages exist
+- Primary page is included in the views list
+- No page appears in more than one view group
+- Duplicate navigation positions produce a warning
+
+## DSL Reference
+
+File: `config/lcp_ruby/views/<name>.rb`
+
+```ruby
+define_view_group :deals do
+  model :deal
+  primary :deal
+
+  navigation menu: "main", position: 3
+  breadcrumb relation: :company
+
+  view :deal, label: "Detailed", icon: :maximize
+  view :deal_short,  label: "Short",    icon: :list
+end
+```
+
+### `define_view_group(name, &block)`
+
+Creates a view group definition. The block supports these methods:
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `model` | `value` | Sets the model name |
+| `primary` | `value` | Sets the primary page name |
+| `navigation` | `menu:`, `position:` | Sets navigation config. `position` is optional |
+| `breadcrumb` | `false` or `relation:` | Sets breadcrumb config. Use `breadcrumb false` to disable, `breadcrumb relation: :company` to set parent relation |
+| `switcher` | `false`, `:auto`, or context symbols | Sets switcher config. Use `switcher false` to disable, `switcher :auto` for auto-detection, `switcher :index, :show` for explicit contexts |
+| `view` | `page_name`, `label:`, `icon:` | Adds a view entry. `label` and `icon` are optional |
+
+## API
+
+### `LcpRuby.loader.view_groups_for_model(model_name)`
+
+Returns an array of `ViewGroupDefinition` objects for the given model name. Returns an empty array if none exist. Multiple view groups can reference the same model (e.g., a "Deals" group and a "Pipeline" group both for the `deal` model).
+
+### `LcpRuby.loader.view_group_for_page(page_name)`
+
+Returns the `ViewGroupDefinition` that contains the given page, or `nil`.
+
+### `navigable_entries` (helper)
+
+Available in views via `LayoutHelper`. Returns an array of hashes sorted by navigation position, one per view group. Each hash contains:
+
+| Key | Description |
+|-----|-------------|
+| `:presenter` | The primary `PresenterDefinition` object |
+| `:label` | Display label |
+| `:slug` | URL slug |
+| `:icon` | Icon name |
+| `:navigation` | Navigation config hash (`menu`, `position`) |
+
+Only view groups whose primary page is routable are included.
+
+```erb
+<% navigable_entries.each do |entry| %>
+  <%= link_to entry[:label], resources_path(lcp_slug: entry[:slug]) %>
+<% end %>
+```
+
+### `current_view_group` (helper)
+
+Available in controllers and views. Returns the `ViewGroupDefinition` for the current page, or `nil`.
+
+### `sibling_views` (helper)
+
+Available in controllers and views. Returns an array of view hashes for the current view group, each enriched with `slug` and `presenter_name` keys. Used internally by the `_view_switcher` partial.
+
+### `breadcrumbs` (helper)
+
+Available in controllers and views. Returns an array of `BreadcrumbBuilder::Crumb` structs for the current page. Each crumb has:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `label` | string | Display text |
+| `path` | string or nil | Link URL (nil for the current/last crumb) |
+| `current?` | boolean | True for the last crumb in the chain |
+
+The breadcrumb chain is built automatically based on the view group's `breadcrumb` config, the current record, and the action name. The layout renders them via `app/views/lcp_ruby/shared/_breadcrumbs.html.erb`.
+
+Source: `lib/lcp_ruby/metadata/view_group_definition.rb`, `lib/lcp_ruby/dsl/view_group_builder.rb`, `lib/lcp_ruby/presenter/breadcrumb_builder.rb`, `lib/lcp_ruby/metadata/loader.rb`, `app/helpers/lcp_ruby/layout_helper.rb`

data/docs/reference/view-slots.md

@@ -0,0 +1,228 @@
+# View Slots Reference
+
+The View Slots system provides named injection points in page templates where platform features and host applications can register UI components. Components are rendered in position order, can be conditionally enabled, and can be overridden by name.
+
+## How It Works
+
+- Page templates (index, show) call `render_slot(:slot_name, page: :index)` at defined injection points
+- Components register into `(page, slot)` pairs via `ViewSlots::Registry`
+- Each component has a `name`, `partial`, `position`, and optional `enabled` callback
+- At render time, all components for a slot are filtered by `enabled?`, sorted by `position`, and rendered
+- Registering a component with the same `name` in the same slot replaces the previous one (host app overrides)
+
+## Registry API
+
+### `ViewSlots::Registry.register`
+
+Register a new component or replace an existing one.
+
+```ruby
+LcpRuby::ViewSlots::Registry.register(
+  page:     :index,                       # Required. :index or :show
+  slot:     :toolbar_end,                 # Required. Slot name (symbol or string)
+  name:     :my_button,                   # Required. Unique within the slot
+  partial:  "my_app/slots/my_button",     # Required. Rails partial path
+  position: 15,                           # Optional. Default: 10. Lower = earlier
+  enabled:  ->(ctx) { true }             # Optional. Lambda receiving SlotContext
+)
+```
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `page` | Symbol/String | Yes | — | Page type: `:index` or `:show` |
+| `slot` | Symbol/String | Yes | — | Slot name (see [Slot Names](#slot-names)) |
+| `name` | Symbol/String | Yes | — | Component name. Must be unique within the slot. Re-registering the same name replaces the component. |
+| `partial` | String | Yes | — | Rails partial path |
+| `position` | Integer | No | 10 | Render order within the slot (ascending). Built-ins use multiples of 10. |
+| `enabled` | Lambda | No | Always enabled | `(SlotContext) -> Boolean`. Return `false` to skip rendering. |
+
+### `ViewSlots::Registry.components_for(page, slot)`
+
+Returns an array of `SlotComponent` objects sorted by position.
+
+```ruby
+components = LcpRuby::ViewSlots::Registry.components_for(:index, :toolbar_end)
+# => [#<SlotComponent name=:manage_all position=5>, #<SlotComponent name=:collection_actions position=10>]
+```
+
+### `ViewSlots::Registry.registered?(page, slot, name)`
+
+Returns `true` if a component with the given name is registered in the slot.
+
+```ruby
+LcpRuby::ViewSlots::Registry.registered?(:index, :filter_bar, :search)
+# => true
+```
+
+### `ViewSlots::Registry.clear!`
+
+Removes all registered components. Used in test teardown.
+
+## Slot Names
+
+### Index Page
+
+| Slot | Location | Built-in Components |
+|------|----------|---------------------|
+| `:page_header` | Above the page title | *(none)* |
+| `:toolbar_start` | Toolbar left side | *(none)* |
+| `:toolbar_center` | Toolbar middle | `view_switcher` (10) |
+| `:toolbar_end` | Toolbar right side | `manage_all` (5), `collection_actions` (10) |
+| `:filter_bar` | Below toolbar | `search` (10), `predefined_filters` (20), `advanced_filter` (30) |
+| `:below_content` | Below the table | `summary_bar` (3), `pagination_footer` (10) |
+
+### Show Page
+
+| Slot | Location | Built-in Components |
+|------|----------|---------------------|
+| `:page_header` | Above the page title | *(none)* |
+| `:toolbar_start` | Toolbar left side | `view_switcher` (10), `back_to_list` (20) |
+| `:toolbar_end` | Toolbar right side | `copy_url` (10), `single_actions` (20) |
+| `:below_content` | Below the sections | `approval_status` (5)* |
+
+\* The `approval_status` component is registered dynamically by `Workflow::Approval::Setup` when any workflow has approvals configured. It is enabled only when the current record has an active approval request.
+
+## Built-in Components
+
+All built-in components are registered at engine boot via `ViewSlots::Registry.register_built_ins!`.
+
+| Name | Page | Slot | Position | Description |
+|------|------|------|----------|-------------|
+| `view_switcher` | index | toolbar_center | 10 | View group tab navigation |
+| `manage_all` | index | toolbar_end | 5 | "Manage All" link (custom fields) |
+| `collection_actions` | index | toolbar_end | 10 | "New" button and other collection actions |
+| `search` | index | filter_bar | 10 | Quick search form |
+| `predefined_filters` | index | filter_bar | 20 | Predefined filter scope buttons |
+| `advanced_filter` | index | filter_bar | 30 | Visual filter builder panel |
+| `summary_bar` | index | below_content | 3 | Aggregate summary bar (when `summary.enabled`) |
+| `pagination_footer` | index | below_content | 10 | Pagination footer bar (per-page selector, record count, page links) |
+| `view_switcher` | show | toolbar_start | 10 | View group tab navigation |
+| `back_to_list` | show | toolbar_start | 20 | "Back to list" link |
+| `copy_url` | show | toolbar_end | 10 | "Copy link" button |
+| `single_actions` | show | toolbar_end | 20 | Edit, Delete, and custom action buttons |
+| `approval_status`* | show | below_content | 5 | Approval progress, step/task details, action buttons |
+
+\* Registered dynamically by `Workflow::Approval::Setup`, not part of `BUILT_IN_COMPONENTS`. Enabled when the record has an active approval request.
+
+## SlotContext
+
+Every slot partial receives a `slot_context` local variable — an immutable data object with the current page state.
+
+| Attribute | Type | Available on | Description |
+|-----------|------|--------------|-------------|
+| `presenter` | `PresenterDefinition` | All pages | Current presenter (slug, config, labels) |
+| `model_definition` | `ModelDefinition` | All pages | Model metadata (fields, validations) |
+| `evaluator` | `PermissionEvaluator` | All pages | Permission checks (`can?`, `field_writable?`) |
+| `action_set` | `ActionSet` | All pages | Visible actions for the current user |
+| `params` | Hash | All pages | Request parameters (filter, qs, sort) |
+| `records` | `ActiveRecord::Relation` | Index | Paginated record collection |
+| `record` | `ActiveRecord::Base` | Show | Current record |
+| `locals` | Hash | All pages | Custom data from controller (`@slot_locals`) |
+
+### Accessing SlotContext in Partials
+
+Built-in partials use `slot_context` for all data access:
+
+```erb
+<%# Use slot_context.presenter, not current_presenter %>
+<% if slot_context.presenter.search_config["enabled"] %>
+  ...
+<% end %>
+
+<%# Use slot_context.params, not params %>
+<%= text_field_tag :qs, slot_context.params[:qs] %>
+
+<%# Use slot_context.evaluator for permission checks %>
+<% if slot_context.evaluator.can?(:create) %>
+  ...
+<% end %>
+```
+
+Route helpers (`resources_path`, `new_resource_path`) and Rails helpers (`request.url`, `link_to`, `form_tag`) are accessed from the view context directly — they are not part of `SlotContext`.
+
+### Passing Custom Data via `locals`
+
+Controllers can pass arbitrary data to slot partials through `@slot_locals`:
+
+```ruby
+# In controller action
+@slot_locals = { manage_path: manage_custom_fields_path }
+```
+
+```erb
+<%# In slot partial %>
+<% manage_path = slot_context.locals[:manage_path] %>
+<% if manage_path %>
+  <%= link_to "Manage", manage_path, class: "btn" %>
+<% end %>
+```
+
+## SlotComponent
+
+Immutable value object representing a registered component.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `page` | Symbol | `:index` or `:show` |
+| `slot` | Symbol | Slot name |
+| `name` | Symbol | Component identifier |
+| `partial` | String | Rails partial path |
+| `position` | Integer | Render order (ascending) |
+| `enabled_callback` | Lambda or nil | Conditional rendering callback |
+
+### `enabled?(context)`
+
+Returns `true` if the component should render. Delegates to `enabled_callback` if set, otherwise returns `true`.
+
+## View Helper
+
+### `render_slot(slot, page:)`
+
+Renders all enabled components for a slot, joined as HTML-safe output.
+
+```erb
+<%= render_slot(:toolbar_end, page: :index) %>
+```
+
+Returns empty string if no components are registered for the slot. Components are:
+
+1. Fetched from `Registry.components_for(page, slot)`
+2. Filtered by `component.enabled?(slot_context)`
+3. Rendered via `render partial: component.partial, locals: { slot_context: context }`
+4. Joined with `safe_join`
+
+## Position Ordering
+
+Built-in components use positions in multiples of 10, leaving gaps for host app insertions:
+
+```
+position 5  → host app component (before built-in)
+position 10 → built-in component
+position 15 → host app component (after built-in)
+position 20 → next built-in component
+```
+
+Components at the same position are rendered in registration order.
+
+## Name-Based Override
+
+Registering a component with the same `name` in the same `(page, slot)` replaces the previous registration:
+
+```ruby
+# Override the built-in search with a custom implementation
+LcpRuby::ViewSlots::Registry.register(
+  page: :index, slot: :filter_bar, name: :search,
+  partial: "my_app/custom_search", position: 10
+)
+```
+
+This replaces the built-in search partial with the host app's version.
+
+---
+
+## What's Next
+
+- [View Slots Guide](../guides/view-slots.md) — Step-by-step guide to customizing page layouts
+- [Custom Renderers](../guides/custom-renderers.md) — Custom renderers for host applications
+- [Extensibility Guide](../guides/extensibility.md) — All extension mechanisms
+- [Page Layouts & View Slots Spec](../design/page_layout_and_slots.md) — Full feature specification including future layout variants