# LocalizedNumberInput

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

> **Descontinuado** — Será removido na v20. Use a diretiva [`sNumericMask`](../numeric-mask/README.md) em novos projetos.

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

- Manutenção de formulários legados que já utilizam `sLocalizedNumberInput`
- 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`)

## Migração

A `sNumericMask` já valida o formato conforme o locale e aplica a máscara enquanto o usuário digita, então
a entrada de caracteres inválidos é impedida. O `precision` desta diretiva (casas decimais) corresponde ao
`maxDecimalPlaces` da `sNumericMask`, e `thousandsSeparator` corresponde a `thousandSeparator`.

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

<!-- Depois -->
<input sNumericMask [maxDecimalPlaces]="2" formControlName="valor" />
```

> **Atenção:** o valor do `FormControl` passa a ser uma `string` em formato internacional (ex.: `'1234.56'`),
> e o erro `invalidNumber` deixa de existir — a `sNumericMask` reporta erros próprios (ex.: `negativeNotAllowed`).
> Para aceitar valores negativos, informe `[allowNegative]="true"`.

O schematic `ng generate @seniorsistemas/angular-components:migrate-deprecated-apis` faz essa troca automaticamente.

## Instalação (legado)

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

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

**Dependência:** Requer `provideLocale()` configurado nos providers 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