# A forma da tarefa

Os outros arquivos decidem a forma da **tela**. Este decide a forma da
**tarefa**: em quantas telas ela cabe, onde a pessoa confirma, o que acontece
quando ela erra, e como ela volta atrás.

É a parte que nenhuma guarda mede. Uma tela pode estar perfeita no contraste, no
token e no teclado, e ainda pedir três confirmações para algo reversível e
nenhuma para o que apaga.

Este arquivo é o índice. Ele guarda a regra que vale para toda ação (os quatro
momentos) e a pergunta que vale para toda tela (o que deixa o produto esperto).
Cada tarefa tem o seu padrão num arquivo próprio, com o mesmo esqueleto: o
problema, quando usar, quando não usar, as peças, comportamento, texto,
acessibilidade, no celular e no nativo, e os blocos que o aplicam. Os mesmos
arquivos estão publicados em <https://ds.rivocode.com.br/padroes>.

## Conteúdo

- Os quatro momentos de toda ação
- Os padrões, um por tarefa
- O que deixa o produto esperto

## Os quatro momentos

Toda ação que a pessoa dispara passa por quatro momentos, e a tela desenha os
quatro. Entregar só o "antes" é o defeito mais comum de tela gerada.

| Momento | O que a tela mostra | Peça |
|---|---|---|
| Antes | o botão diz o efeito, com verbo e objeto: "Emitir nota" | `Button` |
| Durante | por padrão, nada espera: a tela já mostra feito, e volta se o servidor recusar. Nas exceções (dinheiro, efeito externo, sem volta), o próprio botão trabalha e recusa o segundo clique; o conteúdo que vem aparece na forma dele | `onMutate`; `loading`, `Skeleton`, `QueryBoundary` |
| Deu certo | ação pequena: um aviso que diz o que aconteceu. Fim de fluxo longo: o desfecho no lugar do formulário, com o próximo passo | `useToast`; `Result` |
| Deu errado | o que falhou, quem falhou e o que fazer, com "Tentar de novo" quando repetir resolve; o que foi digitado continua nos campos | `Alert`, `onRetry`, `Result tone="danger"` |

**Durante começa otimista.** Toda ação aparece feita na hora, com a volta
guardada no `onMutate` e devolvida no `onError`. O `loading` no botão fica para
a lista fechada de exceções de [otimista.md](otimista.md): dinheiro, efeito fora
do sistema, sem volta, servidor que recusa muito e resposta que traz o que a
tela mostra. "Emitir nota" espera; "Favoritar" não.

**Durante não é giro de tela inteira.** O `Spinner` no meio da página tira a
referência do que a pessoa estava fazendo e esconde o que já estava certo. A
ação espera no botão (`loading`), e a consulta espera no lugar dela
(`Skeleton` com a largura da coluna, ou o `skeleton` do `QueryBoundary`). O
tamanho da espera decide o resto: [espera.md](espera.md).

**Deu certo tem dois tamanhos.** Salvar um campo, arquivar, copiar: o aviso
passa, e a tela continua onde estava. Fechar um checkout, concluir um cadastro,
enviar um formulário longo: o `Result` toma o lugar do formulário, leva o foco
ao título e oferece o próximo passo em `actions`. Trocar o formulário por um
parágrafo de "Sucesso!" deixa a pessoa olhando para uma tela que acabou.

**Deu errado guarda o que foi digitado.** O `reset` do formulário mora no
caminho do sucesso, nunca no `catch` nem no `onError`. O resto está em
[erros.md](erros.md).

```tsx
const toast = useToast()

const { mutate: restore } = useMutation({ mutationFn: restoreInvoice })
const { mutate: archive } = useMutation({
  mutationFn: archiveInvoice,
  onMutate: async (id) => {
    await queryClient.cancelQueries({ queryKey: ['notas'] })
    const before = queryClient.getQueryData(['notas'])
    queryClient.setQueryData(['notas'], (list) => list.filter((n) => n.id !== id))
    return { before }
  },
  onError: (_error, id, context) => {
    queryClient.setQueryData(['notas'], context?.before)
    toast.add({
      title: 'A nota não foi arquivada',
      description: 'A conexão caiu. Ela continua na lista.',
      type: 'danger',
      actionProps: { children: 'Tentar de novo', onClick: () => archive(id) },
    })
  },
  onSuccess: (invoice) =>
    toast.add({
      title: `Nota ${invoice.number} arquivada`,
      timeout: 8000,
      actionProps: { children: 'Desfazer', onClick: () => restore(invoice.id) },
    }),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['notas'] }),
})

<Button variant="secondary" onClick={() => archive(invoice.id)}>
  Arquivar nota
</Button>
```

O botão não leva `loading`: a nota sai da lista no clique, e é isso que diz que
deu certo. O `loading` fica para as exceções, como "Emitir nota" no SKILL.md.

No React Native o aviso tem o mesmo `actionProps`, com `onPress` no lugar do
`onClick`: `actionProps: { children: 'Desfazer', onPress: restore }`. Só o
aviso com botão recebe toque. O `Result` existe nos dois pacotes, e no nativo
anuncia com `announceOnMount` em vez de levar o foco.

## Os padrões, um por tarefa

Abra o padrão da tarefa que está na mesa, e só ele.

| A tarefa | O padrão |
|---|---|
| Esperar: quanto dura, o esqueleto, a espera longa com progresso, a tela que não pula | [espera.md](espera.md) |
| Mostrar feito antes de o servidor responder, e voltar quando ele recusa | [otimista.md](otimista.md) |
| Decidir entre confirmar, desfazer ou nada | [confirmar-ou-desfazer.md](confirmar-ou-desfazer.md) |
| Uma tela ou várias: a checagem do wizard e o wizard bem feito | [wizard.md](wizard.md) |
| Sessão, Pix e reserva que vencem | [prazo.md](prazo.md) |
| Vender sem enganar | [padroes-enganosos.md](padroes-enganosos.md) |
| O que fazer quando dá errado, e os quatro finais de uma consulta | [erros.md](erros.md) |
| Salvar: explícito ou automático, a barra de salvar e o aviso de saída | [salvar.md](salvar.md) |
| Lista e detalhe, e o painel de apoio | [lista-e-detalhe.md](lista-e-detalhe.md) |
| Somente leitura, desabilitado e sem permissão | [estados-de-acesso.md](estados-de-acesso.md) |
| Parte da tela falhou e o resto continua | [experiencia-degradada.md](experiencia-degradada.md) |
| Agir em muitos itens de uma vez | [acoes-em-lote.md](acoes-em-lote.md) |
| Filtrar e buscar uma listagem | [filtros-e-busca.md](filtros-e-busca.md) |
| Escolher onde a mensagem aparece: `Alert`, `Banner`, aviso, central ou `Result` | [canal-de-mensagem.md](canal-de-mensagem.md) |
| Nomear a ação: adicionar, criar, remover, excluir, limpar, restaurar | [verbos-de-acao.md](verbos-de-acao.md) |

## O que deixa o produto esperto

O que separa uma tela correta de uma tela boa de usar é o trabalho que ela
poupa. Antes de entregar, passe por estas oito perguntas.

| Pergunta | O que fazer | Peça |
|---|---|---|
| Dá para preencher sozinho? | CEP que traz o endereço, o valor que vem do serviço escolhido, a data de hoje no vencimento | `PostalCodeField`, `defaultValues` |
| Dá para lembrar? | Filtro, coluna, visão e aba que a pessoa escolheu voltam na próxima visita | `useLocalStorage` |
| O padrão é o mais comum? | O campo já vem com o que 80% escolhe; a exceção é que troca | `defaultValue` |
| Dá para agir sem abrir outra tela? | Editar no lugar, agir em lote, ver o detalhe numa folha | `Editable`, `ActionBar`, `Sheet` |
| Dá para desfazer em vez de confirmar? | Faz na hora e oferece a volta no aviso | `useToast` com `actionProps` |
| Quem usa todo dia tem atalho? | Busca global e as ações mais usadas pelo teclado, com o atalho visível | `Command`, `useHotkeys`, `Kbd` |
| O que é raro está fora do caminho? | Opções avançadas recolhidas, e não misturadas com as de todo dia | `Collapsible` |
| A pessoa sabe que terminou? | Sucesso visível, com o que aconteceu e o próximo passo: "Nota 4816 emitida. Ver PDF" | `useToast`, `Result` |

Uma tela que responde "não" a quase todas funciona, mas cobra da pessoa o
trabalho que o sistema podia ter feito.
