# CurrencyInput

O campo de dinheiro em reais. O valor entra e sai em **centavos inteiros**
(`123456` é R$ 1.234,56), a digitação anda da direita para a esquerda como na
maquininha, e o "R$" fica desenhado ao lado, fora do valor.

```tsx
const [cents, setCents] = useState<number | null>(null)

<Field>
  <FieldLabel>Valor da cobrança</FieldLabel>
  <CurrencyInput value={cents} onValueChange={setCents} />
</Field>
```

Cada tecla empurra os dígitos para a esquerda: `1` mostra `0,01`, `12` mostra
`0,12`, `123456` mostra `1.234,56`. A pontuação sai do `Intl.NumberFormat` em
`pt-BR`, e o teclado do celular abre no numérico. Campo vazio é `null`, e não
zero: "não digitou" e "digitou zero" são respostas diferentes num formulário, e
o zero se digita com a tecla `0`.

**Guarde os centavos.** O servidor recebe inteiro, sem ponto flutuante no meio,
e a pontuação é assunto de tela. O campo para em doze dígitos, R$
9.999.999.999,99, que é onde o inteiro ainda cabe folgado.

## Colar

Colar substitui o valor, e o texto colado é lido como a pessoa o escreveria:
`R$ 1.234,56`, `1234,56`, `1.234,5` e `1234.56` entram como R$ 1.234,56, e
`150` entra como R$ 150,00. O separador de centavos é a vírgula ou o ponto que
tiver um ou dois dígitos depois; os outros são milhar. O sinal vem pelo `-`,
antes ou depois do número, ou pelos parênteses da contabilidade: `(10,00)` é
R$ -10,00.

O colado é recusado inteiro, e o valor que estava fica, quando não é só um
valor: texto sem número, texto misturado ao número (`R$ 10 - desconto 2`,
`Total: R$ 10,00`) e valor com mais de doze dígitos. Nada é cortado em
silêncio para caber.

Desabilitado, o campo fica fora do formulário, como qualquer campo
desabilitado do HTML. O leitor de tela ouve o número e, na descrição, "em
reais": o "R$" desenhado ao lado é só visual.

## Sinal

Sem `allowNegative`, o `-` não entra, nem digitado nem colado. Com ele, o `-`
em qualquer ponto do campo põe o sinal, e um segundo `-` tira:

```tsx
<CurrencyInput value={adjustment} onValueChange={setAdjustment} allowNegative />
```

O teclado numérico do iPhone não tem o sinal, então com `allowNegative` o
campo abre o teclado de texto no web, e o de números e pontuação no nativo.

## Limites

`min` e `max` são em centavos. Fora deles o campo se marca inválido, com a
borda de perigo e `aria-invalid`, e **nada é corrigido sozinho**: trocar o
valor de dinheiro que a pessoa digitou, sem ela ver, é o pior erro que um campo
destes pode cometer. A mensagem que diz o limite é do formulário, como no
`TimeField`. Campo vazio não é inválido por causa de `min`: obrigatório é outra
regra, e também é do formulário.

```tsx
<CurrencyInput value={cents} onValueChange={setCents} min={1_000} max={500_000} />
```

## No formulário

O `forValue` do `@rivocode/ui/form` liga o campo ao React Hook Form: o
`onValueChange` já entrega o número que o schema espera. O campo vazio é
`null`, então o schema aceita `null` no tipo (`.nullable()`) e o recusa no
`refine`: sem isso, `defaultValues: { amount: null }` não compila.

```tsx
const schema = z.object({
  amount: z
    .number()
    .int()
    .min(100, 'O mínimo é R$ 1,00')
    .nullable()
    .refine((cents) => cents !== null, 'Informe o valor'),
})

const form = useZodForm(schema, { defaultValues: { amount: null } })

<FormField name="amount" label="Valor da cobrança">
  {(field) => <CurrencyInput {...forValue(field)} />}
</FormField>
```

O `forValue` repassa a `ref` e o `onBlur`: o envio com erro põe o foco no
campo, e o `useZodForm`, que nasce com `mode: 'onTouched'`, confere ao sair dele. No formulário nativo do HTML, sem React Hook Form, o `name`
põe os centavos num campo escondido: o que chega ao servidor é `123456`, e não
`1.234,56`.

## Partes

`classNames` alcança cada nó pelo nome: `input` e `prefix` (o "R$").
`className` veste a raiz, que embrulha os dois.

## Quando não usar

- **Quantidade com passo**, como parcelas, itens ou dias de prazo, é
  `NumberField`: ali o valor anda de um em um pelos botões e pelas setas, e o
  que importa é o limite, não a pontuação.
- **Dinheiro que precisa de molde junto de outros moldes**, na mesma lista de
  campos gerada por configuração, é `MaskedInput` com `mask="moeda"`. Ele
  entrega o cru e o texto pontuado, e o centavo sai por `toCents()`; não tem
  sinal, limite nem colagem inteligente.
- **Valor que a tela só mostra** é texto formatado, e não campo desabilitado:
  use `currency()` numa célula ou no `Stat`. O `currency()` recebe **reais**: o
  valor deste campo se escreve `currency(cents / 100)`, e sem a divisão a tela
  mostra cem vezes mais.

## iOS e Android

No iOS, com `allowNegative`, o campo abre o teclado de números e pontuação, porque o teclado numérico do iOS não tem sinal de menos; no Android abre o numérico, que tem o sinal. É o único ponto em que os dois sistemas ficam diferentes, e é limite do teclado, não da peça. O `-` digitado ou colado põe e tira o sinal do mesmo jeito nos dois.

## No React Native

Traduz, com a mesma conta: o valor em centavos, a digitação que anda da direita para a esquerda, o `-` que põe e tira o sinal e a leitura do texto colado moram num arquivo só, compartilhado pelos dois pacotes. O campo é controlado, como todo o nativo: `value` e `onValueChange` são obrigatórios.

O React Native não avisa quando a pessoa cola, então o campo lê a seleção de antes da troca para saber o que entrou por cima. Com `allowNegative`, o teclado passa a ser o de números e pontuação, que é o que tem o sinal no iPhone. Não há `name`: formulário escondido não existe no celular.

As partes vestem pelo mesmo `classNames` do web: `input` e `prefix`, este no texto do "R$".

## Importação

```tsx
import { CurrencyInput } from '@rivocode/ui'
```

## Exemplos

### Valor da cobrança

```tsx
import { CurrencyInput, Field, FieldDescription, FieldLabel, currency } from '@rivocode/ui'
import { useState } from 'react'

const LIMIT = { min: 1_000, max: 500_000 }

export function Charge() {
  const [cents, setCents] = useState<number | null>(248_000)

  return (
    <div className="w-full max-w-80">
      <Field>
        <FieldLabel>Valor da cobrança</FieldLabel>
        <CurrencyInput value={cents} onValueChange={setCents} />
        <FieldDescription>
          {cents === null ? 'Nada digitado ainda.' : `Vai para o servidor como ${cents} centavos.`}
        </FieldDescription>
      </Field>
    </div>
  )
}

const LIMIT = { min: 1_000, max: 500_000 }
```

### Com limite

```tsx
import { CurrencyInput, Field, FieldDescription, FieldLabel, currency } from '@rivocode/ui'
import { useState } from 'react'

const LIMIT = { min: 1_000, max: 500_000 }

export function WithLimit() {
  const [cents, setCents] = useState<number | null>(750_000)
  const outside = cents !== null && (cents < LIMIT.min || cents > LIMIT.max)

  return (
    <div className="w-full max-w-80">
      <Field invalid={outside}>
        <FieldLabel>Valor do Pix</FieldLabel>
        <CurrencyInput value={cents} onValueChange={setCents} {...LIMIT} />
        <FieldDescription>
          De {currency(LIMIT.min / 100)} a {currency(LIMIT.max / 100)} por transferência.
        </FieldDescription>
      </Field>
    </div>
  )
}
```

### Ajuste com sinal

```tsx
import { CurrencyInput, Field, FieldDescription, FieldLabel, currency } from '@rivocode/ui'
import { useState } from 'react'

export function Adjustment() {
  const [cents, setCents] = useState<number | null>(-1_590)

  return (
    <div className="w-full max-w-80">
      <Field>
        <FieldLabel>Ajuste no saldo</FieldLabel>
        <CurrencyInput value={cents} onValueChange={setCents} allowNegative />
        <FieldDescription>Digite - em qualquer ponto para trocar o sinal.</FieldDescription>
      </Field>
    </div>
  )
}
```

### Tamanhos e estados

```tsx
import { CurrencyInput, Field, FieldDescription, FieldLabel, currency } from '@rivocode/ui'
import { useState } from 'react'

export function States() {
  return (
    <div className="flex w-full max-w-80 flex-col gap-3">
      <Field>
        <FieldLabel>Pequeno</FieldLabel>
        <CurrencyInput size="sm" defaultValue={1_990} />
      </Field>
      <Field>
        <FieldLabel>Vazio</FieldLabel>
        <CurrencyInput />
      </Field>
      <Field>
        <FieldLabel>Grande</FieldLabel>
        <CurrencyInput size="lg" defaultValue={1_234_567} />
      </Field>
      <Field disabled>
        <FieldLabel>Desabilitado</FieldLabel>
        <CurrencyInput defaultValue={48_000} disabled />
      </Field>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `allowNegative` | `boolean` |  | `false` | - | Aceita valor negativo. |
| `classNames` | `Partial<Record<"input" \| "prefix", string>>` |  |  | - | Classe por parte: `input` e `prefix` (o "R$"). |
| `defaultValue` | `number \| null` |  | `null` | - | O valor inicial em centavos, quando o campo controla o proprio estado. |
| `max` | `number` |  |  | - | O maior valor aceito, em centavos. |
| `min` | `number` |  |  | - | O menor valor aceito, em centavos. |
| `name` | `string` |  |  | - | Some no formulario nativo com os centavos, e nunca com o texto pontuado. |
| `onValueChange` | `((cents: number \| null) => void)` |  |  | - | Chamado a cada tecla com os centavos, ou `null` quando o campo esvazia. |
| `render` | `ComponentRenderFn<HTMLProps, FieldControlState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. |
| `size` | `ControlSize \| null` |  |  | - |  |
| `value` | `number \| null` |  |  | - | O valor em centavos inteiros: `123456` e R$ 1.234,56. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
