robobyte-front-builder 1.0.25 → 1.0.27

package/docs/ReportViewer.md

@@ -0,0 +1,581 @@
+# `<ReportViewer>` — Standalone Component Reference (Host-App Usage)
+
+> **Scope.** This document is for embedding `<ReportViewer>` as a React component **outside the UI Builder** — inside a regular page, dialog, drawer, or dashboard tile in a host Next.js app that consumes `robobyte-front-builder`.
+>
+> If you're emitting a **builder schema** (`{ "type": "reportViewer", "props": {…} }`), use [`training/35-reportViewer.md`](../training/35-reportViewer.md) instead — that document covers the inspector-resolved expression scope, `actionsConfig` / `viewerActions` Calculation runtime, `reportRefs` registry, and the `THIS_NODE` sentinel, none of which apply here.
+
+In host-app code you write plain React. There is no Calculation runtime, no cross-report ref registry, no inspector. Row actions are plain AG Grid `cellRenderer` functions, viewer actions are plain `onClick` handlers, and you wire data through props and callbacks.
+
+---
+
+## 1. Quick start
+
+```jsx
+import { ReportViewer } from 'robobyte-front-builder'
+
+export default function OrdersPage() {
+  return (
+    <ReportViewer
+      pageId="ORDERS_BY_REGION"
+      height="70vh"
+      title="Orders"
+      caption="All regions"
+    />
+  )
+}
+```
+
+That's the minimum. The component:
+- Calls `Endpoints.ReportBuilder.Post.GetReportDetails` on mount with the supplied `id` / `pageId`.
+- Renders the toolbar, AG Grid Enterprise grid, and side tool panel.
+- Handles pagination, filtering, sorting, grouping, aggregation, templates internally.
+
+---
+
+## 2. Prerequisites
+
+### 2.1 Provider in your `_app.js`
+
+`<ReportViewer>` reads the API base URL, auth token, AG Grid license, **and the Quartz theme** from `<RoboByteFrontBuilderProvider>`. Without it, HTTP calls go to the wrong host and AG Grid throws a license warning. The `agGridTheme` prop (optional) lets you customize colors, header / row height, fonts, border radius, etc. across every grid the package renders.
+
+```jsx
+import { RoboByteFrontBuilderProvider } from 'robobyte-front-builder'
+
+export default function App({ Component, pageProps }) {
+  const auth = useYourAuth()
+  return (
+    <RoboByteFrontBuilderProvider
+      baseURL={process.env.NEXT_PUBLIC_API_BASE_URL}
+      apiURL={process.env.NEXT_PUBLIC_API_URL}
+      user={auth.user}
+      accessToken={auth.accessToken}
+      agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+      // Optional: theme overrides for every <AgGridReact> in the package.
+      // agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
+    >
+      <Component {...pageProps} />
+    </RoboByteFrontBuilderProvider>
+  )
+}
+```
+
+### 2.2 Peer dependencies installed in the host app
+
+```bash
+npm install \
+  react react-dom next \
+  @mui/material @mui/icons-material @mui/lab @mui/system \
+  @mui/x-data-grid @mui/x-date-pickers @mui/x-internals @mui/x-virtualizer \
+  @emotion/react @emotion/styled \
+  ag-grid-community ag-grid-enterprise ag-grid-react \
+  xlsx react-hot-toast
+```
+
+### 2.3 `next.config.js` transpile + bare-alias plugin
+
+See [INTEGRATION.md](../INTEGRATION.md) for the exact `next-transpile-modules` + `NormalModuleReplacementPlugin` setup. `<ReportViewer>` depends on internal bare-aliased imports (`services/*`, `views/*`) that the plugin resolves.
+
+---
+
+## 3. Props reference
+
+Listed alphabetically. Where types overlap with the builder schema, the **value** here is a real JS object / function, **not** an expression string.
+
+### 3.1 Identity & data
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | string \| number | one of | Report id from the backend. |
+| `pageId` | string \| number | one of | Page / sub-report id. **At least one of `id` / `pageId` must be set.** |
+| `sessionId` | string | no | Persists user filter / search state to `localStorage` under this key across navigations. |
+| `globalParams` | object | no | Object keyed by 0-based **index** into the report's `selectionParams`, e.g. `{ 0: year, 1: region }`. Overrides defaults at request time. |
+
+### 3.2 Filter
+
+| Prop | Type | Description |
+|---|---|---|
+| `filter` | object | Merged into the request. **See section 4 for the full shape.** Plain JS object — not an expression string. |
+
+### 3.3 Presentation
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | string | report's name | Bold heading on the left of the toolbar. |
+| `caption` | string | — | Small secondary text under `title`. |
+| `height` | string | `'85vh'` | CSS height (`'500px'`, `'70vh'`, etc.). |
+| `minimized` | boolean | `false` | Removes toolbar + paddings. Useful inside cards / popovers. |
+| `noHeader` | boolean | `false` | Hides the standalone-page chrome (report-name + Studio button). Toolbar (title / search / filter / refresh / viewer actions) stays. |
+| `isSingle` | boolean | `false` | Return only the first row. |
+| `dataAsObject` | boolean | `false` | Returns data keyed by row's unique id rather than an array. |
+
+### 3.4 Refresh & timer
+
+| Prop | Type | Description |
+|---|---|---|
+| `refresh` | any | Toggle / change this value to force a reload. Use a state value (`refreshTick`) and `setRefreshTick(Date.now())` to trigger. |
+| `externalTimer` | number | Auto-refresh interval **in minutes**. `0` or `null` disables. |
+| `isRerender` | boolean | Toggle to fully remount the grid (resets internal state). |
+
+### 3.5 Columns
+
+| Prop | Type | Description |
+|---|---|---|
+| `extraCols` | `colDef[]` | AG Grid `colDef` objects appended to the report's columns. Plain functions are fine — `valueGetter`, `valueSetter`, `cellRenderer`, `cellStyle` etc. |
+| `columnsConfig` | array | Per-field overrides matched by `field`: `[{ field, config: { editable, valueFormatter, ... } }, …]`. |
+
+### 3.6 Actions
+
+| Prop | Type | Description |
+|---|---|---|
+| `actions` | function | AG Grid `cellRenderer` function for the row's Actions cell. Receives `params` (the AG Grid params object). You write whatever JSX you want. |
+| `viewerActions` | `ViewerAction[]` | Page-level buttons rendered after Filter / Refresh. **See section 7.** |
+
+### 3.7 Programmatic hooks
+
+| Prop | Type | Description |
+|---|---|---|
+| `setData` | `(rows) => void` | Callback fired when row data loads / changes. |
+| `setOutGridApi` | `(api) => void` | Callback receiving the AG Grid API instance once `onGridReady` fires. Use it to read selected rows, refresh server-side, export, etc. |
+| `setEventRowSelected` | `(event) => void` | Optional callback fired on every row-selection change. |
+| `updateRef` | `React.MutableRefObject` | Per-instance ref tracking row mutations. Allocate with `useRef([])` if you want to read pending edits. |
+
+> **`reportRefs`, `nodeId`, `THIS_NODE`, builder-context props** — these only matter inside the UI Builder. Don't pass them.
+
+---
+
+## 4. The `filter` object
+
+Plain JS object passed each request. Three slots:
+
+```ts
+{
+  // Filters always applied (the user cannot remove these via the UI).
+  fixedTFilter?: FilterItem[],
+
+  // Local-style filters; appear in the UI and can be removed by the user.
+  LocalTfilter?: FilterItem[],
+
+  // JS code string evaluated server-side at request time. Pushes additional
+  // FilterItems into a customFilter array. See 4.3.
+  customFilterCode?: string,
+}
+```
+
+### 4.1 `FilterItem` shape
+
+```ts
+{
+  path:          string,    // dotted field path, e.g. "Customer.RegionId"
+  friendlyName?: string,    // label for UI display
+  value:         any,       // string | number | boolean | array (for In/NotIn/Between)
+  method:        FilterOp,
+  orGroupName?:  string,    // optional, groups multiple items into an OR-block
+}
+```
+
+### 4.2 Operator values (`method`)
+
+`Equal` · `NotEqual` · `Greater` · `GreaterOrEqual` · `Less` · `LessOrEqual` · `Contains` · `StartsWith` · `EndsWith` · `In` · `NotIn` · `IsNull` · `IsNotNull` · `Between` (value is `[from, to]`).
+
+### 4.3 `customFilterCode` (advanced)
+
+A code string evaluated by `SGrid` at request time. Scope:
+
+| Var | Source |
+|---|---|
+| `authContext` | The host's auth context (`{ user, accessToken, … }`) from `RoboByteFrontBuilderProvider`. |
+| `context` | The host's system context. |
+| `data` | An empty `{}` in standalone mode (this hook is mainly useful inside the builder where `data` is the page's reactive state). |
+| `customFilter` | An `[]` to push items into. |
+
+Most host-app callers don't need `customFilterCode` — just build the filter object in JS from your React state and pass it as `filter`. Use `customFilterCode` only when the same filter rules must follow the report through a deep link / templated session.
+
+### 4.4 Building a filter from React state
+
+```jsx
+const [region, setRegion] = useState(null)
+const [status, setStatus] = useState('Open')
+
+const filter = useMemo(() => ({
+  Tfilter: [
+    { path: 'Status', value: status, method: 'Equal' },
+    ...(region ? [{ path: 'RegionId', value: region, method: 'Equal' }] : []),
+  ],
+}), [region, status])
+
+return <ReportViewer pageId="ORDERS" filter={filter} height="60vh" />
+```
+
+> **Tip.** `useMemo` matters — passing a fresh object literal on every parent render causes the grid to refetch unnecessarily.
+
+---
+
+## 5. Title / caption / toolbar layout
+
+The toolbar is a single row:
+
+```
+[Title / Caption]                      [Search] [Filter] [Refresh] [viewerActions…]
+```
+
+- Pass `title` and `caption` as plain strings.
+- Search collapses to an icon button when empty; expands on focus / when filters are active. Arrow keys navigate the field-selector popover; Enter picks the highlighted field.
+- **Display Settings** (auto-refresh interval, "Load all data", "Export to Excel") live in the side panel under the Templates tool icon — the user toggles them, not you.
+
+---
+
+## 6. Row actions — custom `cellRenderer`
+
+Inside the builder, `actionsConfig` is an array of `{ label, icon, code }`. Outside, you pass a complete `cellRenderer` function via `actions`. The function receives AG Grid's `params`; you write whatever React you want.
+
+```jsx
+function OrderActionsCell({ params, onEdit, onCancel }) {
+  return (
+    <Box sx={{ display: 'flex', gap: 0.5 }}>
+      <IconButton size='small' onClick={() => onEdit(params.data)}>
+        <EditOutlined fontSize='small' />
+      </IconButton>
+      <IconButton size='small' color='error' onClick={() => onCancel(params.data.Id)}>
+        <DeleteOutlined fontSize='small' />
+      </IconButton>
+    </Box>
+  )
+}
+
+export default function OrdersPage() {
+  const handleEdit   = (row) => setEditing(row)
+  const handleCancel = (id)  => cancelOrder(id).then(refresh)
+
+  return (
+    <ReportViewer
+      pageId="ORDERS"
+      actions={(params) => (
+        <OrderActionsCell params={params} onEdit={handleEdit} onCancel={handleCancel} />
+      )}
+    />
+  )
+}
+```
+
+---
+
+## 7. Viewer actions (`viewerActions`)
+
+Page-level buttons rendered in the toolbar after Filter / Refresh. Each item is a plain object with an `onClick` you write yourself. **No code-string Calculation runtime.**
+
+### 7.1 `ViewerAction` shape
+
+```ts
+{
+  key?:      string,                // React key — auto-generated if omitted
+  label:     string,                // button text
+  icon?:     string,                // MUI icon name resolved against @mui/icons-material
+                                    // (e.g. "AddOutlined", "DownloadOutlined")
+  color?:    'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'inherit',
+  variant?:  'text' | 'outlined' | 'contained',   // default 'outlined'
+  disabled?: boolean,
+  onClick:   () => void | Promise<void>,
+}
+```
+
+> `confirmation` is recognized by the builder runtime; in standalone mode just handle the confirm yourself inside `onClick` (e.g. `if (!window.confirm('Sure?')) return`).
+
+### 7.2 Example — "New" + "Export"
+
+```jsx
+import { ReportViewer } from 'robobyte-front-builder'
+import { useState, useCallback } from 'react'
+
+export default function CustomersPage() {
+  const [refreshTick, setRefreshTick] = useState(0)
+  const [createOpen, setCreateOpen]   = useState(false)
+
+  const viewerActions = [
+    {
+      label:   'New Customer',
+      icon:    'AddOutlined',
+      variant: 'contained',
+      color:   'primary',
+      onClick: () => setCreateOpen(true),
+    },
+    {
+      label:   'Refresh Manually',
+      icon:    'RefreshOutlined',
+      onClick: () => setRefreshTick(Date.now()),
+    },
+    {
+      label:   'Export CSV',
+      icon:    'DownloadOutlined',
+      onClick: () => gridApi?.exportDataAsCsv({ fileName: 'customers.csv' }),
+    },
+  ]
+
+  const [gridApi, setGridApi] = useState(null)
+
+  return (
+    <>
+      <ReportViewer
+        pageId="CUSTOMERS"
+        title="Customers"
+        caption="All accounts"
+        refresh={refreshTick}
+        viewerActions={viewerActions}
+        setOutGridApi={setGridApi}
+      />
+      <CreateCustomerDialog open={createOpen} onClose={() => setCreateOpen(false)} />
+    </>
+  )
+}
+```
+
+---
+
+## 8. Refresh patterns
+
+### 8.1 Trigger on a button click
+
+```jsx
+const [tick, setTick] = useState(0)
+
+<ReportViewer pageId="X" refresh={tick} />
+<Button onClick={() => setTick(t => t + 1)}>Reload</Button>
+```
+
+### 8.2 Auto-refresh every minute
+
+```jsx
+<ReportViewer pageId="X" externalTimer={1} />
+```
+
+### 8.3 Refresh after a mutation
+
+```jsx
+async function saveAndRefresh() {
+  await PostService(Endpoints.X.Post.Save, true, payload)
+  setTick(t => t + 1)
+}
+```
+
+> **Don't mix `refresh` and `externalTimer` for the same window** — both fire and you'll see double-fetches. Pick one source of truth.
+
+---
+
+## 9. Reading loaded data
+
+Pass `setData` to get a callback every time the report loads new rows:
+
+```jsx
+const [rows, setRows] = useState([])
+
+<ReportViewer
+  pageId="X"
+  setData={setRows}
+/>
+
+// Below the grid:
+<Typography variant='caption'>{rows.length} rows loaded</Typography>
+```
+
+### 9.1 Combining with `dataAsObject`
+
+`dataAsObject: true` returns rows keyed by their server-side unique id:
+
+```jsx
+const [rowsById, setRowsById] = useState({})
+<ReportViewer pageId="X" dataAsObject setData={setRowsById} />
+
+// rowsById['ord_123']  ← O(1) lookup by id
+```
+
+### 9.2 Single-record reports
+
+`isSingle: true` returns only the first row. Useful for "current user", "summary", etc.
+
+```jsx
+const [me, setMe] = useState(null)
+<ReportViewer pageId="ME" isSingle minimized setData={setMe} />
+```
+
+---
+
+## 10. AG Grid API access
+
+`setOutGridApi` gives you the live API. Common uses:
+
+```jsx
+const [api, setApi] = useState(null)
+
+<ReportViewer pageId="X" setOutGridApi={setApi} />
+
+// Selected rows:
+const selected = api?.getSelectedRows() ?? []
+
+// Refresh server-side without re-mounting:
+api?.refreshServerSide({ purge: true })
+
+// Export visible rows to CSV:
+api?.exportDataAsCsv({ fileName: 'x.csv' })
+
+// Apply a column state programmatically:
+api?.applyColumnState({ state: [{ colId: 'CreatedAt', sort: 'desc' }] })
+```
+
+---
+
+## 11. Templates
+
+The Templates tool panel (side panel) is fully self-contained — the user opens it via the icon at the right edge of the grid, saves their column layout + filters + sort, and switches between templates. Nothing for the host to wire.
+
+---
+
+## 12. Common recipes
+
+### 12.1 Report inside a Dialog
+
+```jsx
+import { Dialog, DialogTitle, DialogContent } from '@mui/material'
+
+<Dialog open={open} onClose={onClose} maxWidth='xl' fullWidth>
+  <DialogTitle>Customer Orders</DialogTitle>
+  <DialogContent sx={{ p: 0 }}>
+    <ReportViewer
+      pageId="CUSTOMER_ORDERS"
+      filter={{ Tfilter: [{ path: 'CustomerId', value: customerId, method: 'Equal' }] }}
+      height='70vh'
+      noHeader
+    />
+  </DialogContent>
+</Dialog>
+```
+
+### 12.2 Two reports, master/detail
+
+```jsx
+const [selectedCustomerId, setSelectedCustomerId] = useState(null)
+
+<Grid container spacing={2}>
+  <Grid item xs={6}>
+    <ReportViewer
+      pageId="CUSTOMERS"
+      title="Customers"
+      actions={(params) => (
+        <IconButton size='small' onClick={() => setSelectedCustomerId(params.data.Id)}>
+          <OpenInNewOutlined fontSize='small' />
+        </IconButton>
+      )}
+    />
+  </Grid>
+  <Grid item xs={6}>
+    <ReportViewer
+      pageId="ORDERS"
+      title='Orders'
+      caption={selectedCustomerId ? `Customer ${selectedCustomerId}` : 'Pick a customer'}
+      filter={selectedCustomerId
+        ? { Tfilter: [{ path: 'CustomerId', value: selectedCustomerId, method: 'Equal' }] }
+        : { Tfilter: [{ path: 'Id', value: -1, method: 'Equal' }] }}  // force empty
+      height='60vh'
+    />
+  </Grid>
+</Grid>
+```
+
+### 12.3 Bound to URL query params (deep-link friendly)
+
+```jsx
+import { useRouter } from 'next/router'
+
+const router = useRouter()
+const region = router.query.region
+
+const filter = useMemo(() => (
+  region
+    ? { Tfilter: [{ path: 'Region', value: region, method: 'Equal' }] }
+    : {}
+), [region])
+
+return (
+  <ReportViewer
+    pageId="SALES"
+    title='Sales'
+    caption={region ? `Region: ${region}` : 'All regions'}
+    filter={filter}
+    sessionId={`sales-${region ?? 'all'}`}   // separate filter state per region
+  />
+)
+```
+
+### 12.4 Custom toolbar action that triggers a refresh
+
+```jsx
+const [tick, setTick] = useState(0)
+const refresh = useCallback(() => setTick(Date.now()), [])
+
+const viewerActions = [
+  {
+    label: 'Sync Now',
+    icon:  'CloudDownloadOutlined',
+    variant: 'contained',
+    onClick: async () => {
+      try {
+        await PostService(Endpoints.Sync.Post.Trigger, true, {})
+        refresh()
+      } catch (e) {
+        console.error(e)
+      }
+    },
+  },
+]
+
+<ReportViewer pageId="LIVE_FEED" refresh={tick} viewerActions={viewerActions} />
+```
+
+### 12.5 Embed with pre-filtered data and no chrome (tile / widget)
+
+```jsx
+<Card sx={{ p: 2 }}>
+  <Typography variant='h6'>Top 5 customers this week</Typography>
+  <ReportViewer
+    pageId="TOP_CUSTOMERS"
+    filter={{ Tfilter: [{ path: 'Range', value: 'week', method: 'Equal' }] }}
+    height='320px'
+    minimized
+    isSingle={false}
+  />
+</Card>
+```
+
+---
+
+## 13. Pitfalls
+
+- **Forgetting `<RoboByteFrontBuilderProvider>`** — `apiURL` / `accessToken` / AG Grid license come from there. Without it the report 404s on the API call and the grid throws a license banner. Wrap once at `_app.js` level.
+- **`filter` object identity** — passing `filter={{ Tfilter: [...] }}` inline rebuilds the object every render and triggers refetches. Memoize with `useMemo`.
+- **Mixing `refresh` with `externalTimer`** — both reload independently. Pick one strategy per report.
+- **`viewerActions` icon string** — the value must match an export from `@mui/icons-material` exactly (e.g. `'AddOutlined'`, not `'add-outlined'`). Unknown icon names render the button without an icon, no error.
+- **`actions` is a function, not an array** — in standalone mode `actions` is an AG Grid `cellRenderer` callback. If you tried passing a JSON array (`actionsConfig` style), nothing renders. Use the function form shown in section 6.
+- **`globalParams` is index-keyed** — keys are 0-based positional indices into the report's `selectionParams`, not names. Wrong index → wrong override.
+- **Setting `nodeId` / `reportRefs`** — these are builder-internal. Don't pass them; they'll either be ignored or interfere with the standalone grid.
+- **Mounting two `<ReportViewer>` with the same `sessionId`** — they share saved filter state, which usually isn't what you want. Suffix with a discriminator (`sessionId={`orders-${tenantId}`}`).
+- **Resetting `data` to refresh** — `<ReportViewer>` doesn't take a `data` prop in standalone mode. To force a reload, change `refresh` or `isRerender`. Re-rendering the parent with new props alone won't refetch.
+
+---
+
+## 14. Cheat sheet
+
+1. **Import**: `import { ReportViewer } from 'robobyte-front-builder'`.
+2. **Minimum props**: `pageId` (or `id`) + `height`.
+3. **Filter from React state**: build a plain `{ Tfilter: [...] }` object, memoize, pass via `filter`.
+4. **Refresh on demand**: bump a state value passed as `refresh`. Auto-refresh: `externalTimer={minutes}`.
+5. **Row actions**: pass `actions={(params) => <YourCell params={params} />}`.
+6. **Page-level buttons**: `viewerActions={[{ label, icon, variant, onClick }, …]}`.
+7. **Read loaded rows**: pass `setData`. Read the AG Grid API: pass `setOutGridApi`.
+8. **Wrap your app once in `<RoboByteFrontBuilderProvider>`** at `_app.js` level — that's where the API URL, token, and AG Grid license come from.
+
+---
+
+## Cross-references
+
+- **Schema-level / AI-builder usage** of the same component: [`training/35-reportViewer.md`](../training/35-reportViewer.md).
+- **Package installation, peer deps, `next.config.js`**: [`INTEGRATION.md`](../INTEGRATION.md).
+- **All `RoboByteFrontBuilderProvider` props**: [`README.md`](../README.md).
+- **AG Grid theme customization** (the `agGridTheme` prop and `useAgGridTheme()` hook): README → *AG Grid theme*.