robobyte-front-builder 1.0.19 → 1.0.21

package/README.md

@@ -0,0 +1,211 @@
+# robobyte-front-builder
+
+A low-code UI builder, Report builder, Print Layout designer, and Navigation extension system for Next.js applications.
+
+[![npm version](https://img.shields.io/npm/v/robobyte-front-builder)](https://www.npmjs.com/package/robobyte-front-builder)
+
+---
+
+## What's included
+
+- **UI Builder** — drag-and-drop canvas for building data-driven views with 50+ components
+- **Report Builder** — design and preview paginated reports
+- **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
+- **Navigation Extension API** — inject nav items from the host app without forking the package
+- **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
+
+---
+
+## Requirements
+
+| Dependency | Version |
+|---|---|
+| Node.js | ≥ 18 |
+| React / React DOM | ≥ 18 |
+| Next.js | ≥ 13 |
+| @mui/material | ≥ 7 |
+| AG Grid | ≥ 33 |
+
+---
+
+## Installation
+
+```bash
+npm install robobyte-front-builder
+```
+
+### Required peer dependencies
+
+These must be installed in the **host app** (they must be shared as a single instance):
+
+```bash
+npm install \
+  react react-dom next \
+  @mui/material @mui/icons-material @mui/lab @mui/system \
+  @mui/x-data-grid @mui/x-date-pickers @mui/x-internals @mui/x-virtualizer \
+  @emotion/react @emotion/styled \
+  ag-grid-community ag-grid-enterprise ag-grid-react \
+  xlsx react-hot-toast
+```
+
+> Everything else (`dayjs`, `lodash`, `recharts`, etc.) ships inside the package and does not need to be installed in the host app.
+
+---
+
+## Setup
+
+### 1. next.config.js
+
+Add the package to `transpilePackages` so Next.js compiles the source-first package:
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['robobyte-front-builder'],
+}
+
+module.exports = nextConfig
+```
+
+### 2. Wrap your app
+
+In `pages/_app.js`, wrap your tree with the provider:
+
+```jsx
+import { RoboByteFrontBuilderProvider } from 'robobyte-front-builder'
+
+export default function App({ Component, pageProps }) {
+  return (
+    <RoboByteFrontBuilderProvider
+      baseURL="https://your-api.example.com"
+      apiURL="https://your-api.example.com/api"
+      getAccessToken={() => yourAuthModule.getToken()}
+      getUser={() => yourAuthModule.getCurrentUser()}
+    >
+      <Component {...pageProps} />
+    </RoboByteFrontBuilderProvider>
+  )
+}
+```
+
+### 3. Add pages
+
+Create page files in your host app that re-export the 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
+```
+
+| Host page path | Export to use |
+|---|---|
+| `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` |
+
+---
+
+## Navigation Extension API
+
+Inject nav items into the builder's sidebar from anywhere in the host app without touching this package:
+
+```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,
+  })
+
+  return <div>...</div>
+}
+```
+
+---
+
+## RoboByteFrontBuilderProvider props
+
+| 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 |
+
+---
+
+## Advanced: accessing builder context
+
+For host apps that need to read or drive builder state programmatically:
+
+```js
+import { useBuilder } from 'robobyte-front-builder'
+
+const { schema, dispatch } = useBuilder()
+```
+
+---
+
+## Local development
+
+To link the package locally without publishing:
+
+```json
+// host app package.json
+"robobyte-front-builder": "file:../../RoboByteFrontBuilder"
+```
+
+Run `npm install` once, then Next.js hot-reload picks up changes automatically.
+
+---
+
+## 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 publish
+```
+
+---
+
+## Changelog
+
+### 1.0.21
+- Added Timer Engine — configurable auto-refresh timers per view (interval, cron, manual trigger)
+- 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
+
+### 1.0.20
+- KPI components: Metric, Trend, Badge, StatusDot, IconBox, Sparkline, MiniBarChart, Donut, Funnel, HeatmapGrid, TagList, Timeline, ComparisonBars
+- Threshold engine and number formatting utilities
+- Dark / light theme toggle in UI builder and Print Layout builder
+
+### 1.0.x
+- UI Builder, Report Builder, Navigator Builder, Print Builder initial releases
+- Navigation Extension API
+- AG Grid and MUI data grid integration
+- Drag-and-drop canvas with 50+ components

package/next.config.js

@@ -1,33 +1,36 @@
 const path = require('path');
-const withTM = require('next-transpile-modules')([
-  '@fullcalendar/common',
-  '@fullcalendar/react',
-  '@fullcalendar/daygrid',
-  '@fullcalendar/list',
-  '@fullcalendar/timegrid',
-  '@mui/x-data-grid',
-  '@mui/material',
-  '@mui/utils',
-  'suneditor',
-  'suneditor-react',
-]);
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  // Next.js 13+ has built-in transpilePackages — no need for next-transpile-modules
+  transpilePackages: [
+    '@mui/x-data-grid',
+    '@mui/material',
+    '@mui/utils',
+    'suneditor',
+    'suneditor-react',
+  ],
   trailingSlash: true,
   reactStrictMode: false,
   eslint: {
     ignoreDuringBuilds: true,
   },
   async rewrites() {
-    // Dynamic rewrites for friendly URLs - handled by [slug].js
-    // This allows /reports to internally route to /viewer/22
     return []
   },
   webpack: (config) => {
+    const src = path.resolve(__dirname, 'src');
+
+    // Resolve bare imports (pages/*, services/*, views/*, context/*, src/*)
+    // to the local src/ directory — same as the host app would do via
+    // NormalModuleReplacementPlugin, but simpler for standalone dev mode.
     config.resolve.alias = {
       ...config.resolve.alias,
-      apexcharts: path.resolve(__dirname, './node_modules/apexcharts-clevision'),
+      pages:   path.join(src, 'pages'),
+      services: path.join(src, 'services'),
+      views:   path.join(src, 'views'),
+      context: path.join(src, 'context'),
+      src:     src,
     };
 
     config.module.rules.push({
@@ -40,36 +43,4 @@ const nextConfig = {
   },
 };
 
-module.exports = withTM(nextConfig);
-
-
-
-
-
-// const path = require('path');
-// const withTM = require('next-transpile-modules')([
-//   '@fullcalendar/common',
-//   '@fullcalendar/react',
-//   '@fullcalendar/daygrid',
-//   '@fullcalendar/list',
-//   '@fullcalendar/timegrid',
-//   '@mui/x-data-grid',
-// ]);
-
-// /** @type {import('next').NextConfig} */
-// const nextConfig = {
-//   trailingSlash: true,
-//   reactStrictMode: false,
-//   eslint: {
-//     ignoreDuringBuilds: true,
-//   },
-//   webpack: config => {
-//     config.resolve.alias = {
-//       ...config.resolve.alias,
-//       apexcharts: path.resolve(__dirname, './node_modules/apexcharts-clevision'),
-//     };
-//     return config;
-//   },
-// };
-
-// module.exports = withTM(nextConfig);
+module.exports = nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robobyte-front-builder",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "RoboByte low-code UI builder, Report builder, and navigation extension system",
   "main": "src/lib/index.js",
   "files": [
@@ -21,133 +21,87 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "export": "next export",
     "lint": "eslint --fix \"src/**/*.{js,jsx}\"",
     "format": "prettier --write \"src/**/*.{js,jsx}\"",
-    "prepublishOnly": "echo 'Publishing @robobyte/front-builder — source-first package, no build step required'"
+    "prepublishOnly": "echo 'Publishing robobyte-front-builder — source-first package, no build step required'"
   },
   "peerDependencies": {
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@mui/icons-material": "^7",
+    "@mui/lab": "^7",
+    "@mui/material": "^7",
+    "@mui/system": "^7",
+    "@mui/x-data-grid": "^7",
+    "@mui/x-date-pickers": "^7",
+    "@mui/x-internals": "^7",
+    "@mui/x-virtualizer": "^7",
+    "ag-grid-community": "^33",
+    "ag-grid-enterprise": "^33",
+    "ag-grid-react": "^33",
+    "next": ">=13",
     "react": ">=18",
     "react-dom": ">=18",
-    "next": ">=13",
-    "@mui/material": ">=7",
-    "@mui/icons-material": ">=7",
-    "@mui/lab": ">=7",
-    "@mui/system": ">=7",
-    "@mui/x-data-grid": ">=7",
-    "@mui/x-date-pickers": ">=7",
-    "@mui/x-tree-view": ">=7",
-    "@emotion/cache": ">=11",
-    "@emotion/react": ">=11",
-    "@emotion/server": ">=11",
-    "@emotion/styled": ">=11",
-    "axios": ">=1"
+    "xlsx": ">=0.18",
+    "react-hot-toast": ">=2"
   },
   "dependencies": {
-    "@auth0/auth0-react": "2.1.0",
-    "@aws-amplify/auth": "5.3.6",
-    "@aws-amplify/ui-react": "4.6.3",
-    "@babel/eslint-parser": "7.21.8",
-    "@casl/ability": "6.5.0",
-    "@casl/react": "3.1.0",
-    "@date-io/date-fns": "^2.16.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@fullcalendar/common": "5.11.5",
-    "@fullcalendar/core": "6.1.7",
-    "@fullcalendar/daygrid": "6.1.7",
-    "@fullcalendar/interaction": "6.1.7",
-    "@fullcalendar/list": "6.1.7",
-    "@fullcalendar/react": "6.1.7",
-    "@fullcalendar/timegrid": "6.1.7",
     "@hookform/resolvers": "3.1.0",
-    "@microsoft/signalr": "^8.0.0",
     "@monaco-editor/react": "^4.7.0",
-    "@popperjs/core": "2.11.7",
     "@react-google-maps/api": "^2.19.2",
-    "@reduxjs/toolkit": "1.9.5",
-    "@unicef/material-ui-currency-textfield": "^0.8.6",
-    "ag-grid-community": "^33.3.2",
-    "ag-grid-enterprise": "^33.3.2",
-    "ag-grid-react": "^33.3.2",
-    "apexcharts-clevision": "3.28.5",
-    "aws-amplify": "^5.3.13",
-    "axios-mock-adapter": "1.21.4",
-    "babel-eslint": "10.1.0",
-    "chart.js": "4.3.0",
+    "axios": "^1.6.0",
     "classnames": "2.5.1",
-    "cleave.js": "1.6.0",
-    "clipboard-copy": "4.0.1",
-    "clsx": "1.2.1",
-    "date-fns": "^2.30.0",
     "dayjs": "^1.11.9",
     "draft-js": "0.11.7",
-    "firebase": "9.22.0",
-    "hls.js": "^1.0.3-0.canary.7275",
-    "https": "^1.0.0",
-    "i18next": "22.5.0",
-    "i18next-browser-languagedetector": "7.0.1",
-    "i18next-http-backend": "2.2.1",
-    "jsonwebtoken": "9.0.0",
     "jspdf": "^3.0.3",
-    "jspdf-autotable": "^5.0.2",
-    "jwt-decode": "^4.0.0",
-    "keen-slider": "6.8.5",
+    "jspdf-autotable": "^5.0.7",
     "list": "^2.0.19",
+    "lodash": "^4.17.21",
     "mdi-material-ui": "7.7.0",
     "moment": "^2.30.1",
     "moment-timezone": "^0.5.47",
-    "notistack": "^3.0.2",
-    "nprogress": "0.2.0",
     "numeral": "^2.0.6",
-    "payment": "2.4.6",
-    "prismjs": "1.29.0",
-    "prop-types": "^15.8.1",
-    "react-apexcharts": "1.4.0",
     "react-beautiful-dnd": "13.1.1",
-    "react-chartjs-2": "5.2.0",
-    "react-colorful": "^5.6.1",
-    "react-credit-cards": "0.8.3",
     "react-datepicker": "4.11.0",
-    "react-draft-wysiwyg": "1.15.0",
-    "react-dropzone": "14.2.3",
     "react-hook-form": "7.43.9",
-    "react-hot-toast": "2.4.1",
-    "react-i18next": "12.3.1",
-    "react-multi-date-picker": "^4.5.2",
     "react-number-format": "^5.4.0",
     "react-perfect-scrollbar": "1.5.8",
-    "react-popper": "2.3.0",
-    "react-quill": "^2.0.0",
-    "react-redux": "8.0.5",
     "react-signature-canvas": "^1.1.0-alpha.2",
-    "react-to-pdf": "0.0.14",
     "react-use": "^17.6.0",
-    "react-viewer": "^3.2.2",
     "recharts": "2.6.2",
-    "rsuite": "^5.60.1",
-    "sass": "^1.77.8",
-    "styled-components": "^6.1.10",
-    "stylelint": "16.6.1",
-    "stylis": "4.2.0",
-    "stylis-plugin-rtl": "2.1.1",
     "suneditor": "^2.47.5",
     "suneditor-react": "^3.6.1",
-    "sweetalert2": "^11.17.2",
-    "swiper": "^11.2.5",
     "uuid": "^11.1.0",
+    "xlsx": "^0.18.5",
     "yup": "1.1.1"
   },
   "devDependencies": {
     "@babel/core": "^7.22.0",
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@mui/icons-material": "^7",
+    "@mui/lab": "^7",
+    "@mui/material": "^7",
+    "@mui/system": "^7",
+    "@mui/x-data-grid": "^7",
+    "@mui/x-date-pickers": "^7",
+    "ag-charts-enterprise": "latest",
+    "ag-grid-community": "^33",
+    "ag-grid-enterprise": "^33",
+    "ag-grid-react": "^33",
     "eslint": "8.41.0",
     "eslint-config-next": "13.4.3",
     "eslint-config-prettier": "8.8.0",
     "eslint-import-resolver-alias": "1.1.2",
     "eslint-import-resolver-typescript": "3.5.5",
     "eslint-plugin-import": "2.27.5",
-    "next-transpile-modules": "^10.0.0",
-    "prettier": "2.8.8"
+    "next": "^13",
+    "next-transpile-modules": "^9",
+    "prettier": "2.8.8",
+    "react": "^18",
+    "react-dom": "^18"
   }
 }

package/src/context/BuilderContext.jsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, useEffect, useState } from 'react'
+import { createContext, useCallback, useContext, useEffect, useReducer, useRef, useState } from 'react'
 import { executeActionsByEvent } from 'services/builderHelper/actionExecutor'
 import { findNode } from 'services/builderHelper'
 import { executeJSCode } from 'services/builderHelper/jsExecutor'
@@ -88,11 +88,74 @@ const initialSchema = {
     className: '',
     children: []
   },
-  actions: []
+  dialogs: [],
+  actions: [],
+  timers: []
+}
+
+// ── History reducer (undo / redo) ─────────────────────────────────────────────
+//
+//  State shape:  { past: Schema[], present: Schema, future: Schema[] }
+//
+//  SET   — normal edit: discard redo stack, push present → past, apply new state
+//  UNDO  — move one step back in history
+//  REDO  — move one step forward in history
+//
+//  History is capped at 100 entries per direction to bound memory usage.
+//
+const HISTORY_LIMIT = 100
+
+function historyReducer(state, action) {
+  switch (action.type) {
+    case 'SET': {
+      const next = typeof action.payload === 'function'
+        ? action.payload(state.present)
+        : action.payload
+      if (next === state.present) return state
+      return {
+        past:    [...state.past, state.present].slice(-HISTORY_LIMIT),
+        present: next,
+        future:  []
+      }
+    }
+    case 'UNDO': {
+      if (state.past.length === 0) return state
+      const prev = state.past[state.past.length - 1]
+      return {
+        past:    state.past.slice(0, -1),
+        present: prev,
+        future:  [state.present, ...state.future].slice(0, HISTORY_LIMIT)
+      }
+    }
+    case 'REDO': {
+      if (state.future.length === 0) return state
+      const next = state.future[0]
+      return {
+        past:    [...state.past, state.present].slice(-HISTORY_LIMIT),
+        present: next,
+        future:  state.future.slice(1)
+      }
+    }
+    default:
+      return state
+  }
 }
 
 export function BuilderProvider({ children }) {
-  const [schema, setSchema] = useState(initialSchema)
+  const [historyState, dispatch] = useReducer(historyReducer, {
+    past:    [],
+    present: initialSchema,
+    future:  []
+  })
+
+  // Convenience aliases — schema reads the present snapshot;
+  // setSchema dispatches a SET action (automatically tracked in history).
+  const schema    = historyState.present
+  const setSchema = useCallback((updater) => dispatch({ type: 'SET', payload: updater }), [])
+  const undo      = useCallback(() => dispatch({ type: 'UNDO' }), [])
+  const redo      = useCallback(() => dispatch({ type: 'REDO' }), [])
+  const canUndo   = historyState.past.length > 0
+  const canRedo   = historyState.future.length > 0
   const [selectedId, setSelectedId] = useState(null)
   const [viewMetaData, setViewMetaData] = useState({
     id: null,
@@ -105,7 +168,7 @@ export function BuilderProvider({ children }) {
   })
 
   // ✅ NEW: editor mode
-  const [mode, setMode] = useState('edit') // 'edit' | 'preview'
+  const [mode, setMode] = useState('edit') // 'edit' | 'preview' | 'print'
 
   // ✅ NEW: global data object for action results
   const [data, setData] = useState({})
@@ -116,6 +179,39 @@ export function BuilderProvider({ children }) {
   // ✅ NEW: validation errors
   const [validationErrors, setValidationErrors] = useState({})
   const [draggingNodeId, setDraggingNodeId] = useState(null)
+  const [clipboard, setClipboard] = useState(null)  // copy/paste clipboard
+
+  // ── Unified ref storage ────────────────────────────────────────────────────
+  // dataRef    : mutable non-reactive store; read/write from any function
+  //              without triggering re-renders. Access via dataRef.current.
+  // reportRefs : registry of { [nodeId]: updateRef } for every ReportViewer.
+  //              Each report registers itself; access from JS functions via
+  //              reportRefs['nodeId'].current (the updateRef array).
+  const dataRef       = useRef({})
+  const reportRefs    = useRef({})
+  const dialogRefs    = useRef({})
+  const printDialogRef = useRef(null) // { open: (data?) => void, close: () => void }
+
+  const openDialog = useCallback((key, data) => {
+    const ref = dialogRefs.current[key]
+    if (ref) ref.open(data)
+    else console.warn(`[openDialog] No dialog registered with key "${key}"`)
+  }, [])
+
+  const closeDialog = useCallback((key) => {
+    const ref = dialogRefs.current[key]
+    if (ref) ref.close()
+    else console.warn(`[closeDialog] No dialog registered with key "${key}"`)
+  }, [])
+
+  const openPrintLayout = useCallback((data) => {
+    if (printDialogRef.current) printDialogRef.current.open(data)
+    else console.warn('[openPrintLayout] PrintDialog is not mounted')
+  }, [])
+
+  const closePrintLayout = useCallback(() => {
+    if (printDialogRef.current) printDialogRef.current.close()
+  }, [])
 
   useEffect(() => {
     console.log('BUILDER SCHEMA:', schema)
@@ -131,7 +227,10 @@ export function BuilderProvider({ children }) {
 
       // Execute onLoad actions with fresh context
       if (schema.actions && schema.actions.length > 0) {
-        executeActionsByEvent(schema.actions, 'onLoad', { form: {}, data: {} }, setData).catch(err => {
+        executeActionsByEvent(schema.actions, 'onLoad', {
+          form: {}, data: {}, setData,
+          dataRef: dataRef.current, reportRefs: reportRefs.current,
+        }).catch(err => {
           console.error('onLoad actions error:', err)
         })
       }
@@ -154,7 +253,10 @@ export function BuilderProvider({ children }) {
 
     // If validation passes, execute onSubmit actions
     if (Object.keys(errors).length === 0) {
-      await executeActionsByEvent(schema.actions, 'onSubmit', { form, data }, setData)
+      await executeActionsByEvent(schema.actions, 'onSubmit', {
+        form, data, setData,
+        dataRef: dataRef.current, reportRefs: reportRefs.current,
+      })
       return true
     }
     return false
@@ -172,6 +274,12 @@ export function BuilderProvider({ children }) {
         schema,
         setSchema,
 
+        // ── Undo / redo ──────────────────────────────────────────────────────
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+
         viewMetaData,
         setViewMetaData,
 
@@ -181,6 +289,12 @@ export function BuilderProvider({ children }) {
         draggingNodeId,
         setDraggingNodeId,
 
+        // ── Copy/paste clipboard ─────────────────────────────────────────────
+        // clipboard — the last copied node (plain object, not cloned yet)
+        // setClipboard — store a node reference for later paste
+        clipboard,
+        setClipboard,
+
         // ✅ mode API
         mode,
         setMode,
@@ -191,6 +305,20 @@ export function BuilderProvider({ children }) {
         data,
         setData,
 
+        // ── Unified ref storage ──────────────────────────────────────────────
+        // dataRef       — mutable non-reactive store (useRef({})); mutate via dataRef.current
+        // reportRefs    — registry of { [nodeId]: updateRef } for all ReportViewers
+        // dialogRefs    — registry of { [key]: { open, close } } for all Dialogs
+        // printDialogRef — ref to the single PrintDialog { open, close }
+        dataRef,
+        reportRefs,
+        dialogRefs,
+        openDialog,
+        closeDialog,
+        printDialogRef,
+        openPrintLayout,
+        closePrintLayout,
+
         // ✅ form state and handlers
         form,
         setForm,