robobyte-front-builder 1.0.25 → 1.0.27

package/training/35-reportViewer.md

@@ -0,0 +1,673 @@
+# Component: `reportViewer` — Complete AI Reference Manual
+
+> **Audience.** This document is written for an AI session that needs to **emit a builder schema** containing a `reportViewer`, or **embed `<ReportViewer />`** as a React component in code generated against `robobyte-front-builder`. Every prop, every code scope, and every gotcha is documented here so the model does not need to grep source.
+
+Renders an AG Grid Enterprise–powered server-side report. The component fetches its column definitions and rows from the backend by `id` / `pageId`, applies server-side pagination, filtering, sorting, grouping, and aggregation, and exposes a toolbar with title, search, filter dialog, refresh, row actions, and user-defined "viewer actions". Use this whenever the data lives on the server.
+
+> ⚠️ **Use `reportViewer` for server-fetched data.** Use `dataGrid` for client-side editable grids. Use `dataTableViewer` for static / already-in-memory arrays.
+
+---
+
+## 1. Quick start
+
+Minimum viable schema — fetch a report by id and render at 70vh height:
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "employeesReport",
+    "id": "EMPLOYEE_LIST",
+    "height": "70vh"
+  }
+}
+```
+
+Note: `id` and/or `pageId` is required — without one the viewer renders the "No report selected" empty state.
+
+---
+
+## 2. Two ways to use it
+
+### As a builder component (most common)
+
+Drop a `reportViewer` node into the schema. The UI Builder resolves props from the inspector, registers a `reportRef` under `props.main.key`, and renders the report inside `ViewerComponentWrapper`.
+
+```json
+{
+  "type": "reportViewer",
+  "props": { "key": "ordersReport", "pageId": "ORDERS_BY_REGION" }
+}
+```
+
+### As a React component (host-app code)
+
+The same page is exported as a React component for inline embedding (Reports inside dialogs, drawers, custom dashboards). Import path:
+
+```jsx
+import { ReportViewer } from 'robobyte-front-builder'
+
+<ReportViewer
+  pageId="ORDERS_BY_REGION"
+  minimized={false}
+  noHeader={true}
+  filter={{ Tfilter: [{ path: 'RegionId', value: 4, method: 'Equal' }] }}
+  height="400px"
+  title="Q1 Orders"
+  caption="2026-01-01 → 2026-03-31"
+/>
+```
+
+When embedded this way, `noHeader={true}` hides the standalone-page chrome (report-name + Studio button).
+
+---
+
+## 3. Complete props reference
+
+All props are inspector fields on the `Main` tab. Types refer to the inspector field type (`expression` means: accepts a literal value OR a JS expression evaluated in the page's calculation scope).
+
+### 3.1 Identity & data source
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `key` | expression | yes | Stable identifier. Used as `nodeName` in `reportRefs`. Pick something kebab/camel-cased and unique on the page. |
+| `id` | expression | one of | Report ID (the backend's top-level report id). |
+| `pageId` | expression | one of | Page/sub-report identifier (for multi-page reports). At least one of `id` / `pageId` must be set. |
+| `sessionId` | expression | no | When set, the viewer hydrates filters / saved state from `localStorage` under this session id. Used to share filter state across navigations. |
+| `globalParams` | expression | no | Object keyed by **selection-param index** → value. Overrides specific `selectionParams` defined in the report. Example: `{ 0: data.year, 1: data.month }`. |
+
+### 3.2 Filter
+
+| Prop | Type | Description |
+|---|---|---|
+| `filter` | expression | External filter object merged with the report's own filters. **See section 4 for the full shape.** |
+
+### 3.3 Presentation (toolbar / chrome)
+
+| Prop | Type | Description |
+|---|---|---|
+| `title` | expression | Bold heading rendered at the **start** of the report toolbar. Falls back to the report's own backend name if unset. |
+| `caption` | expression | Small secondary text rendered under `title` (e.g. row count, time range). |
+| `height` | expression | Grid height. CSS units. Default `"85vh"`. Common: `"70vh"`, `"500px"`, `"60vh"`. |
+| `minimized` | boolean | Removes toolbar + paddings; useful when the viewer is embedded inside a Card or Dialog. |
+| `noHeader` | boolean | Hides the report-name header (the row with name + Studio button). The toolbar with title/search/filter/refresh stays. |
+| `isSingle` | boolean | `true` → return only the first row. Used for "single-record" reports. |
+| `dataAsObject` | boolean | `true` → keyed-by-id object instead of an array (use the row's unique id field as the key). |
+
+### 3.4 Refresh control
+
+| Prop | Type | Description |
+|---|---|---|
+| `refresh` | expression | Change this value to force a data reload. Typical pattern: `data.refreshTick` then `setData(prev => ({...prev, refreshTick: Date.now()}))`. |
+| `externalTimer` | expression | Auto-refresh interval **in minutes**. Set to a numeric value; setting to `0` or `null` disables. |
+| `isRerender` | boolean | When toggled, fully remounts the grid (resets internal state). |
+
+### 3.5 Columns & rows
+
+| Prop | Type | Description |
+|---|---|---|
+| `extraCols` | `extra-cols-editor` | Array of additional AG Grid `colDef` objects appended to the end of the columns. See section 8. |
+| `columnsConfig` | `columns-config-editor` | Per-field overrides on **existing** report columns, matched by `field`. See section 9. |
+
+### 3.6 Action arrays
+
+| Prop | Type | Description |
+|---|---|---|
+| `actionsConfig` | `actions-config-editor` | **Row actions.** Appears as buttons in the row's Actions cell. See section 6. |
+| `viewerActions` | `actions-config-editor` | **Page-level actions.** Appears as buttons in the toolbar after Filter / Refresh. See section 7. |
+
+### 3.7 Programmatic plumbing (set automatically; almost never set by hand)
+
+| Prop | Type | Description |
+|---|---|---|
+| `updateRef` | ref | Per-instance ref tracking row mutations. Set by `ReportViewerRenderer`. |
+| `nodeId` | string | Builder node id. Set by `ReportViewerRenderer`. |
+| `reportRefs` | ref | Shared registry `{ [nodeName]: updateRef }`. Set by `ReportViewerRenderer`. |
+| `setOutGridApi` | function | Callback receiving the AG Grid API instance. Used in custom React embeddings only — builder schemas don't set this. |
+| `setData` | function | Callback receiving loaded rows. Builder schemas don't set this. |
+
+---
+
+## 4. The `filter` object — complete shape
+
+Filter is merged from three sources at runtime: the **report's own** filter (backend-defined), the **user's local** filters (added in the in-grid UI), and **`filter` prop** (external). The final object passed to the API is `Tfilter` (all filters merged into one AND-group).
+
+### 4.1 Fields you can pass via `filter` prop
+
+```ts
+{
+  // Filters that always apply (e.g. an outer "show only my records" constraint
+  // that the user cannot remove via the in-grid filter UI).
+  fixedTFilter?: FilterItem[],
+
+  // Local-style filters that DO appear in the in-grid filter UI; the user can
+  // remove or modify them.
+  LocalTfilter?: FilterItem[],
+
+  // JS code string evaluated to produce additional filter items at request
+  // time. See section 4.3.
+  customFilterCode?: string,
+}
+```
+
+### 4.2 `FilterItem` shape
+
+```ts
+{
+  path:           string,      // dotted path to the field, e.g. "Customer.RegionId"
+  friendlyName:   string,      // label shown in the UI (e.g. "Region")
+  value:          any,         // string | number | boolean | array (for In/NotIn)
+  method:         FilterOp,    // see operators table below
+  dtoClassName?:  string,      // optional class hint for the backend
+  modelClassName?: string,
+  afterSelect?:   any,         // implementation-specific
+  orGroupName?:   string,      // group multiple filters into an OR-block
+}
+```
+
+#### Operators (`method` values)
+
+| `method` | Meaning | Value type |
+|---|---|---|
+| `Equal` | `field == value` | scalar |
+| `NotEqual` | `field != value` | scalar |
+| `Greater` | `field > value` | numeric / date |
+| `GreaterOrEqual` | `field >= value` | numeric / date |
+| `Less` | `field < value` | numeric / date |
+| `LessOrEqual` | `field <= value` | numeric / date |
+| `Contains` | substring match | string |
+| `StartsWith` | prefix | string |
+| `EndsWith` | suffix | string |
+| `In` | `field IN (...values)` | array |
+| `NotIn` | `field NOT IN (...values)` | array |
+| `IsNull` | null check | — |
+| `IsNotNull` | non-null check | — |
+| `Between` | range | `[from, to]` |
+
+### 4.3 `customFilterCode`
+
+A code string evaluated at request time. **Push items into the `customFilter` array.** Available scope:
+
+| Variable | Source |
+|---|---|
+| `authContext` | The host's auth context (`user`, `accessToken`, claims). |
+| `context` | The host's system context. |
+| `data` | The page's reactive state. |
+| `customFilter` | Empty `FilterItem[]` to push into. |
+
+Example — restrict the report to the current user's shop:
+
+```js
+const filter = {
+  customFilterCode: `
+    if (authContext?.user?.shopId) {
+      customFilter.push({
+        field:     'ShopId',
+        value:     authContext.user.shopId,
+        method:    'Equal',
+        operation: 'Equal'
+      })
+    }
+  `
+}
+```
+
+Notes:
+- The code runs **after** static filters are gathered, so it can read other context to compose conditional filters.
+- The code can `return` either an array of `FilterItem`s OR an object `{ Tfilter: [...] }`. Pushing into `customFilter` is the simplest path.
+- A common pattern is to keep the filter shape in `data` and have `customFilterCode` translate it server-side.
+
+---
+
+## 5. Title, caption, toolbar layout
+
+The toolbar is a **single row** since the recent redesign:
+
+```
+[Title / Caption stacked]                       [Search] [Filter] [Refresh] [viewerActions...]
+```
+
+- **Left:** `title` (h6, bold) + `caption` (small secondary). Either may be omitted; if both are set, they stack tightly. Both clip with ellipsis on narrow widths.
+- **Right (right-aligned group, gap-spaced):**
+  - **Search** — collapses to a bordered icon button by default. Click or focus to expand into a TextField with chip startAdornment + search icon endAdornment. Arrow keys / Home / End navigate the field-selector popover; Enter picks the highlighted field; Esc closes the popover.
+  - **PDF export** (icon button) — only when "Load all data" is on.
+  - **Filter** — outlined button. Opens the `CustomFilterDialog`.
+  - **Refresh** — outlined button. Toggles `localRefresh` to trigger a reload.
+  - **viewerActions** — user-defined buttons (section 7).
+
+The **side panel** ("Templates" tool panel, opens from the right edge) holds:
+- Display Settings: **Auto-refresh** select (Off, 30s, 1m, 2m, 5m, 15m, 30m), **Load all data** checkbox, **Export to Excel** button.
+- Templates: save / save as new / edit current grid layout (columns, filters, sort).
+
+---
+
+## 6. Row actions (`actionsConfig`)
+
+An array of action buttons rendered in each row's Actions cell. Each action runs its `code` as an `async function Calculation(form, data, setData, dataRef, reportRefs, openDialog, closeDialog, urlParams, page)`.
+
+### 6.1 Schema
+
+```ts
+[
+  {
+    label:        string,           // button text
+    icon:         string,           // MUI icon name, e.g. "EditOutlined" — empty / unset = no icon
+    color:        'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'inherit',
+    variant:      'text' | 'outlined' | 'contained',
+    code:         string,           // async function body
+    confirmation: string?,          // optional confirmation prompt before running
+    disabled:     string | boolean? // expression that may return truthy to disable
+  }
+]
+```
+
+### 6.2 Scope available inside `code`
+
+| Var | What it is |
+|---|---|
+| `form` | Form values (read-only snapshot). |
+| `data` | Page reactive state. |
+| `setData` | Setter for page state. |
+| `dataRef` | Mutable non-reactive store. |
+| `reportRefs` | Registry of all report `updateRef`s on the page. |
+| `openDialog(key, data?)` / `closeDialog(key)` | Dialog control. |
+| `rowData` | **Row-specific** — the current AG Grid row's data object. |
+| `setRefValue`, `getRefValue`, `setRefRow`, `hasRefValue`, `clearRefRow`, `clearAllRef`, `getNodeRef`, `THIS_NODE` | Node-aware ref helpers. Pass `THIS_NODE` to target the current report; pass another report's nodeName to cross-target. |
+| `page.data`, `page.setData`, `page.dataRef`, `page.reportRefs` | Parent page scope (when this report is inside a Dialog or embedded view). |
+| `GetService`, `PostService`, `UpdateService`, `PatchService`, `DeleteService` | Auth-aware HTTP wrappers. |
+| `showToast(message, type?)` | `'success' | 'error' | 'warning' | 'info' | 'loading'` |
+| `router`, `urlParams`, `globalData`, `setGlobalData` | Navigation + global store. |
+
+### 6.3 Examples
+
+Open an edit dialog seeded with the row:
+
+```json
+{
+  "label": "Edit",
+  "icon": "EditOutlined",
+  "color": "primary",
+  "variant": "text",
+  "code": "openDialog('editEmployee', { id: rowData.Id, name: rowData.Name })"
+}
+```
+
+Delete with confirmation:
+
+```json
+{
+  "label": "Delete",
+  "icon": "DeleteOutlined",
+  "color": "error",
+  "variant": "text",
+  "confirmation": "Delete this employee? This cannot be undone.",
+  "code": "await DeleteService(Endpoints.HR.Delete.Employee, true, {}, { id: rowData.Id }); reportRefs[THIS_NODE]?.current && (await reportRefs[THIS_NODE].current.refresh?.()); showToast('Deleted', 'success')"
+}
+```
+
+---
+
+## 7. Viewer actions (`viewerActions`)
+
+**New.** Page-level buttons rendered in the toolbar after Refresh. Same schema as `actionsConfig`, but `code` runs **without a row context** — `rowData` is not in scope.
+
+Use these for:
+- "New" / "Add" buttons that open a creation dialog.
+- "Export PDF" / "Download" using custom logic.
+- "Reset filters" / "Open in new tab" / etc.
+- Any whole-report-level operation.
+
+### 7.1 Schema (identical to row actions, minus `rowData`)
+
+```json
+"viewerActions": [
+  {
+    "label": "New Customer",
+    "icon": "AddOutlined",
+    "color": "primary",
+    "variant": "contained",
+    "code": "openDialog('newCustomer')"
+  },
+  {
+    "label": "Reset Filters",
+    "icon": "RestoreOutlined",
+    "color": "inherit",
+    "variant": "outlined",
+    "code": "setData(prev => ({ ...prev, customerFilter: {} }))"
+  }
+]
+```
+
+### 7.2 Scope inside viewer-action `code`
+
+Identical to row actions **minus** `rowData`. Specifically: `form`, `data`, `setData`, `dataRef`, `reportRefs`, `openDialog`, `closeDialog`, `pageData`, `pageSetData`, `pageDataRef`, `pageReportRefs`, all `*Service` helpers, `showToast`, `router`, etc.
+
+### 7.3 Render rules
+
+- Buttons are rendered in declared order.
+- Defaults: `variant: 'outlined'`, `color: 'primary'`, no icon.
+- `disabled` accepts a boolean or an expression that resolves to a boolean.
+
+---
+
+## 8. Extra columns (`extraCols`)
+
+An array of complete AG Grid `colDef` objects **appended** to the end of the report's columns.
+
+Common fields:
+
+```ts
+{
+  headerName?:   string,
+  field?:        string,       // server field path (use friendlyName-mapped names for report-defined columns)
+  pinned?:       'left' | 'right',
+  width?:        number,
+  editable?:     boolean | expression,
+  cellRenderer?: string | function,
+  valueGetter?:  function,
+  valueSetter?:  function,
+  cellStyle?:    object | function,
+  comparator?:   function,
+  // …any other AG Grid colDef field
+}
+```
+
+Functions can be written as JS strings and are evaluated in a context that has `reportRefs`, `nodeName`, `data`, `dataRef`, `setData`, `openDialog`, `closeDialog`.
+
+Example — append a computed column:
+
+```json
+"extraCols": [
+  {
+    "headerName": "Full Name",
+    "field": "FullName",
+    "valueGetter": "params.data.FirstName + ' ' + params.data.LastName",
+    "width": 200,
+    "pinned": "left"
+  }
+]
+```
+
+---
+
+## 9. Column overrides (`columnsConfig`)
+
+Per-field overrides matched by `field` name to existing report columns. Doesn't add columns — it modifies them.
+
+```json
+"columnsConfig": [
+  {
+    "field": "Salary",
+    "config": {
+      "editable": true,
+      "cellStyle": { "textAlign": "right" },
+      "valueFormatter": "params.value != null ? params.value.toLocaleString() : ''"
+    }
+  },
+  {
+    "field": "Status",
+    "config": {
+      "cellRenderer": "statusBadgeRenderer"
+    }
+  }
+]
+```
+
+Inside string-typed functions you get the same scope as `extraCols` functions (`reportRefs`, `nodeName`, `data`, etc.).
+
+---
+
+## 10. The `reportRefs` API
+
+Each report on a page registers an `updateRef` under its `key`. From any Calculation, you can interact with another report's data:
+
+```js
+// Inside a row action or viewer action
+const otherRef = reportRefs['ordersReport']?.current
+// otherRef is an array of { rowId, field, oldValue, newValue, rowData, ... } for pending edits
+
+// Common helpers (auto-injected into row-action scope):
+setRefValue('ordersReport', rowId, 'Status', 'Approved')
+getRefValue('ordersReport', rowId, 'Status')
+clearRefRow('ordersReport', rowId)
+clearAllRef('ordersReport')
+getNodeRef('ordersReport')   // raw updateRef
+```
+
+Pass `THIS_NODE` (the sentinel) to target the **current** report from inside its own row action.
+
+---
+
+## 11. Refresh & timers
+
+Three ways to trigger reload:
+
+1. **Bind to a reactive value.** Pass `refresh: data.refreshTick` and toggle it: `setData(p => ({...p, refreshTick: Date.now()}))`.
+2. **Auto-refresh via external timer.** Set `externalTimer` to a number of minutes. The viewer toggles its internal `localRefresh` every interval.
+3. **User clicks the Refresh button** in the toolbar.
+
+---
+
+## 12. Sessions (`sessionId`)
+
+When `sessionId` is set, the viewer:
+- Reads a previously-saved filter payload from `localStorage` (key derived from `sessionId`) on mount.
+- Saves the user's filters / search chips / selected params to that key on change.
+
+Use this to share filter state across navigations (e.g. a dashboard tile and a deep-link page that both display the same report should use the same `sessionId`).
+
+---
+
+## 13. Selection params (`globalParams`)
+
+If the report's backend definition declares `selectionParams` (e.g. "Year", "Region"), pass `globalParams` as an object keyed by **0-based index** to override specific ones at runtime:
+
+```json
+{
+  "id": "SALES_BY_REGION",
+  "globalParams": "{ 0: data.selectedYear, 1: data.selectedRegion }"
+}
+```
+
+`globalParams` keys missing from the object leave the report's defaults intact.
+
+---
+
+## 14. Common recipes
+
+### 14.1 Master / detail with two reports
+
+Click a row in the master report → load detail rows scoped to that id:
+
+```json
+{
+  "type": "layout",
+  "props": { "cols": 2 },
+  "children": [
+    {
+      "type": "layout-cell",
+      "children": [
+        {
+          "type": "reportViewer",
+          "props": {
+            "key": "customers",
+            "id": "CUSTOMER_LIST",
+            "actionsConfig": [
+              {
+                "label": "View Orders",
+                "icon": "OpenInNewOutlined",
+                "code": "setData(prev => ({ ...prev, selectedCustomerId: rowData.Id }))"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "type": "layout-cell",
+      "children": [
+        {
+          "type": "reportViewer",
+          "props": {
+            "key": "customerOrders",
+            "id": "ORDER_LIST",
+            "filter": "data.selectedCustomerId ? { Tfilter: [{ path: 'CustomerId', value: data.selectedCustomerId, method: 'Equal' }] } : { Tfilter: [] }"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 14.2 Toolbar "New" + "Export PDF" via viewer actions
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "invoices",
+    "id": "INVOICE_LIST",
+    "title": "Invoices",
+    "caption": "All open invoices",
+    "viewerActions": [
+      {
+        "label": "New Invoice",
+        "icon": "AddOutlined",
+        "variant": "contained",
+        "code": "openDialog('newInvoice')"
+      },
+      {
+        "label": "Open Print Layout",
+        "icon": "PrintOutlined",
+        "code": "openPrintLayout('invoiceLayout', { filter: data.invoiceFilter })"
+      }
+    ]
+  }
+}
+```
+
+### 14.3 Auto-refresh + bound external filter
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "liveSignups",
+    "id": "USER_SIGNUPS",
+    "externalTimer": 1,
+    "filter": "{ Tfilter: [{ path: 'CreatedAt', value: [data.fromDate, data.toDate], method: 'Between' }] }"
+  }
+}
+```
+
+### 14.4 Tenant-scoped report via `customFilterCode`
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "myShopOrders",
+    "id": "ORDER_LIST",
+    "filter": "{ customFilterCode: \"if (authContext?.user?.shopId) customFilter.push({ path: 'ShopId', value: authContext.user.shopId, method: 'Equal' })\" }"
+  }
+}
+```
+
+### 14.5 Inline edit + save via `columnsConfig` and a viewer action
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "prices",
+    "id": "PRICE_LIST",
+    "columnsConfig": [
+      { "field": "Price", "config": { "editable": true } }
+    ],
+    "viewerActions": [
+      {
+        "label": "Save Changes",
+        "icon": "SaveOutlined",
+        "variant": "contained",
+        "code": "const pending = reportRefs['prices']?.current ?? []; if (pending.length === 0) { showToast('Nothing to save', 'info'); return } await PostService(Endpoints.Pricing.Post.UpdateMany, true, { changes: pending }); showToast('Saved', 'success'); pending.length = 0"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 15. Pitfalls
+
+- **Forgetting `key`** — every report must have a unique `key`. Without it, `reportRefs` collides and cross-report helpers (`setRefValue` etc.) target the wrong table.
+- **Using `dataGrid` for server data** — `dataGrid` is client-side. Performance dies on large datasets and pagination doesn't exist.
+- **Filter passed as object literal in the inspector** — the inspector treats `filter` as an **expression**. Write `{ Tfilter: [...] }`, **not** `{"Tfilter": [...]}` (the latter is a JSON literal; you want a JS object). The same goes for `globalParams`.
+- **`actionsConfig` `code` not awaiting async work** — if you call a `*Service` and don't `await`, the next line runs before the response. Always `await` HTTP calls.
+- **Refresh races** — toggling `refresh` and `externalTimer` simultaneously can cause double-fetches. If you need precise timing, drive everything through `refresh` + `setData`.
+- **Action button labels in RTL pages** — the toolbar is LTR by default but the page may be RTL; labels render fine either way, but icons appear on the visual "start" side of the button (left in LTR, right in RTL).
+- **`globalParams` index, not key** — keys are 0-based positional indices into `selectionParams`, not names. Misindex and you'll silently override the wrong param.
+- **Setting `setOutGridApi` from a builder schema** — it only makes sense in code-level embedding. Builder schemas don't have a place for raw function props.
+
+---
+
+## 16. Full schema examples
+
+### 16.1 Minimal
+
+```json
+{
+  "type": "reportViewer",
+  "props": { "key": "list", "id": "EMPLOYEE_LIST" }
+}
+```
+
+### 16.2 Heavily configured
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "ordersReport",
+    "id": "ORDER_LIST",
+    "pageId": "OPEN_ORDERS",
+    "title": "Open Orders",
+    "caption": "Real-time, refreshes every minute",
+    "height": "70vh",
+    "noHeader": true,
+    "externalTimer": 1,
+    "sessionId": "dashboard.orders",
+    "filter": "{ fixedTFilter: [{ path: 'Status', value: 'Open', method: 'Equal' }], customFilterCode: \"if (authContext?.user?.regionId) customFilter.push({ path: 'RegionId', value: authContext.user.regionId, method: 'Equal' })\" }",
+    "globalParams": "{ 0: data.year }",
+    "columnsConfig": [
+      { "field": "Amount", "config": { "editable": false, "cellStyle": { "textAlign": "right" }, "valueFormatter": "params.value?.toLocaleString()" } }
+    ],
+    "extraCols": [
+      { "headerName": "Margin", "field": "Margin", "valueGetter": "(params.data.Revenue - params.data.Cost) / params.data.Revenue", "valueFormatter": "(params.value * 100).toFixed(1) + '%'" }
+    ],
+    "actionsConfig": [
+      { "label": "View", "icon": "VisibilityOutlined", "color": "primary", "variant": "text", "code": "openDialog('orderDetail', { orderId: rowData.Id })" },
+      { "label": "Approve", "icon": "CheckOutlined", "color": "success", "variant": "text", "code": "await PostService(Endpoints.Orders.Post.Approve, true, { id: rowData.Id }); showToast('Approved', 'success'); setData(p => ({ ...p, refreshTick: Date.now() }))" },
+      { "label": "Cancel", "icon": "CloseOutlined", "color": "error", "variant": "text", "confirmation": "Cancel this order?", "code": "await DeleteService(Endpoints.Orders.Delete.Cancel, true, {}, { id: rowData.Id }); showToast('Cancelled', 'info')" }
+    ],
+    "viewerActions": [
+      { "label": "New Order", "icon": "AddOutlined", "color": "primary", "variant": "contained", "code": "openDialog('newOrder')" },
+      { "label": "Export Report", "icon": "DownloadOutlined", "code": "openPrintLayout('ordersReport', { filter: data.activeFilter })" }
+    ]
+  }
+}
+```
+
+---
+
+## 17. Cheat sheet — minimum mental model
+
+1. **Use `reportViewer` when data lives on the server.** Use a unique `key`. Set `id` and/or `pageId`. That's enough.
+2. **Style the toolbar via `title` + `caption`.** Both are optional. Place row-level buttons in `actionsConfig`, page-level buttons in `viewerActions`.
+3. **Filter via the `filter` prop.** Three slots: `fixedTFilter` (always applied), `LocalTfilter` (user-removable), `customFilterCode` (server-evaluated JS to compose conditional filters from auth/context).
+4. **Modify columns** with `columnsConfig` (per-field overrides) and `extraCols` (appended new columns).
+5. **Cross-report ops** go through `reportRefs[otherReportKey]` or the `setRefValue` / `getRefValue` helpers (with `THIS_NODE` for self-targeting).
+6. **Refresh** by toggling `refresh`, by setting `externalTimer`, or by the user clicking Refresh.
+
+If anything in this manual contradicts what's in [README.md](../README.md), README is the source of truth for the package surface — but for `reportViewer` specifically, this document is authoritative.