Pular para o conteúdo

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.

/padroes/otimista.mdo mesmo arquivo que a skill entrega ao agente

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

  • 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".
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

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.