lcp 0.1.0

data/docs/guides/userstamps.md

@@ -0,0 +1,288 @@
+# Userstamps Guide
+
+This guide covers automatic user tracking in LCP Ruby. When enabled, userstamps automatically record **who created** and **who last modified** each record — analogous to how Rails manages `created_at` / `updated_at` timestamps, but for user identity.
+
+## Quick Start
+
+Add `userstamps` to your model definition:
+
+**YAML:**
+
+```yaml
+model:
+  name: document
+  fields:
+    - { name: title, type: string }
+  options:
+    userstamps: true
+    timestamps: true
+```
+
+**DSL:**
+
+```ruby
+define_model :document do
+  field :title, :string
+
+  userstamps
+  timestamps true
+end
+```
+
+This automatically:
+- Creates `created_by_id` and `updated_by_id` columns (`bigint`, nullable, indexed)
+- Adds a `before_save` callback that sets them from `LcpRuby::Current.user`
+- Adds `belongs_to :created_by` and `belongs_to :updated_by` associations
+
+No additional setup is required — the platform handles column creation, callbacks, and associations.
+
+## How It Works
+
+The `UserstampsApplicator` registers a `before_save` callback on the model:
+
+- **On create** (`new_record?`): sets both `created_by_id` and `updated_by_id` to `Current.user.id`
+- **On update**: sets only `updated_by_id` — the creator is never overwritten
+- **No user** (`Current.user` is nil): writes `nil` to the fields without raising an error
+
+`LcpRuby::Current.user` is set automatically in `ApplicationController` for web requests. In seeds, jobs, or console sessions, set it manually:
+
+```ruby
+LcpRuby::Current.user = LcpRuby::User.find_by(email: "admin@example.com")
+# ... create/update records ...
+LcpRuby::Current.user = nil
+```
+
+> **Note:** `update_columns` bypasses the callback by design, just like Rails timestamps.
+
+## Name Snapshots
+
+By default, userstamps only store user IDs. Enable `store_name: true` to also capture a denormalized copy of the user's name at the time of create/update:
+
+**YAML:**
+
+```yaml
+options:
+  userstamps:
+    store_name: true
+```
+
+**DSL:**
+
+```ruby
+userstamps store_name: true
+```
+
+This adds two additional `string` columns:
+- `created_by_name` — set once on create
+- `updated_by_name` — refreshed on every save
+
+Name snapshots are useful when:
+- You want to display "Created by Jane Doe" without a JOIN
+- The user's name might change later, but you want to preserve the name at creation time
+- You need fast index rendering without eager-loading the user association
+
+The name is read from `Current.user.name`. Ensure your user model responds to `name`.
+
+## Custom Column Names
+
+Override the default column names when your domain model uses different terminology:
+
+**YAML:**
+
+```yaml
+options:
+  userstamps:
+    created_by: author_id
+    updated_by: editor_id
+    store_name: true
+```
+
+**DSL:**
+
+```ruby
+userstamps created_by: :author_id, updated_by: :editor_id, store_name: true
+```
+
+This creates:
+- `author_id` / `editor_id` (FK columns)
+- `author_name` / `editor_name` (name columns, derived by replacing `_id` with `_name`)
+- `belongs_to :author` / `belongs_to :editor` associations
+
+## Displaying in Presenters
+
+Userstamp fields are not regular model fields — they are auto-generated columns. To display them, reference them directly in your presenter:
+
+### Index Columns
+
+```ruby
+index do
+  column :title, link_to: :show
+  column :created_by_name, label: "Created by"
+  column :updated_by_name, label: "Last modified by"
+  column :updated_at, renderer: :relative_date
+end
+```
+
+### Show Page
+
+```ruby
+show do
+  section "Details" do
+    field :title, renderer: :heading
+  end
+
+  section "Audit Trail", columns: 2 do
+    field :created_by_name, label: "Created by"
+    field :created_at, renderer: :datetime
+    field :updated_by_name, label: "Last modified by"
+    field :updated_at, renderer: :datetime
+  end
+end
+```
+
+### Forms
+
+Userstamp fields should **not** appear in forms — they are set automatically by the platform. Simply omit them from your form sections:
+
+```ruby
+form do
+  section "Document" do
+    field :title
+    field :status, input_type: :select
+  end
+end
+```
+
+## Permissions
+
+When `readable: all` is used in permissions, userstamp columns (and timestamp columns) are automatically included. No additional configuration is needed.
+
+If you use explicit field lists, add the userstamp columns you want to expose:
+
+```yaml
+permissions:
+  model: document
+  roles:
+    viewer:
+      crud: [index, show]
+      fields:
+        readable: [title, status, created_by_name, updated_by_name, created_at, updated_at]
+        writable: []
+    editor:
+      crud: [index, show, create, update]
+      fields:
+        readable: all
+        writable: [title, status]
+```
+
+> **Note:** Userstamp columns should never be writable — the `before_save` callback manages them.
+
+## Validation
+
+The `ConfigurationValidator` checks for:
+
+- **Field conflicts** — error if `created_by_id` (or custom name) is also defined as an explicit field
+- **Name column conflicts** — error if `created_by_name` collides with an explicit field (when `store_name: true`)
+- **Missing timestamps** — warning if userstamps are enabled without `timestamps: true` (not an error, but recommended)
+
+## Complete Example
+
+### Model
+
+```ruby
+define_model :tracked_document do
+  label "Tracked Document"
+  label_plural "Tracked Documents"
+
+  field :title, :string, limit: 200, null: false do
+    validates :presence
+  end
+  field :content, :text
+  field :status, :enum, default: "draft",
+    values: { draft: "Draft", review: "Review", published: "Published", archived: "Archived" }
+
+  scope :published, where: { status: "published" }
+  scope :drafts, where: { status: "draft" }
+
+  userstamps store_name: true
+  timestamps true
+  label_method :title
+end
+```
+
+### Presenter
+
+```ruby
+define_presenter :tracked_document do
+  model :tracked_document
+  label "Documents"
+  slug "documents"
+
+  index do
+    default_sort :updated_at, :desc
+    column :title, link_to: :show, sortable: true
+    column :status, renderer: :badge
+    column :created_by_name, label: "Created by"
+    column :updated_by_name, label: "Modified by"
+    column :updated_at, renderer: :relative_date, sortable: true
+  end
+
+  show do
+    section "Document" do
+      field :title, renderer: :heading
+      field :status, renderer: :badge
+    end
+
+    section "Content" do
+      field :content
+    end
+
+    section "Audit Trail", columns: 2 do
+      field :created_by_name, label: "Created by"
+      field :created_at, renderer: :datetime
+      field :updated_by_name, label: "Last modified by"
+      field :updated_at, renderer: :datetime
+    end
+  end
+
+  form do
+    section "Document" do
+      field :title, autofocus: true
+      field :status, input_type: :select
+    end
+
+    section "Content" do
+      field :content, input_type: :textarea
+    end
+  end
+
+  action :create, type: :built_in, on: :collection
+  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
+end
+```
+
+### Seeds
+
+```ruby
+admin = LcpRuby::User.find_by(email: "admin@example.com")
+LcpRuby::Current.user = admin
+
+DocumentModel = LcpRuby.registry.model_for("tracked_document")
+DocumentModel.create!(title: "First Document", content: "Created by admin.", status: "published")
+
+LcpRuby::Current.user = nil
+```
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `created_by` | string | `"created_by_id"` | Creator FK column name |
+| `updated_by` | string | `"updated_by_id"` | Updater FK column name |
+| `store_name` | boolean | `false` | Add denormalized `_name` snapshot columns |
+
+The `user_class` engine configuration option determines which class the `belongs_to` associations point to. See [Engine Configuration — user_class](../reference/engine-configuration.md#user_class).
+
+Source: `lib/lcp_ruby/model_factory/userstamps_applicator.rb`

data/docs/guides/view-groups.md

@@ -0,0 +1,259 @@
+# View Groups Guide
+
+View groups let you offer multiple views of the same model (e.g., a detailed admin table and a compact summary table) and control the navigation menu. This guide walks through common scenarios.
+
+For the full attribute reference, see the [View Groups Reference](../reference/view-groups.md).
+
+## Adding Multiple Views for a Model
+
+Suppose you have a `deal` model with two presenters: `deal` (all columns, full editing) and `deal_short` (key columns only, read-only). To let users switch between them:
+
+**Step 1.** Create both presenters in `config/lcp_ruby/presenters/`:
+
+```yaml
+# config/lcp_ruby/presenters/deal.yml
+presenter:
+  name: deal
+  model: deal
+  label: "Deals"
+  slug: deals
+  # ... full index/show/form config
+```
+
+```yaml
+# config/lcp_ruby/presenters/deal_short.yml
+presenter:
+  name: deal_short
+  model: deal
+  label: "Deals (Short)"
+  slug: deals-short
+  read_only: true
+  # ... minimal index config
+```
+
+**Step 2.** Create a view group in `config/lcp_ruby/views/`:
+
+```yaml
+# config/lcp_ruby/views/deals.yml
+view_group:
+  model: deal
+  primary: deal
+  navigation:
+    menu: main
+    position: 3
+  views:
+    - page: deal
+      label: "Detailed"
+      icon: maximize
+    - page: deal_short
+      label: "Short"
+      icon: list
+```
+
+The `primary` page determines which entry appears in the navigation menu. Users land on the primary page and can switch to other views using the view switcher tabs.
+
+**Step 3.** The view switcher renders automatically. No template changes needed -- the `_view_switcher` partial appears on index, show, and form pages where the presenters actually differ.
+
+By default, the switcher uses **auto-detection**: it compares the `index_config`, `show_config`, and `form_config` of all presenters in the group. If all presenters have identical configuration for a given page type, the switcher is hidden on that page. For example, if two presenters share the same index layout but differ on show, the switcher only appears on the show page.
+
+You can override auto-detection with an explicit `switcher` key:
+
+```yaml
+# Only show switcher on show pages
+switcher: [show]
+
+# Show switcher on all page types
+switcher: [index, show, form]
+
+# Disable switcher entirely
+switcher: false
+```
+
+See the [View Groups Reference](../reference/view-groups.md#switcher) for all options.
+
+## Navigation Menu Integration
+
+The `navigable_entries` helper returns all view groups sorted by position. Use it in your layout to build the navigation menu:
+
+```erb
+<nav>
+  <% navigable_entries.each do |entry| %>
+    <%= link_to entry[:label],
+          lcp_ruby.resources_path(lcp_slug: entry[:slug]),
+          class: "nav-link #{entry[:slug] == params[:lcp_slug] ? 'active' : ''}" %>
+  <% end %>
+</nav>
+```
+
+Each entry represents one view group (not one page). The label, slug, and icon come from the primary page's presenter.
+
+## Single-View Groups
+
+When a model has only one presenter, you can either:
+
+**Option A: Let auto-creation handle it.** If you do not define a view group, the engine creates one automatically with `position: 99`. The presenter appears in the navigation menu at the end. Auto-creation only works when the model has **exactly one** routable page. If the model has multiple presenters/pages, you must create an explicit view group — otherwise none of them will appear in the menu.
+
+**Option B: Define an explicit view group** to control the position:
+
+```yaml
+# config/lcp_ruby/views/todo_lists.yml
+view_group:
+  model: todo_list
+  primary: todo_list
+  navigation:
+    menu: main
+    position: 1
+  views:
+    - page: todo_list
+      label: "Todo Lists"
+```
+
+Single-view groups do not render a view switcher -- the `has_switcher?` method returns `false` when there is only one view.
+
+## URL Behavior When Switching Views
+
+When a user clicks a view switcher tab:
+
+- On **index pages**, the URL changes to the target presenter's slug. Query parameters (search, filters, pagination) are preserved.
+- On **show pages**, the URL changes to the target presenter's slug with the same record ID (e.g., `/deals/5` to `/deals-short/5`).
+
+Each presenter has its own slug, so each view has a distinct, bookmarkable URL.
+
+## Multiple View Groups for the Same Model
+
+You can define multiple view groups that reference the same model. For example, a CRM might have both a "Deals" group and a "Pipeline" group:
+
+```yaml
+# config/lcp_ruby/views/deals.yml
+view_group:
+  model: deal
+  primary: deal
+  navigation:
+    menu: main
+    position: 3
+  views:
+    - page: deal
+      label: "Detailed"
+    - page: deal_short
+      label: "Short"
+```
+
+```yaml
+# config/lcp_ruby/views/pipeline.yml
+view_group:
+  model: deal
+  primary: deal_pipeline
+  navigation:
+    menu: main
+    position: 4
+  views:
+    - page: deal_pipeline
+      label: "Pipeline"
+```
+
+Both appear as separate entries in the navigation menu. A page can only belong to one view group.
+
+## Breadcrumb Navigation
+
+Breadcrumbs provide hierarchical context: `Home > Companies > Acme Inc > Deals > Big Deal`. They are rendered automatically in the layout and configured per view group.
+
+### Default Breadcrumbs
+
+Without any `breadcrumb` config, every page gets a basic breadcrumb: `Home > {View Label}`. On show pages, the record name is appended. On edit/new pages, the action name is appended.
+
+### Adding a Parent Relation
+
+To show parent context, add a `breadcrumb` key with a `relation` pointing to a `belongs_to` association:
+
+```yaml
+# config/lcp_ruby/views/deals.yml
+view_group:
+  model: deal
+  primary: deal
+  navigation:
+    menu: main
+    position: 3
+  breadcrumb:
+    relation: company
+  views:
+    - page: deal
+      label: "Detailed"
+      icon: maximize
+```
+
+This produces breadcrumbs like:
+- Index: `Home > Deals`
+- Show: `Home > Companies > Acme Inc > Deals > Big Deal`
+- Edit: `Home > Companies > Acme Inc > Deals > Big Deal > Edit`
+
+The engine resolves the parent's view group automatically from the association's target model. If the parent's view group also has a `breadcrumb.relation`, the chain recurses up (limited to 5 levels).
+
+### Nullable FK Handling
+
+If the belongs_to association is optional and the parent record is nil, the parent breadcrumb level is skipped. For example, a deal without a company shows: `Home > Deals > Big Deal`.
+
+### Configuring the Home Link
+
+By default the "Home" crumb links to `"/"`. When the engine is mounted at a sub-path, override it in the initializer:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.breadcrumb_home_path = "/crm"
+end
+```
+
+See [Engine Configuration — `breadcrumb_home_path`](../reference/engine-configuration.md#breadcrumb_home_path) for details.
+
+### Disabling Breadcrumbs
+
+To hide breadcrumbs for a specific view group:
+
+```yaml
+breadcrumb: false
+```
+
+### Self-Referential Trees
+
+When the parent model has a self-referential `breadcrumb.relation` (e.g., department → parent department), the engine follows the full ancestor chain. The list crumb (e.g., "Departments") appears once at the top of the chain, not at every level.
+
+For example, an employee in the DevOps department (child of Engineering):
+
+```
+Home > Departments > Engineering > DevOps > Employees > Eva Green
+```
+
+This works across model boundaries: the employee view group follows its `department` relation into the department's self-referential `parent` chain, producing a clean path without duplicates.
+
+### Polymorphic Associations
+
+For polymorphic belongs_to associations, the engine reads `{relation}_type` on the record to determine the parent model and resolves its view group dynamically.
+
+## DSL Alternative
+
+The same configuration in Ruby DSL:
+
+```ruby
+# config/lcp_ruby/views/deals.rb
+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
+```
+
+To disable breadcrumbs in DSL:
+
+```ruby
+define_view_group :reports do
+  model :report
+  primary :report
+  breadcrumb false
+  view :report
+end
+```