impact-nova 1.7.21 → 1.7.23

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\nPrefer **subpath imports** when you need only a few exports; use the barrel `impact-nova` when you need many from the same area.\n\n| Use case | Import |\n|----------|--------|\n| Button only | `import { Button } from 'impact-nova/button';` |\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| 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, getIconComponent } from 'impact-nova/icons';` |\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**, **DataTableColumnList**, **DataTableFormatOptions** from `impact-nova`.\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\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` (or `impact-nova/chart` if available) 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### 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.\n- **Vite**: Dedupe react/ag-grid when using impact-nova to avoid dual instances:\n\n```js\nresolve: {\n  dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n  alias: {\n    // If impact-nova/horizontal-scroller doesn't re-export default:\n    'impact-nova/horizontal-scroller': resolve(__dirname, 'node_modules/impact-nova/dist/components/ui/horizontal-scroller/horizontal-scroller.js'),\n  },\n},\n```\n\n---\n\n## 5. Known workarounds\n\n- **HorizontalScroller**: Some builds expose it as default export from the component file; if the package entry is empty, add a Vite alias to `.../horizontal-scroller/horizontal-scroller.js` and a small `declare module 'impact-nova/horizontal-scroller'` (default export + props type) for TypeScript.\n- **Chart**: If the main export path doesn’t work, apps sometimes use `import { Chart as ImpactChart } from 'impact-nova/dist/components/ui/chart/chart';`. Prefer the public export when available.\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---\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";
+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\nPrefer **subpath imports** when you need only a few exports; use the barrel `impact-nova` when you need many from the same area.\n\n| Use case | Import |\n|----------|--------|\n| Button only | `import { Button } from 'impact-nova/button';` |\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| 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, getIconComponent } from 'impact-nova/icons';` |\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**, **DataTableColumnList**, **DataTableFormatOptions** from `impact-nova`.\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\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` (or `impact-nova/chart` if available) 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### 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.\n- **Vite**: Dedupe react/ag-grid when using impact-nova to avoid dual instances:\n\n```js\nresolve: {\n  dedupe: ['react', 'react-dom', 'ag-grid-community', 'ag-grid-enterprise', 'ag-grid-react'],\n  alias: {\n    // If impact-nova/horizontal-scroller doesn't re-export default:\n    'impact-nova/horizontal-scroller': resolve(__dirname, 'node_modules/impact-nova/dist/components/ui/horizontal-scroller/horizontal-scroller.js'),\n  },\n},\n```\n\n---\n\n## 5. Known workarounds\n\n- **HorizontalScroller**: Some builds expose it as default export from the component file; if the package entry is empty, add a Vite alias to `.../horizontal-scroller/horizontal-scroller.js` and a small `declare module 'impact-nova/horizontal-scroller'` (default export + props type) for TypeScript.\n- **Chart**: If the main export path doesn’t work, apps sometimes use `import { Chart as ImpactChart } from 'impact-nova/dist/components/ui/chart/chart';`. Prefer the public export when available.\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---\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. CreateItemFlow (multi-step creation wizard)\n\nUse **CreateItemFlow** for any multi-step creation or onboarding wizard. It provides a split-panel layout with a left sidebar and a right content area driven by a shared context.\n\n### Import\n\n```ts\nimport {\n  CreateItemFlowRoot,\n  CreateItemFlowCard,\n  CreateItemFlowLeftPanel,\n  CreateItemFlowTitle,\n  CreateItemFlowDescription,\n  CreateItemFlowImage,\n  CreateItemFlowRightPanel,\n  CreateItemFlowStepper,\n  CreateItemFlowContentTitle,\n  CreateItemFlowContentDescription,\n  CreateItemFlowContent,\n  CreateItemFlowStepContent,\n  CreateItemFlowActions,\n} from 'impact-nova';\n```\n\n### Minimal multi-step example\n\n```tsx\nimport { useState } from 'react';\nimport {\n  CreateItemFlowRoot, CreateItemFlowCard,\n  CreateItemFlowLeftPanel, CreateItemFlowTitle, CreateItemFlowDescription, CreateItemFlowImage,\n  CreateItemFlowRightPanel, CreateItemFlowStepper,\n  CreateItemFlowContent, CreateItemFlowStepContent, CreateItemFlowContentTitle,\n  CreateItemFlowActions,\n} from 'impact-nova';\n\nexport function CreateAlertFlow() {\n  const [step, setStep] = useState(1);\n\n  return (\n    <CreateItemFlowRoot step={step} totalSteps={3} onStepChange={setStep}>\n      <CreateItemFlowCard>\n        <CreateItemFlowLeftPanel>\n          <div>\n            <CreateItemFlowTitle>Create Alert</CreateItemFlowTitle>\n            <CreateItemFlowDescription>Configure your alert step by step.</CreateItemFlowDescription>\n          </div>\n          <CreateItemFlowImage />\n        </CreateItemFlowLeftPanel>\n\n        <CreateItemFlowRightPanel>\n          <CreateItemFlowStepper />\n          <CreateItemFlowContent>\n            <CreateItemFlowStepContent forStep={1}>\n              <CreateItemFlowContentTitle>Alert Details</CreateItemFlowContentTitle>\n              {/* form fields */}\n            </CreateItemFlowStepContent>\n            <CreateItemFlowStepContent forStep={2}>\n              <CreateItemFlowContentTitle>Configuration</CreateItemFlowContentTitle>\n            </CreateItemFlowStepContent>\n            <CreateItemFlowStepContent forStep={3}>\n              <CreateItemFlowContentTitle>Review</CreateItemFlowContentTitle>\n            </CreateItemFlowStepContent>\n          </CreateItemFlowContent>\n          <CreateItemFlowActions\n            onCancel={() => {}}\n            onSubmit={() => {}}\n          />\n        </CreateItemFlowRightPanel>\n      </CreateItemFlowCard>\n    </CreateItemFlowRoot>\n  );\n}\n```\n\n### Key rules\n\n- **CreateItemFlowRoot** is the context provider — every other sub-component must be a descendant.\n- **CreateItemFlowActions** is smart: it auto-renders Cancel+Next (step 1), Back+Cancel+Next (middle), Back+Cancel+Submit (last). Pass `children` to fully override.\n- **CreateItemFlowStepContent** renders nothing when `forStep` doesn't match the current step — use one per step.\n- **CreateItemFlowImage** renders a default SVG illustration when neither `src` nor `children` are provided.\n- The left panel is hidden below the `lg` breakpoint.\n- Compose **Tabs**, **Select**, **Input**, etc. inside **CreateItemFlowContent** for rich step content.\n- For a single-step flow, set `totalSteps={1}` — the stepper is hidden and Submit appears directly.\n- To override action buttons entirely, pass children to `CreateItemFlowActions`:\n\n```tsx\n<CreateItemFlowActions>\n  <Button variant=\"tertiary\">Save as Draft</Button>\n  <div className=\"flex gap-3\">\n    <Button variant=\"secondary\">Cancel</Button>\n    <Button variant=\"default\">Publish</Button>\n  </div>\n</CreateItemFlowActions>\n```\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impact-nova",
-  "version": "1.7.21",
+  "version": "1.7.23",
   "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",
   "main": "./dist/index.js",