impact-nova 2.5.16 → 2.6.0-alpha.0

package/dist/llms/index.js

@@ -6,7 +6,10 @@ import rule_4 from './rules/troubleshooting.js';
 import rule_5 from './rules/accessibility.js';
 import rule_6 from './rules/command-palette.js';
 import rule_7 from './rules/real-world-patterns.js';
-import rule_8 from './rules/migration.js';
+import rule_8 from './rules/data-table-comments.js';
+import rule_9 from './rules/data-table-notes.js';
+import rule_10 from './rules/data-table-chat.js';
+import rule_11 from './rules/migration.js';
 const rules = [
   {
     name: "impact-nova-overview",
@@ -64,10 +67,31 @@ const rules = [
     alwaysApply: false,
     globs: ["**/*chart*","**/*Chart*","**/highcharts*","**/*Chart*.tsx"],
   },
+  {
+    name: "data-table-comments",
+    description: "Impact Nova: DataTable cell comments",
+    rule: rule_8,
+    alwaysApply: false,
+    globs: ["**/*data-table*","**/*DataTable*","**/*comment*","**/ag-grid-react/comments/**"],
+  },
+  {
+    name: "data-table-notes",
+    description: "Impact Nova: DataTable cell notes",
+    rule: rule_9,
+    alwaysApply: false,
+    globs: ["**/*data-table*","**/*DataTable*","**/*notes*","**/ag-grid-react/notes/**"],
+  },
+  {
+    name: "data-table-chat",
+    description: "Impact Nova: DataTable row Chat",
+    rule: rule_10,
+    alwaysApply: false,
+    globs: ["**/*data-table*","**/*DataTable*","**/*chat*","**/ag-grid-react/chat/**"],
+  },
   {
     name: "migration-impact-ui",
     description: "Impact Nova: migrate from Impact UI",
-    rule: rule_8,
+    rule: rule_11,
     alwaysApply: false,
     globs: ["**/migration/**/*","**/*migration*"],
   },

package/dist/llms/rules/ag-grid.js

@@ -1 +1 @@
-export default "# AG Grid & Data Table — Mandatory Rules\n\n**When working with DataTable, or any data table that uses AG Grid (including Impact Nova's grid components), the following rules are mandatory. Do not deviate.**\n\n---\n\n## 1. Use AG Grid documentation only\n\n- **Refer only to AG Grid's official documentation** for grid behavior, APIs, column definitions, filtering, sorting, and all grid features.\n- Do not rely on third-party tutorials or generic \"data grid\" patterns that contradict or bypass AG Grid's docs.\n- Official docs: [ag-grid.com/documentation](https://www.ag-grid.com/documentation/) (React: [AG Grid React](https://www.ag-grid.com/react-data-grid/)).\n\n---\n\n## 2. Follow AG Grid recommended patterns\n\n- **Always follow AG Grid's recommended patterns** for:\n  - Column definitions (`ColDef`, `ColGroupDef`)\n  - Cell renderers and editors\n  - Filtering, sorting, and row selection\n  - API ref access (`gridRef.current?.api`)\n  - Theming and styling (AG Grid theme / CSS variables)\n- Do not invent custom patterns that bypass or replace AG Grid's intended usage.\n\n---\n\n## 3. Use the AG Grid API only\n\n- **Rely on the AG Grid API only** for all grid operations:\n  - Getting/setting data, refreshing cells, updating columns\n  - Export (CSV/Excel if using Enterprise)\n  - Filter/sort state, row selection, pinned columns\n  - Any behavior that AG Grid exposes via its API\n- Do not manipulate the DOM or internal structure of the grid directly. Do not use non-API workarounds unless AG Grid docs explicitly suggest them.\n\n---\n\n## 4. Collaboration with ag-mcp (when installed)\n\n- **If the user has installed the ag-mcp server** (AG Grid MCP), this MCP can collaborate with it:\n  - Use **ag-mcp** for AG Grid–specific questions: API reference, column config, React integration, and official examples.\n  - Use **impact-nova-mcp** for Impact Nova wrappers (`DataTable`, `DataTableContent`, `processBackendColumnDefs`, `BackendColDef`, cell renderers from `impact-nova/ag-grid-react/cell-renderers`).\n  - When generating or editing grid code: prefer fetching AG Grid details from ag-mcp when available, and combine with Impact Nova's DataTable/column/cell-renderer patterns from this MCP.\n- If ag-mcp is not installed, still follow rules 1–3 using AG Grid's official documentation only.\n\n---\n\n**Summary:** For any code or design involving AG Grid or Impact Nova's DataTable (which uses AG Grid), use **only** AG Grid documentation, **only** AG Grid recommended patterns, and **only** the AG Grid API—with no deviation. When ag-mcp is available, use it to get accurate AG Grid API and docs; use this MCP for Impact Nova–specific integration.\n\n---\n\n## 5. Mandatory Data Table component usage\n\n**CRITICAL RULE:** If you see a table in a screenshot, or if the user asks for a table by default, you **MUST** use **Impact Nova DataTable** from `impact-nova/data-table`. **Do not build a raw AG Grid or HTML table.**\n\n```tsx\nimport {\n  DataTable,\n  DataTableContent,\n  DataTableToolbar,\n  useDataTable,\n} from 'impact-nova/data-table';\n```\n\nA typical Default Data Table in Impact Nova features this exact structure:\n\n```tsx\nconst DataTableWithFilters = () => {\n    const { tStory } = useStorybookStoryI18n();\n    const [sheetOpen, setSheetOpen] = useState(false);\n    const [activeTab, setActiveTab] = useState(\"columns\");\n    const [showFilterStrip, setShowFilterStrip] = useState(false);\n\n    return (\n    <div className=\"h-[800px] w-full p-8 bg-slate-50 flex flex-col items-center justify-center\">\n       <div className=\"w-full max-w-[1200px] h-[600px] bg-white rounded-lg overflow-hidden flex flex-col [box-shadow:0px_0px_4px_0px_rgba(0,0,0,0.12)]\">\n        <DataTable className=\"h-full\">\n            <DataTableToolbar className=\"border-b border-[#e6e8f0]\">\n                <div className=\"flex items-center gap-2\">\n                    <h2 className=\"font-bold text-sm text-slate-800\">Sales Report</h2>\n                </div>\n                \n                <div className=\"flex items-center gap-2\">\n                    <Button \n                        variant=\"secondary\" \n                        size=\"icon\" \n                        onClick={() => setShowFilterStrip(!showFilterStrip)}\n                        aria-label={showFilterStrip ? tStory('filterStrip.hideFilters') : tStory('filterStrip.showFilters')}\n                    >\n                        {showFilterStrip ? <FunnelHide size=\"xs\" /> : <FunnelShow size=\"xs\" />}\n                    </Button>\n\n                    <div className=\"h-4 w-[1px] bg-[#e6e8f0] mx-1\" />\n\n                    {/* Scoped Sheet for Settings - Renders inside this relative container */}\n                    <DataTableSheet open={sheetOpen} onOpenChange={setSheetOpen}>\n                        <DropdownMenu>\n                            <DataTableViewMenuTrigger />\n                            <DataTableViewMenuContent>\n                                <DataTableViewMenuSettingsItem />\n                                <DataTableViewMenuDensity />\n                            </DataTableViewMenuContent>\n                        </DropdownMenu>\n                        \n                        <DataTableSheetContent>\n                            <DataTableSheetHeader title=\"Table Settings\" />\n                            <Tabs value={activeTab} onValueChange={setActiveTab} variant=\"line\" hideInactiveLabel tooltipClassName=\"z-[110]\" className=\"flex-1 flex flex-col min-h-0 w-full px-4\">\n                                <TabsList>\n                                    <TabsTrigger \n                                        value=\"columns\" \n                                        icon={<Column size={16} />}\n                                    >\n                                        Columns\n                                    </TabsTrigger>\n                                    <TabsTrigger \n                                        value=\"format\" \n                                        icon={<Font size={16} />}\n                                    >\n                                        Format\n                                    </TabsTrigger>\n                                    <TabsTrigger \n                                        value=\"custom-filters\" \n                                        icon={<Filter size={16} />}\n                                    >\n                                        Filters\n                                    </TabsTrigger>\n                                </TabsList>\n                                \n                                <TabsContent value=\"columns\" className=\"flex-1 min-h-0 relative p-0 data-[state=inactive]:hidden mt-0\">\n                                     <div className=\"flex-1 h-full p-2\">\n                                        <DataTableColumnList />\n                                     </div>\n                                </TabsContent>\n                                <TabsContent value=\"format\" className=\"flex-1 min-h-0 relative p-4 pt-1 data-[state=inactive]:hidden overflow-y-auto mt-0\">\n                                     <DataTableFormatOptions />\n                                </TabsContent>\n                                <TabsContent value=\"custom-filters\" className=\"flex-1 min-h-0 relative p-4 pt-1 data-[state=inactive]:hidden overflow-y-auto mt-0\">\n                                     <div className=\"flex flex-col gap-4 text-sm text-[#60697d]\">\n                                         <p>Custom filter configuration would go here.</p>\n                                         <Button variant=\"outline\" className=\"w-full justify-start\">\n                                            + Add Condition\n                                         </Button>\n                                     </div>\n                                </TabsContent>\n                            </Tabs>\n                        </DataTableSheetContent>\n                    </DataTableSheet>\n                </div>\n            </DataTableToolbar>\n            \n            <DataTableContent\n                rowData={rowData}\n                columnDefs={columnDefs}\n                // Standard AG Grid props work here\n                pagination={true}\n                paginationPageSize={20}\n            />\n        </DataTable>\n      </div>\n      <p className=\"mt-4 text-slate-400 text-sm\">\n        Note: The settings panel opens *inside* the table container, respecting its boundaries.\n      </p>\n    </div>\n    );\n};\n```\nNote: This component (`DataTable`) internally uses `ag-grid-react` as a customized version. Rely on it rather than naked AG Grid.\n\n---\n\n## 6. Built-in Clipboard Handlers for JSON Objects\n\n**All DataTable and AG Grid instances in Impact Nova automatically support copying and pasting JSON objects.**\n\nThe `AgGridWrapper` component includes built-in clipboard handlers that:\n- **When copying**: Automatically stringify object values to JSON format\n- **When pasting**: Automatically parse JSON strings back to objects\n\n### How it works\n\n```tsx\n// When you copy a cell with an object value like:\n{ \n  wp: { value: 6479, _isDisabled: true, cellMetadata: {...} },\n  iaf: { value: 6090, _isDisabled: true, cellMetadata: {...} }\n}\n\n// It's automatically converted and split into separate Excel columns:\n// Column 1      Column 2\n// WP: 6479      IAF: 6090\n\n// Technical metadata (_isDisabled, cellMetadata) is hidden for clarity\n// Only the meaningful \"value\" is shown - perfect for PMs and non-technical users\n// Tab-separated format automatically expands into multiple columns in Excel\n```\n\n**Example with simple properties:**\n```tsx\n// Copy this object:\n{ name: \"John\", age: 30, status: \"active\" }\n\n// Expands into 3 Excel columns:\n// Column 1      Column 2    Column 3\n// name: John    age: 30     status: active\n```\n\n**When pasting:**\n```tsx\n// You can paste JSON strings and they'll be parsed back to objects:\n'{\"name\":\"Jane\",\"age\":25}' → { name: \"Jane\", age: 25 }\n```\n\n**Benefits:**\n- ✅ Simple and readable for non-technical users (PMs, stakeholders)\n- ✅ Extracts only meaningful values, hides technical metadata\n- ✅ Automatically expands object properties into separate Excel columns\n- ✅ Perfect for analysis - each property gets its own column\n- ✅ Works seamlessly for both single-cell and multi-cell copy operations\n- ✅ Still supports pasting JSON back for developers\n\n### Usage\n\n**No configuration needed!** This works automatically for all DataTable instances:\n\n```tsx\n<DataTable>\n  <DataTableContent\n    rowData={data}\n    columnDefs={columns}\n    // Clipboard handlers are already active ✅\n  />\n</DataTable>\n```\n\n### Override if needed\n\nYou can override the default behavior by passing your own handlers:\n\n```tsx\n<DataTableContent\n  rowData={data}\n  columnDefs={columns}\n  processCellForClipboard={(params) => {\n    // Custom copy logic\n    return customFormat(params.value);\n  }}\n  processCellFromClipboard={(params) => {\n    // Custom paste logic\n    return customParse(params.value);\n  }}\n/>\n```\n\n**Key benefits:**\n- ✅ Works automatically for all tables\n- ✅ No code duplication needed\n- ✅ Handles complex object structures\n- ✅ Gracefully falls back to string if JSON parsing fails\n- ✅ Can be overridden when custom behavior is needed\n\n---\n\n## 6. Column autosize on container resize\n\n**AgGridWrapper** (from `impact-nova/ag-grid-react`) automatically re-runs `autoSizeStrategy` when the grid container width changes (accordion expand, viewport resize, responsive layout).\n\n- Pass `autoSizeStrategy` to DataTable/AgGridWrapper props (e.g. `{ type: 'fitCellContents', scaleUpToFitGridWidth: true }`).\n- **Do not** add app-level ResizeObserver hacks or deferred grid mount delays — the framework handles this.\n- When applying saved column views, wait for `firstDataRendered` or `newColumnsLoaded` grid events before applying column state — not `setTimeout(0)`.\n- Strip `width`/`flex` from saved column state when applying structural views so autosize can recalculate correctly.\n\n---\n\n## 6b. Truncated text in custom cell renderers\n\n**Do not** use `OverflowTooltip` inside AG Grid cells. Use the grid-native tooltip API via **`useAgGridTruncationTooltip`** from `impact-nova/ag-grid-react`:\n\n```tsx\nimport { useAgGridTruncationTooltip } from 'impact-nova/ag-grid-react';\n\nconst MyCellRenderer = (params: ICellRendererParams) => {\n  const textRef = useRef<HTMLSpanElement>(null);\n  const displayValue = String(params.value ?? '');\n\n  useAgGridTruncationTooltip(\n    params.setTooltip,\n    displayValue,\n    textRef,\n    'ellipsis',\n    'cell',\n  );\n\n  return (\n    <span ref={textRef} className=\"truncate\">\n      {displayValue}\n    </span>\n  );\n};\n```\n\n- Pass AG Grid's `setTooltip` callback (from `ICellRendererParams` / header APIs).\n- Apply `truncate` (or `line-clamp`) on the measured element.\n- `location` is `'cell' | 'leaf' | 'group'` — affects tooltip show mode wiring.\n- For general (non-grid) truncated labels, use `OverflowTooltip` from `impact-nova/tooltip` instead.\n\n---\n\n## 7. AG Grid v36 version pin (mandatory)\n\nImpact Nova **2.2.0+** targets **AG Grid v36**. Consumer apps must install all three packages at the **exact same version**:\n\n```bash\nnpm install ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1\n```\n\n**Rules:**\n\n- Pin `36.0.1` in `package.json` — do not float `^36` across community/react/enterprise.\n- Vite/webpack: `resolve.dedupe: ['ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react']` (see `create-impact-nova` template).\n- **Do not** import legacy AG Grid CSS theme files (`ag-grid.css`, `ag-theme-*`). Impact Nova `AgGridWrapper` applies the v36 Quartz theme (`themeQuartz.withPart(iconSetMaterial)`) via the `theme` prop.\n- Column settings (`DataTableColumnList`) sync pin/sort/filter from the live `GridApi` — do not mirror column state in app-level React state.\n\n**Column settings sheet pattern (scroll-safe — use compound layout components):**\n\n```tsx\n<DataTableSheet open={sheetOpen} onOpenChange={setSheetOpen}>\n  <DataTableSheetContent>\n    <DataTableSheetHeader title=\"Table Settings\" />\n    <DataTableSheetBody>\n      <DataTableSheetSection>{savedViews}</DataTableSheetSection>\n      <DataTableSheetTabs value={tab} onValueChange={setTab} variant=\"line\" className=\"px-4\">\n        <DataTableSheetTabsList>\n          <TabsTrigger value=\"columns\">Columns</TabsTrigger>\n          <TabsTrigger value=\"format\">Format</TabsTrigger>\n        </DataTableSheetTabsList>\n        <DataTableSheetTabPanel layout=\"list\" value=\"columns\" className=\"p-0 pt-2\">\n          <DataTableColumnList />\n        </DataTableSheetTabPanel>\n        <DataTableSheetTabPanel layout=\"scroll\" value=\"format\" className=\"p-4 pt-1\">\n          <DataTableFormatOptions />\n        </DataTableSheetTabPanel>\n      </DataTableSheetTabs>\n    </DataTableSheetBody>\n  </DataTableSheetContent>\n</DataTableSheet>\n```\n\nDo **not** use raw `Tabs` + manual `overflow-y-auto` in sheet bodies — see `impact-nova://data-table-sheet-layout`.\n\nStorybook reference: `Data Display/DataTable/Sheet layout` (`CanonicalComposition`) and `Column settings scenarios` (`PinSortSearchAndReset`).\n\n---\n\n## 8. 50k+ Column Consumer Settings\n\nWhen building grids with **10,000+ columns** (planning grids, large attribute tables), apply these settings:\n\n### Required grid props\n\n```tsx\n<DataTableContent\n  ensureDomOrder={false}         // Skip DOM reordering for screen readers — critical at 10k+\n  maintainColumnOrder={true}     // Preserve column ordering after runtime column defs changes\n  suppressColumnVirtualisation={false} // Ensure column virtualization is ON (default)\n/>\n```\n\n### Column picker (DataTableColumnList)\n\n- At 80+ visible items, `DataTableColumnList` automatically switches to **virtual-index drag mode** (pointer-based reorder with TanStack Virtual) instead of dnd-kit sortable (50k useSortable hooks + DOM nodes).\n- No consumer configuration needed — the switch is automatic.\n- Drag-and-drop, search, select-all, pin switches, apply/discard all remain functional.\n\n### Saved views and state management\n\n- **Use `applyColumnState({ state, applyOrder: true })` for restoring saved column views** — this is the AG Grid recommended pattern for partial column state application.\n- **Evaluate `gridApi.getState()` / `gridApi.setState()` for full grid snapshots** (includes sort, filter, column state, grouping) when persisting complex view configurations.\n- Keep `mergePartialOrderedColumnState` for picker-initiated partial edits (picker only modifies a subset of columns).\n- **Do not** manually diff columnDefs for saved views — AG Grid's state APIs handle runtime-calculated columns.\n\n### Column runtime state guard\n\n- After `newColumnsLoaded` events, Impact Nova's `columnRuntimeStateGuard` automatically restores hide/pin/order from the cached tree to prevent column-def refreshes from resetting user layout.\n- **Use `deferColumnRuntimeStateGuard(gridApi)`** when your app applies external state (e.g., from a backend save) — this skips the guard for that cycle and rebuilds the cache from your new live state.\n\n### Performance budget (CI ratchet)\n\n| Operation | Target at 50k |\n|-----------|---------------|\n| Hash fingerprint (3x) | < 200ms |\n| Tree build from grid | < 2s |\n| Cache resolve skip path | < 300ms |\n| Indicator patch (sort/filter badges) | < 500ms |\n| Authority build + fingerprint | < 500ms |\n| Authority reorder (splice) | < 50ms |\n| Column sheet open (collapsed groups) | < 500ms |\n| Drag frame time (virtual-index) | < 16ms |\n\n---\n";
+export default "# AG Grid & Data Table — Mandatory Rules\n\n**When working with DataTable, or any data table that uses AG Grid (including Impact Nova's grid components), the following rules are mandatory. Do not deviate.**\n\n---\n\n## 1. Use AG Grid documentation only\n\n- **Refer only to AG Grid's official documentation** for grid behavior, APIs, column definitions, filtering, sorting, and all grid features.\n- Do not rely on third-party tutorials or generic \"data grid\" patterns that contradict or bypass AG Grid's docs.\n- Official docs: [ag-grid.com/documentation](https://www.ag-grid.com/documentation/) (React: [AG Grid React](https://www.ag-grid.com/react-data-grid/)).\n\n---\n\n## 2. Follow AG Grid recommended patterns\n\n- **Always follow AG Grid's recommended patterns** for:\n  - Column definitions (`ColDef`, `ColGroupDef`)\n  - Cell renderers and editors\n  - Filtering, sorting, and row selection\n  - API ref access (`gridRef.current?.api`)\n  - Theming and styling (AG Grid theme / CSS variables)\n- Do not invent custom patterns that bypass or replace AG Grid's intended usage.\n\n---\n\n## 3. Use the AG Grid API only\n\n- **Rely on the AG Grid API only** for all grid operations:\n  - Getting/setting data, refreshing cells, updating columns\n  - Export (CSV/Excel if using Enterprise)\n  - Filter/sort state, row selection, pinned columns\n  - Any behavior that AG Grid exposes via its API\n- Do not manipulate the DOM or internal structure of the grid directly. Do not use non-API workarounds unless AG Grid docs explicitly suggest them.\n\n---\n\n## 4. Collaboration with ag-mcp (when installed)\n\n- **If the user has installed the ag-mcp server** (AG Grid MCP), this MCP can collaborate with it:\n  - Use **ag-mcp** for AG Grid–specific questions: API reference, column config, React integration, and official examples.\n  - Use **impact-nova-mcp** for Impact Nova wrappers (`DataTable`, `DataTableContent`, `processBackendColumnDefs`, `BackendColDef`, cell renderers from `impact-nova/ag-grid-react/cell-renderers`).\n  - When generating or editing grid code: prefer fetching AG Grid details from ag-mcp when available, and combine with Impact Nova's DataTable/column/cell-renderer patterns from this MCP.\n- If ag-mcp is not installed, still follow rules 1–3 using AG Grid's official documentation only.\n\n---\n\n**Summary:** For any code or design involving AG Grid or Impact Nova's DataTable (which uses AG Grid), use **only** AG Grid documentation, **only** AG Grid recommended patterns, and **only** the AG Grid API—with no deviation. When ag-mcp is available, use it to get accurate AG Grid API and docs; use this MCP for Impact Nova–specific integration.\n\n---\n\n## 5. Mandatory Data Table component usage\n\n**CRITICAL RULE:** If you see a table in a screenshot, or if the user asks for a table by default, you **MUST** use **Impact Nova DataTable** from `impact-nova/data-table`. **Do not build a raw AG Grid or HTML table.**\n\n```tsx\nimport {\n  DataTable,\n  DataTableContent,\n  DataTableToolbar,\n  useDataTable,\n} from 'impact-nova/data-table';\n```\n\nA typical Default Data Table in Impact Nova features this exact structure:\n\n```tsx\nconst DataTableWithFilters = () => {\n    const { tStory } = useStorybookStoryI18n();\n    const [sheetOpen, setSheetOpen] = useState(false);\n    const [activeTab, setActiveTab] = useState(\"columns\");\n    const [showFilterStrip, setShowFilterStrip] = useState(false);\n\n    return (\n    <div className=\"h-[800px] w-full p-8 bg-slate-50 flex flex-col items-center justify-center\">\n       <div className=\"w-full max-w-[1200px] h-[600px] bg-white rounded-lg overflow-hidden flex flex-col [box-shadow:0px_0px_4px_0px_rgba(0,0,0,0.12)]\">\n        <DataTable className=\"h-full\">\n            <DataTableToolbar className=\"border-b border-[#e6e8f0]\">\n                <div className=\"flex items-center gap-2\">\n                    <h2 className=\"font-bold text-sm text-slate-800\">Sales Report</h2>\n                </div>\n                \n                <div className=\"flex items-center gap-2\">\n                    <Button \n                        variant=\"secondary\" \n                        size=\"icon\" \n                        onClick={() => setShowFilterStrip(!showFilterStrip)}\n                        aria-label={showFilterStrip ? tStory('filterStrip.hideFilters') : tStory('filterStrip.showFilters')}\n                    >\n                        {showFilterStrip ? <FunnelHide size=\"xs\" /> : <FunnelShow size=\"xs\" />}\n                    </Button>\n\n                    <div className=\"h-4 w-[1px] bg-[#e6e8f0] mx-1\" />\n\n                    {/* Scoped Sheet for Settings - Renders inside this relative container */}\n                    <DataTableSheet open={sheetOpen} onOpenChange={setSheetOpen}>\n                        <DropdownMenu>\n                            <DataTableViewMenuTrigger />\n                            <DataTableViewMenuContent>\n                                <DataTableViewMenuSettingsItem />\n                                <DataTableViewMenuDensity />\n                            </DataTableViewMenuContent>\n                        </DropdownMenu>\n                        \n                        <DataTableSheetContent>\n                            <DataTableSheetHeader title=\"Table Settings\" />\n                            <Tabs value={activeTab} onValueChange={setActiveTab} variant=\"line\" hideInactiveLabel tooltipClassName=\"z-[110]\" className=\"flex-1 flex flex-col min-h-0 w-full px-4\">\n                                <TabsList>\n                                    <TabsTrigger \n                                        value=\"columns\" \n                                        icon={<Column size={16} />}\n                                    >\n                                        Columns\n                                    </TabsTrigger>\n                                    <TabsTrigger \n                                        value=\"format\" \n                                        icon={<Font size={16} />}\n                                    >\n                                        Format\n                                    </TabsTrigger>\n                                    <TabsTrigger \n                                        value=\"custom-filters\" \n                                        icon={<Filter size={16} />}\n                                    >\n                                        Filters\n                                    </TabsTrigger>\n                                </TabsList>\n                                \n                                <TabsContent value=\"columns\" className=\"flex-1 min-h-0 relative p-0 data-[state=inactive]:hidden mt-0\">\n                                     <div className=\"flex-1 h-full p-2\">\n                                        <DataTableColumnList />\n                                     </div>\n                                </TabsContent>\n                                <TabsContent value=\"format\" className=\"flex-1 min-h-0 relative p-4 pt-1 data-[state=inactive]:hidden overflow-y-auto mt-0\">\n                                     <DataTableFormatOptions />\n                                </TabsContent>\n                                <TabsContent value=\"custom-filters\" className=\"flex-1 min-h-0 relative p-4 pt-1 data-[state=inactive]:hidden overflow-y-auto mt-0\">\n                                     <div className=\"flex flex-col gap-4 text-sm text-[#60697d]\">\n                                         <p>Custom filter configuration would go here.</p>\n                                         <Button variant=\"outline\" className=\"w-full justify-start\">\n                                            + Add Condition\n                                         </Button>\n                                     </div>\n                                </TabsContent>\n                            </Tabs>\n                        </DataTableSheetContent>\n                    </DataTableSheet>\n                </div>\n            </DataTableToolbar>\n            \n            <DataTableContent\n                rowData={rowData}\n                columnDefs={columnDefs}\n                // Standard AG Grid props work here\n                pagination={true}\n                paginationPageSize={20}\n            />\n        </DataTable>\n      </div>\n      <p className=\"mt-4 text-slate-400 text-sm\">\n        Note: The settings panel opens *inside* the table container, respecting its boundaries.\n      </p>\n    </div>\n    );\n};\n```\nNote: This component (`DataTable`) internally uses `ag-grid-react` as a customized version. Rely on it rather than naked AG Grid.\n\n---\n\n## 6. Built-in Clipboard Handlers for JSON Objects\n\n**All DataTable and AG Grid instances in Impact Nova automatically support copying and pasting JSON objects.**\n\nThe `AgGridWrapper` component includes built-in clipboard handlers that:\n- **When copying**: Automatically stringify object values to JSON format\n- **When pasting**: Automatically parse JSON strings back to objects\n\n### How it works\n\n```tsx\n// When you copy a cell with an object value like:\n{ \n  wp: { value: 6479, _isDisabled: true, cellMetadata: {...} },\n  iaf: { value: 6090, _isDisabled: true, cellMetadata: {...} }\n}\n\n// It's automatically converted and split into separate Excel columns:\n// Column 1      Column 2\n// WP: 6479      IAF: 6090\n\n// Technical metadata (_isDisabled, cellMetadata) is hidden for clarity\n// Only the meaningful \"value\" is shown - perfect for PMs and non-technical users\n// Tab-separated format automatically expands into multiple columns in Excel\n```\n\n**Example with simple properties:**\n```tsx\n// Copy this object:\n{ name: \"John\", age: 30, status: \"active\" }\n\n// Expands into 3 Excel columns:\n// Column 1      Column 2    Column 3\n// name: John    age: 30     status: active\n```\n\n**When pasting:**\n```tsx\n// You can paste JSON strings and they'll be parsed back to objects:\n'{\"name\":\"Jane\",\"age\":25}' → { name: \"Jane\", age: 25 }\n```\n\n**Benefits:**\n- ✅ Simple and readable for non-technical users (PMs, stakeholders)\n- ✅ Extracts only meaningful values, hides technical metadata\n- ✅ Automatically expands object properties into separate Excel columns\n- ✅ Perfect for analysis - each property gets its own column\n- ✅ Works seamlessly for both single-cell and multi-cell copy operations\n- ✅ Still supports pasting JSON back for developers\n\n### Usage\n\n**No configuration needed!** This works automatically for all DataTable instances:\n\n```tsx\n<DataTable>\n  <DataTableContent\n    rowData={data}\n    columnDefs={columns}\n    // Clipboard handlers are already active ✅\n  />\n</DataTable>\n```\n\n### Override if needed\n\nYou can override the default behavior by passing your own handlers:\n\n```tsx\n<DataTableContent\n  rowData={data}\n  columnDefs={columns}\n  processCellForClipboard={(params) => {\n    // Custom copy logic\n    return customFormat(params.value);\n  }}\n  processCellFromClipboard={(params) => {\n    // Custom paste logic\n    return customParse(params.value);\n  }}\n/>\n```\n\n**Key benefits:**\n- ✅ Works automatically for all tables\n- ✅ No code duplication needed\n- ✅ Handles complex object structures\n- ✅ Gracefully falls back to string if JSON parsing fails\n- ✅ Can be overridden when custom behavior is needed\n\n---\n\n## 6. Column autosize on container resize\n\n**AgGridWrapper** (from `impact-nova/ag-grid-react`) automatically re-runs `autoSizeStrategy` when the grid container width changes (accordion expand, viewport resize, responsive layout).\n\n- Pass `autoSizeStrategy` to DataTable/AgGridWrapper props (e.g. `{ type: 'fitCellContents', scaleUpToFitGridWidth: true }`).\n- **Do not** add app-level ResizeObserver hacks or deferred grid mount delays — the framework handles this.\n- When applying saved column views, wait for `firstDataRendered` or `newColumnsLoaded` grid events before applying column state — not `setTimeout(0)`.\n- Strip `width`/`flex` from saved column state when applying structural views so autosize can recalculate correctly.\n\n---\n\n## 6b. Truncated text in custom cell renderers\n\n**Do not** use `OverflowTooltip` inside AG Grid cells. Use the grid-native tooltip API via **`useAgGridTruncationTooltip`** from `impact-nova/ag-grid-react`:\n\n```tsx\nimport { useAgGridTruncationTooltip } from 'impact-nova/ag-grid-react';\n\nconst MyCellRenderer = (params: ICellRendererParams) => {\n  const textRef = useRef<HTMLSpanElement>(null);\n  const displayValue = String(params.value ?? '');\n\n  useAgGridTruncationTooltip(\n    params.setTooltip,\n    displayValue,\n    textRef,\n    'ellipsis',\n    'cell',\n  );\n\n  return (\n    <span ref={textRef} className=\"truncate\">\n      {displayValue}\n    </span>\n  );\n};\n```\n\n- Pass AG Grid's `setTooltip` callback (from `ICellRendererParams` / header APIs).\n- Apply `truncate` (or `line-clamp`) on the measured element.\n- `location` is `'cell' | 'leaf' | 'group'` — affects tooltip show mode wiring.\n- For general (non-grid) truncated labels, use `OverflowTooltip` from `impact-nova/tooltip` instead.\n\n---\n\n## 7. AG Grid v36 version pin (mandatory)\n\nImpact Nova **2.2.0+** targets **AG Grid v36**. Consumer apps must install all three packages at the **exact same version**:\n\n```bash\nnpm install ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1\n```\n\n**Rules:**\n\n- Pin `36.0.1` in `package.json` — do not float `^36` across community/react/enterprise.\n- Vite/webpack: `resolve.dedupe: ['ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react']` (see `create-impact-nova` template).\n- **Do not** import legacy AG Grid CSS theme files (`ag-grid.css`, `ag-theme-*`). Impact Nova `AgGridWrapper` applies the v36 Quartz theme (`themeQuartz.withPart(iconSetMaterial)`) via the `theme` prop.\n- Column settings (`DataTableColumnList`) sync pin/sort/filter from the live `GridApi` — do not mirror column state in app-level React state.\n\n**Column settings sheet pattern (scroll-safe — use compound layout components):**\n\n```tsx\n<DataTableSheet open={sheetOpen} onOpenChange={setSheetOpen}>\n  <DataTableSheetContent>\n    <DataTableSheetHeader title=\"Table Settings\" />\n    <DataTableSheetBody>\n      <DataTableSheetSection>{savedViews}</DataTableSheetSection>\n      <DataTableSheetTabs value={tab} onValueChange={setTab} variant=\"line\" className=\"px-4\">\n        <DataTableSheetTabsList>\n          <TabsTrigger value=\"columns\">Columns</TabsTrigger>\n          <TabsTrigger value=\"format\">Format</TabsTrigger>\n        </DataTableSheetTabsList>\n        <DataTableSheetTabPanel layout=\"list\" value=\"columns\" className=\"p-0 pt-2\">\n          <DataTableColumnList />\n        </DataTableSheetTabPanel>\n        <DataTableSheetTabPanel layout=\"scroll\" value=\"format\" className=\"p-4 pt-1\">\n          <DataTableFormatOptions />\n        </DataTableSheetTabPanel>\n      </DataTableSheetTabs>\n    </DataTableSheetBody>\n  </DataTableSheetContent>\n</DataTableSheet>\n```\n\nDo **not** use raw `Tabs` + manual `overflow-y-auto` in sheet bodies — see `impact-nova://data-table-sheet-layout`.\n\nStorybook reference: `Data Display/DataTable/Sheet layout` (`CanonicalComposition`) and `Column settings scenarios` (`PinSortSearchAndReset`).\n\n---\n\n## Cell Comments / Notes / Row Chat (independent opt-ins)\n\nThree **separate** `DataTableContent` props. Omit a prop → zero host, listeners, or fetch for that feature.\n\n| Feature | Identity | Import | Full guide |\n|---------|----------|--------|------------|\n| **Comments** | cell `{ rowId, colId }` | `impact-nova/ag-grid-react/comments` | `impact-nova://data-table-comments` |\n| **Notes** | cell `{ rowId, colId }` | `impact-nova/ag-grid-react/notes` | `impact-nova://data-table-notes` |\n| **Chat** | row `{ getRowId }` | `impact-nova/ag-grid-react/chat` | `impact-nova://data-table-chat` |\n\nDo **not** use AG Grid Notes for comment threads. Do **not** put threads or conversations in `rowData`. Do **not** key by DOM, `rowIndex`, or page number. Do **not** call private AG Grid beans (`INotesService`, `CellCtrl`, `showNote`).\n\nSame cell may have Comment + Note: blue triangle = Comment (`--iv-comment-indicator-color` / `--color-primary`); yellow = Note (`--iv-note-indicator-color` / `--color-warning`); split = both. Notes owns hover/click unless comment-mode; Comment still via menu / panel / comment-mode.\n\n---\n\n## Cell Comments (opt-in)\n\nUse `comments` on `DataTableContent` and helpers from `impact-nova/ag-grid-react/comments`.\n\nThis is a Google Sheets–style **cell comment thread** (create → reply → resolve → reopen). It is not Notes and has no read/unread state.\n\n**Start here:** Storybook `Data Display/DataTable/Comments/QuickStart`. **Implement from:** `impact-nova://data-table-comments`.\n\n### Identity\n\n`getRowId` + stable `colId` → `{ rowId, colId }`. Default thread id is `rowId + \"\\\\0\" + colId`. Overlay is one React tree per grid, lazy-loaded when `comments` is set.\n\n### Required config\n\n`hasIndicator` (O(1), unresolved only), `loadThread`, `persist`, `getAuthor`. Optional: `getSummaries` (list sheet), `locateRow` (row not in current model), `getCapabilities`, `commentMode` / `CommentModeToggle`, `messageActions` / `renderAvatar` (open overlay only).\n\n### Grid page vs thread page vs list page\n\nAG Grid pagination/SSRM is which **rows** are loaded. `loadThread` `request` is which **messages** are loaded. `getSummaries` is which **thread cards** are in the sheet. These are independent.\n\n### Off-page cells\n\nA comment exists even when the cell is not rendered. The triangle is a projection on painted cells only (`.iv-has-cell-comment` via `cellClassRules`).\n\n- CSRM + AG Grid `pagination`: Nova uses live `getRowNode(rowId)` then `paginationGoToPage`. No `locateRow`.\n- SSRM / app-replaced `rowData`: implement `locateRow` to load that page, then return `{ status: \"ready\" }`. Filtered-out rows (`rowIndex == null`) stay **Not in current view**.\n\n### UI\n\n- Right-click a cell → **Add comment**. When Notes are off, native AG Grid note items are stripped. When Notes are on, native note actions stay.\n- Do not pass `notesDataSource` for Comments — use `notes={...}` for AG Grid Notes.\n\n---\n\n## Cell Notes (opt-in)\n\nUse `notes` on `DataTableContent` and types from `impact-nova/ag-grid-react/notes`.\n\nThis is public AG Grid 36 `NotesModule` + `notesDataSource` (cell text + native popup). It is not a Comment thread.\n\n**Start here:** Storybook `Data Display/DataTable/Notes/QuickStart`. **Implement from:** `impact-nova://data-table-notes`.\n\n`getNote` / `setNote` keyed by `{ rowId, colId }`. Omit `notes` for zero Notes runtime. The popup shell is AG Grid’s `.ag-notes-popup` — do not replace it with a React slot.\n\n---\n\n## Row Chat (opt-in)\n\nUse `chat` on `DataTableContent` and helpers from `impact-nova/ag-grid-react/chat`.\n\nChat is **row-scoped**: many conversations per `getRowId`. It is not a cell comment and not an AG Grid Note.\n\n**Start here:** Storybook `Data Display/DataTable/Chat/QuickStart`. **Implement from:** `impact-nova://data-table-chat`.\n\n### Required config\n\n`hasConversation` (O(1) presence), `loadConversation` (newest window + `before` cursor), `persist` (one event, not the lifetime array), `getAuthor`. Optional: `unreadCount`, `getSummaries`, `locateRow` (required for app-paged / SSRM), `column: false`, `can(action, context)`, `listPeople`, `renderComposer` / `renderAvatar` / `renderMessageBody`.\n\n### System column\n\nDefault injects pinned-right `iv-chat` (69px). Excluded from the column tree, saved views, auto-size, and export. Do not persist it in consumer column state. Cell renderer is a vanilla `ICellRendererComp` — not per-row React.\n\n### Pagination\n\n- Client pagination: all rows stay in the model. Do not pass `locateRow`.\n- Server / app-paged: pass `locateRow(rowId)` and load the page. Filtered rows (`rowIndex == null`) open Chat with **Hidden by current filter** — Nova does not call `locateRow`.\n\n### Permissions and composition\n\nPass `can(action, context)` with `ChatAction = view | create | edit | delete | invite | remove-member`. Do not explode booleans (`canAddMember`). Leave / admin / transfer-ownership are **not** Chat domain — use `listActions`.\n\nChat is a DataTable config + `render*` slots — **not** a Radix `<Chat><ChatHeader/></Chat>` tree. Map vendor DTOs in `loadConversation` / `listPeople` / `persist`. Do not add a WebSocket layer inside Nova.\n\n---\n\n";

package/dist/llms/rules/best-practices.js

@@ -1 +1 @@
-export default "# Impact Nova — Best Practices & Do's and Don'ts\n\n## Use Impact Nova components only\n\n**When building with Impact Nova, use the components that are present in this design system only.** The library includes a full set of UI components (forms, navigation, feedback, data display, layout, etc.). There is no need to create new custom components for standard UI—use what Impact Nova provides. Check `list_components` or the component catalog to see what's available; use `get_component` for the spec and usage of any component. Prefer composing existing Impact Nova components over building from scratch.\n\n## Do's\n\n1. **Use compound components** — Use subcomponents (e.g. `Dialog.Content`, `Card.Header`, `Select.Trigger`) for full control without prop drilling.\n2. **Use `cn()` and Tailwind token classes** — Merge classNames with the `cn()` helper; use design token classes (e.g. `bg-brand`, `text-content`, `border-stroke`) not raw hex or arbitrary values.\n3. **Use design tokens** — Prefer Tailwind theme tokens (colors, spacing, radius from the design system). No arbitrary values where a token exists.\n4. **Accessibility first** — Components are built on Radix UI; preserve aria-labels, keyboard support, and screen reader compatibility. Add `aria-label` for icon-only buttons.\n5. **i18n for user-facing strings** — Mount `ImpactNovaProviders` from `impact-nova/form` at app root; use `useImpactNovaI18n()` / `t()` for labels, placeholders, and button text. Override via props when needed.\n6. **File naming** — Use `kebab-case.tsx` for files (e.g. `file-upload.tsx`).\n7. **TypeScript** — Import and extend component props (e.g. `ButtonProps`) for type-safe wrappers.\n8. **Use `variant` and `size` props** — For appearance, use the component's built-in variant and size props (e.g. `Button variant=\"default\" size=\"lg\"`). Add `className` only for layout (e.g. margin, gap) or intentional overrides.\n\n## Don'ts\n\n1. **No inline styles for token-backed values** — Don't use `style={{ color: '...' }}` or inline hex for colors that exist as tokens.\n2. **Don't bypass tokens** — Avoid hardcoded spacing or colors; use Tailwind token classes.\n3. **Don't skip i18n** — For any user-facing label, placeholder, or message, use the i18n context or pass overrides via props.\n4. **Don't add unnecessary classNames for styling** — Components are already styled to the design standard. Use `variant` and `size` for appearance. Use `className` only for layout (e.g. `mt-4`, `flex gap-2`) or intentional overrides, not for duplicating built-in styles (e.g. don't add `rounded-lg` if the component already applies it).\n5. **Don't use non-token colors** — Stick to the design token palette (primary, secondary, accent, destructive, muted, etc.).\n6. **Don't create new components when Impact Nova already provides one** — The design system has the components you need. Use `list_components` / `get_component` to find and use them instead of building custom equivalents.\n7. **Error and empty states** — Use **Alert** for form or API errors; use **EmptyContainer** when there is no data to show (with optional action like \"Select filter\" or \"Add item\").\n\n## Composition over inheritance\n\nFavor composition. Compose subcomponents rather than extending or wrapping with custom styling that overrides the design system.\n\n## Imports\n\n**Prefer subpath imports** in production apps for tree-shaking (~98% smaller bundles vs full barrel). Use the barrel only for i18n bootstrapping or when importing many symbols from one area in a single file.\n\n- **Subpath (preferred)**: `import { Button } from 'impact-nova/button';`, `import { Card, CardContent } from 'impact-nova/card';`, `import { DataTable, DataTableContent, useDataTable } from 'impact-nova/data-table';`, `import { FilterPanel, FilterPanelSidebar } from 'impact-nova/filter-panel';`, `import { Combobox } from 'impact-nova/combobox';`\n- **App providers**: `import { ImpactNovaProviders } from 'impact-nova/form';` — mount once at root (i18n + TooltipProvider)\n- **Barrel (locale packs only)**: `import { de } from 'impact-nova';` — OK for locale packs; avoid barrel for UI components\n- **Icons (required peer)**: `npm install impact-nova-icons@^0.1.1` then `import { Pin, Chart } from 'impact-nova-icons';` — use `createIconResolver` from `impact-nova-icons/resolver` for dynamic lookup. Icons are **not** exported from `impact-nova`\n- **Types only**: `import type { Option } from 'impact-nova/select';`, `import type { SavedTableViewItem } from 'impact-nova/data-table';`, `import type { RowSelectionState } from 'impact-nova/virtualized';`\n- **i18n hooks**: `import { useImpactNovaI18n } from 'impact-nova/i18n';`\n- **Locale packs**: `import { de } from 'impact-nova/locale/de';` (also `es`, `hi`, `kn`)\n- **CSS (once at root)**: `import 'impact-nova/dist/impact-nova.css';` — or split layers: `impact-nova/impact-nova-tokens.scss`, `impact-nova/impact-nova-base.scss`, `impact-nova/impact-nova-components.css`\n\n**Vite consumers:** add `resolve.dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react']` to avoid dual React/AG Grid instances. Exclude `impact-nova-icons` from `optimizeDeps` to prevent SVG asset warnings. Pre-bundle Highcharts modules in `optimizeDeps.include` if using Chart.\n\n## Truncated text tooltips (OverflowTooltip)\n\nUse **`OverflowTooltip`** from `impact-nova/tooltip` when CSS truncation (`truncate`, `line-clamp`) may clip content and you want a tooltip **only when overflow is detected**.\n\n```tsx\nimport { OverflowTooltip } from 'impact-nova/tooltip';\n\n<OverflowTooltip content={fullLabel}>\n  <span className=\"truncate\">{fullLabel}</span>\n</OverflowTooltip>\n```\n\n**Rules:**\n\n1. **General UI** — `OverflowTooltip` or headless `useOverflowTooltip` (custom trigger via `setTriggerRef` + `onTriggerPointerEnter`).\n2. **AG Grid custom cell renderers** — `useAgGridTruncationTooltip` from `impact-nova/ag-grid-react` with AG Grid's `setTooltip`. Never wrap grid cell text in `OverflowTooltip`.\n3. **`focusable` defaults to `false`** — pointer-only, safe inside buttons, Select options, and comboboxes. Set `focusable` for standalone keyboard-accessible truncated labels.\n4. **Do not wrap Badge globally** — apply `OverflowTooltip` at call sites when a badge label may truncate.\n5. Measurement is **lazy** (pointerenter / focusin) — no mount-time ResizeObserver.\n\n## Horizontal scroll overflow (ScrollOverflowAffordance)\n\nFor metric rails, chip rows, or any horizontal overflow content with fade edges:\n\n```tsx\nimport { ScrollOverflowAffordance } from 'impact-nova/horizontal-scroller';\n\n<ScrollOverflowAffordance contentDependency={items}>\n  <div className=\"flex gap-2\">{/* overflow children */}</div>\n</ScrollOverflowAffordance>\n```\n\nUse **`HorizontalScroller`** when you have `items[]` + `renderItem`. Use **`useHorizontalScrollOverflow`** for fully custom scroll chrome.\n\n## Calendar / week pickers\n\nWeek range, week picker, Wk gutter, dual-month join: apps should use **`WeekPicker`**, **`WeekRangePicker`**, or **`MultiWeekPicker`** from `impact-nova/date-picker`. Import `Calendar` from `impact-nova/calendar` only for custom chrome. There is no `<FiscalCalendar>` — pass `calendarKind=\"fiscal\"`.\n\n**Do not restyle selected days or the Wk gutter.** Selection language is built in:\n\n- Start/end days are `rounded-lg` brand squares. Do not flatten them when a week range crosses months.\n- Week **range** (`weekMode=\"range\"`) is one connected day block plus one vertical Wk track. Dual-month panes square **only the Wk cells** at the join (last week of the first month / first week of the next).\n- Week **multiple** keeps each week as its own pill.\n- Gutter highlight is pane-local: a clipped Gregorian week ending on the last Monday does not paint the next month’s W01.\n- Interval track tucks under the start/end buttons (Monday `pl-2` must not show accent left of the start square).\n\n```tsx\nimport { WeekRangePicker } from 'impact-nova/date-picker';\n\n<WeekRangePicker label=\"Reporting period\" value={range} onChange={setRange} />\n```\n\n## AG Grid / Data tables (mandatory)\n\n**When working with DataTable, or any data table that uses AG Grid:**\n- **CRITICAL RULE:** If you see a table in a screenshot, or if the user asks for a table by default, you **MUST** use **Impact Nova DataTable** from `impact-nova/data-table`. **Do not build a raw AG Grid or HTML table.**\n- Use **only** AG Grid's official documentation.\n- Follow **only** AG Grid recommended patterns.\n- Rely **only** on the AG Grid API for grid behavior. No deviation.\n- If the user has **ag-mcp** installed, use it for AG Grid API and docs and combine with this MCP for Impact Nova DataTable/column/cell-renderer integration. See resource `impact-nova://ag-grid-rules` for full rules and the default table structure.\n";
+export default "# Impact Nova — Best Practices & Do's and Don'ts\n\n## Use Impact Nova components only\n\n**When building with Impact Nova, use the components that are present in this design system only.** The library includes a full set of UI components (forms, navigation, feedback, data display, layout, etc.). There is no need to create new custom components for standard UI—use what Impact Nova provides. Check `list_components` or the component catalog to see what's available; use `get_component` for the spec and usage of any component. Prefer composing existing Impact Nova components over building from scratch.\n\n## Do's\n\n1. **Use compound components** — Use subcomponents (e.g. `Dialog.Content`, `Card.Header`, `Select.Trigger`) for full control without prop drilling.\n2. **Use `cn()` and Tailwind token classes** — Merge classNames with the `cn()` helper; use design token classes (e.g. `bg-brand`, `text-content`, `border-stroke`) not raw hex or arbitrary values.\n3. **Use design tokens** — Prefer Tailwind theme tokens (colors, spacing, radius from the design system). No arbitrary values where a token exists.\n4. **Accessibility first** — Components are built on Radix UI; preserve aria-labels, keyboard support, and screen reader compatibility. Add `aria-label` for icon-only buttons.\n5. **i18n for user-facing strings and formatting** — Mount `ImpactNovaProviders` from `impact-nova/form` at app root. Use `useImpactNovaI18n()` / `t()` for labels. Format dates/numbers with `formatDate` / `formatNumber` / `formatCurrency` from `impact-nova/i18n` using `dateLocale` / `numberLocale`. Currency is always an explicit ISO code. Do not call `toLocaleString`. See `impact-nova://i18n`.\n6. **File naming** — Use `kebab-case.tsx` for files (e.g. `file-upload.tsx`).\n7. **TypeScript** — Import and extend component props (e.g. `ButtonProps`) for type-safe wrappers.\n8. **Use `variant` and `size` props** — For appearance, use the component's built-in variant and size props (e.g. `Button variant=\"default\" size=\"lg\"`). Add `className` only for layout (e.g. margin, gap) or intentional overrides.\n\n## Don'ts\n\n1. **No inline styles for token-backed values** — Don't use `style={{ color: '...' }}` or inline hex for colors that exist as tokens.\n2. **Don't bypass tokens** — Avoid hardcoded spacing or colors; use Tailwind token classes.\n3. **Don't skip i18n** — For any user-facing label, placeholder, or message, use the i18n context or pass overrides via props. Passing `locale=\"de-DE\"` without `messages={de}` still shows English chrome.\n4. **Don't add unnecessary classNames for styling** — Components are already styled to the design standard. Use `variant` and `size` for appearance. Use `className` only for layout (e.g. `mt-4`, `flex gap-2`) or intentional overrides, not for duplicating built-in styles (e.g. don't add `rounded-lg` if the component already applies it).\n5. **Don't use non-token colors** — Stick to the design token palette (primary, secondary, accent, destructive, muted, etc.).\n6. **Don't create new components when Impact Nova already provides one** — The design system has the components you need. Use `list_components` / `get_component` to find and use them instead of building custom equivalents.\n7. **Error and empty states** — Use **Alert** for form or API errors; use **EmptyContainer** when there is no data to show (with optional action like \"Select filter\" or \"Add item\").\n\n## Composition over inheritance\n\nFavor composition. Compose subcomponents rather than extending or wrapping with custom styling that overrides the design system.\n\n## Imports\n\n**Prefer subpath imports** in production apps for tree-shaking (~98% smaller bundles vs full barrel). Use the barrel only for i18n bootstrapping or when importing many symbols from one area in a single file.\n\n- **Subpath (preferred)**: `import { Button } from 'impact-nova/button';`, `import { Card, CardContent } from 'impact-nova/card';`, `import { DataTable, DataTableContent, useDataTable } from 'impact-nova/data-table';`, `import { FilterPanel, FilterPanelSidebar } from 'impact-nova/filter-panel';`, `import { Combobox } from 'impact-nova/combobox';`\n- **App providers**: `import { ImpactNovaProviders } from 'impact-nova/form';` — mount once at root (i18n + TooltipProvider)\n- **Barrel (locale packs only)**: `import { de } from 'impact-nova';` — OK for locale packs; avoid barrel for UI components\n- **Icons (required peer)**: `npm install impact-nova-icons@^0.1.1` then `import { Pin, Chart } from 'impact-nova-icons';` — use `createIconResolver` from `impact-nova-icons/resolver` for dynamic lookup. Icons are **not** exported from `impact-nova`\n- **Types only**: `import type { Option } from 'impact-nova/select';`, `import type { SavedTableViewItem } from 'impact-nova/data-table';`, `import type { RowSelectionState } from 'impact-nova/virtualized';`\n- **i18n**: `import { useImpactNovaI18n, formatDate, formatNumber, formatCurrency } from 'impact-nova/i18n';`\n- **Locale packs**: `import { de } from 'impact-nova/locale/de';` (also `es`, `hi`, `kn`). Formatting locales are any valid BCP 47 tag; packs are opt-in.\n- **CSS (once at root)**: `import 'impact-nova/dist/impact-nova.css';` — or split layers: `impact-nova/impact-nova-tokens.scss`, `impact-nova/impact-nova-base.scss`, `impact-nova/impact-nova-components.css`\n\n**Vite consumers:** add `resolve.dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react']` to avoid dual React/AG Grid instances. Exclude `impact-nova-icons` from `optimizeDeps` to prevent SVG asset warnings. Pre-bundle Highcharts modules in `optimizeDeps.include` if using Chart.\n\n## Truncated text tooltips (OverflowTooltip)\n\nUse **`OverflowTooltip`** from `impact-nova/tooltip` when CSS truncation (`truncate`, `line-clamp`) may clip content and you want a tooltip **only when overflow is detected**.\n\n```tsx\nimport { OverflowTooltip } from 'impact-nova/tooltip';\n\n<OverflowTooltip content={fullLabel}>\n  <span className=\"truncate\">{fullLabel}</span>\n</OverflowTooltip>\n```\n\n**Rules:**\n\n1. **General UI** — `OverflowTooltip` or headless `useOverflowTooltip` (custom trigger via `setTriggerRef` + `onTriggerPointerEnter`).\n2. **AG Grid custom cell renderers** — `useAgGridTruncationTooltip` from `impact-nova/ag-grid-react` with AG Grid's `setTooltip`. Never wrap grid cell text in `OverflowTooltip`.\n3. **`focusable` defaults to `false`** — pointer-only, safe inside buttons, Select options, and comboboxes. Set `focusable` for standalone keyboard-accessible truncated labels.\n4. **Do not wrap Badge globally** — apply `OverflowTooltip` at call sites when a badge label may truncate.\n5. Measurement is **lazy** (pointerenter / focusin) — no mount-time ResizeObserver.\n\n## Horizontal scroll overflow (ScrollOverflowAffordance)\n\nFor metric rails, chip rows, or any horizontal overflow content with fade edges:\n\n```tsx\nimport { ScrollOverflowAffordance } from 'impact-nova/horizontal-scroller';\n\n<ScrollOverflowAffordance contentDependency={items}>\n  <div className=\"flex gap-2\">{/* overflow children */}</div>\n</ScrollOverflowAffordance>\n```\n\nUse **`HorizontalScroller`** when you have `items[]` + `renderItem`. Use **`useHorizontalScrollOverflow`** for fully custom scroll chrome.\n\n## Calendar / week pickers\n\nWeek range, week picker, Wk gutter, dual-month join: apps should use **`WeekPicker`**, **`WeekRangePicker`**, or **`MultiWeekPicker`** from `impact-nova/date-picker`. Import `Calendar` from `impact-nova/calendar` only for custom chrome. There is no `<FiscalCalendar>` — pass `calendarKind=\"fiscal\"`.\n\n**Do not restyle selected days or the Wk gutter.** Selection language is built in:\n\n- Start/end days are `rounded-lg` brand squares. Do not flatten them when a week range crosses months.\n- Week **range** (`weekMode=\"range\"`) is one connected day block plus one vertical Wk track. Dual-month panes square **only the Wk cells** at the join (last week of the first month / first week of the next).\n- Week **multiple** keeps each week as its own pill.\n- Gutter highlight is pane-local: a clipped Gregorian week ending on the last Monday does not paint the next month’s W01.\n- Interval track tucks under the start/end buttons (Monday `pl-2` must not show accent left of the start square).\n\n```tsx\nimport { WeekRangePicker } from 'impact-nova/date-picker';\n\n<WeekRangePicker label=\"Reporting period\" value={range} onChange={setRange} />\n```\n\n## AG Grid / Data tables (mandatory)\n\n**When working with DataTable, or any data table that uses AG Grid:**\n- **CRITICAL RULE:** If you see a table in a screenshot, or if the user asks for a table by default, you **MUST** use **Impact Nova DataTable** from `impact-nova/data-table`. **Do not build a raw AG Grid or HTML table.**\n- Use **only** AG Grid's official documentation.\n- Follow **only** AG Grid recommended patterns.\n- Rely **only** on the AG Grid API for grid behavior. No deviation.\n- If the user has **ag-mcp** installed, use it for AG Grid API and docs and combine with this MCP for Impact Nova DataTable/column/cell-renderer integration. See resource `impact-nova://ag-grid-rules` for full rules and the default table structure.\n- Cell comments, AG Grid notes, and row Chat are **separate** `DataTableContent` opt-ins. Fetch `impact-nova://data-table-comments`, `impact-nova://data-table-notes`, or `impact-nova://data-table-chat` before implementing. Do not invent APIs or store threads in `rowData`.\n";

package/dist/llms/rules/data-table-chat.js

@@ -0,0 +1 @@
+export default "> MCP resource `impact-nova://data-table-chat`. Follow this guide — do not invent APIs or put threads in `rowData`.\n\n# DataTable row Chat\n\nMCP resource: **`impact-nova://data-table-chat`**.\n\nLearning path for enabling **row Chat** on Impact Nova `DataTable`.\n\nStorybook: **Data Display / DataTable / Chat / QuickStart**.\n\nChat is **not** a cell comment and **not** an AG Grid Note.\n\n- Comment → cell `{ rowId, colId }`\n- Note → cell text\n- Chat → **row** `{ rowId }` from `getRowId`, with **many conversations** per row\n- Thread reply → `{ rowId, conversationId, parentId }`\n- Pin → a flag on a message in that conversation\n\n## 1. Opt-in\n\nOmit `chat` and the grid is unchanged: no Chat column, host, listeners, or fetch.\n\n```tsx\n<DataTableContent getRowId={(params) => params.data.id} chat={chat} />\n```\n\nRequired:\n\n| Piece | Why |\n|---|---|\n| `getRowId` | Stable row identity. Never `rowIndex` or a DOM node |\n| `hasConversation` | O(1) presence for visible Chat cells |\n| `loadConversation` | Newest window (50) for `{ rowId, conversationId }` + `before` cursor for older messages |\n| `persist` | One event (`create-conversation` or one message), not the lifetime array |\n| `getAuthor` | Name stamped on new messages |\n\nOptional: `unreadCount`, `getSummaries` (rows list + per-row chats), `locateRow` (required for app-paged / SSRM), `column: false`, `colId`, `priority(rowId)` (`high` / `medium` / `low`), `quickActions`, `messageActions` / `threadActions` / `listActions`, `composerTools`, `listPeople({ query, limit })` (directory for Add member; Nova shows 10 after excluding current members), `can(action, context)` (authorization), `renderComposer` / `renderAvatar` / `renderMessageBody` / `renderMembers` / `renderPeoplePicker`.\n\nComposer ships **attach file / image** (local `File` → object URL until persist writes it), **emoji**, **bold / italic / link**, and a **Quick action** menu from `composerTools` (omit the menu when you pass none). Nova does not own product verbs. An offer table passes “Finalize offer”, a ticket table passes “Resolve”, a request table passes “Complete” — each `onSelect` writes the row, then calls `context.close()` to dismiss Chat. Stay-in-thread tools use `context.insertText(...)` instead. The same `close()` is on `quickActions`, `messageActions`, `threadActions`, and `listActions`. Persist `set-priority` with `high` / `medium` / `low`, or `null` to clear (Normal). Message-row and composer checkmarks set priority. Conversation **⋯** is notify + mute (`set-notify`, `mute-conversation`) — not priority. Persist `set-members` when adding or removing people; omit `listPeople` for a read-only member list derived from authors.\n\n`loadConversation` may be **client-windowed** (return the full array; Nova keeps the newest 50 and `before` for older) or **server-windowed** (return only the requested page plus `hasMoreOlder`). The thread virtualizes after 32 messages, follows a new latest message when you are near the bottom (WhatsApp-style), and does not jump on load-older prepend.\n\n## 2. System column\n\nDefault injects pinned-right `iv-chat` (69px). It is excluded from the column tree, saved views, auto-size, and export. Do not persist it in consumer column state.\n\n## 3. Pagination\n\n- **Client pagination:** all rows stay in the model. Nova uses live `rowIndex`. Do not pass `locateRow`.\n- **Server / app-paged:** `getRowNode` is missing. Pass `locateRow(rowId)` and load the page (see Comments `ServerPagedCommentsDemo`). Chat opens for that `rowId` immediately.\n\nFiltered rows (`rowIndex == null`) open Chat with **Hidden by current filter**. Nova does not call `locateRow`.\n\n## 4. Panel\n\nChat uses a right **Sheet** (`impact-nova/sheet`) — not FilterPanel and not DataTableSheet. Widths are Chat-owned: catalog 840px, row-chats 340 + 640 min. Pinned/thread shares the remaining width with the main thread (up to 640px each, shrinks with the viewport). Scroll, virtualize, sort, and paginate do not retarget the open row.\n\n- Toolbar **Chats** opens unique **row names**. Click a row to see its chats.\n- Chat cell opens that row’s chats. **+ Chat** starts another conversation on the same row.\n- Back returns to the unique-row list.\n\nEmpty lists use `EmptyContainer` (`impact-nova/empty-container`).\n\nThe thread header cluster (pin + avatars, or `AddUser` when empty) opens the **Info** drawer. Thread replies open the **Thread** drawer. The drawer shares width with the main thread (up to 640px each) and shrinks with the viewport. `loadConversation` receives `purpose: \"page\" | \"thread\" | \"pinned\"`. Persist `pin-message`, `add-message` with `parentId`, `edit-message`, and `delete-message`. Do not add a WebSocket layer inside Nova.\n\nThe **Info** drawer is the WhatsApp-style panel: pinned cards and members share the height like VS Code sidebars. Each chevron has three angles: **45° split**, **90° expanded**, **0° collapsed**. Expanding one collapses the other to its header.\n\n## 5. Mapping your backend\n\nNova never sees REST URLs or vendor DTOs. `loadConversation`, `listPeople`, `getSummaries`, and `persist` **are** the adapters.\n\n```ts\ntype PeopleDto = { user_id: string; display_name: string; avatar_url?: string; role?: string }\n\nlistPeople: async ({ query, limit } = {}) => {\n  const json = await api.getPeople({ query, limit })\n  return json.users.map((row: PeopleDto) => ({\n    id: row.user_id,\n    name: row.display_name,\n    avatarUrl: row.avatar_url,\n  }))\n}\n```\n\nApply the same mapping in `loadConversation` for `conversation.members` and in `persist` when you write `set-members` back. Nova's member model is `{ id, name, avatarUrl? }`. Roles stay in the consumer; do not send them in for Nova to interpret.\n\n## 6. Permissions\n\nImpact Nova is not the source of truth for authorization. Pass `can(action, context)`:\n\n| Action | Default when `can` is omitted |\n|---|---|\n| `view` / `create` / `edit` / `delete` | `getCapabilities(rowId)` (`canEdit` / `canDelete` default false) |\n| `invite` / `remove-member` | `canCreate` **and** `listPeople` is provided |\n\nReturn `true` or `false` to override one action. Return `undefined` to use the default.\n\n```ts\ncan: (action, context) => {\n  if (action === \"invite\" || action === \"remove-member\") return isAdmin(context.rowId)\n  if (action === \"edit\") return context.message?.author === currentUser\n  return undefined\n}\n```\n\nA visible button is not a grant. If `persist` throws `{ status: 403 }` or `{ status: 401 }`, Nova rolls back optimistic member changes and toasts permission denied.\n\nLeave / transfer-ownership are not Chat domain verbs. Put them on `listActions` and call your API, then `context.close()` if the user left.\n\n## 7. Composition\n\nChat is a DataTable opt-in, same as Comments — not a Radix `<Chat><ChatHeader/></Chat>` tree. Zero-config is `chat={config}`. Escape hatches replace one piece:\n\n| Slot | Replaces |\n|---|---|\n| `renderAvatar` | Author glyph (`{ author, member? }`) |\n| `renderMessageBody` | Message text |\n| `renderComposer` | Reply box (host still owns draft + persist) |\n| `renderMembers` | Info-drawer roster |\n| `renderPeoplePicker` | Add-member directory |\n| `renderMessageActions` / `renderThreadActions` | `…` menus |\n| `messageActions` / `threadActions` / `listActions` / `quickActions` / `composerTools` | Extra actions Nova does not understand |\n\nDo not rebuild Chat to add “Open purchase order”. Add a `ChatUiAction` and handle it in `onSelect`.\n\n## 8. Members UX\n\n**Add member** is the first row in the members list. It opens a full-panel directory (search, first 10 people, multi-select). Persist `set-members` plus `add-message` with `system: true` so the thread shows “{{name}} was added” / “{{name}} was removed”. If the toolbar has no members yet, it shows `AddUser` from `impact-nova-icons`.\n\nThe on-screen roster is bounded (40, then Show more). `listPeople` runs when the picker opens — never once per grid row.\n\n## Related\n\n- [data-table-comments.md](impact-nova://data-table-comments)\n- [data-table-notes.md](impact-nova://data-table-notes)\n";

package/dist/llms/rules/data-table-comments.js

@@ -0,0 +1 @@
+export default "> MCP resource `impact-nova://data-table-comments`. Follow this guide — do not invent APIs or put threads in `rowData`.\n\n# DataTable cell comments\n\nMCP resource: **`impact-nova://data-table-comments`**.\n\nLearning path for enabling Google Sheets–style **cell comments** on Impact Nova `DataTable`.\n\nStorybook: **Data Display / DataTable / Comments / QuickStart**.\n\nThis is **not** AG Grid Notes, and there is **no** read/unread model.\n\n## 1. What is a comment?\n\nA comment is a conversation attached to a **logical cell**:\n\n```\ngrid + getRowId(row) + colId  →  CellAddress { rowId, colId }\n```\n\nThe thread lives in **your** store (or API). It is not a field on `rowData`. The cell triangle is only painted when that cell is currently rendered.\n\nThe overlay is shown only while that logical cell intersects the usable grid viewport (below the header, not under a pinned column). Scroll it fully away and the overlay hides; scroll it back and the same thread restores, including an unsaved draft. Explicit close (X / Escape / click outside) ends the session. Use the Comments panel to keep a list while navigating.\n\n## 2. What is not a comment?\n\n- AG Grid Notes — a separate opt-in on `notes={...}`; see [data-table-notes.md](impact-nova://data-table-notes)\n- Read/unread, badges, or per-cell React widgets\n- Storing `page` or frozen `rowIndex` on the thread (filters change the live index)\n\n## 3. Quick start (required)\n\nStart at Storybook **QuickStart**. Copy the Docs source.\n\nRequired:\n\n| Piece | Why |\n|---|---|\n| `getRowId` | Stable row identity |\n| `comments.hasIndicator` | O(1). `true` only for **unresolved** threads that should show the triangle |\n| `comments.loadThread` | Fetch the thread for an address |\n| `comments.persist` | Create / reply / edit / delete / resolve |\n| `comments.getAuthor` | Name stamped on new messages |\n\nOptional:\n\n| Piece | Why |\n|---|---|\n| `getSummaries` | Comments list in `DataTableSheet` |\n| `locateRow` | Row is **not** in the current grid model (SSRM / app-paged `rowData`) |\n| `getCapabilities` | View-only vs edit per cell |\n| `commentMode` / `CommentModeToggle` | Click empty cells to compose |\n| `loadThread` `request` | Windowed thread history (`preview` \\| `page`) |\n\n```tsx\nimport { DataTable, DataTableContent, DataTableToolbar } from \"impact-nova/data-table\";\nimport {\n  CommentModeToggle,\n  defaultGetThreadId,\n  type DataTableCommentsConfig,\n} from \"impact-nova/ag-grid-react/comments\";\n\n<DataTable className=\"h-[640px]\">\n  <DataTableToolbar>\n    <CommentModeToggle pressed={commentMode} onPressedChange={setCommentMode} />\n  </DataTableToolbar>\n  <DataTableContent\n    getRowId={(params) => params.data.id}\n    columnDefs={columnDefs}\n    rowData={rowData}\n    comments={comments}\n  />\n</DataTable>\n```\n\nOmit `comments` entirely to disable the feature. Nova will not mount the comments host.\n\n## 4. Right-click → Add comment\n\nWith `comments` set, the grid context menu includes **Add comment** (native AG Grid note items are stripped). Comment mode is **not** required.\n\nStory: **AddComment**. Persist event: `{ type: \"add-message\", threadId, address, message }`.\n\n## 5. Client-side grid\n\nAll rows in `rowData` (CSRM). Optional AG Grid `pagination` only changes what is painted.\n\n- Comment store is still separate\n- Panel click: `getRowNode(rowId)` → live `rowIndex` → `paginationGoToPage` → `ensureIndexVisible`\n- Do **not** implement `locateRow`\n\nStory: **ClientSidePagination**.\n\n## 6. Server-side / app-paged grid\n\nOnly the current page/block is in the grid model. The comment still exists.\n\n1. Panel (or your UI) identifies `{ rowId, colId }`\n2. `getRowNode(rowId)` misses\n3. `comments.locateRow(address)` loads that page into the grid (your API)\n4. Return `{ status: \"ready\" }` or `{ status: \"ready\", rowIndex }`\n5. Nova reveals the cell and opens the overlay\n\nFiltered-out rows (`rowIndex == null`) stay **Not in current view**. `locateRow` is not called for those.\n\nStory: **ServerSidePagination**.\n\n## 7. Three different “pages”\n\n| Kind | What it pages | Config |\n|---|---|---|\n| Grid | Which rows AG Grid has loaded/painted | `pagination` / SSRM / your `rowData` slice |\n| Comments list | Which thread **summaries** are in the sheet | `getSummaries({ cursor, limit, query })` |\n| Thread history | Which **messages** are in the overlay | `loadThread(..., { purpose, limit, before })` |\n\nThese are independent. A 10,000-message thread is still one cell.\n\n## 8. Cell identity\n\nUse `getRowId` + stable `colId`. Default thread id is `rowId + \"\\\\0\" + colId` (`defaultGetThreadId`). Override `getThreadId` only if column ids regenerate.\n\nDo not key comments by DOM nodes, rendered cell components, or array indexes.\n\n## 9. Thread lifecycle\n\nCreate → reply → resolve → reopen. Indicator is on **unresolved** threads only.\n\nStories: **Lifecycle**, **Loading**, **PersistError**, **ReadOnly**.\n\n## 10. Large scale\n\n`hasIndicator` must be O(1). Overlay holds **one** windowed thread. Panel virtualizes summaries. Story: **LargeScale** (50k columns) — architecture proof, not the copy-paste starter.\n\n## 11. Appearance (optional)\n\nThe default UI is already production-ready. Omit every field below to keep it.\n\n**Level 1 — CSS.** Set variables on a wrapper (they inherit):\n\n```css\n.planning-grid {\n  --iv-comment-indicator-color: var(--color-success);\n  --iv-comment-indicator-size: 12px;\n}\n```\n\nStable hooks (popover is portaled): `[data-iv-comments]`, `[data-slot=\"comments-popover\"]`, `[data-slot=\"comments-header\"]`, `[data-slot=\"comments-message\"]`, `[data-slot=\"comments-composer\"]`, `[data-slot=\"comments-panel\"]`.\n\nIndicator shape stays CSS `::after` (no per-cell React).\n\n**Level 2 — extra menu items.** Append after Edit/Delete without replacing the menu:\n\n```tsx\ncomments={{\n  hasIndicator,\n  loadThread,\n  persist,\n  getAuthor,\n  messageActions: [\n    {\n      id: \"open\",\n      label: \"Open\",\n      onSelect: ({ address, message }) => openRecord(address, message.id),\n    },\n  ],\n}}\n```\n\n`threadActions` appends after Delete thread on the overlay and panel `…` menus.\n\n**Level 3 — replace one piece.** Unspecified slots keep Nova defaults:\n\n```tsx\ncomments={{\n  hasIndicator,\n  loadThread,\n  persist,\n  getAuthor,\n  renderAvatar: ({ author }) => <YourAvatar name={author} />,\n}}\n```\n\nAlso available: `renderMessageBody`, `renderComposer`, `renderMessageActions` (receives Edit/Delete plus `messageActions`), `renderThreadActions`.\n\nThese render only while the overlay or panel is open. They do not run per cell.\n\n**Not customizable (intentionally):** overlay anchoring, cell identity, persistence, virtualization, AG Grid presence, Comment indicator as a React component.\n\n## 12. API reference\n\nTypes and helpers: `impact-nova/ag-grid-react/comments`.\n\nSee `DataTableCommentsConfig` in that subpath. Contributor tripwire: `src/components/data/ag-grid-react/comments/comments.decisions.md`.\n\n## 13. Testing\n\nStorybook `play` functions under **Data Display / DataTable / Comments** are the behavioural suite (`npm run test:storybook`). Unit tests live next to `comments/*.ts`.\n";

package/dist/llms/rules/data-table-notes.js

@@ -0,0 +1 @@
+export default "> MCP resource `impact-nova://data-table-notes`. Follow this guide — do not invent APIs or put threads in `rowData`.\n\n# DataTable cell notes\n\nMCP resource: **`impact-nova://data-table-notes`**.\n\nAG Grid **Notes** on Impact Nova `DataTable`. A note is short text on a logical cell. A **comment** is a conversation. They can coexist.\n\nStorybook: **Data Display / DataTable / Notes / QuickStart**.\n\n## When to use Notes vs Comments\n\n- **Note** — cell-specific text (override reason, reminder). AG Grid owns the popup and menu.\n- **Comment** — thread with replies, resolve/reopen. Nova owns the overlay.\n\n## Enable Notes\n\n```tsx\nimport { DataTable, DataTableContent } from \"impact-nova/data-table\";\nimport type { DataTableNotesConfig } from \"impact-nova/ag-grid-react/notes\";\n\n<DataTableContent\n  getRowId={(params) => params.data.id}\n  notes={notes}\n  columnDefs={columnDefs}\n  rowData={rowData}\n/>\n```\n\n`getNote` / `setNote` are keyed by `{ rowId, colId }`. Omit `notes` for zero Notes work.\n\n## Same cell\n\nBlue triangle = Comment. Yellow = Note. Split blue/yellow = both. Hover opens the AG Grid note. Context menu keeps comment actions and native note actions.\n\n## Appearance (optional)\n\nUnset variables keep the Nova yellow default. No Notes component map.\n\n```css\n.planning-grid {\n  --iv-note-indicator-color: var(--color-destructive);\n  --iv-note-indicator-size: 12px;\n  --iv-note-popup-background: var(--color-warning-surface);\n  --iv-note-popup-text: var(--color-foreground);\n  --iv-note-popup-input-background: var(--color-background);\n  --iv-note-popup-border: 1px solid var(--color-warning-border);\n}\n```\n\nThe popup shell is AG Grid’s `.ag-notes-popup`. Nova only tokenises it via `--ag-note-*` mapped from the `--iv-note-*` knobs above. Do not replace the native editor with a React slot. Extra Comment `messageActions` still work on the same grid — they are Comment overlay items, not AG Grid note menu items.\n\n## Performance\n\nOpt-in. `getNote` runs for painted cells only. No per-cell React. 50,000+ columns use AG Grid column virtualization.\n";

package/dist/llms/rules/installation.js

@@ -1 +1 @@
-export default "# Install and configure Impact Nova\n\nUse these steps to add Impact Nova to an existing project. Run the commands in your project root and apply the code changes to your entry file and layout.\n\n## 0. Scaffold a new app (recommended)\n\n**`create-impact-nova@^1.4.9`** is on npm. Scaffold auto-detects dependency mode:\n\n| Where you run | `impact-nova` dependency |\n|---------------|--------------------------|\n| Published CLI / MCP (outside monorepo) | `impact-nova@^2.5.15` from npm (`latest` tag) |\n| Inside impact-nova monorepo | `file:` link to repo root |\n\n```bash\nnpx create-impact-nova my-dashboard\ncd my-dashboard\nnpm run dev\n```\n\nMCP: **`scaffold_impact_nova_app`** with `projectName` and optional `modules[]` from the user prompt.\n\n**Overrides:** CLI `--from-npm` · `--link-monorepo` · MCP `usePublishedPackages: true | false`\n\n```bash\nnpx create-impact-nova my-dashboard --from-npm\n```\n\nBase template is shell-only (Home + shared primitives). Feature pages come from recipes — see `create-impact-nova/recipes/README.md`.\n\n**Local link in an existing app** (manual):\n\n```bash\nnpm install impact-nova@file:../path-to-impact-nova-repo\n```\n\nRun `npm run build` in the impact-nova repo after design-system changes.\n\n## 1. Install the package and peer dependencies\n\n```bash\nnpm install impact-nova impact-nova-icons\nnpm install react@^19 react-dom@^19\n```\n\n**Required peers:** `react@^19`, `react-dom@^19`, `impact-nova-icons@^0.1.1`\n\n**Optional peers** (install when you use these features):\n\n| Package | Version | When needed |\n|---------|---------|-------------|\n| `ag-grid-community` | `36.0.1` | AG Grid types/API (pin with react + enterprise) |\n| `ag-grid-react` | `36.0.1` | DataTable / AG Grid |\n| `ag-grid-enterprise` | `36.0.1` | Enterprise grid features |\n| `highcharts` | `^12` | Chart component |\n| `highcharts-react-official` | `^3` | Chart component |\n| `highcharts-border-radius` | `^0.0.4` | Rounded chart corners |\n\nIf you use AG Grid or Highcharts in your app, also install:\n\n```bash\nnpm install ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1\n# Optional, for charts:\nnpm install highcharts@^12 highcharts-react-official@^3 highcharts-border-radius@^0.0.4\n```\n\n## 2. Import styles in your root entry\n\nIn your app root (e.g. `main.tsx`, `App.tsx`, or `layout.tsx`), **import the CSS before your app component**:\n\n```tsx\nimport 'impact-nova/dist/impact-nova.css';\nimport App from './App';\n// ... rest of your bootstrap\n```\n\n## 3. Add Manrope font (recommended)\n\nIn your `index.html` or layout:\n\n```html\n<link href=\"https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap\" rel=\"stylesheet\" />\n```\n\nIn your global CSS or Tailwind base:\n\n```css\n@layer base {\n  body {\n    font-family: 'Manrope', sans-serif;\n  }\n}\n```\n\n## 4. Wrap your app with providers (recommended)\n\nMount **`ImpactNovaProviders`** once at the app root. It bundles i18n (`ImpactNovaI18nProvider`) and `TooltipProvider` (required for tooltips since v2.0.8):\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\n\nfunction Root() {\n  return (\n    <ImpactNovaProviders locale=\"en\">\n      <App />\n    </ImpactNovaProviders>\n  );\n}\n```\n\nFor another locale, pass a locale pack:\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\nimport { de } from 'impact-nova/locale/de';\n\n<ImpactNovaProviders locale=\"de\" messages={de}>\n  <App />\n</ImpactNovaProviders>\n```\n\n**Barrel exception:** locale packs may use `import { de } from 'impact-nova'`. All UI components still use subpaths (see §5).\n\n## 5. Subpath imports (recommended)\n\nPrefer subpath imports in feature code for tree-shaking:\n\n```tsx\nimport { Button } from 'impact-nova/button';\nimport { Card, CardContent } from 'impact-nova/card';\nimport { DataTable, DataTableContent, useDataTable } from 'impact-nova/data-table';\nimport { CheckCircle } from 'impact-nova-icons';\n```\n\nThe barrel `import { Button } from 'impact-nova'` still works but pulls a larger module graph. **Use subpaths for all UI components**; reserve the barrel for locale packs at app root only. Use `ImpactNovaProviders` from `impact-nova/form` for app setup.\n\n## 6. Using Impact Nova with CSS or SCSS (no Tailwind)\n\nIf your app uses **plain CSS or SCSS** and does **not** use Tailwind, you can still use Impact Nova. Tailwind is optional. Impact Nova ships a single built CSS file (no SCSS source).\n\n- **Import the library CSS** in your app root (e.g. `main.tsx`, `App.tsx`):\n  ```tsx\n  import 'impact-nova/dist/impact-nova.css';\n  ```\n  **CSS split exports** (optional, for layered theming): `impact-nova/impact-nova-tokens.scss`, `impact-nova/impact-nova-base.scss`, `impact-nova/impact-nova-components.css`\n  Or from your main stylesheet: `@import 'impact-nova/dist/impact-nova.css';` in your main.css or main.scss.\n- **Component styling** comes from Impact Nova's CSS. Use each component's `variant` and `size` props; no Tailwind classes are required.\n- **Your layout and spacing** stay in your CSS or SCSS (margins, padding, flexbox, grid). Use your usual class names; the design system does not require Tailwind utilities.\n- **Manrope font:** Add the font link in `index.html` and in your CSS/SCSS set `body { font-family: 'Manrope', sans-serif; }` (see section 3).\n- **Summary:** No Tailwind, no Tailwind config. Load `impact-nova.css` once; use components with their props; use your existing CSS/SCSS for the rest.\n\n## 6b. Theming in consumer apps\n\n| Surface | What ships |\n|---------|------------|\n| **npm / consumer apps** | **Impact Light** only — `import 'impact-nova/dist/impact-nova.css'` (from `src/theme/tokens/light.json`) |\n| **Storybook / dev** | 10 curated **theme presets** (Impact Dark, Midnight, Ocean, …) — preview switcher only |\n\n**Do not** copy Storybook preset JSON or `theme-presets.ts` into consumer apps. Presets are not in the published package.\n\n**Custom branding:** override CSS variables on `:root` or a scoped class (e.g. `.my-brand`). Use Storybook **Theme Builder** / **Token Catalog** to explore tokens, then export CSS/JSON for your overrides.\n\n## 7. Using Impact Nova with Webpack\n\nIf your app is built with **Webpack** (including Create React App, which uses Webpack):\n\n- **CSS import:** Webpack will bundle the library CSS as long as you have a rule for `.css`. Ensure your config includes something like:\n  ```js\n  module: {\n    rules: [\n      {\n        test: /\\.css$/,\n        use: ['style-loader', 'css-loader'],\n        // or with MiniCssExtractPlugin:\n        // use: [MiniCssExtractPlugin.loader, 'css-loader'],\n      },\n      // ... other rules (e.g. for .tsx, .js)\n    ],\n  },\n  ```\n  Then in your root component or entry:\n  ```tsx\n  import 'impact-nova/dist/impact-nova.css';\n  ```\n- **Create React App (CRA):** No extra config. Add `import 'impact-nova/dist/impact-nova.css';` in `index.tsx` or `App.tsx`.\n- **Dedupe React / AG Grid:** If you see “multiple copies of React” or AG Grid issues, use Webpack’s `resolve.alias` so the app uses a single version:\n  ```js\n  resolve: {\n    alias: {\n      react: path.resolve(__dirname, 'node_modules/react'),\n      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),\n      // If using AG Grid:\n      'ag-grid-react': path.resolve(__dirname, 'node_modules/ag-grid-react'),\n      'ag-grid-community': path.resolve(__dirname, 'node_modules/ag-grid-community'),\n      'ag-grid-enterprise': path.resolve(__dirname, 'node_modules/ag-grid-enterprise'),\n    },\n  },\n  ```\n- **Tailwind + Webpack:** If you use Tailwind, add the Impact Nova preset and include the package in `content` (see section 7 below).\n\n## 8. Optional: extend Tailwind with Impact Nova preset\n\nIf your project uses Tailwind and you want the same theme (colors, radius), extend your `tailwind.config.js` with the preset from the package:\n\n```js\n// tailwind.config.js\nimport impactNovaPreset from 'impact-nova/tailwind.config.js';\n// → dist/tailwind.config.js (bundled theme; no package src/ required)\n\nexport default {\n  presets: [impactNovaPreset],\n  content: [\n    './index.html',\n    './src/**/*.{js,ts,jsx,tsx}',\n    './node_modules/impact-nova/dist/**/*.js',\n  ],\n  // ... rest of your config\n};\n```\n\n## Summary checklist\n\n- [ ] `npm install impact-nova impact-nova-icons` (and react, react-dom; optional: ag-grid, highcharts)\n- [ ] `import 'impact-nova/dist/impact-nova.css'` in root entry (or @import in main.css/main.scss if using CSS or SCSS without Tailwind; see §6)\n- [ ] Add Manrope font link and body font-family\n- [ ] Wrap app with `<ImpactNovaProviders locale=\"en\">` from `impact-nova/form`\n- [ ] Use subpath imports in feature code (see §5)\n- [ ] (Optional) Add Tailwind preset and content path for impact-nova\n- [ ] **Webpack:** Ensure a CSS rule (style-loader + css-loader) and, if needed, resolve.alias for React/AG Grid\n\nAfter this, import components via subpaths: `import { Button } from 'impact-nova/button';`\n\n## 9. Dashboard app shell (optional)\n\nTo scaffold a full dashboard (sidebar, header, breadcrumb, filters), read resource **`impact-nova://layout`** or call `get_real_world_patterns` with `topic: \"layout\"`. Use `Layout` from `impact-nova/layout` — not `DynamicLayout` (grid/flex utility only).\n";
+export default "# Install and configure Impact Nova\n\nUse these steps to add Impact Nova to an existing project. Run the commands in your project root and apply the code changes to your entry file and layout.\n\n## 0. Scaffold a new app (recommended)\n\n**`create-impact-nova@^1.4.9-alpha.0`** is on npm. Scaffold auto-detects dependency mode:\n\n| Where you run | `impact-nova` dependency |\n|---------------|--------------------------|\n| Published CLI / MCP (outside monorepo) | `impact-nova@^2.6.0-alpha.0` from npm (`latest` tag) |\n| Inside impact-nova monorepo | `file:` link to repo root |\n\n```bash\nnpx create-impact-nova my-dashboard\ncd my-dashboard\nnpm run dev\n```\n\nMCP: **`scaffold_impact_nova_app`** with `projectName` and optional `modules[]` from the user prompt.\n\n**Overrides:** CLI `--from-npm` · `--link-monorepo` · MCP `usePublishedPackages: true | false`\n\n```bash\nnpx create-impact-nova my-dashboard --from-npm\n```\n\nBase template is shell-only (Home + shared primitives). Feature pages come from recipes — see `create-impact-nova/recipes/README.md`.\n\n**Local link in an existing app** (manual):\n\n```bash\nnpm install impact-nova@file:../path-to-impact-nova-repo\n```\n\nRun `npm run build` in the impact-nova repo after design-system changes.\n\n## 1. Install the package and peer dependencies\n\n```bash\nnpm install impact-nova impact-nova-icons\nnpm install react@^19 react-dom@^19\n```\n\n**Required peers:** `react@^19`, `react-dom@^19`, `impact-nova-icons@^0.1.1`\n\n**Optional peers** (install when you use these features):\n\n| Package | Version | When needed |\n|---------|---------|-------------|\n| `ag-grid-community` | `36.0.1` | AG Grid types/API (pin with react + enterprise) |\n| `ag-grid-react` | `36.0.1` | DataTable / AG Grid |\n| `ag-grid-enterprise` | `36.0.1` | Enterprise grid features |\n| `highcharts` | `^12` | Chart component |\n| `highcharts-react-official` | `^3` | Chart component |\n| `highcharts-border-radius` | `^0.0.4` | Rounded chart corners |\n\nIf you use AG Grid or Highcharts in your app, also install:\n\n```bash\nnpm install ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1\n# Optional, for charts:\nnpm install highcharts@^12 highcharts-react-official@^3 highcharts-border-radius@^0.0.4\n```\n\n## 2. Import styles in your root entry\n\nIn your app root (e.g. `main.tsx`, `App.tsx`, or `layout.tsx`), **import the CSS before your app component**:\n\n```tsx\nimport 'impact-nova/dist/impact-nova.css';\nimport App from './App';\n// ... rest of your bootstrap\n```\n\n## 3. Add Manrope font (recommended)\n\nIn your `index.html` or layout:\n\n```html\n<link href=\"https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap\" rel=\"stylesheet\" />\n```\n\nIn your global CSS or Tailwind base:\n\n```css\n@layer base {\n  body {\n    font-family: 'Manrope', sans-serif;\n  }\n}\n```\n\n## 4. Wrap your app with providers (recommended)\n\nMount **`ImpactNovaProviders`** once at the app root. It bundles i18n (`ImpactNovaI18nProvider`) and `TooltipProvider` (required for tooltips since v2.0.8):\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\n\nfunction Root() {\n  return (\n    <ImpactNovaProviders locale=\"en\">\n      <App />\n    </ImpactNovaProviders>\n  );\n}\n```\n\nFormatting locales are BCP 47 tags, not an enum. Pass a regional tag for dates/numbers, and a message pack only when you want translated chrome. `locale=\"de-DE\"` does not auto-load German copy.\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\nimport { de } from 'impact-nova/locale/de';\n\n<ImpactNovaProviders locale=\"de-DE\" messages={de}>\n  <App />\n</ImpactNovaProviders>\n```\n\nIndependent date/number locales:\n\n```tsx\n<ImpactNovaProviders\n  locale=\"de-DE\"\n  dateLocale=\"en-GB\"\n  numberLocale=\"en-US\"\n  messages={de}\n>\n```\n\nFormat with `formatDate` / `formatNumber` / `formatCurrency` from `impact-nova/i18n`. Currency is always explicit. Full contract: resource `impact-nova://i18n`.\n\n**Locale packs:** `import { de } from 'impact-nova/locale/de'` (also `es`, `hi`, `kn`). All UI components still use subpaths (see §5).\n\n## 5. Subpath imports (recommended)\n\nPrefer subpath imports in feature code for tree-shaking:\n\n```tsx\nimport { Button } from 'impact-nova/button';\nimport { Card, CardContent } from 'impact-nova/card';\nimport { DataTable, DataTableContent, useDataTable } from 'impact-nova/data-table';\nimport { CheckCircle } from 'impact-nova-icons';\n```\n\nThe barrel `import { Button } from 'impact-nova'` still works but pulls a larger module graph. **Use subpaths for all UI components**; reserve the barrel for locale packs at app root only. Use `ImpactNovaProviders` from `impact-nova/form` for app setup.\n\n## 6. Using Impact Nova with CSS or SCSS (no Tailwind)\n\nIf your app uses **plain CSS or SCSS** and does **not** use Tailwind, you can still use Impact Nova. Tailwind is optional. Impact Nova ships a single built CSS file (no SCSS source).\n\n- **Import the library CSS** in your app root (e.g. `main.tsx`, `App.tsx`):\n  ```tsx\n  import 'impact-nova/dist/impact-nova.css';\n  ```\n  **CSS split exports** (optional, for layered theming): `impact-nova/impact-nova-tokens.scss`, `impact-nova/impact-nova-base.scss`, `impact-nova/impact-nova-components.css`\n  Or from your main stylesheet: `@import 'impact-nova/dist/impact-nova.css';` in your main.css or main.scss.\n- **Component styling** comes from Impact Nova's CSS. Use each component's `variant` and `size` props; no Tailwind classes are required.\n- **Your layout and spacing** stay in your CSS or SCSS (margins, padding, flexbox, grid). Use your usual class names; the design system does not require Tailwind utilities.\n- **Manrope font:** Add the font link in `index.html` and in your CSS/SCSS set `body { font-family: 'Manrope', sans-serif; }` (see section 3).\n- **Summary:** No Tailwind, no Tailwind config. Load `impact-nova.css` once; use components with their props; use your existing CSS/SCSS for the rest.\n\n## 6b. Theming in consumer apps\n\n| Surface | What ships |\n|---------|------------|\n| **npm / consumer apps** | **Impact Light** only — `import 'impact-nova/dist/impact-nova.css'` (from `src/theme/tokens/light.json`) |\n| **Storybook / dev** | 10 curated **theme presets** (Impact Dark, Midnight, Ocean, …) — preview switcher only |\n\n**Do not** copy Storybook preset JSON or `theme-presets.ts` into consumer apps. Presets are not in the published package.\n\n**Custom branding:** override CSS variables on `:root` or a scoped class (e.g. `.my-brand`). Use Storybook **Theme Builder** / **Token Catalog** to explore tokens, then export CSS/JSON for your overrides.\n\n## 7. Using Impact Nova with Webpack\n\nIf your app is built with **Webpack** (including Create React App, which uses Webpack):\n\n- **CSS import:** Webpack will bundle the library CSS as long as you have a rule for `.css`. Ensure your config includes something like:\n  ```js\n  module: {\n    rules: [\n      {\n        test: /\\.css$/,\n        use: ['style-loader', 'css-loader'],\n        // or with MiniCssExtractPlugin:\n        // use: [MiniCssExtractPlugin.loader, 'css-loader'],\n      },\n      // ... other rules (e.g. for .tsx, .js)\n    ],\n  },\n  ```\n  Then in your root component or entry:\n  ```tsx\n  import 'impact-nova/dist/impact-nova.css';\n  ```\n- **Create React App (CRA):** No extra config. Add `import 'impact-nova/dist/impact-nova.css';` in `index.tsx` or `App.tsx`.\n- **Dedupe React / AG Grid:** If you see “multiple copies of React” or AG Grid issues, use Webpack’s `resolve.alias` so the app uses a single version:\n  ```js\n  resolve: {\n    alias: {\n      react: path.resolve(__dirname, 'node_modules/react'),\n      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),\n      // If using AG Grid:\n      'ag-grid-react': path.resolve(__dirname, 'node_modules/ag-grid-react'),\n      'ag-grid-community': path.resolve(__dirname, 'node_modules/ag-grid-community'),\n      'ag-grid-enterprise': path.resolve(__dirname, 'node_modules/ag-grid-enterprise'),\n    },\n  },\n  ```\n- **Tailwind + Webpack:** If you use Tailwind, add the Impact Nova preset and include the package in `content` (see section 7 below).\n\n## 8. Optional: extend Tailwind with Impact Nova preset\n\nIf your project uses Tailwind and you want the same theme (colors, radius), extend your `tailwind.config.js` with the preset from the package:\n\n```js\n// tailwind.config.js\nimport impactNovaPreset from 'impact-nova/tailwind.config.js';\n// → dist/tailwind.config.js (bundled theme; no package src/ required)\n\nexport default {\n  presets: [impactNovaPreset],\n  content: [\n    './index.html',\n    './src/**/*.{js,ts,jsx,tsx}',\n    './node_modules/impact-nova/dist/**/*.js',\n  ],\n  // ... rest of your config\n};\n```\n\n## Summary checklist\n\n- [ ] `npm install impact-nova impact-nova-icons` (and react, react-dom; optional: ag-grid, highcharts)\n- [ ] `import 'impact-nova/dist/impact-nova.css'` in root entry (or @import in main.css/main.scss if using CSS or SCSS without Tailwind; see §6)\n- [ ] Add Manrope font link and body font-family\n- [ ] Wrap app with `<ImpactNovaProviders locale=\"en\">` from `impact-nova/form`\n- [ ] Use subpath imports in feature code (see §5)\n- [ ] (Optional) Add Tailwind preset and content path for impact-nova\n- [ ] **Webpack:** Ensure a CSS rule (style-loader + css-loader) and, if needed, resolve.alias for React/AG Grid\n\nAfter this, import components via subpaths: `import { Button } from 'impact-nova/button';`\n\n## 9. Dashboard app shell (optional)\n\nTo scaffold a full dashboard (sidebar, header, breadcrumb, filters), read resource **`impact-nova://layout`** or call `get_real_world_patterns` with `topic: \"layout\"`. Use `Layout` from `impact-nova/layout` — not `DynamicLayout` (grid/flex utility only).\n";

package/dist/llms/rules/migration.js

@@ -1 +1 @@
-export default "# Migration: Impact UI → Impact Nova\n\nGuide 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`.\n\n---\n\n## 1. Prerequisites & MCP usage\n\n**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.\n\n- **impact-ui-mcp-server** (optional) — Source API: Impact UI component names, props, import paths.\n- **Impact Nova MCP** — Target API: Nova imports, compound components, patterns; validate with `validate_snippet`.\n\n**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`.\n\nBefore migrating: find all usages of the old UI library; choose big-bang or incremental strategy.\n\n---\n\n## 2. Phase 1 — Install and configure Impact Nova\n\n**Dependencies:**\n```bash\nnpm install impact-nova impact-nova-icons\nnpm install react@^19 react-dom@^19\n```\nWith 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.\n\n**Styles:** In app root: `import 'impact-nova/dist/impact-nova.css';`\n\n**Font (Manrope):** Link in HTML; set `body { font-family: 'Manrope', sans-serif; }` in global CSS.\n\n**i18n:** Wrap app with `<ImpactNovaProviders locale=\"en\">` from `impact-nova/form`. Use locale packs (e.g. `de`) for other locales.\n\n**Tailwind (optional):** Preset `impact-nova/tailwind.config.js`; add `node_modules/impact-nova/dist/**/*.js` to `content`.\n\n**Vite:** Add `resolve.dedupe: ['react','react-dom','ag-grid-community','ag-grid-enterprise','ag-grid-react']`.\n\nUse MCP **`get_installation_and_config`** for project-specific steps.\n\n---\n\n## 3. Phase 2 — Component mapping (Impact UI → Impact Nova)\n\nUse **`get_component`** for exact API of each Nova component.\n\n| Legacy (Impact UI / common) | Impact Nova | Import |\n|-----------------------------|-------------|--------|\n| Button | Button | `impact-nova` / `impact-nova/button` |\n| Modal / Dialog | Dialog, AlertDialog, Prompt | `impact-nova`, `impact-nova/prompt` |\n| Slide-out / Drawer | Sheet | `impact-nova/sheet` |\n| Select / Dropdown | Select | `impact-nova/select` |\n| Input, TextField | Input, SmartInput | `impact-nova/input`, `impact-nova/smart-input` |\n| Textarea | Textarea | `impact-nova/textarea` |\n| Checkbox | Checkbox | `impact-nova/checkbox` |\n| Radio group | RadioGroup, RadioGroupItem | `impact-nova/radio-group` |\n| Switch / Toggle | Switch | `impact-nova/switch` |\n| Date picker / range | DatePicker, DateRangePicker, WeekRangePicker, MonthRangePicker | `impact-nova/date-picker` |\n| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | `impact-nova/tabs` |\n| Alert / Banner | Alert, AlertTitle, AlertDescription, AlertIcon | `impact-nova/alert` |\n| Toast / Snackbar | toast, Toaster, useToast | `impact-nova` |\n| Badge / Tag | Badge, Tag, Chips | `impact-nova/badge`, `impact-nova`, `impact-nova/chips` |\n| Loader / Spinner | Loader, LoadingSpinner (icons) | `impact-nova/loader`, `impact-nova-icons` |\n| Accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | `impact-nova/accordion` |\n| Sidebar / Nav | Sidebar | `impact-nova/sidebar` |\n| Header / AppBar | Header + subcomponents | `impact-nova/header` |\n| Breadcrumb | Breadcrumb, BreadcrumbList, etc. | `impact-nova/breadcrumb` |\n| Avatar | Avatar, AvatarFallback | `impact-nova/avatar` |\n| Tooltip | Tooltip, TooltipTrigger, TooltipContent | `impact-nova/tooltip` |\n| File upload | FileUpload (composition) | `impact-nova/file-upload` |\n| Data grid / Table | DataTable, AG Grid | `impact-nova`, `impact-nova/ag-grid-react/cell-renderers` |\n| Filter panel / strip | FilterPanel, FilterStrip | `impact-nova/filter-panel`, `impact-nova` |\n| Empty state | EmptyContainer + subcomponents | `impact-nova/empty-container` |\n| Confirmation dialog | Prompt, AlertDialog | `impact-nova/prompt`, `impact-nova` |\n| Nested list / Tree | NestedList | `impact-nova/nested-list` |\n| Chart | Chart | `impact-nova/chart` |\n| Horizontal scroll list | HorizontalScroller | `impact-nova/horizontal-scroller` |\n\nIcons: `impact-nova-icons` (e.g. Pin, Chart, LoadingSpinner) + `createIconResolver` for string lookup.\n\n---\n\n## 4. Phase 3 — Import and API changes\n\n**Imports:** **Prefer subpath imports** in all feature code. Run a codemod or migrate manually:\n\n```tsx\n// Before (barrel)\nimport { Button, Select, DataTable } from 'impact-nova';\n\n// After (subpath — preferred)\nimport { Button } from 'impact-nova/button';\nimport { Select } from 'impact-nova/select';\nimport { DataTable, useDataTable } from 'impact-nova/data-table';\nimport { CheckCircle } from 'impact-nova-icons';\n```\n\nBarrel OK for locale packs: `import { de } from 'impact-nova';`\n\nTypes: `import type { Option } from 'impact-nova/select';`, `import type { SavedTableViewItem } from 'impact-nova/data-table';`, `import type { RowSelectionState } from 'impact-nova/virtualized';`\n\n**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.\n\n---\n\n## 5. Phase 4 — Compound patterns\n\nUse **`get_real_world_patterns`** for more detail.\n\n- **Filter UI:** FilterPanel + FilterPanelSidebar, FilterPanelBody, FilterPanelFooter; FilterStrip; types FilterItem, SavedFilterItem, FilterSidebarItem.\n- **Data table + AG Grid:** DataTable, DataTableContent, processBackendColumnDefs, BackendColDef; AG_GRID_CELL_COMPONENTS, LinkCellRenderer from `impact-nova/ag-grid-react/cell-renderers`.\n- **Sheet:** Sheet, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter from `impact-nova/sheet`; pair with react-hook-form.\n- **Empty state:** EmptyContainer, EmptyContainerImage, EmptyContainerTitle, EmptyContainerDescription, EmptyContainerAction.\n- **Toast + Alert:** Toaster + toast()/useToast; Alert + AlertTitle, AlertDescription, AlertIcon from `impact-nova/alert`.\n- **Tabs + NestedList + Accordion:** Tabs components; NestedList + NestedListItem; Accordion components.\n\n---\n\n## 6. Phase 5 — Verification\n\n**Setup:** Impact Nova MCP enabled; keep impact-ui-mcp-server during migration. Nova + peers installed; CSS + Manrope + ImpactNovaProviders; optional Tailwind + Vite dedupe.\n\n**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.\n\n**MCP:** Use `validate_snippet`, `get_component`, `suggest_components_for_ui`.\n\n**Build/tests:** `npm run build`, lint, manual test of forms, filters, tables, toasts, dialogs.\n";
+export default "# Migration: Impact UI → Impact Nova\n\nGuide 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`.\n\n---\n\n## 1. Prerequisites & MCP usage\n\n**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.\n\n- **impact-ui-mcp-server** (optional) — Source API: Impact UI component names, props, import paths.\n- **Impact Nova MCP** — Target API: Nova imports, compound components, patterns; validate with `validate_snippet`.\n\n**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`.\n\nBefore migrating: find all usages of the old UI library; choose big-bang or incremental strategy.\n\n---\n\n## 2. Phase 1 — Install and configure Impact Nova\n\n**Dependencies:**\n```bash\nnpm install impact-nova impact-nova-icons\nnpm install react@^19 react-dom@^19\n```\nWith 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.\n\n**Styles:** In app root: `import 'impact-nova/dist/impact-nova.css';`\n\n**Font (Manrope):** Link in HTML; set `body { font-family: 'Manrope', sans-serif; }` in global CSS.\n\n**i18n:** Wrap app with `<ImpactNovaProviders locale=\"en\">` from `impact-nova/form`. Formatting locales are BCP 47 (`de-DE`, `en-GB`, …). Pass a locale pack (`de` from `impact-nova/locale/de`) for translated chrome. Format with `formatDate` / `formatNumber` from `impact-nova/i18n`. See `impact-nova://i18n`.\n\n**Tailwind (optional):** Preset `impact-nova/tailwind.config.js`; add `node_modules/impact-nova/dist/**/*.js` to `content`.\n\n**Vite:** Add `resolve.dedupe: ['react','react-dom','ag-grid-community','ag-grid-enterprise','ag-grid-react']`.\n\nUse MCP **`get_installation_and_config`** for project-specific steps.\n\n---\n\n## 3. Phase 2 — Component mapping (Impact UI → Impact Nova)\n\nUse **`get_component`** for exact API of each Nova component.\n\n| Legacy (Impact UI / common) | Impact Nova | Import |\n|-----------------------------|-------------|--------|\n| Button | Button | `impact-nova` / `impact-nova/button` |\n| Modal / Dialog | Dialog, AlertDialog, Prompt | `impact-nova`, `impact-nova/prompt` |\n| Slide-out / Drawer | Sheet | `impact-nova/sheet` |\n| Select / Dropdown | Select | `impact-nova/select` |\n| Input, TextField | Input, SmartInput | `impact-nova/input`, `impact-nova/smart-input` |\n| Textarea | Textarea | `impact-nova/textarea` |\n| Checkbox | Checkbox | `impact-nova/checkbox` |\n| Radio group | RadioGroup, RadioGroupItem | `impact-nova/radio-group` |\n| Switch / Toggle | Switch | `impact-nova/switch` |\n| Date picker / range | DatePicker, DateRangePicker, WeekRangePicker, MonthRangePicker | `impact-nova/date-picker` |\n| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | `impact-nova/tabs` |\n| Alert / Banner | Alert, AlertTitle, AlertDescription, AlertIcon | `impact-nova/alert` |\n| Toast / Snackbar | toast, Toaster, useToast | `impact-nova` |\n| Badge / Tag | Badge, Tag, Chips | `impact-nova/badge`, `impact-nova`, `impact-nova/chips` |\n| Loader / Spinner | Loader, LoadingSpinner (icons) | `impact-nova/loader`, `impact-nova-icons` |\n| Accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | `impact-nova/accordion` |\n| Sidebar / Nav | Sidebar | `impact-nova/sidebar` |\n| Header / AppBar | Header + subcomponents | `impact-nova/header` |\n| Breadcrumb | Breadcrumb, BreadcrumbList, etc. | `impact-nova/breadcrumb` |\n| Avatar | Avatar, AvatarFallback | `impact-nova/avatar` |\n| Tooltip | Tooltip, TooltipTrigger, TooltipContent | `impact-nova/tooltip` |\n| File upload | FileUpload (composition) | `impact-nova/file-upload` |\n| Data grid / Table | DataTable, AG Grid | `impact-nova`, `impact-nova/ag-grid-react/cell-renderers` |\n| Filter panel / strip | FilterPanel, FilterStrip | `impact-nova/filter-panel`, `impact-nova` |\n| Empty state | EmptyContainer + subcomponents | `impact-nova/empty-container` |\n| Confirmation dialog | Prompt, AlertDialog | `impact-nova/prompt`, `impact-nova` |\n| Nested list / Tree | NestedList | `impact-nova/nested-list` |\n| Chart | Chart | `impact-nova/chart` |\n| Horizontal scroll list | HorizontalScroller | `impact-nova/horizontal-scroller` |\n\nIcons: `impact-nova-icons` (e.g. Pin, Chart, LoadingSpinner) + `createIconResolver` for string lookup.\n\n---\n\n## 4. Phase 3 — Import and API changes\n\n**Imports:** **Prefer subpath imports** in all feature code. Run a codemod or migrate manually:\n\n```tsx\n// Before (barrel)\nimport { Button, Select, DataTable } from 'impact-nova';\n\n// After (subpath — preferred)\nimport { Button } from 'impact-nova/button';\nimport { Select } from 'impact-nova/select';\nimport { DataTable, useDataTable } from 'impact-nova/data-table';\nimport { CheckCircle } from 'impact-nova-icons';\n```\n\nBarrel OK for locale packs: `import { de } from 'impact-nova';`\n\nTypes: `import type { Option } from 'impact-nova/select';`, `import type { SavedTableViewItem } from 'impact-nova/data-table';`, `import type { RowSelectionState } from 'impact-nova/virtualized';`\n\n**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.\n\n---\n\n## 5. Phase 4 — Compound patterns\n\nUse **`get_real_world_patterns`** for more detail.\n\n- **Filter UI:** FilterPanel + FilterPanelSidebar, FilterPanelBody, FilterPanelFooter; FilterStrip; types FilterItem, SavedFilterItem, FilterSidebarItem.\n- **Data table + AG Grid:** DataTable, DataTableContent, processBackendColumnDefs, BackendColDef; AG_GRID_CELL_COMPONENTS, LinkCellRenderer from `impact-nova/ag-grid-react/cell-renderers`.\n- **Sheet:** Sheet, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter from `impact-nova/sheet`; pair with react-hook-form.\n- **Empty state:** EmptyContainer, EmptyContainerImage, EmptyContainerTitle, EmptyContainerDescription, EmptyContainerAction.\n- **Toast + Alert:** Toaster + toast()/useToast; Alert + AlertTitle, AlertDescription, AlertIcon from `impact-nova/alert`.\n- **Tabs + NestedList + Accordion:** Tabs components; NestedList + NestedListItem; Accordion components.\n\n---\n\n## 6. Phase 5 — Verification\n\n**Setup:** Impact Nova MCP enabled; keep impact-ui-mcp-server during migration. Nova + peers installed; CSS + Manrope + ImpactNovaProviders; optional Tailwind + Vite dedupe.\n\n**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.\n\n**MCP:** Use `validate_snippet`, `get_component`, `suggest_components_for_ui`.\n\n**Build/tests:** `npm run build`, lint, manual test of forms, filters, tables, toasts, dialogs.\n";

package/dist/llms/rules/real-world-patterns.js

@@ -1 +1 @@
-export default "# Impact Nova — Real-World Patterns (from production apps)\n\nPatterns observed in apps that use Impact Nova extensively (e.g. filter UIs, data tables, sheets, empty states).\n\n---\n\n## 1. Subpath imports (tree-shaking)\n\n**Default for production apps:** use subpath imports. Production apps (e.g. mtp-mfe-itemsmart-v3) migrated to 100% subpath imports — zero barrel `from 'impact-nova'` in feature code. Barrel is OK for i18n bootstrapping only.\n\n| Use case | Import |\n|----------|--------|\n| Layout (app shell) | `import { Layout } from 'impact-nova/layout';` |\n| Sidebar | `import { Sidebar, SidebarProvider, SidebarContent } from 'impact-nova/sidebar';` |\n| Header | `import { Header, HeaderLeft, HeaderRight, HeaderTitle } from 'impact-nova/header';` |\n| Breadcrumb | `import { Breadcrumb, BreadcrumbList, BreadcrumbHeader } from 'impact-nova/breadcrumb';` |\n| Button only | `import { Button } from 'impact-nova/button';` |\n| Combobox | `import { Combobox } from 'impact-nova/combobox';` |\n| Sheet (side panel) | `import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter } from 'impact-nova/sheet';` |\n| Filter panel | `import { FilterPanel, FilterPanelSidebar } from 'impact-nova/filter-panel';` and `FilterPanelBody`, `FilterPanelFooter` |\n| Filter strip | `import { FilterStrip } from 'impact-nova/filter-strip';` |\n| Empty state | `import { EmptyContainer, EmptyContainerImage, EmptyContainerTitle, EmptyContainerDescription, EmptyContainerAction } from 'impact-nova/empty-container';` |\n| Accordion | `import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from 'impact-nova/accordion';` |\n| Date pickers | `import { DateRangePicker } from 'impact-nova/date-picker';` or `WeekRangePicker`, `MonthRangePicker`. Week range selection language (Wk gutter join, rounded-lg start/end caps) is built into Calendar — do not restyle the grid. |\n| Select | `import { Select } from 'impact-nova/select';` |\n| Data table | `import { DataTable, DataTableContent, DataTableToolbar, useDataTable } from 'impact-nova/data-table';` |\n| Progress bar | `import { ProgressBar } from 'impact-nova/progress-bar';` |\n| Virtualized list hooks | `import { useVirtualizedList, useDebouncedValue } from 'impact-nova/virtualized';` |\n| Expandable list row | `import { ExpandableListItem, type ExpandableListItemSection } from 'impact-nova/expandable-list-item';` |\n| Row selection type | `import type { RowSelectionState } from 'impact-nova/virtualized';` |\n| Alert | `import { Alert, AlertTitle, AlertDescription, AlertIcon } from 'impact-nova/alert';` |\n| Tooltip | `import { Tooltip, TooltipTrigger, TooltipContent } from 'impact-nova/tooltip';` |\n| Icons | `import { Pin, Unpin, Chart } from 'impact-nova-icons';` + `createIconResolver` for dynamic lookup |\n| AG Grid cell renderers | `import { AG_GRID_CELL_COMPONENTS, LinkCellRenderer } from 'impact-nova/ag-grid-react/cell-renderers';` |\n| Prompt | `import { Prompt } from 'impact-nova/prompt';` |\n| Radio group | `import { RadioGroup, RadioGroupItem } from 'impact-nova/radio-group';` |\n| Button group | `import { ButtonGroup } from 'impact-nova/button-group';` |\n| Smart input | `import { SmartInput as InputWrapper } from 'impact-nova/smart-input';` |\n| Chips | `import { Chip } from 'impact-nova/chips';` |\n| Loader | `import { Loader } from 'impact-nova/loader';` |\n\n---\n\n## 2. Type-only imports\n\nUse type-only imports for types to avoid pulling runtime code:\n\n```ts\nimport type { Option, MultiValue, ActionMeta } from 'impact-nova/select';\nimport type { FilterSidebarItem } from 'impact-nova/filter-panel';\nimport type { FilterItem, SavedFilterItem } from 'impact-nova/filter-strip';\nimport type { NestedListItem } from 'impact-nova/nested-list';\nimport type { FileUploadProps } from 'impact-nova/file-upload';\nimport type { BackendColDef } from 'impact-nova';\n```\n\n---\n\n## 3. Compound patterns\n\n### Filter UI (panel + strip)\n\n- **FilterPanel** + **FilterPanelSidebar** for the sliding panel; **FilterPanelBody** and **FilterPanelFooter** for content and Apply/Cancel.\n- **FilterStrip** to show applied filters (chips/tags). Types: `FilterItem`, `SavedFilterItem` from `impact-nova/filter-strip`.\n- Config drives **FilterSidebarItem** (from `impact-nova/filter-panel`); form state often with react-hook-form.\n\n### Data table + AG Grid\n\n**Mandatory (no deviation):** For DataTable or any data table using AG Grid, refer **only** to AG Grid's official documentation, follow **only** AG Grid recommended patterns, and use **only** the AG Grid API for grid operations. See resource `impact-nova://ag-grid-rules` for full rules. If the user has **ag-mcp** installed, use it for AG Grid API/docs and collaborate with this MCP for Impact Nova integration.\n\n- **DataTable**, **DataTableContent**, **DataTableSheet**, **DataTableSheetContent**, **DataTableSheetHeader**, **DataTableSheetBody**, **DataTableSheetSection**, **DataTableSheetTabs**, **DataTableSheetTabsList**, **DataTableSheetTabPanel**, **DataTableColumnList**, **DataTableFormatOptions** from `impact-nova/data-table`.\n- **Settings sheet layout:** Use compound sheet layout components — not raw `Tabs` + manual `overflow-y-auto`. `DataTableSheetTabPanel layout=\"list\"` for column/KPI lists; `layout=\"scroll\"` for format/filter forms. Resource: `impact-nova://data-table-sheet-layout`.\n- **AG Grid v36 peers:** `ag-grid-community@36.0.1`, `ag-grid-react@36.0.1`, `ag-grid-enterprise@36.0.1` — exact pin, dedupe in Vite. No legacy `ag-theme-*` CSS.\n- **Column settings:** `DataTableColumnList` reads pin/sort/filter from the live `GridApi` (frozen vs scrollable sections). Storybook: `Data/DataTable/Column settings scenarios`.\n- Use **processBackendColumnDefs** from `impact-nova` when column defs come from the backend; type **BackendColDef**.\n- Cell renderers: **AG_GRID_CELL_COMPONENTS** or **LinkCellRenderer** from `impact-nova/ag-grid-react/cell-renderers`; extend/wrap as needed (e.g. PlanningLinkCellRenderer).\n\n### Sheet (side panel with form)\n\n- **Sheet**, **SheetContent**, **SheetHeader**, **SheetTitle**, **SheetBody**, **SheetFooter** from `impact-nova/sheet`.\n- Use for “Match With”, “Bulk Edit”, “View Management” panels. Pair with react-hook-form for form content.\n\n### Empty state\n\n- **EmptyContainer** wrapping **EmptyContainerImage**, **EmptyContainerTitle**, **EmptyContainerDescription**, **EmptyContainerAction** (e.g. a Button to “Select filter” or “Add item”).\n- **Lazy illustrations:** When no custom `children` are passed to `EmptyContainerImage`, one random illustration loads via dynamic `import()` — only ~1 webp chunk per empty state, not all 6 upfront. Pass custom children to skip illustration loading entirely.\n\n### Tabs + NestedList + Accordion (view management)\n\n- **Tabs**, **TabsList**, **TabsTrigger**, **TabsContent** for switching sections.\n- **NestedList** with **SelectionMode**; data shape **NestedListItem** from `impact-nova/nested-list`.\n- **Accordion**, **AccordionItem**, **AccordionTrigger**, **AccordionContent** for expandable blocks (e.g. Versions & Variance).\n\n### Chart (Highcharts)\n\n- Use **Chart** from `impact-nova/chart` as the wrapper.\n- For **series, options, and configuration** refer to **Highcharts documentation** ([highcharts.com/docs](https://www.highcharts.com/docs/)); use the Highcharts API for chart behavior. Impact Nova provides the React integration and styling; options/series follow Highcharts.\n- Install: `highcharts@^12`, `highcharts-react-official@^3`, optional `highcharts-border-radius@^0.0.4`.\n\n### Toast + Alert\n\n- **toast**, **Toaster**, **useToast** from `impact-nova`; wrap app with **Toaster**.\n- **Alert**, **AlertTitle**, **AlertDescription**, **AlertIcon** from `impact-nova/alert` for inline or toast-style messages.\n\n### Expandable list row vs virtualized list (independent, composable)\n\nBoth are **decoupled** subpaths. Pick the integration style that fits — preset, compound, or headless hooks.\n\n#### ExpandableListItem (`impact-nova/expandable-list-item`)\n\n| Style | When | Example |\n|-------|------|---------|\n| **Preset** | Data-driven sections from API/config | `<ExpandableListItem title=\"…\" description=\"…\" sections={sections} />` |\n| **Compound** | Custom row layout / slots | `ExpandableListItemRoot` → `Row` → `Checkbox` + `Trigger` → `Content` |\n| **Inside virtualized** | Large lists (optional) | Render preset or compound inside `VirtualizedListItem` |\n\n- Props: **`title`**, **`description`** (not legacy `sku` / `subtitle`)\n- Sections: `ExpandableListItemSection[]` — `metrics` | `attributes` | `custom`\n- Storybook: **Expandable List Item → Composition**\n\n#### Virtualized (`impact-nova/virtualized`)\n\n| Style | When | Example |\n|-------|------|---------|\n| **Compound UI** | New list chrome (search, select-all, viewport) | `VirtualizedList` → `Viewport` → `Content` → `Item` |\n| **Headless hooks** | Full DOM control / existing layout | `useVirtualizedList` + `getItemProps` / `resetRowSize` |\n| **Custom rows** | Any row JSX | ExpandableListItem optional — not required |\n\n- Expandable rows: `getItemProps(index, { measure: isExpanded })`; call `resetRowSize(index)` on collapse\n- Types: `RowSelectionState`, `VirtualRowModel`, `UseVirtualizedListResult`\n- Storybook: **Virtualized List → Composition** and **Custom row UI**\n- Patterns: `query_patterns` → `virtualized-selectable-list`, `expandable-list-item-preset`, `expandable-list-item-compound`\n- **Renamed:** `impact-nova/expandable-sku` → `impact-nova/expandable-list-item`. See `impact-nova://removed-imports`.\n\n### Command Palette & keyboard shortcuts\n\nImplementation is **more involved** than other components. Use the dedicated guide: resource **`impact-nova://command-palette`**.\n\n- **Import:** `import { CommandPaletteProvider, CommandPalette, useShortcut, useGlobalShortcut, ShortcutSettings, ShortcutScopeProvider, Kbd, useCommandPalette, useBrowserShortcuts } from 'impact-nova/command-palette';`\n- **Minimal setup:** Wrap app with `CommandPaletteProvider`; render `<CommandPalette />` once inside it (⌘K overlay). Register commands with `useShortcut` (scoped: page/module/modal) or `useGlobalShortcut` (app-wide). Use correct `scope` for priority (modal > page > module > global).\n- **Multi-table:** When multiple DataTables share the same shortcut, wrap each in `ShortcutScopeProvider` with a unique `instance` so only the focused one responds.\n- **ShortcutSettings:** AG Grid–powered panel for user customisation; put inside a Sheet (e.g. Keyboard Shortcuts settings). For AG Grid behaviour follow `impact-nova://ag-grid-rules`.\n- **Kbd:** Use `<Kbd keybinding={{ key: 'k', meta: true }} />` to show shortcut in UI. **Button trigger:** `useCommandPalette().setOpen(true)`.\n\n---\n\n## 4. App setup\n\n- **CSS once at root**: `import 'impact-nova/dist/impact-nova.css';` (e.g. in App.tsx or main.tsx).\n- **AG Grid**: Set `LicenseManager.setLicenseKey(...)` if using enterprise. Install `ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1`.\n- **Vite**: Dedupe react/ag-grid when using impact-nova to avoid dual instances. Exclude `impact-nova-icons` from `optimizeDeps` to prevent SVG asset warnings in dev:\n\n```js\noptimizeDeps: {\n  exclude: ['impact-nova-icons'],\n},\nresolve: {\n  dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n},\n```\n\n---\n\n## 5. Known workarounds\n\n- **HorizontalScroller**: If the package entry is empty in your build, add a Vite alias to `.../horizontal-scroller/horizontal-scroller.js` and a small `declare module 'impact-nova/horizontal-scroller'` for TypeScript.\n- **Chart**: Prefer `import { Chart } from 'impact-nova/chart'`. Pre-bundle Highcharts UMD modules in Vite `optimizeDeps.include` if you see interop errors in dev.\n\n---\n\n## 6. Forms and options\n\n- **Select options**: Use type **Option** (or **SelectOption**) from `impact-nova/select` for `{ value, label }` (and optional fields). **MultiValue** for multi-select.\n- **react-hook-form**: Use Impact Nova form controls (SmartInput, Select, DateRangePicker, RadioGroup, ButtonGroup, Chips, etc.) as controlled components; pass `value`/`onChange` from the form library.\n- **Validation and errors**: Show validation errors with **Alert** or field-level messages; use the form library’s error state (e.g. `formState.errors`) and optional schema validation (e.g. Zod) with react-hook-form.\n\n### ReactHooksForm (config-driven dynamic forms)\n\nUse when the form layout and rules come from **JSON** (`IFormConfig`) — bulk edit sheets, settings, wizards, filters.\n\n```tsx\nimport { ReactHooksForm, type IFormConfig, type FormContext } from 'impact-nova/form-react';\n\nconst formContext: FormContext = {\n  transport: {\n    fetchSelectOptions: async ({ fieldId, apiConfig }) => { /* your fetch */ },\n    showFormErrorToast: ({ title, description }) => { /* your toast */ },\n  },\n  validateForm: ({ formValues }) => ({ isValid: true }), // optional cross-field rules\n};\n\n<ReactHooksForm formConfig={formConfig} formContext={formContext} onSubmit={handleSubmit} />\n```\n\n| Concept | What it does |\n|---------|----------------|\n| `isRequired` | Mandatory field — blocks submit when visible and empty |\n| `disableDependency` + `__empty__` | Disable child until parent has value; **auto-clear** when parent empties |\n| `disableDependency` + `null` | Disable when other field has any value (mutually exclusive) |\n| `disableDependency` + `\"true\"` | Disable when switch/checkbox is on (grand total, lock) |\n| `visibilityDependency` | Show/hide fields (month range vs multi-month; filter hierarchy) |\n| `formContext.transport` | **Required** for API selects — Nova never calls HTTP |\n| `formContext.validateForm` | Cross-field submit validation (e.g. “at least one edit”) |\n| `doNotIncludeInSubmit` | UI-only toggles excluded from payload |\n| `includeOnlyVisibleFieldsInSubmit` | Only active picker variant submitted |\n\n**MCP resource (full catalog):** `impact-nova://dynamic-form-framework`\n\n**Storybook (12 ItemSmart patterns):** `Dynamic Form / ReactHooksForm` + `Dynamic Form / Guide`\n\n| Story | URL slug |\n|-------|----------|\n| Required fields | `dynamic-form-reacthooksform--required-fields` |\n| Disable dependency | `dynamic-form-reacthooksform--disable-dependency-period-gates-value` |\n| validateForm gate | `dynamic-form-reacthooksform--item-details-bulk-edit-validate-form` |\n| Scenario simulate | `dynamic-form-reacthooksform--scenario-simulate` |\n| Filter disable chain | `dynamic-form-reacthooksform--filter-disable-chain` |\n| Filter visibility | `dynamic-form-reacthooksform--filter-visibility-hierarchy` |\n\n**`query_patterns` ids:** `config-driven-dynamic-form`, `form-required-fields`, `form-visibility-dependency`, `time-phased-metric-bulk-edit`, `form-validate-form-submit-gate`, `form-mutually-exclusive-fields`, `form-switch-disable-bypass`, `form-approval-hub-lock`, `filter-form-dependencies`, `form-filter-visibility-hierarchy`\n\n**Fixtures:** `impact-nova/src/form-react/stories/fixtures/itemSmartProductionFormConfigs.ts`\n\n**ItemSmart reference:** `mtp-mfe-itemsmart-v3/docs/react-hooks-form-production-patterns.md`\n\n**Packages:** `impact-nova/form-engine` · `impact-nova/form-react` · `impact-nova/filter-shell`\n\n---\n\n## 7. Breadcrumb and toolbar\n\n- **Breadcrumb** with **BreadcrumbList**, **BreadcrumbItem**, **BreadcrumbLink**, **BreadcrumbSeparator**, **BreadcrumbPage** for table/section context.\n- **DataTableToolbar** for table toolbars (view mode, view management, filters, Update/Cancel when editing).\n\nUse these patterns so the MCP and generated code stay close to how Impact Nova is used in real apps.\n\n---\n\n## 8. Wizard (multi-step flow)\n\nUse **Wizard** for any multi-step creation or onboarding flow. Radix-style controlled state (`value` / `onValueChange`), optional split-panel layout, and `useWizard()` for flexible footers.\n\n### Import\n\n```ts\nimport {\n  WizardRoot,\n  WizardLayout,\n  WizardSidebar,\n  WizardTitle,\n  WizardDescription,\n  WizardMedia,\n  WizardBody,\n  WizardProgress,\n  WizardHeader,\n  WizardContent,\n  WizardStep,\n  WizardFooter,\n  useWizard,\n} from 'impact-nova/wizard';\n```\n\n### Minimal multi-step example\n\n```tsx\nimport { useState } from 'react';\nimport {\n  WizardRoot, WizardLayout,\n  WizardSidebar, WizardTitle, WizardDescription, WizardMedia,\n  WizardBody, WizardProgress,\n  WizardContent, WizardStep, WizardHeader,\n  WizardFooter,\n} from 'impact-nova/wizard';\nimport { Button } from 'impact-nova/button';\n\nexport function CreateAlertFlow() {\n  const [step, setStep] = useState(1);\n\n  return (\n    <WizardRoot value={step} totalSteps={3} onValueChange={setStep}>\n      <WizardLayout>\n        <WizardSidebar>\n          <WizardTitle>Create Alert</WizardTitle>\n          <WizardDescription>Configure your alert step by step.</WizardDescription>\n          <WizardMedia />\n        </WizardSidebar>\n\n        <WizardBody>\n          <WizardProgress />\n          <WizardContent>\n            <WizardStep value={1}>\n              <WizardHeader>Alert Details</WizardHeader>\n            </WizardStep>\n            <WizardStep value={2}>\n              <WizardHeader>Configuration</WizardHeader>\n            </WizardStep>\n            <WizardStep value={3}>\n              <WizardHeader>Review</WizardHeader>\n            </WizardStep>\n          </WizardContent>\n          <WizardFooter>\n            <Button variant=\"secondary\">Cancel</Button>\n            <Button variant=\"default\">Submit</Button>\n          </WizardFooter>\n        </WizardBody>\n      </WizardLayout>\n    </WizardRoot>\n  );\n}\n```\n\n### Key rules\n\n- **WizardRoot** is the context provider — every other sub-component must be a descendant.\n- Use **useWizard()** for `goNext`, `goBack`, `isFirstStep`, `isLastStep` without prop drilling.\n- **WizardStep** renders nothing when `value` doesn't match the current step — use one per step.\n- **WizardMedia** renders a default SVG when neither `src` nor `children` are provided.\n- The sidebar is hidden below the `lg` breakpoint.\n- All sub-components except **WizardRoot** are optional — compose only what you need.\n---\n\n## 9. App layout (app shell)\n\n**Use `Layout`** for the app chrome — not `DynamicLayout` (that is a grid/flex/stack utility only).\n\nFull beginner scaffold: resource **`impact-nova://layout`**.\n\n### Structure\n\n```tsx\nimport { Layout } from 'impact-nova/layout';\nimport { Sidebar, SidebarProvider } from 'impact-nova/sidebar';\nimport { Header, HeaderLeft, HeaderTitle } from 'impact-nova/header';\nimport { BreadcrumbHeader, Breadcrumb, BreadcrumbList } from 'impact-nova/breadcrumb';\nimport { FilterStrip } from 'impact-nova/filter-strip';\n\n<SidebarProvider defaultOpen={false} id=\"app-sidebar\" className=\"flex h-svh min-h-0 w-full min-w-0 overflow-hidden\">\n  <Layout\n    sidebar={<Sidebar collapsible=\"offcanvas\">...</Sidebar>}\n    header={<Header>...</Header>}\n  >\n    {/* Page content — Item Smart parity */}\n    <PageShell>\n      <PageStickyHeader pageTitle=\"...\" filterStrip={filtersApplied ? <FilterStrip ... /> : undefined} />\n      {filtersApplied ? <WorkspaceBody /> : <EmptyStateView title=\"...\" primaryActionLabel=\"Select filter\" />}\n    </PageShell>\n  </Layout>\n</SidebarProvider>\n```\n\n### Key rules\n\n- **`SidebarProvider` at app root** — wraps `Layout`, not inside the sidebar slot.\n- **Page background** — `PageShell` → `bg-brand-subtle` (not `bg-canvas-wash` on module pages)\n- **Filter strip** — white sticky bar via `PageStickyHeader` `filterStrip` slot (`page-filter-strip` class)\n- **Tables** — `module-table-container mx-6 flex min-h-[480px] flex-1` → white `DataTable` card with shadow\n- **Subpath imports** — `impact-nova/layout`, `impact-nova/sidebar`, `impact-nova/header`, `impact-nova/breadcrumb`, `impact-nova/filter-strip`.\n- **With React Router** — put `<Outlet />` inside `Layout` children; route pages render breadcrumb + body.\n- **With Command Palette** — `CommandPaletteProvider` at root; `<CommandPalette />` as sibling inside `SidebarProvider`. See `impact-nova://command-palette`.\n\n### Premium primitives (shipped in create-impact-nova template)\n\n| Component | Role |\n|-----------|------|\n| `PageShell` | `bg-brand-subtle` + flex fill chain |\n| `PageStickyHeader` | Breadcrumb `z-30` + white filter strip slot |\n| `EmptyStateView` | Illustration + primary/secondary CTAs |\n| `SummaryMetricCard` | Dashboard KPI tiles (`border-[#C3C8D4]`, hover shadow) |\n| `module-table-container` | Table card shadow + `min-h-[480px] flex-1` fill |\n";
+export default "# Impact Nova — Real-World Patterns (from production apps)\n\nPatterns observed in apps that use Impact Nova extensively (e.g. filter UIs, data tables, sheets, empty states).\n\n---\n\n## 1. Subpath imports (tree-shaking)\n\n**Default for production apps:** use subpath imports. Production apps (e.g. mtp-mfe-itemsmart-v3) migrated to 100% subpath imports — zero barrel `from 'impact-nova'` in feature code. Barrel is OK for i18n bootstrapping only.\n\n| Use case | Import |\n|----------|--------|\n| Layout (app shell) | `import { Layout } from 'impact-nova/layout';` |\n| Sidebar | `import { Sidebar, SidebarProvider, SidebarContent } from 'impact-nova/sidebar';` |\n| Header | `import { Header, HeaderLeft, HeaderRight, HeaderTitle } from 'impact-nova/header';` |\n| Breadcrumb | `import { Breadcrumb, BreadcrumbList, BreadcrumbHeader } from 'impact-nova/breadcrumb';` |\n| Button only | `import { Button } from 'impact-nova/button';` |\n| Combobox | `import { Combobox } from 'impact-nova/combobox';` |\n| Sheet (side panel) | `import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetBody, SheetFooter } from 'impact-nova/sheet';` |\n| Filter panel | `import { FilterPanel, FilterPanelSidebar } from 'impact-nova/filter-panel';` and `FilterPanelBody`, `FilterPanelFooter` |\n| Filter strip | `import { FilterStrip } from 'impact-nova/filter-strip';` |\n| Empty state | `import { EmptyContainer, EmptyContainerImage, EmptyContainerTitle, EmptyContainerDescription, EmptyContainerAction } from 'impact-nova/empty-container';` |\n| Accordion | `import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from 'impact-nova/accordion';` |\n| Date pickers | `import { DateRangePicker } from 'impact-nova/date-picker';` or `WeekRangePicker`, `MonthRangePicker`. Week range selection language (Wk gutter join, rounded-lg start/end caps) is built into Calendar — do not restyle the grid. |\n| Select | `import { Select } from 'impact-nova/select';` |\n| Data table | `import { DataTable, DataTableContent, DataTableToolbar, useDataTable } from 'impact-nova/data-table';` |\n| Progress bar | `import { ProgressBar } from 'impact-nova/progress-bar';` |\n| Virtualized list hooks | `import { useVirtualizedList, useDebouncedValue } from 'impact-nova/virtualized';` |\n| Expandable list row | `import { ExpandableListItem, type ExpandableListItemSection } from 'impact-nova/expandable-list-item';` |\n| Row selection type | `import type { RowSelectionState } from 'impact-nova/virtualized';` |\n| Alert | `import { Alert, AlertTitle, AlertDescription, AlertIcon } from 'impact-nova/alert';` |\n| Tooltip | `import { Tooltip, TooltipTrigger, TooltipContent } from 'impact-nova/tooltip';` |\n| Icons | `import { Pin, Unpin, Chart } from 'impact-nova-icons';` + `createIconResolver` for dynamic lookup |\n| AG Grid cell renderers | `import { AG_GRID_CELL_COMPONENTS, LinkCellRenderer } from 'impact-nova/ag-grid-react/cell-renderers';` |\n| Prompt | `import { Prompt } from 'impact-nova/prompt';` |\n| Radio group | `import { RadioGroup, RadioGroupItem } from 'impact-nova/radio-group';` |\n| Button group | `import { ButtonGroup } from 'impact-nova/button-group';` |\n| Smart input | `import { SmartInput as InputWrapper } from 'impact-nova/smart-input';` |\n| Chips | `import { Chip } from 'impact-nova/chips';` |\n| Loader | `import { Loader } from 'impact-nova/loader';` |\n\n---\n\n## 2. Type-only imports\n\nUse type-only imports for types to avoid pulling runtime code:\n\n```ts\nimport type { Option, MultiValue, ActionMeta } from 'impact-nova/select';\nimport type { FilterSidebarItem } from 'impact-nova/filter-panel';\nimport type { FilterItem, SavedFilterItem } from 'impact-nova/filter-strip';\nimport type { NestedListItem } from 'impact-nova/nested-list';\nimport type { FileUploadProps } from 'impact-nova/file-upload';\nimport type { BackendColDef } from 'impact-nova';\n```\n\n---\n\n## 3. Compound patterns\n\n### Filter UI (panel + strip)\n\n- **FilterPanel** + **FilterPanelSidebar** for the sliding panel; **FilterPanelBody** and **FilterPanelFooter** for content and Apply/Cancel.\n- **FilterStrip** to show applied filters (chips/tags). Types: `FilterItem`, `SavedFilterItem` from `impact-nova/filter-strip`.\n- Config drives **FilterSidebarItem** (from `impact-nova/filter-panel`); form state often with react-hook-form.\n\n### Data table + AG Grid\n\n**Mandatory (no deviation):** For DataTable or any data table using AG Grid, refer **only** to AG Grid's official documentation, follow **only** AG Grid recommended patterns, and use **only** the AG Grid API for grid operations. See resource `impact-nova://ag-grid-rules` for full rules. If the user has **ag-mcp** installed, use it for AG Grid API/docs and collaborate with this MCP for Impact Nova integration.\n\n- **DataTable**, **DataTableContent**, **DataTableSheet**, **DataTableSheetContent**, **DataTableSheetHeader**, **DataTableSheetBody**, **DataTableSheetSection**, **DataTableSheetTabs**, **DataTableSheetTabsList**, **DataTableSheetTabPanel**, **DataTableColumnList**, **DataTableFormatOptions** from `impact-nova/data-table`.\n- **Settings sheet layout:** Use compound sheet layout components — not raw `Tabs` + manual `overflow-y-auto`. `DataTableSheetTabPanel layout=\"list\"` for column/KPI lists; `layout=\"scroll\"` for format/filter forms. Resource: `impact-nova://data-table-sheet-layout`.\n- **AG Grid v36 peers:** `ag-grid-community@36.0.1`, `ag-grid-react@36.0.1`, `ag-grid-enterprise@36.0.1` — exact pin, dedupe in Vite. No legacy `ag-theme-*` CSS.\n- **Column settings:** `DataTableColumnList` reads pin/sort/filter from the live `GridApi` (frozen vs scrollable sections). Storybook: `Data/DataTable/Column settings scenarios`.\n- Use **processBackendColumnDefs** from `impact-nova` when column defs come from the backend; type **BackendColDef**.\n- Cell renderers: **AG_GRID_CELL_COMPONENTS** or **LinkCellRenderer** from `impact-nova/ag-grid-react/cell-renderers`; extend/wrap as needed (e.g. PlanningLinkCellRenderer).\n- **Cell comments / notes / row Chat** are independent opt-ins on `DataTableContent`. Omit a prop → zero host. Do not put threads in `rowData`. Do not use AG Grid Notes for comment threads.\n  - **Comments** (`comments={…}` from `impact-nova/ag-grid-react/comments`): cell `{ rowId, colId }` thread. Required: `hasIndicator`, `loadThread`, `persist`, `getAuthor`. Resource: `impact-nova://data-table-comments`. Topic: `comments`.\n  - **Notes** (`notes={…}` from `impact-nova/ag-grid-react/notes`): AG Grid `NotesModule` via public `notesDataSource`. Yellow indicator. Resource: `impact-nova://data-table-notes`. Topic: `notes`.\n  - **Chat** (`chat={…}` from `impact-nova/ag-grid-react/chat`): row `{ getRowId }`, many conversations per row. Required: `hasConversation`, `loadConversation`, `persist`, `getAuthor`. Permissions: `can(action, context)`. Resource: `impact-nova://data-table-chat`. Topic: `chat`.\n\n### Sheet (side panel with form)\n\n- **Sheet**, **SheetContent**, **SheetHeader**, **SheetTitle**, **SheetBody**, **SheetFooter** from `impact-nova/sheet`.\n- Use for “Match With”, “Bulk Edit”, “View Management” panels. Pair with react-hook-form for form content.\n\n### Empty state\n\n- **EmptyContainer** wrapping **EmptyContainerImage**, **EmptyContainerTitle**, **EmptyContainerDescription**, **EmptyContainerAction** (e.g. a Button to “Select filter” or “Add item”).\n- **Lazy illustrations:** When no custom `children` are passed to `EmptyContainerImage`, one random illustration loads via dynamic `import()` — only ~1 webp chunk per empty state, not all 6 upfront. Pass custom children to skip illustration loading entirely.\n\n### Tabs + NestedList + Accordion (view management)\n\n- **Tabs**, **TabsList**, **TabsTrigger**, **TabsContent** for switching sections.\n- **NestedList** with **SelectionMode**; data shape **NestedListItem** from `impact-nova/nested-list`.\n- **Accordion**, **AccordionItem**, **AccordionTrigger**, **AccordionContent** for expandable blocks (e.g. Versions & Variance).\n\n### Chart (Highcharts)\n\n- Use **Chart** from `impact-nova/chart` as the wrapper.\n- For **series, options, and configuration** refer to **Highcharts documentation** ([highcharts.com/docs](https://www.highcharts.com/docs/)); use the Highcharts API for chart behavior. Impact Nova provides the React integration and styling; options/series follow Highcharts.\n- Install: `highcharts@^12`, `highcharts-react-official@^3`, optional `highcharts-border-radius@^0.0.4`.\n\n### Toast + Alert\n\n- **toast**, **Toaster**, **useToast** from `impact-nova`; wrap app with **Toaster**.\n- **Alert**, **AlertTitle**, **AlertDescription**, **AlertIcon** from `impact-nova/alert` for inline or toast-style messages.\n\n### Expandable list row vs virtualized list (independent, composable)\n\nBoth are **decoupled** subpaths. Pick the integration style that fits — preset, compound, or headless hooks.\n\n#### ExpandableListItem (`impact-nova/expandable-list-item`)\n\n| Style | When | Example |\n|-------|------|---------|\n| **Preset** | Data-driven sections from API/config | `<ExpandableListItem title=\"…\" description=\"…\" sections={sections} />` |\n| **Compound** | Custom row layout / slots | `ExpandableListItemRoot` → `Row` → `Checkbox` + `Trigger` → `Content` |\n| **Inside virtualized** | Large lists (optional) | Render preset or compound inside `VirtualizedListItem` |\n\n- Props: **`title`**, **`description`** (not legacy `sku` / `subtitle`)\n- Sections: `ExpandableListItemSection[]` — `metrics` | `attributes` | `custom`\n- Storybook: **Expandable List Item → Composition**\n\n#### Virtualized (`impact-nova/virtualized`)\n\n| Style | When | Example |\n|-------|------|---------|\n| **Compound UI** | New list chrome (search, select-all, viewport) | `VirtualizedList` → `Viewport` → `Content` → `Item` |\n| **Headless hooks** | Full DOM control / existing layout | `useVirtualizedList` + `getItemProps` / `resetRowSize` |\n| **Custom rows** | Any row JSX | ExpandableListItem optional — not required |\n\n- Expandable rows: `getItemProps(index, { measure: isExpanded })`; call `resetRowSize(index)` on collapse\n- Types: `RowSelectionState`, `VirtualRowModel`, `UseVirtualizedListResult`\n- Storybook: **Virtualized List → Composition** and **Custom row UI**\n- Patterns: `query_patterns` → `virtualized-selectable-list`, `expandable-list-item-preset`, `expandable-list-item-compound`\n- **Renamed:** `impact-nova/expandable-sku` → `impact-nova/expandable-list-item`. See `impact-nova://removed-imports`.\n\n### Command Palette & keyboard shortcuts\n\nImplementation is **more involved** than other components. Use the dedicated guide: resource **`impact-nova://command-palette`**.\n\n- **Import:** `import { CommandPaletteProvider, CommandPalette, useShortcut, useGlobalShortcut, ShortcutSettings, ShortcutScopeProvider, Kbd, useCommandPalette, useBrowserShortcuts } from 'impact-nova/command-palette';`\n- **Minimal setup:** Wrap app with `CommandPaletteProvider`; render `<CommandPalette />` once inside it (⌘K overlay). Register commands with `useShortcut` (scoped: page/module/modal) or `useGlobalShortcut` (app-wide). Use correct `scope` for priority (modal > page > module > global).\n- **Multi-table:** When multiple DataTables share the same shortcut, wrap each in `ShortcutScopeProvider` with a unique `instance` so only the focused one responds.\n- **ShortcutSettings:** AG Grid–powered panel for user customisation; put inside a Sheet (e.g. Keyboard Shortcuts settings). For AG Grid behaviour follow `impact-nova://ag-grid-rules`.\n- **Kbd:** Use `<Kbd keybinding={{ key: 'k', meta: true }} />` to show shortcut in UI. **Button trigger:** `useCommandPalette().setOpen(true)`.\n\n---\n\n## 4. App setup\n\n- **CSS once at root**: `import 'impact-nova/dist/impact-nova.css';` (e.g. in App.tsx or main.tsx).\n- **AG Grid**: Set `LicenseManager.setLicenseKey(...)` if using enterprise. Install `ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1`.\n- **Vite**: Dedupe react/ag-grid when using impact-nova to avoid dual instances. Exclude `impact-nova-icons` from `optimizeDeps` to prevent SVG asset warnings in dev:\n\n```js\noptimizeDeps: {\n  exclude: ['impact-nova-icons'],\n},\nresolve: {\n  dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n},\n```\n\n---\n\n## 5. Known workarounds\n\n- **HorizontalScroller**: If the package entry is empty in your build, add a Vite alias to `.../horizontal-scroller/horizontal-scroller.js` and a small `declare module 'impact-nova/horizontal-scroller'` for TypeScript.\n- **Chart**: Prefer `import { Chart } from 'impact-nova/chart'`. Pre-bundle Highcharts UMD modules in Vite `optimizeDeps.include` if you see interop errors in dev.\n\n---\n\n## 6. Forms and options\n\n- **Select options**: Use type **Option** (or **SelectOption**) from `impact-nova/select` for `{ value, label }` (and optional fields). **MultiValue** for multi-select.\n- **react-hook-form**: Use Impact Nova form controls (SmartInput, Select, DateRangePicker, RadioGroup, ButtonGroup, Chips, etc.) as controlled components; pass `value`/`onChange` from the form library.\n- **Validation and errors**: Show validation errors with **Alert** or field-level messages; use the form library’s error state (e.g. `formState.errors`) and optional schema validation (e.g. Zod) with react-hook-form.\n\n### ReactHooksForm (config-driven dynamic forms)\n\nUse when the form layout and rules come from **JSON** (`IFormConfig`) — bulk edit sheets, settings, wizards, filters.\n\n```tsx\nimport { ReactHooksForm, type IFormConfig, type FormContext } from 'impact-nova/form-react';\n\nconst formContext: FormContext = {\n  transport: {\n    fetchSelectOptions: async ({ fieldId, apiConfig }) => { /* your fetch */ },\n    showFormErrorToast: ({ title, description }) => { /* your toast */ },\n  },\n  validateForm: ({ formValues }) => ({ isValid: true }), // optional cross-field rules\n};\n\n<ReactHooksForm formConfig={formConfig} formContext={formContext} onSubmit={handleSubmit} />\n```\n\n| Concept | What it does |\n|---------|----------------|\n| `isRequired` | Mandatory field — blocks submit when visible and empty |\n| `disableDependency` + `__empty__` | Disable child until parent has value; **auto-clear** when parent empties |\n| `disableDependency` + `null` | Disable when other field has any value (mutually exclusive) |\n| `disableDependency` + `\"true\"` | Disable when switch/checkbox is on (grand total, lock) |\n| `visibilityDependency` | Show/hide fields (month range vs multi-month; filter hierarchy) |\n| `formContext.transport` | **Required** for API selects — Nova never calls HTTP |\n| `formContext.validateForm` | Cross-field submit validation (e.g. “at least one edit”) |\n| `doNotIncludeInSubmit` | UI-only toggles excluded from payload |\n| `includeOnlyVisibleFieldsInSubmit` | Only active picker variant submitted |\n\n**MCP resource (full catalog):** `impact-nova://dynamic-form-framework`\n\n**Storybook (12 ItemSmart patterns):** `Dynamic Form / ReactHooksForm` + `Dynamic Form / Guide`\n\n| Story | URL slug |\n|-------|----------|\n| Required fields | `dynamic-form-reacthooksform--required-fields` |\n| Disable dependency | `dynamic-form-reacthooksform--disable-dependency-period-gates-value` |\n| validateForm gate | `dynamic-form-reacthooksform--item-details-bulk-edit-validate-form` |\n| Scenario simulate | `dynamic-form-reacthooksform--scenario-simulate` |\n| Filter disable chain | `dynamic-form-reacthooksform--filter-disable-chain` |\n| Filter visibility | `dynamic-form-reacthooksform--filter-visibility-hierarchy` |\n\n**`query_patterns` ids:** `config-driven-dynamic-form`, `form-required-fields`, `form-visibility-dependency`, `time-phased-metric-bulk-edit`, `form-validate-form-submit-gate`, `form-mutually-exclusive-fields`, `form-switch-disable-bypass`, `form-approval-hub-lock`, `filter-form-dependencies`, `form-filter-visibility-hierarchy`\n\n**Fixtures:** `impact-nova/src/form-react/stories/fixtures/itemSmartProductionFormConfigs.ts`\n\n**ItemSmart reference:** `mtp-mfe-itemsmart-v3/docs/react-hooks-form-production-patterns.md`\n\n**Packages:** `impact-nova/form-engine` · `impact-nova/form-react` · `impact-nova/filter-shell`\n\n---\n\n## 7. Breadcrumb and toolbar\n\n- **Breadcrumb** with **BreadcrumbList**, **BreadcrumbItem**, **BreadcrumbLink**, **BreadcrumbSeparator**, **BreadcrumbPage** for table/section context.\n- **DataTableToolbar** for table toolbars (view mode, view management, filters, Update/Cancel when editing).\n\nUse these patterns so the MCP and generated code stay close to how Impact Nova is used in real apps.\n\n---\n\n## 8. Wizard (multi-step flow)\n\nUse **Wizard** for any multi-step creation or onboarding flow. Radix-style controlled state (`value` / `onValueChange`), optional split-panel layout, and `useWizard()` for flexible footers.\n\n### Import\n\n```ts\nimport {\n  WizardRoot,\n  WizardLayout,\n  WizardSidebar,\n  WizardTitle,\n  WizardDescription,\n  WizardMedia,\n  WizardBody,\n  WizardProgress,\n  WizardHeader,\n  WizardContent,\n  WizardStep,\n  WizardFooter,\n  useWizard,\n} from 'impact-nova/wizard';\n```\n\n### Minimal multi-step example\n\n```tsx\nimport { useState } from 'react';\nimport {\n  WizardRoot, WizardLayout,\n  WizardSidebar, WizardTitle, WizardDescription, WizardMedia,\n  WizardBody, WizardProgress,\n  WizardContent, WizardStep, WizardHeader,\n  WizardFooter,\n} from 'impact-nova/wizard';\nimport { Button } from 'impact-nova/button';\n\nexport function CreateAlertFlow() {\n  const [step, setStep] = useState(1);\n\n  return (\n    <WizardRoot value={step} totalSteps={3} onValueChange={setStep}>\n      <WizardLayout>\n        <WizardSidebar>\n          <WizardTitle>Create Alert</WizardTitle>\n          <WizardDescription>Configure your alert step by step.</WizardDescription>\n          <WizardMedia />\n        </WizardSidebar>\n\n        <WizardBody>\n          <WizardProgress />\n          <WizardContent>\n            <WizardStep value={1}>\n              <WizardHeader>Alert Details</WizardHeader>\n            </WizardStep>\n            <WizardStep value={2}>\n              <WizardHeader>Configuration</WizardHeader>\n            </WizardStep>\n            <WizardStep value={3}>\n              <WizardHeader>Review</WizardHeader>\n            </WizardStep>\n          </WizardContent>\n          <WizardFooter>\n            <Button variant=\"secondary\">Cancel</Button>\n            <Button variant=\"default\">Submit</Button>\n          </WizardFooter>\n        </WizardBody>\n      </WizardLayout>\n    </WizardRoot>\n  );\n}\n```\n\n### Key rules\n\n- **WizardRoot** is the context provider — every other sub-component must be a descendant.\n- Use **useWizard()** for `goNext`, `goBack`, `isFirstStep`, `isLastStep` without prop drilling.\n- **WizardStep** renders nothing when `value` doesn't match the current step — use one per step.\n- **WizardMedia** renders a default SVG when neither `src` nor `children` are provided.\n- The sidebar is hidden below the `lg` breakpoint.\n- All sub-components except **WizardRoot** are optional — compose only what you need.\n---\n\n## 9. App layout (app shell)\n\n**Use `Layout`** for the app chrome — not `DynamicLayout` (that is a grid/flex/stack utility only).\n\nFull beginner scaffold: resource **`impact-nova://layout`**.\n\n### Structure\n\n```tsx\nimport { Layout } from 'impact-nova/layout';\nimport { Sidebar, SidebarProvider } from 'impact-nova/sidebar';\nimport { Header, HeaderLeft, HeaderTitle } from 'impact-nova/header';\nimport { BreadcrumbHeader, Breadcrumb, BreadcrumbList } from 'impact-nova/breadcrumb';\nimport { FilterStrip } from 'impact-nova/filter-strip';\n\n<SidebarProvider defaultOpen={false} id=\"app-sidebar\" className=\"flex h-svh min-h-0 w-full min-w-0 overflow-hidden\">\n  <Layout\n    sidebar={<Sidebar collapsible=\"offcanvas\">...</Sidebar>}\n    header={<Header>...</Header>}\n  >\n    {/* Page content — Item Smart parity */}\n    <PageShell>\n      <PageStickyHeader pageTitle=\"...\" filterStrip={filtersApplied ? <FilterStrip ... /> : undefined} />\n      {filtersApplied ? <WorkspaceBody /> : <EmptyStateView title=\"...\" primaryActionLabel=\"Select filter\" />}\n    </PageShell>\n  </Layout>\n</SidebarProvider>\n```\n\n### Key rules\n\n- **`SidebarProvider` at app root** — wraps `Layout`, not inside the sidebar slot.\n- **Page background** — `PageShell` → `bg-brand-subtle` (not `bg-canvas-wash` on module pages)\n- **Filter strip** — white sticky bar via `PageStickyHeader` `filterStrip` slot (`page-filter-strip` class)\n- **Tables** — `module-table-container mx-6 flex min-h-[480px] flex-1` → white `DataTable` card with shadow\n- **Subpath imports** — `impact-nova/layout`, `impact-nova/sidebar`, `impact-nova/header`, `impact-nova/breadcrumb`, `impact-nova/filter-strip`.\n- **With React Router** — put `<Outlet />` inside `Layout` children; route pages render breadcrumb + body.\n- **With Command Palette** — `CommandPaletteProvider` at root; `<CommandPalette />` as sibling inside `SidebarProvider`. See `impact-nova://command-palette`.\n\n### Premium primitives (shipped in create-impact-nova template)\n\n| Component | Role |\n|-----------|------|\n| `PageShell` | `bg-brand-subtle` + flex fill chain |\n| `PageStickyHeader` | Breadcrumb `z-30` + white filter strip slot |\n| `EmptyStateView` | Illustration + primary/secondary CTAs |\n| `SummaryMetricCard` | Dashboard KPI tiles (`border-[#C3C8D4]`, hover shadow) |\n| `module-table-container` | Table card shadow + `min-h-[480px] flex-1` fill |\n";

package/dist/llms/rules/requirements.js

@@ -1 +1 @@
-export default "# Impact Nova — baseline\n\nUse **Impact Nova** design-system components and tokens. Prefer subpath imports (e.g. `impact-nova/button`) when you only need a few modules. For live component lists, specs, and codegen, use the **impact-nova-mcp** MCP server (see npm `impact-nova-mcp`). Browse **Storybook**: https://impact-nova.iaproducts.ai/\n\n## Peer dependency summary\n\n```json\n{\n  \"impactNova\": {\n    \"package\": \"impact-nova\",\n    \"recommendedVersion\": \"2.5.15\",\n    \"recommendedDistTag\": \"latest\",\n    \"description\": \"Design system package — ESM with 90+ subpath exports. Install: npm install impact-nova@latest\"\n  },\n  \"createImpactNova\": {\n    \"package\": \"create-impact-nova\",\n    \"recommendedVersion\": \"^1.4.9\",\n    \"description\": \"Vite + React scaffold with recipe-based modules\"\n  },\n  \"localDevelopment\": {\n    \"defaultScaffoldDependency\": \"auto\",\n    \"description\": \"create-impact-nova auto-detects: file: link when run inside the impact-nova monorepo; npm (impact-nova@^2.5.15) otherwise. CLI: --from-npm or --link-monorepo to override. Rebuild impact-nova (npm run build) after DS changes when using file: link.\",\n    \"cliFlagForNpm\": \"--from-npm\",\n    \"cliFlagForMonorepo\": \"--link-monorepo\",\n    \"mcpScaffoldFlag\": \"usePublishedPackages: true | false (omit for auto-detect)\"\n  },\n  \"mandatoryRules\": {\n    \"componentsOnly\": \"Use Impact Nova components only — never create new custom UI components\",\n    \"tables\": \"Any table/grid/spreadsheet → DataTable from impact-nova/data-table (not HTML table, not raw ag-grid-react)\",\n    \"validateBeforeDone\": \"Call validate_snippet on generated UI code\",\n    \"resource\": \"impact-nova://design-system-mandate\"\n  },\n  \"requiredPeers\": [\n    {\n      \"package\": \"react\",\n      \"recommendedVersion\": \"^19.0.0\",\n      \"description\": \"React 19 required\"\n    },\n    {\n      \"package\": \"react-dom\",\n      \"recommendedVersion\": \"^19.0.0\",\n      \"description\": \"React DOM 19 required\"\n    },\n    {\n      \"package\": \"impact-nova-icons\",\n      \"recommendedVersion\": \">=0.1.0\",\n      \"description\": \"Icons peer — not bundled in impact-nova; 0.1.x and 0.2.x supported\"\n    }\n  ],\n  \"optionalPeers\": [\n    {\n      \"package\": \"ag-grid-community\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"AG Grid community types/API; pin to the same version as ag-grid-react\"\n    },\n    {\n      \"package\": \"ag-grid-react\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"For DataTable and grid components; use exact version to match Impact Nova\"\n    },\n    {\n      \"package\": \"ag-grid-enterprise\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"Required if using ag-grid-react with enterprise features\"\n    },\n    {\n      \"package\": \"highcharts\",\n      \"recommendedVersion\": \"^12.0.0\",\n      \"description\": \"For Chart component\"\n    },\n    {\n      \"package\": \"highcharts-react-official\",\n      \"recommendedVersion\": \"^3.0.0\",\n      \"description\": \"For Chart component\"\n    },\n    {\n      \"package\": \"highcharts-border-radius\",\n      \"recommendedVersion\": \"^0.0.4\",\n      \"description\": \"Optional Highcharts plugin for rounded corners\"\n    }\n  ]\n}\n```\n";
+export default "# Impact Nova — baseline\n\nUse **Impact Nova** design-system components and tokens. Prefer subpath imports (e.g. `impact-nova/button`) when you only need a few modules. For live component lists, specs, and codegen, use the **impact-nova-mcp** MCP server (see npm `impact-nova-mcp`). Browse **Storybook**: https://impact-nova.iaproducts.ai/\n\n## Peer dependency summary\n\n```json\n{\n  \"impactNova\": {\n    \"package\": \"impact-nova\",\n    \"recommendedVersion\": \"2.6.0-alpha.0\",\n    \"recommendedDistTag\": \"latest\",\n    \"description\": \"Design system package — ESM with 90+ subpath exports. Install: npm install impact-nova@latest\"\n  },\n  \"createImpactNova\": {\n    \"package\": \"create-impact-nova\",\n    \"recommendedVersion\": \"^1.4.9\",\n    \"description\": \"Vite + React scaffold with recipe-based modules\"\n  },\n  \"localDevelopment\": {\n    \"defaultScaffoldDependency\": \"auto\",\n    \"description\": \"create-impact-nova auto-detects: file: link when run inside the impact-nova monorepo; npm (impact-nova@^2.6.0-alpha.0) otherwise. CLI: --from-npm or --link-monorepo to override. Rebuild impact-nova (npm run build) after DS changes when using file: link.\",\n    \"cliFlagForNpm\": \"--from-npm\",\n    \"cliFlagForMonorepo\": \"--link-monorepo\",\n    \"mcpScaffoldFlag\": \"usePublishedPackages: true | false (omit for auto-detect)\"\n  },\n  \"mandatoryRules\": {\n    \"componentsOnly\": \"Use Impact Nova components only — never create new custom UI components\",\n    \"tables\": \"Any table/grid/spreadsheet → DataTable from impact-nova/data-table (not HTML table, not raw ag-grid-react)\",\n    \"validateBeforeDone\": \"Call validate_snippet on generated UI code\",\n    \"resource\": \"impact-nova://design-system-mandate\"\n  },\n  \"requiredPeers\": [\n    {\n      \"package\": \"react\",\n      \"recommendedVersion\": \"^19.0.0\",\n      \"description\": \"React 19 required\"\n    },\n    {\n      \"package\": \"react-dom\",\n      \"recommendedVersion\": \"^19.0.0\",\n      \"description\": \"React DOM 19 required\"\n    },\n    {\n      \"package\": \"impact-nova-icons\",\n      \"recommendedVersion\": \">=0.1.0\",\n      \"description\": \"Icons peer — not bundled in impact-nova; 0.1.x and 0.2.x supported\"\n    }\n  ],\n  \"optionalPeers\": [\n    {\n      \"package\": \"ag-grid-community\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"AG Grid community types/API; pin to the same version as ag-grid-react\"\n    },\n    {\n      \"package\": \"ag-grid-react\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"For DataTable and grid components; use exact version to match Impact Nova\"\n    },\n    {\n      \"package\": \"ag-grid-enterprise\",\n      \"recommendedVersion\": \"36.0.1\",\n      \"description\": \"Required if using ag-grid-react with enterprise features\"\n    },\n    {\n      \"package\": \"highcharts\",\n      \"recommendedVersion\": \"^12.0.0\",\n      \"description\": \"For Chart component\"\n    },\n    {\n      \"package\": \"highcharts-react-official\",\n      \"recommendedVersion\": \"^3.0.0\",\n      \"description\": \"For Chart component\"\n    },\n    {\n      \"package\": \"highcharts-border-radius\",\n      \"recommendedVersion\": \"^0.0.4\",\n      \"description\": \"Optional Highcharts plugin for rounded corners\"\n    }\n  ]\n}\n```\n";

package/dist/llms/rules/troubleshooting.js

@@ -1 +1 @@
-export default "# Impact Nova — Troubleshooting\n\nCommon setup and runtime issues when using Impact Nova, and how to fix them.\n\n---\n\n## 1. Duplicate React or AG Grid (Vite)\n\n**Symptom:** \"Invalid hook call\", \"Multiple copies of React\", or AG Grid warnings about multiple instances.\n\n**Fix:** In Vite config, add `resolve.dedupe` so the app uses a single copy of React and AG Grid:\n\n```js\n// vite.config.js / vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n  resolve: {\n    dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n  },\n});\n```\n\n---\n\n## 2. Styles not applying\n\n**Symptom:** Components render but look unstyled or wrong.\n\n**Fix:**\n\n- Import Impact Nova CSS **once** at the app root, **before** your app component:  \n  `import 'impact-nova/dist/impact-nova.css';`  \n  Or, if you use **CSS or SCSS (no Tailwind)**, you can `@import 'impact-nova/dist/impact-nova.css';` in your main.css or main.scss. See installation **§5. Using Impact Nova with CSS or SCSS (no Tailwind)**.\n- Ensure your build includes the CSS (no rule excluding `node_modules/impact-nova`).\n- If using Tailwind, ensure the design system tokens aren’t overridden by a conflicting Tailwind theme.\n\n---\n\n## 3. Font (Manrope) not loading\n\n**Symptom:** Text renders in fallback font.\n\n**Fix:**\n\n- Add the Manrope link in `index.html`:  \n  `<link href=\"https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap\" rel=\"stylesheet\" />`\n- In global CSS or Tailwind base:  \n  `body { font-family: 'Manrope', sans-serif; }`\n\n---\n\n## 4. Chart component not found or wrong export\n\n**Symptom:** `import { Chart } from 'impact-nova'` fails, Chart doesn't render, or dev throws:\n\n`The requested module '.../highcharts-react-official/dist/highcharts-react.min.js' does not provide an export named 'default'`\n\n**Fix:**\n\n- Use the public subpath: `import { Chart } from 'impact-nova/chart';`\n- Ensure Highcharts is installed: `npm install highcharts@^12 highcharts-react-official@^3`\n- In Vite, add `highcharts-react-official` to `optimizeDeps.include` (the `create-impact-nova` template includes it in `HIGHCHARTS_OPTIMIZE_DEPENDENCIES`). Clear `.vite` cache and restart dev after changing config.\n\n---\n\n## 5. impact-nova-icons SVG warnings in Vite dev\n\n**Symptom:** Hundreds of \"Failed to resolve import\" warnings for `.svg` files from `impact-nova-icons` on dev startup.\n\n**Fix:** Exclude icons from dependency pre-bundling:\n\n```js\noptimizeDeps: {\n  exclude: ['impact-nova-icons'],\n},\n```\n\nIf using Module Federation, add an asset URL rewrite plugin for `impact-nova-icons/dist/assets/*2.svg.js` shims.\n\n---\n\n## 6. React 19 — \"Cannot access refs during render\"\n\n**Symptom:** React 19 error about updating or reading refs during render.\n\n**Fix:** Never assign to `ref.current` during render. Use refs only in event handlers, effects, or callbacks. Prefer deriving values during render instead of mirroring props into refs.\n\n---\n\n## 6b. Truncated text tooltip not showing\n\n**Symptom:** `OverflowTooltip` never opens, or tooltips appear inside AG Grid cells incorrectly.\n\n**Fix:**\n\n- Ensure the trigger has **`truncate`** (or `line-clamp`) and a bounded width so CSS overflow can occur.\n- Pass explicit **`content`** when children are not plain text.\n- Inside buttons, Select options, or comboboxes: keep default **`focusable={false}`** (pointer-only).\n- **AG Grid cells:** use `useAgGridTruncationTooltip` from `impact-nova/ag-grid-react` — do not use `OverflowTooltip` in cell renderers.\n\n---\n\n## 7. HorizontalScroller or other subpath missing\n\n**Symptom:** Import from `impact-nova/horizontal-scroller` (or similar) fails.\n\n**Fix:**\n\n- If the package doesn’t export that subpath, add a Vite alias to the component file and a small TypeScript declaration:\n\n```js\n// vite.config\nresolve: {\n  alias: {\n    'impact-nova/horizontal-scroller': resolve(__dirname, 'node_modules/impact-nova/dist/components/ui/horizontal-scroller/horizontal-scroller.js'),\n  },\n},\n```\n\n```ts\n// declare module 'impact-nova/horizontal-scroller'\ndeclare module 'impact-nova/horizontal-scroller' {\n  const Component: React.ComponentType<{ /* props */ }>;\n  export default Component;\n}\n```\n\n---\n\n## 8. AG Grid CSS not applied (legacy container conflict)\n\n**Symptom:** AG Grid in a micro-frontend (MFE) looks wrong or unstyled; the new AG Grid theme is not applied.\n\n**Cause:** The **container** (host app) is loading legacy AG Grid CSS. Those legacy style tags conflict with the new theme, so the MFE’s AG Grid doesn’t get the correct styles.\n\n**Fix:** Apply the fix in the **container** app, not in the MFE/remote repo. In the container, when you mount the remote (e.g. in a `useEffect`), remove the legacy AG Grid style tags from the document so the new theme can apply. Example:\n\n```tsx\n// In the CONTAINER app (not in the MFE repo)\nuseEffect(() => {\n  const { onParentNavigate } = mount(ref.current, {\n    initialPath: history.location.pathname,\n    onNavigate: ({ pathname: nextPathname }) => {\n      const { pathname } = history.location;\n      if (pathname !== nextPathname) {\n        history.push(nextPathname);\n      }\n    },\n    containerStore,\n    routes,\n    defaultHistory: history,\n  });\n\n  history.listen(onParentNavigate);\n\n  const removeAgGridStyles = () => {\n    const styleTags = document.querySelectorAll('style');\n    styleTags.forEach((styleTag) => {\n      const content = styleTag.textContent || styleTag.innerHTML || '';\n      // Legacy AG Grid styles (--ag-legacy-styles-loaded + .ag-icon)\n      const isLegacyStyles =\n        content.includes('--ag-legacy-styles-loaded') && content.includes('.ag-icon');\n      // Generic AG Grid selectors that override the new theme\n      const hasAgGridSelectors =\n        content.includes('ag-grid,ag-grid-angular') ||\n        content.includes('ag-grid, ag-grid-angular') ||\n        content.includes('ag-grid-ng2') ||\n        content.includes('ag-grid-polymer') ||\n        content.includes('ag-grid-aurelia');\n      if (isLegacyStyles || hasAgGridSelectors) {\n        styleTag.remove();\n      }\n    });\n  };\n\n  removeAgGridStyles();\n\n  const domNode = document.getElementById('itemsmart-remote'); // or your remote mount node id\n  return () => {\n    unmountComponentAtNode(domNode);\n  };\n}, []);\n```\n\nAdjust `mount`, `ref`, `history`, `containerStore`, `routes`, and the mount node id to match your container’s setup. The important part is calling `removeAgGridStyles()` so legacy AG Grid `<style>` tags are removed and the new theme can apply.\n\n---\n\n## 9. AG Grid license or enterprise features\n\n**Symptom:** AG Grid shows watermark or enterprise features don’t work.\n\n**Fix:** Set the license key once (e.g. in root or layout):\n\n```ts\nimport { LicenseManager } from 'ag-grid-enterprise';\n\nLicenseManager.setLicenseKey('your-license-key');\n```\n\n---\n\n## 10. i18n / locale not applied\n\n**Symptom:** Date pickers, selects, or other components show wrong locale or default English.\n\n**Fix:** Wrap the app with `ImpactNovaProviders` from `impact-nova/form` and pass the correct `locale` (and optional `messages`):\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\nimport { de } from 'impact-nova/locale/de';\n\n<ImpactNovaProviders locale=\"de\" messages={de}>\n  <App />\n</ImpactNovaProviders>\n```\n\n---\n\n## 11. React 19 compatibility\n\n**Symptom:** Peer dependency warnings or runtime errors after adding Impact Nova.\n\n**Fix:** Impact Nova targets React 19. Upgrade React and React DOM:\n\n```bash\nnpm install react@^19 react-dom@^19\n```\n\nUse `analyze_project_for_impact_nova` with your `package.json` content to get exact recommended versions and install commands.\n\n---\n\nUse `get_installation_and_config` for full setup steps and `impact-nova://install` for the installation resource.\n";
+export default "# Impact Nova — Troubleshooting\n\nCommon setup and runtime issues when using Impact Nova, and how to fix them.\n\n---\n\n## 1. Duplicate React or AG Grid (Vite)\n\n**Symptom:** \"Invalid hook call\", \"Multiple copies of React\", or AG Grid warnings about multiple instances.\n\n**Fix:** In Vite config, add `resolve.dedupe` so the app uses a single copy of React and AG Grid:\n\n```js\n// vite.config.js / vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n  resolve: {\n    dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n  },\n});\n```\n\n---\n\n## 2. Styles not applying\n\n**Symptom:** Components render but look unstyled or wrong.\n\n**Fix:**\n\n- Import Impact Nova CSS **once** at the app root, **before** your app component:  \n  `import 'impact-nova/dist/impact-nova.css';`  \n  Or, if you use **CSS or SCSS (no Tailwind)**, you can `@import 'impact-nova/dist/impact-nova.css';` in your main.css or main.scss. See installation **§5. Using Impact Nova with CSS or SCSS (no Tailwind)**.\n- Ensure your build includes the CSS (no rule excluding `node_modules/impact-nova`).\n- If using Tailwind, ensure the design system tokens aren’t overridden by a conflicting Tailwind theme.\n\n---\n\n## 3. Font (Manrope) not loading\n\n**Symptom:** Text renders in fallback font.\n\n**Fix:**\n\n- Add the Manrope link in `index.html`:  \n  `<link href=\"https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap\" rel=\"stylesheet\" />`\n- In global CSS or Tailwind base:  \n  `body { font-family: 'Manrope', sans-serif; }`\n\n---\n\n## 4. Chart component not found or wrong export\n\n**Symptom:** `import { Chart } from 'impact-nova'` fails, Chart doesn't render, or dev throws:\n\n`The requested module '.../highcharts-react-official/dist/highcharts-react.min.js' does not provide an export named 'default'`\n\n**Fix:**\n\n- Use the public subpath: `import { Chart } from 'impact-nova/chart';`\n- Ensure Highcharts is installed: `npm install highcharts@^12 highcharts-react-official@^3`\n- In Vite, add `highcharts-react-official` to `optimizeDeps.include` (the `create-impact-nova` template includes it in `HIGHCHARTS_OPTIMIZE_DEPENDENCIES`). Clear `.vite` cache and restart dev after changing config.\n\n---\n\n## 5. impact-nova-icons SVG warnings in Vite dev\n\n**Symptom:** Hundreds of \"Failed to resolve import\" warnings for `.svg` files from `impact-nova-icons` on dev startup.\n\n**Fix:** Exclude icons from dependency pre-bundling:\n\n```js\noptimizeDeps: {\n  exclude: ['impact-nova-icons'],\n},\n```\n\nIf using Module Federation, add an asset URL rewrite plugin for `impact-nova-icons/dist/assets/*2.svg.js` shims.\n\n---\n\n## 6. React 19 — \"Cannot access refs during render\"\n\n**Symptom:** React 19 error about updating or reading refs during render.\n\n**Fix:** Never assign to `ref.current` during render. Use refs only in event handlers, effects, or callbacks. Prefer deriving values during render instead of mirroring props into refs.\n\n---\n\n## 6b. Truncated text tooltip not showing\n\n**Symptom:** `OverflowTooltip` never opens, or tooltips appear inside AG Grid cells incorrectly.\n\n**Fix:**\n\n- Ensure the trigger has **`truncate`** (or `line-clamp`) and a bounded width so CSS overflow can occur.\n- Pass explicit **`content`** when children are not plain text.\n- Inside buttons, Select options, or comboboxes: keep default **`focusable={false}`** (pointer-only).\n- **AG Grid cells:** use `useAgGridTruncationTooltip` from `impact-nova/ag-grid-react` — do not use `OverflowTooltip` in cell renderers.\n\n---\n\n## 7. HorizontalScroller or other subpath missing\n\n**Symptom:** Import from `impact-nova/horizontal-scroller` (or similar) fails.\n\n**Fix:**\n\n- If the package doesn’t export that subpath, add a Vite alias to the component file and a small TypeScript declaration:\n\n```js\n// vite.config\nresolve: {\n  alias: {\n    'impact-nova/horizontal-scroller': resolve(__dirname, 'node_modules/impact-nova/dist/components/ui/horizontal-scroller/horizontal-scroller.js'),\n  },\n},\n```\n\n```ts\n// declare module 'impact-nova/horizontal-scroller'\ndeclare module 'impact-nova/horizontal-scroller' {\n  const Component: React.ComponentType<{ /* props */ }>;\n  export default Component;\n}\n```\n\n---\n\n## 8. AG Grid CSS not applied (legacy container conflict)\n\n**Symptom:** AG Grid in a micro-frontend (MFE) looks wrong or unstyled; the new AG Grid theme is not applied.\n\n**Cause:** The **container** (host app) is loading legacy AG Grid CSS. Those legacy style tags conflict with the new theme, so the MFE’s AG Grid doesn’t get the correct styles.\n\n**Fix:** Apply the fix in the **container** app, not in the MFE/remote repo. In the container, when you mount the remote (e.g. in a `useEffect`), remove the legacy AG Grid style tags from the document so the new theme can apply. Example:\n\n```tsx\n// In the CONTAINER app (not in the MFE repo)\nuseEffect(() => {\n  const { onParentNavigate } = mount(ref.current, {\n    initialPath: history.location.pathname,\n    onNavigate: ({ pathname: nextPathname }) => {\n      const { pathname } = history.location;\n      if (pathname !== nextPathname) {\n        history.push(nextPathname);\n      }\n    },\n    containerStore,\n    routes,\n    defaultHistory: history,\n  });\n\n  history.listen(onParentNavigate);\n\n  const removeAgGridStyles = () => {\n    const styleTags = document.querySelectorAll('style');\n    styleTags.forEach((styleTag) => {\n      const content = styleTag.textContent || styleTag.innerHTML || '';\n      // Legacy AG Grid styles (--ag-legacy-styles-loaded + .ag-icon)\n      const isLegacyStyles =\n        content.includes('--ag-legacy-styles-loaded') && content.includes('.ag-icon');\n      // Generic AG Grid selectors that override the new theme\n      const hasAgGridSelectors =\n        content.includes('ag-grid,ag-grid-angular') ||\n        content.includes('ag-grid, ag-grid-angular') ||\n        content.includes('ag-grid-ng2') ||\n        content.includes('ag-grid-polymer') ||\n        content.includes('ag-grid-aurelia');\n      if (isLegacyStyles || hasAgGridSelectors) {\n        styleTag.remove();\n      }\n    });\n  };\n\n  removeAgGridStyles();\n\n  const domNode = document.getElementById('itemsmart-remote'); // or your remote mount node id\n  return () => {\n    unmountComponentAtNode(domNode);\n  };\n}, []);\n```\n\nAdjust `mount`, `ref`, `history`, `containerStore`, `routes`, and the mount node id to match your container’s setup. The important part is calling `removeAgGridStyles()` so legacy AG Grid `<style>` tags are removed and the new theme can apply.\n\n---\n\n## 9. AG Grid license or enterprise features\n\n**Symptom:** AG Grid shows watermark or enterprise features don’t work.\n\n**Fix:** Set the license key once (e.g. in root or layout):\n\n```ts\nimport { LicenseManager } from 'ag-grid-enterprise';\n\nLicenseManager.setLicenseKey('your-license-key');\n```\n\n---\n\n## 10. i18n / locale not applied\n\n**Symptom:** Date pickers, selects, or numbers show US formatting, or UI copy stays English after setting `locale`.\n\n**Fix:** Wrap the app with `ImpactNovaProviders` from `impact-nova/form`. Formatting uses BCP 47 (`locale`, optional `dateLocale` / `numberLocale`). UI copy is a separate opt-in pack — `locale=\"de-DE\"` does not load German messages by itself.\n\n```tsx\nimport { ImpactNovaProviders } from 'impact-nova/form';\nimport { de } from 'impact-nova/locale/de';\nimport { formatDate, formatNumber } from 'impact-nova/i18n';\n\n<ImpactNovaProviders locale=\"de-DE\" messages={de}>\n  <App />\n</ImpactNovaProviders>\n```\n\nDo not call `toLocaleString` in feature code. Use `formatDate` / `formatNumber` with `dateLocale` / `numberLocale` from `useImpactNovaI18n()`. See `impact-nova://i18n`.\n\n---\n\n## 11. React 19 compatibility\n\n**Symptom:** Peer dependency warnings or runtime errors after adding Impact Nova.\n\n**Fix:** Impact Nova targets React 19. Upgrade React and React DOM:\n\n```bash\nnpm install react@^19 react-dom@^19\n```\n\nUse `analyze_project_for_impact_nova` with your `package.json` content to get exact recommended versions and install commands.\n\n---\n\nUse `get_installation_and_config` for full setup steps and `impact-nova://install` for the installation resource.\n";

package/dist/providers/app-providers.d.ts

@@ -5,9 +5,11 @@ export interface ImpactNovaProvidersProps {
     /** TooltipProvider delay (ms). */
     tooltipDelayDuration?: number;
     locale?: string;
+    dateLocale?: string;
+    numberLocale?: string;
     messages?: ImpactNovaMessages;
 }
 /**
  * App-level Impact Nova providers — mount once at root (Next.js `app/providers.tsx`).
  */
-export declare function ImpactNovaProviders({ children, tooltipDelayDuration, locale, messages, }: ImpactNovaProvidersProps): import("react/jsx-runtime").JSX.Element;
+export declare function ImpactNovaProviders({ children, tooltipDelayDuration, locale, dateLocale, numberLocale, messages, }: ImpactNovaProvidersProps): import("react/jsx-runtime").JSX.Element;

package/dist/providers/app-providers.js

@@ -1,23 +1,34 @@
 import { jsx as o } from "react/jsx-runtime";
 import "react";
-import { ImpactNovaI18nProvider as a } from "../i18n/impact-nova-i18n-context.js";
-import { defaultMessages as m } from "../i18n/defaultMessages.js";
-import { TooltipProvider as n } from "../components/feedback/tooltip/tooltip.js";
-function v({
+import { ImpactNovaI18nProvider as n } from "../i18n/impact-nova-i18n-context.js";
+import { defaultMessages as p } from "../i18n/defaultMessages.js";
+import { TooltipProvider as d } from "../components/feedback/tooltip/tooltip.js";
+function u({
   children: r,
   tooltipDelayDuration: e = 200,
   locale: t = "en",
-  messages: i = m
+  dateLocale: i,
+  numberLocale: a,
+  messages: m = p
 }) {
-  return /* @__PURE__ */ o(a, { locale: t, messages: i, children: /* @__PURE__ */ o(
+  return /* @__PURE__ */ o(
     n,
     {
-      delayDuration: e,
-      disableHoverableContent: !1,
-      children: r
+      locale: t,
+      dateLocale: i,
+      numberLocale: a,
+      messages: m,
+      children: /* @__PURE__ */ o(
+        d,
+        {
+          delayDuration: e,
+          disableHoverableContent: !1,
+          children: r
+        }
+      )
     }
-  ) });
+  );
 }
 export {
-  v as ImpactNovaProviders
+  u as ImpactNovaProviders
 };