npm package: @mstechnology/ngx-phone-input
Description: Componente de entrada de teléfono internacional para Angular con Angular Material
Author: MS Technology
Latest version: 1.0.101

# NgxPhoneInput

[![npm version](https://badge.fury.io/js/%40mstechnology%2Fngx-phone-input.svg)](https://www.npmjs.com/package/@mstechnology/ngx-phone-input)
[![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 entrada de teléfono internacional para Angular 18+, construido con Angular Material. Incluye selector de país con banderas, validación automática por longitud y soporte completo para formularios reactivos.

## ✨ Características

- 🌍 **+35 países incluidos** - Lista predeterminada con países de América, Europa y Asia
- 🎯 **Integración con Reactive Forms** - Implementa `ControlValueAccessor` y `Validator`
- ✅ **Validación automática** - Valida longitud según el país seleccionado
- 🚩 **Banderas emoji** - Selector visual con banderas de cada país
- 📦 **Standalone Component** - Sin necesidad de módulos adicionales
- ⚡ **Angular Signals** - Máximo rendimiento con signals
- 🎨 **Personalizable** - Acepta lista de países personalizada y clases CSS
- 🧹 **Botón 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-phone-input
```

Asegúrate de tener Angular Material configurado:
```bash
ng add @angular/material
```

## 🚀 Uso Básico

### 1. Importar el componente
```typescript
import { NgxPhoneInput } from '@mstechnology/ngx-phone-input';

@Component({
  selector: 'app-mi-componente',
  standalone: true,
  imports: [NgxPhoneInput, ReactiveFormsModule],
  templateUrl: './mi-componente.html'
})
export class MiComponente { }
```

### 2. Usar en el template
```html
<form [formGroup]="miFormulario">
  <lib-ngx-phone-input
    class="w-full"
    formControlName="telefono"
    initialCountryIso="CO"
    label="Teléfono celular"
    [required]="true"
    (phoneChange)="onPhoneChange($event)">
  </lib-ngx-phone-input>

  @if (miFormulario.get('telefono')?.hasError('required')) {
    <span class="error">El teléfono es requerido</span>
  }
  @if (miFormulario.get('telefono')?.hasError('invalidLength'); let error) {
    <span class="error">
      Se requieren {{ error.requiredLength }} dígitos para {{ error.countryName }}
    </span>
  }
</form>
```

### 3. Configurar en el componente
```typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { PhoneValue } from '@mstechnology/ngx-phone-input';

@Component({ ... })
export class MiComponente {
  miFormulario: FormGroup;

  constructor(private fb: FormBuilder) {
    this.miFormulario = this.fb.group({
      telefono: ['', Validators.required]
    });
  }

  onPhoneChange(phone: PhoneValue): void {
    console.log('Número completo:', phone.fullNumber);  // +573001234567
    console.log('Código país:', phone.countryCode);      // +57
    console.log('Número nacional:', phone.nationalNumber); // 3001234567
    console.log('Es válido:', phone.isValid);            // true/false
    console.log('País:', phone.country?.name);           // Colombia
  }
}
```

## 📖 API

### Inputs

| Propiedad | Tipo | Requerido | Default | Descripción |
|-----------|------|-----------|---------|-------------|
| `class` | `string` | ✅ | `''` | Clases CSS para el contenedor |
| `data` | `Country[]` | ❌ | Lista interna | Lista de países personalizada |
| `initialCountryIso` | `string` | ❌ | `'CO'` | Código ISO del país inicial |
| `label` | `string` | ❌ | `'Teléfono'` | Etiqueta del campo |
| `appearance` | `'fill' \| 'outline'` | ❌ | `'outline'` | Apariencia de Material |
| `showCountryName` | `boolean` | ❌ | `false` | Mostrar nombre del país |
| `showClearButton` | `boolean` | ❌ | `true` | Mostrar botón limpiar |
| `showHint` | `boolean` | ❌ | `true` | Mostrar contador de caracteres |
| `required` | `boolean` | ❌ | `false` | Campo requerido |

### Outputs

| Evento | Tipo | Descripción |
|--------|------|-------------|
| `phoneChange` | `EventEmitter<PhoneValue>` | Emite información completa al cambiar |

### Interfaces
```typescript
interface Country {
  code: string;    // '+57'
  iso: string;     // 'CO'
  flag: string;    // '🇨🇴'
  name: string;    // 'Colombia'
  mask: string;    // '000 000 0000'
  length: number;  // 10
}

interface PhoneValue {
  fullNumber: string;      // '+573001234567'
  countryCode: string;     // '+57'
  nationalNumber: string;  // '3001234567'
  country: Country | null;
  isValid: boolean;
}
```

### Errores de Validación

| Error | Descripción |
|-------|-------------|
| `required` | Campo vacío cuando es requerido |
| `minLength` | Menos de 5 dígitos |
| `invalidLength` | No coincide con longitud del país |
```typescript
// Acceder a los errores
const errors = this.form.get('telefono')?.errors;

if (errors?.['invalidLength']) {
  console.log(`Se requieren ${errors['invalidLength'].requiredLength} dígitos`);
}
```

## 💡 Ejemplos Avanzados

### Lista de países personalizada
```typescript
import { Country } from '@mstechnology/ngx-phone-input';

misPaises: Country[] = [
  { code: '+57', iso: 'CO', flag: '🇨🇴', name: 'Colombia', mask: '000 000 0000', length: 10 },
  { code: '+1', iso: 'US', flag: '🇺🇸', name: 'USA', mask: '(000) 000-0000', length: 10 },
];
```
```html
<lib-ngx-phone-input
  class="w-full"
  [data]="misPaises"
  formControlName="telefono">
</lib-ngx-phone-input>
```

### Valor inicial programático
```typescript
// Establecer valor (detecta país automáticamente)
this.form.patchValue({
  telefono: '+573001234567'
});

// Resetear
this.form.get('telefono')?.reset();
```

### Con apariencia fill
```html
<lib-ngx-phone-input
  class="w-full"
  appearance="fill"
  [showCountryName]="true"
  formControlName="telefono">
</lib-ngx-phone-input>
```

## 🎨 Estilos Globales (Opcional)
```scss
// Para que el panel del selector tenga scroll
::ng-deep .ngx-phone-country-panel {
  max-height: 300px;
}

// Ancho personalizado
.custom-phone {
  max-width: 400px;
}
```

## 📄 Licencia

MIT © MS Technology

---

**¿Te resultó útil?** ⭐ Dale una estrella al repositorio