# Confirmar, desfazer, ou nada

A decisão que mais gente erra tem uma regra só: **o custo de desfazer decide**.

## O problema

Confirmação cobra de todo mundo, toda vez, para proteger o engano de vez em
quando, e a pessoa aprende a clicar sem ler, que é exatamente o estado que a
confirmação existia para evitar. A tela que pede três confirmações para
arquivar e nenhuma para apagar de vez erra nos dois lados.

## Quando usar

Em toda ação que muda ou apaga alguma coisa. A tabela decide:

| A ação | O que ela ganha |
|---|---|
| Reversível e barata (marcar, arquivar, reordenar) | **nada.** Faz e pronto |
| Reversível mas confusa de reverter (excluir rascunho, remover linha) | **desfazer**, num aviso, com prazo |
| Sem volta e de efeito externo (emitir, cancelar nota, apagar de vez) | **confirmar**, com `AlertDialog` |

**Desfazer ganha de confirmar sempre que for possível.** Desfazer só cobra de
quem errou. Confirmação só se justifica quando desfazer não existe: a
prefeitura já recebeu, o e-mail já saiu, o registro já foi embora.

O excluir tem ainda um terceiro degrau, para o que leva muita coisa junto: veja
os três níveis em [verbos-de-acao.md](https://ds.rivocode.com.br/padroes/verbos-de-acao.md).

## Quando não usar

- **Nunca confirme duas vezes a mesma coisa.** Se a revisão do wizard já mostrou
  o que vai acontecer, o diálogo em cima dela é ruído.
- **Nunca confirme o que dava para desfazer**: arquivar, remover da lista,
  excluir rascunho.
- **Nunca deixe sem proteção o que não tem volta**: emitir, cancelar nota,
  excluir de vez disparando no clique.
- **Desfazer não é para o que tem efeito externo.** O "Desfazer" de um e-mail
  enviado mente; segure o envio por alguns segundos ou confirme antes.

## As peças

- `useToast` com `actionProps` e `timeout` maior que o padrão: o desfazer.
- `AlertDialog`: a confirmação que não se dispensa clicando fora.
- `Popconfirm`: a confirmação local e pequena, ancorada no próprio gatilho;
  abaixo de 640px ela vira folha de baixo.
- `ToolCall` com aprovação: a confirmação que o assistente pede antes de agir.

## Comportamento

O desfazer mora no aviso que confirma a ação, e a ação acontece na hora:

```tsx
const { mutate: restore } = useMutation({ mutationFn: restoreDraft })
const { mutate: remove } = useMutation({
  mutationFn: removeDraft,
  onSuccess: (draft) =>
    toast.add({
      title: `Rascunho "${draft.title}" excluído`,
      timeout: 8000,
      actionProps: { children: 'Desfazer', onClick: () => restore(draft.id) },
    }),
})
```

Quando confirmar for a resposta certa, o diálogo nomeia o objeto e o efeito, e o
escape nomeia o estado que fica:

```tsx
const { mutate: cancel, isPending: canceling } = useMutation({ mutationFn: cancelInvoice })

<AlertDialog>
  <AlertDialogTrigger render={<Button variant="danger" />}>Cancelar nota</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogTitle>Cancelar a nota 4813?</AlertDialogTitle>
    <AlertDialogDescription>
      A prefeitura recebe o cancelamento e o cliente é avisado. Não dá para desfazer.
    </AlertDialogDescription>
    <AlertDialogFooter>
      <AlertDialogClose render={<Button variant="secondary" />}>Manter nota</AlertDialogClose>
      <AlertDialogClose render={<Button variant="danger" loading={canceling} />} onClick={() => cancel()}>
        Cancelar nota
      </AlertDialogClose>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

- O botão que confirma fica sempre no mesmo canto do rodapé, em todos os
  diálogos do produto.
- A ação em curso segura o diálogo aberto com o `loading` no botão, e o erro
  aparece dentro dele, sem fechar.
- O desfazer vale enquanto o aviso está na tela; depois do prazo, a ação é
  definitiva. Prazo curto demais é armadilha: 8 segundos é o piso.

## Texto

- O título é uma **pergunta que nomeia o objeto**: "Cancelar a nota 4813?", e
  não "Tem certeza?".
- A descrição diz o efeito, quem é avisado e que não se desfaz.
- O escape nomeia o estado que fica: "Manter nota", "Continuar editando", e
  nunca "Cancelar" ao lado de uma ação que também se chama cancelar.
- O aviso do desfazer diz o que aconteceu, com o nome: "Rascunho 'Proposta de
  maio' excluído". O botão é só "Desfazer".

A forma exata do par de botões está em [texto.md](https://ds.rivocode.com.br/skill/reference/texto.md).

## Acessibilidade

- O `AlertDialog` leva o foco ao escape, e não ao que apaga: o Enter apressado
  não destrói nada. Fechar devolve o foco ao gatilho.
- O aviso com desfazer é lido quando entra, e o botão dele se alcança pelo
  teclado: `F6` leva o foco para a área de avisos. O desfazer também precisa de
  um caminho fora do aviso quando o prazo é curto para quem navega devagar: a
  lixeira, o "Restaurar" do item, o histórico.

## No celular e no nativo

O `Popconfirm` vira `AlertDialog` no `@rivocode/ui-native`: painel ancorado não
é idioma de toque. O `AlertDialog` nativo é controlado, com `onConfirm`,
`onCancel` e `labels`; `onConfirm` que devolve promessa segura o modal em
espera. O desfazer no aviso existe com `actionProps` e `onPress`.

## Os blocos que o aplicam

- [Configurações](https://ds.rivocode.com.br/blocos#configuracoes)
- [Assistente de agendamento](https://ds.rivocode.com.br/blocos#assistente-de-agendamento)
