igniteui-cli 15.5.0 → 15.6.0

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 (76) hide show
  1. package/package.json +4 -4
  2. package/templates/blazor/igb/projects/ai-config/files/skills/AGENTS.md +6 -3
  3. package/templates/blazor/igb/projects/ai-config/files/skills/README.md +30 -45
  4. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/SKILL.md +48 -96
  5. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/charts.md +61 -238
  6. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/data-display.md +60 -193
  7. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/feedback.md +36 -92
  8. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +66 -224
  9. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout-manager.md +39 -88
  10. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md +75 -152
  11. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +40 -149
  12. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md +58 -243
  13. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +89 -280
  14. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +143 -431
  15. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/SKILL.md +91 -157
  16. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/data-operations.md +50 -228
  17. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +61 -222
  18. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/features.md +67 -360
  19. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/grid-migration.md +55 -236
  20. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md +53 -202
  21. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md +31 -232
  22. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/state.md +27 -119
  23. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/structure.md +88 -363
  24. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/types.md +87 -415
  25. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/SKILL.md +86 -0
  26. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +220 -0
  27. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/SKILL.md +83 -211
  28. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/common-patterns.md +93 -184
  29. package/templates/react/igr-ts/projects/_base/files/src/main.tsx +1 -0
  30. package/templates/react/igr-ts/projects/_base_with_home/files/src/app/home/style.module.css +3 -3
  31. package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
  32. package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
  33. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
  34. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
  35. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
  36. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
  37. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
  38. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
  39. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
  40. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
  41. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
  42. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
  43. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
  44. package/templates/react/igr-ts/projects/side-nav/files/src/app/app.css +9 -9
  45. package/templates/react/igr-ts/projects/side-nav/files/src/app/home/style.module.css +7 -7
  46. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/app.css +8 -8
  47. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.module.css +1 -69
  48. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.tsx +5 -5
  49. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginBar.module.css +5 -26
  50. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginDialog.module.css +0 -1
  51. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.module.css +1 -56
  52. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.tsx +2 -2
  53. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/Profile.module.css +11 -11
  54. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectFacebook.tsx +1 -1
  55. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectGoogle.tsx +1 -1
  56. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectMicrosoft.tsx +1 -1
  57. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/app.css +9 -9
  58. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/home/style.module.css +7 -7
  59. package/templates/react/igr-ts/projects/side-nav-mini-auth/files/src/app/app.css +7 -7
  60. package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
  61. package/templates/webcomponents/igc-ts/constants.js +5 -5
  62. package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
  63. package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
  64. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
  65. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
  66. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
  67. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
  68. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
  69. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
  70. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
  71. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
  72. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
  73. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
  74. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
  75. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
  76. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
@@ -0,0 +1,65 @@
1
+ # Choosing Components
2
+
3
+ Ask the MCP server for the authoritative list: `list_components({ framework: 'react', filter: 'date' })`. This file only records the picks that are easy to get wrong.
4
+
5
+ ## Disambiguation
6
+
7
+ | Requirement | Use | Not |
8
+ |---|---|---|
9
+ | Static list of rows | `IgrList` | a grid |
10
+ | Plain dropdown | `IgrSelect` | `IgrCombo` |
11
+ | Searchable or multi-select dropdown | `IgrCombo` | `IgrSelect` |
12
+ | Flat tabular data, display only | `IgrGridLite` | `IgrGrid` |
13
+ | Editing, selection, paging, grouping, summaries, export | `IgrGrid` | `IgrGridLite` |
14
+ | Parent/child rows | `IgrTreeGrid` | `IgrGrid` |
15
+ | Auto-dismissing message | `IgrToast` | `IgrSnackbar` |
16
+ | Message with an action | `IgrSnackbar` | `IgrToast` |
17
+ | One collapsible section | `IgrExpansionPanel` | `IgrAccordion` |
18
+ | Several collapsible sections | `IgrAccordion` | `IgrExpansionPanel` |
19
+ | Linear wizard with validation per step | `IgrStepper` | `IgrTabs` |
20
+ | View switching | `IgrTabs` | `IgrStepper` |
21
+
22
+ `IgrGridLite` has no editing, selection, paging, grouping, summaries, pinning, or export. If the requirement lists any of those, it is `IgrGrid`.
23
+
24
+ ## Pattern → components
25
+
26
+ - **Form / login** — `IgrInput`, `IgrCheckbox`, `IgrSelect` + `IgrSelectItem`, `IgrRadioGroup` + `IgrRadio`, `IgrSwitch`, `IgrSlider`, `IgrButton`
27
+ - **Dates** — `IgrDatePicker`, `IgrDateRangePicker`, `IgrDateTimeInput`, `IgrCalendar`
28
+ - **App shell** — `IgrNavbar`, `IgrNavDrawer` + `IgrNavDrawerItem`, `IgrTabs`, `IgrSplitter`, `IgrTileManager`
29
+ - **Cards** — `IgrCard`, `IgrCardHeader`, `IgrCardMedia`, `IgrCardContent`, `IgrCardActions`
30
+ - **Status** — `IgrBadge`, `IgrChip`, `IgrAvatar`, `IgrIcon`, `IgrLinearProgress`, `IgrCircularProgress`
31
+ - **Overlays** — `IgrDialog`, `IgrToast`, `IgrSnackbar`, `IgrTooltip`, `IgrDropdown`
32
+ - **Charts** (`igniteui-react-charts`) — `IgrCategoryChart` (line/area/column), `IgrPieChart`, `IgrFinancialChart`, `IgrSparkline`, `IgrDataChart` for multi-series/multi-axis control
33
+ - **Gauges** (`igniteui-react-gauges`) — `IgrLinearGauge`, `IgrRadialGauge`, `IgrBulletGraph`
34
+ - **Maps** (`igniteui-react-maps`) — `IgrGeographicMap` plus `IgrGeographicSymbolSeries` / `…ProportionalSymbolSeries` / `…ShapeSeries`
35
+ - **AI chat** — `IgrChat` (markdown rendering via `createChatMarkdownRenderer` from `igniteui-react/extras`)
36
+
37
+ ## `IgrTabs`: content vs navigation
38
+
39
+ These are different, and mixing them is the most common `IgrTabs` bug.
40
+
41
+ **Content panels** — content lives inside each `IgrTab`:
42
+
43
+ ```tsx
44
+ <IgrTabs>
45
+ <IgrTab label="Profile" selected><ProfilePanel /></IgrTab>
46
+ <IgrTab label="Security"><SecurityPanel /></IgrTab>
47
+ </IgrTabs>
48
+ ```
49
+
50
+ Use a `slot="label"` child instead of the `label` prop when the header needs an icon or custom markup.
51
+
52
+ **Router navigation** — tabs are label-only; the router renders content *outside* `IgrTabs`. Inline content here renders in addition to the routed view and pushes it off screen.
53
+
54
+ ```tsx
55
+ import type { IgrTabComponentEventArgs } from 'igniteui-react';
56
+
57
+ <IgrTabs onChange={(e: IgrTabComponentEventArgs) => navigate(pathFor(e.detail.label))}>
58
+ {tabs.map(t => (
59
+ <IgrTab key={t.path} label={t.label} selected={location.pathname === t.path} />
60
+ ))}
61
+ </IgrTabs>
62
+ <Outlet />
63
+ ```
64
+
65
+ `IgrTabs`' `onChange` detail is the selected `IgrTab` element itself, so `e.detail.label`, `e.detail.selected`, and `e.detail.disabled` are available.
@@ -0,0 +1,90 @@
1
+ # Charts, Gauges, Maps, and Grids
2
+
3
+ ## Two rules cover most failures
4
+
5
+ **1. Charts, gauges, and maps require module registration.** These live in the older `igniteui-react-charts` / `-gauges` / `-maps` packages, which are not auto-registering wrappers. Call `.register()` once at module scope, outside the component. A missing registration fails silently — the chart, an axis, or a series simply does not appear.
6
+
7
+ **2. Charts, gauges, maps, and grids size themselves from their parent.** A parent with no resolved height renders them at zero. Give the container real dimensions and let the component fill it.
8
+
9
+ ```css
10
+ .viz {
11
+ min-height: 320px;
12
+ flex-grow: 1;
13
+ flex-basis: 0;
14
+ }
15
+ .viz > * { width: 100%; height: 100%; }
16
+ ```
17
+
18
+ Inside a flexible CSS Grid track, also set `min-height: 0` on the cell, or the track refuses to shrink and the chart overflows.
19
+
20
+ ## Registration
21
+
22
+ ```tsx
23
+ import { IgrCategoryChart, IgrCategoryChartModule } from 'igniteui-react-charts';
24
+
25
+ IgrCategoryChartModule.register(); // module scope, once
26
+
27
+ export default function Trend({ data }: { data: Point[] }) {
28
+ return (
29
+ <div className="viz">
30
+ <IgrCategoryChart dataSource={data} chartType="column" yAxisTitle="Revenue" />
31
+ </div>
32
+ );
33
+ }
34
+ ```
35
+
36
+ One module per component: `IgrCategoryChartModule`, `IgrPieChartModule`, `IgrFinancialChartModule`, `IgrSparklineModule`, `IgrLinearGaugeModule`, `IgrRadialGaugeModule`, `IgrBulletGraphModule`, `IgrGeographicMapModule`.
37
+
38
+ `IgrDataChart` is the exception — it needs one module per capability, and each missing one drops a feature silently:
39
+
40
+ | Module | Provides |
41
+ |---|---|
42
+ | `IgrDataChartCoreModule` | the chart itself (always) |
43
+ | `IgrDataChartCategoryCoreModule` | category axis base (always, with category series) |
44
+ | `IgrDataChartCategoryModule` | column, line, area, spline series |
45
+ | `IgrDataChartVerticalCategoryModule` | bar series (horizontal) |
46
+ | `IgrDataChartInteractivityModule` | hover, selection, highlight layers |
47
+ | `IgrDataChartAnnotationModule` | tooltip and callout layers |
48
+ | `IgrLegendModule` | `IgrLegend` |
49
+
50
+ Bar charts are horizontal: categories on `IgrCategoryYAxis`, values on `IgrNumericXAxis` — the reverse of a column chart. The category axis needs its own `dataSource` in addition to the series'. Pass a legend by ref (`<IgrLegend ref={legend} />` rendered before the chart, then `legend={legend.current ?? undefined}`).
51
+
52
+ Note: `igniteui-react-charts` components are not the `igc-*` wrappers, so their visuals are set through props (`brushes`, `outlines`, `markerTypes`, `xAxisLabelTextColor`, …), not through `--ig-*` design tokens.
53
+
54
+ ## Grid Lite
55
+
56
+ MIT, needs both `igniteui-react` and `igniteui-grid-lite` installed, imports from `igniteui-react/grid-lite`, and needs no registration.
57
+
58
+ ```tsx
59
+ import { IgrGridLite, IgrGridLiteColumn, type IgrCellContext } from 'igniteui-react/grid-lite';
60
+
61
+ const money = (ctx: IgrCellContext<Order>) => <span>${(ctx.value as number).toFixed(2)}</span>;
62
+
63
+ <div className="viz">
64
+ <IgrGridLite data={orders} sortingExpressions={sort} onSorted={onSorted}>
65
+ <IgrGridLiteColumn field="id" dataType="number" />
66
+ <IgrGridLiteColumn field="customer" dataType="string" sortable />
67
+ <IgrGridLiteColumn field="total" dataType="number" cellTemplate={money} />
68
+ </IgrGridLite>
69
+ </div>
70
+ ```
71
+
72
+ - `dataType` is `'string' | 'number' | 'boolean'` and drives sorting and filtering; set it explicitly.
73
+ - `cellTemplate` / `headerTemplate` receive `IgrCellContext<T>` / `IgrHeaderContext<T>` — `ctx.value`, `ctx.row.data`, `ctx.row.index`, `ctx.column.field`. Define templates outside the component or memoize them.
74
+ - Sorting expressions are `{ key, direction: 'ascending' | 'descending' }`.
75
+ - `autoGenerate` defaults to `false`. Set it and pass no column children to derive columns from the data; explicit columns always win.
76
+
77
+ ## Column widths
78
+
79
+ **Do not set `width` on `IgrGridLiteColumn` or `IgrColumn` unless the user asked for specific widths.** Both are fluid by default (`IgrGridLiteColumn` falls back to `minmax(136px, 1fr)`). Fixed pixel widths pin the layout and leave dead space to the right of the last column. If some columns genuinely need a fixed width, leave at least one without one so it absorbs the remainder.
80
+
81
+ ## Premium grid essentials
82
+
83
+ `igniteui-react-grids`, no registration, needs its own theme CSS (`igniteui-react-grids/grids/themes/<variant>/<design-system>.css`) on top of the base theme.
84
+
85
+ - `height` is required for row virtualization; `primaryKey` is required for editing, selection, and row-targeted APIs.
86
+ - Cell templates use `bodyTemplate` with `IgrCellTemplateContext` (`ctx.cell.value`, `ctx.cell.row.data`) — not Grid Lite's `cellTemplate`/`ctx.value`.
87
+ - Header templates use `headerTemplate` with `IgrColumnTemplateContext` (`ctx.column.header`).
88
+ - Filtering needs `allowFiltering` on the grid *and* `filterable` on each column.
89
+
90
+ For anything beyond this, see [grid-lite-to-igr-grid-migration](../../grid-lite-to-igr-grid-migration/SKILL.md) or `get_doc({ framework: 'react', name: 'grid-editing' })`.
@@ -0,0 +1,43 @@
1
+ # Ignite UI CLI MCP Server
2
+
3
+ Provides authoritative component docs and API reference. Prefer it over recall for prop, slot, event, and enum names.
4
+
5
+ ## Tools
6
+
7
+ All tools take a named-argument object. **The platform argument is named differently across tools** — doc tools use `framework`, API tools use `platform`. Both accept `angular | react | webcomponents | blazor`; always pass `react`.
8
+
9
+ | Tool | Arguments |
10
+ |---|---|
11
+ | `list_components` | `framework`, `filter?` (substring over name/keywords/summary) |
12
+ | `get_doc` | `framework`, `name` (kebab-case doc name from `list_components`/`search_docs`, no `.md`) |
13
+ | `search_docs` | `query` (full-text; `grid*` prefix matching supported), `framework` |
14
+ | `search_api` | `query`, `platform?` (omit to search all platforms) |
15
+ | `get_api_reference` | `platform`, `component`, `section?` (`properties \| methods \| events \| all`), `member?` |
16
+ | `get_project_setup_guide` | `framework?` |
17
+
18
+ ```
19
+ list_components({ framework: 'react', filter: 'date' })
20
+ get_doc({ framework: 'react', name: 'grid-editing' })
21
+ get_api_reference({ platform: 'react', component: 'IgrCombo', section: 'events' })
22
+ search_api({ query: 'row selection', platform: 'react' })
23
+ ```
24
+
25
+ Pass the doc `name` field from `list_components` to `get_doc`, not the human-readable title. Use `section` on `get_api_reference` to keep responses small. Narrow filters beat broad ones — `filter: 'list view'` rather than `'list'`.
26
+
27
+ ## Setup
28
+
29
+ If `list_components` is unavailable, add the server config, then tell the user to reload the editor so the tools activate. Do not block on it — this skill works without MCP; fall back to the installed `.d.ts` files under `node_modules/igniteui-webcomponents/components/` and `node_modules/igniteui-webcomponents-grids/grids/lib/`, which carry `@slot`, `@csspart`, `@fires`, and `@cssproperty` annotations.
30
+
31
+ VS Code — `.vscode/mcp.json`:
32
+
33
+ ```json
34
+ {
35
+ "servers": {
36
+ "igniteui-cli": { "command": "npx", "args": ["-y", "igniteui-cli", "mcp"] }
37
+ }
38
+ }
39
+ ```
40
+
41
+ Cursor (`.cursor/mcp.json`) and Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) use the same entry under an `mcpServers` key instead of `servers`. JetBrains: **Settings → Tools → AI Assistant → MCP Servers**, command `npx`, arguments `-y igniteui-cli mcp`.
42
+
43
+ `npx -y` resolves whether or not `igniteui-cli` is already installed locally.
@@ -1,147 +1,19 @@
1
1
  # Troubleshooting
2
2
 
3
- ## Issue: Components render without styles
4
-
5
- **Cause:** Missing theme CSS import. Without the theme CSS, components will render with broken layouts, missing icons (showing placeholders), and no visual styling.
6
-
7
- **Solution:** Add the theme CSS import **before** any component usage. In Vite/CRA apps, add it to your entry point. In Next.js, add it to each client component file or the root layout:
8
-
9
- ```tsx
10
- // Always required for core components
11
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
12
-
13
- // Also required when using grids (IgrGrid, IgrTreeGrid, etc.)
14
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
15
- ```
16
-
17
- **Next.js example:**
18
-
19
- ```tsx
20
- 'use client';
21
-
22
- import 'igniteui-webcomponents/themes/light/bootstrap.css';
23
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
24
-
25
- import { IgrNavbar, IgrButton } from 'igniteui-react';
26
- import { IgrGrid, IgrColumn, IgrPaginator } from 'igniteui-react-grids';
27
- ```
28
-
29
- ## Issue: Grid renders but icons show as placeholders and styles are missing
30
-
31
- **Cause:** The grid theme CSS (`igniteui-react-grids/grids/themes/...`) is not imported. The base theme CSS alone is not enough for grids.
32
-
33
- **Solution:** Import **both** theme CSS files:
34
-
35
- ```tsx
36
- import 'igniteui-webcomponents/themes/light/bootstrap.css'; // Base theme
37
- import 'igniteui-react-grids/grids/themes/light/bootstrap.css'; // Grid theme
38
- ```
39
-
40
- ## Issue: Grid Lite does not render or compilation error
41
-
42
- **Cause:** `IgrGridLite` is a React wrapper component from `igniteui-react/grid-lite`. It requires **both** `igniteui-react` and `igniteui-grid-lite` packages to be installed. It uses the `Igr` prefix (like all other Ignite UI React wrappers) and does **not** require any `.register()` call.
43
-
44
- **Solution:**
45
-
46
- 1. Install both required packages: `npm install igniteui-react igniteui-grid-lite`
47
- 2. Import `IgrGridLite` from `igniteui-react/grid-lite`
48
- 3. Wrap in a sized container (see [CHARTS-GRIDS.md](./CHARTS-GRIDS.md) for a full example)
49
-
50
- ## Issue: `IgrGridLite` is confused with `IgrGrid` from `igniteui-react-grids`
51
-
52
- **Solution:** These are different components:
53
- - `igniteui-react/grid-lite` → lightweight MIT grid (`IgrGridLite`, React wrapper — no `.register()` needed, requires both `igniteui-react` and `igniteui-grid-lite` packages)
54
- - `igniteui-react-grids` → full-featured commercial grids (`IgrGrid`, `IgrTreeGrid`, etc. — React wrappers)
55
-
56
- Import from the correct package for your needs:
57
-
58
- ```tsx
59
- // Lightweight grid (MIT, React wrapper, no registration needed)
60
- import { IgrGridLite } from 'igniteui-react/grid-lite';
61
-
62
- // Full-featured grid (commercial, React wrapper)
63
- import { IgrGrid } from 'igniteui-react-grids';
64
- ```
65
-
66
- ## Issue: Events fire but have unexpected shape
67
-
68
- **Cause:** Ignite UI events are `CustomEvent` objects from the underlying web component, not React `SyntheticEvent` objects.
69
-
70
- **Solution:** Type the handler parameter as `CustomEvent` and access `.detail` for event-specific data or `.target` for the element:
71
-
72
- ```tsx
73
- const handleChange = (e: CustomEvent) => {
74
- const target = e.target as HTMLElement;
75
- const detail = e.detail;
76
- // Use target or detail as appropriate
77
- };
78
- ```
79
-
80
- ## Issue: Component methods not accessible
81
-
82
- **Solution:** Use `useRef` with the component type:
83
-
84
- ```tsx
85
- const dialogRef = useRef<IgrDialog>(null);
86
-
87
- // Call imperative method
88
- dialogRef.current?.show();
89
- ```
90
-
91
- ## Issue: Chart / gauge / map does not render or is invisible
92
-
93
- **Cause:** Two common causes:
94
- 1. The corresponding module was not registered (e.g., `IgrCategoryChartModule.register()` was not called)
95
- 2. The parent container has no explicit dimensions — these components inherit size from their container and will be invisible if the container has zero height/width
96
-
97
- **Solution:**
98
-
99
- 1. **Register the module** at the top level of the file (outside the component):
100
-
101
- ```tsx
102
- import { IgrCategoryChart, IgrCategoryChartModule } from 'igniteui-react-charts';
103
- IgrCategoryChartModule.register();
104
- ```
105
-
106
- 2. **Wrap the chart in a sized container** with explicit dimensions:
107
-
108
- ```css
109
- .chart-container {
110
- min-width: 400px;
111
- min-height: 300px;
112
- flex-grow: 1;
113
- flex-basis: 0;
114
- }
115
- .chart-container > * { height: 100%; width: 100%; }
116
- ```
117
-
118
- ```tsx
119
- <div className={styles['chart-container']}>
120
- <IgrCategoryChart dataSource={data} />
121
- </div>
122
- ```
123
-
124
- ## Issue: IgrTabs used for navigation fills the entire view with content
125
-
126
- **Cause:** Inline content was included in `IgrTab` elements when using tabs for navigation with React Router. The tab content areas take up space and push the routed content out of view.
127
-
128
- **Solution:** When using `IgrTabs` for navigation, use **only the label** (via `label` prop or `slot="label"`) — do NOT include inline content. Let the router's `<Outlet />` render the content:
129
-
130
- ```tsx
131
- // ✅ Correct — navigation tabs with label-only (no inline content)
132
- <IgrTabs onChange={handleTabChange}>
133
- <IgrTab label="Dashboard" selected={location.pathname === '/dashboard'} />
134
- <IgrTab label="Orders" selected={location.pathname === '/orders'} />
135
- </IgrTabs>
136
- <Outlet />
137
-
138
- // ❌ Wrong — inline content creates unwanted space when used for navigation
139
- <IgrTabs>
140
- <IgrTab label="Dashboard">
141
- <p>This content will show and take up space!</p> {/* Don't do this for navigation */}
142
- </IgrTab>
143
- <IgrTab label="Orders">
144
- <p>This content will show and take up space!</p> {/* Don't do this for navigation */}
145
- </IgrTab>
146
- </IgrTabs>
147
- ```
3
+ | Symptom | Cause | Fix |
4
+ |---|---|---|
5
+ | Components render unstyled, icons show as placeholder boxes | No theme CSS | Import `igniteui-webcomponents/themes/<variant>/<design-system>.css` before use; in Next.js, in `app/layout.tsx` or each `'use client'` file |
6
+ | Grid unstyled but other components fine | Grid theme CSS missing — the base theme does not cover grids | Also import `igniteui-react-grids/grids/themes/<variant>/<design-system>.css` |
7
+ | Theme overrides do nothing | Override CSS imported before the theme | Import overrides *after* the theme |
8
+ | `--ig-primary-h` / `-s` / `-l` overrides do nothing | Those tokens do not exist | Override the shade: `--ig-primary-500: #0d6efd` — other shades derive from it |
9
+ | CSS rules never match | Selector uses the React name | Target the element: `igc-button`, not `IgrButton`; `::part()` for internals |
10
+ | Chart / gauge / map invisible | Module not registered, or container has no height | `.register()` at module scope; size the container |
11
+ | A chart series or axis silently missing | `IgrDataChart` capability module not registered | Register the module for that series/layer type |
12
+ | Grid Lite fails to resolve | `igniteui-grid-lite` not installed (optional peer) | `npm install igniteui-grid-lite`; import from `igniteui-react/grid-lite` |
13
+ | Grid renders no rows | No `height` on the grid | Set `height` — row virtualization needs it |
14
+ | Dead space right of the last column | Explicit `width` on every column | Remove widths, or leave one column without one |
15
+ | Event handler gets `undefined` | Reading React `SyntheticEvent` fields | It is a `CustomEvent`; read `e.detail` (or `e.target`) |
16
+ | Navigation tabs push routed content off screen | Inline content inside router-driven `IgrTab` | Label-only tabs; render the route outlet outside `IgrTabs` |
17
+ | Filter UI never appears | Only `filterable` set | `allowFiltering` on the grid *and* `filterable` on the column |
18
+ | `*Module.register()` reported as deprecated | `igniteui-react` / `-grids` / `grid-lite` / `-dockmanager` auto-register | Delete the call — it is only needed for charts, gauges, and maps |
19
+ | Child renders in the wrong place | Wrong or misspelled `slot` name | Confirm the name via `get_doc` or the `@slot` annotations in the component `.d.ts` |
@@ -0,0 +1,85 @@
1
+ # Writing `Igr*` JSX
2
+
3
+ ## Props and slots
4
+
5
+ Props behave like any React component — pass expressions, not strings, for numbers and booleans (`<IgrSlider value={50} />`, not `value="50"`).
6
+
7
+ Children go to the default slot; named slots use the `slot` attribute on the child:
8
+
9
+ ```tsx
10
+ <IgrCard>
11
+ <IgrCardHeader>
12
+ <IgrIcon slot="thumbnail" name="home" collection="material" />
13
+ <h3 slot="title">Title</h3>
14
+ <p slot="subtitle">Subtitle</p>
15
+ </IgrCardHeader>
16
+ <IgrCardContent>Body</IgrCardContent>
17
+ <IgrCardActions>
18
+ <IgrButton slot="start">Cancel</IgrButton>
19
+ <IgrButton slot="end">Confirm</IgrButton>
20
+ </IgrCardActions>
21
+ </IgrCard>
22
+ ```
23
+
24
+ Slot names are per-component (`start`, `end`, `prefix`, `suffix`, `helper-text`, `title`, `subtitle`, `thumbnail`, `label`, `icon`, `content`, …). Confirm them with `get_doc` or the `@slot` annotations in the component's `.d.ts` — guessing a slot name silently renders the child into the default slot.
25
+
26
+ ## Events
27
+
28
+ The web component's `igcFoo` becomes the `onFoo` prop. Handlers receive the `CustomEvent`, so payloads live on `e.detail`.
29
+
30
+ Each event has a generated type pair: `Igr<X>EventArgs` is `CustomEvent<Igr<X>EventArgsDetail>`. Use the `…EventArgs` alias:
31
+
32
+ ```tsx
33
+ import {
34
+ IgrCheckbox, type IgrCheckboxChangeEventArgs,
35
+ IgrInput, type IgrComponentValueChangedEventArgs,
36
+ } from 'igniteui-react';
37
+
38
+ <IgrCheckbox onChange={(e: IgrCheckboxChangeEventArgs) => setChecked(e.detail.checked)}>
39
+ Subscribe
40
+ </IgrCheckbox>
41
+
42
+ <IgrInput label="Search" onInput={(e: IgrComponentValueChangedEventArgs) => setQuery(e.detail)} />
43
+ ```
44
+
45
+ Frequently used events — `onInput` (per keystroke) and `onChange` (committed) on `IgrInput`; `onChange` on `IgrCheckbox`, `IgrSwitch`, `IgrSelect`, `IgrCombo`, `IgrRadioGroup`, `IgrTabs`, `IgrCalendar`, `IgrDatePicker`; `onInput`/`onChange` on `IgrSlider`; `onClosing`/`onClosed` on `IgrDialog`. Detail shapes differ per component — `get_api_reference({ platform: 'react', component: 'IgrCombo', section: 'events' })`.
46
+
47
+ ## Refs
48
+
49
+ The exported name is both the component and its element type, so `useRef<IgrDialog>` gives you the custom element and its imperative API:
50
+
51
+ ```tsx
52
+ const dialog = useRef<IgrDialog>(null);
53
+ await dialog.current?.show(); // show/hide/toggle return Promise<boolean>
54
+
55
+ <IgrDialog ref={dialog} title="Confirm">
56
+ <p>Are you sure?</p>
57
+ <IgrButton slot="footer" onClick={() => dialog.current?.hide()}>Close</IgrButton>
58
+ </IgrDialog>
59
+ ```
60
+
61
+ ## Forms
62
+
63
+ Inputs, select, checkbox, switch, and radio are form-associated custom elements, so uncontrolled forms work natively — give each a `name` and read `FormData`. Native validation (`required`, `pattern`, …) participates too.
64
+
65
+ ```tsx
66
+ const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
67
+ e.preventDefault();
68
+ const data = new FormData(e.currentTarget);
69
+ data.get('name');
70
+ };
71
+
72
+ <form onSubmit={onSubmit}>
73
+ <IgrInput name="name" label="Name" required />
74
+ <IgrSelect name="role" label="Role" required>
75
+ <IgrSelectItem value="admin">Admin</IgrSelectItem>
76
+ </IgrSelect>
77
+ <IgrButton type="submit">Submit</IgrButton>
78
+ </form>
79
+ ```
80
+
81
+ Controlled: pass `value`/`checked` and update from `e.detail`. With React Hook Form, wrap in `Controller` and map `field.onChange(e.detail)` — components are not native `<input>`s, so `register()` alone will not track them.
82
+
83
+ ## TypeScript
84
+
85
+ `ComponentProps<typeof IgrInput>` extracts the prop type when you wrap a component. For editor completion, keep `"jsx": "react-jsx"` and `"moduleResolution": "bundler"` in `tsconfig.json`.