robobyte-front-builder 1.0.27 → 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/README.md

@@ -39,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)
 
 ---
 
@@ -198,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>
@@ -344,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 |
 
@@ -403,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robobyte-front-builder",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "RoboByte low-code UI builder, Report builder, and navigation extension system",
   "keywords": [
     "low-code",

package/src/lib/index.js

@@ -113,3 +113,17 @@ export { default as fetchReportDataByPageId } from '../services/reportData/fetch
 // every internal grid uses to read the live theme.
 export { DEFAULT_AG_THEME_PARAMS, buildAgGridTheme, DEFAULT_AG_THEME } from './agGridTheme'
 export { AgGridThemeProvider, useAgGridTheme } from './agGridThemeContext'
+
+// ── MUI theme ────────────────────────────────────────────────────────────────
+// Default MUI theme options + a builder. Host apps override via the
+// `muiTheme` prop on RoboByteFrontBuilderProvider; deep-merged with defaults.
+// Tokens are coordinated with DEFAULT_AG_THEME_PARAMS so brand colors stay
+// in sync between MUI surfaces and AG Grid surfaces — see lib/muiTheme.js.
+export {
+  DEFAULT_MUI_THEME_OPTIONS,
+  DARK_MUI_THEME_OPTIONS,
+  DEFAULT_MUI_THEME,
+  DEFAULT_MUI_THEME_DARK,
+  buildMuiTheme,
+  isResolvedMuiTheme,
+} from './muiTheme'

package/src/lib/muiTheme.js

@@ -0,0 +1,655 @@
+/**
+ * Centralized MUI theme configuration.
+ *
+ * Every `<RoboByteFrontBuilderProvider>` wraps its children in a MUI
+ * ThemeProvider built from these defaults. Host apps can override any token
+ * by passing the `muiTheme` prop:
+ *
+ *   <RoboByteFrontBuilderProvider
+ *     muiTheme={{
+ *       palette: { primary: { main: '#6366f1' } },
+ *       shape:   { borderRadius: 12 },
+ *     }}
+ *   />
+ *
+ * The override object is deep-merged on top of DEFAULT_MUI_THEME_OPTIONS —
+ * keys you set win, everything else falls back to the package defaults.
+ *
+ * Default identity (in plain English):
+ *   - Inter font family (with sensible system fallbacks).
+ *   - 8px border-radius across the surface.
+ *   - Soft layered shadows (Tailwind-style, not Material elevation).
+ *   - Flat buttons (no ripple, no elevation) with cleaner hover states.
+ *   - Outlined text fields with rounded corners, default size 'small'.
+ *   - Tooltips: dark, arrowed, faster open delay.
+ *   - Compact tabs / chips / icon buttons matching the buttons' radius.
+ *   - Light & dark palette pair, both designed in true greys (not blue-tinted).
+ *
+ * Future: a single unified `theme` prop will derive MUI, AG Grid, and chart
+ * themes from a shared token bag. Until then, this file plus `agGridTheme.js`
+ * are the two sources to coordinate when changing brand colors.
+ */
+
+import { createTheme, alpha } from '@mui/material/styles'
+import merge from 'lodash/merge'
+
+// ── Brand tokens ─────────────────────────────────────────────────────────────
+// Keep COLORS coordinated with DEFAULT_AG_THEME_PARAMS in agGridTheme.js so a
+// brand-color change in one place doesn't desync the report grids.
+
+const COLORS = {
+  primary: {
+    main:         '#3b82f6',   // blue-500
+    light:        '#60a5fa',
+    dark:         '#2563eb',
+    contrastText: '#ffffff',
+  },
+  secondary: {
+    main:         '#FF1185',   // matches DEFAULT_AG_THEME_PARAMS.accentColor
+    light:        '#ff4ea0',
+    dark:         '#d10b6e',
+    contrastText: '#ffffff',
+  },
+  success: {
+    main:         '#10b981',
+    light:        '#34d399',
+    dark:         '#059669',
+    contrastText: '#ffffff',
+  },
+  warning: {
+    main:         '#f59e0b',
+    light:        '#fbbf24',
+    dark:         '#d97706',
+    contrastText: '#ffffff',
+  },
+  error: {
+    main:         '#ef4444',
+    light:        '#f87171',
+    dark:         '#dc2626',
+    contrastText: '#ffffff',
+  },
+  info: {
+    main:         '#0ea5e9',
+    light:        '#38bdf8',
+    dark:         '#0284c7',
+    contrastText: '#ffffff',
+  },
+}
+
+const LIGHT_PALETTE = {
+  mode: 'light',
+  ...COLORS,
+  background: { default: '#fafafa', paper: '#ffffff' },
+  text: {
+    primary:   '#0f172a',
+    secondary: '#475569',
+    disabled:  '#94a3b8',
+  },
+  divider: 'rgba(15, 23, 42, 0.08)',
+  action: {
+    hover:               'rgba(15, 23, 42, 0.04)',
+    selected:            'rgba(15, 23, 42, 0.08)',
+    selectedOpacity:     0.08,
+    disabled:            'rgba(15, 23, 42, 0.30)',
+    disabledBackground:  'rgba(15, 23, 42, 0.06)',
+    focus:               'rgba(15, 23, 42, 0.10)',
+  },
+  // Internal helpers used by component overrides — kept off-spec on `palette`
+  // so they don't collide with MUI's color augmentation. Read them via
+  // theme.palette.rbb.X inside styleOverride callbacks.
+  rbb: {
+    inputBackground:     '#ffffff',
+    inputBackgroundHover:'#fafafa',
+    focusRingColor:      'rgba(59, 130, 246, 0.20)',    // primary @ 20% — soft halo
+    focusRingError:      'rgba(239, 68, 68, 0.20)',
+    surface1:            '#f8fafc',                      // subtle surface tint
+  },
+}
+
+const DARK_PALETTE = {
+  mode: 'dark',
+  ...COLORS,
+  background: { default: '#0a0a0a', paper: '#171717' },
+  text: {
+    primary:   '#fafafa',
+    secondary: '#a1a1aa',
+    disabled:  '#52525b',
+  },
+  divider: 'rgba(250, 250, 250, 0.08)',
+  action: {
+    hover:               'rgba(250, 250, 250, 0.06)',
+    selected:            'rgba(250, 250, 250, 0.10)',
+    selectedOpacity:     0.10,
+    disabled:            'rgba(250, 250, 250, 0.30)',
+    disabledBackground:  'rgba(250, 250, 250, 0.06)',
+    focus:               'rgba(250, 250, 250, 0.12)',
+  },
+  rbb: {
+    inputBackground:     '#0f0f0f',
+    inputBackgroundHover:'#171717',
+    focusRingColor:      'rgba(96, 165, 250, 0.25)',    // primary-light @ 25%
+    focusRingError:      'rgba(248, 113, 113, 0.25)',
+    surface1:            '#0f0f0f',
+  },
+}
+
+// ── Typography ───────────────────────────────────────────────────────────────
+// The font stack falls back gracefully if the host hasn't loaded Inter.
+// Hosts can add `import { Inter } from 'next/font/google'` for the real thing.
+
+const FONT_FAMILY = [
+  '"Inter"',
+  '"SF Pro Display"',
+  '-apple-system',
+  'BlinkMacSystemFont',
+  '"Segoe UI"',
+  'Roboto',
+  '"Helvetica Neue"',
+  'Arial',
+  'sans-serif',
+].join(',')
+
+const TYPOGRAPHY = {
+  fontFamily: FONT_FAMILY,
+  fontSize:   14,
+  // Headings use slightly tighter tracking and bolder weight than MUI default.
+  h1:         { fontWeight: 700, letterSpacing: '-0.02em', lineHeight: 1.2 },
+  h2:         { fontWeight: 700, letterSpacing: '-0.02em', lineHeight: 1.25 },
+  h3:         { fontWeight: 600, letterSpacing: '-0.015em', lineHeight: 1.3 },
+  h4:         { fontWeight: 600, letterSpacing: '-0.01em',  lineHeight: 1.35 },
+  h5:         { fontWeight: 600, lineHeight: 1.4 },
+  h6:         { fontWeight: 600, lineHeight: 1.4 },
+  subtitle1:  { fontWeight: 500 },
+  subtitle2:  { fontWeight: 500 },
+  body1:      { lineHeight: 1.5 },
+  body2:      { lineHeight: 1.5 },
+  button:     { fontWeight: 500, textTransform: 'none', letterSpacing: 0 },
+  caption:    { letterSpacing: '0.01em' },
+  overline:   { fontWeight: 600, letterSpacing: '0.08em' },
+}
+
+// ── Shadows ──────────────────────────────────────────────────────────────────
+// 25-step elevation ladder. Softer and more spread than MUI defaults so
+// surfaces float subtly without that "drawn shadow" look. Steps 0-6 are the
+// commonly-used ones; 7-24 are reserved for very-elevated surfaces (drag
+// previews, drawers, etc.) — kept distinct but capped to avoid heaviness.
+
+const SOFT_SHADOWS = [
+  'none',
+  '0 1px 2px 0 rgba(15, 23, 42, 0.04)',
+  '0 1px 3px 0 rgba(15, 23, 42, 0.06), 0 1px 2px -1px rgba(15, 23, 42, 0.06)',
+  '0 4px 6px -1px rgba(15, 23, 42, 0.08), 0 2px 4px -2px rgba(15, 23, 42, 0.06)',
+  '0 10px 15px -3px rgba(15, 23, 42, 0.08), 0 4px 6px -4px rgba(15, 23, 42, 0.06)',
+  '0 12px 20px -4px rgba(15, 23, 42, 0.10), 0 6px 8px -4px rgba(15, 23, 42, 0.06)',
+  '0 20px 25px -5px rgba(15, 23, 42, 0.10), 0 8px 10px -6px rgba(15, 23, 42, 0.08)',
+  '0 24px 40px -8px rgba(15, 23, 42, 0.12)',
+  '0 25px 50px -12px rgba(15, 23, 42, 0.15)',
+]
+const HIGH_SHADOW = '0 25px 50px -12px rgba(15, 23, 42, 0.18)'
+const SHADOWS = [
+  ...SOFT_SHADOWS,
+  ...Array(25 - SOFT_SHADOWS.length).fill(HIGH_SHADOW),
+]
+
+// ── Component overrides ──────────────────────────────────────────────────────
+// Each entry either changes defaultProps (e.g. disable ripple) or layers
+// styleOverrides on top of MUI defaults. Keep these minimal and surgical —
+// the goal is "make MUI not look like stock MUI", not "rewrite MUI."
+
+const TRANSITION = 'all 150ms cubic-bezier(0.4, 0, 0.2, 1)'
+
+const COMPONENT_OVERRIDES = {
+  // ── Buttons ──────────────────────────────────────────────────────────────
+  // Flat by default, no ripple. Modern hover + active + focus states. Focus
+  // uses :focus-visible so mouse clicks don't show the keyboard outline.
+  MuiButton: {
+    defaultProps: {
+      disableElevation: true,
+      disableRipple:    true,
+    },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius:  theme.shape.borderRadius,
+        fontWeight:    500,
+        textTransform: 'none',
+        letterSpacing: 0,
+        boxShadow:     'none',
+        transition:    TRANSITION,
+        // Reset MUI's default ripple-based active visual; we use a subtle
+        // scale-down instead — the same micro-interaction Linear/Vercel use.
+        '&:active':    { transform: 'scale(0.98)', boxShadow: 'none' },
+        '&:hover':     { boxShadow: 'none' },
+        // Keyboard-only focus ring: 2px offset, theme-aware color.
+        '&:focus-visible': {
+          outline:        `2px solid ${theme.palette.primary.main}`,
+          outlineOffset:  2,
+        },
+        // Cleaner disabled — 50% opacity, not greyed-out.
+        '&.Mui-disabled': {
+          opacity:    0.5,
+          transform:  'none',
+          boxShadow:  'none',
+        },
+      }),
+      sizeSmall:  { padding: '4px 12px', minHeight: 32, fontSize: 13 },
+      sizeMedium: { padding: '6px 16px', minHeight: 36 },
+      sizeLarge:  { padding: '8px 22px', minHeight: 42 },
+      // Contained: solid background, slight darken on hover (no shadow noise).
+      containedPrimary: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.primary.dark },
+      }),
+      containedSecondary: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.secondary.dark },
+      }),
+      containedSuccess: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.success.dark },
+      }),
+      containedError: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.error.dark },
+      }),
+      containedWarning: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.warning.dark },
+      }),
+      containedInfo: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.info.dark },
+      }),
+      // Outlined: hover deepens the border + adds a soft bg tint.
+      outlined: ({ theme }) => ({
+        borderColor: theme.palette.divider,
+        '&:hover': {
+          backgroundColor: theme.palette.action.hover,
+        },
+      }),
+      outlinedPrimary: ({ theme }) => ({
+        '&:hover': {
+          borderColor:     theme.palette.primary.main,
+          backgroundColor: alpha(theme.palette.primary.main, 0.05),
+        },
+      }),
+      outlinedSecondary: ({ theme }) => ({
+        '&:hover': {
+          borderColor:     theme.palette.secondary.main,
+          backgroundColor: alpha(theme.palette.secondary.main, 0.05),
+        },
+      }),
+      outlinedError: ({ theme }) => ({
+        '&:hover': {
+          borderColor:     theme.palette.error.main,
+          backgroundColor: alpha(theme.palette.error.main, 0.05),
+        },
+      }),
+      // Text: subtle bg tint on hover, no underline.
+      text: ({ theme }) => ({
+        '&:hover': { backgroundColor: theme.palette.action.hover },
+      }),
+      textPrimary: ({ theme }) => ({
+        '&:hover': { backgroundColor: alpha(theme.palette.primary.main, 0.05) },
+      }),
+    },
+  },
+
+  // ── Button group ─────────────────────────────────────────────────────────
+  MuiButtonGroup: {
+    defaultProps: { disableElevation: true, disableRipple: true },
+    styleOverrides: {
+      root:  ({ theme }) => ({ boxShadow: 'none', borderRadius: theme.shape.borderRadius }),
+      grouped: { '&:not(:last-of-type)': { borderRightColor: 'inherit' } },
+    },
+  },
+
+  // ── Toggle buttons ───────────────────────────────────────────────────────
+  MuiToggleButton: {
+    defaultProps: { disableRipple: true },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius:  theme.shape.borderRadius,
+        fontWeight:    500,
+        textTransform: 'none',
+        transition:    TRANSITION,
+        '&.Mui-selected': {
+          backgroundColor: alpha(theme.palette.primary.main, 0.08),
+          color:           theme.palette.primary.main,
+          '&:hover': { backgroundColor: alpha(theme.palette.primary.main, 0.12) },
+        },
+        '&:focus-visible': {
+          outline:        `2px solid ${theme.palette.primary.main}`,
+          outlineOffset:  2,
+        },
+      }),
+    },
+  },
+
+  // ── Icon buttons ─────────────────────────────────────────────────────────
+  // Matches Button's interaction language: same transition, focus ring,
+  // hover bg, scale-on-active.
+  MuiIconButton: {
+    defaultProps: { disableRipple: true },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius: Math.max(theme.shape.borderRadius - 2, 6),
+        transition:   TRANSITION,
+        '&:hover':    { backgroundColor: theme.palette.action.hover },
+        '&:active':   { transform: 'scale(0.94)' },
+        '&:focus-visible': {
+          outline:        `2px solid ${theme.palette.primary.main}`,
+          outlineOffset:  2,
+        },
+        '&.Mui-disabled': { opacity: 0.5 },
+      }),
+    },
+  },
+
+  // ── Floating action button ───────────────────────────────────────────────
+  MuiFab: {
+    defaultProps: { disableRipple: true },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        boxShadow:    theme.shadows[4],
+        transition:   TRANSITION,
+        '&:hover':    { boxShadow: theme.shadows[6] },
+        '&:active':   { transform: 'scale(0.95)' },
+      }),
+    },
+  },
+
+  // ── Text fields & inputs ─────────────────────────────────────────────────
+  // Small + outlined by default. Distinctive but subtle modern focus:
+  //  - resting: 1px divider border, subtle surface tint
+  //  - hover:   border darkens to text.disabled
+  //  - focus:   1px primary border + soft halo shadow (not double-thick border)
+  //  - error:   1px error border + red halo on focus
+  MuiTextField: {
+    defaultProps: { size: 'small', variant: 'outlined' },
+  },
+  MuiOutlinedInput: {
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius:    theme.shape.borderRadius,
+        backgroundColor: theme.palette.rbb?.inputBackground ?? theme.palette.background.paper,
+        transition:      TRANSITION,
+
+        // Resting border
+        '& .MuiOutlinedInput-notchedOutline': {
+          borderColor: theme.palette.divider,
+          transition:  TRANSITION,
+        },
+
+        // Hover: stronger border, subtle bg shift
+        '&:hover': {
+          backgroundColor: theme.palette.rbb?.inputBackgroundHover ?? theme.palette.background.paper,
+        },
+        '&:hover .MuiOutlinedInput-notchedOutline': {
+          borderColor: theme.palette.text.disabled,
+        },
+
+        // Focus: thin primary border + soft halo shadow (Vercel/Linear style)
+        '&.Mui-focused .MuiOutlinedInput-notchedOutline': {
+          borderWidth: 1,
+          borderColor: theme.palette.primary.main,
+        },
+        '&.Mui-focused': {
+          boxShadow: `0 0 0 3px ${theme.palette.rbb?.focusRingColor ?? 'rgba(59, 130, 246, 0.20)'}`,
+        },
+
+        // Error state — red border, red halo on focus
+        '&.Mui-error .MuiOutlinedInput-notchedOutline': {
+          borderColor: theme.palette.error.main,
+        },
+        '&.Mui-error.Mui-focused': {
+          boxShadow: `0 0 0 3px ${theme.palette.rbb?.focusRingError ?? 'rgba(239, 68, 68, 0.20)'}`,
+        },
+
+        // Disabled — soften, don't grey out
+        '&.Mui-disabled': {
+          backgroundColor: theme.palette.action.disabledBackground,
+          opacity:         0.7,
+        },
+      }),
+      input: ({ theme }) => ({
+        '&::placeholder': {
+          color:    theme.palette.text.disabled,
+          opacity:  1,
+        },
+      }),
+    },
+  },
+
+  // ── Filled / standard input variants ─────────────────────────────────────
+  // Same focus halo treatment for consistency, in case consumers pick these.
+  MuiFilledInput: {
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius:    theme.shape.borderRadius,
+        backgroundColor: theme.palette.rbb?.surface1 ?? theme.palette.action.hover,
+        transition:      TRANSITION,
+        '&:before, &:after': { display: 'none' },
+        '&.Mui-focused': {
+          boxShadow:       `0 0 0 3px ${theme.palette.rbb?.focusRingColor ?? 'rgba(59, 130, 246, 0.20)'}`,
+          backgroundColor: theme.palette.background.paper,
+        },
+      }),
+    },
+  },
+
+  // ── Input labels: cleaner sizing ─────────────────────────────────────────
+  MuiInputLabel: {
+    styleOverrides: {
+      root:    { fontSize: 14 },
+      shrink:  { fontWeight: 500 },
+    },
+  },
+
+  // ── Form helper text ─────────────────────────────────────────────────────
+  // No layout shift between empty and filled — reserve the line.
+  MuiFormHelperText: {
+    styleOverrides: {
+      root: { marginLeft: 2, marginTop: 4, fontSize: 12, lineHeight: 1.4 },
+    },
+  },
+
+  // ── Autocomplete: cleaner option list ────────────────────────────────────
+  MuiAutocomplete: {
+    styleOverrides: {
+      paper: ({ theme }) => ({
+        borderRadius: theme.shape.borderRadius,
+        border:       `1px solid ${theme.palette.divider}`,
+        boxShadow:    theme.shadows[4],
+        marginTop:    4,
+      }),
+      option: ({ theme }) => ({
+        borderRadius: Math.max(theme.shape.borderRadius - 4, 4),
+        margin:       '1px 4px',
+        '&[aria-selected="true"]': {
+          backgroundColor: alpha(theme.palette.primary.main, 0.08),
+          color:           theme.palette.primary.main,
+        },
+      }),
+    },
+  },
+
+  // ── Select: align dropdown with outlined input ───────────────────────────
+  MuiSelect: {
+    styleOverrides: {
+      icon: ({ theme }) => ({ color: theme.palette.text.secondary }),
+    },
+  },
+
+  // Chips: smaller radius than the global shape — chips read better as pills.
+  MuiChip: {
+    styleOverrides: {
+      root: { borderRadius: 6, fontWeight: 500 },
+    },
+  },
+
+  // Tooltips: dark, smaller font, faster open. Arrowed by default.
+  MuiTooltip: {
+    defaultProps: {
+      arrow:          true,
+      enterDelay:     200,
+      enterNextDelay: 150,
+      placement:      'top',
+    },
+    styleOverrides: {
+      tooltip: { fontSize: 12, padding: '4px 8px', fontWeight: 500 },
+    },
+  },
+
+  // Cards: flat by default with a hairline border instead of an elevation.
+  MuiCard: {
+    defaultProps: { elevation: 0 },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        border:        '1px solid',
+        borderColor:   theme.palette.divider,
+        borderRadius:  theme.shape.borderRadius * 1.25,
+      }),
+    },
+  },
+
+  // Paper: don't auto-apply elevation — components that want it set it explicitly.
+  MuiPaper: {
+    defaultProps: { elevation: 0 },
+  },
+
+  // Dialogs: slightly larger radius (more "modal-y"), softer shadow.
+  MuiDialog: {
+    styleOverrides: {
+      paper: ({ theme }) => ({
+        borderRadius: theme.shape.borderRadius * 1.5,
+        boxShadow:    theme.shadows[8],
+      }),
+    },
+  },
+
+  // AppBar / Toolbar: flat with hairline divider, theme-paper background.
+  MuiAppBar: {
+    defaultProps: { elevation: 0, color: 'inherit' },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        backgroundColor: theme.palette.background.paper,
+        color:           theme.palette.text.primary,
+        borderBottom:    `1px solid ${theme.palette.divider}`,
+      }),
+    },
+  },
+
+  // Inputs: no ripple on selection controls (desktop-first).
+  MuiCheckbox: { defaultProps: { disableRipple: true } },
+  MuiRadio:    { defaultProps: { disableRipple: true } },
+  MuiSwitch:   { defaultProps: { disableRipple: true } },
+
+  // Tabs: cleaner typography, no uppercase.
+  MuiTab: {
+    styleOverrides: {
+      root: { textTransform: 'none', fontWeight: 500, minHeight: 40 },
+    },
+  },
+  MuiTabs: {
+    styleOverrides: {
+      root: { minHeight: 40 },
+    },
+  },
+
+  // Menus / popovers: subtle border, soft shadow.
+  MuiMenu: {
+    styleOverrides: {
+      paper: ({ theme }) => ({
+        border:       `1px solid ${theme.palette.divider}`,
+        borderRadius: theme.shape.borderRadius,
+        boxShadow:    theme.shadows[4],
+      }),
+    },
+  },
+  MuiPopover: {
+    styleOverrides: {
+      paper: ({ theme }) => ({
+        border:       `1px solid ${theme.palette.divider}`,
+        borderRadius: theme.shape.borderRadius,
+      }),
+    },
+  },
+
+  // Lists & list items: a touch tighter than MUI default.
+  MuiListItemButton: {
+    styleOverrides: {
+      root: ({ theme }) => ({
+        borderRadius: Math.max(theme.shape.borderRadius - 4, 4),
+      }),
+    },
+  },
+
+  // Accordions: flat, hairline separators.
+  MuiAccordion: {
+    defaultProps: { elevation: 0, disableGutters: true },
+    styleOverrides: {
+      root: ({ theme }) => ({
+        border:       `1px solid ${theme.palette.divider}`,
+        borderRadius: theme.shape.borderRadius,
+        '&:before':   { display: 'none' },
+        '&.Mui-expanded': { margin: 0 },
+      }),
+    },
+  },
+}
+
+// ── Shape ────────────────────────────────────────────────────────────────────
+const SHAPE = { borderRadius: 8 }
+
+// ── Public exports ───────────────────────────────────────────────────────────
+
+/**
+ * MUI theme options object — light mode, package defaults.
+ * Pass these (or a deep-merged override) to `createTheme`.
+ */
+export const DEFAULT_MUI_THEME_OPTIONS = Object.freeze({
+  palette:    LIGHT_PALETTE,
+  typography: TYPOGRAPHY,
+  shape:      SHAPE,
+  shadows:    SHADOWS,
+  components: COMPONENT_OVERRIDES,
+})
+
+/**
+ * MUI theme options object — dark mode counterpart.
+ * Use by passing `{ palette: { mode: 'dark' } }` as the `muiTheme` override
+ * on the provider, or by calling `buildMuiTheme(null, { mode: 'dark' })`.
+ */
+export const DARK_MUI_THEME_OPTIONS = Object.freeze({
+  palette:    DARK_PALETTE,
+  typography: TYPOGRAPHY,
+  shape:      SHAPE,
+  shadows:    SHADOWS,
+  components: COMPONENT_OVERRIDES,
+})
+
+/**
+ * Build a fully-resolved MUI Theme from optional overrides.
+ *
+ * @param {Object} [overrides] - theme options merged on top of defaults.
+ * @param {Object} [opts]
+ * @param {'light'|'dark'} [opts.mode='light']
+ * @returns {import('@mui/material/styles').Theme}
+ */
+export function buildMuiTheme(overrides, { mode = 'light' } = {}) {
+  const base = mode === 'dark' ? DARK_MUI_THEME_OPTIONS : DEFAULT_MUI_THEME_OPTIONS
+  // lodash.merge does deep merge — safer than {...base, ...overrides} which
+  // would clobber nested keys like palette.primary.
+  const merged = merge({}, base, overrides ?? {})
+  return createTheme(merged)
+}
+
+/** Pre-built light theme — convenient when no override is in play. */
+export const DEFAULT_MUI_THEME = buildMuiTheme()
+
+/** Pre-built dark theme — same overrides, dark palette. */
+export const DEFAULT_MUI_THEME_DARK = buildMuiTheme(null, { mode: 'dark' })
+
+/**
+ * Convenience: detect whether the value passed to a provider's `muiTheme`
+ * prop is an already-built Theme (vs. a raw options object). A Theme has
+ * `spacing` as a function and `palette.augmentColor` etc.; an options
+ * object does not.
+ */
+export function isResolvedMuiTheme(value) {
+  return Boolean(value && typeof value.spacing === 'function' && value.palette?.augmentColor)
+}

package/src/lib/providers/RoboByteFrontBuilderProvider.jsx

@@ -46,10 +46,12 @@
 import { useEffect, useMemo } from 'react'
 import { useRouter } from 'next/router'
 import { Toaster } from 'react-hot-toast'
+import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles'
 import { ModuleRegistry } from 'ag-grid-community'
 import { AllEnterpriseModule, LicenseManager } from 'ag-grid-enterprise'
 import { NavigationExtensionProvider } from '../navigation/NavigationExtensionContext'
 import { AgGridThemeProvider } from '../agGridThemeContext'
+import { buildMuiTheme, isResolvedMuiTheme, DEFAULT_MUI_THEME } from '../muiTheme'
 import { configureRoboByte } from '../../services/config'
 import { AuthContext } from '../../context/AuthContext'
 import { setRouter } from '../../services/routerRef'
@@ -107,6 +109,26 @@ const RoboByteFrontBuilderProvider = ({
    * pass a plain params object.
    */
   agGridTheme = null,
+  /**
+   * Optional MUI theme overrides applied to every component the package
+   * renders. Three accepted shapes:
+   *
+   *   1. nothing (default)         — uses DEFAULT_MUI_THEME from lib/muiTheme.js
+   *   2. theme options object      — deep-merged on top of the defaults, e.g.
+   *      muiTheme={{ palette: { primary: { main: '#6366f1' } }, shape: { borderRadius: 12 } }}
+   *   3. a pre-built MUI Theme     — used as-is (escape hatch for full control)
+   *
+   * The package mounts a `<MuiThemeProvider>` wrapping children with the
+   * resolved theme. Host apps with their own outer `<ThemeProvider>` should
+   * pass their theme options here so the package's internal components share
+   * the host's visual identity.
+   *
+   * Pass `disableMuiTheme={true}` to skip the inner ThemeProvider entirely —
+   * use this when the host has already wrapped the app in its own
+   * ThemeProvider and wants it to win without merging.
+   */
+  muiTheme = null,
+  disableMuiTheme = false,
   toasterProps = {},
 }) => {
   // Apply URL + endpoint config synchronously before any child renders.
@@ -130,7 +152,29 @@ const RoboByteFrontBuilderProvider = ({
     [user, accessToken]
   )
 
-  return (
+  // ── Resolve the MUI theme ────────────────────────────────────────────────
+  // Three cases:
+  //   - disableMuiTheme: no wrapping ThemeProvider; host provides its own
+  //   - muiTheme is a pre-built Theme: use as-is
+  //   - muiTheme is null OR an options object: deep-merge with defaults
+  // JSON.stringify keys the memo so a fresh `{ palette: { ... } }` literal
+  // each render doesn't rebuild the theme. Resolved Themes (case 2) are
+  // expected to be stable from the caller's side.
+  const resolvedMuiTheme = useMemo(() => {
+    if (disableMuiTheme) return null
+    if (isResolvedMuiTheme(muiTheme)) return muiTheme
+    if (!muiTheme) return DEFAULT_MUI_THEME
+    return buildMuiTheme(muiTheme)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [disableMuiTheme, isResolvedMuiTheme(muiTheme) ? muiTheme : JSON.stringify(muiTheme ?? null)])
+
+  // Wrapper helper — applies MuiThemeProvider conditionally based on flag.
+  const withMuiTheme = (node) =>
+    disableMuiTheme
+      ? node
+      : <MuiThemeProvider theme={resolvedMuiTheme}>{node}</MuiThemeProvider>
+
+  return withMuiTheme(
     <AuthContext.Provider value={authValue}>
       <NavigationExtensionProvider items={navExtensions}>
         <AgGridThemeProvider params={agGridTheme}>

package/src/pages/_app.js

@@ -31,6 +31,7 @@ export default function App({ Component, pageProps }) {
       user={DEV_USER}
       accessToken={DEV_ACCESS_TOKEN}
       agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+      agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
     >
       {getLayout(<Component {...pageProps} />)}
     </RoboByteFrontBuilderProvider>

package/src/pages/printBuilder/index.jsx

@@ -11,30 +11,37 @@ import { Endpoints, Services } from 'services/Endpoints'
 import { PRINT_COMPONENT_SECTIONS } from 'views/builder/sidebar/tabs/Components/printComponentCatalog'
 import ComponentsTab from 'views/builder/sidebar/tabs/Components/ComponentsTab'
 import TreeTab from 'views/builder/sidebar/tabs/TreeTab'
-import { createTheme } from '@mui/material/styles'
+import { buildMuiTheme } from 'src/lib/muiTheme'
 
-// ── Builder themes (inlined to avoid cross-package path resolution issues) ────
+// ── Builder themes ────────────────────────────────────────────────────────────
+// Deep-merge with the package's DEFAULT_MUI_THEME_OPTIONS so every component
+// override (button polish, input focus halo, transitions, Inter typography,
+// soft shadows) is inherited. The builder UI only overrides palette.
 const _STORAGE_KEY = 'rbb:builderThemeMode'
 const BUILDER_THEMES = {
-  dark: createTheme({
-    palette: {
-      mode: 'dark',
-      primary:    { main: '#9c27b0' },
-      secondary:  { main: '#f5a623' },
-      background: { default: '#141618', paper: '#1e2227' },
-      divider:    '#3a3f45',
-      text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+  dark: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#141618', paper: '#1e2227' },
+        divider:    '#3a3f45',
+        text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+      },
     },
-  }),
-  light: createTheme({
-    palette: {
-      mode: 'light',
-      primary:   { main: '#9c27b0' },
-      secondary: { main: '#f5a623' },
-      background: { default: '#f0f2f5', paper: '#ffffff' },
-      divider:   '#dde1e7',
+    { mode: 'dark' }
+  ),
+  light: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#f0f2f5', paper: '#ffffff' },
+        divider:    '#dde1e7',
+      },
     },
-  }),
+    { mode: 'light' }
+  ),
 }
 function getBuilderThemeMode() {
   try { return localStorage.getItem(_STORAGE_KEY) === 'light' ? 'light' : 'dark' } catch { return 'dark' }

package/src/pages/viewBuilder/index.jsx

@@ -9,30 +9,40 @@ import { useRouter } from 'next/router'
 import { useEffect, useState } from 'react'
 import { Endpoints, Services } from 'services/Endpoints'
 import { ChevronLeft, ChevronRight } from '@mui/icons-material'
-import { createTheme } from '@mui/material/styles'
+import { buildMuiTheme } from 'src/lib/muiTheme'
 
-// ── Builder themes (inlined to avoid cross-package path resolution issues) ────
+// ── Builder themes ────────────────────────────────────────────────────────────
+// These deep-merge ON TOP of the package's DEFAULT_MUI_THEME_OPTIONS so every
+// component override (button polish, input focus halo, transitions, soft
+// shadows, Inter typography, …) is inherited. The builder UI just contributes
+// its own palette (purple primary, gold secondary, builder-specific surface
+// colors). Without this merge the builder pages used a bare-palette theme
+// and looked completely different from the rest of the package.
 const _STORAGE_KEY = 'rbb:builderThemeMode'
 const BUILDER_THEMES = {
-  dark: createTheme({
-    palette: {
-      mode: 'dark',
-      primary:    { main: '#9c27b0' },
-      secondary:  { main: '#f5a623' },
-      background: { default: '#141618', paper: '#1e2227' },
-      divider:    '#3a3f45',
-      text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+  dark: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#141618', paper: '#1e2227' },
+        divider:    '#3a3f45',
+        text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+      },
     },
-  }),
-  light: createTheme({
-    palette: {
-      mode: 'light',
-      primary:   { main: '#9c27b0' },
-      secondary: { main: '#f5a623' },
-      background: { default: '#f0f2f5', paper: '#ffffff' },
-      divider:   '#dde1e7',
+    { mode: 'dark' }
+  ),
+  light: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#f0f2f5', paper: '#ffffff' },
+        divider:    '#dde1e7',
+      },
     },
-  }),
+    { mode: 'light' }
+  ),
 }
 function getBuilderThemeMode() {
   try { return localStorage.getItem(_STORAGE_KEY) === 'light' ? 'light' : 'dark' } catch { return 'dark' }