robobyte-front-builder 1.0.21 → 1.0.23

package/README.md

@@ -1,15 +1,50 @@
 # robobyte-front-builder
 
-A low-code UI builder, Report builder, Print Layout designer, and Navigation extension system for Next.js applications.
+A low-code **UI Builder**, **Report Builder**, **Print Layout Designer**, and **Navigation Extension API** for Next.js applications.
 
 [![npm version](https://img.shields.io/npm/v/robobyte-front-builder)](https://www.npmjs.com/package/robobyte-front-builder)
 
 ---
 
+## Table of Contents
+
+1. [What's included](#whats-included)
+2. [Requirements](#requirements)
+3. [Installation](#installation)
+4. [Peer dependencies](#peer-dependencies)
+5. [next.config.js setup](#nextconfigjs-setup)
+6. [Provider setup](#provider-setup-_appjs)
+7. [Builder pages](#builder-pages)
+8. [Navigation Extension API](#navigation-extension-api)
+9. [Provider props reference](#provider-props-reference)
+10. [fetchReportDataByPageId](#fetchreportdatabypageid)
+11. [ReportViewer as a component](#reportviewer-as-a-component)
+12. [Data Grid component](#data-grid-component)
+13. [Dialog component](#dialog-component)
+14. [Popover component](#popover-component)
+15. [Excel Upload component](#excel-upload-component)
+16. [Wizard component](#wizard-component)
+17. [Repeater component](#repeater-component)
+18. [Menu component](#menu-component)
+19. [View Renderer component](#view-renderer-component)
+20. [Layout Grid component](#layout-grid-component)
+21. [Breadcrumb component](#breadcrumb-component)
+22. [Print Layout Builder](#print-layout-builder)
+23. [Calculation Scope Reference](#calculation-scope-reference)
+24. [KPI Component Actions](#kpi-component-actions)
+25. [Global Data Store](#global-data-store)
+26. [Dark / Light theme](#dark--light-theme)
+27. [Syncing local changes](#syncing-local-changes)
+28. [Troubleshooting](#troubleshooting)
+29. [Publishing](#publishing)
+30. [Changelog](#changelog)
+
+---
+
 ## What's included
 
 - **UI Builder** — drag-and-drop canvas for building data-driven views with 50+ components
-- **Report Builder** — design and preview paginated reports
+- **Report Builder** — design and preview paginated reports with AG Grid
 - **Print Layout Designer** — multi-zone print templates (header / body pages / footer)
 - **Navigator Builder** — configure sidebar navigation
 - **Viewer** — production read-only renderer for saved UI Builder views
@@ -17,6 +52,7 @@ A low-code UI builder, Report builder, Print Layout designer, and Navigation ext
 - **KPI Components** — 12 ready-to-use metric visualisations (gauge, trend, bullet chart, rating, countdown, …)
 - **Timer Engine** — configurable auto-refresh timers per view
 - **Undo / Redo / Copy / Paste** — full clipboard and history support in the builder
+- **Global Data Store** — cross-route reactive state that survives client-side navigations
 
 ---
 
@@ -38,9 +74,11 @@ A low-code UI builder, Report builder, Print Layout designer, and Navigation ext
 npm install robobyte-front-builder
 ```
 
-### Required peer dependencies
+---
+
+## Peer dependencies
 
-These must be installed in the **host app** (they must be shared as a single instance):
+Only the libraries that **must be shared as a single instance** are declared as `peerDependencies` — React, MUI, Emotion, and AG Grid. Everything else ships inside the package so the host app doesn't need to install them manually.
 
 ```bash
 npm install \
@@ -52,152 +90,826 @@ npm install \
   xlsx react-hot-toast
 ```
 
-> Everything else (`dayjs`, `lodash`, `recharts`, etc.) ships inside the package and does not need to be installed in the host app.
+> **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.
 
 ---
 
-## Setup
-
-### 1. next.config.js
+## `next.config.js` setup
 
-Add the package to `transpilePackages` so Next.js compiles the source-first package:
+Two things are required: **transpile** the package and set up the **context-aware bare-alias webpack plugin** so that bare imports like `services/*`, `context/*`, etc. resolve to the correct source tree.
 
 ```js
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  transpilePackages: ['robobyte-front-builder'],
-}
-
-module.exports = nextConfig
+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 }) {
+    if (isServer) {
+      config.resolve.conditionNames = ['require', 'node', 'default']
+    }
+
+    const { NormalModuleReplacementPlugin } = require('webpack')
+
+    // Package-owned services — always resolved from the package
+    const packageOwnedServices = [
+      'services/reportData/fetchReportData',
+    ]
+    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
+    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
+  },
+})
 ```
 
-### 2. Wrap your app
+> **Restart the dev server** whenever `next.config.js` changes — hot-reload does not apply to webpack plugin changes.
 
-In `pages/_app.js`, wrap your tree with the provider:
+---
+
+## Provider setup (`_app.js`)
+
+Wrap the component tree with `RoboByteFrontBuilderProvider`. Bridge your host auth context into it so the package attaches auth headers to every API call.
 
 ```jsx
 import { RoboByteFrontBuilderProvider } from 'robobyte-front-builder'
 
-export default function App({ Component, pageProps }) {
+function RoboByteBridge({ children }) {
+  const auth = useContext(YourAuthContext)
   return (
     <RoboByteFrontBuilderProvider
-      baseURL="https://your-api.example.com"
-      apiURL="https://your-api.example.com/api"
-      getAccessToken={() => yourAuthModule.getToken()}
-      getUser={() => yourAuthModule.getCurrentUser()}
+      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}
     >
-      <Component {...pageProps} />
+      {children}
     </RoboByteFrontBuilderProvider>
   )
 }
+
+export default function App({ Component, pageProps }) {
+  const getLayout = Component.getLayout ?? (page => page)
+  return (
+    <YourAuthProvider>
+      <RoboByteBridge>
+        {getLayout(<Component {...pageProps} />)}
+      </RoboByteBridge>
+    </YourAuthProvider>
+  )
+}
 ```
 
-### 3. Add pages
+---
 
-Create page files in your host app that re-export the builder pages:
+## Builder pages
 
-```js
-// pages/ui-builder/[id].js
-export { default } from 'robobyte-front-builder/UIBuilderPage'
-// or:
-import { UIBuilderPage } from 'robobyte-front-builder'
-export default UIBuilderPage
-```
+All builder routes live under the `/builders/` prefix. Create a thin wrapper page in your host app for each route.
 
-| Host page path | Export to use |
+| Route | Package export |
 |---|---|
-| `pages/ui-builder/[id].js` | `UIBuilderPage` |
-| `pages/ui-builder/views/index.js` | `ViewsList` |
-| `pages/viewer/[id].js` | `ViewerPage` |
-| `pages/report-builder/[id].js` | `ReportBuilderPage` |
-| `pages/report-builder/reports/index.js` | `ReportsList` |
-| `pages/report-builder/viewer/index.js` | `ReportViewer` |
-| `pages/navigator-builder/index.js` | `NavigatorBuilderPage` |
-| `pages/print-builder/index.js` | `PrintBuilderPage` |
-| `pages/print-builder/layouts/index.js` | `PrintLayoutsList` |
+| `/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` |
+| `/printBuilder` | `PrintBuilderPage` |
+| `/printBuilder/layouts` | `PrintLayoutsList` |
+
+### Page wrapper pattern
+
+Use 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
+```
+
+### Viewer page (`/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
+```
 
 ---
 
 ## Navigation Extension API
 
-Inject nav items into the builder's sidebar from anywhere in the host app without touching this package:
+### 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'
 
-export default function MyFeatureModule() {
-  useNavExtension({
-    key: 'my-feature',
-    label: 'My Feature',
-    icon: <MyIcon />,
-    href: '/my-feature',
-    order: 10,
-  })
+function MyFeaturePlugin() {
+  useNavExtension(
+    [{ id: 'my-feature', title: 'My Feature', icon: 'StarOutline', type: 'static', path: '/my-feature', insertAt: 'start' }],
+    'my-feature-plugin'
+  )
+  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 (default `'end'`) |
+| `children` | NavItem[] | no | Collapsible group |
+| `action` / `subject` | string | no | CASL ACL visibility |
+
+---
+
+## Provider props reference
+
+| Prop | Type | Description |
+|---|---|---|
+| `baseURL` | string | Root API server URL |
+| `apiURL` | string | `/api` prefix URL |
+| `user` | object | Current user object from your auth context |
+| `accessToken` | string | Bearer token attached to every service call |
+| `agGridLicenseKey` | string | AG Grid Enterprise license key — the provider calls `LicenseManager.setLicenseKey()` and registers all enterprise modules internally |
+| `navExtensions` | array | Static nav items to inject into the sidebar |
+| `endpoints` | object | Full-URL overrides per endpoint group + name |
+
+> **AG Grid note:** Do not call `LicenseManager` or `ModuleRegistry` in the host app — the provider handles it entirely.
+
+---
+
+## `fetchReportDataByPageId`
 
-  return <div>...</div>
+Fetches report data by `pageId` without any AG Grid dependency. Always imported from the package path — the `NormalModuleReplacementPlugin` in `next.config.js` routes it to the package's canonical implementation.
+
+```js
+import fetchReportDataByPageId from 'services/reportData/fetchReportData'
+
+const result = await fetchReportDataByPageId({
+  pageId,          // required
+  filter,          // { Tfilter, TFilter, customFilterCode, ... }
+  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
+  page,            // page number (default 1)
+  pageSize,        // page size (default 50)
+  authContext,
+  context,
+})
+
+if (result.success) {
+  console.log(result.rows)
+  console.log(result.total)
+}
+```
+
+### `customFilterCode`
+
+```js
+const filter = {
+  customFilterCode: `
+    if (authContext?.user?.shopId) {
+      customFilter.push({ field: 'ShopId', value: authContext.user.shopId, operation: 'Equal' })
+    }
+  `
 }
 ```
 
 ---
 
-## RoboByteFrontBuilderProvider props
+## 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"
+/>
+```
 
 | Prop | Type | Description |
 |---|---|---|
-| `baseURL` | `string` | Base URL for file/asset requests |
-| `apiURL` | `string` | API base URL for all data endpoints |
-| `getAccessToken` | `() => string` | Called before each request to get the auth token |
-| `getUser` | `() => object` | Returns the current user object |
-| `navExtensions` | `array` | Static nav items to inject (alternative to `useNavExtension`) |
-| `theme` | `object` | MUI theme override |
+| `id` | string | Report ID |
+| `pageId` | string | Report page ID |
+| `filter` | object | External filter |
+| `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 selectionParams by index |
+| `sessionId` | string | Load filter payload from localStorage |
+| `updateRef` | ref | Ref for programmatic updates |
+
+---
+
+## Data Grid component
+
+The **Data Grid** wraps AG Grid Enterprise and is configurable entirely from the builder inspector.
+
+### Inspector — Main tab
+
+| Field | Description |
+|---|---|
+| `Key` | Reference key for `reportRefs` access |
+| `Data Key` | Key to read/write row data in page `data` |
+| `Columns` | Expression returning an AG Grid `colDef[]` array |
+| `Extra Columns` | Visual editor for adding new columns on top of data-driven ones |
+| `Columns Config` | Visual editor for overriding existing column properties by `field` name |
+| `Row Actions` | Visual editor for per-row action buttons |
+| `Add Button Label` | Label for the add-row button (default `"Add"`) |
+| `New Row Template` | Code returning the default object for a new row |
+| `Read Only` | Expression — when truthy, disables all editing |
+| `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 |
+
+### `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
+```
+
+---
+
+## Dialog component
+
+Renders a hidden MUI Dialog opened programmatically via `openDialog(key)` / `closeDialog(key)`.
+
+### Inspector — Main tab
+
+| Field | Description |
+|---|---|
+| `Key` | Identifier used to open/close — must be unique on the page |
+| `View ID` | When set, renders a full embedded view inside the dialog body |
+| `Title` | Dialog title bar text (expression) |
+| `Hide Title Bar` | Hides the entire title bar |
+| `Max Width` | `xs` / `sm` / `md` / `lg` / `xl` |
+| `Full Width` | Stretch to max width breakpoint |
+| `Full Screen` | Full-screen mode |
+| `Show Close Button` | Shows the × icon |
+| `Close on Backdrop` | Closes when user clicks outside |
+| `Action Buttons` | Footer buttons, each with its own Calculation code |
+
+### Usage
+
+```js
+// Open with optional seed data
+openDialog('confirmDelete')
+openDialog('editUser', { userId: row.id, name: row.name })
+
+// Close
+closeDialog('confirmDelete')
+```
+
+### Isolated data store
+
+Each dialog gets its own `data` / `setData` scope. 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 }))
+```
+
+---
+
+## Popover component
+
+A self-contained trigger (button, icon button, or text) that opens a floating panel. No `openDialog` call needed.
+
+### Inspector — Main tab
+
+| Field | Description |
+|---|---|
+| `Trigger Type` | `button` / `icon-button` / `text` |
+| `Trigger Label` | Label text |
+| `Placement` | `bottom-start`, `bottom`, `bottom-end`, `top-start`, etc. |
+| `Trigger On` | `click` (default) or `hover` |
+| `Controlled Open` | Expression — overrides the internal open/close state |
+| `Close On Content Click` | Closes when any child inside is clicked |
 
 ---
 
-## Advanced: accessing builder context
+## Excel Upload component
+
+Lets users upload `.xlsx`, `.xls`, or `.csv` files, map columns to field names, and access the result in actions.
+
+### Display variants
+
+| Variant | Description |
+|---|---|
+| `dropzone` | Large dashed drop zone with drag & drop |
+| `button` | Compact outlined button |
+| `icon` | Icon-only button |
+
+### Actions
+
+| Event | `newValue` | Notes |
+|---|---|---|
+| `onUpload` | `{ fileName, headers, rowCount }` | Fires after parsing, before the mapping dialog |
+| `onMapped` | `Array<object>` | Fires before data is saved — **return a modified array** to override |
+| `onClear` | `[]` | Fires when the user clears the data |
 
-For host apps that need to read or drive builder state programmatically:
+### `reportRefs` API
 
 ```js
-import { useBuilder } from 'robobyte-front-builder'
+const uploader = reportRefs['myUploaderKey']
+uploader.rows          // current mapped rows
+uploader.setRows(arr)  // replace stored rows
+uploader.clear()       // clear all stored rows
+```
+
+---
+
+## Wizard component
+
+A MUI Stepper with optional validation, async lifecycle hooks, and controlled or uncontrolled step state.
 
-const { schema, dispatch } = useBuilder()
+### Inspector props — Wizard
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal'` \| `'vertical'` | `'horizontal'` | Stepper orientation |
+| `linear` | boolean | `true` | Prevent skipping ahead |
+| `hideNavigation` | boolean | `false` | Hide Back / Next / Finish buttons |
+| `key` | string | `'wizardStep'` | `data` key written with the current step index |
+| `activeStep` | number \| expression | — | When set, wizard is controlled by `data[key]` |
+| `onStepChange` | JS action | — | Receives `{ from, to, direction, goToStep, nextStep, prevStep }` |
+| `onFinish` | JS action | — | Runs when user clicks Finish on the last step |
+
+### Inspector props — Wizard Step
+
+| Prop | Type | Description |
+|---|---|---|
+| `label` | string | Step label in the stepper header |
+| `optional` | boolean | Marks the step as optional |
+| `onEnter` | JS action | Fires when this step becomes active |
+| `onNext` | JS action | Return `false` to block navigation (validation) |
+
+### Navigation helpers
+
+```js
+goToStep(n)   // jump to step n (0-based)
+nextStep()    // advance one step
+prevStep()    // go back one step
 ```
 
 ---
 
-## Local development
+## Repeater component
+
+Renders a list of identical template items from a static array, a dynamic count, or a fetched API endpoint.
+
+| Mode | How to configure |
+|---|---|
+| Static items | Set `items` to a static or expression array |
+| Count | Set `count` to a number; optionally `dataKey` to store values |
+| Endpoint | Set `endpoint` + `serviceId` or `widgetId` |
+
+### Expressions inside a Repeater
+
+| Variable | Value |
+|---|---|
+| `dataItem` | The current array element |
+| `itemIndex` | Zero-based item index |
+| `form[key]` | The current item's scoped form value |
+
+---
+
+## Menu component
+
+Renders a MUI Tabs bar in two modes: **navigation mode** (items-based, each tab is a link/action) and **tab-panel mode** (tabs-based, each tab owns a drop zone).
+
+| Prop | Type | Description |
+|---|---|---|
+| `items` | array | Navigation items `{ title, icon?, href? }` — enables navigation mode |
+| `tabs` | array | Tab panel items `{ label, icon? }` — enables tab-panel mode |
+| `vertical` | boolean | Render tabs vertically |
+| `justified` | boolean | Stretch tabs to fill full width |
+
+---
+
+## View Renderer component
+
+Embeds a saved builder view inline inside another view, with isolated or shared state.
+
+| Prop | Type | Description |
+|---|---|---|
+| `viewId` | string | **Required.** ID of the saved view to embed |
+| `isolated` | boolean | `true` = own data/form/refs, `false` = shares parent state |
+| `initialData` | expression | Seed data passed on mount (isolated mode only) |
+| `externalData` | expression | Additional data merged on every parent re-render |
+| `heightMode` | `'auto'` \| `'fixed'` | `'fixed'` enables a pixel height with scroll |
+| `height` | number | Pixel height when `heightMode` is `'fixed'` |
+
+---
+
+## Layout Grid component
+
+A CSS Grid container whose column count, gap, and per-cell styling are configured in the builder inspector.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `cols` | number | `2` | Number of equal-width columns |
+| `gap` | number px | `8` | Column gap |
+| `rowGap` | number px | same as `gap` | Row gap |
+| `cellMinHeight` | number/string | — | Default min-height for every cell |
+| `cellPadding` | number/string | — | Inner padding for every cell |
+| `cellBackgroundColor` | color | — | Background color for every cell |
+| `cellBorder` | string | — | CSS border shorthand for every cell |
+| `cellBorderRadius` | number/string | — | Border radius for every cell |
+| `cellBoxShadow` | string | — | Box-shadow for every cell |
+| `cellJustifyContent` | string | — | Flexbox `justify-content` inside every cell |
+| `cellAlignItems` | string | — | Flexbox `align-items` inside every cell |
+
+---
+
+## Breadcrumb component
 
-To link the package locally without publishing:
+Renders a MUI Breadcrumbs navigation trail.
 
 ```json
-// host app package.json
-"robobyte-front-builder": "file:../../RoboByteFrontBuilder"
+{
+  "type": "breadcrumb",
+  "props": {
+    "main": {
+      "items": {
+        "valueType": "value",
+        "value": [
+          { "label": "Home",    "href": "/" },
+          { "label": "Reports", "href": "/reports" },
+          { "label": "Q1 2025" }
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Print Layout Builder
+
+> ⚠️ **Preview — needs more testing.** Functional but not production-ready.
+
+Design reusable print layouts with configurable headers, footers, multi-page bodies, watermarks, and page numbering.
+
+### Backend API endpoints required
+
+| Method | URL | Description |
+|---|---|---|
+| `POST` | `UiBuilderModule/PrintLayout` | Create a new layout |
+| `PUT` | `UiBuilderModule/PrintLayout` | Update an existing layout |
+| `GET` | `UiBuilderModule/PrintLayout/GetAll` | List all layouts |
+| `GET` | `UiBuilderModule/PrintLayout/GetById?id=<id>` | Fetch by ID |
+| `DELETE` | `UiBuilderModule/PrintLayout?id=<id>` | Delete a layout |
+
+### Triggering print from a view
+
+```js
+openPrintLayout('your-layout-id', {
+  invoiceNumber: data.invoiceNumber,
+  customerName:  data.customer.name,
+  lines:         data.lines,
+})
+```
+
+### Page numbering format
+
+Use `{page}` and `{pages}` tokens in the Format field:
+
+```
+Page {page} of {pages}   →  Page 1 of 4
+```
+
+---
+
+## Calculation Scope Reference
+
+Every Calculation function receives the same set of variables:
+
+### Core state
+
+| Variable | Description |
+|---|---|
+| `form` | Form field values (read-only snapshot) |
+| `data` | Reactive page state |
+| `setData` | Write page state — `setData(prev => ({ ...prev, key: value }))` |
+| `dataRef` | Mutable non-reactive store |
+| `reportRefs` | Map of `{ [key]: ref }` for every Data Grid / Excel Upload on the page |
+
+### Dialog / layout
+
+| Variable | Description |
+|---|---|
+| `openDialog(key, data?)` | Open a dialog, optionally seeding its isolated state |
+| `closeDialog(key)` | Close a dialog |
+| `openPrintLayout(layoutId, data?)` | Open the print preview |
+| `closePrintLayout()` | Close the active print preview |
+
+### Navigation & routing
+
+| Variable | Description |
+|---|---|
+| `router` | Next.js router — `router.push('/path')`, `router.query`, etc. |
+| `urlParams` | `{ query, pathname, asPath }` snapshot |
+
+### Global store
+
+| Variable | Description |
+|---|---|
+| `globalData` | Cross-route global state (read) |
+| `setGlobalData(updater)` | Write global state — shallow-merges by default |
+
+### Services
+
+| Variable | Description |
+|---|---|
+| `GetService` | Authenticated GET |
+| `PostService` | Authenticated POST |
+| `UpdateService` | Authenticated PUT |
+| `PatchService` | Authenticated PATCH |
+| `DeleteService` | Authenticated DELETE |
+| `fetchReportData` | Fetch report data by `pageId` |
+
+### Helpers
+
+| Variable | Description |
+|---|---|
+| `showToast(message, type?)` | `'success'` \| `'error'` \| `'warning'` \| `'info'` \| `'loading'` |
+
+### Parent page scope (inside dialogs / embedded views)
+
+| Variable | Description |
+|---|---|
+| `page.data` | Parent page's reactive state |
+| `page.setData` | Write to the parent page's state |
+| `page.dataRef` | Parent page's non-reactive store |
+| `page.reportRefs` | Parent page's grid refs |
+
+### Repeater-only
+
+| Variable | Description |
+|---|---|
+| `dataItem` | The current repeated item |
+| `itemIndex` | Zero-based iteration index |
+
+---
+
+## KPI Component Actions
+
+KPI components support interaction events configured in the inspector Main tab → Actions section.
+
+| Component | Event | Click-context variables |
+|---|---|---|
+| **Metric** | `onClick` | `clickedValue` |
+| **Rating** | `onChange` | `newValue`, `clickedValue` |
+| **Chart** | `onDataClick` | `clickedItem`, `clickedValue`, `clickedField`, `clickedLabel`, `clickedIndex` |
+| **HeatmapGrid** | `onCellClick` | `clickedItem`, `clickedValue`, `clickedRow`, `clickedCol`, `clickedRowIndex`, `clickedColIndex` |
+| **Timeline** | `onItemClick` | `clickedItem`, `clickedIndex`, `clickedLabel`, `clickedStatus`, `clickedValue` |
+| **StepStage** | `onStepClick` | `clickedItem`, `clickedIndex`, `clickedId`, `clickedLabel`, `clickedStatus` |
+| **TagList** | `onTagClick` | `clickedItem`, `clickedTag`, `clickedLabel`, `clickedValue`, `clickedIndex` |
+
+---
+
+## Global Data Store
+
+A module-level reactive singleton that survives client-side navigations.
+
+### In Calculation functions
+
+```js
+// Read
+console.log(globalData.selectedUser)
+
+// Write
+setGlobalData(prev => ({ ...prev, selectedUser: clickedItem }))
+
+// Navigate — globalData persists to the next page
+router.push('/user-detail')
+```
+
+### In React components
+
+```jsx
+import { useGlobalStore } from 'robobyte-front-builder'
+
+function MyComponent() {
+  const { globalData, setGlobalData } = useGlobalStore()
+  return <p>Selected: {globalData.selectedUser?.name}</p>
+}
+```
+
+### Resetting on logout
+
+```js
+import { resetGlobalData } from 'robobyte-front-builder'
+
+function handleLogout() {
+  resetGlobalData()
+  // ... your auth logout
+}
+```
+
+### API
+
+| Export | Description |
+|---|---|
+| `useGlobalStore()` | React hook — `{ globalData, setGlobalData }` |
+| `getGlobalData()` | Synchronous read from non-React code |
+| `setGlobalData(updater)` | Write from anywhere |
+| `subscribeGlobal(fn)` | Subscribe to changes — returns unsubscribe function |
+| `resetGlobalData()` | Reset to `{}` and notify all subscribers |
+
+---
+
+## Dark / Light theme
+
+Both the UI Builder and Print Layout Builder support dark and light modes (default: dark). A toggle button (☀️ / 🌙) is available in each builder's toolbar. The choice is persisted in `localStorage` under `rbb:builderThemeMode`. The theme is scoped to the builder pages only and does not affect the rest of the host application.
+
+---
+
+## Syncing local changes
+
+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/lib/index.js $PKG/lib/index.js
+cp $SRC/lib/providers/RoboByteFrontBuilderProvider.jsx $PKG/lib/providers/RoboByteFrontBuilderProvider.jsx
+cp $SRC/services/reportData/fetchReportData.js $PKG/services/reportData/fetchReportData.js
+# ... add other files as needed
 ```
 
-Run `npm install` once, then Next.js hot-reload picks up changes automatically.
+Hot-reload picks up all file changes automatically. Only `next.config.js` changes require a dev server restart.
+
+---
+
+## Troubleshooting
+
+**"Module not found: Can't resolve 'xlsx'"**  
+→ Install `xlsx` in the host app: `npm install xlsx --legacy-peer-deps`
+
+**"Cannot find module 'services/...'"**  
+→ Ensure the `NormalModuleReplacementPlugin` is configured in `next.config.js`
+
+**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'`.
+
+**Static props (`getLayout`, `acl`) not picked up from package exports**  
+→ Use the explicit import + assignment pattern. 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`.
+
+**Old routes returning 404**  
+→ Check that host-app pages exist under `/builders/...` and that old paths have `getServerSideProps = () => ({ notFound: true })` stubs.
 
 ---
 
 ## Publishing
 
 ```bash
-npm version patch   # bug fix  → 1.0.x
-npm version minor   # feature  → 1.x.0
-npm version major   # breaking → x.0.0
+npm login          # one-time setup
+
+npm version patch  # 1.0.x — bug fixes
+npm version minor  # 1.x.0 — new features
+npm version major  # x.0.0 — breaking changes
+
 npm publish
 ```
 
+Dry run (verify what will be published without actually publishing):
+```bash
+npm publish --dry-run
+```
+
 ---
 
 ## Changelog
 
 ### 1.0.21
-- Added Timer Engine — configurable auto-refresh timers per view (interval, cron, manual trigger)
+- Added Timer Engine — configurable auto-refresh timers per view
 - Added full Undo / Redo history with keyboard shortcuts (Ctrl+Z / Ctrl+Y)
 - Added Cut / Copy / Paste with system clipboard support (Ctrl+X / Ctrl+C / Ctrl+V)
 - Added Undo / Redo buttons to the viewer toolbar
-- Expanded KPI component suite: Gauge, BulletChart, ColorScale, Rating, Countdown, AvatarGroup, StepStage
-- Print Layout designer: multi-zone canvas (header / body / footer), `@page` CSS, print dialog
+- Expanded KPI suite: Gauge, BulletChart, ColorScale, Rating, Countdown, AvatarGroup, StepStage
+- Print Layout designer: multi-zone canvas, `@page` CSS, print dialog
 
 ### 1.0.20
 - KPI components: Metric, Trend, Badge, StatusDot, IconBox, Sparkline, MiniBarChart, Donut, Funnel, HeatmapGrid, TagList, Timeline, ComparisonBars
@@ -209,3 +921,8 @@ npm publish
 - Navigation Extension API
 - AG Grid and MUI data grid integration
 - Drag-and-drop canvas with 50+ components
+- Global Data Store
+
+---
+
+*Full user manual: [RoboByteBuilder_User_Manual.docx](./RoboByteBuilder_User_Manual.docx) (included in the package)*