🧰 AlpuraAutocompleteComponent – Guía de uso

Este documento explica cómo utilizar el componente AlpuraAutocompleteComponent, un autocompletado reutilizable que se integra con formularios de Angular y puede manejar datos locales o remotos (API) con búsqueda asíncrona.

---

📁 Importaciones necesarias

Para usar el componente AlpuraAutocompleteComponent, importa su clase y añádelo a tu módulo y plantilla:

import { AlpuraAutocompleteComponent } from '@alpura/commons';
import { ReactiveFormsModule } from "@angular/forms"; // Necesario para formControlName

@Component({
  //...
  standalone: true,
  imports: [
    AlpuraAutocompleteComponent,
    ReactiveFormsModule,
    // ... otros módulos
  ],
})
export class TuComponente {
  // ...
}

---

🧩 HTML de ejemplo

El componente está diseñado para funcionar con formControlName dentro de un FormGroup. Los mat-error deben ir dentro de alpura-autocomplete para su correcto funcionamiento.

<form [formGroup]="myForm">
  <alpura-autocomplete
    formControlName="idAseguradora"
    [searchFn]="findAseguradora"
    (noMatchFound)="onNoMatch()"
    [ngClass]="{
      'is-invalid': myForm.get('idAseguradora')?.invalid && myForm.get('idAseguradora')?.touched
    }"
  >
    @if (myForm.get('idAseguradora')?.invalid &&
    myForm.get('idAseguradora')?.touched) {
    <mat-error>El nombre es requerido.</mat-error>
    }
  </alpura-autocomplete>
</form>

---

⚙️ Inputs

Nombre	Tipo	Descripción
ngClass	string or string[] or Set(string) or Record(string, unknown) or null or undefined	Clases CSS personalizadas para aplicar al mat-form-field.
items	IAlpuraAutocompleteItem[]	Lista de elementos para autocompletar localmente. Se usa si no se proporciona searchFn.
label	string	Label del campo de autocompletado.
searchFn	((term: string, size?: number, offset?: number, loadInfo?: boolean) => Observable(IAlpuraAutocompleteItem)[]) or null	Función para búsqueda remota. Recibe el término de búsqueda, paginación (size, offset) y una bandera loadInfo para la carga inicial del valor.

---

📤 Outputs

Nombre	Tipo	Descripción
noMatchFound	EventEmitter(void)	Se emite cuando el usuario sale del campo (blur) y el texto introducido no coincide con ninguna opción válida.

---

🧪 Interfaces

export interface IAlpuraAutocompleteItem {
  /** Identificador único del ítem. */
  id: string;
  /** campo o etiqueta principal visible del ítem. */
  campo: string;
  /** Segundo campo o etiqueta visible (opcional). Se muestra debajo del campo principal. */
  campo2?: string;
  /** Tercer campo o etiqueta visible (opcional). Se muestra junto a campo2. */
  campo3?: string;
}

---

✍️ Uso en TypeScript

Implementación de searchFn

La función searchFn es el corazón de la búsqueda remota. El componente le proporciona 4 parámetros para manejar toda la lógica de obtención de datos:

• term: string: El texto que el usuario escribe en el campo. Cuando loadInfo es true, este parámetro contendrá el id del valor que se está cargando.
• size?: number: El número de registros por página que el componente sugiere para la paginación.
• offset?: number: El desplazamiento para la paginación (ej. offset = 100 para la segunda página si size es 100).
• loadInfo?: boolean: Una bandera que el componente pone en true cuando necesita cargar la información de un id específico (por ejemplo, al inicializar el formControlName con un valor). Esto te permite diferenciar entre una búsqueda por texto y una carga por id.

En el siguiente ejemplo se muestra una función que debe retornar un Observable que emita un arreglo de IAlpuraAutocompleteItem:

import { Observable, map, of } from 'rxjs';
import { IAlpuraAutocompleteItem } from '@alpura/commons';
// ...

public findAseguradora = (
  term: string,
  size: number = 10,
  offset: number = 0,
  loadInfo: boolean = false
): Observable<IAlpuraAutocompleteItem[]> => {
  // Si loadInfo es true, el componente está intentando cargar el valor inicial.
  // El 'term' en este caso es el ID del ítem que se busca para mostrar su nombre.
  if (loadInfo) {
    // Llama a un servicio que busca un solo ítem por su ID.
    // El componente espera un arreglo, así que envolvemos el resultado.
    return this.aseguradoraService.fetchAseguradoraById(term).pipe(
      map(aseguradora => {
        if (!aseguradora) return [];
        const item: IAlpuraAutocompleteItem = {
          id: aseguradora.id,
          nombre: aseguradora.nombreComercial,
        };
        return [item]; // Retorna un arreglo con el único ítem encontrado
      })
    );
  }

  // Búsqueda normal por término de texto, usando paginación.
  return this.aseguradoraService.fetchAseguradorasList(term, size, offset).pipe(
    map(apiResponse =>
      apiResponse.map(item => ({
        id: item.id,
        nombre: item.nombreComercial,
      }))
    )
  );
};

public onNoMatch(): void {
  console.log('El texto no coincide con ninguna opción.');
  // Aquí puedes mostrar un mensaje al usuario o limpiar otros campos.
}

Nota: La función searchFn debe ser una propiedad de la clase (usando una función de flecha) o estar bindeada con .bind(this) para mantener el contexto this si accede a servicios u otras propiedades del componente.

---

🚀 Resultado esperado

• Un campo de autocompletado robusto que se integra fácilmente con formularios reactivos.
• Búsqueda eficiente que filtra localmente o consulta una API con debounce.
• Selección de un ítem que actualiza el FormControl con el id del ítem.
• Carga automática del nombre del ítem cuando se inicializa el FormControl con un id.
• Indicador de carga visual durante las operaciones asíncronas.
• Comportamiento predecible al interactuar y salir del campo.

---

📬 Soporte

Para dudas o mantenimiento, contactar al equipo de arquitectura.

---