igniteui-webcomponents 6.5.1 → 7.0.0

package/skills/igniteui-wc-integrate-with-framework/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: igniteui-wc-integrate-with-framework
+description: Integrate igniteui-webcomponents into React, Angular, Vue, or vanilla JS applications with framework-specific configurations
+user-invokable: true
+---
+
+# Integrate with Framework
+
+This skill helps users integrate Ignite UI Web Components into their application. It detects the framework or platform in use and loads the appropriate step-by-step integration reference.
+
+## Example Usage
+
+- "How do I use igniteui-webcomponents in my React app?"
+- "Integrate the button component in Angular"
+- "Set up igniteui-webcomponents in Vue 3"
+- "Help me add web components to my vanilla JS project"
+
+## Related Skills
+
+- [igniteui-wc-optimize-bundle-size](../igniteui-wc-optimize-bundle-size/SKILL.md) - Reduce bundle size after integration
+- [igniteui-wc-customize-component-theme](../igniteui-wc-customize-component-theme/SKILL.md) - Style components after setup
+
+## When to Use
+
+- User wants to add igniteui-webcomponents to a framework project
+- User is experiencing framework-specific integration issues
+- User needs help with component imports and registration
+- User asks about React, Angular, Vue, or vanilla JS setup
+
+---
+
+## Framework Detection
+
+Before loading a reference, identify the target framework from the project context. Check the following signals in order:
+
+### 1. Detect React
+
+**Evidence to look for:**
+- `package.json` contains `"react"` or `"react-dom"` in `dependencies` or `devDependencies`
+- Files with `.tsx` or `.jsx` extensions exist in `src/`
+- Entry point imports `ReactDOM` or `createRoot`
+- `vite.config.ts` uses `@vitejs/plugin-react` or `@vitejs/plugin-react-swc`
+
+→ **Load:** [react.md](./references/react.md)
+
+---
+
+### 2. Detect Angular
+
+**Evidence to look for:**
+- `package.json` contains `"@angular/core"` in `dependencies`
+- `angular.json` file exists in the workspace root
+- Files with `.component.ts`, `.module.ts`, or `.component.html` patterns exist
+- Entry point calls `bootstrapApplication` or `platformBrowserDynamic`
+
+→ **Load:** [angular.md](./references/angular.md)
+
+---
+
+### 3. Detect Vue 3
+
+**Evidence to look for:**
+- `package.json` contains `"vue"` in `dependencies` or `devDependencies`
+- Files with `.vue` extensions exist in `src/`
+- `vite.config.ts` uses `@vitejs/plugin-vue`
+- Entry point calls `createApp`
+
+→ **Load:** [vue.md](./references/vue.md)
+
+---
+
+### 4. Vanilla JavaScript / HTML (fallback)
+
+**Evidence to look for:**
+- No major framework found in `package.json`
+- Plain `.html` files reference a `<script type="module">`
+- Entry point is a plain `.js` or `.ts` file with no framework imports
+- User explicitly asks for vanilla JS or HTML integration
+
+→ **Load:** [vanilla-js.md](./references/vanilla-js.md)
+
+---
+
+## If the Framework Cannot Be Determined
+
+Ask the user directly:
+
+> "What framework or platform are you using? (React, Angular, Vue 3, or Vanilla JS / HTML)"
+
+Then load the matching reference from the options above.
+
+---
+
+## Framework Reference Files
+
+| Framework / Platform | Reference |
+|----------------------|-----------|
+| React | [react.md](./references/react.md) |
+| Angular | [angular.md](./references/angular.md) |
+| Vue 3 | [vue.md](./references/vue.md) |
+| Vanilla JS / HTML | [vanilla-js.md](./references/vanilla-js.md) |
+
+Each reference covers:
+
+- Installation
+- Theme import (required for styling)
+- Component registration
+- Usage examples
+- TypeScript support
+- Platform-specific considerations
+- Common issues and solutions
+

package/skills/igniteui-wc-integrate-with-framework/references/angular.md

@@ -0,0 +1,185 @@
+# Integrating Ignite UI Web Components — Angular
+
+## Installation
+
+```bash
+npm install igniteui-webcomponents
+```
+
+## Setup
+
+### Step 1 — Register the theme and components
+
+In `src/main.ts`, import a theme and register the components before bootstrapping:
+
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { appConfig } from './app/app.config';
+import { AppComponent } from './app/app.component';
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import { defineComponents, IgcButtonComponent, IgcInputComponent } from 'igniteui-webcomponents';
+
+defineComponents(IgcButtonComponent, IgcInputComponent);
+
+bootstrapApplication(AppComponent, appConfig)
+  .catch((err) => console.error(err));
+```
+
+### Step 2 — Add `CUSTOM_ELEMENTS_SCHEMA`
+
+Angular requires `CUSTOM_ELEMENTS_SCHEMA` to accept custom element tags in templates.
+
+**Standalone components** — add the schema to each component that uses Ignite UI elements:
+
+```typescript
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-my-component',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <igc-button variant="contained">Click me</igc-button>
+  `
+})
+export class MyComponent {}
+```
+
+**NgModule-based apps** — add the schema once to `AppModule` (or the relevant module):
+
+```typescript
+import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+## Available Themes
+
+| Theme     | Light                                                  | Dark                                                  |
+|-----------|--------------------------------------------------------|-------------------------------------------------------|
+| Bootstrap | `igniteui-webcomponents/themes/light/bootstrap.css`    | `igniteui-webcomponents/themes/dark/bootstrap.css`    |
+| Material  | `igniteui-webcomponents/themes/light/material.css`     | `igniteui-webcomponents/themes/dark/material.css`     |
+| Fluent    | `igniteui-webcomponents/themes/light/fluent.css`       | `igniteui-webcomponents/themes/dark/fluent.css`       |
+| Indigo    | `igniteui-webcomponents/themes/light/indigo.css`       | `igniteui-webcomponents/themes/dark/indigo.css`       |
+
+## Usage in Templates
+
+```typescript
+import { Component, ViewChild, ElementRef, AfterViewInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-my-component',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <igc-button
+      #myButton
+      variant="contained"
+      (click)="handleClick($event)">
+      Click me
+    </igc-button>
+
+    <igc-input
+      [label]="inputLabel"
+      [placeholder]="'Enter your name'"
+      [required]="true"
+      (igcChange)="handleChange($event)">
+    </igc-input>
+  `
+})
+export class MyComponent implements AfterViewInit {
+  @ViewChild('myButton') buttonRef!: ElementRef;
+
+  inputLabel = 'Name';
+
+  ngAfterViewInit() {
+    // Access the native element directly if needed
+    const button = this.buttonRef.nativeElement;
+  }
+
+  handleClick(event: PointerEvent) {
+    console.log('Button clicked');
+  }
+
+  handleChange(event: CustomEvent) {
+    console.log('Input changed', event.detail);
+  }
+}
+```
+
+## Working with Complex Properties
+
+Use Angular property binding `[property]` to pass objects and arrays:
+
+```typescript
+@Component({
+  selector: 'app-my-component',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <igc-combo [data]="items"></igc-combo>
+  `
+})
+export class MyComponent {
+  items = [
+    { value: 1, label: 'Item 1' },
+    { value: 2, label: 'Item 2' },
+  ];
+}
+```
+
+## Key Considerations
+
+| Concern | Details |
+|---------|---------|
+| **CUSTOM_ELEMENTS_SCHEMA** | Required in every module or standalone component that uses `igc-*` tags |
+| **Event binding** | Use Angular syntax: `(igcChange)="handler($event)"` |
+| **Property binding** | Use `[property]="value"` for reactive data and complex types |
+| **Form integration** | Web components work with Angular Forms via `ngModel` or reactive form controls |
+
+## TypeScript Support
+
+The `igniteui-webcomponents` package automatically registers all component types in `HTMLElementTagNameMap`. DOM queries are fully typed:
+
+```typescript
+import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents';
+
+defineComponents(IgcButtonComponent);
+
+// Automatically typed as IgcButtonComponent | null
+const button = document.querySelector('igc-button');
+```
+
+## Common Issues
+
+### Angular template error: "Unknown element"
+
+Add `CUSTOM_ELEMENTS_SCHEMA` to the component's `schemas` array (standalone) or to the module (NgModule).
+
+### Events not firing
+
+Use Angular's event binding syntax `(igcChange)="handler($event)"` — not `(change)`. Ignite UI components emit prefixed custom events (e.g., `igcInput`, `igcChange`).
+
+### No styles applied
+
+Ensure you import a theme CSS file in `main.ts` before bootstrapping.
+
+### Properties not updating
+
+Use `[property]="value"` binding for complex or reactive data. Attribute strings (e.g. `label="Name"`) work for primitive values only.
+
+---
+
+## Next Steps
+
+- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/) — import only the components you use
+- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors
+- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference

package/skills/igniteui-wc-integrate-with-framework/references/react.md

@@ -0,0 +1,116 @@
+# Integrating Ignite UI Web Components — React
+
+React integration uses the **`igniteui-react`** package, which provides React-native wrappers around Ignite UI Web Components:
+
+- ✅ Native React event handling
+- ✅ Full TypeScript types and IntelliSense for all props
+- ✅ Automatic global type declarations (`HTMLElementTagNameMap`)
+- ✅ camelCase props instead of kebab-case attributes
+- ✅ Seamless complex data binding (objects and arrays work as props)
+- ✅ React DevTools integration
+
+Components use the `Igr` prefix (e.g. `IgrButton`, `IgrInput`, `IgrCombo`).
+
+### Installation
+
+```bash
+npm install igniteui-react
+```
+
+### Setup
+
+Import a theme in your application entry point (`src/main.tsx` or `src/index.tsx`):
+
+```typescript
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+```
+
+### Available Themes
+
+| Theme     | Light                                                  | Dark                                                  |
+|-----------|--------------------------------------------------------|-------------------------------------------------------|
+| Bootstrap | `igniteui-webcomponents/themes/light/bootstrap.css`    | `igniteui-webcomponents/themes/dark/bootstrap.css`    |
+| Material  | `igniteui-webcomponents/themes/light/material.css`     | `igniteui-webcomponents/themes/dark/material.css`     |
+| Fluent    | `igniteui-webcomponents/themes/light/fluent.css`       | `igniteui-webcomponents/themes/dark/fluent.css`       |
+| Indigo    | `igniteui-webcomponents/themes/light/indigo.css`       | `igniteui-webcomponents/themes/dark/indigo.css`       |
+
+### Usage
+
+```tsx
+import { IgrButton, IgrInput } from 'igniteui-react';
+
+function MyComponent() {
+  // onClick is a standard React mouse event
+  const handleClick = (e: React.MouseEvent) => console.log('Clicked');
+
+  // onChange receives the component's change event
+  const handleChange = (e: CustomEvent) => console.log(`Changed: ${e.detail}`);
+
+  return (
+    <div>
+      <IgrButton variant="contained" onClick={handleClick}>
+        Click me
+      </IgrButton>
+
+      <IgrInput
+        label="Name"
+        placeholder="Enter your name"
+        required
+        onChange={handleChange}
+      />
+    </div>
+  );
+}
+```
+
+### Complex Data
+
+Objects and arrays bind directly as props with `igniteui-react`:
+
+```tsx
+import { IgrCombo } from 'igniteui-react';
+
+function MyComponent() {
+  const items = [
+    { value: 1, label: 'Item 1' },
+    { value: 2, label: 'Item 2' },
+  ];
+
+  return <IgrCombo data={items} />;
+}
+```
+
+### TypeScript Support
+
+The `igniteui-react` package ships with full type definitions. No extra configuration needed:
+
+```tsx
+import { IgrButton } from 'igniteui-react';
+
+// TypeScript knows about all IgrButton props
+<IgrButton variant="contained">Click</IgrButton>
+
+// DOM queries are also typed automatically (via igniteui-webcomponents peer)
+const button = document.querySelector('igc-button'); // IgcButtonComponent | null
+```
+
+---
+
+## Common Issues
+
+### Components not rendering
+
+The `igniteui-react` package registers components automatically on import. Ensure the package is installed and components are imported before the component tree renders.
+
+### No styles applied
+
+Ensure you import a theme CSS file in your entry point. Without it, components render unstyled.
+
+---
+
+## Next Steps
+
+- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/) — import only the components you use
+- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors
+- [igniteui-react on npm](https://www.npmjs.com/package/igniteui-react) — React wrapper documentation
+- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference

package/skills/igniteui-wc-integrate-with-framework/references/vanilla-js.md

@@ -0,0 +1,118 @@
+# Integrating Ignite UI Web Components — Vanilla JavaScript / HTML
+
+## Installation
+
+```bash
+npm install igniteui-webcomponents
+```
+
+## Setup
+
+In your main JavaScript/TypeScript entry file, import a theme and register the components you need:
+
+```typescript
+// 1. Import a theme (required for correct styling)
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+
+// 2. Import and register specific components (recommended)
+import { defineComponents, IgcButtonComponent, IgcInputComponent } from 'igniteui-webcomponents';
+
+defineComponents(IgcButtonComponent, IgcInputComponent);
+```
+
+To register all components at once (increases bundle size):
+
+```typescript
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import { defineAllComponents } from 'igniteui-webcomponents';
+
+defineAllComponents();
+```
+
+## Available Themes
+
+| Theme     | Light                                                  | Dark                                                  |
+|-----------|--------------------------------------------------------|-------------------------------------------------------|
+| Bootstrap | `igniteui-webcomponents/themes/light/bootstrap.css`    | `igniteui-webcomponents/themes/dark/bootstrap.css`    |
+| Material  | `igniteui-webcomponents/themes/light/material.css`     | `igniteui-webcomponents/themes/dark/material.css`     |
+| Fluent    | `igniteui-webcomponents/themes/light/fluent.css`       | `igniteui-webcomponents/themes/dark/fluent.css`       |
+| Indigo    | `igniteui-webcomponents/themes/light/indigo.css`       | `igniteui-webcomponents/themes/dark/indigo.css`       |
+
+## Usage in HTML
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module" src="./main.js"></script>
+</head>
+<body>
+  <igc-button variant="contained">Click me</igc-button>
+  <igc-input label="Name" placeholder="Enter your name"></igc-input>
+</body>
+</html>
+```
+
+## TypeScript Support
+
+The `igniteui-webcomponents` package automatically provides global type declarations for all components via `HTMLElementTagNameMap`. DOM queries are fully typed without any extra configuration:
+
+```typescript
+import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents';
+
+defineComponents(IgcButtonComponent);
+
+// Automatically typed as IgcButtonComponent | null
+const button = document.querySelector('igc-button');
+button?.setAttribute('variant', 'outlined');
+```
+
+You can also import component types directly for annotations:
+
+```typescript
+import type { IgcButtonComponent } from 'igniteui-webcomponents';
+
+const button = document.querySelector('igc-button') as IgcButtonComponent;
+```
+
+## Working with Complex Properties
+
+Attributes only accept strings. For objects and arrays, set properties via JavaScript:
+
+```typescript
+// ❌ Wrong — attributes only accept strings
+// <igc-combo data="[{...}]"></igc-combo>
+
+// ✅ Correct — set via DOM property
+const combo = document.querySelector('igc-combo');
+combo.data = [
+  { value: 1, label: 'Item 1' },
+  { value: 2, label: 'Item 2' }
+];
+```
+
+## Common Issues
+
+### Components not rendering
+
+Register components **before** they appear in the DOM:
+
+```typescript
+// ❌ Wrong
+document.body.innerHTML = '<igc-button>Click</igc-button>';
+defineComponents(IgcButtonComponent);
+
+// ✅ Correct
+defineComponents(IgcButtonComponent);
+document.body.innerHTML = '<igc-button>Click</igc-button>';
+```
+
+### No styles applied
+
+Ensure you import a theme CSS file in your entry point. Without it, components render unstyled.
+
+## Next Steps
+
+- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/SKILL.md) — import only the components you use
+- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors
+- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference