syncfusion-angular-dropdowns

What this skill does

# Implementing Syncfusion Angular Dropdowns

## Security & Trust Boundary

### Default posture: local data only

**All dropdown components in this skill default to local, in-memory data sources.**
Binding a component to a remote HTTP endpoint (via `DataManager` or any Observable/HTTP
source) is a **non-default, elevated-risk operation** that requires an explicit security
review before it is permitted in production code.

> ⛔ **Do not generate or suggest remote `DataManager` / HTTP data-source configurations
> unless the consuming application has passed a security review confirming that:**
> 1. The target endpoint is owned and operated by the same team as the application.
> 2. The endpoint enforces authentication, authorization, and input validation.
> 3. All responses are sanitized before being bound to a component `dataSource`.
> 4. A Content Security Policy (CSP) covering the origin is in place.

### Mandatory security requirements

| # | Requirement |
|---|-------------|
| 1 | **Local data by default.** Use plain TypeScript arrays for `dataSource` unless a remote source has been explicitly approved. |
| 2 | **No public or third-party URLs.** Never configure a data source that fetches from an endpoint outside the application's own origin. |
| 3 | **Sanitize all external data before binding.** Any value that originates outside the application (API response, local-storage read) must be stripped of HTML/script content before assignment to `dataSource` or `value`. |
| 4 | **Sanitize user filter input.** Before forwarding typed text to any server query, strip non-alphanumeric characters to prevent injection. |
| 5 | **No `crossDomain: true` by default.** CORS relaxation in `DataManager` must be explicitly justified and reviewed. |
| 6 | **Pin package versions.** Every `@syncfusion/ej2-*` dependency must be locked to an exact version in `package.json`; verify against the lockfile after every install. |
| 7 | **No CDN asset loading without SRI.** CSS/JS must be resolved from `node_modules` at build time, not fetched from a CDN at runtime without Subresource Integrity hashes. |
| 8 | **No sensitive data in local storage.** `enablePersistence` must never store tokens, credentials, or PII; sanitize any value read back before use. |

---

## AutoComplete

A text input component that provides matching suggestions as the user types. Supports free-form input, remote data, filtering strategies, grouping, virtual scrolling, and full Angular forms integration.

### Component Overview & Architecture

The **AutoComplete** is a text input component that provides matching suggestions as the user types. It is designed for:

1. **Type-ahead suggestions** — shows matching items from a data source as the user types
2. **Free-form input** — users can type any value, not restricted to the list
3. **Search/filter** — multiple filter strategies (StartsWith, Contains, EndsWith)
4. **Autofill** — automatically completes the first matched suggestion in the input
5. **Grouped suggestions** — categorize items by a `groupBy` field
6. **Virtual scrolling** — efficiently handles thousands of items
7. **Template customization** — item, group, header, footer, and empty-state templates

### Key Characteristics

| Aspect | Details |
|--------|---------|
| **Selection** | Single item; user can also type any free-form value |
| **Data Sources** | Local arrays, remote DataManager, OData, Web API, Observable (async pipe) |
| **Filtering** | Built-in filtering: `StartsWith`, `EndsWith`, `Contains` |
| **Autofill** | Completes the first match inline as the user types |
| **Performance** | Virtual scrolling for large datasets (1,000+ items) |
| **Forms** | Template-driven (`ngModel`) and reactive (`FormControl`) form integration |
| **Accessibility** | WCAG 2.2 compliant, full keyboard navigation, ARIA attributes |
| **Customization** | Item, group, header, footer, noRecords, actionFailure templates; CSS theming |

---

### Documentation Navigation Guide

#### 📄 Getting Started
**Read:** [references/autocomplete-getting-started.md](references/autocomplete-getting-started.md)
- Install `@syncfusion/ej2-angular-dropdowns` package
- Set up Angular 21+ project with standalone components
- Import `AutoCompleteModule` and required CSS themes
- Create your first AutoComplete with basic data binding
- Configure popup height, width, and placeholder
- Enable two-way binding with `[(value)]`

#### 📄 Data Binding
**Read:** [references/autocomplete-data-binding.md](references/autocomplete-data-binding.md)
- Bind to local arrays (strings, numbers, objects, complex objects)
- Map `value`, `text`, and `iconCss` fields via `fields` property
- Remote data using DataManager with OData, Web API adapters
- Async pipe pattern for RxJS Observables
- Object binding with `allowObjectBinding`
- Preselecting values using the `value` property

#### 📄 Filtering & Search
**Read:** [references/autocomplete-filtering-and-search.md](references/autocomplete-filtering-and-search.md)
- Configure `filterType` (StartsWith, Contains, EndsWith)
- Limit suggestion count with `suggestionCount`
- Minimum character threshold with `minLength`
- Case-sensitive filtering with `ignoreCase`
- Diacritics/accent-insensitive filtering with `ignoreAccent`
- Debounce delay to optimize remote filtering with `debounceDelay`
- Custom filtering via the `filtering` event with `updateData`

#### 📄 Grouping & Templates
**Read:** [references/autocomplete-grouping-and-templates.md](references/autocomplete-grouping-and-templates.md)
- Group suggestions by category using `fields.groupBy`
- Item templates for custom rendering
- Group header templates (inline and fixed)
- Header and footer templates for the popup
- Empty state with `noRecordsTemplate`
- Action failure template for remote data errors

#### 📄 Feature Configuration
**Read:** [references/autocomplete-feature-configuration.md](references/autocomplete-feature-configuration.md)
- Autofill: inline suggestion completion with `autofill` property
- Highlight matched characters with `highlight` property
- Disable individual items with `fields.disabled` or `disableItem` method
- Disable entire component with `enabled` property
- Resizable popup with `allowResize`
- Virtual scrolling for large datasets with `enableVirtualization`
- Show/hide popup button with `showPopupButton`
- Show/hide clear button with `showClearButton`
- RTL support with `enableRtl`
- Sort order with `sortOrder`

#### 📄 Form Support & Validation
**Read:** [references/autocomplete-form-support-and-validation.md](references/autocomplete-form-support-and-validation.md)
- Template-driven forms using `ngModel` and `FormsModule`
- Reactive forms using `FormControl`, `FormGroup`, and `ReactiveFormsModule`
- Binding and validation patterns
- Pre-selecting values via form model

#### 📄 Accessibility & Localization
**Read:** [references/autocomplete-accessibility-and-localization.md](references/autocomplete-accessibility-and-localization.md)
- WCAG 2.2, Section 508, and ADA compliance
- Full keyboard shortcuts (Arrow keys, Tab, Enter, Escape, Alt+Down/Up)
- ARIA attributes: `aria-haspopup`, `aria-expanded`, `aria-selected`, `aria-autocomplete`
- Screen reader support and focus management
- Localization with `L10n.load()` for `noRecordsTemplate` and `actionFailureTemplate`
- RTL language support

#### 📄 Advanced Patterns & How-To
**Read:** [references/autocomplete-advanced-patterns-how-to.md](references/autocomplete-advanced-patterns-how-to.md)
- Autofill feature with the `autofill` property
- Highlight searched characters with the `highlight` property
- Multi-field custom filtering with `Predicate` (filter by both Name and Code)
- Icon support via `fields.iconCss`
- Suggestion list on focus from browser local storage
  > ⚠️ **Security note:** Local storage is accessible to any JavaScript running on the same
  > origin and is a common XSS attack surface. Never store sensitive data (tokens, PII) in
  > local storage. Sanitize any values