lcp 0.1.0

data/docs/guides/dashboards.md

@@ -0,0 +1,504 @@
+# Dashboards Guide
+
+Dashboards in LCP Ruby are **standalone pages** with `layout: grid` and widget zones. They reuse the full Pages infrastructure — no separate abstraction is needed.
+
+For record-bound multi-zone pages with tabs and related data (e.g., employee detail with leave requests and trainings), see the [Composite Pages Guide](composite-pages.md) instead.
+
+## Quick Start
+
+### 1. Define a Dashboard Page
+
+Create a page YAML in `config/lcp_ruby/pages/`:
+
+```yaml
+# config/lcp_ruby/pages/main_dashboard.yml
+page:
+  name: main_dashboard
+  slug: dashboard
+  layout: grid
+  title_key: lcp_ruby.dashboard.title
+  zones:
+    - name: total_orders
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: count
+        icon: shopping-cart
+        link_to: orders
+      position: { row: 1, col: 1, width: 4, height: 1 }
+
+    - name: revenue
+      type: widget
+      widget:
+        type: kpi_card
+        model: order
+        aggregate: sum
+        aggregate_field: total_amount
+        format: currency
+        icon: dollar-sign
+      position: { row: 1, col: 5, width: 4, height: 1 }
+
+    - name: open_tasks
+      type: widget
+      widget:
+        type: kpi_card
+        model: task
+        aggregate: count
+        icon: check-square
+        link_to: tasks
+      scope: open
+      position: { row: 1, col: 9, width: 4, height: 1 }
+
+    - name: welcome
+      type: widget
+      widget:
+        type: text
+        content_key: lcp_ruby.dashboard.welcome
+      position: { row: 2, col: 1, width: 12, height: 1 }
+
+    - name: recent_tasks
+      presenter: tasks
+      scope: recent
+      limit: 5
+      position: { row: 3, col: 1, width: 6, height: 2 }
+
+    - name: recent_orders
+      presenter: orders
+      scope: recent
+      limit: 5
+      position: { row: 3, col: 7, width: 6, height: 2 }
+```
+
+### 2. Add a View Group (optional)
+
+If you don't define an explicit view group, one will be auto-created. For custom navigation:
+
+```yaml
+# config/lcp_ruby/views/dashboard.yml
+view_group:
+  name: dashboard
+  primary: main_dashboard
+  navigation:
+    menu: main
+    position: 1
+  views:
+    - page: main_dashboard
+      label: "Dashboard"
+```
+
+### 3. Configure Landing Page (optional)
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  # Simple: everyone lands on the dashboard
+  config.landing_page = "dashboard"
+
+  # Role-based: different dashboards per role
+  config.landing_page = {
+    "admin" => "admin-dashboard",
+    "manager" => "manager-dashboard",
+    "default" => "dashboard"
+  }
+end
+```
+
+## Widget Types
+
+### KPI Card
+
+Displays an aggregate value (count, sum, avg, min, max) from a model.
+
+```yaml
+- name: total_revenue
+  type: widget
+  widget:
+    type: kpi_card
+    model: order           # Required: model to query
+    aggregate: sum         # Required: count, sum, avg, min, max
+    aggregate_field: total_amount  # Required for sum/avg/min/max
+    format: currency       # Optional: currency, percentage, decimal, integer
+    icon: dollar-sign      # Optional: Lucide icon name
+    link_to: orders        # Optional: slug to link "View all"
+    label_key: dashboard.revenue  # Optional: i18n key for label
+  scope: completed         # Optional: named scope to apply
+  position: { row: 1, col: 1, width: 3, height: 1 }
+```
+
+### Text
+
+Displays static i18n content.
+
+```yaml
+- name: welcome
+  type: widget
+  widget:
+    type: text
+    content_key: lcp_ruby.dashboard.welcome  # Required: i18n key
+  position: { row: 2, col: 1, width: 12, height: 1 }
+```
+
+### List
+
+Displays a limited list of records from a model.
+
+```yaml
+- name: recent_tasks
+  type: widget
+  widget:
+    type: list
+    model: task            # Required: model to query
+    link_to: tasks         # Optional: slug to link "View all"
+  scope: recent            # Optional: named scope
+  limit: 5                 # Optional: max records (default: 5)
+  position: { row: 3, col: 1, width: 6, height: 2 }
+```
+
+### Chart
+
+Displays a chart visualization using the Chartkick gem (wraps Chart.js). Supports `line`, `bar` (horizontal), `column` (vertical), `pie`, `donut`, and `area` chart types. Single-series via top-level `group_by` + `aggregate`, or multi-series via an explicit `series:` array.
+
+> **Note:** The `chartkick` gem must be installed in your host application:
+>
+> 1. Add `gem "chartkick"` to your Gemfile and run `bundle install`.
+> 2. Declare the JavaScript assets in your `app/assets/config/manifest.js` (Sprockets):
+>    ```js
+>    //= link Chart.bundle.js
+>    //= link chartkick.js
+>    ```
+> The engine layout automatically includes the `<script>` tags when the gem is detected. Without the gem, chart widgets display a fallback message.
+
+```yaml
+- name: orders_by_month
+  type: widget
+  widget:
+    type: chart
+    chart_type: line         # Required: line, bar, column, pie, donut, area
+    model: order             # Required: model to query
+    group_by: created_at     # Required: field to group by
+    group_period: month      # Optional: day, week, month, quarter, year
+    aggregate: count         # Required: count, sum, avg, min, max
+    label_key: dashboard.orders_chart  # Optional: i18n key for title
+  position: { row: 2, col: 1, width: 8, height: 2 }
+```
+
+Aggregate fields are required for `sum`, `avg`, `min`, and `max`:
+
+```yaml
+- name: revenue_by_month
+  type: widget
+  widget:
+    type: chart
+    chart_type: area
+    model: order
+    group_by: created_at
+    group_period: month
+    aggregate: sum
+    aggregate_field: total_amount  # Required for sum/avg/min/max
+    link_to: orders
+  position: { row: 2, col: 1, width: 8, height: 2 }
+```
+
+Use `pie` or `donut` chart types to group by a categorical field:
+
+```yaml
+- name: deals_by_stage
+  type: widget
+  widget:
+    type: chart
+    chart_type: pie
+    model: deal
+    group_by: stage
+    aggregate: count
+  position: { row: 2, col: 9, width: 4, height: 2 }
+```
+
+#### Multi-series charts
+
+Compare two or more metrics side-by-side with an explicit `series:` array. Each series can override `group_by`, `aggregate`, `aggregate_field`, or `group_period`; chart-level keys act as the inherited default. The chart-level `scope:` (if any) and the series' own `scope:` are applied cumulatively.
+
+```yaml
+- name: hires_vs_departures
+  type: widget
+  widget:
+    type: chart
+    chart_type: column
+    model: employee
+    group_by: hire_date
+    group_period: year
+    aggregate: count
+    legend: bottom
+    min: 0
+    ytitle: "Number of employees"
+    series:
+      - name: Hires
+        color: "#0072B2"
+        scope: hired_in_year
+      - name: Departures
+        color: "#999999"
+        scope: departed_in_year
+        group_by: departure_date    # override inherited group_by
+  position: { row: 3, col: 1, width: 8, height: 2 }
+```
+
+Multi-series is supported for `column`, `bar`, `line`, and `area`. Combining `series:` with `pie`/`donut` is a hard validation error.
+
+Stack series on the Y axis with `stacked: true` (legal for column/bar/line/area):
+
+```yaml
+- name: workforce_composition
+  type: widget
+  widget:
+    type: chart
+    chart_type: column
+    model: employee
+    group_by: role
+    aggregate: count
+    stacked: true
+    legend: bottom
+    series:
+      - name_key: lcp_ruby.dashboard.series.active
+        color: "#0072B2"
+        scope: active_employees
+      - name_key: lcp_ruby.dashboard.series.on_leave
+        color: "#E69F00"
+        scope: on_leave_employees
+```
+
+#### Common chart options
+
+The most useful Chartkick options reach the chart helper declaratively:
+
+| Option | Notes |
+|---|---|
+| `legend:` | `auto` (default, context-aware), `true`, `false`, `top`, `bottom`, `left`, `right`. |
+| `stacked: true` | Stack series on the Y axis (column/bar/line/area only). |
+| `colors: [...]` | Index-keyed series colors (column/bar/line/area) or per-slice colors (pie/donut). Per-series `color:` wins on collision. Defaults to the Okabe-Ito colorblind-safe palette. |
+| `min:`, `max:` | Numeric Y-axis bounds. Not applicable to pie/donut. |
+| `xtitle:` / `xtitle_key:` | X axis title (literal or i18n key). |
+| `ytitle:` / `ytitle_key:` | Y axis title (literal or i18n key). |
+| `prefix:`, `suffix:` | Value prefix/suffix (e.g. `prefix: "€"`, `suffix: "%"`). |
+| `precision:`, `thousands:` | Numeric formatting (e.g. `precision: 0`, `thousands: " "`). |
+| `points: true` / `curve: false` | Line/area dot markers and smoothing toggles. |
+| `sort:` | `asc` (default for date `group_period`), `desc`, `none`, `value_asc`, `value_desc`. For multi-series, `value_*` sorts by per-category sum across series. |
+| `download: true` | Chartkick PNG download button. |
+| `height:` | CSS height (e.g. `"320px"`). |
+| `empty:` / `empty_key:` | Message shown when every series has zero rows (default: `lcp_ruby.charts.no_data`). |
+| `library: { ... }` | Raw Chart.js options passthrough. Deep-merged over platform defaults — escape hatch for anything not exposed above (dual-axis scales, custom plugins, etc.). |
+
+See the [Chart Widget Multi-Series spec](../design/chart_widget_multi_series.md) for the full feature surface, validation rules, payload shapes, and scope composition pipeline.
+
+### KPI Trend Indicators
+
+KPI cards can display a trend indicator showing the percentage change compared to a previous period. Use the `compare_scope` attribute to reference a named scope that defines the comparison dataset:
+
+```yaml
+- name: revenue_this_month
+  type: widget
+  widget:
+    type: kpi_card
+    model: order
+    aggregate: sum
+    aggregate_field: total_amount
+    format: currency
+    icon: dollar-sign
+    link_to: orders
+    compare_scope: previous_month  # Named scope for comparison period
+  scope: this_month
+  position: { row: 1, col: 1, width: 4, height: 1 }
+```
+
+The trend indicator computes the percentage change between the current value (from the zone's `scope`) and the comparison value (from `compare_scope`). If the current value is higher, the indicator shows a positive trend (up arrow); if lower, a negative trend (down arrow).
+
+Define the scopes on the model:
+
+```yaml
+# config/lcp_ruby/models/order.yml
+model:
+  name: order
+  scopes:
+    - name: this_month
+      where: { created_at: { gte: beginning_of_month } }
+    - name: previous_month
+      where: { created_at: { gte: beginning_of_previous_month, lt: beginning_of_month } }
+```
+
+### Presenter Zone
+
+Displays a compact table from an existing presenter (reuses column definitions, actions, and field rendering).
+
+```yaml
+- name: recent_orders
+  presenter: orders        # Required: presenter name
+  scope: recent            # Optional: named scope
+  default_scope: active    # Optional: named scope applied before `scope` (both cumulative)
+  limit: 10                # Optional: max records (default: 10)
+  position: { row: 3, col: 7, width: 6, height: 2 }
+```
+
+## Grid Layout
+
+The grid uses a 12-column CSS Grid layout. Each zone specifies its position:
+
+```yaml
+position:
+  row: 1      # Grid row (1-based)
+  col: 1      # Grid column (1-based, out of 12)
+  width: 4    # Column span (default: 1)
+  height: 1   # Row span (default: 1)
+```
+
+On screens narrower than 768px, zones stack into a single column.
+
+## Conditional Zones
+
+Use `visible_when` to show/hide zones based on conditions.
+
+### Role Shortcut
+
+The simplest form — show a zone only to specific roles:
+
+```yaml
+- name: admin_stats
+  type: widget
+  widget:
+    type: kpi_card
+    model: user
+    aggregate: count
+  visible_when:
+    role: admin
+  position: { row: 1, col: 1, width: 4, height: 1 }
+
+# Multiple roles:
+- name: management_kpi
+  type: widget
+  widget:
+    type: kpi_card
+    model: order
+    aggregate: sum
+    aggregate_field: total_amount
+  visible_when:
+    role: [admin, manager]
+  position: { row: 1, col: 5, width: 4, height: 1 }
+```
+
+### Condition Object
+
+Full condition expressions for dynamic visibility:
+
+```yaml
+- name: status_alert
+  type: widget
+  widget:
+    type: kpi_card
+    model: task
+    aggregate: count
+  visible_when:
+    field: role
+    operator: eq
+    value: admin
+  position: { row: 1, col: 1, width: 4, height: 1 }
+```
+
+## Dedicated Dashboard Presenter
+
+For presenter zones on dashboards, you can create a dedicated presenter with a compact column set:
+
+```yaml
+# config/lcp_ruby/presenters/dashboard_tasks.yml
+presenter:
+  name: dashboard_tasks
+  model: task
+  embeddable: true
+  read_only: true
+  index:
+    table_columns:
+      - { field: title }
+      - { field: status }
+      - { field: due_date }
+    default_sort: { field: due_date, direction: asc }
+  actions:
+    collection: []
+    single:
+      - { name: show, type: built_in }
+```
+
+Reference it in the dashboard page:
+
+```yaml
+- name: upcoming_tasks
+  presenter: dashboard_tasks
+  scope: upcoming
+  limit: 5
+  position: { row: 3, col: 1, width: 6, height: 2 }
+```
+
+## Page Filters
+
+Dashboard pages support the same `filter_form:` and `scope_filters:` blocks as index and composite pages. The filter values flow into every widget on the page through `Widgets::ScopeApplicator`, so a single filter bar on top of the dashboard restricts every KPI / chart / list to the chosen subset.
+
+```yaml
+# config/lcp_ruby/pages/sales_dashboard.yml
+page:
+  name: sales_dashboard
+  slug: sales-dashboard
+  layout: grid
+  filter_form:
+    - field: region_id
+      input_type: association_select
+      model: region
+    - field: closed_at
+      input_type: date_range
+  scope_filters:
+    - name: lifecycle
+      widget: button_group
+      default: active
+      scopes:
+        active: { label_key: lcp_ruby.deals.scope.active }
+        archived: { label_key: lcp_ruby.deals.scope.archived }
+  zones:
+    - name: total_revenue
+      type: widget
+      widget: { type: kpi_card, model: deal, aggregate: sum, aggregate_field: amount }
+      position: { row: 1, col: 1, width: 4, height: 1 }
+    # ... more widgets, all auto-filtered by region_id / closed_at / lifecycle
+```
+
+Reference: [page_filters.md](../reference/page_filters.md) for the full block schema, derivation rules, and per-input-type semantics. The dashboard controller path wires `Pages::FilterForm` and `Pages::ScopeFilterSet` exactly like index pages — no dashboard-specific configuration needed.
+
+## Permissions
+
+- Widget zones that reference a model check `can?(:index)` for that model
+- If the user has no access to a widget's model, the widget is hidden (not an error)
+- Presenter zones also check `can_access_presenter?` for the referenced presenter
+- Standalone dashboard pages skip presenter-level authorization (no primary presenter)
+
+## Dashboards vs. Index Composites
+
+If you need a full index table (search, filters, pagination, CRUD actions) alongside KPI widgets, use an **index composite page** instead of a dashboard. Index composites use `semantic` layout with a model-bound main zone that renders an index table, plus sidebar/below widget zones.
+
+```yaml
+# Index composite — model-bound, full index + sidebar widgets
+page:
+  name: orders_overview
+  model: order
+  slug: orders
+  zones:
+    - name: orders_table
+      presenter: orders_index
+      area: main
+    - name: total_orders
+      type: widget
+      area: sidebar
+      widget: { type: kpi_card, model: order, aggregate: count }
+```
+
+| | Dashboard | Index Composite |
+|---|---|---|
+| **Layout** | `grid` (explicit positions) | `semantic` (main + sidebar/below) |
+| **Model** | Standalone — no model | Model-bound — permissions, CRUD actions |
+| **Main area** | Widgets only | Full index table with search/filters/pagination |
+| **URL** | `/dashboard` | `/orders` (model slug) |
+
+See the [Composite Pages Guide — Index-Level Composite Pages](composite-pages.md#index-level-composite-pages) for details.

data/docs/guides/debugging/README.md

@@ -0,0 +1,38 @@
+# Debugging Guide
+
+Practical recipes for inspecting LCP Ruby internals at runtime. Every snippet runs via `bundle exec rails runner '<code>'` from the host app directory.
+
+## Index
+
+- [Models](models.md) — columns, validations, scopes, associations, inheritance, schema
+- [Controllers](controllers.md) — routing, callbacks, concerns, auth chain, Warden
+- [Permissions](permissions.md) — role checks, field access, record rules, condition evaluation
+- [Presenters](presenters.md) — columns, layout, actions, search config, view groups
+- [Metadata](metadata.md) — loader, registry, boot validation, configuration
+- [Data](data.md) — DB state, duplicates, seeds, custom fields, workflow state
+
+## General tips
+
+### `rails runner` vs `rails console`
+
+Both work. `rails runner` is better for scripted checks (paste a block, get output). `rails console` is better for interactive exploration.
+
+```bash
+# One-liner
+bundle exec rails runner 'puts LcpRuby.registry.registered_names.size'
+
+# Multi-line script
+bundle exec rails runner 'script.rb'
+```
+
+### Key entry points
+
+| Object | Access | What it holds |
+|--------|--------|---------------|
+| `LcpRuby.registry` | `LcpRuby.registry.model_for("article")` | AR class for each model |
+| `LcpRuby.loader` | `LcpRuby.loader.model_definitions` | Parsed YAML metadata (hash of definition objects) |
+| `LcpRuby.configuration` | `LcpRuby.configuration.authentication` | Engine config from initializer |
+
+### Require `ostruct` for fake users
+
+Ruby 3.4+ removed `ostruct` from default requires. Always add `require "ostruct"` when creating fake user objects for permission checks.

data/docs/guides/debugging/controllers.md

@@ -0,0 +1,147 @@
+# Debugging: Controllers & Routing
+
+## Where does a URL route to?
+
+```ruby
+puts Rails.application.routes.recognize_path("/showcase/features").inspect
+# => {:controller=>"lcp_ruby/resources", :action=>"index", :lcp_slug=>"features"}
+
+puts Rails.application.routes.recognize_path("/showcase/articles/1").inspect
+# => {:controller=>"lcp_ruby/resources", :action=>"show", :lcp_slug=>"articles", :id=>"1"}
+
+# Custom controller route
+puts Rails.application.routes.recognize_path("/showcase/host-inventory/new").inspect
+# => {:controller=>"host_inventory_items_wizard", :action=>"new", ...}
+```
+
+## What before_action callbacks does a controller have?
+
+```ruby
+LcpRuby::ResourcesController._process_action_callbacks.each do |c|
+  puts "#{c.kind} #{c.filter}" if c.kind == :before
+end
+# => before verify_authenticity_token
+# => before authenticate_user!
+# => before set_presenter_and_model
+# => before authorize_presenter_access
+```
+
+For a host controller:
+
+```ruby
+HostInventoryItemsWizardController._process_action_callbacks.each do |c|
+  puts "#{c.kind} #{c.filter}" if c.kind == :before
+end
+```
+
+## What concerns are included?
+
+```ruby
+puts HostInventoryItemsWizardController.ancestors.first(10).map(&:name).compact
+# Shows the include chain: Controller, Concerns, ApplicationController, ...
+```
+
+## Does a controller inherit from LCP or host?
+
+```ruby
+c = DocsController
+puts c.superclass.name
+# => "ApplicationController" (host) or "LcpRuby::ApplicationController" (engine)
+```
+
+## Authentication chain: who blocks unauthenticated requests?
+
+Common misconception: Warden middleware blocks requests. It doesn't — it only populates `request.env["warden"]`. The blocking happens in the controller callback.
+
+```ruby
+# Check if authenticate_user! is a before_action
+LcpRuby::ResourcesController._process_action_callbacks.each do |c|
+  puts "FOUND: #{c.filter}" if c.filter == :authenticate_user!
+end
+
+# Check Warden is in middleware (it always is with Devise)
+Rails.application.config.middleware.each do |m|
+  puts m.inspect if m.inspect.include?("Warden")
+end
+# => Warden::Manager — present but passive
+
+# Check auth mode
+puts LcpRuby.configuration.authentication  # => :built_in, :external, or :none
+```
+
+## What layout does a controller use?
+
+```ruby
+# Check computed layout
+puts LcpRuby::ResourcesController._layout
+puts DocsController._layout
+```
+
+## Route listing for a presenter slug
+
+```ruby
+# All routes matching a slug
+Rails.application.routes.routes.each do |r|
+  path = r.path.spec.to_s
+  puts "#{r.verb.ljust(8)} #{path} → #{r.defaults[:controller]}##{r.defaults[:action]}" if path.include?("features")
+end
+```
+
+## Custom controller routing: which presenters use host controllers?
+
+```ruby
+LcpRuby.loader.presenter_definitions.each do |name, pd|
+  if pd.custom_controller?
+    puts "#{name} (slug: #{pd.slug}) → controller: #{pd.controller_name}"
+  end
+  if pd.action_controllers?
+    puts "#{name} (slug: #{pd.slug}) → action_controllers: #{pd.action_controllers}"
+  end
+end
+```
+
+## Testing a route from the console
+
+```ruby
+app = ActionDispatch::Integration::Session.new(Rails.application)
+app.host! "localhost"  # REQUIRED — see HostAuthorization below
+
+# Public route (no auth needed)
+app.get "/docs/README"
+puts app.response.status  # => 200
+
+# Auth-protected route (will redirect to login)
+app.get "/showcase/features"
+puts app.response.status  # => 302 (redirect to login)
+```
+
+## Mysterious 403 from `ActionDispatch::HostAuthorization`
+
+If you get a **403 Forbidden** with an **empty body** from `rails runner` or integration tests, it's likely NOT authentication — it's the `HostAuthorization` middleware rejecting requests without a valid `Host` header.
+
+This middleware is in the Rails default stack (since Rails 6) and checks that the request's Host header matches `config.hosts`. In test/runner mode, requests often lack a Host header entirely.
+
+**Diagnosis:**
+
+```ruby
+# Check if HostAuthorization is in the stack
+Rails.application.config.middleware.each do |m|
+  puts m.inspect if m.inspect.include?("Host")
+end
+# => ActionDispatch::HostAuthorization
+
+# Check allowed hosts
+puts Rails.application.config.hosts.inspect
+# In development: typically [/.*/] (allow all) or empty (allow all)
+```
+
+**Fix for integration tests:** Always set the host:
+
+```ruby
+app = ActionDispatch::Integration::Session.new(Rails.application)
+app.host! "localhost"  # ← this fixes the 403
+app.get "/any/path"
+puts app.response.status  # => 200 (or auth redirect, not 403)
+```
+
+**Common misdiagnosis:** The 403 + empty body looks identical to what you'd expect from Warden/Devise rejecting an unauthenticated request. The key difference: Warden redirects (302) to the login page or returns 401 JSON — it never returns 403 with empty body. If you see 403 + empty body, check HostAuthorization first.