# Numeric

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

Pipe e serviço Angular para formatação de valores numéricos de acordo com o locale ativo. O `NumericPipe` retorna um `Observable<string>` e deve ser usado sempre com o pipe `async`. O `NumericService` oferece o método `instant()` para formatação síncrona em TypeScript.

## Quando usar

- Exibir valores numéricos formatados conforme o locale do usuário (separadores de milhar e decimal)
- Formatar valores monetários, percentuais ou números com precisão configurável em templates ou em código TypeScript
- Quando a formatação precisa reagir automaticamente a mudanças de locale

## Quando não usar

- Para entrada de dados numéricos pelo usuário — use `sNumericMask` do pacote `numeric-mask`, que cuida de formatação no campo de input
- Para manipulação aritmética de grandes números — use a biblioteca `BigNumber.js` diretamente

## Instalação

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

@NgModule({
  imports: [NumericModule, AsyncPipe],
})
export class MeuModulo {}
```

O `NumericModule` requer `LocaleModule.forRoot()` configurado no módulo raiz da aplicação.

## Uso básico

```html
<!-- Valor inteiro com locale do usuário -->
{{ 1234567 | numeric | async }}

<!-- Com opções de formatação -->
{{ 1234567.89 | numeric:{ numberFormatOptions: { minimumFractionDigits: 2 } } | async }}

<!-- Com locale fixo -->
{{ 1234567.89 | numeric:{ locale: 'en-US', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}

<!-- Moeda -->
{{ 1234.56 | numeric:{ numberFormatOptions: { style: 'currency', currency: 'BRL' } } | async }}
```

## API

### NumericPipe

#### Assinatura

```typescript
transform(
  value: number | string | BigNumber,
  options?: {
    locale?: string;
    numberFormatOptions?: Intl.NumberFormatOptions;
  }
): Observable<string>
```

| Parâmetro | Tipo | Padrão | Obrigatório | Descrição |
|-----------|------|--------|:-----------:|-----------|
| `value` | `number \| string \| BigNumber` | — | Sim | Valor a ser formatado |
| `options.locale` | `string` | Locale do `LocaleService` | Não | Sobrescreve o locale para formatação |
| `options.numberFormatOptions` | `Intl.NumberFormatOptions` | `{}` | Não | Opções de formatação da API `Intl.NumberFormat` |

### NumericService

#### Método `instant()`

```typescript
instant(
  value: number | string | BigNumber,
  options?: {
    locale?: string;
    numberFormatOptions?: Intl.NumberFormatOptions;
  }
): string | null
```

Retorna o valor formatado de forma síncrona. Deve ser chamado somente após o `LocaleService` ter sido inicializado.

### Tipos

```typescript
// Aceita qualquer opção da API nativa
type NumericOptions = {
  locale?: string;
  numberFormatOptions?: Intl.NumberFormatOptions;
};

// Tipos de entrada aceitos
type NumericValue = number | string | BigNumber;
```

## Exemplos

### Formatação por locale

```html
<!-- pt-BR: 1.234.567,89 -->
{{ 1234567.89 | numeric:{ locale: 'pt-BR', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}

<!-- en-US: 1,234,567.89 -->
{{ 1234567.89 | numeric:{ locale: 'en-US', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}

<!-- de-DE: 1.234.567,89 -->
{{ 1234567.89 | numeric:{ locale: 'de-DE', numberFormatOptions: { minimumFractionDigits: 2 } } | async }}
```

### Formatação de moedas

```html
<!-- BRL: R$ 1.234,56 -->
{{ 1234.56 | numeric:{ locale: 'pt-BR', numberFormatOptions: { style: 'currency', currency: 'BRL' } } | async }}

<!-- USD: $1,234.56 -->
{{ 1234.56 | numeric:{ locale: 'en-US', numberFormatOptions: { style: 'currency', currency: 'USD' } } | async }}
```

### Uso do NumericService em TypeScript

```typescript
import { inject } from '@angular/core';
import { NumericService } from '@seniorsistemas/angular-components/numeric';

const numericService = inject(NumericService);

// Formatação com locale e opções
const valor = numericService.instant(1234567.89, {
  locale: 'pt-BR',
  numberFormatOptions: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
});
// Resultado: "1.234.567,89"
```

## Acessibilidade

- Os valores formatados são texto puro, lidos por leitores de tela conforme o locale configurado
- Não há componente visual; a acessibilidade depende do elemento host que exibe o valor

## Componentes relacionados

- [`sNumericMask`](../numeric-mask/README.md) — máscara de entrada para campos numéricos
- [`Locale`](../locale/) — serviço e pipes de localização usados internamente