lcp 0.1.0

data/docs/guides/eager-loading.md

@@ -0,0 +1,230 @@
+# Eager Loading Guide
+
+## Quick Start
+
+The engine prevents N+1 queries automatically. When you add a FK column to your index table or an association list to your show page, the engine detects the dependency and eager-loads the associated records.
+
+**Before (N+1 problem):** Without eager loading, displaying a company name for each deal triggers a separate `SELECT` per deal:
+
+```
+SELECT * FROM deals ...
+SELECT * FROM companies WHERE id = 1  -- for deal 1
+SELECT * FROM companies WHERE id = 2  -- for deal 2
+SELECT * FROM companies WHERE id = 3  -- for deal 3
+... (one per deal)
+```
+
+**After (batched):** With the engine's auto-detection, all companies are loaded in one query:
+
+```
+SELECT * FROM deals ...
+SELECT * FROM companies WHERE id IN (1, 2, 3, ...)
+```
+
+## Common Patterns
+
+### Displaying Parent Name in Child Index
+
+Add the FK column to `table_columns`. The engine auto-detects the `belongs_to` association and eager-loads it:
+
+```yaml
+# presenters/deal.yml
+index:
+  table_columns:
+    - { field: title, width: "40%" }
+    - { field: company_id, width: "20%" }   # Auto-detects belongs_to :company
+    - { field: stage, width: "20%" }
+```
+
+The index view renders the company's `to_label` (or `label_method` from model config) instead of the raw integer ID.
+
+### Show Page with Association Lists
+
+Add `association_list` sections to the show layout. The engine preloads the associated records:
+
+```yaml
+# presenters/company.yml
+show:
+  layout:
+    - section: "Company Information"
+      columns: 2
+      fields:
+        - { field: name, renderer: heading }
+        - { field: industry }
+    - section: "Contacts"
+      type: association_list
+      association: contacts      # Auto-preloads :contacts
+    - section: "Deals"
+      type: association_list
+      association: deals         # Auto-preloads :deals
+    - section: "Members"
+      type: association_list
+      association: group_memberships
+      link_through: employee     # Auto-preloads { group_memberships: [:employee] }
+```
+
+### Nested Forms
+
+Nested fields sections automatically preload the child association on edit:
+
+```yaml
+form:
+  sections:
+    - title: "Items"
+      type: nested_fields
+      association: todo_items    # Auto-preloads :todo_items on edit
+      fields:
+        - { field: title }
+        - { field: completed }
+```
+
+### Dot-Path Fields (Association Traversal)
+
+When using dot-notation fields like `company.name` or `contacts.full_name`, the engine automatically detects the association chain and eager-loads all required associations:
+
+```yaml
+# presenters/deal.yml
+index:
+  table_columns:
+    - { field: title, width: "40%" }
+    - { field: "company.name", width: "20%" }      # Auto-detects belongs_to :company
+    - { field: "contact.full_name", width: "20%" }  # Auto-detects belongs_to :contact
+```
+
+Deep dot-paths are also supported — `company.industry.name` will preload `{ company: :industry }`.
+
+Template fields with dot-path references also trigger eager loading:
+
+```yaml
+table_columns:
+  - { field: "{company.name}: {title}" }  # Auto-detects :company
+```
+
+### Link-through Columns and Fields
+
+`link: true` / `link_through:` on index columns and show fields add eager-loads for the associations they reference — no manual `includes:` needed. See the [Linking dot-path fields and columns](presenters.md#linking-dot-path-fields-and-columns) section of the presenters guide.
+
+```yaml
+# presenters/membership.yml
+index:
+  table_columns:
+    - { field: "employee.full_name", link: true }  # preloads :employee
+    - { field: manager_label, link_through: manager }  # preloads :manager
+
+show:
+  layout:
+    - section: "Details"
+      fields:
+        - { field: employee, link: true }  # plain belongs_to — preloads :employee
+```
+
+Dot-path-based links (like `"employee.full_name"`) are covered by existing dot-path detection. Plain-association and `link_through:` on non-dot-path fields use a dedicated collector that adds the include with `reason: :display`.
+
+### Has-Many Collection Fields
+
+Displaying has_many fields in the index table also triggers eager loading:
+
+```yaml
+table_columns:
+  - field: "contacts.full_name"           # Auto-detects has_many :contacts
+    renderer: collection
+    options: { limit: 3 }
+```
+
+### Conditions Referencing Associations
+
+When `item_classes` or action `visible_when`/`disable_when` conditions reference associations via dot-paths or collection quantifiers, those associations need eager loading too. The `DependencyCollector` auto-detects these at runtime, but the `ConfigurationValidator` emits warnings recommending explicit `includes` for clarity:
+
+```yaml
+index:
+  includes: [company, approvals]    # Explicit: covers condition dependencies
+  table_columns:
+    - { field: title }
+  item_classes:
+    - class: verified-row
+      when: { field: "company.verified", operator: eq, value: true }
+    - class: approved-row
+      when:
+        collection: approvals
+        quantifier: any
+        condition: { field: status, operator: eq, value: approved }
+```
+
+Without explicit `includes`, the engine auto-includes them but the validator warns:
+
+```
+Presenter 'tasks' index: item_classes[0] references 'company' but index.includes
+does not contain 'company'. Add 'includes: [company]' to the index configuration
+to avoid N+1 queries.
+```
+
+**Note:** This validation applies only to index-context conditions (`item_classes`, action `visible_when`/`disable_when`). Show and form conditions evaluate against single records where lazy loading is acceptable.
+
+## Enabling strict_loading for Development
+
+Add to your initializer to catch any remaining lazy loads:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.strict_loading = :development
+end
+```
+
+This raises `ActiveRecord::StrictLoadingViolationError` whenever a lazy association load occurs on LCP-managed index pages, helping you identify missing eager loads during development.
+
+## Manual Overrides
+
+For edge cases where auto-detection doesn't cover your needs, add explicit includes:
+
+```yaml
+index:
+  includes: [company, contact]
+  table_columns:
+    - { field: title }
+```
+
+Or in DSL:
+
+```ruby
+index do
+  includes :company, :contact
+  column :title
+end
+```
+
+Use `eager_load` when you need a LEFT JOIN (e.g., for future sorting/filtering by association columns):
+
+```yaml
+index:
+  eager_load: [company]
+```
+
+## Troubleshooting
+
+### Checking Query Counts
+
+Enable Rails SQL logging to see actual queries:
+
+```ruby
+# In Rails console or test
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+```
+
+Or check the Rails development log (`log/development.log`) for SELECT query counts after loading an index page.
+
+### FK Column Shows ID Instead of Name
+
+If a FK column (e.g., `company_id`) shows the integer ID instead of the company name:
+
+1. Verify the model has a `belongs_to` association with matching `foreign_key`
+2. Verify the target model has a `label_method` in its options (or implements `to_label`)
+3. Check that the FK field is included in the permission's `readable` fields
+
+### Association Not Preloaded
+
+If you see N+1 queries despite adding a FK column:
+
+1. Check the presenter YAML has the column in `table_columns`
+2. Verify the model YAML has the `belongs_to` association defined
+3. Check the `foreign_key` in the association matches the column `field` name

data/docs/guides/event-handlers.md

@@ -0,0 +1,135 @@
+# Event Handlers
+
+Event handlers respond to model lifecycle events (create, update, destroy) and field value changes. Use them for logging, notifications, side effects, and workflow automation.
+
+## When to Use Event Handlers
+
+Use event handlers when you need to:
+- Log important state transitions (e.g., deal stage changes)
+- Send notifications when records change
+- Trigger external integrations (e.g., sync to CRM, send webhooks)
+- Enforce business rules as side effects (e.g., auto-assign records)
+
+For operations that the user explicitly triggers, use [custom actions](custom-actions.md) instead.
+
+## Defining Events in Model YAML
+
+First, declare the events in your [model YAML](../reference/models.md#events):
+
+```yaml
+events:
+  - name: after_create
+    type: lifecycle
+  - name: on_stage_change
+    type: field_change
+    field: stage
+```
+
+### Event Types
+
+| Type | Trigger | Requires `field` |
+|------|---------|-----------------|
+| `lifecycle` | ActiveRecord callbacks (`after_create`, `after_update`, `before_destroy`, `after_destroy`) or soft delete events (`after_discard`, `after_undiscard`) | no |
+| `field_change` | A specific field's value changes during an update | yes |
+
+The `after_discard` and `after_undiscard` events are dispatched by the [soft delete](soft-delete.md) system when a record is discarded or restored. They fire after cascade discard/undiscard is complete.
+
+## Creating a Handler
+
+Create a file at `app/event_handlers/<model>/<handler>.rb`:
+
+```ruby
+module LcpRuby
+  module HostEventHandlers
+    module Deal
+      class OnStageChange < LcpRuby::Events::HandlerBase
+        def self.handles_event
+          "on_stage_change"
+        end
+
+        def call
+          old_stage = old_value("stage")
+          new_stage = new_value("stage")
+          Rails.logger.info("[CRM] Deal '#{record.title}' stage: #{old_stage} -> #{new_stage}")
+        end
+      end
+    end
+  end
+end
+```
+
+The class follows the same nesting convention as actions: `LcpRuby::HostEventHandlers::<Model>::<HandlerName>`.
+
+### Required Class Method
+
+**`self.handles_event`** — returns the event name string this handler responds to. Must match the `name` in the model YAML event definition.
+
+## HandlerBase API
+
+### Available in `#call`
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `record` | AR instance | The affected record |
+| `changes` | Hash | Hash of changed attributes (`{ "field" => [old, new] }`) |
+| `current_user` | User | The current user |
+| `event_name` | String | Name of the triggered event |
+
+### Convenience Methods
+
+| Method | Description |
+|--------|-------------|
+| `old_value(field)` | Previous value of a field (before the change) |
+| `new_value(field)` | New value of a field (after the change) |
+| `field_changed?(field)` | Whether a specific field changed |
+
+## Async Handlers
+
+For long-running operations (API calls, email sending), override `async?` to run the handler via ActiveJob:
+
+```ruby
+class SendNotification < LcpRuby::Events::HandlerBase
+  def self.handles_event
+    "after_create"
+  end
+
+  def async?
+    true
+  end
+
+  def call
+    NotificationMailer.new_deal(record).deliver_later
+  end
+end
+```
+
+Async handlers are executed by `AsyncHandlerJob`. Make sure your ActiveJob backend (Sidekiq, etc.) is configured.
+
+## Auto-Discovery
+
+Enable auto-discovery in your initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+Rails.application.config.after_initialize do
+  app_path = Rails.root.join("app")
+  LcpRuby::Events::HandlerRegistry.discover!(app_path.to_s)
+end
+```
+
+This scans `app/event_handlers/` for classes following the naming convention and registers them.
+
+## Complete Initializer Pattern
+
+A host app typically registers both actions and event handlers together:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+Rails.application.config.after_initialize do
+  app_path = Rails.root.join("app")
+  LcpRuby::Actions::ActionRegistry.discover!(app_path.to_s)
+  LcpRuby::Events::HandlerRegistry.discover!(app_path.to_s)
+end
+```
+
+Source: `lib/lcp_ruby/events/handler_base.rb`, `lib/lcp_ruby/events/handler_registry.rb`, `lib/lcp_ruby/events/dispatcher.rb`, `lib/lcp_ruby/events/async_handler_job.rb`

data/docs/guides/export.md

@@ -0,0 +1,305 @@
+# Export Guide
+
+This guide walks through setting up data export on your presenters, from basic CSV export to saved profiles and export history.
+
+## Prerequisites
+
+- A working LCP Ruby application with at least one model and presenter
+- For XLSX support: add `gem 'caxlsx'` to your Gemfile
+- For export profiles and history: Active Storage configured in your application
+
+## Basic Setup
+
+### 1. Add Export Config to Your Presenter
+
+**YAML:**
+
+```yaml
+presenter:
+  name: employees
+  model: employee
+
+  export:
+    formats: [csv, xlsx]
+```
+
+**DSL:**
+
+```ruby
+define_presenter :employees do
+  model :employee
+
+  export formats: [:csv, :xlsx]
+end
+```
+
+### 2. Add the Export Action
+
+Export requires an explicit action declaration. You can add it to collection actions, batch actions, or both:
+
+**YAML:**
+
+```yaml
+actions:
+  collection:
+    - { name: export, type: built_in, icon: download }
+    - { name: create, type: built_in, label: "New Employee" }
+  batch:
+    - { name: export, type: built_in, icon: download }
+    - { name: destroy, type: built_in, icon: trash, confirm: true, style: danger }
+```
+
+**DSL:**
+
+```ruby
+action :export, type: :built_in, on: :collection, icon: "download"
+action :export, type: :built_in, on: :batch, icon: "download"
+action :create, type: :built_in, on: :collection, label: "New Employee"
+action :destroy, type: :built_in, on: :batch, icon: "trash", confirm: true, style: :danger
+```
+
+### 3. Set Up Permissions
+
+The export action is authorized via the `actions` permission config, not the `crud` list:
+
+```yaml
+permissions:
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      actions: all
+    editor:
+      crud: [index, show, create, update]
+      actions:
+        allowed: [export]
+    viewer:
+      crud: [index, show]
+      actions:
+        allowed: []  # no export button
+```
+
+That's it for basic export. Users with the `export` action permission will see an Export button in the toolbar. Clicking it opens a dialog with format selection and a field picker.
+
+## Field Ceiling
+
+By default, the field picker shows all fields readable by the current user. You can restrict which fields appear:
+
+```ruby
+export formats: [:csv, :xlsx],
+  fields: [:name, :email, :department_id, :hire_date, :salary]
+```
+
+The `fields` list acts as a ceiling — it's intersected with the user's `readable_fields`. If a user's role only grants access to `[name, email]`, they'll only see those two fields even though the ceiling includes five.
+
+This is useful for hiding internal/technical fields (like `lock_version`, `updated_at`) from exports.
+
+## CSV Delimiter
+
+For European locales where comma is the decimal separator, use semicolon:
+
+```ruby
+export formats: [:csv], csv_delimiter: ";"
+```
+
+## Max Records
+
+Set a safety limit to prevent huge exports:
+
+```ruby
+export formats: [:csv, :xlsx], max_records: 5000
+```
+
+A COUNT query runs before loading records. If the count exceeds the limit, the dialog shows an error asking the user to apply filters. Default is 10,000.
+
+## Export Profiles and History
+
+To enable saved profiles and export history, run the generator:
+
+```bash
+rails generate lcp_ruby:export
+```
+
+This creates 6 metadata files:
+
+```
+config/lcp_ruby/models/export_profile.yml
+config/lcp_ruby/models/export_log.yml
+config/lcp_ruby/presenters/export_profiles.yml
+config/lcp_ruby/presenters/export_logs.yml
+config/lcp_ruby/permissions/export_profile.yml
+config/lcp_ruby/permissions/export_log.yml
+```
+
+### Saved Profiles
+
+After running the generator, the export dialog shows a "Save as profile" input. Users type a name and the current field selection + formatting is saved for future use.
+
+Profile visibility levels:
+
+| Level | Who sees it |
+|-------|-------------|
+| `personal` | Only the creator |
+| `role` | Users with the profile's target role |
+| `global` | All users |
+
+To browse and manage saved profiles, add them to your menu:
+
+```yaml
+menu:
+  items:
+    - view_group: export_profiles
+    - view_group: export_logs
+```
+
+### Export History
+
+Enable history tracking per presenter:
+
+```ruby
+export formats: [:csv, :xlsx], save_history: true
+```
+
+Every export creates an `export_log` record with:
+- Target presenter and format
+- Selected fields and applied filters (JSON snapshot)
+- Record count and file size
+- Attached file (via Active Storage)
+- Timestamps and userstamps
+
+## Association Fields
+
+The field picker automatically shows expandable groups for `belongs_to` and `has_one` associations. Users can select nested fields like `department.name` or `author.email`.
+
+Rules:
+- Only `belongs_to` and `has_one` are traversed (no `has_many`)
+- Max depth: 3 levels with cycle detection
+- FK fields are shown as regular fields alongside their expandable association groups
+- Each association level is permission-checked: a fresh `PermissionEvaluator` is built for the target model, showing only the user's readable fields on that model
+- When the target model has no permission definition, all non-excluded fields are shown
+- Column headers use humanized path segments (e.g., "Department Name")
+
+### FK Fields in the Ceiling
+
+When you specify a `fields` ceiling that includes FK fields, the corresponding associations are automatically included:
+
+```ruby
+export formats: [:csv, :xlsx],
+  fields: [:name, :department_id, :manager_id, :hire_date]
+```
+
+This shows `name`, `hire_date`, `department_id`, `manager_id` as regular fields, plus expandable groups for `department` and `manager`.
+
+### Timestamps and Userstamps
+
+Timestamp fields (`created_at`, `updated_at`) and userstamp fields (`created_by`, `updated_by`) are automatically included in the field picker when the model has `timestamps` or `userstamps` enabled. They are subject to the same `readable_fields` and `fields` ceiling filtering as regular fields.
+
+## Custom Column Headers
+
+Column headers default to humanized field names. Customize via i18n:
+
+```yaml
+# config/locales/en.yml
+en:
+  lcp_ruby:
+    export:
+      headers:
+        employee:
+          name: "Full Name"
+          email: "Email Address"
+          "department.name": "Dept."
+```
+
+Lookup order:
+1. `lcp_ruby.export.headers.<model>.<dot_path>`
+2. Humanized path segments joined with spaces
+
+## Formatting Options
+
+The export dialog includes a collapsible "Formatting options" section:
+
+| Type | Option | Values |
+|------|--------|--------|
+| Enum | Display as | Label / Raw key / Both |
+| Date | Format | ISO 8601 / Locale / Custom strftime |
+| Datetime | Format | ISO 8601 / Locale / Epoch / Custom strftime |
+| Boolean | Display as | true/false / Yes/No / 1/0 |
+| Decimal | Separator | Dot (.) / Comma (,) |
+
+Formatting options are saved with export profiles.
+
+## Filter and Sort Preservation
+
+Collection export automatically preserves the current view state:
+
+- **Filters** — quick search, predefined filters, advanced filters, custom field filters
+- **Sort order** — the exported file uses the same sort as the index page
+
+Users see exactly the same data in the export as on their screen (minus pagination).
+
+## Soft Delete Integration
+
+Export respects the presenter's scope:
+
+- **Active presenter** — exports only non-discarded records
+- **Archive presenter** (`scope: discarded`) — exports only discarded records
+- **Batch explicit mode** — exports exactly selected IDs regardless of discard status
+
+```ruby
+# Active view — export only active records
+define_presenter :documents do
+  export formats: [:csv, :xlsx]
+  action :export, type: :built_in, on: :collection, icon: "download"
+end
+
+# Archive view — export only discarded records
+define_presenter :documents_archive do
+  scope "discarded"
+  export formats: [:csv]
+  action :export, type: :built_in, on: :collection, icon: "download"
+end
+```
+
+## XLSX Support
+
+Add the `caxlsx` gem to your Gemfile:
+
+```ruby
+gem 'caxlsx'
+```
+
+XLSX exports feature bold header rows and automatic column width. If the gem is not installed and a user selects XLSX format, the dialog shows a clear error message.
+
+## Complete Example
+
+```ruby
+define_presenter :employees do
+  model :employee
+  label "Employees"
+  slug "employees"
+
+  # Export with all options
+  export formats: [:csv, :xlsx],
+    max_records: 5000,
+    save_history: true,
+    fields: [:name, :email, :role, :department_id, :hire_date, :salary],
+    csv_delimiter: ","
+
+  # ... index, show, form, search config ...
+
+  # Actions
+  action :export, type: :built_in, on: :collection, icon: "download"
+  action :export, type: :built_in, on: :batch, icon: "download"
+  action :create, type: :built_in, on: :collection, label: "New Employee"
+  action :show, type: :built_in, on: :single
+  action :edit, type: :built_in, on: :single
+  action :destroy, type: :built_in, on: :single, confirm: true, style: :danger
+  action :destroy, type: :built_in, on: :batch, icon: "trash", confirm: true, style: :danger
+end
+```
+
+## See Also
+
+- [Export Reference](../reference/export.md) — complete attribute reference
+- [Permissions Reference](../reference/permissions.md) — `actions` config
+- [Batch Actions Guide](batch-actions.md) — batch selection modes
+- [Soft Delete Guide](soft-delete.md) — discard/restore integration