igniteui-cli 14.10.0-alpha.3 → 14.10.0-alpha.4

package/templates/react/igr-ts/projects/_base/files/__dot__claude/skills/igniteui-react-components/reference/REVEAL-SDK.md

@@ -0,0 +1,198 @@
+# Reveal SDK Integration
+
+Reveal SDK is a companion product for embedding interactive BI dashboards and data visualizations inside your React application. It requires client-side runtime dependencies, a backend Reveal server, and proper initialization.
+
+> **⚠️ IMPORTANT:** `RvRevealView` is NOT self-sufficient. You must load the Reveal client runtime, configure the backend URL, and initialize Reveal properly using `useEffect` after mount — never in the render phase.
+
+## Step 1: Install Dependencies
+
+```bash
+npm install reveal-sdk-wrappers-react reveal-sdk-wrappers
+```
+
+## Step 2: Load Reveal Client Runtime
+
+Reveal SDK requires these client-side scripts to be loaded **before** using any Reveal components. Add them to your `index.html` or load them dynamically:
+
+```html
+<!-- In public/index.html (or equivalent) -->
+<script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dayjs@1.11.5/dayjs.min.js"></script>
+<script src="https://dl.revealbi.io/reveal/libs/1.6.4/infragistics.reveal.js"></script>
+```
+
+Replace `1.6.4` with your Reveal SDK version.
+
+> **Note:** The Reveal SDK exposes its API through the `$.ig` global namespace. If TypeScript reports that `$` is not defined, add this declaration:
+> ```tsx
+> declare const $: any;
+> ```
+
+## Step 3: Container Sizing (REQUIRED)
+
+Reveal views require a **properly sized container**. Without explicit dimensions, the dashboard will not render:
+
+```css
+/* dashboard.module.css */
+.reveal-container {
+  width: 100%;
+  height: 100%;
+  min-width: 400px;
+  min-height: 400px;
+}
+```
+
+## Step 4: Basic Integration Pattern
+
+> **⚠️ CRITICAL:** Always initialize Reveal in `useEffect` after the component mounts — never during render. Add guards for missing `$` and `$.ig` to prevent errors if scripts haven't loaded.
+
+```tsx
+import { useEffect, useRef } from 'react';
+import styles from './dashboard.module.css';
+
+declare const $: any;
+
+export default function DashboardView() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const revealViewRef = useRef<any>(null);
+
+  useEffect(() => {
+    // Guard: Ensure Reveal runtime is loaded
+    if (typeof $ === 'undefined' || !$.ig) {
+      console.error('Reveal SDK runtime not loaded. Ensure jQuery, Day.js, and infragistics.reveal.js are included.');
+      return;
+    }
+
+    // Guard: Prevent double initialization
+    if (revealViewRef.current) {
+      return;
+    }
+
+    // Guard: Ensure container exists
+    if (!containerRef.current) {
+      return;
+    }
+
+    // Configure Reveal SDK backend URL (REQUIRED)
+    $.ig.RevealSdkSettings.setBaseUrl('https://your-reveal-server/reveal-api/');
+
+    // Initialize RevealView with the container element
+    revealViewRef.current = new $.ig.RevealView(containerRef.current);
+
+    // Optional: Load a specific dashboard
+    // $.ig.RVDashboard.loadDashboard('your-dashboard-id').then((dashboard: any) => {
+    //   revealViewRef.current.dashboard = dashboard;
+    // });
+
+    // Cleanup on unmount
+    return () => {
+      if (revealViewRef.current) {
+        revealViewRef.current = null;
+      }
+    };
+  }, []);
+
+  return <div ref={containerRef} className={styles['reveal-container']} />;
+}
+```
+
+## Using RvRevealView Wrapper (Alternative)
+
+The `RvRevealView` wrapper simplifies some boilerplate but still requires proper runtime setup and `useEffect` initialization:
+
+```tsx
+import { useEffect } from 'react';
+import { RvRevealView } from 'reveal-sdk-wrappers-react';
+import { RevealViewOptions } from 'reveal-sdk-wrappers';
+import styles from './dashboard.module.css';
+
+declare const $: any;
+
+export default function DashboardView() {
+  useEffect(() => {
+    // Guard: Ensure Reveal runtime is loaded
+    if (typeof $ === 'undefined' || !$.ig) {
+      console.error('Reveal SDK runtime not loaded.');
+      return;
+    }
+
+    // Configure backend URL (REQUIRED) — must be done before render
+    $.ig.RevealSdkSettings.setBaseUrl('https://your-reveal-server/reveal-api/');
+
+    // Optional: Apply theme sync with Ignite UI
+    setRevealTheme();
+  }, []);
+
+  const options: RevealViewOptions = {
+    visualizations: {
+      menu: {
+        copy: false,
+        duplicate: false
+      }
+    }
+  };
+
+  return (
+    <div className={styles['reveal-container']}>
+      <RvRevealView options={options} />
+    </div>
+  );
+}
+
+function setRevealTheme() {
+  // Guard: Ensure $.ig exists
+  if (typeof $ === 'undefined' || !$.ig) return;
+
+  const style = window.getComputedStyle(document.body);
+  const theme = new $.ig.RevealTheme();
+
+  // Sync fonts with Ignite UI
+  theme.regularFont = style.getPropertyValue('--ig-font-family').trim() || 'sans-serif';
+  theme.mediumFont = theme.regularFont;
+  theme.boldFont = theme.regularFont;
+
+  // Auto-detect light/dark mode
+  const color = style.getPropertyValue('--ig-surface-500').trim() || '#fff';
+  const [r, g, b] = [1, 3, 5].map(i => parseInt(color.substring(i, i + 2), 16));
+  const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+
+  theme.isDark = brightness < 128;
+  theme.fontColor = theme.isDark ? 'white' : 'black';
+  theme.dashboardBackgroundColor = style.getPropertyValue('--ig-gray-100').trim();
+  theme.visualizationBackgroundColor = style.getPropertyValue('--ig-surface-500').trim();
+
+  $.ig.RevealSdkSettings.theme = theme;
+}
+```
+
+## Token Mapping Reference (Theme Sync)
+
+| Reveal Theme Property | Ignite UI CSS Token | Purpose |
+|---|---|---|
+| `regularFont`, `mediumFont`, `boldFont` | `--ig-font-family` | Font family |
+| `isDark` | Computed from `--ig-surface-500` brightness | Light/dark mode detection |
+| `fontColor` | Derived from `isDark` | Text color (white for dark, black for light) |
+| `dashboardBackgroundColor` | `--ig-gray-100` | Dashboard background |
+| `visualizationBackgroundColor` | `--ig-surface-500` | Individual visualization card background |
+
+## Common Issues
+
+### Reveal view is blank or throws errors
+- **Cause:** Reveal runtime scripts not loaded (jQuery, Day.js, infragistics.reveal.js)
+- **Solution:** Add the required scripts to `index.html` before your React app loads
+
+### `$` or `$.ig` is undefined
+- **Cause:** Scripts not loaded or loaded after React component renders
+- **Solution:** Ensure scripts are in `<head>` or loaded before React mounts; add guards in `useEffect`
+
+### Dashboard not visible
+- **Cause:** Container has no dimensions
+- **Solution:** Add explicit `width`, `height`, `min-width`, `min-height` to the container
+
+### Double initialization errors
+- **Cause:** `useEffect` running multiple times (Strict Mode) without cleanup
+- **Solution:** Use a ref to track initialization state and prevent re-initialization
+
+> **Tip:** When switching between light and dark Ignite UI themes, call `setRevealTheme()` again after the theme change so Reveal dashboards stay in sync.
+
+See the [customize-theme skill](../../igniteui-react-customize-theme/SKILL.md) for more details on Ignite UI CSS custom properties and theme switching.

package/templates/react/igr-ts/projects/_base/files/__dot__claude/skills/igniteui-react-components/reference/TROUBLESHOOTING.md

@@ -0,0 +1,147 @@
+# Troubleshooting
+
+## Issue: Components render without styles
+
+**Cause:** Missing theme CSS import. Without the theme CSS, components will render with broken layouts, missing icons (showing placeholders), and no visual styling.
+
+**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:
+
+```tsx
+// Always required for core components
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+
+// Also required when using grids (IgrGrid, IgrTreeGrid, etc.)
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+```
+
+**Next.js example:**
+
+```tsx
+'use client';
+
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+
+import { IgrNavbar, IgrButton } from 'igniteui-react';
+import { IgrGrid, IgrColumn, IgrPaginator } from 'igniteui-react-grids';
+```
+
+## Issue: Grid renders but icons show as placeholders and styles are missing
+
+**Cause:** The grid theme CSS (`igniteui-react-grids/grids/themes/...`) is not imported. The base theme CSS alone is not enough for grids.
+
+**Solution:** Import **both** theme CSS files:
+
+```tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css';    // Base theme
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css'; // Grid theme
+```
+
+## Issue: Grid Lite does not render or compilation error
+
+**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.
+
+**Solution:**
+
+1. Install both required packages: `npm install igniteui-react igniteui-grid-lite`
+2. Import `IgrGridLite` from `igniteui-react/grid-lite`
+3. Wrap in a sized container (see [CHARTS-GRIDS.md](./CHARTS-GRIDS.md) for a full example)
+
+## Issue: `IgrGridLite` is confused with `IgrGrid` from `igniteui-react-grids`
+
+**Solution:** These are different components:
+- `igniteui-react/grid-lite` → lightweight MIT grid (`IgrGridLite`, React wrapper — no `.register()` needed, requires both `igniteui-react` and `igniteui-grid-lite` packages)
+- `igniteui-react-grids` → full-featured commercial grids (`IgrGrid`, `IgrTreeGrid`, etc. — React wrappers)
+
+Import from the correct package for your needs:
+
+```tsx
+// Lightweight grid (MIT, React wrapper, no registration needed)
+import { IgrGridLite } from 'igniteui-react/grid-lite';
+
+// Full-featured grid (commercial, React wrapper)
+import { IgrGrid } from 'igniteui-react-grids';
+```
+
+## Issue: Events fire but have unexpected shape
+
+**Cause:** Ignite UI events are `CustomEvent` objects from the underlying web component, not React `SyntheticEvent` objects.
+
+**Solution:** Type the handler parameter as `CustomEvent` and access `.detail` for event-specific data or `.target` for the element:
+
+```tsx
+const handleChange = (e: CustomEvent) => {
+  const target = e.target as HTMLElement;
+  const detail = e.detail;
+  // Use target or detail as appropriate
+};
+```
+
+## Issue: Component methods not accessible
+
+**Solution:** Use `useRef` with the component type:
+
+```tsx
+const dialogRef = useRef<IgrDialog>(null);
+
+// Call imperative method
+dialogRef.current?.show();
+```
+
+## Issue: Chart / gauge / map does not render or is invisible
+
+**Cause:** Two common causes:
+1. The corresponding module was not registered (e.g., `IgrCategoryChartModule.register()` was not called)
+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
+
+**Solution:**
+
+1. **Register the module** at the top level of the file (outside the component):
+
+```tsx
+import { IgrCategoryChart, IgrCategoryChartModule } from 'igniteui-react-charts';
+IgrCategoryChartModule.register();
+```
+
+2. **Wrap the chart in a sized container** with explicit dimensions:
+
+```css
+.chart-container {
+  min-width: 400px;
+  min-height: 300px;
+  flex-grow: 1;
+  flex-basis: 0;
+}
+.chart-container > * { height: 100%; width: 100%; }
+```
+
+```tsx
+<div className={styles['chart-container']}>
+  <IgrCategoryChart dataSource={data} />
+</div>
+```
+
+## Issue: IgrTabs used for navigation fills the entire view with content
+
+**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.
+
+**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:
+
+```tsx
+// ✅ Correct — navigation tabs with label-only (no inline content)
+<IgrTabs onChange={handleTabChange}>
+  <IgrTab label="Dashboard" selected={location.pathname === '/dashboard'} />
+  <IgrTab label="Orders" selected={location.pathname === '/orders'} />
+</IgrTabs>
+<Outlet />
+
+// ❌ Wrong — inline content creates unwanted space when used for navigation
+<IgrTabs>
+  <IgrTab label="Dashboard">
+    <p>This content will show and take up space!</p>  {/* Don't do this for navigation */}
+  </IgrTab>
+  <IgrTab label="Orders">
+    <p>This content will show and take up space!</p>  {/* Don't do this for navigation */}
+  </IgrTab>
+</IgrTabs>
+```

package/templates/react/igr-ts/projects/_base/files/__dot__claude/skills/igniteui-react-customize-theme/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: igniteui-react-customize-theme
+description: This skill customizes Ignite UI for React component styling using CSS custom properties, Sass, and the full theming system and should be used when applying brand colors, dark mode, component-level overrides, or scoped themes in a React application
+user-invocable: true
+---
+
+# Ignite UI for React — Theming Skill
+
+## Description
+
+This skill teaches AI agents how to theme Ignite UI for React applications. Two approaches are supported:
+
+- **CSS custom properties** — works in any project without additional build tooling
+- **Sass** — available when the project has Sass configured; provides the full palette/typography/elevation API
+
+The skill also covers component-level theming, layout controls (spacing, sizing, roundness), and how to use the **Ignite UI Theming MCP server** for AI-assisted code generation — all in a React application context.
+
+## Example Usage
+
+- "How do I change the primary color in my Ignite UI React app?"
+- "Apply a dark theme to my React app"
+- "Customize the grid header colors"
+- "How do I scope a theme to a specific section of my React app?"
+- "Set up Material Design theming for Ignite UI components"
+
+## Prerequisites
+
+- A React project with `igniteui-react` installed
+- A theme CSS file imported in your entry point (see [igniteui-react-components](../igniteui-react-components/SKILL.md))
+- **Optional**: Sass configured in the project (enables the Sass-based theming API)
+- **Optional**: The **Ignite UI Theming MCP server** (`igniteui-theming`) for AI-assisted code generation
+
+## Related Skills
+
+- [igniteui-react-components](../igniteui-react-components/SKILL.md) — Choose the right components and set up your React project
+- [igniteui-react-optimize-bundle-size](../igniteui-react-optimize-bundle-size/SKILL.md) — Optimize after theming
+
+## When to Use
+
+- Applying custom brand colors or a dark theme to an Ignite UI React app
+- Overriding individual component styles (e.g., grid header color, button appearance)
+- Switching between light and dark mode in a React app
+- Scoping different themes to different sections of a React app
+- Setting up the Ignite UI Theming MCP server for AI-assisted theming
+
+---
+
+## Content Guide
+
+This skill is organized into focused sections. Refer to the appropriate file for detailed instructions:
+
+| Topic | File | When to Use |
+|---|---|---|
+| CSS Theming | [CSS-THEMING.md](./reference/CSS-THEMING.md) | Pre-built themes, CSS custom properties, scoped overrides, layout controls, light/dark switching |
+| Sass Theming | [SASS-THEMING.md](./reference/SASS-THEMING.md) | Sass-based theming with palette(), component theme functions |
+| MCP Server | [MCP-SERVER.md](./reference/MCP-SERVER.md) | AI-assisted theming code generation |
+| Reveal Theme Sync | [REVEAL-THEME.md](./reference/REVEAL-THEME.md) | Syncing Reveal SDK dashboards with Ignite UI theme |
+| Troubleshooting | [TROUBLESHOOTING.md](./reference/TROUBLESHOOTING.md) | Common issues and solutions |
+
+---
+
+## Quick Start
+
+### 1. Import a Pre-built Theme (REQUIRED)
+
+```tsx
+// main.tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+```
+
+**For grids**, also import:
+
+```tsx
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+```
+
+### 2. Override with CSS Custom Properties
+
+```css
+/* src/index.css */
+:root {
+  --ig-primary-h: 211deg;
+  --ig-primary-s: 100%;
+  --ig-primary-l: 50%;
+}
+```
+
+```tsx
+// main.tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css'; // Theme first
+import './index.css'; // Overrides second
+```
+
+---
+
+## Theming Architecture
+
+The Ignite UI theming system is built on four pillars:
+
+| Concept | Purpose |
+|---|---|
+| **Palette** | Color system with primary, secondary, surface, gray, info, success, warn, error families |
+| **Typography** | Font family, type scale (h1–h6, subtitle, body, button, caption, overline) |
+| **Elevations** | Box-shadow levels 0–24 for visual depth |
+| **Schema** | Per-component recipes mapping palette colors to component tokens |
+
+### Design Systems
+
+- **Bootstrap** (default), **Material**, **Fluent**, **Indigo**
+- Each has light and dark variants
+
+---
+
+## Key Concepts
+
+### CSS Custom Properties
+
+Override tokens in your CSS:
+
+```css
+:root { --ig-primary-h: 211deg; }
+.admin-panel { --ig-primary-h: 260deg; }
+```
+
+### Component-Level Theming
+
+Target web component tag names in CSS:
+
+```css
+igc-button { --ig-button-foreground: var(--ig-secondary-500); }
+```
+
+### CSS `::part()` Selectors
+
+```css
+igc-input::part(input) { font-size: 1.1rem; }
+```
+
+### Layout Controls
+
+```css
+:root {
+  --ig-size: 2;          /* 1=small, 2=medium, 3=large */
+  --ig-spacing: 1;       /* 0.5=compact, 1=default, 2=spacious */
+  --ig-radius-factor: 1; /* 0=square, 1=max radius */
+}
+```
+
+### Light/Dark Switching
+
+See [CSS-THEMING.md](./reference/CSS-THEMING.md) for approaches: class toggle, media query, or stylesheet swap.
+
+---
+
+## Best Practices
+
+1. **Import theme CSS first**, then your custom overrides
+2. **Use palette tokens** (`var(--ig-primary-500)`) for all colors — never hardcode hex values
+3. **Use CSS custom properties on `:root`** for global theme adjustments
+4. **Scope overrides with CSS classes** for different sections
+5. **Use `::part()` selectors** to style shadow DOM internals
+6. **In CSS selectors, use web component tag names** (`igc-button`), not React names (`IgrButton`)
+7. **Test both light and dark themes**
+8. **Use the MCP server** for AI-assisted theme generation when available
+
+## Key Rules
+
+1. **Never overwrite existing files directly** — propose theme code as an update for user review
+2. **Always call `detect_platform` first** when using MCP tools
+3. **Always call `get_component_design_tokens` before `create_component_theme`**
+4. **Palette shades**: 50 = lightest, 900 = darkest
+5. **Surface color must match variant** — light color for `light`, dark for `dark`
+6. **Sass**: Use `@use 'igniteui-theming'` — not `igniteui-angular/theming`
+7. **Sass**: Component themes use `@include tokens($theme)` inside a selector
+8. **Never hardcode colors after palette generation**
+
+## Additional Resources
+
+- [Ignite UI for React — Themes Overview](https://www.infragistics.com/products/ignite-ui-react/react/components/themes/overview)
+- [igniteui-theming npm package](https://www.npmjs.com/package/igniteui-theming)
+- [CSS Custom Properties on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- [CSS ::part() on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)