igniteui-cli 15.5.1 → 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 (58) 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 +8 -4
  26. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +42 -6
  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/ai-config/files/skills/README.md +30 -83
  30. package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
  31. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
  32. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
  33. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
  34. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
  35. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
  36. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
  37. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
  38. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
  39. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
  40. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
  41. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
  42. package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
  43. package/templates/webcomponents/igc-ts/constants.js +5 -5
  44. package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
  45. package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
  46. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
  47. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
  48. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
  49. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
  50. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
  51. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
  52. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
  53. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
  54. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
  55. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
  56. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
  57. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
  58. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
@@ -1,180 +1,132 @@
1
- # Ignite UI Blazor Gotchas & Pitfalls
1
+ # Gotchas — Mistakes That Compile But Look Wrong
2
2
 
3
- ## Table of Contents
4
- - [CSS Isolation & Scoping](#css-isolation--scoping)
5
- - [Chart Properties](#chart-properties)
6
- - [Component Properties](#component-properties)
7
- - [Theming Pitfalls](#theming-pitfalls)
8
- - [Map Component](#map-component)
9
- - [Dark Theme Specifics](#dark-theme-specifics)
10
- - [Blazor-specific Gotchas](#blazor-specific-gotchas)
3
+ Check every entry against your component list before writing code. Chart, CSS, and Razor entries apply broadly, not only to the components they name.
11
4
 
12
- ---
5
+ ## Razor & Blazor
13
6
 
14
- ## CSS Isolation & Scoping
7
+ ### RZ9986 — dynamic `class` on an Ignite UI component
15
8
 
16
- Ignite UI for Blazor components render as web components (`igc-chip`, `igc-grid`, etc.). Use three CSS mechanisms depending on what you need and where the CSS lives:
9
+ Mixing literal text with `@(...)` in one attribute on a component fails the build with *"Component attributes do not support complex content"*. Make the whole value a single C# expression.
17
10
 
18
- | Mechanism | Purpose | Priority |
19
- |---|---|---|
20
- | Design tokens `--ig-*` | Override colors, borders, shadows via CSS vars | **Primary** - use whenever a token exists |
21
- | `::part()` | Target a named shadow DOM part directly | **Secondary** - only when no token covers it; confirm part names via `get_doc` |
22
- | `::deep` | Pierce Blazor CSS isolation in `.razor.css` files | **File helper** - add it in `.razor.css`; never needed in global CSS |
11
+ ```razor
12
+ @* ❌ RZ9986 *@
13
+ <IgbChip class="chip @(item == _selected ? "chip-active" : "")" />
23
14
 
24
- `::deep` and `::part()` solve different problems and are often combined: `::deep igc-chip::part(base) { ... }`.
15
+ @* ✅ *@
16
+ <IgbChip class="@ChipClass(item)" />
25
17
 
26
- **`::deep` applies only to `igc-*` selectors - never to plain HTML or CSS class selectors.**
18
+ @code { string ChipClass(Item i) => i == _selected ? "chip chip-active" : "chip"; }
19
+ ```
27
20
 
28
- `::deep` is not a general-purpose CSS scope piercer. It only works when Blazor's scope attribute is present on a parent element above the targeted element in the DOM. This means:
21
+ ### CS1012 — single quotes in an inline lambda
29
22
 
30
- - **DO** use `::deep` for `igc-*` element selectors and `igc-*::part()` combinations in `.razor.css` files.
31
- - **DO NOT** use `::deep` for plain HTML class selectors. These are already scoped by Blazor's CSS isolation and work without `::deep`.
32
- - **DO NOT** use `::deep` to target the root element of a component - Blazor places the scope attribute on the root element itself, so there is no scoped parent above it to make `::deep` work. Style the root element with a plain class selector.
23
+ `@onclick="() => Navigate('/dashboard')"` fails: the single quotes are parsed as a C# `char` literal. Use a named handler.
33
24
 
34
- **Global CSS (`app.css`)** - write selectors directly:
35
- ```css
36
- igc-chip { --ig-chip-background: var(--ig-primary-500); }
37
- igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
25
+ ```razor
26
+ @* ❌ *@ <IgbNavDrawerItem @onclick="() => Navigate('/dashboard')">
27
+ @* ✅ *@ <IgbNavDrawerItem @onclick="NavigateToDashboard">
28
+
29
+ @code { void NavigateToDashboard() => NavigationManager.NavigateTo("/dashboard"); }
38
30
  ```
39
31
 
40
- **`.razor.css` isolation file** - prefix `igc-*` selectors with `::deep`; write plain HTML class selectors without it:
41
- ```css
42
- ::deep igc-chip { --ig-chip-background: var(--ig-primary-500); }
43
- ::deep igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
32
+ ### BL0005 — setting parameters through `@ref`
44
33
 
45
- .class-selector { display: grid; grid-template-columns: 260px 1fr; }
46
- ```
34
+ Assigning component parameters from `OnAfterRenderAsync` (`chart.Brushes = "…"`) raises *"Component parameter should not be set outside of its component"*. Pass them as inline markup attributes instead.
47
35
 
48
- `create_component_theme(platform: "blazor", output: "css")` generates global CSS selectors - use as-is in `app.css`, or add `::deep` when placing in a `.razor.css` file. Never add `::deep` to `:root {}` blocks or plain HTML class rules.
36
+ ### Async vs sync methods
49
37
 
50
- Blazor projects do **not** use Sass/SCSS.
38
+ Every component method has an `XAsync()` form and a sync twin `X()`. **Use `Async`.** The sync twin requires `IJSInProcessRuntime` and throws `InvalidOperationException` on Blazor Server; it only works in WebAssembly and MAUI WebView.
51
39
 
52
- ---
40
+ ### Other basics
53
41
 
54
- ## Chart Properties
42
+ - Parameters are PascalCase (`ChartType`, `DataSource`) — never Angular's `[chartType]`.
43
+ - Templates are Blazor render fragments with a cast `context`, not `<ng-template>`. On a grid column the cell template is `BodyTemplate`:
44
+ ```razor
45
+ <IgbColumn Field="Name" Header="Name">
46
+ <BodyTemplate>
47
+ @{ var cell = (IgbCellTemplateContext)context; }
48
+ <strong>@cell.Cell.Value</strong>
49
+ </BodyTemplate>
50
+ </IgbColumn>
51
+ ```
52
+ - `@bind-Value` / `@bind-Checked` — verify the bindable parameter exists rather than inventing one.
53
+ - Mock data is C# `record` or `class`, not a TypeScript interface.
54
+ - `AddIgniteUIBlazor()` must be called in `Program.cs`. Listing `typeof(Igb…Module)` values pre-loads those modules; in `IgniteUI.Blazor.Lite` components also self-register on first render.
55
55
 
56
- ### Markers shown by default
57
- Category charts show markers at every data point by default. If the screenshot does not show markers, set `MarkerTypes` using the documented pattern for the installed version. When setting it from code, add the enum value after the chart reference is ready:
58
- ```razor
59
- <IgbCategoryChart @ref="chart" ... />
60
-
61
- @code {
62
- private IgbCategoryChart chart = default!;
63
-
64
- protected override void OnAfterRender(bool firstRender)
65
- {
66
- if (firstRender)
67
- {
68
- chart.MarkerTypes.Add(MarkerType.None);
69
- }
70
- }
71
- }
72
- ```
56
+ ## CSS scoping
73
57
 
74
- ### Charts do NOT inherit CSS theme colors
75
- Charts, maps, gauges, and sparklines ignore the global CSS custom property theme. Set their visual properties explicitly via component parameters:
76
- ```razor
77
- <IgbCategoryChart
78
- Brushes="#4FC3F7 #81C784 #FFB74D"
79
- Outlines="#4FC3F7 #81C784 #FFB74D"
80
- MarkerBrushes="#4FC3F7 #81C784 #FFB74D"
81
- MarkerOutlines="#4FC3F7 #81C784 #FFB74D"
82
- XAxisLabelTextColor="#666666"
83
- YAxisLabelTextColor="#666666" />
84
- ```
58
+ Full rules are in the theming skill's [`common-patterns.md`](../../igniteui-blazor-theming/references/common-patterns.md). The short version:
85
59
 
86
- After a palette exists, prefer referencing palette tokens via `var(--ig-primary-500)` where the component supports CSS custom properties, or resolve the actual color value from the palette for DV component parameters.
60
+ | Mechanism | When |
61
+ |---|---|
62
+ | `--ig-*` design tokens | **primary** — whenever a token exists for the property |
63
+ | `::part(name)` | only when no token covers it, and only after confirming the part name |
64
+ | `::deep` | only in `.razor.css`, only on `igc-*` selectors |
87
65
 
88
- ### `Brushes`, `Outlines`, `MarkerBrushes`, `MarkerOutlines` are brush-list strings
89
- These are **string** parameters, not arrays. Pass colors as a single string separated by spaces.
90
- ```razor
91
- Brushes="#FF6B6B #4ECDC4 #45B7D1"
66
+ ```css
67
+ /* app.css — global, no ::deep */
68
+ igc-chip { --ig-chip-background: var(--ig-primary-500); }
69
+ igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
70
+
71
+ /* MyView.razor.css — ::deep on igc-*, never on your own class selectors */
72
+ ::deep igc-chip { --ig-chip-background: var(--ig-primary-500); }
73
+ .dashboard-shell { display: grid; grid-template-columns: 260px 1fr; }
92
74
  ```
93
75
 
94
- ### `AreaFillOpacity` exists on `IgbCategoryChart`
95
- It does **NOT** exist on `IgbSparkline`. For sparkline fill, use the `Brush` parameter.
76
+ `::deep` does **not** work on the component's own root element — Blazor puts the scope attribute there, so there is no scoped parent above it. Never add `::deep` to a `:root {}` block. `create_component_theme` emits global CSS; use it verbatim in `app.css`. Blazor projects have no Sass step.
96
77
 
97
- ### `IgbSparkline` has no SplineArea type - use `IgbCategoryChart` for smooth area sparklines
98
- `IgbSparkline` supports only `Line`, `Area`, `Column`, and `WinLoss` display types. `Area` renders as angular polygon fills, not smooth curves. If the design shows smooth mountain-shaped area sparklines, use a small `IgbCategoryChart` with `ChartType="CategoryChartType.SplineArea"`:
78
+ ## Charts
99
79
 
100
- ```razor
101
- <!-- ❌ Angular fill - no smooth curves available on IgbSparkline -->
102
- <IgbSparkline DisplayType="SparklineDisplayType.Area" Brush="#5B57E8" ... />
103
-
104
- <!-- ✅ Smooth spline area sparkline -->
105
- <IgbCategoryChart @ref="splineChart"
106
- ChartType="@CategoryChartType.SplineArea"
107
- Brushes="#5B57E8"
108
- Outlines="#5B57E8"
109
- AreaFillOpacity="0.35"
110
- XAxisLabelTextColor="transparent"
111
- YAxisLabelTextColor="transparent"
112
- Height="70px"
113
- Width="100%"
114
- DataSource="@SparkData" />
115
- ```
80
+ ### They ignore the CSS theme entirely
116
81
 
82
+ Charts, maps, gauges, and sparklines do not read `--ig-*` custom properties. Set colors through parameters, using resolved values rather than `var()` references:
117
83
 
118
- ### `IncludedProperties` and `ExcludedProperties` are string arrays
119
- Pass them as bound parameters:
120
84
  ```razor
121
- <IgbCategoryChart IncludedProperties='@(new string[] { "Month", "Revenue" })' ... />
85
+ <IgbCategoryChart Brushes="#4FC3F7 #81C784" Outlines="#4FC3F7 #81C784"
86
+ MarkerBrushes="#4FC3F7 #81C784"
87
+ XAxisLabelTextColor="#666666" YAxisMajorStroke="#EEEEEE" />
122
88
  ```
123
89
 
124
- ### `InnerExtent` is a chart-level property - never a series-level property
90
+ `Brushes`, `Outlines`, `MarkerBrushes`, `MarkerOutlines` are **space-separated strings**, not arrays.
125
91
 
126
- `InnerExtent` controls the hole size at the center of a donut/pie chart. It is a property of the **chart** component (`IgbDoughnutChart`, `IgbPieChart`, `IgbDataPieChart`), not of any series child. Placing it on `IgbRingSeries` causes a runtime crash:
92
+ ### Curve type is the most visible fidelity mistake
127
93
 
128
- ```
129
- System.InvalidOperationException: IgbRingSeries does not have a property matching 'InnerExtent'
130
- ```
94
+ Match `ChartType` to the shape in the image: smooth flowing → `Spline` / `SplineArea`; angular → `Line` / `Area`; stepped → `StepLine` / `StepArea`. Do not default to `Line` when the image shows curves.
131
95
 
132
- Correct usage:
133
- ```razor
134
- <!-- ✅ InnerExtent on the chart -->
135
- <IgbDoughnutChart InnerExtent="0.45" Width="220px" Height="220px">
136
- <IgbRingSeries ValueMemberPath="Value" LabelMemberPath="Label" ... />
137
- </IgbDoughnutChart>
96
+ ### Markers appear at every point by default
138
97
 
139
- <!-- ❌ Runtime crash -->
140
- <IgbRingSeries InnerExtent="0.45" ... />
98
+ If the image has no dots on the line, add `MarkerType.None` to `MarkerTypes` once the chart reference is ready.
99
+
100
+ ### `IncludedProperties` / `ExcludedProperties` are `string[]`
101
+
102
+ ```razor
103
+ <IgbCategoryChart IncludedProperties='@(new string[] { "Month", "Revenue" })' />
141
104
  ```
142
105
 
143
- ### Set `Brushes`, `Outlines`, and visual parameters inline - not via `@ref` in `OnAfterRenderAsync`
106
+ A plain string is a type mismatch. `XAxisLabel` formats labels — it does not select a data field.
144
107
 
145
- Setting visual parameters via `@ref` property assignment in `OnAfterRenderAsync` triggers Blazor warning **BL0005** (*Component parameter should not be set outside of its component*). Always pass them as **inline Razor markup attributes** instead.
108
+ ### `InnerExtent` is a chart property, never a series property
146
109
 
147
110
  ```razor
148
- <!-- ✅ Inline markup - no BL0005 -->
149
- <IgbRingSeries Brushes="#CF6E7A #6C74DC #D4A84B" Outlines="#13131F #13131F #13131F" ... />
150
-
151
- <!-- ❌ BL0005 warning -->
152
- jobSeries.Brushes = "#CF6E7A #6C74DC #D4A84B";
111
+ @* ✅ *@ <IgbDoughnutChart InnerExtent="0.45"><IgbRingSeries … /></IgbDoughnutChart>
112
+ @* ❌ runtime crash: IgbRingSeries does not have a property matching 'InnerExtent' *@
113
+ <IgbRingSeries InnerExtent="0.45" />
153
114
  ```
154
115
 
155
- ### Smooth area/line charts
156
- Match `ChartType` to the curve shape in the screenshot:
157
- - Smooth flowing curves → `Spline` (lines) or `SplineArea` (filled)
158
- - Angular/jagged lines → `Line` or `Area`
159
- - Step-shaped → `StepLine` or `StepArea`
116
+ ### Choosing the right circular component
160
117
 
161
- Do not default to `Line` or `Area` when the screenshot shows smooth curves. The difference is immediately visible and is the most common chart fidelity mistake.
118
+ - Thick static ring, centered label, no needle → `IgbDoughnutChart` + `IgbRingSeries`, label absolutely positioned over it.
119
+ - Thin animated spinner → `IgbCircularProgress` (not a visualization).
120
+ - Needle on a scale arc → `IgbRadialGauge`.
162
121
 
163
- ### Circular ring with centered percentage - choosing the right component
164
- - **Thick static ring with a centred label and no needle** → `IgbDoughnutChart` + `IgbRingSeries`. Place `InnerExtent` on the chart, not the series. Overlay the label with `position: absolute` inside a `position: relative` wrapper.
165
- - **Thin animated spinner / loading progress** → `IgbCircularProgress`. Not a data visualisation.
166
- - **Needle pointer on a scale arc** → `IgbRadialGauge`.
167
-
168
- `IgbRadialGauge` and `IgbCircularProgress` will never produce a clean static ring. Use `IgbDoughnutChart` whenever the design shows a coloured arc ring with a centred value and no needle.
122
+ Neither gauge nor progress will produce a clean static ring.
169
123
 
170
124
  ```razor
171
125
  <div class="gauge-wrapper">
172
126
  <IgbDoughnutChart InnerExtent="0.62" Height="160px" Width="160px" AllowSliceExplosion="false">
173
- <IgbRingSeries ValueMemberPath="Value" LabelMemberPath="Category"
174
- LabelsPosition="@LabelsPosition.None"
175
- DataSource="@GaugeData"
176
- Brushes="#5B57E8 #e8e8f5"
177
- Outlines="transparent transparent"
127
+ <IgbRingSeries DataSource="@GaugeData" ValueMemberPath="Value" LabelMemberPath="Category"
128
+ LabelsPosition="LabelsPosition.None"
129
+ Brushes="#5B57E8 #E8E8F5" Outlines="transparent transparent"
178
130
  RadiusFactor="0.95" />
179
131
  </IgbDoughnutChart>
180
132
  <div class="gauge-label">75%</div>
@@ -186,357 +138,117 @@ Do not default to `Line` or `Area` when the screenshot shows smooth curves. The
186
138
  .gauge-label { position: absolute; font-size: 1.9rem; font-weight: 700; }
187
139
  ```
188
140
 
189
- ### Charts inside CSS Grid can collapse
190
- Charts may render with zero height inside a CSS Grid container. Set `min-height: 0` on the grid cell and `Height="100%"` on the chart component so the chart fills its container without requiring a fixed pixel value:
191
- ```css
192
- .chart-container {
193
- min-height: 0; /* Prevents the CSS Grid track from collapsing */
194
- }
195
- ```
196
- ```razor
197
- <IgbCategoryChart Height="100%" Width="100%" ... />
198
- ```
199
-
200
- ---
201
-
202
- ## Component Properties
203
-
204
- ### IgbAvatar: use `Shape` parameter
205
- Use the `Shape` parameter with `AvatarShape.Circle`, `AvatarShape.Rounded`, or `AvatarShape.Square`. There is no `RoundShape` property:
206
- ```razor
207
- <IgbAvatar Shape="AvatarShape.Circle" Initials="JD" />
208
- ```
209
-
210
- ### Icons in web component slots: use IgbIcon, not font-icon spans
141
+ ### `IgbSparkline` has no smooth area
211
142
 
212
- Always use `IgbIcon` in slots (`prefix`, `suffix`, `start`, `end`, `icon`). `<span class="material-icons">` is `display: inline` - `vertical-align` is ignored by the slot's flex container, so the icon drifts to the top. `IgbIcon` is `display: inline-flex; align-items: center` and self-centers automatically.
143
+ It supports only `Line`, `Area`, `Column`, `WinLoss`, and `Area` fills with angular polygons. For a smooth mountain-shaped micro-chart use a small `IgbCategoryChart` with `ChartType="CategoryChartType.SplineArea"` and `AreaFillOpacity` — `AreaFillOpacity` does not exist on `IgbSparkline`.
213
144
 
214
- ```razor
215
- <!-- ❌ icon drifts to top -->
216
- <IgbInput><span slot="prefix" class="material-icons">search</span></IgbInput>
145
+ ### Charts collapse to zero height inside CSS Grid
217
146
 
218
- <!-- ✅ self-centering -->
219
- <IgbInput><IgbIcon @ref="_icon" slot="prefix" IconName="search" Collection="material" /></IgbInput>
147
+ ```css
148
+ .chart-container { min-height: 0; } /* stops the grid track collapsing */
220
149
  ```
221
- Register the icon in `OnAfterRenderAsync(firstRender)` after `EnsureReady()`.
222
-
223
- ### IgbList: slot-based structure
224
- Use named `slot` attributes on child elements inside `IgbListItem` for positioning:
225
150
  ```razor
226
- <IgbListItem>
227
- <IgbAvatar slot="start" Shape="AvatarShape.Circle" Initials="AB" />
228
- <span slot="title">Item Title</span>
229
- <span slot="subtitle">Secondary text</span>
230
- <IgbIcon slot="end" Collection="material" IconName="chevron_right" />
231
- </IgbListItem>
151
+ <IgbCategoryChart Height="100%" Width="100%" />
232
152
  ```
233
153
 
234
- ### IgbNavDrawer:
235
- The component's `::part(base)` is always `position: fixed; transform: translateX(-Npx)` - the host contributes `width: 0` to the layout. `Open="true"` makes it visible but still floating over content. `slot="mini"` adds a collapsed icon-only state. There is no `pin`/`pinned` Blazor parameter.
154
+ Charts never auto-size — always set `Width` and `Height`.
236
155
 
237
- To make the drawer occupy real layout space (pinned sidebar), override the parts in **global CSS**: set explicit width on the host, `position: relative; transform: none` on `::part(base)`, hide `::part(overlay)`, and strip `inert` from `::part(base)` via JS in `OnAfterRenderAsync`. See `layout.md` for the full pattern.
156
+ ### Map series are declared, not added from code
238
157
 
239
- ### IgbTileManager: drag and resize modes
240
- Set `DragMode` and `ResizeMode` for interactive dashboards:
241
158
  ```razor
242
- <IgbTileManager DragMode="TileManagerDragMode.TileHeader" ResizeMode="TileManagerResizeMode.Always">
243
- <IgbTile ColSpan="2" RowSpan="1">...</IgbTile>
244
- </IgbTileManager>
159
+ <IgbGeographicMap Height="500px" Width="100%">
160
+ <IgbGeographicSymbolSeries DataSource="Locations"
161
+ LatitudeMemberPath="Lat" LongitudeMemberPath="Lon"
162
+ MarkerType="MarkerType.Circle" MarkerBrush="#FF5722" />
163
+ </IgbGeographicMap>
245
164
  ```
246
165
 
247
- Valid drag modes include `TileHeader`, `Tile`, and `None`. Valid resize modes include `Always`, `Hover`, and `None`.
166
+ OpenStreetMap tiles are light. For a dark design, filter the container: `filter: grayscale(0.8) brightness(0.6);` — tune to match the image.
248
167
 
249
- ### IgbGrid: virtual rendering
250
- The grid requires a container with a defined height. Without it, the grid will not virtualize and may render all rows:
251
- ```css
252
- ::deep igc-grid {
253
- height: 500px;
254
- }
255
- ```
168
+ ## Components
256
169
 
257
- ---
170
+ ### `IgbNavDrawer` — use `Position="Relative"` for a pinned sidebar
258
171
 
259
- ## Theming Pitfalls
172
+ With `Start`/`End`/`Top`/`Bottom` the panel is `position: fixed`, floats over the content behind a dimming overlay, and the host contributes `width: 0` to the layout. There is no `Pin` parameter — but **`NavDrawerPosition.Relative` is the built-in pinned mode**: the panel becomes in-flow, the overlay is hidden, and closing slides it out by a negative margin.
260
173
 
261
- ### DV components do NOT inherit CSS theme colors
262
- Charts, maps, gauges, and sparklines ignore the global CSS custom property theme entirely. Set their visual properties explicitly via component parameters. After a palette exists, use the resolved color values (not `var()` references) for DV component parameters:
263
174
  ```razor
264
- <IgbCategoryChart
265
- Brushes="@primaryColor"
266
- Outlines="@primaryColor"
267
- XAxisLabelTextColor="@grayColor"
268
- YAxisMajorStroke="@grayLightColor" />
269
- ```
270
-
271
- ### Component-scoped theme overrides
272
- For core UI component theming, use `create_component_theme` with `platform: "blazor"` and `output: "css"`. The MCP generates global CSS selectors (`igc-*`). Place the output in:
273
-
274
- - **Global `app.css`** - use as-is (no `::deep`).
275
- - **`.razor.css` isolation file** - add `::deep` to each selector:
276
-
277
- ```css
278
- /* Dashboard.razor.css - add ::deep for isolation file */
279
- ::deep igc-grid {
280
- --ig-grid-header-background: var(--ig-primary-100);
281
- --ig-grid-content-background: var(--ig-surface-500);
282
- }
283
- ```
284
-
285
- Use `::part()` on an `igc-*` selector only when the property you need is not covered by any design token (verify via `get_component_design_tokens` first). In isolation files, combine `::deep` with `::part()`:
286
-
287
- ```css
288
- /* MyView.razor.css */
289
- ::deep igc-dialog::part(footer) {
290
- border-top: 1px solid var(--ig-gray-200);
291
- }
292
- ```
293
-
294
- ### Nav drawer sizing
295
- Size the drawer with layout CSS around the drawer or with CSS parts/tokens verified from the current docs.
296
- ```css
297
- .shell {
298
- display: grid;
299
- grid-template-columns: 260px 1fr;
300
- }
301
- ```
302
-
303
- ### Dark theme overrides for grids
304
- In dark themes, grid headers and rows may need explicit background overrides to match the design's surface hierarchy:
305
- ```css
306
- ::deep igc-grid {
307
- --ig-grid-header-background: var(--ig-surface-500);
308
- --ig-grid-content-background: var(--ig-surface-500);
309
- --ig-grid-row-hover-background: var(--ig-gray-100);
310
- }
311
- ```
312
-
313
- ### No hardcoded colors after palette generation
314
- Once a palette has been defined (via CSS custom property overrides or MCP `create_palette` / `create_theme`), core UI component colors should come from generated palette tokens - do not hardcode hex/RGB/HSL values. DV component parameters are the exception: charts, maps, gauges, and sparklines often need resolved color strings because they do not consume CSS variables consistently.
315
-
316
- **WRONG** (hardcoded hex - breaks theme switching, ignores the palette):
317
- ```css
318
- /* app.css - global */
319
- igc-avatar {
320
- --ig-avatar-background: #e91e63;
321
- }
175
+ <div class="app-shell">
176
+ <IgbNavDrawer Open="true" Position="NavDrawerPosition.Relative">…</IgbNavDrawer>
177
+ <main>@Body</main>
178
+ </div>
322
179
  ```
323
-
324
- **RIGHT** (palette token - stays in sync with the theme):
325
180
  ```css
326
- /* app.css - global */
327
- igc-avatar {
328
- --ig-avatar-background: var(--ig-primary-500);
329
- --ig-avatar-color: var(--ig-primary-500-contrast);
330
- }
331
-
332
- /* MyView.razor.css - isolation file: same tokens, add ::deep */
333
- ::deep igc-avatar {
334
- --ig-avatar-background: var(--ig-primary-500);
335
- --ig-avatar-color: var(--ig-primary-500-contrast);
336
- }
181
+ igc-nav-drawer { --menu-full-width: 260px; --menu-mini-width: 60px; }
182
+ .app-shell { display: flex; height: 100vh; }
337
183
  ```
338
184
 
339
- ### Read luminance warnings from theme generation
340
- If `create_theme` returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use `create_custom_palette` or define semantic CSS variables such as `--surface-1` and `--surface-2` in the global CSS file instead of relying on a single generated surface color.
185
+ Width comes from `--menu-full-width` — no `::part()` override needed. Content in `slot="mini"` shows while the drawer is closed, giving an icon rail. Do not call `ShowAsync()` from `OnAfterRenderAsync`; the component is not ready. Drive it with `Open`.
341
186
 
342
- ---
187
+ ### Icons in slots must be `IgbIcon`
343
188
 
344
- ## Map Component
189
+ A font-icon `<span>` is `display: inline`, so `vertical-align` is ignored by the slot's flex container and the glyph drifts to the top. `IgbIcon` is `inline-flex; align-items: center` and self-centers.
345
190
 
346
- ### Adding markers programmatically
347
- Map series are added as child components in Razor markup, not programmatically:
348
191
  ```razor
349
- <IgbGeographicMap Height="500px" Width="100%">
350
- <IgbGeographicSymbolSeries
351
- DataSource="Locations"
352
- LatitudeMemberPath="Lat"
353
- LongitudeMemberPath="Lon"
354
- MarkerType="MarkerType.Circle"
355
- MarkerBrush="#FF5722" />
356
- </IgbGeographicMap>
357
- ```
358
-
359
- ### Dark map styling
360
- OpenStreetMap tiles are light by default. For dark themes, apply a CSS filter to the map container. Adjust the values to match the map tone in the design image:
361
- ```css
362
- .map-container {
363
- /* tune grayscale (0-1) and brightness (0-1) to match the design */
364
- filter: grayscale(0.8) brightness(0.6);
365
- }
192
+ @* ❌ *@ <IgbInput><span slot="prefix" class="material-icons">search</span></IgbInput>
193
+ @* ✅ *@ <IgbInput><IgbIcon @ref="_icon" slot="prefix" IconName="search" Collection="material" /></IgbInput>
366
194
  ```
367
195
 
368
- ---
369
-
370
- ## Dark Theme Specifics
196
+ The parameter is `IconName`; `Name` is the framework's element identity on every component. Register the icon in `OnAfterRenderAsync(firstRender)` after `await EnsureReady()`, or nothing renders.
371
197
 
372
- ### Use the dark theme CSS variant
373
- Switch the theme `<link>` from light to dark:
374
- ```html
375
- <!-- Light -->
376
- <link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
377
- <!-- Dark -->
378
- <link href="_content/IgniteUI.Blazor/themes/dark/bootstrap.css" rel="stylesheet" />
379
- ```
380
-
381
- > **If the view includes any full-featured grid**, switch the grid-specific stylesheet variant too:
382
- > ```html
383
- > <!-- Light -->
384
- > <link href="_content/IgniteUI.Blazor/themes/grid/light/bootstrap.css" rel="stylesheet" />
385
- > <!-- Dark -->
386
- > <link href="_content/IgniteUI.Blazor/themes/grid/dark/bootstrap.css" rel="stylesheet" />
387
- > ```
388
- >
389
- > **If the view uses `IgbGridLite`**, switch its single stylesheet instead:
390
- > ```html
391
- > <!-- Light -->
392
- > <link href="_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css" rel="stylesheet" />
393
- > <!-- Dark -->
394
- > <link href="_content/IgniteUI.Blazor.GridLite/css/themes/dark/bootstrap.css" rel="stylesheet" />
395
- > ```
396
-
397
- ### CSS custom properties for dark panels
398
- When the design has multiple dark surface depths (e.g., sidebar darker than content area), define semantic tokens:
399
- ```css
400
- :root {
401
- --surface-1: var(--ig-gray-900); /* deepest (sidebar, drawer) */
402
- --surface-2: var(--ig-gray-800); /* content area */
403
- --surface-3: var(--ig-gray-700); /* elevated cards/panels */
404
- }
405
- ```
198
+ ### `Name` never groups or names a form field
406
199
 
407
- Apply these in layout CSS rather than hardcoding hex values.
200
+ `<IgbRadioGroup Name="plan">` does not group radios — being children of the group does, and the selection is the group's `@bind-Value`.
408
201
 
409
- ### Programmatic dark/light toggle
410
- Swap the CSS `<link>` element via JS interop:
411
- ```html
412
- <script>
413
- window.themeSwitcher = {
414
- setTheme(href) {
415
- document.getElementById('theme-css').href = href;
416
- }
417
- };
418
- </script>
419
- ```
202
+ ### `IgbAvatar` uses `Shape`
420
203
 
421
- ```csharp
422
- await JS.InvokeVoidAsync(
423
- "themeSwitcher.setTheme",
424
- "_content/IgniteUI.Blazor/themes/dark/bootstrap.css");
425
- ```
204
+ `AvatarShape.Circle | Rounded | Square`. There is no `RoundShape`.
426
205
 
427
- Or toggle a CSS class with variable overrides (see `igniteui-blazor-theming` skill for full patterns).
206
+ ### `IgbCombo`'s generic parameter is `T`
428
207
 
429
- ---
208
+ `<IgbCombo T="Person" …>`, not `TValue`.
430
209
 
431
- ## Blazor-specific Gotchas
210
+ ### `IgbCard` has no default width
432
211
 
433
- ### RZ9986 - Dynamic CSS class on Ignite UI components
212
+ Always set one.
434
213
 
435
- Blazor raises **RZ9986: Component attributes do not support complex content** when a CSS class string is built inline on an Ignite UI component:
214
+ ### `IgbTileManager` drag and resize modes
436
215
 
437
- ```razor
438
- @* WRONG - RZ9986 build failure *@
439
- <IgbChip class="chip @(item == _selected ? "chip-active" : "")" />
440
- ```
216
+ `DragMode`: `None | TileHeader | Tile`. `ResizeMode`: `None | Hover | Always`.
441
217
 
442
- Move the class logic into a C# helper method that returns the complete string:
218
+ ### Grids need a height
443
219
 
444
- ```razor
445
- @* RIGHT - no RZ9986 *@
446
- <IgbChip class="@ChipClass(item)" />
220
+ Without one the grid renders every row and virtualization is off. Also remember the **grid-specific stylesheet** alongside the base theme for any full-featured grid.
447
221
 
448
- @code {
449
- private string ChipClass(Item item) =>
450
- item == _selected ? "chip chip-active" : "chip";
451
- }
452
- ```
222
+ ## Dark themes
453
223
 
454
- This applies to **any** `Igb*` component. The `RZ9986` issue is caused by **complex attribute content** on components (for example, mixing literal text with `@(...)` blocks in the same attribute). To avoid it, make the entire `class` value a single C# expression - either by using a helper method as shown above or by returning the full class string from one inline expression.
224
+ Switch both stylesheets together:
455
225
 
456
- ### Always register modules in `Program.cs`
457
- Every `Igb*` component needs its `IgbXxxModule` registered via `AddIgniteUIBlazor()`. If a component silently fails to render, the most common cause is a missing module registration:
458
- ```csharp
459
- builder.Services.AddIgniteUIBlazor(
460
- typeof(IgbCategoryChartModule),
461
- typeof(IgbListModule),
462
- typeof(IgbNavbarModule)
463
- );
226
+ ```html
227
+ <link href="_content/IgniteUI.Blazor/themes/dark/bootstrap.css" rel="stylesheet" />
228
+ <link href="_content/IgniteUI.Blazor/themes/grid/dark/bootstrap.css" rel="stylesheet" />
229
+ <!-- IgbGridLite instead: _content/IgniteUI.Blazor.GridLite/css/themes/dark/bootstrap.css -->
464
230
  ```
465
231
 
466
- ### Two-way binding uses `@bind-` prefix where the component exposes bindable values
467
- Blazor uses `@bind-Value`, `@bind-Checked`, etc. Verify the exact bindable parameter from the component docs before inventing one:
468
- ```razor
469
- <IgbInput @bind-Value="searchText" />
470
- <IgbSwitch @bind-Checked="isDarkMode" />
471
- ```
232
+ For a runtime toggle, prefer `IgbThemeProvider` (`Theme`, `Variant`) over swapping `<link href>` via JS interop — no interop and it can scope to a region.
472
233
 
473
- ### Event handler pattern
474
- Use the event pattern shown in the Blazor docs for that component. Native click handling on Ignite UI buttons commonly uses Blazor's `@onclick`; component events use their PascalCase event names:
475
- ```razor
476
- <IgbButton @onclick="HandleClick">Save</IgbButton>
477
- <IgbGrid RowSelectionChanging="OnRowSelection" />
234
+ **Multiple surface depths.** A single generated surface will not cover a sidebar darker than the content area. Define semantic variables and use them in layout CSS:
478
235
 
479
- @code {
480
- private void HandleClick() { /* ... */ }
481
- private void OnRowSelection(IgbRowSelectionEventArgs args) { /* ... */ }
236
+ ```css
237
+ :root {
238
+ --surface-1: var(--ig-gray-900); /* sidebar */
239
+ --surface-2: var(--ig-gray-800); /* content */
240
+ --surface-3: var(--ig-gray-700); /* elevated cards */
482
241
  }
483
242
  ```
484
243
 
485
- ### Template context with `<Template>`
486
- Ignite UI Blazor uses `<Template>` child elements with the `context` parameter - not Angular's `<ng-template>`:
487
- ```razor
488
- <IgbGrid Data="Data">
489
- <IgbColumn Field="Name" Header="Name">
490
- <Template>
491
- <div>
492
- <strong>@context.Cell.Value</strong>
493
- </div>
494
- </Template>
495
- </IgbColumn>
496
- </IgbGrid>
497
- ```
498
-
499
- ### `@ref` for programmatic access
500
- Use `@ref` with a matching field of the component type:
501
- ```razor
502
- <IgbDialog @ref="dialog">
503
- <p>Dialog content</p>
504
- </IgbDialog>
505
-
506
- @code {
507
- private IgbDialog dialog = default!;
244
+ Grid headers and rows often need explicit backgrounds to match the design's hierarchy in dark mode:
508
245
 
509
- private async Task ShowDialog()
510
- {
511
- await dialog.ShowAsync();
512
- }
246
+ ```css
247
+ igc-grid {
248
+ --ig-grid-header-background: var(--ig-surface-500);
249
+ --ig-grid-content-background: var(--ig-surface-500);
250
+ --ig-grid-row-hover-background: var(--ig-gray-100);
513
251
  }
514
252
  ```
515
253
 
516
- ### C# data models - use records or classes
517
- Use C# `record` or `class` types for mock data - not TypeScript interfaces:
518
- ```csharp
519
- record SalesRecord(string Month, double Revenue, double Profit);
520
- record Contact(string Name, string Email, string Initials);
521
- ```
522
-
523
- ### Avoid inline styles - use CSS isolation
524
- Keep layout, spacing, typography, and surface styling in `.razor.css` files rather than using `style=""` inline attributes. This makes theming consistent and maintainable.
525
-
526
- ### Parameter naming: PascalCase
527
- Blazor component parameters use PascalCase (`ChartType`, `DataSource`, `MarkerTypes`) - not Angular's camelCase bindings (`[chartType]`, `[dataSource]`, `[markerTypes]`).
528
-
529
- ### Single quotes in Razor attribute expressions cause CS1012
530
- In Razor, `@onclick="() => Navigate('/dashboard')"` fails because the single quotes inside the double-quoted attribute are parsed as C# `char` literals, producing error CS1012. Use a named method or a variable instead:
531
- ```razor
532
- @* WRONG - single quotes parsed as char literal *@
533
- <IgbNavDrawerItem @onclick="() => Navigate('/dashboard')">
534
-
535
- @* RIGHT - use a method reference or extract the path *@
536
- <IgbNavDrawerItem @onclick="NavigateToDashboard">
537
-
538
- @code {
539
- private void NavigateToDashboard() => NavigationManager.NavigateTo("/dashboard");
540
- }
541
- ```
542
- This applies to any inline lambda where a string literal containing `/` or special chars appears inside a double-quoted Razor attribute. Prefer named handler methods over inline lambdas with string arguments.
254
+ **No hardcoded hex after the palette exists.** Core component colors come from palette tokens (`var(--ig-primary-500)`, `var(--ig-primary-500-contrast)`) so theme switching keeps working. Chart, map, gauge and sparkline parameters are the exception — they need resolved color values.