npm - impact-nova - Versions diffs - 2.5.8 → 2.5.9 - Mend

impact-nova 2.5.8 → 2.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

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

	@@ -1 +1 @@
1	- export default "# Impact Nova — Best Practices & Do's and Don'ts\n\n## Use Impact Nova components only\n\nWhen 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\nPrefer 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\nVite 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\nRules:\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## AG Grid / Data tables (mandatory)\n\nWhen 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";
1	+ export default "# Impact Nova — Best Practices & Do's and Don'ts\n\n## Use Impact Nova components only\n\nWhen 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\nPrefer 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\nVite 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\nRules:\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\nDo 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\nWhen 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";

package/dist/llms/rules/installation.js CHANGED Viewed

	@@ -1 +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.7` 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.7` 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\nOverrides: 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\nLocal 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\nRequired peers: `react@^19`, `react-dom@^19`, `impact-nova-icons@^0.1.1`\n\nOptional 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\nBarrel 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\nDo not copy Storybook preset JSON or `theme-presets.ts` into consumer apps. Presets are not in the published package.\n\nCustom 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";
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.8` 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.8` 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\nOverrides: 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\nLocal 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\nRequired peers: `react@^19`, `react-dom@^19`, `impact-nova-icons@^0.1.1`\n\nOptional 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\nBarrel 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\nDo not copy Storybook preset JSON or `theme-presets.ts` into consumer apps. Presets are not in the published package.\n\nCustom 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/real-world-patterns.js CHANGED Viewed

	@@ -1 +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\nDefault 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` \|\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\nMandatory (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\nMCP resource (full catalog): `impact-nova://dynamic-form-framework`\n\nStorybook (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\nFixtures: `impact-nova/src/form-react/stories/fixtures/itemSmartProductionFormConfigs.ts`\n\nItemSmart reference: `mtp-mfe-itemsmart-v3/docs/react-hooks-form-production-patterns.md`\n\nPackages: `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\nUse `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";
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\nDefault 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\nMandatory (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\nMCP resource (full catalog): `impact-nova://dynamic-form-framework`\n\nStorybook (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\nFixtures: `impact-nova/src/form-react/stories/fixtures/itemSmartProductionFormConfigs.ts`\n\nItemSmart reference: `mtp-mfe-itemsmart-v3/docs/react-hooks-form-production-patterns.md`\n\nPackages: `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\nUse `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 CHANGED Viewed

	@@ -1 +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.7\",\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.7\",\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.7) 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";
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.8\",\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.8\",\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.8) 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/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "impact-nova",
-  "version": "2.5.8",
+  "version": "2.5.9",
   "description": "Enterprise-grade React design system built with React 19, Vite, Tailwind CSS, and Radix UI. Built-in internationalization (i18n) and comprehensive UI component library for scalable, accessible, and performant applications.",
   "type": "module",
   "workspaces": [