Padrões de UX / Ação e resposta
Fazer antes de o servidor responder
O padrão de toda ação: aparece feita na hora, e volta atrás com aviso quando o servidor recusa. Só dinheiro, efeito externo e o que não tem volta esperam.
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.
- 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
useMutationdo TanStack Query, comonMutate,onErroreonSettled.useToastpara o aviso de que a volta aconteceu, com "Tentar de novo" emactionProps.- As peças que já trabalham assim por baixo:
Kanban(oonMovemuda o dado na hora),SortableList,Switch,Rating.
Comportamento
A regra tem duas metades, e a segunda é a que se esquece:
- Mude a tela já, guardando como ela estava.
- Se o servidor recusar, volte ao que estava e diga, num aviso com "Tentar de novo".
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
cancelQueriesantes de mudar impede que uma resposta velha em voo sobrescreva o que a pessoa acabou de fazer. - O
onSettledrevalida 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
Toasta 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.