# Migration: Impact UI → Impact Nova

Guide for migrating from **Impact UI** (or similar legacy UI) to **Impact Nova**. Use with other Impact Nova MCP tools: `get_component`, `get_installation_and_config`, `get_real_world_patterns`, `validate_snippet`.

---

## 1. Prerequisites & MCP usage

**Impact UI MCP (optional):** If migrating from Impact UI, `impact-ui-mcp-server` can help map legacy component names during transition. Disable it after migration completes.

- **impact-ui-mcp-server** (optional) — Source API: Impact UI component names, props, import paths.
- **Impact Nova MCP** — Target API: Nova imports, compound components, patterns; validate with `validate_snippet`.

**Impact Nova MCP tools:** `query_components` | `get_component_props` | `get_deprecations` | `get_component` | `get_installation_and_config` | `get_real_world_patterns` | `validate_snippet` | `suggest_components_for_ui`.

Before migrating: find all usages of the old UI library; choose big-bang or incremental strategy.

---

## 2. Phase 1 — Install and configure Impact Nova

**Dependencies:**
```bash
npm install impact-nova impact-nova-icons
npm install react@^19 react-dom@^19
```
With AG Grid: `ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1`. Optional charts: `highcharts@^12 highcharts-react-official@^3`. Then `npm uninstall impact-ui` when ready.

**Styles:** In app root: `import 'impact-nova/dist/impact-nova.css';`

**Font (Manrope):** Link in HTML; set `body { font-family: 'Manrope', sans-serif; }` in global CSS.

**i18n:** Wrap app with `<ImpactNovaProviders locale="en">` from `impact-nova/form`. Use locale packs (e.g. `de`) for other locales.

**Tailwind (optional):** Preset `impact-nova/tailwind.config.js`; add `node_modules/impact-nova/dist/**/*.js` to `content`.

**Vite:** Add `resolve.dedupe: ['react','react-dom','ag-grid-community','ag-grid-enterprise','ag-grid-react']`.

Use MCP **`get_installation_and_config`** for project-specific steps.

---

## 3. Phase 2 — Component mapping (Impact UI → Impact Nova)

Use **`get_component`** for exact API of each Nova component.

| Legacy (Impact UI / common) | Impact Nova | Import |
|-----------------------------|-------------|--------|
| Button | Button | `impact-nova` / `impact-nova/button` |
| Modal / Dialog | Dialog, AlertDialog, Prompt | `impact-nova`, `impact-nova/prompt` |
| Slide-out / Drawer | Sheet | `impact-nova/sheet` |
| Select / Dropdown | Select | `impact-nova/select` |
| Input, TextField | Input, SmartInput | `impact-nova/input`, `impact-nova/smart-input` |
| Textarea | Textarea | `impact-nova/textarea` |
| Checkbox | Checkbox | `impact-nova/checkbox` |
| Radio group | RadioGroup, RadioGroupItem | `impact-nova/radio-group` |
| Switch / Toggle | Switch | `impact-nova/switch` |
| Date picker / range | DatePicker, DateRangePicker, WeekRangePicker, MonthRangePicker | `impact-nova/date-picker` |
| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | `impact-nova/tabs` |
| Alert / Banner | Alert, AlertTitle, AlertDescription, AlertIcon | `impact-nova/alert` |
| Toast / Snackbar | toast, Toaster, useToast | `impact-nova` |
| Badge / Tag | Badge, Tag, Chips | `impact-nova/badge`, `impact-nova`, `impact-nova/chips` |
| Loader / Spinner | Loader, LoadingSpinner (icons) | `impact-nova/loader`, `impact-nova-icons` |
| Accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | `impact-nova/accordion` |
| Sidebar / Nav | Sidebar | `impact-nova/sidebar` |
| Header / AppBar | Header + subcomponents | `impact-nova/header` |
| Breadcrumb | Breadcrumb, BreadcrumbList, etc. | `impact-nova/breadcrumb` |
| Avatar | Avatar, AvatarFallback | `impact-nova/avatar` |
| Tooltip | Tooltip, TooltipTrigger, TooltipContent | `impact-nova/tooltip` |
| File upload | FileUpload (composition) | `impact-nova/file-upload` |
| Data grid / Table | DataTable, AG Grid | `impact-nova`, `impact-nova/ag-grid-react/cell-renderers` |
| Filter panel / strip | FilterPanel, FilterStrip | `impact-nova/filter-panel`, `impact-nova` |
| Empty state | EmptyContainer + subcomponents | `impact-nova/empty-container` |
| Confirmation dialog | Prompt, AlertDialog | `impact-nova/prompt`, `impact-nova` |
| Nested list / Tree | NestedList | `impact-nova/nested-list` |
| Chart | Chart | `impact-nova/chart` |
| Horizontal scroll list | HorizontalScroller | `impact-nova/horizontal-scroller` |

Icons: `impact-nova-icons` (e.g. Pin, Chart, LoadingSpinner) + `createIconResolver` for string lookup.

---

## 4. Phase 3 — Import and API changes

**Imports:** **Prefer subpath imports** in all feature code. Run a codemod or migrate manually:

```tsx
// Before (barrel)
import { Button, Select, DataTable } from 'impact-nova';

// After (subpath — preferred)
import { Button } from 'impact-nova/button';
import { Select } from 'impact-nova/select';
import { DataTable, useDataTable } from 'impact-nova/data-table';
import { CheckCircle } from 'impact-nova-icons';
```

Barrel OK for locale packs: `import { de } from 'impact-nova';`

Types: `import type { Option } from 'impact-nova/select';`, `import type { SavedTableViewItem } from 'impact-nova/data-table';`, `import type { RowSelectionState } from 'impact-nova/virtualized';`

**API:** Severity/type → `variant` (e.g. `variant="destructive"`). Alert: use AlertTitle, AlertDescription, AlertIcon. Toast: `toast()`, Toaster, useToast. Dialog: compound components; confirmations → Prompt or AlertDialog. Select options: type `Option` from `impact-nova/select`. Prefer compound components (e.g. SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter). Use **`validate_snippet`** on snippets.

---

## 5. Phase 4 — Compound patterns

Use **`get_real_world_patterns`** for more detail.

- **Filter UI:** FilterPanel + FilterPanelSidebar, FilterPanelBody, FilterPanelFooter; FilterStrip; types FilterItem, SavedFilterItem, FilterSidebarItem.
- **Data table + AG Grid:** DataTable, DataTableContent, processBackendColumnDefs, BackendColDef; AG_GRID_CELL_COMPONENTS, LinkCellRenderer from `impact-nova/ag-grid-react/cell-renderers`.
- **Sheet:** Sheet, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter from `impact-nova/sheet`; pair with react-hook-form.
- **Empty state:** EmptyContainer, EmptyContainerImage, EmptyContainerTitle, EmptyContainerDescription, EmptyContainerAction.
- **Toast + Alert:** Toaster + toast()/useToast; Alert + AlertTitle, AlertDescription, AlertIcon from `impact-nova/alert`.
- **Tabs + NestedList + Accordion:** Tabs components; NestedList + NestedListItem; Accordion components.

---

## 6. Phase 5 — Verification

**Setup:** Impact Nova MCP enabled; keep impact-ui-mcp-server during migration. Nova + peers installed; CSS + Manrope + ImpactNovaProviders; optional Tailwind + Vite dedupe.

**Migration:** All legacy imports → Nova (barrel/subpath); Alert/Toast/Dialog use Nova variants and compounds; Option/MultiValue from `impact-nova/select`; types via `import type`; use tokens and variant/size.

**MCP:** Use `validate_snippet`, `get_component`, `suggest_components_for_ui`.

**Build/tests:** `npm run build`, lint, manual test of forms, filters, tables, toasts, dialogs.