robobyte-front-builder 1.0.26 → 1.0.28

package/INTEGRATION.md

@@ -176,6 +176,10 @@ function RoboByteBridge({ children }) {
       // Optional — Quartz theme overrides for every <AgGridReact> in the
       // package. Merged on top of the package defaults.
       // agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
+      // Optional — MUI theme overrides for every MUI component the package
+      // renders. Deep-merged on top of DEFAULT_MUI_THEME_OPTIONS in
+      // lib/muiTheme.js (Inter font, 8px radius, soft shadows, flat buttons).
+      // muiTheme={{ palette: { primary: { main: '#6366f1' } }, shape: { borderRadius: 12 } }}
     >
       {children}
     </RoboByteFrontBuilderProvider>
@@ -204,6 +208,8 @@ export default function App({ Component, pageProps }) {
 | `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. |
 | `agGridTheme`      | object   | Optional. Quartz theme overrides applied to every `<AgGridReact>` in the package. Merged on top of `DEFAULT_AG_THEME_PARAMS` (see [`src/lib/agGridTheme.js`](src/lib/agGridTheme.js)). Example: `{ accentColor: '#3b82f6', headerHeight: 32 }`. |
+| `muiTheme`         | object \| Theme | Optional. MUI theme overrides (options object) deep-merged on top of `DEFAULT_MUI_THEME_OPTIONS` (see [`src/lib/muiTheme.js`](src/lib/muiTheme.js)), OR a pre-built MUI `Theme` used as-is. Defaults give Inter font, 8px radius, soft shadows, flat buttons. Example: `{ palette: { primary: { main: '#6366f1' } }, shape: { borderRadius: 12 } }`. |
+| `disableMuiTheme`  | boolean  | Optional. When `true`, the provider skips its inner `<ThemeProvider>` — use this when the host has its own MUI ThemeProvider wrapping the app and wants it to apply inside the builder pages without merging. Default `false`. |
 | `navExtensions`    | array    | Static nav items to inject into the sidebar (optional) |
 | `endpoints`        | object   | Full-URL overrides per endpoint group + name (optional) |
 

package/LICENSE

@@ -0,0 +1,65 @@
+MIT License
+
+Copyright (c) 2024-2026 RoboByte / Hossny37
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Third-party components and commercial dependencies
+
+The MIT license above applies to the source code of `robobyte-front-builder`
+itself. This package depends on third-party libraries with their own licenses
+that consumers must comply with separately. The notable ones:
+
+### AG Grid Enterprise (peer dependency)
+
+This package's report and grid components rely on AG Grid Enterprise features
+(server-side row model, side tool panel, integrated charts, etc.) via the
+`ag-grid-enterprise` peer dependency. AG Grid Enterprise is a **commercial,
+proprietary product owned by AG Grid Ltd**. Consumers deploying this package
+in production must obtain a valid AG Grid Enterprise license from AG Grid
+Ltd and comply with their license terms:
+
+  https://www.ag-grid.com/license-pricing/
+
+AG Grid Community (the base library, MIT-licensed) is sufficient for
+development with a watermark; production use requires a paid license.
+
+### MUI X (peer dependency)
+
+`@mui/x-data-grid`, `@mui/x-date-pickers`, and related packages have free
+(MIT) and paid (Pro / Premium) tiers. This package uses only the free
+tiers by default. If a consumer opts to install Pro / Premium variants,
+they must comply with MUI's commercial license:
+
+  https://mui.com/pricing/
+
+### Other dependencies
+
+All other runtime and peer dependencies are open-source under permissive
+licenses (MIT, Apache 2.0, ISC, BSD). Run `npm ls --omit dev` to inspect
+the full graph and `npm-license-checker` (or similar) to enumerate licenses.
+
+---
+
+The license above does not waive or modify the terms of any third-party
+license referenced in this document. Consumers are responsible for
+obtaining and complying with licenses required by their use of those
+third-party components.

package/README.md

@@ -3,6 +3,27 @@
 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)
+[![license](https://img.shields.io/npm/l/robobyte-front-builder)](./LICENSE)
+[![github](https://img.shields.io/badge/github-Hossny37%2FRoboByteFrontBuilder-181717?logo=github)](https://github.com/Hossny37/RoboByteFrontBuilder)
+
+---
+
+## 📚 Documentation
+
+| Document | Audience | What it covers |
+|---|---|---|
+| **[README.md](./README.md)** *(this file)* | Everyone | Public surface, provider props, every component's inspector schema, action-scope tables, troubleshooting, changelog. The exhaustive reference. |
+| **[INTEGRATION.md](./INTEGRATION.md)** | Host-app developers | `next.config.js` setup, peer deps, page wrapper pattern, provider bridge, print layout integration steps. |
+| **[docs/ReportViewer.md](./docs/ReportViewer.md)** | Host-app developers | Embedding `<ReportViewer>` in regular React (cancellation, memo'd filters, `viewerActions`, master/detail patterns). |
+| **[docs/fetchReportData.md](./docs/fetchReportData.md)** | Host-app developers | Calling `fetchReportDataByPageId` directly from host code (hooks, KPI counters, XLSX export, paginated cursors). |
+| **[docs/printLayout.md](./docs/printLayout.md)** | Host-app developers | Triggering print layouts via `PrintDialog` ref API, recommended `PrintProvider` + `usePrintLayout()` pattern. |
+| **[training/00-index.md](./training/00-index.md)** | AI sessions / schema authors | Component catalog index — categories and one-page refs for every component the builder ships. |
+| **[training/35-reportViewer.md](./training/35-reportViewer.md)** | AI sessions / schema authors | Full AI manual for the `reportViewer` component (Calculation scope, action arrays, filter shape, recipes). |
+| **[training/48-fetchReportData.md](./training/48-fetchReportData.md)** | AI sessions / schema authors | In-builder Calculation reference for the auto-injected `fetchReportData` helper. |
+| **[training/49-printLayout.md](./training/49-printLayout.md)** | AI sessions / schema authors | In-builder Calculation reference for `openPrintLayout` / `closePrintLayout`. |
+| **[RoboByteBuilder_User_Manual.docx](./RoboByteBuilder_User_Manual.docx)** | End users | Visual user manual for the builder UI. Ships inside the package. |
+
+> **Pair convention.** Most features have **two** manuals: a `docs/` one for host-app React code (consumer of the package) and a `training/` one for AI sessions emitting builder schemas / Calculation code. They cross-link each other; pick the audience that matches your task.
 
 ---
 
@@ -18,27 +39,28 @@ A low-code **UI Builder**, **Report Builder**, **Print Layout Designer**, and **
 8. [Navigation Extension API](#navigation-extension-api)
 9. [Provider props reference](#provider-props-reference)
 10. [AG Grid theme](#ag-grid-theme)
-11. [fetchReportDataByPageId](#fetchreportdatabypageid)
-12. [ReportViewer as a component](#reportviewer-as-a-component)
-13. [Data Grid component](#data-grid-component)
-14. [Dialog component](#dialog-component)
-15. [Popover component](#popover-component)
-16. [Excel Upload component](#excel-upload-component)
-17. [Wizard component](#wizard-component)
-18. [Repeater component](#repeater-component)
-19. [Menu component](#menu-component)
-20. [View Renderer component](#view-renderer-component)
-21. [Layout Grid component](#layout-grid-component)
-22. [Breadcrumb component](#breadcrumb-component)
-23. [Print Layout Builder](#print-layout-builder)
-24. [Calculation Scope Reference](#calculation-scope-reference)
-25. [KPI Component Actions](#kpi-component-actions)
-26. [Global Data Store](#global-data-store)
-27. [Dark / Light theme](#dark--light-theme)
-28. [Syncing local changes](#syncing-local-changes)
-29. [Troubleshooting](#troubleshooting)
-30. [Publishing](#publishing)
-31. [Changelog](#changelog)
+11. [MUI theme](#mui-theme)
+12. [fetchReportDataByPageId](#fetchreportdatabypageid)
+13. [ReportViewer as a component](#reportviewer-as-a-component)
+14. [Data Grid component](#data-grid-component)
+15. [Dialog component](#dialog-component)
+16. [Popover component](#popover-component)
+17. [Excel Upload component](#excel-upload-component)
+18. [Wizard component](#wizard-component)
+19. [Repeater component](#repeater-component)
+20. [Menu component](#menu-component)
+21. [View Renderer component](#view-renderer-component)
+22. [Layout Grid component](#layout-grid-component)
+23. [Breadcrumb component](#breadcrumb-component)
+24. [Print Layout Builder](#print-layout-builder)
+25. [Calculation Scope Reference](#calculation-scope-reference)
+26. [KPI Component Actions](#kpi-component-actions)
+27. [Global Data Store](#global-data-store)
+28. [Dark / Light theme](#dark--light-theme)
+29. [Syncing local changes](#syncing-local-changes)
+30. [Troubleshooting](#troubleshooting)
+31. [Publishing](#publishing)
+32. [Changelog](#changelog)
 
 ---
 
@@ -177,6 +199,14 @@ function RoboByteBridge({ children }) {
       // "AG Grid theme" section for the full list of params and the
       // programmatic API. Omit to use the package defaults.
       agGridTheme={{ accentColor: '#3b82f6' }}
+      // Optional: MUI theme overrides applied to every MUI component the
+      // package renders. Deep-merged on top of DEFAULT_MUI_THEME_OPTIONS.
+      // See the "MUI theme" section for the full token list. Omit to use
+      // the package defaults (Inter font, 8px radius, soft shadows, etc.).
+      muiTheme={{
+        palette: { primary: { main: '#3b82f6' } },
+        shape:   { borderRadius: 10 },
+      }}
     >
       {children}
     </RoboByteFrontBuilderProvider>
@@ -323,6 +353,8 @@ function MyFeaturePlugin() {
 | `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 |
 | `agGridTheme` | object | Quartz theme overrides applied to every `<AgGridReact>` in the package. Merged on top of `DEFAULT_AG_THEME_PARAMS`. Example: `{ accentColor: '#3b82f6', headerHeight: 32 }`. See [AG Grid theme](#ag-grid-theme). |
+| `muiTheme` | object \| Theme | MUI theme overrides (options object) deep-merged on top of `DEFAULT_MUI_THEME_OPTIONS`, OR a pre-built MUI `Theme` used as-is. Example: `{ palette: { primary: { main: '#6366f1' } }, shape: { borderRadius: 12 } }`. See [MUI theme](#mui-theme). |
+| `disableMuiTheme` | boolean | When `true`, the provider skips its inner `<ThemeProvider>` entirely — use this if the host app already wraps everything in its own MUI ThemeProvider and wants it to apply inside the builder pages without merging. Default `false`. |
 | `navExtensions` | array | Static nav items to inject into the sidebar |
 | `endpoints` | object | Full-URL overrides per endpoint group + name |
 
@@ -382,6 +414,83 @@ The hook falls back to `DEFAULT_AG_THEME` when called outside `RoboByteFrontBuil
 
 ---
 
+## MUI theme
+
+Every Material-UI component the package renders (`Button`, `TextField`, `Dialog`, `Tooltip`, `Chip`, `Card`, `Tabs`, …) reads its theme from a single MUI `<ThemeProvider>` mounted by `RoboByteFrontBuilderProvider`. The default theme lives at [`src/lib/muiTheme.js`](src/lib/muiTheme.js) and is designed to look distinctly *not* like stock MUI — Inter typography, 8px radius, soft shadows, flat buttons, no ripple, faster tooltips, dark mode pair.
+
+### Key default tokens
+
+| Token | Value | Rationale |
+|---|---|---|
+| `typography.fontFamily` | `Inter, SF Pro Display, system-ui, …` | Modern UI font with graceful system fallbacks. |
+| `shape.borderRadius` | `8` | Soft corners across the surface (vs MUI's default 4). |
+| `palette.primary.main` | `#3b82f6` | Tailwind blue-500, professional neutral primary. |
+| `palette.secondary.main` | `#FF1185` | Matches `DEFAULT_AG_THEME_PARAMS.accentColor` — brand color shared with AG Grid surfaces. |
+| `shadows[1..8]` | soft, large-radius | Tailwind-like elevation instead of Material's hard shadows. |
+| `MuiButton.disableElevation` | `true` | Flat buttons by default. |
+| `MuiButton.disableRipple` | `true` | Desktop-first. |
+| `MuiTextField.size` | `'small'` | Builder UI is data-dense. |
+| `MuiTooltip.arrow` / `enterDelay` | `true` / `200ms` | Less hover-spam, more obvious anchoring. |
+
+### Host-app override via the provider
+
+```jsx
+<RoboByteFrontBuilderProvider
+  muiTheme={{
+    palette: {
+      primary: { main: '#6366f1' },     // indigo-500
+    },
+    shape: { borderRadius: 12 },
+    typography: { fontFamily: '"Plus Jakarta Sans", sans-serif' },
+  }}
+>
+  <App />
+</RoboByteFrontBuilderProvider>
+```
+
+The override is deep-merged on top of the package defaults — keys you set win, everything else falls back.
+
+### Three ways to pass `muiTheme`
+
+| Pass | What happens |
+|---|---|
+| Nothing | Uses `DEFAULT_MUI_THEME`. |
+| Theme **options** object (`{ palette, shape, typography, components, … }`) | Deep-merged with defaults; package builds the final `Theme`. |
+| A pre-built MUI `Theme` (from your own `createTheme`) | Used as-is. Escape hatch for full control. |
+
+### Disable the inner ThemeProvider
+
+If the host has its own `<ThemeProvider>` wrapping the entire app and wants it to apply inside the builder pages without merging, pass `disableMuiTheme={true}`:
+
+```jsx
+<ThemeProvider theme={yourGlobalTheme}>
+  <RoboByteFrontBuilderProvider disableMuiTheme>
+    <App />
+  </RoboByteFrontBuilderProvider>
+</ThemeProvider>
+```
+
+### Programmatic use
+
+```js
+import {
+  DEFAULT_MUI_THEME_OPTIONS,   // raw default options (frozen)
+  DARK_MUI_THEME_OPTIONS,      // dark counterpart
+  DEFAULT_MUI_THEME,           // pre-built light Theme
+  DEFAULT_MUI_THEME_DARK,      // pre-built dark Theme
+  buildMuiTheme,               // (overrides, { mode? }) => Theme
+  isResolvedMuiTheme,          // (value) => boolean — detect options vs Theme
+} from 'robobyte-front-builder'
+```
+
+### Coordinating with AG Grid + brand identity
+
+The MUI `palette.secondary.main` (`#FF1185`) and the AG Grid `accentColor` are intentionally the same string. Change one, change the other, or wait for the future unified `theme` prop that will derive both from a shared token bag.
+
+> **Future plan.** A single unified `theme` prop will derive MUI, AG Grid, and chart themes from one set of design tokens. Until then, `muiTheme` and `agGridTheme` are the two sources to coordinate.
+
+---
+
 ## `fetchReportDataByPageId`
 
 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.
@@ -996,4 +1105,40 @@ npm publish --dry-run
 
 ---
 
+## License & third-party components
+
+`robobyte-front-builder` itself is released under the **[MIT License](./LICENSE)** — the source code in this repository is free to use, modify, and distribute, including in commercial products.
+
+> **Important:** this package depends on third-party libraries with their own licenses. The MIT license applies only to *this* package's source code; it does not relicense or waive obligations under those third-party licenses.
+
+### AG Grid Enterprise — commercial license required for production
+
+The report and grid components use AG Grid Enterprise features (server-side row model, side tool panel, status bar, integrated charts, master/detail). The `ag-grid-enterprise` package is a **commercial product** owned by AG Grid Ltd:
+
+- **Development:** AG Grid Enterprise works without a license key, but renders a watermark and prints a console warning. Fine for local dev and evaluation.
+- **Production deployment:** requires a paid AG Grid Enterprise license. See [ag-grid.com/license-pricing](https://www.ag-grid.com/license-pricing/) for the current terms.
+
+Pass your license key via the provider — the package calls `LicenseManager.setLicenseKey()` and registers `AllEnterpriseModule` + `IntegratedChartsModule.with(AgChartsEnterpriseModule)` internally:
+
+```jsx
+<RoboByteFrontBuilderProvider
+  agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+  // …other props…
+>
+  …
+</RoboByteFrontBuilderProvider>
+```
+
+### MUI X — free vs. Pro / Premium tiers
+
+`@mui/x-data-grid`, `@mui/x-date-pickers`, and related packages have a free MIT tier and paid Pro / Premium tiers. This package uses only the free tier. If you swap in `@mui/x-data-grid-pro` or `@mui/x-date-pickers-pro` in your host app, comply with MUI's commercial license: [mui.com/pricing](https://mui.com/pricing/).
+
+### Everything else
+
+All other runtime and peer dependencies are open-source under permissive licenses (MIT, Apache 2.0, ISC, BSD). Run `npm ls --omit dev` for the full dependency graph and a tool like `license-checker` for a license enumeration.
+
+A condensed version of this notice lives in the [`LICENSE`](./LICENSE) file shipped with the package.
+
+---
+
 *Full user manual: [RoboByteBuilder_User_Manual.docx](./RoboByteBuilder_User_Manual.docx) (included in the package)*