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/EVENT-HANDLING.md

@@ -0,0 +1,70 @@
+# Event Handling
+
+## How Events Work
+
+Ignite UI React wrappers map web component custom events to React-style `onXxx` callback props. The event name is converted from the web component event name to a camelCase `on`-prefixed prop.
+
+```tsx
+import { IgrButton, IgrInput, IgrCheckbox } from 'igniteui-react';
+
+function MyForm() {
+  const handleClick = (event: CustomEvent) => {
+    console.log('Button clicked');
+  };
+
+  const handleInput = (event: CustomEvent) => {
+    // event.target is the underlying web component element (e.g., igc-input)
+    console.log('Input value:', (event.target as any).value);
+  };
+
+  const handleChange = (event: CustomEvent) => {
+    console.log('Checkbox changed:', event.detail);
+  };
+
+  return (
+    <>
+      <IgrButton onClick={handleClick}>
+        <span>Submit</span>
+      </IgrButton>
+      <IgrInput label="Name" onInput={handleInput} />
+      <IgrCheckbox onChange={handleChange}>Accept terms</IgrCheckbox>
+    </>
+  );
+}
+```
+
+## Common Event Props
+
+| Component | Event Prop | Fires When |
+|---|---|---|
+| `IgrButton` | `onClick` | Button is clicked |
+| `IgrInput` | `onInput` | Value changes (each keystroke) |
+| `IgrInput` | `onChange` | Value committed (blur / Enter) |
+| `IgrCheckbox` | `onChange` | Checked state changes |
+| `IgrSwitch` | `onChange` | Toggle state changes |
+| `IgrSelect` | `onChange` | Selection changes |
+| `IgrCombo` | `onChange` | Selection changes |
+| `IgrSlider` | `onInput` | Slider value changes (live) |
+| `IgrSlider` | `onChange` | Slider value committed |
+| `IgrDialog` | `onClosing` | Dialog is about to close |
+| `IgrDialog` | `onClosed` | Dialog has closed |
+| `IgrTabs` | `onChange` | Active tab changes |
+| `IgrCalendar` | `onChange` | Selected date changes |
+| `IgrDatepicker` | `onChange` | Selected date changes |
+
+## TypeScript Event Types
+
+When using TypeScript, event handlers receive the underlying `CustomEvent`:
+
+```tsx
+import { IgrInput } from 'igniteui-react';
+
+function SearchBar() {
+  const handleInput = (e: CustomEvent) => {
+    const value = (e.target as HTMLInputElement).value;
+    console.log('Search:', value);
+  };
+
+  return <IgrInput label="Search" onInput={handleInput} />;
+}
+```

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

@@ -0,0 +1,139 @@
+# Installation & Setup
+
+## Install the Package
+
+```bash
+# Core UI components (MIT)
+npm install igniteui-react
+
+# If you need the lightweight grid (MIT)
+# Requires BOTH packages - igniteui-react and igniteui-grid-lite
+npm install igniteui-react igniteui-grid-lite
+
+# If you need advanced grids (commercial)
+npm install igniteui-react-grids
+
+# If you need charts (commercial)
+npm install igniteui-react-charts
+
+# If you need gauges (commercial)
+npm install igniteui-react-gauges
+
+# If you need maps (commercial)
+npm install igniteui-react-maps
+```
+
+## Peer Dependencies
+
+`igniteui-react` requires `react` and `react-dom` (v18+ or v19+). These are typically already in your project:
+
+```bash
+npm install react react-dom
+```
+
+## Import a Theme (REQUIRED)
+
+> **CRITICAL:** Components will render without styles, with broken icons and missing visuals if the theme CSS is not imported. **Always import the theme CSS before using any Ignite UI component.**
+
+Import one theme CSS file in your entry point (`main.tsx`, `index.tsx`, or `App.tsx`). The theme CSS must be imported **in every file that uses Ignite UI components** if your framework does not have a single global entry point (e.g., Next.js — see below).
+
+```tsx
+// main.tsx or index.tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+```
+
+Available themes:
+
+| Import | Theme |
+|---|---|
+| `igniteui-webcomponents/themes/light/bootstrap.css` | Bootstrap Light |
+| `igniteui-webcomponents/themes/dark/bootstrap.css` | Bootstrap Dark |
+| `igniteui-webcomponents/themes/light/material.css` | Material Light |
+| `igniteui-webcomponents/themes/dark/material.css` | Material Dark |
+| `igniteui-webcomponents/themes/light/fluent.css` | Fluent Light |
+| `igniteui-webcomponents/themes/dark/fluent.css` | Fluent Dark |
+| `igniteui-webcomponents/themes/light/indigo.css` | Indigo Light |
+| `igniteui-webcomponents/themes/dark/indigo.css` | Indigo Dark |
+
+Grid theme CSS files follow the same pattern under `igniteui-react-grids/grids/themes/`.
+
+**For grids**, you **must also** import the grid theme CSS. Without it, the grid will be missing styles and icons will show as placeholders:
+
+```tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+```
+
+## Next.js Setup
+
+In Next.js, there is no single `main.tsx` entry point. Import the theme CSS **in each client component file** that uses Ignite UI components, or in a shared layout component:
+
+```tsx
+// app/components/DataTable.tsx
+'use client';
+
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+
+import { IgrGrid, IgrColumn, IgrPaginator } from 'igniteui-react-grids';
+
+export default function DataTable({ data }: { data: any[] }) {
+  return (
+    <IgrGrid data={data} autoGenerate={false}>
+      <IgrColumn field="name" header="Name" />
+      <IgrColumn field="email" header="Email" />
+      <IgrPaginator perPage={10} />
+    </IgrGrid>
+  );
+}
+```
+
+Alternatively, import themes once in a root layout:
+
+```tsx
+// app/layout.tsx
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import 'igniteui-react-grids/grids/themes/light/bootstrap.css';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Minimal App Example (Vite / CRA)
+
+```tsx
+// main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import 'igniteui-webcomponents/themes/light/bootstrap.css';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+```tsx
+// App.tsx
+import { IgrButton, IgrInput } from 'igniteui-react';
+
+function App() {
+  return (
+    <div>
+      <IgrInput label="Name" />
+      <IgrButton><span>Submit</span></IgrButton>
+    </div>
+  );
+}
+
+export default App;
+```
+
+> **No `defineComponents()` needed.** React wrappers auto-register. See [CHARTS-GRIDS.md](./reference/CHARTS-GRIDS.md) for exceptions (charts, gauges, maps).

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

@@ -0,0 +1,187 @@
+# JSX Usage Patterns
+
+## Props vs HTML Attributes
+
+Ignite UI React components accept props just like any React component. Use JSX expression syntax for dynamic values:
+
+```tsx
+// ✅ Correct — JSX expression
+<IgrInput label="Email" placeholder="you@example.com" type="email" />
+<IgrSlider value={50} min={0} max={100} />
+<IgrButton disabled={isLoading}>Submit</IgrButton>
+
+// ❌ Wrong — string for numeric/boolean values
+<IgrSlider value="50" />
+```
+
+## Children vs Slots
+
+Ignite UI components use the web component **slot** mechanism under the hood. In JSX, pass children to the default slot and use the `slot` attribute to target named slots:
+
+```tsx
+<IgrButton>
+  {/* Default slot — button label */}
+  <span>Click Me</span>
+</IgrButton>
+
+<IgrCard>
+  <IgrCardHeader>
+    <h3 slot="title">Card Title</h3>
+    <p slot="subtitle">Card subtitle</p>
+  </IgrCardHeader>
+  <IgrCardContent>
+    <p>Default slot content inside the card body.</p>
+  </IgrCardContent>
+  <IgrCardActions>
+    <IgrButton slot="start">Cancel</IgrButton>
+    <IgrButton slot="end">Confirm</IgrButton>
+  </IgrCardActions>
+</IgrCard>
+
+<IgrNavDrawerItem>
+  <span slot="icon">📊</span>
+  <span slot="content">Dashboard</span>
+</IgrNavDrawerItem>
+```
+
+> **Tip:** Check the component documentation for available slot names. Common slots include `start`, `end`, `prefix`, `suffix`, `header`, `content`, `icon`, `title`, `subtitle`.
+
+## Render Props (Grids & Complex Components)
+
+Some components like the Data Grid support **render props** for custom cell rendering:
+
+```tsx
+import { IgrGrid, IgrColumn } from 'igniteui-react-grids';
+
+function UserGrid({ users }: { users: User[] }) {
+  return (
+    <IgrGrid data={users} autoGenerate={false}>
+      <IgrColumn field="name" header="Name" />
+      <IgrColumn field="email" header="Email" />
+      <IgrColumn
+        field="status"
+        header="Status"
+        bodyTemplate={(ctx) => (
+          <IgrBadge>{ctx.cell.value}</IgrBadge>
+        )}
+      />
+    </IgrGrid>
+  );
+}
+```
+
+## IgrTabs — Content Panels vs Navigation
+
+`IgrTabs` supports two distinct usage patterns. Choosing the wrong one is a common mistake.
+
+### Pattern 1: Tabs with Content Panels (inline content)
+
+Use `IgrTab` with inline content when the tabbed content is rendered inline — no routing involved. The tab label can be set via a `label` prop or via a `slot="label"` element:
+
+```tsx
+import { IgrTabs, IgrTab } from 'igniteui-react';
+
+// Simple text labels using the label prop
+function SettingsPage() {
+  return (
+    <IgrTabs>
+      <IgrTab label="Profile" selected>
+        <p>Profile settings content here</p>
+      </IgrTab>
+      <IgrTab label="Security">
+        <p>Security settings content here</p>
+      </IgrTab>
+      <IgrTab label="Notifications">
+        <p>Notification preferences content here</p>
+      </IgrTab>
+    </IgrTabs>
+  );
+}
+```
+
+**Alternative: Using slot="label" for complex headers (e.g., with icons):**
+
+```tsx
+import { IgrTabs, IgrTab, IgrIcon } from 'igniteui-react';
+
+function SettingsPage() {
+  return (
+    <IgrTabs>
+      <IgrTab selected>
+        <span slot="label">
+          <IgrIcon name="home" collection="material" />
+          Profile
+        </span>
+        <p>Profile settings content here</p>
+      </IgrTab>
+      <IgrTab>
+        <span slot="label">
+          <IgrIcon name="security" collection="material" />
+          Security
+        </span>
+        <p>Security settings content here</p>
+      </IgrTab>
+      <IgrTab>
+        <span slot="label">
+          <IgrIcon name="notifications" collection="material" />
+          Notifications
+        </span>
+        <p>Notification preferences content here</p>
+      </IgrTab>
+    </IgrTabs>
+  );
+}
+```
+
+### Pattern 2: Tabs as Navigation (with React Router — NO inline content)
+
+> **⚠️ CRITICAL:** When using `IgrTabs` for navigation with React Router (or any router), **do NOT include inline content in `IgrTab`**. Only render tab labels (via `label` prop or `slot="label"`), and let the router's `<Outlet />` handle the content below the tabs.
+
+```tsx
+import { IgrTabs, IgrTab } from 'igniteui-react';
+import { useNavigate, useLocation, Outlet } from 'react-router-dom';
+
+const tabs = [
+  { path: '/dashboard', label: 'Dashboard' },
+  { path: '/orders', label: 'Orders' },
+  { path: '/customers', label: 'Customers' },
+];
+
+function MainLayout() {
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  const handleTabChange = (e: CustomEvent) => {
+    const selectedIndex = (e.target as any).selectedIndex;
+    if (selectedIndex !== undefined && tabs[selectedIndex]) {
+      navigate(tabs[selectedIndex].path);
+    }
+  };
+
+  return (
+    <div>
+      {/* Tabs for navigation — label prop only, no inline content */}
+      <IgrTabs onChange={handleTabChange}>
+        {tabs.map((tab) => (
+          <IgrTab
+            key={tab.path}
+            label={tab.label}
+            selected={location.pathname === tab.path}
+          />
+        ))}
+      </IgrTabs>
+
+      {/* Router outlet renders the routed view */}
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+```
+
+**Key rules for tabs-as-navigation:**
+- ✅ Use only `IgrTab` with label prop or `slot="label"` — no inline content
+- ✅ Sync the active tab to the current route using the `selected` prop
+- ✅ Handle `onChange` to call `navigate()` for route changes
+- ✅ Use `<Outlet />` (or the equivalent in your router) for content rendering

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

@@ -0,0 +1,229 @@
+# Refs & Forms
+
+## Refs & Imperative API
+
+Use `useRef` to access the underlying web component element and call imperative methods (e.g., showing/hiding a dialog, focusing an input).
+Components from `igniteui-react`, `igniteui-react-grids` and `igniteui-react-dockmanager` are React Function Components forward the native element to `useRef` and expose alias with the same name for accessing the custom element API:
+
+```tsx
+import { useRef } from 'react';
+import { IgrDialog, IgrButton, IgrInput } from 'igniteui-react';
+
+function MyPage() {
+  const dialogRef = useRef<IgrDialog>(null);
+  const inputRef = useRef<IgrInput>(null);
+
+  const openDialog = () => {
+    // Access the underlying web component and call its methods
+    dialogRef.current?.show();
+  };
+
+  const focusInput = () => {
+    inputRef.current?.focus();
+  };
+
+  return (
+    <>
+      <IgrButton onClick={openDialog}>
+        <span>Open Dialog</span>
+      </IgrButton>
+
+      <IgrDialog ref={dialogRef} title="Confirmation">
+        <p>Are you sure?</p>
+        <IgrButton slot="footer" onClick={() => dialogRef.current?.hide()}>
+          <span>Close</span>
+        </IgrButton>
+      </IgrDialog>
+
+      <IgrButton onClick={focusInput}>
+        <span>Focus Input</span>
+      </IgrButton>
+      <IgrInput ref={inputRef} label="Name" />
+    </>
+  );
+}
+```
+
+> **Tip:** The ref gives you direct access to the web component's DOM element. You can call any method documented in the web component API.
+
+
+## Uncontrolled Components
+
+`igniteui-react` Inputs integrate with the native form handling through Element internals, allowing to take advantage of the native state management adn validation to create intuitive, straight-forward forms:
+
+```tsx
+import { useRef } from 'react';
+import { IgrInput, IgrButton } from 'igniteui-react';
+
+function SimpleForm() {
+  const nameRef = useRef<IgrInput>(null);
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    // e.preventDefault(); // optionally prevent default submit form custom handling
+    const formData = new FormData(e.target);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <IgrInput name="name" label="Name" required={true} />
+      <IgrInput name="description" label="description" minLength={0}>
+      <IgrButton type="submit">
+        <span>Submit</span>
+      </IgrButton>
+    </form>
+  );
+}
+```
+
+## Controlled Components with `useState`
+
+Wire up Ignite UI form components with React state for controlled behavior:
+
+```tsx
+import { useState } from 'react';
+import { IgrInput, IgrCheckbox, IgrSelect, IgrSelectItem } from 'igniteui-react';
+
+function ProfileForm() {
+  const [name, setName] = useState('');
+  const [newsletter, setNewsletter] = useState(false);
+  const [role, setRole] = useState('user');
+
+  return (
+    <form>
+      <IgrInput
+        label="Name"
+        value={name}
+        onInput={(e: CustomEvent<string>) => setName(e.detail) }
+      />
+
+      <IgrCheckbox
+        checked={newsletter}
+        onChange={(e: CustomEvent<IgcCheckboxChangeEventArgs>) =>
+          setNewsletter(e.detail.checked)
+        }
+      >
+        Subscribe to newsletter
+      </IgrCheckbox>
+
+      <IgrSelect
+        label="Role"
+        value={role}
+        onChange={(e: CustomEvent<IgcSelectItemComponent>) =>
+          setRole(e.detail.value)
+        }
+      >
+        <IgrSelectItem value="user">User</IgrSelectItem>
+        <IgrSelectItem value="admin">Admin</IgrSelectItem>
+        <IgrSelectItem value="editor">Editor</IgrSelectItem>
+      </IgrSelect>
+    </form>
+  );
+}
+```
+
+## React Hook Form Integration
+
+Ignite UI components are form-associated web components. You can integrate them with React Hook Form using `Controller`:
+
+```tsx
+import { useForm, Controller } from 'react-hook-form';
+import { IgrInput, IgrCheckbox, IgrButton } from 'igniteui-react';
+
+interface FormData {
+  email: string;
+  acceptTerms: boolean;
+}
+
+function SignUpForm() {
+  const { control, handleSubmit, formState: { errors } } = useForm<FormData>();
+
+  const onSubmit = (data: FormData) => {
+    console.log(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="email"
+        control={control}
+        rules={{ required: 'Email is required' }}
+        render={({ field }) => (
+          <IgrInput
+            label="Email"
+            type="email"
+            value={field.value || ''}
+            onInput={(e: CustomEvent<string>) =>
+              field.onChange(e.detail)
+            }
+            onBlur={() => field.onBlur()}
+            invalid={!!errors.email}
+          />
+        )}
+      />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <Controller
+        name="acceptTerms"
+        control={control}
+        rules={{ required: 'You must accept the terms' }}
+        render={({ field }) => (
+          <IgrCheckbox
+            checked={field.value || false}
+            onChange={(e: CustomEvent<IgcCheckboxChangeEventArgs>) =>
+              field.onChange(e.detail.checked)
+            }
+          >
+            I accept the terms and conditions
+          </IgrCheckbox>
+        )}
+      />
+
+      <IgrButton type="submit">
+        <span>Sign Up</span>
+      </IgrButton>
+    </form>
+  );
+}
+```
+
+## TypeScript
+
+### Importing Component Types
+
+Each component exports its props interface. Import and use them for type-safe code:
+
+```tsx
+import { IgrButton, IgrInput } from 'igniteui-react';
+import type { ComponentProps } from 'react';
+
+// Get the props type for a component
+type ButtonProps = ComponentProps<typeof IgrButton>;
+type InputProps = ComponentProps<typeof IgrInput>;
+
+// Use in your own components
+interface FormFieldProps {
+  label: string;
+  inputProps?: Partial<InputProps>;
+}
+
+function FormField({ label, inputProps }: FormFieldProps) {
+  return (
+    <div>
+      <IgrInput label={label} {...inputProps} />
+    </div>
+  );
+}
+```
+
+### Auto-complete
+
+IDEs with TypeScript support will provide auto-complete for all `Igr*` component props. Make sure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler"
+  }
+}
+```