# Fazer antes de o servidor responder

**Otimista é o padrão da casa.** Toda ação aparece feita na hora, e se o
servidor recusar, a tela volta ao que era e diz. Esperar o servidor é a
exceção, e ela tem lista fechada, logo abaixo em "Quando não usar".

## O problema

Esperar o servidor para marcar como lida, favoritar ou reordenar cobra meio
segundo de toda pessoa, toda vez, pelo erro raro. E a tela otimista que não
volta atrás é pior que a lenta: mostra feito o que não foi.

## Quando usar

Sempre, a não ser que a ação caia numa das exceções de baixo. Comece toda
`useMutation` pelo `onMutate`, e não pelo `loading`: marcar como lida,
favoritar, fixar, seguir, reordenar, mudar a quantidade no carrinho, mover o
cartão no `Kanban`, ligar um `Switch` de preferência, renomear, editar um campo
na linha, arquivar com "Desfazer" no aviso, adicionar e tirar etiqueta.

A pergunta não é "esta ação merece ser otimista?", e sim "esta ação está na
lista de exceções?". Se não está, ela é otimista.

## Quando não usar

As exceções são estas, e só estas. Nelas o `loading` no botão é a verdade, e o
`Result` ou o aviso só aparecem quando o servidor confirmou.

- **Dinheiro**: pagar, cobrar, estornar, emitir boleto ou Pix.
- **Efeito fora do sistema**: emitir nota, enviar à prefeitura, mandar e-mail
  ou mensagem, chamar a integração de terceiro. O que saiu não volta com a
  tela.
- **Sem volta**: excluir de vez, cancelar nota, encerrar conta. A proteção
  dessas mora em [confirmar-ou-desfazer.md](https://ds.rivocode.com.br/padroes/confirmar-ou-desfazer.md).
- **O servidor recusa com frequência**: o horário que outra pessoa pode ter
  reservado no mesmo minuto, o estoque disputado, o nome de usuário que precisa
  ser único. A volta viraria rotina.
- **A resposta traz o que a tela mostra**: o número da nota, o código do Pix, o
  identificador que só o servidor gera. Não há o que desenhar antes.

Na dúvida entre as duas, a ação é otimista: a volta com aviso custa um aviso, e
a espera custa meio segundo de toda pessoa, toda vez.

## As peças

- `useMutation` do TanStack Query, com `onMutate`, `onError` e `onSettled`.
- `useToast` para o aviso de que a volta aconteceu, com "Tentar de novo" em
  `actionProps`.
- As peças que já trabalham assim por baixo: `Kanban` (o `onMove` muda o dado
  na hora), `SortableList`, `Switch`, `Rating`.

## Comportamento

A regra tem duas metades, e a segunda é a que se esquece:

1. **Mude a tela já**, guardando como ela estava.
2. **Se o servidor recusar, volte ao que estava e diga**, num aviso com
   "Tentar de novo".

```tsx
const { mutate: markRead } = useMutation({
  mutationFn: markNotificationRead,
  onMutate: async (id) => {
    await queryClient.cancelQueries({ queryKey: ['avisos'] })
    const before = queryClient.getQueryData(['avisos'])
    queryClient.setQueryData(['avisos'], (list) => list.map((n) => (n.id === id ? { ...n, read: true } : n)))
    return { before }
  },
  onError: (_error, id, context) => {
    queryClient.setQueryData(['avisos'], context?.before)
    toast.add({
      title: 'O aviso não foi marcado como lido',
      description: 'A conexão caiu. Ele continua na lista.',
      type: 'danger',
      actionProps: { children: 'Tentar de novo', onClick: () => markRead(id) },
    })
  },
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['avisos'] }),
})
```

- O `cancelQueries` antes de mudar impede que uma resposta velha em voo
  sobrescreva o que a pessoa acabou de fazer.
- O `onSettled` revalida nos dois caminhos: o servidor tem a última palavra.
- Duas mudanças seguidas no mesmo item guardam a foto de antes da primeira, e
  não da segunda; senão a volta para no meio.

## Texto

- O sucesso otimista não ganha aviso: a mudança na tela já é o aviso. "Marcado
  como lido" num `Toast` a cada clique é ruído.
- A volta diz o que não aconteceu e como ficou: "O aviso não foi marcado como
  lido. Ele continua na lista." Nunca só "Erro".
- O botão do aviso repete a ação: "Tentar de novo".

## Acessibilidade

- Quem usa leitor de tela não vê o item mudar de lugar: as peças que reordenam
  (`Kanban`, `SortableList`) anunciam a posição nova, e o aviso da volta é
  lido quando entra.
- A volta não pode levar o foco embora: o foco fica no controle que a pessoa
  tocou, agora no estado antigo.

## No celular e no nativo

No celular a rede cai mais, e a volta acontece mais. O `useToast` do
`@rivocode/ui-native` leva o mesmo `actionProps`, com `onPress` no lugar do
`onClick`. O `Kanban` não porta: no celular mover um cartão é um menu "Mover
para", e o menu também muda a tela antes de o servidor responder.

## Os blocos que o aplicam

- [Quadro de atendimento](https://ds.rivocode.com.br/blocos#quadro-de-atendimento)
