# NumericMask

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

Diretiva Angular para formatação de valores numéricos em campos de input com suporte a internacionalização. Aplica separadores de milhar e decimal conforme o locale configurado, com controle de casas decimais, suporte a valores negativos e notação científica.

## Quando usar

- Campos de entrada de valores numéricos que precisam de formatação automática conforme o locale do usuário
- Campos monetários, de quantidade ou de medidas que exijam separadores de milhar e decimal corretos
- Formulários com validação de valor mínimo e máximo em campos numéricos

## Quando não usar

- Para exibição de valores formatados somente leitura — use o `NumericPipe` do pacote `numeric` com `| async`
- Para inputs do tipo `number` do HTML — a diretiva opera sobre `<input type="text">`
- Quando a entrada é livre (texto, datas, etc.) — use as diretivas de máscara específicas para cada tipo

## Instalação

```typescript
import { NumericMaskDirective } from '@seniorsistemas/angular-components/numeric-mask';

@Component({
  standalone: true,
  imports: [NumericMaskDirective, FormsModule],
})
export class MeuComponent {
  valor: string | null = null;
}
```

## Uso básico

```html
<input
  type="text"
  sNumericMask
  [locale]="'pt-BR'"
  [minDecimalPlaces]="2"
  [maxDecimalPlaces]="2"
  [(ngModel)]="valor"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `locale` | `string \| undefined` | Locale do `LocaleService` | Não | Locale para formatação (ex: `'pt-BR'`, `'en-US'`). Se omitido, usa o locale do `LocaleService` |
| `minDecimalPlaces` | `number` | `0` | Não | Número mínimo de casas decimais a exibir |
| `maxDecimalPlaces` | `number` | `10` | Não | Número máximo de casas decimais permitidas |
| `allowNegative` | `boolean` | `false` | Não | Permite valores negativos. Use as teclas `+` ou `-` para alternar o sinal |
| `allowScientificNotation` | `boolean` | `true` | Não | Habilita suporte a notação científica (ex: `1.5e10`) |
| `min` | `number \| undefined` | `undefined` | Não | Valor mínimo permitido (validação de formulário) |
| `max` | `number \| undefined` | `undefined` | Não | Valor máximo permitido (validação de formulário) |

### Tipos

```typescript
// O valor do modelo (ngModel / FormControl) é sempre string no formato decimal internacional
// Exemplo: "1234567.89" para o valor 1.234.567,89 em pt-BR
type NumericMaskModelValue = string | null;
```

### Erros de validação emitidos

```typescript
// Valor negativo quando allowNegative = false
{ negativeNotAllowed: true }

// Valor abaixo do mínimo
{ min: { min: number; actual: number } }

// Valor acima do máximo
{ max: { max: number; actual: number } }

// Casas decimais acima do máximo
{ excessiveDecimalPlaces: { max: number; actual: number } }
```

## Exemplos

### Campo monetário com 2 casas decimais fixas

```html
<input
  type="text"
  sNumericMask
  locale="pt-BR"
  [minDecimalPlaces]="2"
  [maxDecimalPlaces]="2"
  placeholder="0,00"
  [(ngModel)]="valorMonetario"
/>
```

### Campo com valores negativos

```html
<input
  type="text"
  sNumericMask
  locale="pt-BR"
  [minDecimalPlaces]="2"
  [maxDecimalPlaces]="2"
  [allowNegative]="true"
  placeholder="-0,00"
  [(ngModel)]="variacao"
/>
<!-- Pressione + ou - para alternar entre positivo e negativo -->
```

### Campo com validação de intervalo (porcentagem)

```html
<input
  type="text"
  sNumericMask
  locale="pt-BR"
  [minDecimalPlaces]="2"
  [maxDecimalPlaces]="2"
  [min]="0"
  [max]="100"
  placeholder="0,00"
  [(ngModel)]="percentual"
/>
```

### Campo com locale en-US

```html
<input
  type="text"
  sNumericMask
  locale="en-US"
  [minDecimalPlaces]="2"
  [maxDecimalPlaces]="2"
  placeholder="0.00"
  [(ngModel)]="valor"
/>
```

### Campo com casas decimais variáveis

```html
<input
  type="text"
  sNumericMask
  locale="pt-BR"
  [minDecimalPlaces]="0"
  [maxDecimalPlaces]="4"
  placeholder="0"
  [(ngModel)]="quantidade"
/>
```

## Acessibilidade

- Define automaticamente `inputmode="decimal"` no elemento host para exibir teclado numérico em dispositivos móveis
- Define `autocomplete="off"` para evitar sugestões incorretas do navegador
- Suporte a `Backspace`, `Tab`, `Enter`, `Escape`, `ArrowLeft`, `ArrowRight`, `Delete`, `Home` e `End`
- As teclas `+` e `-` alternam o sinal quando `allowNegative` está ativo

## Componentes relacionados

- [`NumericPipe`](../numeric/README.md) — formatação de valores numéricos para exibição somente leitura
- [`NumberInput`](../number-input/src/lib/number-input/README.md) — diretiva descontinuada, use `sNumericMask` em seu lugar