@igniteui/angular-templates 21.1.1491 → 21.1.1500-rc.0

package/igx-ts/projects/_base/files/__dot__claude/skills/igniteui-angular-components/references/feedback.md

@@ -0,0 +1,149 @@
+# Feedback & Overlay Components
+
+> **Part of the [`igniteui-angular-components`](../SKILL.md) skill hub.**
+> For app setup, providers, and import patterns — see [`setup.md`](./setup.md).
+
+> **AGENT INSTRUCTION:** All components in this file rely on Angular animations and the Ignite UI overlay system. Before using any of them, ensure `provideAnimations()` (or `provideAnimationsAsync()`) is present in `app.config.ts`. If it is missing, add it — these components will throw runtime errors or silently fail to animate without it.
+
+## Contents
+
+- [Dialog](#dialog)
+- [Snackbar](#snackbar)
+- [Toast](#toast)
+- [Banner](#banner)
+- [Key Rules](#key-rules)
+
+## Dialog
+
+> **Docs:** [Dialog Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/dialog)
+
+```typescript
+import { IgxDialogComponent, IgxDialogTitleDirective, IgxDialogActionsDirective } from 'igniteui-angular/dialog';
+import { IgxButtonDirective } from 'igniteui-angular/directives';
+```
+
+```html
+<igx-dialog
+  #confirmDialog
+  [isModal]="true"
+  [closeOnEscape]="true"
+  [closeOnOutsideSelect]="false"
+  title="Confirm Delete"
+  (closed)="onDialogClosed()">
+  <igx-dialog-title>Confirm Delete</igx-dialog-title>
+  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
+  <div igxDialogActions>
+    <button igxButton="flat" (click)="confirmDialog.close()">Cancel</button>
+    <button igxButton="contained" (click)="deleteItem(); confirmDialog.close()">Delete</button>
+  </div>
+</igx-dialog>
+
+<button igxButton="contained" (click)="confirmDialog.open()">Delete Item</button>
+```
+
+Programmatic control:
+
+```typescript
+dialog = viewChild.required<IgxDialogComponent>('confirmDialog');
+
+open() { this.dialog().open(); }
+close() { this.dialog().close(); }
+```
+
+Events: `(opening)`, `(opened)`, `(closing)`, `(closed)`, `(leftButtonSelect)`, `(rightButtonSelect)`.
+
+## Snackbar
+
+> **Docs:** [Snackbar Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/snackbar)
+
+```typescript
+import { IgxSnackbarComponent, IgxSnackbarActionDirective } from 'igniteui-angular/snackbar';
+import { IgxButtonDirective } from 'igniteui-angular/directives';
+```
+
+```html
+<igx-snackbar
+  #snackbar
+  [displayTime]="3000"
+  [autoHide]="true"
+  (animationDone)="onSnackbarDone()">
+  Item saved successfully
+  <button igxButton="flat" igxSnackbarAction (click)="undo()">UNDO</button>
+</igx-snackbar>
+```
+
+Trigger in TypeScript:
+
+```typescript
+snackbar = viewChild.required<IgxSnackbarComponent>('snackbar');
+
+save() {
+  this.dataService.save(this.item);
+  this.snackbar().open('Item saved');  // optional: pass message text
+}
+```
+
+## Toast
+
+> **Docs:** [Toast Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/toast)
+
+```typescript
+import { IgxToastComponent } from 'igniteui-angular/toast';
+```
+
+```html
+<igx-toast #toast [displayTime]="2000">Operation complete</igx-toast>
+
+<button igxButton (click)="toast.open()">Trigger Toast</button>
+```
+
+Toast vs Snackbar: Toast is non-interactive (no action button), always auto-hides. Snackbar supports an action button and can be persistent.
+
+## Banner
+
+> **Docs:** [Banner Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/banner)
+
+```typescript
+import { IgxBannerComponent, IgxBannerActionsDirective } from 'igniteui-angular/banner';
+import { IgxIconComponent } from 'igniteui-angular/icon';
+import { IgxButtonDirective } from 'igniteui-angular/directives';
+```
+
+```html
+<igx-banner #banner (closed)="onBannerClosed()">
+  <igx-icon igxBannerIcon>wifi_off</igx-icon>
+  You are offline. Some features may not be available.
+  <div igxBannerActions>
+    <button igxButton="flat" (click)="banner.dismiss()">Dismiss</button>
+    <button igxButton="flat" (click)="retry()">Retry</button>
+  </div>
+</igx-banner>
+```
+
+Trigger in TypeScript:
+
+```typescript
+banner = viewChild.required<IgxBannerComponent>('banner');
+
+showOfflineWarning() { this.banner().open(); }
+hideWarning() { this.banner().close(); }
+```
+
+Events: `(opening)`, `(opened)`, `(closing)`, `(closed)`.
+
+Banner always renders inline (not overlaid) — it pushes page content down when open.
+
+## Key Rules
+
+- **`provideAnimations()` is required** — add it to `app.config.ts` before using Dialog, Snackbar, Toast, or Banner
+- **Dialog** uses the Ignite UI overlay system — set `[isModal]="true"` for blocking modals
+- **Snackbar** vs **Toast**: Snackbar supports action buttons and can be persistent; Toast is always auto-hiding and non-interactive
+- **Banner** renders **inline** (pushes content), not as an overlay — use Dialog for blocking prompts
+
+## See Also
+
+- [`setup.md`](./setup.md) — App providers, architecture, all entry points
+- [`form-controls.md`](./form-controls.md) — Input Group, Combo, Select, Date/Time Pickers, Calendar, Checkbox, Radio, Switch, Slider
+- [`layout.md`](./layout.md) — Tabs, Stepper, Accordion, Splitter, Navigation Drawer
+- [`data-display.md`](./data-display.md) — List, Tree, Card and other display components
+- [`directives.md`](./directives.md) — Button, Ripple, Tooltip, Drag and Drop

package/igx-ts/projects/_base/files/__dot__claude/skills/igniteui-angular-components/references/form-controls.md

@@ -0,0 +1,361 @@
+# Form Controls & Reactive Forms Integration
+
+> **Part of the [`igniteui-angular-components`](../SKILL.md) skill hub.**
+> For app setup, providers, and import patterns — see [`setup.md`](./setup.md).
+
+## Contents
+
+- [Input Group](#input-group)
+- [Combo (Multi-Select Dropdown)](#combo-multi-select-dropdown)
+- [Simple Combo (Single-Select)](#simple-combo-single-select)
+- [Select](#select)
+- [Date Picker](#date-picker)
+- [Date Range Picker](#date-range-picker)
+- [Time Picker](#time-picker)
+- [Calendar](#calendar)
+- [Checkbox, Radio, Switch](#checkbox-radio-switch)
+- [Slider](#slider)
+- [Reactive Forms Integration](#reactive-forms-integration)
+- [Key Rules](#key-rules)
+
+## Input Group
+
+> **Docs:** [Input Group](https://www.infragistics.com/products/ignite-ui-angular/angular/components/input-group)
+
+```typescript
+import { IGX_INPUT_GROUP_DIRECTIVES } from 'igniteui-angular/input-group';
+import { IgxIconComponent } from 'igniteui-angular/icon';
+```
+
+```html
+<igx-input-group type="border">
+  <igx-prefix><igx-icon>person</igx-icon></igx-prefix>
+  <label igxLabel>Username</label>
+  <input igxInput name="username" type="text" [(ngModel)]="username" />
+  <igx-suffix><igx-icon>clear</igx-icon></igx-suffix>
+  <igx-hint>Enter your username</igx-hint>
+</igx-input-group>
+```
+
+Types: `line` (default), `border`, `box`, `search`.
+
+## Combo (Multi-Select Dropdown)
+
+> **Docs:** [Combo Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/combo)
+
+```typescript
+import { IgxComboComponent } from 'igniteui-angular/combo';
+```
+
+```html
+<igx-combo
+  [data]="cities"
+  [valueKey]="'id'"
+  [displayKey]="'name'"
+  [groupKey]="'region'"
+  placeholder="Select cities"
+  [allowCustomValues]="false"
+  [(ngModel)]="selectedCityIds">
+</igx-combo>
+```
+
+Key inputs: `[data]`, `[valueKey]`, `[displayKey]`, `[groupKey]`, `[placeholder]`, `[allowCustomValues]`, `[filterFunction]`, `[itemsMaxHeight]`, `[type]`.
+
+Events: `(opening)`, `(opened)`, `(closing)`, `(closed)`, `(selectionChanging)`, `(addition)`, `(searchInputUpdate)`.
+
+## Simple Combo (Single-Select)
+
+> **Docs:** [Combo — Single Selection](https://www.infragistics.com/products/ignite-ui-angular/angular/components/combo#single-selection)
+
+```typescript
+import { IgxSimpleComboComponent } from 'igniteui-angular/simple-combo';
+```
+
+```html
+<igx-simple-combo
+  [data]="countries"
+  [valueKey]="'code'"
+  [displayKey]="'name'"
+  placeholder="Select country"
+  [(ngModel)]="selectedCountry">
+</igx-simple-combo>
+```
+
+Same API as `igx-combo` but restricted to single selection.
+
+## Select
+
+> **Docs:** [Select Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/select)
+
+```typescript
+import { IgxSelectComponent, IgxSelectItemComponent } from 'igniteui-angular/select';
+```
+
+```html
+<igx-select [(ngModel)]="selectedRole" placeholder="Choose role">
+  @for (role of roles; track role.id) {
+    <igx-select-item [value]="role.id">{{ role.name }}</igx-select-item>
+  }
+</igx-select>
+```
+
+## Date Picker
+
+> **Docs:** [Date Picker](https://www.infragistics.com/products/ignite-ui-angular/angular/components/date-picker)
+
+```typescript
+import { IgxDatePickerComponent } from 'igniteui-angular/date-picker';
+```
+
+```html
+<igx-date-picker
+  [(ngModel)]="selectedDate"
+  [minValue]="minDate"
+  [maxValue]="maxDate"
+  [hideOutsideDays]="true"
+  [displayMonthsCount]="2">
+</igx-date-picker>
+```
+
+Implements `ControlValueAccessor` and `Validator`. Works with both reactive and template-driven forms.
+
+## Date Range Picker
+
+> **Docs:** [Date Range Picker](https://www.infragistics.com/products/ignite-ui-angular/angular/components/date-range-picker)
+
+```typescript
+import { IgxDateRangePickerComponent, IgxDateRangeStartComponent, IgxDateRangeEndComponent } from 'igniteui-angular/date-picker';
+import { IgxDateTimeEditorDirective } from 'igniteui-angular/directives';
+import { IGX_INPUT_GROUP_DIRECTIVES } from 'igniteui-angular/input-group';
+import { IgxIconComponent } from 'igniteui-angular/icon';
+import { IgxPickerToggleComponent, IgxPickerClearComponent } from 'igniteui-angular/core';
+```
+
+```html
+<igx-date-range-picker [(ngModel)]="dateRange">
+  <igx-date-range-start>
+    <input igxInput igxDateTimeEditor type="text" />
+  </igx-date-range-start>
+  <igx-date-range-end>
+    <input igxInput igxDateTimeEditor type="text" />
+  </igx-date-range-end>
+</igx-date-range-picker>
+```
+
+
+`IgxDateRangePickerComponent` is imported from `igniteui-angular/date-picker`.
+
+In the two-input configuration:
+
+- place the `input` directly inside `igx-date-range-start` and `igx-date-range-end`
+- use `igx-picker-toggle igxPrefix` for the calendar action
+- use `igx-picker-clear igxSuffix` for the clear action
+
+A plain `igx-prefix` or `igx-suffix` with an `igx-icon` is decorative only and does not trigger picker actions.
+Do not wrap the inputs in an additional `igx-input-group`.
+
+**Avoid these patterns in two-input mode:**
+
+- `<igx-prefix><igx-icon>calendar_today</igx-icon></igx-prefix>`
+
+- placing the toggle on only one input unless explicitly requested
+
+Common two-input configuration with calendar toggles:
+
+```html
+<igx-date-range-picker [(ngModel)]="dateRange">
+  <igx-date-range-start>
+    <igx-picker-toggle igxPrefix>
+      <igx-icon>calendar_today</igx-icon>
+    </igx-picker-toggle>
+    <label igxLabel>Start Date</label>
+    <input igxInput igxDateTimeEditor type="text" />
+    <igx-picker-clear igxSuffix>
+      <igx-icon>clear</igx-icon>
+    </igx-picker-clear>
+  </igx-date-range-start>
+
+  <igx-date-range-end>
+    <igx-picker-toggle igxPrefix>
+      <igx-icon>calendar_today</igx-icon>
+    </igx-picker-toggle>
+    <label igxLabel>End Date</label>
+    <input igxInput igxDateTimeEditor type="text" />
+    <igx-picker-clear igxSuffix>
+      <igx-icon>clear</igx-icon>
+    </igx-picker-clear>
+  </igx-date-range-end>
+</igx-date-range-picker>
+```
+
+## Time Picker
+
+> **Docs:** [Time Picker](https://www.infragistics.com/products/ignite-ui-angular/angular/components/time-picker)
+
+```typescript
+import { IgxTimePickerComponent } from 'igniteui-angular/time-picker';
+```
+
+```html
+<igx-time-picker
+  [(ngModel)]="selectedTime"
+  [inputFormat]="'HH:mm'"
+  [is24HourFormat]="true">
+</igx-time-picker>
+```
+
+## Calendar
+
+> **Docs:** [Calendar Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/calendar)
+
+```typescript
+import { IgxCalendarComponent } from 'igniteui-angular/calendar';
+```
+
+```html
+<igx-calendar
+  [(ngModel)]="selectedDate"
+  [selection]="'single'"
+  [hideOutsideDays]="true"
+  [weekStart]="1">
+</igx-calendar>
+```
+
+Selection modes: `'single'`, `'multi'`, `'range'`.
+
+## Checkbox, Radio, Switch
+
+> **Docs:** [Checkbox](https://www.infragistics.com/products/ignite-ui-angular/angular/components/checkbox) · [Radio Button](https://www.infragistics.com/products/ignite-ui-angular/angular/components/radio-button) · [Switch](https://www.infragistics.com/products/ignite-ui-angular/angular/components/switch)
+
+```typescript
+import { IgxCheckboxComponent } from 'igniteui-angular/checkbox';
+import { IgxRadioComponent, IgxRadioGroupDirective } from 'igniteui-angular/radio';
+import { IgxSwitchComponent } from 'igniteui-angular/switch';
+```
+
+```html
+<igx-checkbox [(ngModel)]="rememberMe">Remember me</igx-checkbox>
+
+<igx-radio-group>
+  <igx-radio name="plan" value="basic" [(ngModel)]="plan">Basic</igx-radio>
+  <igx-radio name="plan" value="pro" [(ngModel)]="plan">Pro</igx-radio>
+</igx-radio-group>
+
+<igx-switch [(ngModel)]="darkMode">Dark mode</igx-switch>
+```
+
+## Slider
+
+> **Docs:** [Slider Component](https://www.infragistics.com/products/ignite-ui-angular/angular/components/slider/slider)
+
+```typescript
+import { IgxSliderComponent, IgxSliderType } from 'igniteui-angular/slider';
+
+public sliderType = IgxSliderType;
+  public priceRange = {
+      lower: 200,
+      upper: 800
+  };
+```
+
+```html
+<!-- Single value -->
+<igx-slider [minValue]="0" [maxValue]="100" [(ngModel)]="volume"></igx-slider>
+
+<!-- Range slider -->
+<igx-slider
+  [type]="sliderType.RANGE"
+  [minValue]="0"
+  [maxValue]="100"
+  [lowerBound]="20"
+  [upperBound]="80">
+</igx-slider>
+```
+
+## Reactive Forms Integration
+
+All form controls implement `ControlValueAccessor` and work with both reactive and template-driven forms.
+
+> **Docs:** [Angular Reactive Form Validation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/angular-reactive-form-validation)
+
+```typescript
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormGroup, FormControl, Validators, ReactiveFormsModule } from '@angular/forms';
+import { IgxComboComponent } from 'igniteui-angular/combo';
+import { IGX_INPUT_GROUP_DIRECTIVES } from 'igniteui-angular/input-group';
+import { IgxDatePickerComponent } from 'igniteui-angular/date-picker';
+import { IgxSelectComponent, IgxSelectItemComponent } from 'igniteui-angular/select';
+
+@Component({
+  selector: 'app-my-form',
+  imports: [
+    ReactiveFormsModule,
+    IGX_INPUT_GROUP_DIRECTIVES,
+    IgxComboComponent,
+    IgxDatePickerComponent,
+    IgxSelectComponent,
+    IgxSelectItemComponent
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <igx-input-group>
+        <label igxLabel>Name</label>
+        <input igxInput formControlName="name" />
+        @if (form.controls.name.invalid && form.controls.name.touched) {
+          <igx-hint>Name is required</igx-hint>
+        }
+      </igx-input-group>
+
+      <igx-combo
+        [data]="skills"
+        formControlName="skills"
+        [valueKey]="'id'"
+        [displayKey]="'name'"
+        placeholder="Select skills">
+      </igx-combo>
+
+      <igx-date-picker formControlName="startDate"></igx-date-picker>
+
+      <igx-select formControlName="role" placeholder="Choose role">
+        @for (r of roles; track r.id) {
+          <igx-select-item [value]="r.id">{{ r.name }}</igx-select-item>
+        }
+      </igx-select>
+    </form>
+  `
+})
+export class MyFormComponent {
+  form = new FormGroup({
+    name: new FormControl('', Validators.required),
+    skills: new FormControl<number[]>([]),
+    startDate: new FormControl<Date | null>(null),
+    role: new FormControl<string | null>(null)
+  });
+
+  skills = [{ id: 1, name: 'Angular' }, { id: 2, name: 'TypeScript' }];
+  roles = [{ id: 'admin', name: 'Admin' }, { id: 'user', name: 'User' }];
+
+  submit() {
+    if (this.form.valid) {
+      console.log(this.form.value);
+    }
+  }
+}
+```
+
+## Key Rules
+
+- **Always check `app.config.ts` first** — add `provideAnimations()` before using Combo, Select, Date Picker, or any overlay component
+- **Import from specific entry points** — avoid the root `igniteui-angular` barrel
+- Date/Time pickers implement both `ControlValueAccessor` and `Validator` — they integrate with reactive forms natively
+- For `igx-date-range-picker` with separate start and end inputs, use this structure for both inputs: `igx-picker-toggle igxPrefix`, then `input igxInput igxDateTimeEditor`, then optional `igx-picker-clear igxSuffix`.
+- Do not use a plain `igx-prefix` / `igx-suffix` icon for calendar or clear actions.
+
+## See Also
+
+- [`setup.md`](./setup.md) — App providers, architecture, all entry points
+- [`layout.md`](./layout.md) — Tabs, Stepper, Accordion, Splitter, Navigation Drawer
+- [`data-display.md`](./data-display.md) — List, Tree, Card and other display components
+- [`feedback.md`](./feedback.md) — Dialog, Snackbar, Toast, Banner
+- [`directives.md`](./directives.md) — Button, Ripple, Tooltip, Drag and Drop