lcp 0.1.0

data/docs/guides/custom-actions.md

@@ -0,0 +1,238 @@
+# Custom Actions
+
+Custom actions let host apps define domain-specific operations beyond standard CRUD. Use them for business logic like "Close Deal as Won," "Send Invoice," or "Archive Project."
+
+## When to Use Custom Actions
+
+Use a custom action when you need to:
+- Execute business logic that goes beyond simple field updates
+- Provide a user-facing button with confirmation dialogs
+- Return custom responses (redirects, CSV downloads, JSON data)
+- Enforce action-specific authorization beyond CRUD permissions
+
+For simple field updates, standard CRUD (edit/update) is sufficient.
+
+## Creating an Action
+
+Create a file at `app/actions/<model>/<action>.rb`:
+
+```ruby
+module LcpRuby
+  module HostActions
+    module Deal
+      class CloseWon < LcpRuby::Actions::BaseAction
+        def call
+          unless record
+            return failure(message: "No deal specified")
+          end
+
+          if record.stage.in?(["closed_won", "closed_lost"])
+            return failure(message: "Deal is already closed")
+          end
+
+          record.update!(stage: "closed_won")
+          success(message: "Deal '#{record.title}' marked as won!")
+        end
+      end
+    end
+  end
+end
+```
+
+The class is resolved by convention: `LcpRuby::HostActions::<Model>::<ActionName>`.
+
+- Module nesting matches the model name (e.g., `Deal` for model `deal`)
+- Class name matches the action name in CamelCase (e.g., `CloseWon` for action `close_won`)
+
+> **Action lookup is model-scoped, not presenter-scoped.** If a model has multiple presenters (e.g. `deal.rb` and `deal_archive.rb`), all of them resolve `action :close_won, type: :custom` to the same `LcpRuby::HostActions::Deal::CloseWon` class. There is no per-presenter override path. If you need different behavior for different presenters of the same model, declare distinct action names (`close_won_archive`, `close_won_active`, …) and put each presenter's actions in its own class.
+
+## BaseAction API
+
+### Available in `#call`
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `record` | AR instance | The target record (single actions) |
+| `records` | array | Array of records (batch actions) |
+| `current_user` | User | The current user |
+| `params` | Hash | Request parameters |
+| `model_class` | Class | The dynamic AR model class |
+
+### Return Values
+
+Every `#call` must return a result object using one of these methods:
+
+**`success(message:, redirect_to:, data:)`**
+
+```ruby
+# Simple success
+success(message: "Done!")
+
+# With redirect
+success(message: "Created!", redirect_to: "/deals")
+
+# With data (for JSON responses)
+success(data: { count: 5 })
+```
+
+**`failure(message:, errors:)`**
+
+```ruby
+# Simple failure
+failure(message: "Cannot close this deal")
+
+# With error details
+failure(message: "Validation failed", errors: record.errors.full_messages)
+```
+
+#### Result kwargs
+
+The kwargs map onto the controller response as follows. All are optional unless noted.
+
+| Method | Kwarg | Type | Effect |
+|--------|-------|------|--------|
+| `success` | `message:` | String | Flash notice (`flash[:notice]`). Omit for a silent success. |
+| `success` | `redirect_to:` | String / path helper | HTTP redirect target. When omitted, the controller stays on the source page (HTML) or returns the JSON payload (XHR). |
+| `success` | `data:` | Hash | Custom payload for JSON / download responses. Ignored for plain HTML redirects. |
+| `failure` | `message:` | String (**required**) | Flash error (`flash[:alert]`). Always shown. |
+| `failure` | `errors:` | Array&lt;String&gt; | Per-field / per-record validation messages. Rendered alongside `message:` (e.g. as a list under the alert). |
+
+`failure` never honours `redirect_to:` — the controller re-renders the source page so error context is preserved. To redirect on failure, build the URL yourself and call `success(message: …, redirect_to: …)` from a guarded branch.
+
+#### Localized messages with `I18n.t`
+
+Actions execute synchronously inside the controller's request cycle, **inside** the `I18n.with_locale(...)` block established by `Controller::LocaleBinding`. That means `I18n.t` calls inside `#call` automatically use the request's resolved locale (`current_user.profile[:locale]` → `Accept-Language` → `I18n.default_locale`):
+
+```ruby
+def call
+  record.update!(stage: "won")
+  success(message: I18n.t("deals.actions.closed_won"))
+end
+```
+
+If the translation key is missing, pass a `default:` so the action does not crash:
+
+```ruby
+success(message: I18n.t("deals.actions.closed_won", default: "Deal closed."))
+```
+
+> **Async actions:** when `async: true` enqueues the action through `BackgroundJobs`, the worker runs **outside** the request cycle and `I18n.locale` falls back to `I18n.default_locale`. If the worker needs the user's locale, pass it explicitly via `params:` and wrap the call in `I18n.with_locale(params[:locale]) { ... }`.
+
+### Class-Level Overrides
+
+**`.visible?(record, user)`** — control whether the action button appears in the UI for a given record and user. Defaults to `true`.
+
+```ruby
+def self.visible?(record, user)
+  record.stage != "closed"
+end
+```
+
+**`.authorized?(record, user)`** — additional authorization check beyond permission YAML. Defaults to `true`. In batch context with per-record iteration, this is called for each record — unauthorized records are skipped.
+
+```ruby
+def self.authorized?(record, user)
+  user.department == record.department
+end
+```
+
+**`.batch_capable?`** — indicates whether the action handles the `records` array directly. Defaults to `false`, meaning the platform iterates per-record automatically during batch execution. Override to `true` for bulk operations (e.g., `update_all`). See [Batch Actions Guide](batch-actions.md#custom-batch-actions) for details.
+
+```ruby
+def self.batch_capable?
+  true
+end
+```
+
+**`.param_schema`** — define expected parameters for the action.
+
+```ruby
+def self.param_schema
+  { reason: { type: :string, required: true } }
+end
+```
+
+## Registering the Action in YAML
+
+Reference the action in a [presenter YAML](../reference/presenters.md#actions-configuration):
+
+```yaml
+actions:
+  single:
+    - name: close_won
+      type: custom
+      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] }
+```
+
+### Confirm Per Role
+
+The `confirm` attribute can be role-specific. Use a hash with `except` or `only` to control which roles see the confirmation dialog:
+
+```yaml
+# Admin skips confirmation, everyone else sees it
+- name: archive
+  type: custom
+  label: "Archive"
+  confirm:
+    except: [admin]
+  confirm_message: "Are you sure you want to archive this?"
+
+# Only viewers and sales_reps see confirmation
+- name: force_delete
+  type: custom
+  label: "Force Delete"
+  confirm:
+    only: [viewer, sales_rep]
+```
+
+See [Presenters Reference — Confirm Per Role](../reference/presenters.md#confirm-per-role) for the full syntax.
+
+### Action Categories
+
+| Category | Use For |
+|----------|---------|
+| `collection` | Actions that don't target a specific record (e.g., "Export All") |
+| `single` | Actions on one record (e.g., "Close Deal") |
+| `batch` | Actions on multiple selected records (e.g., "Archive Selected") |
+
+## Auto-Discovery
+
+Enable auto-discovery in your initializer so action classes are automatically registered:
+
+```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)
+end
+```
+
+This scans `app/actions/` for classes following the naming convention and registers them.
+
+## Permission Control
+
+Custom action execution is controlled by the `actions` attribute in [permissions YAML](../reference/permissions.md#actions):
+
+```yaml
+roles:
+  sales_rep:
+    actions:
+      allowed: [close_won]
+      denied: []
+```
+
+The `PermissionEvaluator.can_execute_action?` method checks this configuration before executing the action.
+
+## Response Handling
+
+The `ActionsController` handles three response formats based on the result:
+
+- **HTML** — redirects with a flash message (default)
+- **CSV** — sends a file download when `data` contains CSV content
+- **JSON** — returns JSON when requested
+
+Source: `lib/lcp_ruby/actions/base_action.rb`, `lib/lcp_ruby/actions/action_registry.rb`, `lib/lcp_ruby/actions/action_executor.rb`

data/docs/guides/custom-fields.md

@@ -0,0 +1,439 @@
+# Custom Fields Guide
+
+Custom fields let users define additional fields on models at runtime — no code changes, no migrations, no server restarts. This is useful for systems where end-users or administrators need to extend the data model to fit their specific needs.
+
+## When to Use Custom Fields
+
+Custom fields are a good fit when:
+- End-users need to add domain-specific fields (e.g., a CRM where each company tracks different metadata)
+- The set of fields varies per deployment or tenant
+- You want to avoid creating a new migration for every client-specific field
+
+Custom fields are **not** a replacement for regular model fields. Use regular fields for core domain attributes that are shared across all deployments.
+
+## Quick Start
+
+### Step 1: Generate custom field definition metadata
+
+Run the generator to create the `custom_field_definition` model, presenter, permissions, and view group:
+
+```bash
+rails generate lcp_ruby:custom_fields
+```
+
+This creates:
+- `config/lcp_ruby/models/custom_field_definition.rb` — model definition (DSL format)
+- `config/lcp_ruby/presenters/custom_fields.rb` — presenter definition (DSL format)
+- `config/lcp_ruby/permissions/custom_field_definition.yml` — permissions
+- `config/lcp_ruby/views/custom_fields.rb` — view group (DSL format)
+
+For YAML format instead of DSL, use `--format=yaml`.
+
+### Step 2: Enable custom fields on a model
+
+```yaml
+# config/lcp_ruby/models/project.yml
+model:
+  name: project
+  options:
+    custom_fields: true
+  fields:
+    - name: name
+      type: string
+      validations:
+        - type: presence
+    - name: status
+      type: string
+      default: active
+```
+
+Or with the Ruby DSL:
+
+```ruby
+# config/lcp_ruby/models/project.rb
+define_model :project do
+  custom_fields true
+  field :name, :string, validations: [{ type: :presence }]
+  field :status, :string, default: "active"
+end
+```
+
+### Step 3: Set up permissions
+
+The `custom_data` virtual field controls access to all custom fields. Include it in `readable` and `writable` field lists:
+
+```yaml
+# config/lcp_ruby/permissions/project.yml
+permissions:
+  model: project
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields:
+        readable: all    # 'all' automatically includes custom_data
+        writable: all
+    viewer:
+      crud: [index, show]
+      fields:
+        readable: all
+        writable: []
+```
+
+### Step 4: Customize permissions for custom field definitions (optional)
+
+The generator already created a permissions file for the `custom_field_definition` model. You can customize it:
+
+```yaml
+# config/lcp_ruby/permissions/custom_field_definition.yml
+permissions:
+  model: custom_field_definition
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions: all
+      scope: all
+      presenters: all
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      actions: { allowed: [] }
+      scope: all
+      presenters: all
+  default_role: viewer
+```
+
+### Step 5: Boot the app and create field definitions
+
+After starting the application, navigate to `/projects/custom-fields` (the nested custom fields management route). Create a new custom field definition:
+
+- **Field name**: `website` (lowercase, no spaces)
+- **Type**: `string`
+- **Label**: `Website URL`
+- **Section**: `Contact Info` (custom fields are grouped by section)
+
+The `target_model` is automatically set from the parent URL context (e.g., `/projects/custom-fields` sets it to `project`).
+
+### Manage Page (Bulk Editing)
+
+For editing all custom field definitions at once, use the **Manage All** page at `/:lcp_slug/custom-fields/manage`. This page renders all definitions in a bulk form with add/remove/reorder support.
+
+The manage page UI is fully **presenter-driven** — it reads the `custom_fields` presenter definition to determine which fields, sections, and conditions to render. There is no hardcoded field HTML. To customize what appears on the manage page, modify the `custom_fields` presenter:
+
+```ruby
+# config/lcp_ruby/presenters/custom_fields.rb
+define_presenter :custom_fields do
+  model :custom_field_definition
+  # ...
+
+  form do
+    section "General", columns: 3 do
+      field :field_name, readonly: true
+      field :custom_type
+      field :label
+      field :section
+      field :position
+      field :active
+    end
+
+    # This section only appears when custom_type is string or text
+    section "Text Constraints", columns: 2,
+      visible_when: { field: :custom_type, operator: :in, value: "string,text" } do
+        field :min_length
+        field :max_length
+        field :default_value
+        field :placeholder
+    end
+
+    # This section only appears when custom_type is a numeric type
+    section "Numeric Constraints", columns: 2,
+      visible_when: { field: :custom_type, operator: :in, value: "integer,float,decimal" } do
+        field :min_value
+        field :max_value
+        field :precision,
+          visible_when: { field: :custom_type, operator: :eq, value: "decimal" }
+    end
+
+    section "Enum Values",
+      visible_when: { field: :custom_type, operator: :eq, value: "enum" } do
+        field :enum_values
+    end
+  end
+end
+```
+
+The manage page uses [row-scoped conditional rendering](conditional-rendering.md#row-scoped-conditions-in-nested-fields) — each row evaluates `visible_when` conditions independently against its own data. Changing `custom_type` in one row only affects that row's visible sections.
+
+### Step 6: Use the custom fields
+
+Navigate to `/projects/new`. A new "Contact Info" section appears at the bottom of the form with the "Website URL" field. Fill it in, save, and the value persists.
+
+## Working with Sections
+
+Custom fields are grouped into sections by their `section` attribute. All fields sharing the same section value appear under the same heading.
+
+```
+Section: "Contact Info"     →  renders as <h2>Contact Info</h2>
+  - website (string)
+  - phone_number (string)
+
+Section: "Custom Fields"    →  renders as <h2>Custom Fields</h2>  (default)
+  - priority (integer)
+  - internal_notes (text)
+```
+
+Use the `position` attribute to control ordering within a section. Lower numbers appear first.
+
+## Field Types
+
+Each custom field has a `custom_type` that determines its behavior:
+
+| Type | Form Input | Validation Support |
+|------|-----------|-------------------|
+| `string` | Text field | `min_length`, `max_length`, `required` |
+| `text` | Textarea | `min_length`, `max_length`, `required` |
+| `integer` | Number field | `min_value`, `max_value`, `required` |
+| `float` | Number field | `min_value`, `max_value`, `required` |
+| `decimal` | Number field | `min_value`, `max_value`, `precision`, `required` |
+| `boolean` | Checkbox | `required` |
+| `date` | Date picker | `required` |
+| `datetime` | Datetime picker | `required` |
+| `enum` | Select dropdown | `enum_values` (required), `required` |
+
+## Enum Fields
+
+When defining an enum custom field, provide the `enum_values` attribute as a JSON array:
+
+```json
+["low", "medium", "high"]
+```
+
+Or with custom labels:
+
+```json
+[
+  { "value": "low", "label": "Low Priority" },
+  { "value": "medium", "label": "Medium Priority" },
+  { "value": "high", "label": "High Priority" }
+]
+```
+
+Validation ensures only allowed values are accepted.
+
+## Enabling Search
+
+Set `searchable: true` on a custom field definition to include it in the index page's text search. When a user types in the search box, custom searchable fields are searched alongside regular searchable fields.
+
+> **Note:** Search on custom fields uses JSON extraction functions, which may be slower than searching regular indexed columns on large datasets. Use `searchable: true` selectively.
+
+## Table Column Visibility
+
+By default, custom fields do not appear in the index table. Set `show_in_table: true` to add them as table columns. You can also control:
+
+- `sortable: true` — allows clicking the column header to sort
+- `column_width: "150px"` — sets a CSS width for the column
+
+## Programmatic Access
+
+Custom field values can be read and written in Ruby code:
+
+```ruby
+model = LcpRuby.registry.model_for("project")
+record = model.find(1)
+
+# Using dynamic accessors (after definitions are loaded)
+record.website                      # => "https://example.com"
+record.website = "https://new.com"
+record.save!
+
+# Using the generic low-level API
+record.read_custom_field("website")
+record.write_custom_field("website", "https://new.com")
+record.save!
+```
+
+### Creating Definitions Programmatically
+
+```ruby
+cfd = LcpRuby.registry.model_for("custom_field_definition")
+
+cfd.create!(
+  target_model: "project",
+  field_name: "budget",
+  custom_type: "decimal",
+  label: "Budget",
+  section: "Financials",
+  required: false,
+  min_value: 0,
+  precision: 2,
+  show_in_table: true,
+  sortable: true
+)
+```
+
+After creating a definition, the `after_commit` callback automatically refreshes the accessor cache on the target model. No restart needed.
+
+## Default Values
+
+Custom fields support default values. When a definition has `default_value` set, new records automatically receive that value:
+
+```ruby
+cfd.create!(
+  target_model: "project",
+  field_name: "status_cf",
+  custom_type: "string",
+  label: "Status",
+  default_value: "active"
+)
+
+record = project_model.new(name: "New Project")
+record.status_cf  # => "active"  (applied automatically)
+
+record.status_cf = "draft"
+record.status_cf  # => "draft"  (explicit value wins)
+```
+
+Defaults are applied via `after_initialize` only for `new_record?` — existing records loaded from the database are never modified.
+
+## Deleting Custom Field Definitions
+
+When a custom field definition is deleted:
+1. The cached definitions are cleared for the affected model
+2. Dynamic accessors (getter/setter methods) for the deleted field are **removed** from the model class
+3. The field value in `custom_data` JSON is preserved (data is not deleted)
+4. The field no longer appears in forms, show views, or table columns
+
+This means `record.respond_to?(:deleted_field)` returns `false` after deletion and re-apply.
+
+## Permission Model
+
+Custom fields support both aggregate and per-field permissions.
+
+### Aggregate: `custom_data` catch-all
+
+The `custom_data` key grants access to **all** active custom fields at once:
+
+| Scenario | Permission Config | Result |
+|----------|------------------|--------|
+| Full access | `readable: all, writable: all` | All custom fields visible and editable |
+| Read-only | `readable: all, writable: []` | Custom fields visible but not editable |
+| No access | `readable: [name, status]` (no `custom_data`) | Custom fields hidden entirely |
+| Explicit | `readable: [name, custom_data], writable: [custom_data]` | Only custom fields writable |
+
+### Per-field: individual custom field names
+
+Individual custom field names can appear in `readable`, `writable`, and `field_overrides`:
+
+```yaml
+permissions:
+  model: project
+  roles:
+    editor:
+      fields:
+        readable: [name, status, website, phone]
+        writable: [name, website]
+    viewer:
+      fields:
+        readable: [name, custom_data]  # catch-all: ALL custom fields
+        writable: []
+  field_overrides:
+    internal_notes:
+      readable_by: [admin, manager]
+      writable_by: [admin]
+```
+
+The `custom_data` catch-all and individual field names are backward compatible — `custom_data` still works as before, but you can now selectively grant access to specific custom fields.
+
+> **Note:** The `readable_by_roles` and `writable_by_roles` attributes on individual field definitions are reserved for future use. Per-field role-based access control is currently managed through the permission system's `field_overrides`.
+
+## Management UI
+
+Custom field definitions are managed via nested routes under the parent model's slug:
+
+```
+GET    /:lcp_slug/custom-fields          # Index
+GET    /:lcp_slug/custom-fields/new      # New form
+POST   /:lcp_slug/custom-fields          # Create
+GET    /:lcp_slug/custom-fields/:id      # Show
+GET    /:lcp_slug/custom-fields/:id/edit # Edit form
+PATCH  /:lcp_slug/custom-fields/:id      # Update
+DELETE /:lcp_slug/custom-fields/:id      # Destroy
+```
+
+For example, if your model presenter has slug `projects`, the management URL is `/projects/custom-fields`. The `target_model` is resolved from the parent URL context and cannot be tampered with via form params.
+
+Authorization is controlled by the `permissions/custom_field_definition.yml` file. Per-target-model restrictions are possible via `record_rules` on the `target_model` field.
+
+## Database Details
+
+### Storage
+
+Custom field values are stored in a single `custom_data` column:
+
+- **PostgreSQL**: `jsonb` type with a GIN index for efficient querying
+- **SQLite**: `json` type (no special indexing)
+
+The column is auto-created when the model table is first built or updated by the schema manager.
+
+### Conflict Avoidance
+
+The engine prevents custom field names from conflicting with:
+- Existing database columns on the model
+- Reserved names: `id`, `type`, `created_at`, `updated_at`, `custom_data`
+
+If a custom field definition has the same name as an existing column, the dynamic accessor is not created (the real column takes precedence).
+
+## Architecture
+
+The custom fields system consists of eight components:
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `CustomFields::Registry` | `lib/lcp_ruby/custom_fields/registry.rb` | Per-model cache of active definitions |
+| `CustomFields::Applicator` | `lib/lcp_ruby/custom_fields/applicator.rb` | Installs read/write methods, accessors, validations, and defaults |
+| `CustomFields::ContractValidator` | `lib/lcp_ruby/custom_fields/contract_validator.rb` | Validates the custom_field_definition model contract at boot |
+| `CustomFields::Query` | `lib/lcp_ruby/custom_fields/query.rb` | DB-portable JSON query helpers with field name validation |
+| `CustomFields::DefinitionChangeHandler` | `lib/lcp_ruby/custom_fields/definition_change_handler.rb` | Cache invalidation on definition changes |
+| `CustomFields::Setup` | `lib/lcp_ruby/custom_fields/setup.rb` | Shared boot logic (registry, handlers, accessors, scopes) |
+| `CustomFields::Utils` | `lib/lcp_ruby/custom_fields/utils.rb` | Environment-aware JSON parsing and numeric conversion |
+
+### Data Flow
+
+```
+custom_field_definitions table
+  │
+  ├── CustomFields::Registry.for_model("project")
+  │   └── returns cached Array of definition records
+  │
+  ├── CustomFields::Applicator
+  │   └── defines read_custom_field / write_custom_field
+  │   └── defines dynamic getters/setters via apply_custom_field_accessors!
+  │   │   (tracks defined accessors; removes stale ones on re-apply)
+  │   └── installs validate :validate_custom_fields
+  │   └── applies default_value to new records via after_initialize
+  │
+  ├── CustomFields::Setup.apply!(loader)
+  │   └── orchestrates boot: registry, handlers, accessors, scopes
+  │
+  ├── Presenter::LayoutBuilder
+  │   └── appends custom field sections to form_sections / show_sections
+  │
+  ├── Presenter::ColumnSet
+  │   └── filters custom fields by custom_data permission
+  │
+  ├── CustomFieldsController
+  │   └── nested routes: /:lcp_slug/custom-fields
+  │   └── resolves target_model from parent URL context
+  │   └── scopes records by target_model
+  │
+  └── ResourcesController
+      └── permits custom field params when custom_data is writable
+      └── includes searchable custom fields in text search
+```
+
+## See Also
+
+- [Custom Fields Reference](../reference/custom-fields.md) — complete attribute reference for all definition fields
+- [Models Reference](../reference/models.md#custom_fields) — `custom_fields` option
+- [Permissions Reference](../reference/permissions.md) — field-level access control
+- [Model DSL Reference](../reference/model-dsl.md#custom_fields) — DSL syntax