# SignaturePad

A área de assinatura na tela: o aceite de um contrato de locação, o recebimento
de uma entrega, o "de acordo" num laudo de vistoria. A pessoa assina com o
dedo, com a caneta ou com o mouse, e quem não consegue desenhar **digita o
nome**, que sai em letra cursiva.

```tsx
const [assinatura, setAssinatura] = useState<SignatureValue | null>(null)

<Field>
  <FieldLabel>Assinatura do locatário</FieldLabel>
  <SignaturePad value={assinatura} onValueChange={setAssinatura} />
</Field>
```

O desenho sai por Pointer Events, então o mesmo código atende dedo, caneta e
mouse. O traço é suave: os pontos são ligados por curvas, e a espessura varia
com a velocidade, fina quando a mão corre e cheia quando ela desacelera, como
tinta de verdade. Com caneta que mede pressão, a pressão entra na conta. O botão
direito do mouse não desenha, e um segundo dedo que encosta no meio do traço
(a palma da mão, quase sempre) é ignorado.

## O valor

`value` é `null` sem assinatura, ou um de dois formatos:

- `{ kind: 'drawn', strokes, width, height }`: os traços, cada um uma lista de
  pontos `{ x, y, time, pressure? }` em unidades de desenho. A área tem 600
  unidades de largura em qualquer tamanho de tela, então a assinatura feita no
  celular sai igual no monitor.
- `{ kind: 'typed', text, font, width, height }`: o nome digitado e a família
  da letra.

`onValueChange` é chamado **ao fim de cada traço**, e não a cada ponto, a cada
letra digitada, ao desfazer e ao limpar. Quando a área esvazia, chega `null`,
que é o que o schema do formulário lê como "sem assinatura". Sem `value`, a
peça guarda a assinatura sozinha a partir de `defaultValue`.

`ratio` é a largura sobre a altura da área, com padrão `3`. A altura sai daí, e
não de um número cravado: a área encolhe junto com a coluna.

## Desfazer, limpar, e o que o leitor de tela ouve

Embaixo do papel ficam **Desfazer o último traço** e **Limpar assinatura**, os
dois `IconButton` com a dica ao pousar, e o botão que troca de modo. Vazia, a
área mostra a linha de base e o "Assine aqui", e os dois botões ficam inativos.

A peça é um `group` com o nome do rótulo do `Field` (ou `aria-label`, ou
"Assinatura" sem nenhum dos dois), descrito pela instrução de como assinar. O
papel é uma imagem cujo nome diz o estado: "Nenhuma assinatura", "Assinatura
desenhada, 3 traços" ou "Assinatura digitada: Maria Souza". Desfazer e limpar
se anunciam num `status`, e limpar pelo teclado leva o foco para o botão de
modo, que continua vivo, em vez de largar o foco no corpo da página.

## Digitar em vez de desenhar

Desenhar pede mão firme e ponteiro fino, e muita gente não tem os dois: quem
usa só teclado, leitor de tela, acionador, ou tem tremor. **Digitar assinatura**
troca o papel pelo campo "Nome para a assinatura", e o nome aparece no papel em
letra cursiva. O valor vira `kind: 'typed'`, e sai exportado do mesmo jeito que
o desenho. Não há prop que desligue esse modo: a alternativa é a peça.

```tsx
<SignaturePad
  value={assinatura}
  onValueChange={setAssinatura}
  font='"Great Vibes", cursive'
/>
```

`font` é a família cursiva, em CSS. Carregue a fonte na página: sem ela, o
navegador cai na cursiva do sistema, e o PNG também. Trocar de modo guarda o
rascunho do outro: quem desenhou, foi digitar e voltou, encontra os traços.
Quando o pai zera o `value` por fora (um `reset` do formulário), os dois
rascunhos vão junto: o campo do nome esvazia e voltar a desenhar não traz traço
antigo. Um caso escapa: se o valor já era `null` quando o pai zera, o React não
avisa a peça, e o rascunho do outro modo continua guardado. Isso acontece quando
a pessoa desenhou, trocou para "Digitar" sem escrever nada e o formulário foi
zerado. Para um reset que apaga tudo sem exceção, remonte a peça com `key`:
`<SignaturePad key={tentativa} … />`, trocando `tentativa` no reset.
Limpar não troca de modo: quem limpou o nome continua no campo do nome.
`defaultMode="type"` abre no nome digitado, para a tela em que a maioria assina
pelo teclado.

## No formulário

Dentro de `Field`, o grupo pega o rótulo, a descrição e o erro; `disabled` e
`invalid` do `Field` chegam sozinhos. No React Hook Form, o `forValue` liga a
peça ao schema, e vazio é `null`:

```tsx
const schema = z.object({
  assinatura: z.custom<SignatureValue | null>().refine((valor) => valor !== null, {
    message: 'Assine para continuar',
  }),
})

<FormField name="assinatura" label="Assinatura do locatário">
  {(field) => <SignaturePad {...forValue(field)} />}
</FormField>
```

No formulário do HTML, `name` põe o **SVG** da assinatura num campo escondido,
vazio quando não há assinatura.

## Exportar

`signatureToSvg(valor)` devolve o SVG em texto, e `signatureToPng(valor)` a
imagem em `data:image/png`, desenhada num canvas com o dobro da resolução
(`scale`). Os dois devolvem `''` sem assinatura.

```tsx
const svg = signatureToSvg(assinatura)
const png = await signatureToPng(assinatura, { paper: true })
```

**A tinta é escura nos dois temas.** A assinatura feita no tema escuro não sai
clara no documento: a tinta, o papel e a guia são os `--rc-signature-*`, fixos
em `scales.css` como o par do código lido por máquina, e não papel de tema. O
`check:contrast` mede a tinta e o "Assine aqui" a 4,5:1 sobre o papel, a linha
de base a 3:1, e reprova a tinta mais clara que o papel. Sem `paper`, o fundo
sai transparente, para assentar sobre o documento; `paper: true` pinta o papel
branco, e `ink` troca a tinta de uma exportação só.

O nome digitado sai no SVG como texto com a `font-family`: quem abrir o arquivo
sem a fonte vê a cursiva do sistema. Para arquivo que precisa sair igual em
qualquer lugar, exporte o PNG.

## Estados

- **Desabilitada**: nem desenho nem botões, a borda vira `border-disabled` e a
  guia `signature-disabled`. A assinatura que já estava continua visível.
- **Só leitura** (`readOnly`): mostra a assinatura sem botões, sem desenho e
  sem o modo de digitar. É a forma de exibir a assinatura já colhida.
- **Inválida** (`invalid`, ou o `Field` inválido): borda `danger` e
  `aria-invalid`. A mensagem é do formulário.

## Partes

`classNames` alcança cada nó pelo nome: `pad` (o papel), `placeholder` (o
"Assine aqui"), `baseline` (a linha), `actions` (a fileira de botões) e `input`
(o campo do nome digitado). `className` veste a raiz.

## Textos

`labels` troca cada texto: `group`, `placeholder`, `instruction`, `undo`,
`clear`, `typeMode`, `drawMode`, `typedName`, `empty`, `undone`, `cleared`, e
as funções `drawn(traços)` e `typed(nome)`, que dizem o estado do papel ao
leitor de tela.

## Quando não usar

- **Aceite que não precisa de rubrica**, como "li e concordo com os termos", é
  `Checkbox`. A assinatura desenhada pesa mais na tela e na mão; peça só quando
  o documento pede o traço.
- **Assinatura que já existe em papel**, digitalizada, é `FileUpload`: a pessoa
  anexa a imagem, e não redesenha.
- **Só o nome, sem valor de assinatura**, como "quem recebeu", é `Input`.
- **Assinatura digital com validade jurídica**, com certificado ICP-Brasil, não
  é esta peça: o traço na tela é evidência de aceite, e não assinatura
  qualificada. O certificado é do serviço que assina o documento.

## No React Native

Traduz, no caminho `@rivocode/ui-native/chart`: o papel é desenhado com o `react-native-svg`, peer da raiz desde a 6.0, e mora com o gráfico pelo peso: quem só usa um `Button` não carrega o papel e o traço da assinatura.

**O traço é o mesmo dos dois lados, linha por linha.** A suavização por curvas, a espessura que varia com a velocidade e com a pressão, o nome digitado em cursiva e o SVG exportado moram em `src/shared/` e atravessam por espelho: a assinatura feita no celular abre igual no web, com o mesmo `value`. O gesto é o `PanResponder` do core, que não cede o toque para a rolagem no meio do traço; `onDrawingChange` avisa quando o dedo começa e termina, para a `ScrollView` em volta desligar o `scrollEnabled`. A força do toque, quando o aparelho a mede, entra como pressão.

**Exporta só o SVG.** `signatureToSvg` sai daqui com a tinta do token, escura nos dois temas; o PNG não porta, porque o React Native não tem canvas. Quem precisa de imagem rasteriza o SVG no servidor, ou captura a área com uma biblioteca de captura de tela. O `value` é controlado, não há `name` (formulário escondido não existe no celular), e o modo de digitar o nome continua lá, na cursiva que o app declarar em `fonts.script` do `RivoProvider` (ou na prop `font`). Sem ela, o nome sai na cursiva de cada sistema (Snell Roundhand no iOS, `cursive` no Android), que é outra letra, com outra largura: declare a `fonts.script` para os dois saírem iguais.

```tsx
import { SignaturePad } from '@rivocode/ui-native/chart'

<SignaturePad
  value={assinatura}
  onValueChange={setAssinatura}
  onDrawingChange={(desenhando) => setRolagem(!desenhando)}
/>
```

O nome do grupo é `label`, no lugar do `aria-label` do web, e sem ele vale o `labels.group`. Dentro do `FormField`, o `forValue` já entrega o `label`.

As partes vestem pelo mesmo `classNames` do web: `pad`, `placeholder`, `actions` e `input`. `baseline` não porta como parte: a linha de base é um traço dentro do `Svg`, e o `react-native-svg` não recebe classe.

## Importação

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

## Exemplos

### Assinar o aceite

```tsx
import {
  Button,
  Field,
  FieldDescription,
  FieldLabel,
  SignaturePad,
  signatureToPng,
  signatureToSvg,
  type SignatureValue,
} from '@rivocode/ui'
import { useState } from 'react'

export function Sign() {
  const [assinatura, setAssinatura] = useState<SignatureValue | null>(null)

  return (
    <Field className="max-w-xl">
      <FieldLabel>Assinatura do locatário</FieldLabel>
      <SignaturePad value={assinatura} onValueChange={setAssinatura} name="assinatura" />
      <FieldDescription>
        {assinatura === null
          ? 'Vale como aceite do contrato de locação.'
          : assinatura.kind === 'typed'
            ? 'Assinatura digitada.'
            : `${assinatura.strokes.length} traço(s).`}
      </FieldDescription>
    </Field>
  )
}
```

### Exportar SVG e PNG

```tsx
import {
  Button,
  Field,
  FieldDescription,
  FieldLabel,
  SignaturePad,
  signatureToPng,
  signatureToSvg,
  type SignatureValue,
} from '@rivocode/ui'
import { useState } from 'react'

const ACEITE: SignatureValue = {
  kind: 'drawn',
  width: 600,
  height: 200,
  strokes: [
    [
      { x: 70, y: 130, time: 0 },
      { x: 95, y: 90, time: 30 },
      { x: 120, y: 70, time: 60 },
      { x: 135, y: 95, time: 90 },
      { x: 150, y: 135, time: 120 },
      { x: 175, y: 105, time: 150 },
      { x: 205, y: 120, time: 180 },
      { x: 240, y: 110, time: 210 },
      { x: 280, y: 128, time: 240 },
      { x: 330, y: 112, time: 270 },
    ],
    [
      { x: 360, y: 140, time: 400 },
      { x: 420, y: 118, time: 430 },
      { x: 500, y: 126, time: 460 },
    ],
  ],
}

export function Export() {
  const [assinatura, setAssinatura] = useState<SignatureValue | null>(ACEITE)
  const [png, setPng] = useState('')

  return (
    <div className="flex max-w-xl flex-col gap-3">
      <Field>
        <FieldLabel>Assinatura</FieldLabel>
        <SignaturePad value={assinatura} onValueChange={setAssinatura} />
      </Field>
      <div className="flex flex-wrap gap-2">
        <Button
          variant="secondary"
          size="sm"
          disabled={assinatura === null}
          onClick={async () => setPng(await signatureToPng(assinatura, { paper: true }))}
        >
          Gerar PNG
        </Button>
        <span className="self-center tabular-nums text-xs text-fg-muted">
          SVG com {signatureToSvg(assinatura).length} caracteres
        </span>
      </div>
      {png ? (
        <img
          src={png}
          alt="Prévia da assinatura exportada"
          className="w-60 rounded-md border border-border"
        />
      ) : null}
    </div>
  )
}
```

### Digitar em vez de desenhar

```tsx
import {
  Button,
  Field,
  FieldDescription,
  FieldLabel,
  SignaturePad,
  signatureToPng,
  signatureToSvg,
  type SignatureValue,
} from '@rivocode/ui'
import { useState } from 'react'

export function Typed() {
  const [assinatura, setAssinatura] = useState<SignatureValue | null>({
    kind: 'typed',
    text: 'Maria Souza',
    font: '"Great Vibes", "Snell Roundhand", cursive',
    width: 600,
    height: 200,
  })

  return (
    <Field className="max-w-xl">
      <FieldLabel>Assinatura</FieldLabel>
      <SignaturePad
        value={assinatura}
        onValueChange={setAssinatura}
        font='"Great Vibes", "Snell Roundhand", cursive'
      />
    </Field>
  )
}
```

### Estados

```tsx
import {
  Button,
  Field,
  FieldDescription,
  FieldLabel,
  SignaturePad,
  signatureToPng,
  signatureToSvg,
  type SignatureValue,
} from '@rivocode/ui'
import { useState } from 'react'

const ACEITE: SignatureValue = {
  kind: 'drawn',
  width: 600,
  height: 200,
  strokes: [
    [
      { x: 70, y: 130, time: 0 },
      { x: 95, y: 90, time: 30 },
      { x: 120, y: 70, time: 60 },
      { x: 135, y: 95, time: 90 },
      { x: 150, y: 135, time: 120 },
      { x: 175, y: 105, time: 150 },
      { x: 205, y: 120, time: 180 },
      { x: 240, y: 110, time: 210 },
      { x: 280, y: 128, time: 240 },
      { x: 330, y: 112, time: 270 },
    ],
    [
      { x: 360, y: 140, time: 400 },
      { x: 420, y: 118, time: 430 },
      { x: 500, y: 126, time: 460 },
    ],
  ],
}

export function States() {
  return (
    <div className="grid max-w-3xl gap-6 sm:grid-cols-2">
      <Field invalid>
        <FieldLabel>Obrigatória</FieldLabel>
        <SignaturePad />
        <FieldDescription>Assine para continuar.</FieldDescription>
      </Field>
      <Field disabled>
        <FieldLabel>Desabilitada</FieldLabel>
        <SignaturePad />
      </Field>
      <Field>
        <FieldLabel>Só leitura</FieldLabel>
        <SignaturePad readOnly defaultValue={ACEITE} />
      </Field>
      <Field>
        <FieldLabel>Mais alta</FieldLabel>
        <SignaturePad ratio={2} />
      </Field>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"actions" \| "baseline" \| "input" \| "pad" \| "placeholder", string>>` |  |  | - | Classe por parte: `pad` (o papel), `placeholder`, `baseline`, `actions` e `input` (o campo do nome). |
| `defaultMode` | `"draw" \| "type"` |  |  | - | Em que modo a area abre quando esta vazia. |
| `defaultValue` | `SignatureValue \| null` |  | `null` | - | A assinatura ao montar, quando ninguem controla. |
| `disabled` | `boolean` |  | `false` | - | Trava o desenho, a digitacao e os botoes. |
| `font` | `string` |  |  | - | A familia cursiva do modo de digitar, em CSS (`'"Great Vibes", cursive'`). |
| `invalid` | `boolean` |  | `false` | - | Pinta a moldura de perigo e anuncia `aria-invalid`. |
| `labels` | `Partial<SignaturePadLabels>` |  |  | - | Os textos da peca: rotulos dos botoes, instrucao, "Assine aqui" e o que o leitor de tela ouve. |
| `name` | `string` |  |  | - | Nome do campo num `<form>`: vai num `input` escondido com o SVG da assinatura, e vazio quando nao ha assinatura. |
| `onValueChange` | `((value: SignatureValue \| null) => void)` |  |  | - | Chamado ao fim de cada traco, a cada letra digitada, ao desfazer e ao limpar. |
| `ratio` | `number` |  |  | - | Largura sobre altura da area. |
| `readOnly` | `boolean` |  | `false` | - | So exibe a assinatura: sem desenho, sem botoes e sem o modo de digitar. |
| `ref` | `Ref<HTMLDivElement>` |  |  | - |  |
| `value` | `SignatureValue \| null` |  |  | - | A assinatura, controlada: os tracos desenhados (`kind: "drawn"`) ou o nome digitado (`kind: "typed"`). |

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)
