# LocalizedNumberInput

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

Diretiva de validação para campos `<input>` que verifica se o valor digitado é um número localizado válido, considerando os separadores decimal e de milhar do locale ativo. Integra-se ao sistema de formulários Angular via `NG_VALIDATORS`, adicionando o erro `invalidNumber` quando o valor não é válido.

## Quando usar

- Campos de entrada numérica em formulários que precisam validar o formato localizado (ex: `1.234,56` em pt-BR)
- Quando o usuário digita livremente e você precisa garantir que o valor é um número no formato correto antes de processar
- Aplicações multi-locale onde os separadores podem variar

## Quando não usar

- Quando você precisa de formatação visual automática enquanto o usuário digita — prefira uma máscara numérica
- Para campos de valores inteiros sem casas decimais — use validação nativa do Angular Forms (`Validators.pattern`)

## Instalação

```typescript
import { LocalizedNumberInputModule } from '@seniorsistemas/angular-components/localized-number-input';

@NgModule({
    imports: [LocalizedNumberInputModule],
})
export class MeuModule {}
```

**Dependência:** Requer `LocaleModule.forRoot()` configurado no módulo raiz da aplicação.

## Uso básico

```html
<input sLocalizedNumberInput [precision]="2" formControlName="valor" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `precision` | `number` | `2` | Não | Número máximo de casas decimais aceitas na validação. |
| `decimalSeparator` | `string` | Locale ativo | Não | Separador decimal personalizado. Usa o do locale ativo se não informado. |
| `thousandsSeparator` | `string` | Locale ativo | Não | Separador de milhar personalizado. Usa o do locale ativo se não informado. |

### Erros de validação

| Chave | Valor | Condição |
|-------|-------|----------|
| `invalidNumber` | `true` | O valor digitado não corresponde ao formato de número localizado esperado. |

## Exemplos

### Validação com locale pt-BR (padrão)

```html
<form [formGroup]="form">
    <input
        sLocalizedNumberInput
        [precision]="2"
        formControlName="valor"
        placeholder="Ex: 1.234,56"
    />
    @if (form.get('valor')?.errors?.['invalidNumber'] && form.get('valor')?.dirty) {
        <small style="color: red;">Número inválido para o locale atual (pt-BR)</small>
    }
</form>
```

### Validação com separadores customizados (en-US)

```html
<input
    sLocalizedNumberInput
    [precision]="2"
    decimalSeparator="."
    thousandsSeparator=","
    formControlName="valorUsd"
    placeholder="Ex: 1,234.56"
/>
```

### Alta precisão decimal (4 casas)

```html
<input
    sLocalizedNumberInput
    [precision]="4"
    formControlName="cotacao"
    placeholder="Ex: 1.234,5678"
/>
```

### Exibindo erro de validação

```typescript
@Component({ ... })
export class MeuComponent {
    form = new FormGroup({
        valor: new FormControl(''),
    });

    get valorInvalido(): boolean {
        const control = this.form.get('valor');
        return !!(control?.errors?.['invalidNumber'] && control.dirty);
    }
}
```

```html
<input sLocalizedNumberInput [precision]="2" formControlName="valor" />
@if (valorInvalido) {
    <small>Informe um número válido. Exemplo: 1.234,56</small>
}
```

## Acessibilidade

- A diretiva integra-se ao sistema de validação nativo do Angular Forms via `NG_VALIDATORS`
- O erro `invalidNumber` é adicionado ao `FormControl` para uso com mensagens de validação padrão
- Use `formControlName` ou `ngModel` para que a validação seja aplicada corretamente
- Os separadores são obtidos automaticamente do `LocaleService` — não é necessário configurar manualmente para o locale padrão

## Componentes relacionados

- [`NumericMask`](../numeric-mask/README.md) — máscara de entrada com formatação visual automática enquanto o usuário digita
- [`BigNumberInput`](../bignumber-input/README.md) — máscara para números de grande precisão