# Espera

A tela que espera mostra o que vem na forma do que vem, pelo tempo que a espera
dura, e não tira do lugar o que a pessoa já estava lendo.

## O problema

Toda ação e toda consulta têm um intervalo entre o pedido e a resposta, e é
nele que a tela parece quebrada. Giro no meio da página esconde o que já estava
certo; esqueleto que volta a cada filtro tira o ponto de leitura; um minuto de
`loading` sem número parece travado, e a pessoa recarrega no meio do lote.

## Quando usar

Em toda ação que faz requisição e em toda consulta que preenche a tela. O
desenho muda com a duração:

| Dura | A tela | Peça |
|---|---|---|
| até 1 s | nada muda além do próprio controle: o clique responde, o dado troca quando chega | o estado de `active` das peças |
| 1 a 10 s | a ação espera no botão, a consulta na forma do conteúdo | `loading`, `Skeleton`, `QueryBoundary` |
| mais de 10 s | quanto falta, o que está acontecendo, e um jeito de parar | `Progress` com `value` e `showValue`, e um `Button` "Cancelar importação" |

## Quando não usar

- **Nada de giro de tela inteira**, nem tarja que cobre a página: o `Spinner`
  é para o espaço pequeno onde o esqueleto não cabe, e não para a área de
  trabalho.
- **Nada de esqueleto depois da primeira carga.** Trocar de página, de filtro
  ou de ordem segura a lista de antes com a barra fina do `isFetching`.
- **Ação que não é exceção não espera**: otimista é o padrão, e a ação aparece
  feita na hora, pelo [otimista.md](https://ds.rivocode.com.br/padroes/otimista.md). A espera no botão fica para
  dinheiro, efeito externo, o que não tem volta e o que depende da resposta.
- **Espera longa que pode seguir sozinha não prende a tela**: vira aviso.

## As peças

- `Button` com `loading`: a ação espera no próprio botão, que recusa o segundo
  clique e anuncia ocupado.
- `Skeleton` e o `skeleton` do `QueryBoundary`: a forma do conteúdo, com a
  largura da coluna.
- `DataTable` e `QueryBoundary` com `isLoading` e `isFetching`: o primeiro é a
  primeira carga, o segundo a revalidação com o dado na mão. Com `isFetching`,
  os filhos do `QueryBoundary` vão numa caixa que veste o `className`, ou o
  `classNames.content` quando ele vem; numa coluna de chat ou de lista que
  precisa de altura, a altura vai em quem a caixa veste, senão a lista cresce e
  empurra o campo de escrever para fora.
- `Progress` com `value`, `max` e `showValue`: o quanto, na espera longa.
- `toast.promise` do `useToast`: a espera longa que sai da tela.

## Comportamento

### O esqueleto é da primeira carga

O esqueleto aparece quando não há nada na tela. Depois dela, a lista de antes
fica até a nova chegar, com a barra fina do `isFetching`: piscar a tabela
inteira a cada clique tira o ponto de leitura de quem estava comparando. Com
TanStack Query, `placeholderData: keepPreviousData` segura a página de antes, e
o `isPending` só fica verdadeiro na primeira vez.

```tsx
const invoices = useQuery({
  queryKey: ['notas', page, filters],
  queryFn: () => listInvoices(page, filters),
  placeholderData: keepPreviousData,
})

<DataTable
  data={invoices.data?.items}
  rowCount={invoices.data?.total ?? 0}
  columns={COLUMNS}
  rowKey={(invoice) => invoice.id}
  isLoading={invoices.isPending}
  isFetching={invoices.isFetching}
  isError={invoices.isError}
  onRetry={invoices.refetch}
/>
```

O esqueleto tem a forma do conteúdo que vem, com a largura da coluna, para a
tela não pular quando os dados chegarem. Retângulo cinza do tamanho da página
inteira não é esqueleto, é giro com outra cor.

### O que passa de 10 s mostra o quanto

Importar a planilha, emitir em lote, enviar arquivo grande: `Progress` com o
número ("128 de 400 notas"), o nome do item da vez quando o total não se
conhece, e a saída para cancelar.

```tsx
<Progress label="Emitindo as notas do mês" value={done} max={total} showValue />
```

Quando a espera longa pode seguir sem a pessoa olhando, ela sai da tela e vira
aviso: `toast.promise` troca o "Emitindo…" pelo resultado num aviso só.

### A tela não some por baixo da pessoa

- **Não mova o que ela vai clicar.** Conteúdo que chega depois entra abaixo do
  ponto de leitura, ou reserva o espaço desde o começo.
- **Ação que demora fica presa ao botão**, com `loading` e o botão
  desabilitado, e nunca uma tarja que cobre a tela.
- **Confirmação não muda de lugar.** O botão que confirma fica sempre no mesmo
  canto do rodapé, em todos os diálogos do produto.
- **Fechar uma folha ou um diálogo devolve o foco ao gatilho**, senão o teclado
  recomeça do topo da página. As peças da casa já fazem isso; layout escrito à
  mão não.

## Texto

- O botão em espera continua dizendo a ação ("Emitir nota"); o `loading`
  desenha o resto. Trocar o rótulo por "Aguarde…" muda a largura do botão.
- A espera longa diz o que está acontecendo com o objeto e o número:
  "Emitindo as notas do mês", "128 de 400 notas". Nunca "Processando…".
- O cancelar nomeia o que para: "Cancelar importação", e diz o que fica feito
  ("As 128 notas já emitidas continuam valendo").

## Acessibilidade

- O `loading` do `Button` põe `aria-busy` e mantém o foco no botão; ele não
  some nem troca de lugar.
- O `Progress` com `label` anuncia o nome e o valor; `aria-valuetext` diz o
  número na forma da tela ("128 de 400 notas").
- A barra fina do `isFetching` sai com nome (`labels.refreshing` no
  `DataTable`), e a área revalidando leva `aria-busy`.
- Quem pediu para reduzir movimento vê o esqueleto parado: as peças já leem a
  preferência.

## No celular e no nativo

O `Skeleton`, o `QueryBoundary`, o `Progress` e o `loading` do `Button` existem
no `@rivocode/ui-native` com os mesmos nomes. O `DataList` do nativo porta o
`isFetching` e o `isRefetchError` com os nomes do web: as linhas ficam, e a
barra fina corre no topo. No celular a espera longa ganha mais um motivo para
sair da tela: a pessoa troca de app no meio, e o aviso com o resultado é o que
ela encontra na volta.

## Os blocos que o aplicam

- [Painel](https://ds.rivocode.com.br/blocos#painel)
- [Listagem de produtos](https://ds.rivocode.com.br/blocos#listagem)
- [Vazio, erro e carregando](https://ds.rivocode.com.br/blocos#vazio-e-erro)
- [Quadro de atendimento](https://ds.rivocode.com.br/blocos#quadro-de-atendimento)
