lcp 0.1.0

data/docs/reference/page_filters.md

@@ -0,0 +1,328 @@
+# Page Filters
+
+Page-level filtering for dashboards and index composite pages. Two
+parallel YAML blocks:
+
+- **`filter_form:`** — value-based filters (text, select, multi-select,
+  date range, association select with cascading dropdowns). Each entry
+  is a form-syntax field that renders through the same `form_helper`
+  pipeline as presenter forms.
+- **`scope_filters:`** — predefined AR-scope toggles (e.g. `active`
+  vs. `archived`). Each entry maps human-readable labels to named
+  scopes on the page's model.
+
+The two blocks coexist on the same page and read disjoint URL keys
+(`?page_filter[...]` vs. `?scope_filter[...]`).
+
+> **Architecture:** filter forms are synthetic, per-request
+> `ActiveModel::API` objects built on the
+> [Virtual Forms](virtual_forms.md) infrastructure. Read the
+> [Virtual Forms reference](virtual_forms.md) first if you want to
+> understand the security model and the dispatcher contract that
+> makes filter forms render through the standard form helpers.
+>
+> **Spec:** [docs/design/page_filters_as_virtual_forms.md](../design/page_filters_as_virtual_forms.md).
+
+## Minimal example
+
+```yaml
+# config/lcp_ruby/pages/employee_overview.yml
+page:
+  name: employee_overview
+  model: employee
+  slug: employees
+  layout: grid
+  index_presenter: employees_index
+
+  filter_form:
+    - field: bu_code
+      input_type: association_select
+      model: business_unit
+      label_key: lcp_ruby.filters.bu_code
+    - field: division_id
+      input_type: association_select
+      model: division
+      input_options:
+        depends_on:
+          field: bu_code
+          foreign_key: bu_code
+    - field: hired_at
+      input_type: date_range
+
+  scope_filters:
+    - name: lifecycle
+      scopes:
+        active: Active
+        archived: Archived
+      default: active
+
+  auto_submit: derive
+
+  zones:
+    - { name: main_table, area: main, presenter: employees_index }
+    - { name: head_count, area: sidebar, type: widget, widget: { type: kpi_card, model: employee, aggregate: count } }
+```
+
+URL after Apply: `/employees?page_filter[bu_code]=10&page_filter[hired_at_from]=2024-01-01&scope_filter[lifecycle]=archived`.
+
+Note `date_range` decomposes into paired `_from` / `_to` URL keys — never a nested Hash. See [§ Date range](#date-range-input_type-date_range) below for the why.
+
+## `filter_form:` field syntax
+
+Each entry is a hash with at minimum `field:` and `input_type:`. The
+shape is identical to a presenter form field — anything that works
+in `presenter.form.sections[].fields[]` works here.
+
+| Key | Required | Description |
+|---|---|---|
+| `field:` | yes | Attribute name in the URL — `?page_filter[<field>]=...` |
+| `input_type:` | yes | One of: `text`, `textarea`, `rich_text_editor`, `number`, `date`, `date_picker`, `datetime`, `boolean`, `checkbox`, `toggle`, `email`, `tel`, `url`, `color`, `select`, `radio`, `enum`, `association_select`, `multi_select`, `date_range`, `slider`, `rating` |
+| `input_options:` | no | Hash of input-specific options (multi, depends_on, values, min/max, …) |
+| `model:` | when `input_type:` is association_select/multi_select | Target model name |
+| `default:` | no | Default value applied when the URL param is absent |
+| `label_key:` | no | i18n key for the field label; falls back to humanized field name |
+| `placeholder:` | no | Placeholder text |
+
+### Cascading associations (`depends_on:`)
+
+```yaml
+- field: division_id
+  input_type: association_select
+  model: division
+  input_options:
+    depends_on:
+      field: bu_code        # parent filter field
+      foreign_key: bu_code  # column on `division` to filter by
+```
+
+When the parent value changes, the `lcp-cascading-selects` Stimulus
+controller fires a request to
+`/select_options?lcp_slug=...&field=division_id&depends_on[bu_code]=10`
+and rebuilds the child options. The fallback chain in
+`/select_options` reaches the filter-form via
+`find_filter_form_field_config`, so dashboards (which have no
+`current_presenter`) still work.
+
+See **[Cascading Selects reference](cascading_selects.md)** for the
+controller contract — form-level data attributes
+(`data-lcp-select-options-path`, `data-lcp-cascade-name-format`,
+`data-lcp-reverse-cascade`), reverse-cascade opt-out, multi-parent
+cascade URL shape, reset strategies, accessibility, race semantics.
+
+### Multi-select (`multi: true`)
+
+Two flavors depending on whether the source is an association or a
+static value list. Pick the right one — picking the wrong one silently
+falls back to a plain `<input type=text>`.
+
+**(a) Multi-select of records from another model (use `multi_select` + `model:`):**
+
+```yaml
+- field: bu_code
+  input_type: multi_select
+  model: business_unit       # source model — REQUIRED for multi_select
+  input_options:
+    multi: true
+```
+
+**(b) Multi-select of static values (use `select` + `multi: true` + `values:`):**
+
+```yaml
+- field: status
+  input_type: select         # NOT multi_select!
+  input_options:
+    multi: true
+    values:
+      active: Active
+      on_leave: On Leave
+      archived: Archived
+```
+
+Why two patterns: `multi_select` requires an `AssociationDefinition`
+under the hood — its renderer fetches options from a target model and
+the multi-chip Tom Select widget is the same shape as a `has_many` /
+HABTM editor on a presenter form. `select` + `multi:` reuses the
+single-value select renderer and just flips Rails' `multiple: true`
+flag, which works for static values.
+
+Both flavors emit bracket-array URL form:
+`?page_filter[bu_code][]=10&page_filter[bu_code][]=20`.
+
+`Type::ArrayOf` defensively coerces incoming values (drops Hash /
+ActionController::Parameters, never `Array(hash)` propagation). See
+[Virtual Forms § Security invariants](virtual_forms.md#security-invariants).
+
+### Date range (`input_type: date_range`)
+
+Renders two `<input type=date>` controls inside a `<fieldset class="lcp-date-range">`,
+named `<field>_from` and `<field>_to`:
+
+```yaml
+- field: hired_at
+  input_type: date_range
+  input_options:
+    min: "2010-01-01"
+    max: "2030-12-31"
+```
+
+URL shape — **two top-level keys**, never nested:
+
+```
+?page_filter[hired_at_from]=2024-01-01&page_filter[hired_at_to]=2024-12-31
+```
+
+Under the hood, the configurator writes ONE `field: hired_at` entry,
+but `VirtualField#attribute_names` decomposes it into TWO synthetic
+AM attributes (`hired_at_from: :date`, `hired_at_to: :date`) on the
+`VirtualForm` class. The URL keys, the value round-trip into the form
+on reload, and `ScopeApplicator.apply_filter_form` all read from those
+paired attributes — there is no intermediate `Hash{from:, to:}` value.
+See [Virtual Forms § Range decomposition](virtual_forms.md#range-decomposition).
+
+`ScopeApplicator.apply_filter_form` reads the two attributes via
+`resolve_filter_value`, composes them into a temporary `{from, to}`
+Hash internally, and dispatches to `apply_date_range_filter`:
+
+- both bounds → `where(field => from..to)`
+- only `_from` → `arel_table[field].gteq(from_date)`
+- only `_to`   → `arel_table[field].lteq(to_date)`
+- neither → no filter (no-op)
+
+Half-open ranges and an "inverted" range (`from > to`) never raise —
+the latter yields an empty query, the former bounds one side only.
+
+## `scope_filters:` syntax
+
+Each entry maps to a named AR scope on the page's model:
+
+| Key | Required | Description |
+|---|---|---|
+| `name:` | yes | URL key — `?scope_filter[<name>]=<scope>` |
+| `scopes:` | yes | Hash of `scope_method => Label` pairs |
+| `default:` | no | Scope key applied when the URL param is absent or invalid |
+| `label_key:` | no | i18n key for the filter label |
+| `widget:` | no | UI widget: `select` (default), `radio`, `button_group` |
+
+```yaml
+scope_filters:
+  - name: lifecycle
+    scopes:
+      active: Active
+      archived: Archived
+    default: active
+    widget: button_group
+```
+
+The model must define each scope:
+
+```ruby
+# host app / generated model
+scope :active,   -> { where(archived_at: nil) }
+scope :archived, -> { where.not(archived_at: nil) }
+```
+
+Attacker-supplied scope values are silently dropped — only declared
+scope keys reach `model_class.public_send(scope_key)`.
+
+## `auto_submit:` derivation
+
+| Value | Behavior |
+|---|---|
+| `true` | Form auto-submits on every change |
+| `false` | Apply button shown; user submits manually |
+| `derive` (default) | `true` iff no `multi:` and no `depends_on:` field on the page; else `false` |
+
+Rationale: cascade AJAX races auto-submit form posts. The validator
+boot-rejects the explicit `auto_submit: true × depends_on:`
+combination.
+
+## Apply button + dirty state
+
+When `auto_submit_effective?` is `false`, the partial renders an
+Apply button. The Stimulus `lcp-filter-dirty` controller adds
+`.is-dirty` to the button and fills a counter
+(`lcp_ruby.filter_form.unapplied_count`) when any field differs from
+the initial snapshot. Reset clears via `<a href="<request.path>">`.
+
+## `/select_options` fallback chain
+
+When a filter form's `association_select` (or `multi_select`) renders,
+the JS cascade controller queries `/select_options?lcp_slug=...&field=...`.
+The controller's fallback chain in `find_form_field_config`:
+
+1. `current_presenter.form.sections[].fields[]` — presenter form fields
+2. `current_presenter.search.parameters[]` — search-toolbar parameters
+3. `current_page.filter_form_definition` (NEW) — filter-form fields
+
+The third article is gated on `current_page` (not `current_presenter`)
+so dashboards reach it cleanly. `filter_options_url_for(field_name)`
+is the helper that emits the URL — it requires only `current_page`
+and a non-empty `filter_form_definition`.
+
+## Reserved `params[:page_filter]` namespace
+
+The `:page_filter` URL key is owned by this feature. Boot validation
+rejects presenters that declare `scope: :page_filter` on the same
+page as a `filter_form:` block (see
+[FilterFormValidator § scope reservation](../../lib/lcp_ruby/pages/filter_form_validator.rb)).
+Pinned by `spec/integration/page_filter_namespace_spec.rb`.
+
+## Validation rules (PR 1 + PR 3.5)
+
+The validator (`Pages::FilterFormValidator`) rejects at boot:
+
+- `parameters:` block (use `filter_form:` / `scope_filters:` instead)
+- Unknown top-level keys with DidYouMean suggestions
+- `multi: true` on range-type inputs (e.g. `date_range`)
+- `depends_on:` on inputs other than `association_select` / `multi_select`
+- Cascade cycles (`a → b → a`)
+- Unknown `depends_on.field` references
+- Missing `depends_on.foreign_key`
+- `auto_submit: true` combined with any `depends_on:` (PR 1)
+- `visible_when × multi:` at page, zone, field, or action level
+  (PR 3.5 gap A)
+- `scope: :page_filter` literal on any presenter on a filter-form page
+  (PR 3.5 gap B, forward-compatible)
+- input_types outside the closed allowlist (e.g. `file_upload`,
+  `tree_select`, `array_input`)
+- `multi:` against API-backed (`api_model: true`) target models
+- Filter-form fields referencing the `custom_data` jsonb column
+
+## Type coercion edge cases — what bad URL params actually filter
+
+URL params are strings; `ActiveModel::Attributes` casts them through
+the per-attribute type (`Integer`, `Date`, …) before they reach
+`ScopeApplicator`. Upstream Rails has long-standing quirks that
+filter UX inherits — they're pinned in
+`spec/lib/lcp_ruby/virtual_fields/virtual_form_spec.rb` so a Rails
+upgrade that changes them trips CI. The ones worth knowing:
+
+| Attribute type | URL value | Coerced value | Filter behavior |
+|---|---|---|---|
+| `:integer` | `"abc"` | `0` (Ruby `"abc".to_i`) | `WHERE col = 0` — **NOT** a no-op. Surprising. |
+| `:decimal` | `"abc"` | `BigDecimal(0)` | Same — `WHERE col = 0`. |
+| `:date` | `"2024-13-99"` | `nil` | No filter applied (good). |
+| `:datetime` | `"not-a-date"` | `nil` | No filter applied (good). |
+| `:boolean` | `"maybe"` | `true` (anything outside FALSE_VALUES) | `WHERE col = true`. |
+| `:boolean` | `"0"`, `"false"`, `"f"` | `false` | `WHERE col = false`. |
+| `:boolean` | `""` | `nil` | No filter applied. |
+| Any scalar | `{ "admin" => "1" }` | `nil` (Hash-injection defense) | No filter applied. Pinned by acceptance test #16. |
+| Any `multi:` | `[ { "admin" => "1" }, "10" ]` | `[ "10" ]` (Hash element dropped) | `WHERE col IN ('10')`. |
+
+If the Integer / Boolean quirks become a real UX issue, a strict
+coercion mode is a future enhancement (open question in the spec).
+
+## Migration from `parameters:`
+
+The legacy `parameters:` page YAML block was retired in PR 5. PR 1
+boot-rejects the key with a precise migration error pointing at
+`filter_form:` / `scope_filters:`. Translation rules:
+
+| Legacy | New |
+|---|---|
+| `type: association_select` | `filter_form:` entry with `input_type: association_select` |
+| `type: enum_select` | `filter_form:` entry with `input_type: select`, `input_options.values: { ... }` |
+| `type: date_range` | `filter_form:` entry with `input_type: date_range` |
+| `type: scope` | `scope_filters:` entry |
+
+`grep -rn '^parameters:' examples/` should return zero hits.