npm package: @mstechnology/ngx-autocomplete
Description: [![npm version](https://badge.fury.io/js/%40mstechnology%2Fngx-autocomplete.svg)](https://www.npmjs.com/package/@mstechnology/ngx-autocomplete) [![Angular](https://img.shields.io/badge/Angular-18+-red.svg)](https://angular.io/) [![License: MIT](https://
Author: MS Technology
Latest version: 1.0.2

# NgxAutocomplete

[![npm version](https://badge.fury.io/js/%40mstechnology%2Fngx-autocomplete.svg)](https://www.npmjs.com/package/@mstechnology/ngx-autocomplete)
[![Angular](https://img.shields.io/badge/Angular-18+-red.svg)](https://angular.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Componente de autocompletado reutilizable para Angular 18+, construido sobre Angular Material. Diseñado para integrarse perfectamente con formularios reactivos.

## ✨ Características

- 🎯 **Integración con Reactive Forms** - Implementa `ControlValueAccessor` para uso directo con `formControlName`
- 🔍 **Filtrado en tiempo real** - Búsqueda case-insensitive mientras el usuario escribe
- 📦 **Standalone Component** - Sin necesidad de módulos adicionales
- 🎨 **Personalizable** - Acepta clases CSS para estilizado flexible
- ⚡ **Signals** - Construido con Angular Signals para máximo rendimiento
- 🧹 **Botón de limpiar** - Incluye botón para resetear el campo

## 📋 Requisitos

| Dependencia | Versión |
|-------------|---------|
| Angular | >= 18.0.0 |
| Angular Material | >= 18.0.0 |
| Angular CDK | >= 18.0.0 |

## 📦 Instalación
```bash
npm install @mstechnology/ngx-autocomplete
```

Asegúrate de tener Angular Material configurado en tu proyecto:
```bash
ng add @angular/material
```

## 🚀 Uso Básico

### 1. Importar el componente
```typescript
import { NgxAutocomplete } from '@mstechnology/ngx-autocomplete';

@Component({
  selector: 'app-mi-componente',
  standalone: true,
  imports: [NgxAutocomplete, ReactiveFormsModule],
  templateUrl: './mi-componente.html'
})
export class MiComponente { }
```

### 2. Usar en el template
```html
<form [formGroup]="miFormulario">
  <lib-ngx-autocomplete
    [data]="usuarios"
    labelKey="nombre"
    valueKey="id"
    label="Seleccionar usuario"
    class="w-full"
    formControlName="usuarioId"
    (itemSelected)="onUsuarioSeleccionado($event)">
  </lib-ngx-autocomplete>
</form>
```

### 3. Configurar en el componente
```typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup } from '@angular/forms';

@Component({ ... })
export class MiComponente {
  miFormulario: FormGroup;
  
  usuarios = [
    { id: 1, nombre: 'Juan Pérez', email: 'juan@email.com' },
    { id: 2, nombre: 'María García', email: 'maria@email.com' },
    { id: 3, nombre: 'Carlos López', email: 'carlos@email.com' }
  ];

  constructor(private fb: FormBuilder) {
    this.miFormulario = this.fb.group({
      usuarioId: [null]
    });
  }

  onUsuarioSeleccionado(usuario: any): void {
    console.log('Usuario seleccionado:', usuario);
    // { id: 1, nombre: 'Juan Pérez', email: 'juan@email.com' }
  }
}
```

## 📖 API

### Inputs

| Propiedad | Tipo | Requerido | Default | Descripción |
|-----------|------|-----------|---------|-------------|
| `data` | `any[]` | ✅ | `[]` | Array de objetos para el autocompletado |
| `labelKey` | `string` | ✅ | `'label'` | Propiedad del objeto a mostrar como texto |
| `valueKey` | `string` | ✅ | `'valor'` | Propiedad del objeto a usar como valor del form |
| `label` | `string` | ❌ | `'Buscar...'` | Etiqueta del campo de entrada |
| `class` | `string` | ✅ | `''` | Clases CSS para el mat-form-field |

### Outputs

| Evento | Tipo | Descripción |
|--------|------|-------------|
| `itemSelected` | `EventEmitter<any>` | Emite el objeto completo cuando se selecciona una opción |


## 🎨 Personalización de Estilos

El componente acepta clases CSS a través del input `class`:
```html
<!-- Ancho completo -->
<lib-ngx-autocomplete class="w-full" ...></lib-ngx-autocomplete>

<!-- Clase personalizada -->
<lib-ngx-autocomplete class="mi-autocomplete" ...></lib-ngx-autocomplete>
```
```css
/* En tu archivo de estilos global o del componente */
.mi-autocomplete {
  width: 300px;
}

.mi-autocomplete .mat-mdc-form-field {
  /* Estilos personalizados */
}
```

## 🔧 Solución de Problemas

### El componente no muestra las opciones

Verifica que:
1. El array `data` no esté vacío
2. Las propiedades `labelKey` y `valueKey` coincidan con las propiedades de tus objetos

### Error: "mat-form-field is not a known element"

Asegúrate de tener Angular Material correctamente instalado:
```bash
ng add @angular/material
```

### El valor no se muestra al cargar

Verifica que el valor inicial coincida exactamente con algún `valueKey` de la data:
```typescript
// ✅ Correcto: el valor 2 existe en la data
this.formulario.patchValue({ usuarioId: 2 });

// ❌ Incorrecto: el valor no existe
this.formulario.patchValue({ usuarioId: 999 });
```

## 📄 Licencia

MIT © MS Technology

## 🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue primero para discutir los cambios que te gustaría realizar.

---

**¿Te resultó útil?** ⭐ Dale una estrella al repositorio