npm package: @nithishdts001/urm-theme-engine
Description: Enterprise-ready, MUI-only, token-driven theme design system engine
Author: nithishdts001
Latest version: 2.0.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @nithishdts001/urm-theme-engine

> Enterprise-ready, MUI-only, token-driven theme design system engine.

Zero Tailwind. Zero Radix. Pure **React + @mui/material**.

---

## Installation

```bash
npm install @nithishdts001/urm-theme-engine
```

### Peer dependencies (must be installed in your app)

```bash
npm install @mui/material @emotion/react @emotion/styled react react-dom
```

---

## Quick Start

```tsx
import { UrmThemeProvider } from '@nithishdts001/urm-theme-engine';

function Root() {
  return (
    <UrmThemeProvider defaultThemeId="professional-dark">
      <App />
    </UrmThemeProvider>
  );
}
```

`UrmThemeProvider` does three things automatically:
1. Restores the last-used theme from `localStorage`
2. Applies all design tokens as `--token-*` CSS custom properties on `<html>`
3. Wraps MUI's `ThemeProvider` so all MUI components reflect your tokens

---

## Using the Hook

```tsx
import { useThemeEngine } from '@nithishdts001/urm-theme-engine';

function ThemeSwitcher() {
  const {
    currentTheme,
    availableThemes,
    selectTheme,
    updateToken,
    saveChanges,
    applyTheme,
    hasUnsavedChanges,
  } = useThemeEngine();

  return (
    <div>
      <p>Active: {currentTheme.name}</p>

      {availableThemes.map(t => (
        <button key={t.id} onClick={() => selectTheme(t.id)}>
          {t.name}
        </button>
      ))}

      <button
        onClick={() => {
          updateToken('color.primary.main', '#ff6b6b');
          saveChanges();
          applyTheme();
        }}
      >
        Change Primary Color
      </button>
    </div>
  );
}
```

---

## Built-in Themes

| ID | Name |
|----|------|
| `light` | Light Theme |
| `dark` | Dark Theme |
| `corporate-blue` | Corporate Blue |
| `ocean-green` | Ocean Green |
| `professional-dark` | Professional Dark *(default)* |

```ts
import { lightTheme, darkTheme, professionalDarkTheme } from '@nithishdts001/urm-theme-engine';
```

---

## Create a MUI Theme Manually

If you want to use the token → MUI theme conversion without the provider:

```ts
import { createUrmMuiTheme, lightTheme } from '@nithishdts001/urm-theme-engine';
import { ThemeProvider } from '@mui/material/styles';

const muiTheme = createUrmMuiTheme(lightTheme.tokens);

<ThemeProvider theme={muiTheme}>
  <App />
</ThemeProvider>
```

---

## CSS Custom Properties

Every token is available as a `--token-*` CSS variable on `:root`:

```css
color: var(--token-color-primary-main);
background: var(--token-background-default);
border-radius: var(--token-radius-md);
font-family: var(--token-font-family);
```

Generate a full `:root {}` CSS block for SSR or static export:

```ts
import { generateCSSBlock, lightTheme } from '@nithishdts001/urm-theme-engine';

const css = generateCSSBlock(lightTheme.tokens);
// → ":root {\n  --token-color-primary-main: #3b82f6;\n  ...\n}\n"
```

---

## Theme Inheritance

```ts
import { resolveInheritedTokens, builtinThemes } from '@nithishdts001/urm-theme-engine';

const myTheme = {
  id: 'my-brand',
  name: 'My Brand',
  baseThemeId: 'light',        // inherits from lightTheme
  tokens: {
    ...lightTheme.tokens,
    color: {
      ...lightTheme.tokens.color,
      primary: { main: '#8b5cf6', light: '#a78bfa', dark: '#6d28d9', contrast: '#fff' },
    },
  },
};

const resolved = resolveInheritedTokens(myTheme, [...builtinThemes, myTheme]);
```

---

## Version History

```ts
import { saveVersion, getVersionHistory, compareVersions } from '@nithishdts001/urm-theme-engine';

// Save a snapshot
const v = saveVersion('my-theme', 'My Theme', tokens, 'Changed primary color', 'update');

// List history
const history = getVersionHistory('my-theme');

// Diff two versions
const diff = compareVersions(history[0], history[1]);
// → { added: [], modified: [{ path: 'color.primary.main', oldValue: '...', newValue: '...' }], removed: [] }
```

---

## Export / Import

```ts
import {
  exportThemeJSON,
  exportCSSVariables,
  downloadFile,
} from '@nithishdts001/urm-theme-engine';

// Download theme as JSON
downloadFile(exportThemeJSON(myTheme), 'my-theme.json', 'application/json');

// Download CSS variables
downloadFile(exportCSSVariables(myTheme.tokens), 'my-theme.css', 'text/css');
```

---

## API Reference

### `<UrmThemeProvider>`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultThemeId` | `string` | last saved or `'professional-dark'` | Initial active theme |
| `injectCssBaseline` | `boolean` | `true` | Inject MUI `<CssBaseline />` |
| `initialThemes` | `Theme[]` | `undefined` | Extra themes to seed the engine |

### `useThemeEngine()` return shape

See `ThemeEngineContextValue` in the exported types for the full interface.

---

## Token Structure

```
DesignTokens
├── color.{primary|secondary|success|warning|error|info}.{main|light|dark|contrast}
├── text.{primary|secondary|disabled}
├── background.{default|surface}
├── branding.{logo|favicon|primary|secondary}
├── shadow.{sm|md|lg|xl}.{offsetX|offsetY|blur|spread|color|opacity}
├── spacing.{base|xs|sm|md|lg|xl}
├── radius.{sm|md|lg|full}
├── font.{family|size|weight|lineHeight}
├── typography.{h1–h6|body|caption}.{fontSize|fontWeight|lineHeight|color}
└── components.{button|input|card|table|alert|navigation}.*
```