robobyte-front-builder 1.0.26 → 1.0.28

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)
+}