# Verbos de ação

Cada verbo diz um efeito, e o mesmo efeito tem o mesmo verbo no produto
inteiro. Adicionar não é criar, remover não é excluir, e limpar não apaga nada
que exista fora do campo.

## O problema

"Remover" que apaga o cliente do sistema, quando a pessoa queria só tirá-lo da
lista de convidados. "Excluir" num botão e "Apagar" no outro para a mesma
coisa, e a pessoa se pergunta se são diferentes. "Limpar" que zera o
formulário inteiro sem volta. O verbo errado é o padrão enganoso que ninguém
quis fazer.

## Quando usar

Em todo botão, item de menu, título de confirmação e aviso de resultado.

| Verbo | O efeito | Volta? | Exemplo |
|---|---|---|---|
| Adicionar | põe algo que já existe dentro de outra coisa | sim, por Remover | "Adicionar participante", "Adicionar ao carrinho" |
| Criar | faz nascer um registro novo, que não existia | sim, por Excluir | "Criar cliente", "Criar proposta" |
| Remover | tira de dentro de outra coisa, e o item continua existindo | sim, por Adicionar | "Remover da lista", "Remover participante" |
| Excluir | apaga o registro, para todos | só pelo desfazer ou pela lixeira | "Excluir rascunho", "Excluir a conta" |
| Arquivar | tira da vista do dia a dia, e guarda | sim, por Restaurar | "Arquivar pedido" |
| Limpar | esvazia um campo, um filtro ou uma seleção, na tela | sim, digitando de novo | "Limpar filtros", "Limpar seleção" |
| Restaurar | traz de volta o que foi arquivado ou excluído, como estava | | "Restaurar pedido" |
| Descartar | joga fora mudanças que ainda não foram salvas | não | "Descartar mudanças" |
| Cancelar | desfaz um efeito que já saiu, perante terceiros | não | "Cancelar nota", "Cancelar assinatura" |

## Quando não usar

- **Nunca "Remover" para o que apaga do sistema**: é "Excluir".
- **Nunca "Excluir" para o que só sai de uma lista**: é "Remover".
- **Nunca "Cancelar" como escape de um diálogo cuja ação também cancela**: o
  escape nomeia o que fica, "Manter nota" ([texto.md](https://ds.rivocode.com.br/skill/reference/texto.md)).
- **Nunca sinônimo para variar**: "Apagar", "Deletar" e "Excluir" na mesma
  tela fazem a pessoa procurar a diferença que não existe.
- **Nunca o verbo sozinho**: "Excluir" sem o objeto não diz o que vai, e é o
  objeto que deixa perceber que se clicou na linha errada.

## As peças

- `Button` com `variant="danger"`: o que exclui ou cancela. Remover e limpar não
  são `danger`. Na linha da tabela ou no rodapé do cartão, ao lado de ações
  `ghost`, o gatilho do excluir é `variant="ghost"` com `tone="danger"`; a confirmação dentro
  do `AlertDialog` continua `danger`.
- `useToast` com `actionProps`: o excluir com desfazer.
- `Popconfirm` e `AlertDialog`: o excluir com confirmação.
- `Input` dentro do `AlertDialog`: o excluir que pede o nome digitado.
- `Menu` com `MenuItem`: o lugar das ações da linha, com o excluir por último e
  separado.

## Comportamento

### Excluir em três níveis de proteção

A proteção cresce com o que a exclusão leva junto, e não com o medo de quem
desenha a tela. O padrão é o primeiro nível
([confirmar-ou-desfazer.md](https://ds.rivocode.com.br/padroes/confirmar-ou-desfazer.md)).

| Nível | Quando | Como |
|---|---|---|
| 1. Direto, com desfazer | um item, recuperável por algum tempo (rascunho, linha, comentário) | exclui na hora, e o aviso oferece "Desfazer" por 8 segundos ou mais |
| 2. Confirmar | sem volta, ou com efeito em outras pessoas (o cliente com notas, o arquivo compartilhado, o lote) | `AlertDialog` com o objeto no título e o efeito na descrição |
| 3. Digitar o nome | leva muita coisa junto e não volta: a conta, a empresa, o projeto com tudo dentro | o `AlertDialog` pede o nome exato, e o botão só age quando ele confere |

```tsx
const [typed, setTyped] = useState('')
const matches = typed.trim() === company.name
const { mutate: removeCompany, isPending: removing } = useMutation({ mutationFn: deleteCompany })

<AlertDialog onOpenChange={(open) => !open && setTyped('')}>
  <AlertDialogTrigger render={<Button variant="danger" />}>Excluir a empresa</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogTitle>{`Excluir ${company.name}?`}</AlertDialogTitle>
    <AlertDialogDescription>
      As 1.240 notas, os 86 clientes e os acessos da equipe são apagados para todos. Não dá para desfazer.
    </AlertDialogDescription>
    <Field>
      <FieldLabel>{`Digite ${company.name} para confirmar`}</FieldLabel>
      <Input value={typed} onValueChange={setTyped} placeholder={company.name} autoComplete="off" />
    </Field>
    <AlertDialogFooter>
      <AlertDialogClose render={<Button variant="secondary" />}>Manter a empresa</AlertDialogClose>
      <Button variant="danger" disabled={!matches} loading={removing} onClick={() => removeCompany(company.id)}>
        Excluir a empresa
      </Button>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

O nível 3 é o único lugar em que o botão desabilitado é a resposta certa: a
condição está escrita no rótulo do campo logo acima, e a pessoa vê o que
falta.

### O excluir fica longe do caminho

No menu da linha, o excluir é o último item, separado por `MenuSeparator`. Na
página do registro, ele mora numa seção própria no fim, e não ao lado do
salvar.

## Texto

- Verbo no infinitivo e o objeto: "Excluir rascunho", "Remover participante".
- O resultado repete o verbo no particípio: "Rascunho excluído", "Participante
  removido", "Pedido restaurado".
- A descrição do excluir diz o que vai junto e quem perde: "As 1.240 notas e os
  acessos da equipe são apagados para todos."
- O escape nomeia o que fica: "Manter rascunho", "Manter a empresa".

## Acessibilidade

- O ícone de lixeira sozinho precisa de nome com o verbo e o objeto:
  `IconButton` com `label="Excluir a nota 4813"`.
- O `AlertDialog` começa com o foco no escape: o Enter apressado não apaga
  nada.
- O campo de digitar o nome tem rótulo visível, e o `autoComplete="off"` impede
  que o navegador preencha a confirmação sozinho.
- Cor nunca é o sinal sozinha: o `danger` vem com o verbo que diz o efeito.

## No celular e no nativo

No celular o excluir da linha mora no menu de ações ou no deslizar, nunca como
o primeiro toque. No `@rivocode/ui-native` o `AlertDialog` é controlado, com
`onConfirm`, `onCancel` e `labels`, e o `onConfirm` que devolve promessa
segura o modal em espera. Ele não recebe filho, então o nível 3 no app é uma
tela própria (ou uma `Sheet`) com o campo e o botão que só age quando o nome
confere.

## Os blocos que o aplicam

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