robobyte-front-builder 1.0.19 → 1.0.23

package/INTEGRATION.md

@@ -0,0 +1,1586 @@
+# robobyte-front-builder — Integration Guide
+
+This package exposes the **UI Builder**, **Report Builder**, **Navigator Builder**, and a **Navigation Extension API** so any host Next.js application can embed them and extend the sidebar navigation without forking this repo.
+
+---
+
+## 1. Prerequisites
+
+| Requirement | Version |
+|---|---|
+| Node.js | ≥ 18 |
+| React / React DOM | ≥ 18 |
+| Next.js | ≥ 13 |
+| @mui/material | ≥ 5 |
+
+---
+
+## 2. Peer dependencies
+
+Only the libraries that **must be shared as a single instance** are declared as `peerDependencies` — React, MUI, Emotion, and AG Grid. Everything else ships as regular `dependencies` inside the package so the host app doesn't need to install them manually.
+
+### Must be 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
+```
+
+> **Why only these?**  
+> React and MUI use context and module registries that break if two copies exist in the same app (hooks errors, theme not applied, AG Grid license warnings). `xlsx` is required by the Excel Upload component and is resolved from the host app's `node_modules` because the builder source is transpiled in the host's webpack context. Everything else — `dayjs`, `lodash`, `recharts`, etc. — can safely run from the package's own `node_modules` copy with no side effects.
+
+---
+
+## 3. Installation
+
+### Local development (file: link — no publish needed)
+
+```json
+// package.json
+"robobyte-front-builder": "file:../../RoboByteFrontBuilder"
+```
+
+Run `npm install` once to create the `node_modules` copy. After that, sync
+changed files manually — Next.js hot-reload picks up the changes without
+restarting, except when `next.config.js` itself changes.
+
+### Published registry
+
+```bash
+npm install robobyte-front-builder
+```
+
+---
+
+## 4. Publishing to npm
+
+### One-time setup
+
+```bash
+npm login
+```
+
+### Publish / update
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1  (bug fixes)
+npm version minor   # 1.0.0 → 1.1.0  (new features)
+npm version major   # 1.0.0 → 2.0.0  (breaking changes)
+npm publish
+```
+
+### Dry run
+
+```bash
+npm publish --dry-run
+```
+
+---
+
+## 5. `next.config.js` setup
+
+Two things are required: **transpile** the package, and set up the
+**context-aware bare-alias webpack plugin** so that bare imports like
+`services/*`, `views/*`, etc. resolve to the correct source tree (host vs.
+package) based on where the importing file lives.
+
+```js
+const path = require('path')
+const withTM = require('next-transpile-modules')(['robobyte-front-builder'])
+
+const hostSrc    = path.resolve(__dirname, 'src')
+const builderSrc = path.resolve(__dirname, 'node_modules/robobyte-front-builder/src')
+
+module.exports = withTM({
+  webpack(config, { isServer }) {
+    // Force CJS on server to avoid ESM directory-import errors
+    if (isServer) {
+      config.resolve.conditionNames = ['require', 'node', 'default']
+    }
+
+    const { NormalModuleReplacementPlugin } = require('webpack')
+
+    // ── Package-owned services ─────────────────────────────────────────────
+    // These modules are canonical in the package. Every caller — host or
+    // package — always resolves to the same single implementation.
+    // This plugin must be registered BEFORE the general alias plugin.
+    const packageOwnedServices = [
+      'services/reportData/fetchReportData',
+      // add more here as needed
+    ]
+    packageOwnedServices.forEach(mod => {
+      config.plugins.push(
+        new NormalModuleReplacementPlugin(
+          new RegExp(`^${mod.replace(/\//g, '\\/')}(\\.js)?$`),
+          resource => {
+            resource.request = path.join(builderSrc, mod)
+          }
+        )
+      )
+    })
+
+    // ── Context-aware bare alias routing ──────────────────────────────────
+    // services/*, views/*, context/*, src/*, pages/* each route to the
+    // correct source tree depending on where the importing file lives.
+    config.plugins.push(
+      new NormalModuleReplacementPlugin(
+        /^(services|views|context|src|pages)(\/|$)/,
+        resource => {
+          const isBuilder =
+            resource.context.includes('robobyte-front-builder') ||
+            resource.context.includes('RoboByteFrontBuilder')
+          const root = isBuilder ? builderSrc : hostSrc
+          resource.request = resource.request.replace(
+            /^(services|views|context|src|pages)(\/|$)/,
+            (_, prefix, sep) =>
+              prefix === 'src'
+                ? root + sep
+                : path.join(root, prefix) + sep
+          )
+        }
+      )
+    )
+
+    return config
+  },
+})
+```
+
+> **Restart the dev server** whenever `next.config.js` changes — hot-reload
+> does not apply to webpack plugin changes.
+
+---
+
+## 6. Provider setup (`_app.js`)
+
+Wrap the component tree with `RoboByteFrontBuilderProvider`. Bridge your host
+auth context into it so the package can attach auth headers to every API call.
+
+```jsx
+import { RoboByteFrontBuilderProvider } from 'robobyte-front-builder'
+
+function RoboByteBridge({ children }) {
+  const auth = useContext(YourAuthContext) // your own auth context
+  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}
+    >
+      {children}
+    </RoboByteFrontBuilderProvider>
+  )
+}
+
+export default function App({ Component, pageProps }) {
+  const getLayout = Component.getLayout ?? (page => page)
+  return (
+    <YourAuthProvider>
+      <RoboByteBridge>
+        {getLayout(<Component {...pageProps} />)}
+      </RoboByteBridge>
+    </YourAuthProvider>
+  )
+}
+```
+
+### Provider props
+
+| Prop               | Type     | Description |
+|--------------------|----------|-------------|
+| `baseURL`          | string   | Root API server URL, e.g. `https://api.example.com/` |
+| `apiURL`           | string   | `/api` prefix URL, e.g. `https://api.example.com/api/` |
+| `user`             | object   | Current user object from your auth context |
+| `accessToken`      | string   | Bearer token — attached to every robobyte service call |
+| `agGridLicenseKey` | string   | AG Grid Enterprise license key. The provider calls `LicenseManager.setLicenseKey()` and registers `AllEnterpriseModule` + `IntegratedChartsModule.with(AgChartsEnterpriseModule)` internally. |
+| `navExtensions`    | array    | Static nav items to inject into the sidebar (optional) |
+| `endpoints`        | object   | Full-URL overrides per endpoint group + name (optional) |
+
+> **AG Grid note:** Do not call `LicenseManager` or `ModuleRegistry` in the
+> host app — the provider handles it entirely via `agGridLicenseKey`.
+
+---
+
+## 7. Builder pages — `/builders/...` path schema
+
+All builder routes live under the `/builders/` prefix. Create a thin wrapper
+page in your host app for each route that imports from the package and assigns
+the required static properties.
+
+### Required pages
+
+| Route | Package export |
+|-------|----------------|
+| `/builders/ui` | `UIBuilderPage` |
+| `/builders/ui/views` | `ViewsList` |
+| `/builders/report` | `ReportBuilderPage` |
+| `/builders/report/list` | `ReportsList` |
+| `/builders/report/viewer` | `ReportViewer` |
+| `/builders/report/reportsPermissions` | `ReportsCard` |
+| `/builders/navigator` | `NavigatorBuilderPage` |
+| `/viewer/[id]` | `ViewerPage` |
+
+### Page wrapper pattern
+
+Use an explicit import + static property assignment. A bare `export { X as default }`
+does **not** reliably carry `getLayout`, `acl`, `authGuard` across package
+boundaries in Next.js.
+
+```jsx
+// pages/builders/report/viewer/index.jsx
+import { ReportViewer } from 'robobyte-front-builder'
+import BlankLayout from 'src/@core/layouts/BlankLayout'
+import PermissionsSubjects from 'src/configs/Permissions/PermissionsSubjects.json'
+
+ReportViewer.getLayout  = page => <BlankLayout>{page}</BlankLayout>
+ReportViewer.acl        = { action: 'view', subject: PermissionsSubjects.Free }
+ReportViewer.authGuard  = true
+ReportViewer.guestGuard = false
+export default ReportViewer
+```
+
+Apply the same pattern for every builder page, adjusting `acl.subject` and
+`getLayout` as appropriate.
+
+### Viewer page (`/viewer/[id]`)
+
+The viewer bridges your host nav context into `SystemContext` so the package
+can resolve view metadata:
+
+```jsx
+// pages/viewer/[id].jsx
+import { useContext } from 'react'
+import { ViewerPage, SystemContext } from 'robobyte-front-builder'
+import { YourNavContext } from 'src/context/YourNavContext'
+
+function SystemContextBridge({ children }) {
+  const { nav } = useContext(YourNavContext)
+  return (
+    <SystemContext.Provider value={{ nav }}>
+      {children}
+    </SystemContext.Provider>
+  )
+}
+
+export default function ViewerRoute() {
+  return (
+    <SystemContextBridge>
+      <ViewerPage />
+    </SystemContextBridge>
+  )
+}
+
+ViewerRoute.authGuard  = true
+ViewerRoute.guestGuard = false
+```
+
+The viewer reads the view id from `router.query.id` (path segment), so always
+navigate to it as `/viewer/${id}` — not `/viewer?viewId=...`.
+
+### Deprecated routes — 404 stubs
+
+Old paths must return a proper 404, not a redirect. Add a stub at each old path:
+
+```js
+// e.g. pages/reportModule/reportBuilder/reportViewer/index.js
+export const getServerSideProps = () => ({ notFound: true })
+export default function Page() { return null }
+```
+
+Paths to stub out:
+
+- `/uiBuilder`, `/viewBuilder`, `/viewBuilder/views`, `/viewBuilder/viewPage`
+- `/reportModule/reportBuilder`, `/reportModule/reportBuilder/reportViewer`, `/reportModule/reportBuilder/reports`
+- `/reportBuilder`, `/reportBuilder/reports`, `/reportBuilder/reportViewer`, `/reportBuilder/reportsPermissions`
+- `/navigatorBuilder`
+
+---
+
+## 8. `fetchReportDataByPageId`
+
+Fetches report data by `pageId` without any AG Grid dependency. The canonical
+implementation lives in the package at `services/reportData/fetchReportData`.
+
+### Sourcing — always from the package
+
+The `packageOwnedServices` entry in `next.config.js` (§4) routes every import
+of `services/reportData/fetchReportData` — from any file, host or package — to
+the package's copy via `NormalModuleReplacementPlugin`. The host app's local
+copy (if any) should be emptied out and never executed.
+
+### Usage
+
+```js
+import fetchReportDataByPageId from 'services/reportData/fetchReportData'
+
+const result = await fetchReportDataByPageId({
+  pageId,            // string | number — required
+  filter,            // { Tfilter, TFilter, customFilterCode, ... } — optional
+  isDataOnly,        // return raw rows only (default false)
+  dataAsObject,      // key rows by unique id (default false)
+  isPagination,      // server-side pagination (default true)
+  isSingle,          // return first row only (default false)
+  globalParams,      // override selectionParams by index (default null)
+  page,              // page number (default 1)
+  pageSize,          // page size (default 50)
+  authContext,       // passed into customFilterCode sandbox (default null)
+  context,           // passed into customFilterCode sandbox (default null)
+})
+
+if (result.success) {
+  console.log(result.rows)   // array of row objects
+  console.log(result.total)  // total count (when isPagination: true)
+} else {
+  console.error(result.error)
+}
+```
+
+### `customFilterCode`
+
+Pass a JS string in `filter.customFilterCode`. It runs in a sandboxed
+`new Function` with `authContext`, `context`, and `filters` in scope. The
+function must push objects to the `customFilter` array — these are merged with
+the formatted `tFilter` before the API call.
+
+```js
+const filter = {
+  customFilterCode: `
+    if (authContext?.user?.shopId) {
+      customFilter.push({ field: 'ShopId', value: authContext.user.shopId, operation: 'Equal' })
+    }
+  `
+}
+```
+
+---
+
+## 9. Embedding `ReportViewer` as a component
+
+`ReportViewer` can be rendered inline anywhere — not only as a full page:
+
+```jsx
+import { ReportViewer } from 'robobyte-front-builder'
+
+<ReportViewer
+  pageId="your-page-id"
+  minimized={true}
+  noHeader={true}
+  filter={{ Tfilter: [...] }}
+  height="400px"
+/>
+```
+
+### Props
+
+| Prop            | Type     | Description |
+|-----------------|----------|-------------|
+| `id`            | string   | Report ID |
+| `pageId`        | string   | Report page ID (alternative to `id`) |
+| `filter`        | object   | External filter (`Tfilter`, `TFilter`, `customFilterCode`) |
+| `minimized`     | bool     | Removes padding and box shadow |
+| `noHeader`      | bool     | Hides the report title and studio button |
+| `height`        | string   | Grid height (default `85vh`) |
+| `isSingle`      | bool     | Return only the first row |
+| `dataAsObject`  | bool     | Key rows by unique id |
+| `setData`       | function | Callback receiving the loaded rows |
+| `setOutGridApi` | function | Callback receiving the AG Grid API instance |
+| `refresh`       | any      | Change this value to force a data reload |
+| `actions`       | array    | Custom row action buttons |
+| `columnsConfig` | array    | Column overrides |
+| `globalParams`  | array    | Override report selectionParams by index |
+| `sessionId`     | string   | Load filter payload from localStorage by session key |
+| `updateRef`     | ref      | Ref for triggering programmatic updates |
+
+---
+
+## 10. Navigation extension API
+
+### Option A — Static items via the Provider
+
+```jsx
+<RoboByteFrontBuilderProvider
+  navExtensions={[
+    {
+      id: 'host-analytics',
+      title: 'Analytics',
+      icon: 'ChartBar',
+      type: 'static',
+      path: '/analytics',
+      insertAt: 'end',
+    },
+  ]}
+>
+  ...
+</RoboByteFrontBuilderProvider>
+```
+
+### Option B — Dynamic items via `useNavExtension` hook
+
+```jsx
+import { useNavExtension } from 'robobyte-front-builder'
+
+function MyFeaturePlugin() {
+  useNavExtension(
+    [{ id: 'my-feature', title: 'My Feature', icon: 'StarOutline', type: 'static', path: '/my-feature', insertAt: 'start' }],
+    'my-feature-plugin'   // stable plugin ID — prevents duplicates on re-renders
+  )
+  return null
+}
+```
+
+### Nav item shape
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | yes | Stable unique identifier |
+| `title` | string | yes | Display label |
+| `icon` | string | no | mdi-material-ui icon name |
+| `type` | `'static'` \| `'dynamic'` \| `'external'` | yes | Route type |
+| `path` | string | for `static` | Absolute path |
+| `viewId` | number | for `dynamic` | Registered view ID |
+| `externalUrl` | string | for `external` | Full URL, opens in new tab |
+| `insertAt` | `'start'` \| `'end'` \| number \| `{ afterId }` \| `{ beforeId }` | no | Placement rule (default `'end'`) |
+| `children` | NavItem[] | no | Collapsible group |
+| `action` / `subject` | string | no | CASL ACL visibility |
+
+---
+
+## 11. Public API summary
+
+```js
+// Configuration
+configureRoboByte, getBaseURL, getApiURL, getAccessToken, getUser
+
+// Provider
+RoboByteFrontBuilderProvider
+
+// Navigation extension
+NavigationExtensionProvider, useNavigationExtensionContext, useNavExtension
+
+// Page components
+UIBuilderPage, ViewsList
+ReportBuilderPage, ReportsList, ReportViewer, ReportsCard
+NavigatorBuilderPage
+ViewerPage
+
+// Contexts
+AuthContext, SystemContext, SystemProvider
+BuilderProvider, useBuilder
+
+// Global data store (cross-route reactive state)
+useGlobalStore          // React hook — { globalData, setGlobalData }
+getGlobalData           // read snapshot from non-React code
+setGlobalData           // write from non-React code (e.g. Calculation functions)
+subscribeGlobal         // subscribe to changes (returns unsubscribe fn)
+resetGlobalData         // clear store on logout / session reset
+```
+
+---
+
+## 12. Syncing local changes to `node_modules`
+
+When using `file:` path, `node_modules/robobyte-front-builder` is a **copy**,
+not a symlink. After editing source files, sync manually:
+
+```bash
+SRC=RoboByteFrontBuilder/src
+PKG=YourApp/node_modules/robobyte-front-builder/src
+
+cp $SRC/views/genericTable/SGrid.js                                    $PKG/views/genericTable/SGrid.js
+cp $SRC/views/genericTable/TAGGrid.js                                  $PKG/views/genericTable/TAGGrid.js
+cp $SRC/pages/reportModule/reportBuilder/reports/index.js              $PKG/pages/reportModule/reportBuilder/reports/index.js
+cp $SRC/pages/reportModule/reportBuilder/reportViewer/index.js         $PKG/pages/reportModule/reportBuilder/reportViewer/index.js
+cp $SRC/pages/reportModule/reportBuilder/reportsPermissions/index.js   $PKG/pages/reportModule/reportBuilder/reportsPermissions/index.js
+cp $SRC/services/reportData/fetchReportData.js                         $PKG/services/reportData/fetchReportData.js
+cp $SRC/lib/providers/RoboByteFrontBuilderProvider.jsx                 $PKG/lib/providers/RoboByteFrontBuilderProvider.jsx
+cp $SRC/lib/index.js                                                   $PKG/lib/index.js
+```
+
+Hot-reload picks up all file changes automatically. Only `next.config.js`
+changes require a full dev server restart.
+
+---
+
+## 13. Data Grid component
+
+The **Data Grid** component wraps AG Grid Enterprise and is configurable entirely from the builder inspector — no code required for common cases.
+
+### Inspector — Main tab
+
+| Field | Description |
+|-------|-------------|
+| `Key` | Component reference key for `reportRefs` access |
+| `Data Key` | Key under which row data is read from / written to page `data` |
+| `Columns` | Expression returning an AG Grid `colDef[]` array |
+| `Extra Columns` | Visual editor for adding new columns on top of the data-driven ones (see below) |
+| `Columns Config` | Visual editor for overriding properties of existing columns matched by `field` name (see below) |
+| `Row Actions` | Visual editor for per-row action buttons shown in a popover |
+| `Add Button Label` | Label for the add-row button (default `"Add"`) |
+| `New Row Template` | Code returning the default object for a newly added row |
+| `Read Only` | Expression — when truthy, disables all editing, hides add/delete controls |
+| `Show Add Button` | Toggle the add-row button |
+| `Show Delete Col` | Toggle the delete-row column |
+| `Height` | Grid height expression (e.g. `'400px'`, `'60vh'`) |
+| `Row Selection` | `none` / `single` / `multiple` |
+| `Pagination` | Enable client-side pagination |
+| `Page Size` | Rows per page when pagination is on |
+
+### Extra Columns editor
+
+Adds **new columns** that don't exist in the data source. Each column is a full AG Grid `colDef`:
+
+| Field | Description |
+|-------|-------------|
+| Header Name | Column header label |
+| Field | Property name to read/write on the row object |
+| Pinned | `left` / `right` / none |
+| Width | Fixed pixel width |
+| Editable | Whether the cell can be edited |
+| Cell Renderer | Built-in or custom renderer (Chip, Link, Icon, Boolean, Currency, Date, Progress, Avatar, Sparkline…) |
+| Cell Editor | Built-in or custom editor (text, number, checkbox, select, date, MultiSelect…) |
+| Value Getter | JS expression to derive the displayed value |
+| Value Formatter | JS expression to format the display string |
+| Value Setter | JS expression called on commit — must return `true` to accept |
+| Cell Editor Params | JS expression returning params passed to the editor |
+| Cell Style | JS expression returning a CSS object |
+| Tooltip | JS expression returning tooltip text |
+
+### Columns Config editor
+
+**Overrides properties of existing columns** from the `Columns` expression, matched by `field` name. Useful for attaching renderers, editors, or functions to API-driven columns without touching the column definition source.
+
+Same per-column fields as Extra Columns, plus the match is done by `field` so the override is applied only to that column.
+
+### Row Actions editor
+
+Each action button has:
+
+| Field | Description |
+|-------|-------------|
+| Label | Button label |
+| Color | MUI palette color |
+| Variant | `text` / `outlined` / `contained` |
+| Icon | MUI icon name |
+| Code | JS action code — `row` and `rowIndex` are available in scope |
+| Confirmation | Optional confirmation message shown before executing |
+| Disabled | Expression — when truthy the button is hidden for that row |
+
+### Read Only mode
+
+`readOnly` is an **expression** field, so it can be driven by data:
+
+```js
+// always read-only:
+true
+
+// driven by page state:
+data.viewMode === 'preview'
+```
+
+When `readOnly` is truthy: editing is disabled on all cells, the add-row button is hidden, and the delete column is hidden. No full re-render occurs — the grid updates in place via `defaultColDef`.
+
+### `reportRefs` API
+
+```js
+const grid = reportRefs['myGridKey']
+
+grid.getRows()              // current row data array
+grid.setRows(arr)           // replace all rows
+grid.addRow(obj)            // append a row
+grid.updateRow(index, obj)  // update a row by index
+grid.deleteRow(index)       // delete a row by index
+grid.getGridApi()           // raw AG Grid API instance
+```
+
+---
+
+## 14. Dialog component
+
+The **Dialog** component renders a hidden MUI Dialog that is opened and closed programmatically from any action, button, or column function via `openDialog(key)` / `closeDialog(key)`.
+
+### Inspector — Main tab
+
+| Field | Description |
+|-------|-------------|
+| `Key` | The identifier used to open/close this dialog — must be unique on the page |
+| `View ID` | When set, renders a full embedded view inside the dialog body. Leave blank to use dropped child components instead |
+| `Title` | Dialog title bar text (expression) |
+| `Hide Title Bar` | Hides the entire title bar including the close button |
+| `Max Width` | `xs` / `sm` / `md` / `lg` / `xl` |
+| `Full Width` | Stretches the dialog to the max width breakpoint |
+| `Full Screen` | Full-screen mode |
+| `Show Close Button` | Shows the × icon in the title bar |
+| `Close on Backdrop` | Closes the dialog when the user clicks outside it |
+| `Action Buttons` | Buttons rendered in a footer bar — each has its own Calculation code |
+
+### Opening and closing
+
+From any action or Calculation on the page:
+
+```js
+// Open — key matches the dialog's Key field
+openDialog('confirmDelete')
+
+// Open with data — merged into the dialog's isolated data store
+openDialog('editUser', { userId: row.id, name: row.name })
+
+// Close
+closeDialog('confirmDelete')
+```
+
+### Isolated data store
+
+Each dialog gets its own isolated `data` / `setData` scope. When `openDialog(key, data)` is called the optional data object is merged into the dialog's initial state, making it immediately available inside the dialog via the normal `data` variable:
+
+```js
+// Caller (e.g. a row action):
+openDialog('editUser', { userId: row.id })
+
+// Inside the dialog's Calculation or child component:
+data.userId   // the value passed from the caller
+```
+
+The dialog's `data` is separate from the parent page's `data`. To read or write the parent page state from inside a dialog use `pageData` and `pageSetData`:
+
+```js
+// Inside a dialog action:
+pageSetData(prev => ({ ...prev, lastEdited: data.userId }))
+```
+
+### Action buttons
+
+Buttons in the `Action Buttons` editor are rendered in a `DialogActions` footer bar. Each button's Calculation runs in the dialog's isolated child context, so `data`, `setData`, `form`, and `reportRefs` all refer to the dialog's own scope. `closeDialog(key)` is pre-wired and available without extra setup:
+
+```js
+// Example: Save button action inside the dialog
+async function Calculation(form, data, setData, ...) {
+  await saveUser(data.userId, form)
+  closeDialog('editUser')
+}
+```
+
+### `openDialog` / `closeDialog` availability
+
+Both are available in every Calculation scope on the page — button actions, row actions, column functions, field `onChange`, and `onMapped`. They are also passed down into embedded views rendered via `View ID`.
+
+---
+
+## 15. Popover component
+
+The **Popover** component renders a self-contained trigger (button, icon button, or text) that opens a floating panel containing dropped child components. No `openDialog` call needed — the trigger and the panel are a single unit.
+
+### Inspector — Main tab
+
+#### Trigger
+
+| Field | Description |
+|-------|-------------|
+| `Key` | Optional reference key |
+| `Trigger Type` | `button` / `icon-button` / `text` |
+| `Trigger Label` | Label text for button and text triggers |
+| `Trigger Variant` | `text` / `outlined` / `contained` |
+| `Trigger Color` | MUI palette color |
+| `Trigger Size` | `small` / `medium` / `large` |
+| `Trigger Icon` | Icon shown on the trigger (MoreVertOutlined, SettingsOutlined, etc.) |
+| `Trigger Full Width` | Stretches the trigger to full container width |
+
+#### Popover panel
+
+| Field | Description |
+|-------|-------------|
+| `Popover Title` | Optional title shown at the top of the panel |
+| `Placement` | Anchor position — `bottom-start`, `bottom`, `bottom-end`, `top-start`, `top`, `top-end`, `left`, `right` |
+| `Trigger On` | `click` (default) or `hover` |
+| `Controlled Open` | Expression — when provided, overrides the internal open/close state |
+| `Max Width (px)` | Maximum panel width |
+| `Max Height (px)` | Maximum panel height (scrolls if content overflows) |
+| `Content Padding` | Padding inside the panel |
+| `Close On Content Click` | Closes the panel when any child inside is clicked |
+
+### When to use Popover vs Dialog
+
+| | Popover | Dialog |
+|---|---|---|
+| Trigger | Self-contained (button lives inside the component) | External — any action calls `openDialog(key)` |
+| Content | Inline child components dropped in the builder | Child components or an embedded view via `viewId` |
+| Layout | Floating panel anchored to the trigger | Centred modal overlay |
+| Use case | Menus, filters, quick-edit panels, info cards | Confirmations, forms, detail views |
+
+---
+
+## 16. Excel Upload component
+
+The **Excel Upload** component lets users upload `.xlsx`, `.xls`, or `.csv` files, map the file's columns to field names, and access the resulting data in actions or via `reportRefs`.
+
+### Display variants
+
+Set via **Display Style** in the inspector Main tab:
+
+| Variant | Description |
+|---------|-------------|
+| `dropzone` | Large dashed drop zone with drag & drop support (default) |
+| `button` | Compact outlined button — dashed when empty, solid on success |
+| `icon` | Icon-only button with a tooltip showing upload status |
+
+### Inspector — Main tab
+
+| Field | Description |
+|-------|-------------|
+| `Key` | Component reference key for `reportRefs` access |
+| `Data Key` | Key under which mapped rows are stored in `data` |
+| `Display Style` | `dropzone` / `button` / `icon` |
+| `Column Mapping` | Pre-configured column → field name pairs (see below) |
+| `Sheet Index` | Zero-based index of the sheet to read (default `0`) |
+| `Button Label` | Upload button label text (default `"Upload Excel"`) |
+| `Show Preview` | Whether to render a preview table after import |
+| `Max Preview Rows` | How many rows to show in the preview (default `5`) |
+
+### Inspector — Style tab
+
+| Field | Description |
+|-------|-------------|
+| `Color` | MUI palette color applied to the button / icon |
+| `Button Style` | `outlined` / `contained` / `text` |
+| `Size` | `small` / `medium` / `large` |
+| `Border Radius` | Custom border radius expression |
+| `Font Size` / `Font Weight` | Typography overrides |
+| `Width` / `Height` / `Margin` / `Padding` | Layout |
+
+### Column mapping
+
+Mapping can be configured in two ways:
+
+**1. Pre-configured in the inspector (Column Mapping field)**  
+Add rows of `Excel Column → Field Name` pairs. When a file is uploaded, the dialog opens with these values pre-filled. The user can still adjust before confirming.
+
+**2. At runtime via the mapping dialog**  
+If no mapping is configured, the dialog opens after upload showing every Excel column as a row. The field name input is pre-filled with the column header — the user edits or clears each one, then confirms.
+
+Clearing a field name in the dialog skips that column entirely.
+
+### Actions
+
+| Event | `newValue` | Notes |
+|-------|-----------|-------|
+| `onUpload` | `{ fileName, headers, rowCount }` | Fires after parsing, before the mapping dialog opens |
+| `onMapped` | `Array<object>` — the mapped rows | Fires before data is saved. **Return a modified array** to override what gets stored. |
+| `onClear` | `[]` | Fires when the user clears the uploaded data |
+
+#### Transforming data in `onMapped`
+
+```js
+async function Calculation(form, data, setData, ...) {
+  // newValue = mapped rows array, e.g. [{ name: 'John', email: '...' }]
+  // Return a modified array to override what gets stored:
+  return newValue.map(row => ({
+    ...row,
+    importedAt: new Date().toISOString(),
+  }))
+}
+```
+
+If the action returns nothing (or a non-array), the original mapped rows are stored unchanged.
+
+### Accessing data via `reportRefs`
+
+```js
+// Inside any action on the same page:
+const uploader = reportRefs['myUploaderKey']
+
+uploader.rows          // current mapped rows array
+uploader.storageKey    // the data key used in page state
+uploader.setRows(arr)  // replace the stored rows
+uploader.clear()       // clear all stored rows
+```
+
+---
+
+## 17. Dark / Light theme for builder pages
+
+Both the **UI Builder** (`/viewBuilder`) and the **Print Layout Builder** (`/printBuilder`) support dark and light modes. The default is dark.
+
+A toggle button (☀️ / 🌙) is available in each builder's toolbar. Clicking it switches modes and persists the choice in `localStorage` under the key `rbb:builderThemeMode`.
+
+The theme is scoped to the builder pages only — it does not affect the rest of the host application. MUI `ThemeProvider` wraps each builder page independently.
+
+**Theme palette summary (dark mode)**
+
+| Token | Value |
+|---|---|
+| `background.default` | `#141618` |
+| `background.paper` | `#1e2227` |
+| `divider` | `#3a3f45` |
+| `primary.main` | `#9c27b0` (purple) |
+| `secondary.main` | `#f5a623` (amber) |
+
+> The canvas drop zone and paper page zones remain white in both modes because they represent the actual document surface.
+
+---
+
+## 18. Print Layout Builder ⚠️ Preview — needs more testing
+
+> **Status:** Functional but not production-ready. This feature is under active development. Expect edge cases and visual glitches. Do not rely on it for production print workflows yet.
+
+The **Print Layout Builder** (`/printBuilder`) lets you design reusable print layouts with configurable headers, footers, multi-page bodies, watermarks, and page numbering. Layouts are saved server-side and can be loaded from any form view via `openPrintLayout(layoutId, data)` in action code.
+
+### Step 1 — Add the `/printBuilder` host page
+
+`PrintBuilderPage` is exported from the package. Create a single file in the host app:
+
+```js
+// host-app/pages/printBuilder/index.jsx
+export { default } from 'robobyte-front-builder/PrintBuilderPage'
+// or named import:
+// import { PrintBuilderPage } from 'robobyte-front-builder'
+// export default PrintBuilderPage
+```
+
+That is all the routing configuration needed. The page includes its own `BuilderProvider`, sidebar, canvas, inspector, and theme toggle.
+
+### Step 2 — Backend API endpoints
+
+The print builder persists layouts via four REST endpoints. The host API must implement all four under `UiBuilderModule/PrintLayout`:
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| `POST` | `UiBuilderModule/PrintLayout` | Create a new layout. Returns `{ data: { id, title, value } }`. |
+| `PUT` | `UiBuilderModule/PrintLayout` | Update an existing layout (pass `id` in the body). |
+| `GET` | `UiBuilderModule/PrintLayout/GetAll` | List all layouts. Returns `{ data: [{ id, title, value, createdBy, createDate }] }`. |
+| `GET` | `UiBuilderModule/PrintLayout/GetById?id=<id>` | Fetch a layout by ID. Returns `{ data: { id, title, value } }` where `value` is the JSON-stringified schema. |
+| `DELETE` | `UiBuilderModule/PrintLayout?id=<id>` | Delete a layout. |
+
+The `value` field is the schema serialised with `JSON.stringify`. The print builder deserialises it with `JSON.parse` after fetching.
+
+### Step 3 — Trigger print from a view
+
+Inside any action code (button `onClick`, row action, etc.) in a UI Builder view:
+
+```js
+openPrintLayout('your-layout-id', {
+  // data object passed into the print layout — available as data.* inside it
+  invoiceNumber: data.invoiceNumber,
+  customerName:  data.customer.name,
+  lines:         data.lines,
+})
+```
+
+`openPrintLayout` is injected into every action's execution scope automatically by `ProductionViewer`. No import is needed.
+
+### Step 4 — Build the layout
+
+Navigate to `/printBuilder` in the host app. Use the **Components** sidebar to drop components into the header, body pages, or footer zones. Switch zones by clicking the zone label in the canvas. Configure page size, margins, watermark, and page numbers in the **Settings** tab.
+
+Save the layout (toolbar Save button). Copy the returned `id` and use it in `openPrintLayout('id', data)` calls.
+
+### Routes
+
+| Route | Behaviour |
+|-------|-----------|
+| `/printBuilder` | New blank layout |
+| `/printBuilder?id=<layoutId>` | Load existing layout |
+| `/printBuilder/layouts` | Browse, preview, and delete all saved layouts |
+
+### Step 1b — Add the layouts list host page
+
+```js
+// host-app/pages/printBuilder/layouts/index.jsx
+export { default } from 'robobyte-front-builder/PrintLayoutsList'
+// or named import:
+// import { PrintLayoutsList } from 'robobyte-front-builder'
+// export default PrintLayoutsList
+```
+
+The list page shows all saved layouts in a card grid. Each card displays the layout title, page size, orientation, number of body pages, creator, and creation date. Available actions per card: **Preview** (scaled read-only canvas in a dialog), **Edit** (navigates to `/printBuilder?id=...`), **Delete** (confirm dialog, removes from list immediately).
+
+### Layout zones
+
+| Zone | Description |
+|------|-------------|
+| **Header** | Repeats at the top of every printed page. Enabled / disabled and height configurable in Settings. |
+| **Body pages** | One or more pages of content. Pages can be added and deleted. |
+| **Footer** | Repeats at the bottom of every printed page. Supports automatic page number insertion. |
+
+### Settings tab
+
+| Setting | Description |
+|---------|-------------|
+| Page Size | A4 / US Letter / US Legal |
+| Orientation | Portrait / Landscape |
+| Body Margins | Top, right, bottom, left in mm |
+| Header | Enable, height (mm), inner margins (mm) |
+| Footer | Enable, height (mm), inner margins (mm), page numbers, alignment, format |
+| Watermark | Enable, text, font size, angle, opacity, color |
+| Test Data | JSON object injected as print data when using Test Print |
+
+### Page numbering format
+
+Use `{page}` and `{pages}` tokens in the **Format** field:
+
+```
+Page {page} of {pages}    →  Page 1 of 4
+{page} / {pages}          →  1 / 4
+```
+
+### Watermark
+
+The watermark renders as a `position: fixed` element in print CSS so it repeats on every physical page. It is always on top of content and does not interfere with layout flow.
+
+### Triggering print from a view
+
+```js
+// In any action code (button, row action, etc.):
+openPrintLayout('your-layout-id', {
+  // data object — available as `data.*` inside the print layout
+  invoiceNumber: data.invoiceNumber,
+  customerName:  data.customer.name,
+  lines:         data.lines,
+})
+```
+
+### DataTableViewer component
+
+A print-optimised table component that renders a flat array as a plain HTML table — no AG Grid, no API fetch. Ideal for embedding tabular data in a print layout.
+
+**Inspector — Main tab**
+
+| Field | Description |
+|-------|-------------|
+| `Data Key` | Key in the print data object holding the rows array |
+| `Columns` | Column definitions — each has a **Header Label** and a **Data Field** name |
+| `Test Data (JSON)` | Static rows shown when no live data is present (for preview / Test Print) |
+| `Font Size` | Table font size in px (default 12) |
+| `Header Background` | Header row background color (default `#f0f0f0`) |
+| `Striped Rows` | Alternate row shading |
+| `Bordered` | Show cell borders (default on) |
+
+### Known limitations / pending work
+
+- Print portal timing is sensitive: the dialog closes before `window.print()` fires; a 350 ms delay is used. This may fail on slow machines.
+- ReportViewer in print context fetches all data (NoPagination) but column mapping depends on `selectFields` being present in the model — layouts may show empty columns if the report model lacks explicit field selection.
+- Zone switching (clicking header/body/footer to open Inspector) has an edge case where `selectedId` may not update if the schema update and `setSelectedId` race.
+- Page number counter (`counter(page)` / `counter(pages)`) is CSS-only and may not render in all browsers when using the table-based layout strategy.
+- Ctrl+P support (without clicking the Print button) is functional but depends on the print CSS being injected at the right time; test this in your target browser.
+
+---
+
+## 19. Calculation Scope Reference
+
+Every Calculation function — whether in a button action, row action, KPI event, field `onChange`, or expression — receives the same set of variables. This is the full reference.
+
+### Core state
+
+| Variable | Type | Description |
+|---|---|---|
+| `form` | object | Form field values (read-only snapshot) |
+| `data` | object | Reactive page state — reads reflect the most recent `setData` call within the same execution |
+| `setData` | function | Write page state — `setData(prev => ({ ...prev, key: value }))` or `setData({ ... })` |
+| `dataRef` | object | Mutable non-reactive store — reads and writes don't trigger a re-render |
+| `reportRefs` | object | Map of `{ [key]: ref }` for every Data Grid / Excel Upload on the page |
+
+### Dialog / layout
+
+| Variable | Type | Description |
+|---|---|---|
+| `openDialog` | function | `openDialog(key, data?)` — open a dialog, optionally seeding its isolated state |
+| `closeDialog` | function | `closeDialog(key)` — close a dialog |
+| `openPrintLayout` | function | `openPrintLayout(layoutId, data?)` — open the print preview for a layout |
+| `closePrintLayout` | function | Close the active print preview |
+
+### Parent page scope (inside dialogs / embedded views)
+
+| Variable | Type | Description |
+|---|---|---|
+| `page.data` | object | Parent page's reactive state |
+| `page.setData` | function | Write to the parent page's state |
+| `page.dataRef` | object | Parent page's non-reactive store |
+| `page.reportRefs` | object | Parent page's grid refs |
+
+### Navigation & routing
+
+| Variable | Type | Description |
+|---|---|---|
+| `router` | NextRouter | Next.js router — `router.push('/path')`, `router.replace(...)`, `router.back()`, `router.query` |
+| `urlParams` | object | `{ query, pathname, asPath }` — snapshot of the current URL, computed at execution time |
+
+### Global store
+
+| Variable | Type | Description |
+|---|---|---|
+| `globalData` | object | Cross-route global state (read) — persists across client-side navigations |
+| `setGlobalData` | function | Write global state — `setGlobalData(prev => ({ ...prev, key: value }))` — shallow-merges by default |
+
+### Services
+
+| Variable | Type | Description |
+|---|---|---|
+| `GetService` | function | Authenticated GET |
+| `PostService` | function | Authenticated POST |
+| `UpdateService` | function | Authenticated PUT |
+| `PatchService` | function | Authenticated PATCH |
+| `DeleteService` | function | Authenticated DELETE |
+| `fetchReportData` | function | Fetch report data by `pageId` (see §8) |
+
+### Helpers
+
+| Variable | Type | Description |
+|---|---|---|
+| `showToast` | function | `showToast(message, type?)` — `'success' \| 'error' \| 'warning' \| 'info' \| 'loading'` |
+
+### Repeater-only
+
+| Variable | Type | Description |
+|---|---|---|
+| `dataItem` | object | The current repeated item (null outside a Repeater) |
+| `itemIndex` | number | The current iteration index — 0-based (null outside a Repeater) |
+
+### KPI event extras
+
+Click-context variables (e.g. `clickedItem`, `clickedValue`) are available as bare names in KPI event actions. See §20 for the full list per event.
+
+---
+
+## 20. KPI Component Actions
+
+KPI components support user-interaction events. Each event has a dedicated **Action** field in the inspector (Main tab → Actions section). The editor is a slide-up code panel identical to the column function editor, with a helper popover listing all available variables including the click-context extras injected for that specific event.
+
+### Supported components and events
+
+| Component | Event | Trigger |
+|---|---|---|
+| **Metric** | `onClick` | User clicks the metric card |
+| **Rating** | `onChange` | User clicks a star |
+| **Chart** | `onDataClick` | User clicks a data point or bar segment |
+| **HeatmapGrid** | `onCellClick` | User clicks a heatmap cell |
+| **Timeline** | `onItemClick` | User clicks a timeline item |
+| **StepStage** | `onStepClick` | User clicks a step dot or label |
+| **TagList** | `onTagClick` | User clicks a tag chip |
+
+### Click-context variables per event
+
+Each event injects additional bare-name variables into the Calculation scope on top of the standard ones (§19).
+
+**Metric — `onClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedValue` | The metric's current display value |
+
+**Rating — `onChange`**
+
+| Variable | Description |
+|---|---|
+| `newValue` | The rating value the user clicked (1–max) |
+| `clickedValue` | Same as `newValue` |
+
+**Chart — `onDataClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedItem` | The full data row object that was clicked |
+| `clickedValue` | The numeric value of the clicked point |
+| `clickedField` | The field name (data key) of the series |
+| `clickedLabel` | The x-axis label of the clicked point |
+| `clickedIndex` | Index of the point in the data array |
+
+**HeatmapGrid — `onCellClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedItem` | The full data row object |
+| `clickedValue` | The value in the clicked cell |
+| `clickedLabel` | Formatted label of the cell value |
+| `clickedRow` | The row label |
+| `clickedCol` | The column label |
+| `clickedRowIndex` | Row index |
+| `clickedColIndex` | Column index |
+
+**Timeline — `onItemClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedItem` | The full timeline item object |
+| `clickedIndex` | Index of the item in the timeline array |
+| `clickedLabel` | The item's label field value |
+| `clickedStatus` | The item's status field value |
+| `clickedValue` | The item's value field value (if configured) |
+
+**StepStage — `onStepClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedItem` | The full step object |
+| `clickedIndex` | Index of the step |
+| `clickedId` | The step's `id` field value |
+| `clickedLabel` | The step's label field value |
+| `clickedStatus` | The step's status field value |
+
+**TagList — `onTagClick`**
+
+| Variable | Description |
+|---|---|
+| `clickedItem` | The full tag item object |
+| `clickedTag` | The raw tag value |
+| `clickedLabel` | Resolved display label |
+| `clickedValue` | The tag's value field (if configured) |
+| `clickedIndex` | Index of the tag in the array |
+
+### Example — open a dialog with clicked data
+
+```js
+// Chart onDataClick — open a detail dialog seeded with the clicked row
+async function Calculation(form, data, setData, dataRef, reportRefs, openDialog, closeDialog, ...) {
+  openDialog('chartDetail', {
+    selectedItem: clickedItem,
+    selectedValue: clickedValue,
+  })
+}
+```
+
+### Example — navigate using the router
+
+```js
+// Metric onClick — push to a detail page
+async function Calculation(..., urlParams, page) {
+  router.push(`/detail/${data.selectedId}`)
+}
+```
+
+### Example — update global state on step click
+
+```js
+// StepStage onStepClick — store the active step globally so another page can read it
+async function Calculation(...) {
+  setGlobalData(prev => ({ ...prev, activeStep: clickedId, activeStepIndex: clickedIndex }))
+}
+```
+
+---
+
+## 21. Global Data Store
+
+The global store is a module-level reactive singleton that survives client-side navigations. It is the recommended way to pass data between routes without URL params or server round-trips.
+
+### In Calculation functions (action code)
+
+`globalData` and `setGlobalData` are always in scope — no import needed:
+
+```js
+async function Calculation(form, data, setData, ...) {
+  // Read
+  console.log(globalData.selectedUser)
+
+  // Write — shallow-merges with previous state
+  setGlobalData(prev => ({ ...prev, selectedUser: clickedItem }))
+  setGlobalData({ theme: 'dark', locale: 'en' })   // full replace also works
+
+  // Navigate — globalData.selectedUser is still there on the next page
+  router.push('/user-detail')
+}
+```
+
+### In React components
+
+```jsx
+import { useGlobalStore } from 'robobyte-front-builder'
+
+function MyComponent() {
+  const { globalData, setGlobalData } = useGlobalStore()
+
+  return (
+    <div>
+      <p>Selected: {globalData.selectedUser?.name}</p>
+      <button onClick={() => setGlobalData({ selectedUser: null })}>Clear</button>
+    </div>
+  )
+}
+```
+
+Components that call `useGlobalStore()` re-render whenever any part of `globalData` changes — whether the update came from another component, a Calculation function, or any other source.
+
+### Resetting on logout
+
+Call `resetGlobalData()` when the user logs out to prevent stale data leaking between sessions:
+
+```js
+import { resetGlobalData } from 'robobyte-front-builder'
+
+function handleLogout() {
+  resetGlobalData()
+  // ... your auth logout
+}
+```
+
+### API
+
+| Export | Description |
+|---|---|
+| `useGlobalStore()` | React hook — returns `{ globalData, setGlobalData }`. Component re-renders on any change. |
+| `getGlobalData()` | Synchronous read from non-React code (returns current snapshot) |
+| `setGlobalData(updater)` | Write from anywhere — accepts a plain object (shallow-merged) or an updater function |
+| `subscribeGlobal(fn)` | Subscribe to changes — returns an unsubscribe function for `useEffect` cleanup |
+| `resetGlobalData()` | Reset to `{}` and notify all subscribers |
+
+---
+
+## 22. Troubleshooting
+
+**"Module not found: Can't resolve 'xlsx'"**
+→ Install `xlsx` in the host app: `npm install xlsx --legacy-peer-deps`. The Excel Upload component imports it at runtime and webpack resolves it from the host's `node_modules`.
+
+**"Cannot find module 'services/...'"**
+→ Ensure the `NormalModuleReplacementPlugin` is configured in `next.config.js` (§4).
+
+**"Module not found: Can't resolve 'pages/builders/...'"**
+→ Add `pages` to the alias regex in the webpack plugin and ensure the `pages/*`
+path resolves to `builderSrc/pages/*` for package files.
+
+**AG Grid table not showing / license warning**
+→ Pass `agGridLicenseKey` to `RoboByteFrontBuilderProvider`. Do not call
+`LicenseManager` or `ModuleRegistry` in the host app.
+
+**AG Grid error #200 — IntegratedChartsModule not registered**
+→ The provider registers `IntegratedChartsModule.with(AgChartsEnterpriseModule)`
+automatically. Ensure `ag-charts-enterprise` is installed in the package.
+
+**ReportViewer renders at half width**
+→ The outer `Box` in `reportViewer/index.js` must use `display: 'block'`, not
+`display: 'flex'`.
+
+**Old routes return 404 instead of the builder**
+→ Check that host-app pages exist under `/builders/...` and that the old paths
+have `getServerSideProps = () => ({ notFound: true })` stubs.
+
+**Static props (`getLayout`, `acl`) not picked up from package exports**
+→ Use the explicit import + assignment pattern (§6). Bare `export { X as default }`
+does not carry static properties across package boundaries.
+
+**Duplicate React / MUI hook errors**
+→ Pin `react`, `react-dom`, and `@mui/material` to the host app's copies via
+`config.resolve.alias` in `next.config.js`.
+
+---
+
+## 23. Layout Grid component
+
+The `layout` / `layout-cell` pair provides a **CSS Grid** container whose column count, gap, and per-cell styling are configured entirely inside the builder inspector — no hand-written CSS required.
+
+### How it works
+
+Drop a **Layout Grid** onto the canvas. The builder auto-initialises it with a 2×2 grid of `layout-cell` children. You can add more cells from the sidebar or adjust the column count in the inspector; cells reflow automatically. Each `layout-cell` is an independent drop-zone that accepts any component.
+
+### Inspector props — Layout Grid (`layout`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | number | `2` | Number of equal-width columns. |
+| `gap` | number px | `8` | Column gap between cells. |
+| `rowGap` | number px | same as `gap` | Row gap — defaults to `gap` when not set. |
+| `cellMinHeight` | number/string | — | Applied to every cell as a grid-level default. |
+| `cellPadding` | number/string | — | Inner padding for every cell. |
+| `cellBackgroundColor` | color | — | Background color applied to every cell. |
+| `cellBorder` | string | — | CSS border shorthand applied to every cell (e.g. `1px solid #ccc`). |
+| `cellBorderRadius` | number/string | — | Border radius applied to every cell. |
+| `cellBoxShadow` | string | — | Box-shadow applied to every cell. |
+| `cellJustifyContent` | string | — | Flexbox `justify-content` inside every cell. |
+| `cellAlignItems` | string | — | Flexbox `align-items` inside every cell. |
+| `cellElementStyle` | object | — | Extra React style object merged last (overrides the above). |
+| `cellElementCss` | string | — | Extra CSS string merged last (overrides the above). |
+
+Individual cells can override any of the above via their own **Style** tab in the inspector.
+
+### Schema example
+
+```json
+{
+  "type": "layout",
+  "props": {
+    "main": {
+      "cols": { "valueType": "value", "value": 3 },
+      "gap":  { "valueType": "value", "value": 16 }
+    }
+  },
+  "children": [
+    { "type": "layout-cell", "props": {}, "children": [] },
+    { "type": "layout-cell", "props": {}, "children": [] },
+    { "type": "layout-cell", "props": {}, "children": [] }
+  ]
+}
+```
+
+---
+
+## 24. Wizard component
+
+The `wizard` / `wizard-step` pair renders a **MUI Stepper** with optional validation, async lifecycle hooks, and controlled or uncontrolled step state. Drop a **Wizard** onto the canvas; each direct `wizard-step` child becomes one step.
+
+### Inspector props — Wizard (`wizard`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `'horizontal'` \| `'vertical'` | `'horizontal'` | Stepper orientation. |
+| `variant` | `'alternativeLabel'` \| — | — | MUI alternativeLabel layout (label below icon). |
+| `linear` | boolean | `true` | When `true` the user cannot skip ahead. |
+| `hideNavigation` | boolean | `false` | Hide the Back / Next / Finish button row. |
+| `key` | string | `'wizardStep'` | `data` key written with the current step index when controlled mode is active. |
+| `activeStep` | number \| expression | — | When set, the wizard is **controlled** — step state is driven by `data[key]`. |
+| `backLabel` | string | `'Back'` | Label for the Back button. |
+| `nextLabel` | string | `'Next'` | Label for the Next button. |
+| `finishLabel` | string | `'Finish'` | Label for the Finish button. |
+| `nextColor` | MUI color | `'primary'` | Color of the Next/Finish button. |
+| `nextVariant` | string | `'contained'` | Variant of the Next/Finish button. |
+| `backColor` | MUI color | `'inherit'` | Color of the Back button. |
+| `backVariant` | string | `'text'` | Variant of the Back button. |
+| `onStepChange` | JS action | — | Runs on every step transition. Receives `{ from, to, direction, goToStep, nextStep, prevStep }`. |
+| `onFinish` | JS action | — | Runs when the user clicks Finish on the last step. Receives `{ goToStep, nextStep, prevStep }`. |
+
+### Inspector props — Wizard Step (`wizard-step`)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | string | Step label shown in the stepper header. |
+| `optional` | boolean | Marks the step as optional (shows "Optional" sub-label). |
+| `onEnter` | JS action | Fires when this step becomes active. Receives `{ stepIndex, goToStep, nextStep, prevStep }`. |
+| `onNext` | JS action | Fires when the user clicks Next/Finish **from** this step. Return `false` to block navigation (validation). Receives `{ stepIndex, goToStep, nextStep, prevStep }`. |
+
+### Navigation helpers available in all wizard JS actions
+
+```js
+goToStep(n)   // jump to step n (0-based)
+nextStep()    // advance one step
+prevStep()    // go back one step
+```
+
+### Controlled mode example
+
+Set `activeStep` to an expression `data.currentStep` and `key` to `"currentStep"`. The wizard will now read and write `data.currentStep` instead of keeping its own internal state — useful when the host app needs to save progress.
+
+---
+
+## 25. Repeater component
+
+The `Repeater` renders a list of identical template items from a static array, a dynamic count, or a fetched API endpoint. It supports three iteration modes and automatically scopes each item's form state so inputs inside the Repeater don't share values.
+
+### Iteration modes
+
+| Mode | How to configure | When to use |
+|------|-----------------|-------------|
+| **Static items** | Set `items` to a static or expression array | Known, enumerable values |
+| **Count** | Set `count` to a number; optionally `dataKey` to store values | Dynamic N-row form arrays |
+| **Endpoint / Widget** | Set `endpoint` + `serviceId` or `widgetId` | Server-fetched lists |
+
+### Inspector props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | array \| expression | — | Static item array. Each element is available as `dataItem` inside children. |
+| `count` | number \| expression | — | Number of slots to render (used when `items` is empty). |
+| `dataKey` | string | — | `data` key where per-item values are stored (`data[dataKey][index]`). Enables full scoping — form inputs write to `data[dataKey][index][fieldKey]`. |
+| `direction` | `'vertical'` \| `'horizontal'` \| `'wrap'` | `'vertical'` | Flex direction of the item list. |
+| `gap` | number | `1` | Gap between items (MUI spacing units). |
+| `endpoint` | string | — | API endpoint ID to fetch items from (used with `serviceId`). |
+| `serviceId` | string | — | Service ID that owns the endpoint. |
+| `widgetId` | string | — | ID of a saved Widget to use as the item template instead of inline children. |
+
+### Expressions inside a Repeater
+
+Inside a Repeater's children the following variables are injected into every expression context:
+
+| Variable | Value |
+|----------|-------|
+| `dataItem` | The current array element |
+| `itemIndex` | Zero-based item index |
+| `form[key]` | The current item's scoped form value for `key` |
+
+### Form-array pattern
+
+```json
+{
+  "type": "repeater",
+  "props": {
+    "main": {
+      "count":   { "valueType": "value", "value": 3 },
+      "dataKey": { "valueType": "value", "value": "contacts" },
+      "direction": { "valueType": "value", "value": "vertical" }
+    }
+  },
+  "children": [
+    { "type": "input", "props": { "main": { "key": { "valueType": "value", "value": "name" }, "label": { "valueType": "value", "value": "Name" } } }, "children": [] }
+  ]
+}
+```
+
+After filling in 3 rows the submitted `data` will contain:
+
+```json
+{ "contacts": [{ "name": "Alice" }, { "name": "Bob" }, { "name": "Carol" }] }
+```
+
+---
+
+## 26. Menu component
+
+The `menu` component renders a **MUI Tabs** bar that can operate in two modes: **navigation mode** (items-based, each tab is a link/action with no drop zone) and **tab-panel mode** (tabs-based, each tab owns a drop zone for child components).
+
+### Mode comparison
+
+| Feature | Navigation mode | Tab-panel mode |
+|---------|----------------|----------------|
+| Config prop | `items` array | `tabs` array |
+| Children | None | One drop zone per tab |
+| Typical use | App-level routing tabs, wizard menus | Sectioned forms, content panels |
+
+### Inspector props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | array | `[]` | Navigation items. Each item: `{ title, icon?, iconPosition?, disabled?, href? }`. Setting this enables navigation mode. |
+| `tabs` | array | `[]` | Tab panel items. Each tab: `{ label, icon?, iconPosition?, disabled? }`. Setting this enables tab-panel mode. |
+| `activeKey` | string | first item title | Active tab key (navigation mode). |
+| `vertical` | boolean | `false` | Render tabs vertically. |
+| `justified` | boolean | `false` | Stretch tabs to fill the full width (`fullWidth` variant). |
+| `reversed` | boolean | `false` | Reverse the order of navigation items. |
+
+### Tab-panel mode example
+
+```json
+{
+  "type": "menu",
+  "props": {
+    "main": {
+      "tabs": {
+        "valueType": "value",
+        "value": [
+          { "label": "General" },
+          { "label": "Advanced" },
+          { "label": "Permissions" }
+        ]
+      }
+    }
+  },
+  "children": [
+    { "type": "input", "props": {}, "children": [] }
+  ]
+}
+```
+
+Children are distributed across tabs in the order they appear. Drag-and-drop in the builder assigns each dropped component to the currently active tab.
+
+---
+
+## 27. View Renderer component
+
+The `viewRenderer` component **embeds a saved builder view inline** inside another view. It fetches the target view's schema at runtime and renders it as a fully functional sub-page. This is useful for shared sub-forms, reusable panels, and composition patterns.
+
+### Inspector props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `viewId` | string | — | **Required.** ID of the saved view to embed. |
+| `isolated` | boolean | `true` | When `true` the embedded view gets its own `data`/`form`/`ref` stores. When `false` it shares the parent page's state (useful for sub-forms where field values should appear in the parent `data` object). |
+| `initialData` | expression | — | Seed data passed into the child view on mount (isolated mode only). Re-evaluated reactively — a new seed resets child state. |
+| `externalData` | expression | — | Additional data merged into child state on every parent re-render without resetting existing child state (isolated mode only). |
+| `heightMode` | `'auto'` \| `'fixed'` | `'auto'` | `'fixed'` enables an explicit pixel height with scroll. |
+| `height` | number | `400` | Pixel height when `heightMode` is `'fixed'`. |
+
+### State isolation
+
+```
+isolated = true  (default)
+  Child view: own data, own form, own refs
+  Parent data: unchanged
+  Use when: embeddable widgets, preview panels, independent sub-pages
+
+isolated = false
+  Child view: shares parent setData / data / form
+  All field keys from the child view appear in the parent's data object
+  Use when: large form split across multiple saved views
+```
+
+### onLoad actions
+
+If the embedded view schema has `actions` with an `onLoad` event, those actions fire automatically when the schema is resolved — using the child's own data/form context when isolated, or the parent's when shared.
+
+---
+
+## 28. Container and Card components
+
+### Container (`container`)
+
+A basic **flex column** wrapper. Use it to group components, control spacing, and apply shared styling (background colour, border, padding, etc.) via the Style tab. Containers are drop targets and can be nested arbitrarily.
+
+There are no required inspector props. All visual configuration is done through the Style tab.
+
+### Card (`card`)
+
+A **MUI Card** wrapper. Behaves like a Container but renders with a card surface (shadow, rounded corners, optional header/subheader). Use when you need a visually distinct panel grouping components.
+
+Both `container` and `card` appear in the `CONTAINER_TYPES` set in `builderHelper.js`, so the paste-as-child heuristic applies — pasting a node while a container or card is selected inserts the node as a child rather than a sibling.
+
+---
+
+## 29. Breadcrumb component
+
+The `breadcrumb` component renders a **MUI Breadcrumbs** navigation trail. Items are configured as a static or expression-driven array in the inspector.
+
+### Inspector props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | array \| expression | Breadcrumb items. Each item: `{ label, href?, icon? }`. The last item is the current page (non-clickable). |
+| `separator` | string | Custom separator character (default `/`). |
+| `maxItems` | number | Maximum number of items before collapsing (MUI default is 8). |
+
+### Example
+
+```json
+{
+  "type": "breadcrumb",
+  "props": {
+    "main": {
+      "items": {
+        "valueType": "value",
+        "value": [
+          { "label": "Home",    "href": "/" },
+          { "label": "Reports", "href": "/reports" },
+          { "label": "Q1 2025" }
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
+## 30. Planned / TODO Components
+
+The following component types appear in earlier schema drafts or were removed from the catalog because they are not yet fully implemented. They are preserved here as a backlog reference.
+
+| Component | Type string | Notes |
+|-----------|-------------|-------|
+| Calendar | `calendar` | Date/range calendar field. Placeholder only — no renderer or inspector definition. |
+| Google Map | `google-map` | Embedded map with marker/search support. Requires Maps JS API key integration. |
+| QR Code | `qrcode` | Barcode/QR generator. Removed from the main catalog; still present in the print catalog as a valid print-time use case. Needs a renderer. |
+| Tooltip | `tooltip` | Hover tooltip wrapper for arbitrary children. Removed pending a design decision on how it wraps other components in the tree. |
+
+### Removed (superseded)
+
+The following structure components were removed because the Layout Grid (`layout` / `layout-cell`) and Data Grid (`data-grid`) cover their use cases with a better UX:
+
+| Component | Type string | Superseded by |
+|-----------|-------------|---------------|
+| Table | `table` | `data-grid` |
+| Cell | `cell` | `layout-cell` / `data-grid` |
+| Header Cell | `header-cell` | `data-grid` |
+| Column Group | `column-group` | `layout` / `data-grid` |
+| Column | `column` | `layout-cell` / `data-grid` |
+| Tab | `tab` | `menu` (supports icons, orientation, disabled tabs, per-tab drop zones, and more) |
+
+The `upload` component was removed in favour of `excel-upload`, which provides Excel-native parsing, column mapping, and AG Grid preview out of the box.