# CountryPhonePicker

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente de seleção de país com DDI e campo de telefone com máscara dinâmica. Exibe uma lista de países com bandeiras, aplica automaticamente a máscara de formatação conforme o país selecionado e emite os dados via Angular Forms.

## Quando usar

- Formulários internacionais que aceitam números de telefone de diferentes países
- Cadastros onde o DDI precisa ser capturado junto ao número
- Formulários regionalizados onde apenas um subconjunto de países é relevante

## Quando não usar

- Formulários exclusivamente nacionais sem necessidade de seleção de país — use um campo de texto com máscara
- Quando o DDI é fixo e não precisa ser selecionado pelo usuário

## Instalação

```typescript
import { CountryPhonePickerModule } from '@seniorsistemas/angular-components/country-phone-picker';

@Component({ standalone: true, imports: [CountryPhonePickerModule] })
export class MeuComponent {}
```

> **Atenção:** É necessário adicionar os estilos de bandeiras no `angular.json`:
> ```json
> "styles": ["node_modules/flag-icons/css/flag-icons.min.css"]
> ```

## Uso básico

```html
<s-country-phone-picker formControlName="telefone" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `countries` | `string[]` | `[]` | — | Lista de códigos ISO 3166-1 alpha-2 exibidos no dropdown. Vazio = todos os países |
| `ordination` | `Ordination` | `Ordination.NO` | — | Critério de ordenação da lista de países |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `selected` | `EventEmitter<CountryPhoneData>` | Emitido ao selecionar um país no dropdown |
| `focusLost` | `EventEmitter<PhoneSelectionData \| null>` | Emitido quando o campo de telefone perde o foco |

### Tipos

```typescript
enum Ordination {
  NO = 'no',   // Sem ordenação (ordem padrão)
  AZ = 'az',   // Ordem alfabética A-Z
  ZA = 'za',   // Ordem alfabética Z-A
}

interface CountryPhoneData {
  id: string;              // Código ISO do país (ex: 'br')
  ddi: string;             // Código DDI (ex: '+55')
  mask: string | string[]; // Máscara(s) de formatação
}

interface PhoneSelectionData {
  id: string;       // Código ISO do país selecionado
  ddi: string;      // Código DDI
  value: string;    // Número formatado com máscara
  rawValue: string; // Número sem formatação
}
```

## Exemplos

### Lista filtrada para países específicos

```html
<s-country-phone-picker
  formControlName="telefone"
  [countries]="['br', 'us', 'ar', 'co', 'py', 'uy', 'cl', 'pe']"
  (selected)="onPaisSelecionado($event)"
  (focusLost)="onFocusLost($event)"
></s-country-phone-picker>
```

### Lista ordenada alfabeticamente

```html
<s-country-phone-picker
  formControlName="telefone"
  [ordination]="'az'"
></s-country-phone-picker>
```

### Reagindo à seleção de país

```typescript
onPaisSelecionado(country: CountryPhoneData) {
  console.log('País selecionado:', country.id, 'DDI:', country.ddi);
}

onFocusLost(data: PhoneSelectionData | null) {
  if (data) {
    console.log('Número formatado:', data.value);
  }
}
```

## Acessibilidade

- Navegação por teclado no dropdown: `Enter`/`Espaço` abre/confirma, `Escape` fecha, `ArrowUp`/`ArrowDown` navega entre países
- O dropdown fecha ao clicar fora do componente
- Implementa `ControlValueAccessor` — compatível com `formControlName`, `formControl` e `ngModel`

## Componentes relacionados

- [`Mask`](../mask/README.md) — diretiva de máscara aplicada internamente ao campo de telefone