# Experiência degradada

Quando um pedaço da tela falha, ele diz isso no lugar dele, e o resto continua
funcionando. Degrade, não bloqueie.

## O problema

O gráfico de faturamento não carregou, e a página inteira vira "Algo deu
errado", levando junto a lista de pedidos que tinha carregado. Ou o contrário:
o serviço de estoque caiu, e a tela mostra "Nenhum produto", que a pessoa lê
como verdade e vai repor o que não falta. Os dois erram no mesmo ponto: tratam
o que falhou como se fosse a tela toda, ou como se fosse vazio.

## Quando usar

Toda tela que junta mais de uma fonte: o painel com quatro consultas, o
registro com o histórico de outro serviço, a listagem com o estoque de outro
sistema, o app que perdeu a conexão no meio do uso. E toda falha parcial de um
serviço de fora: a busca por CEP que não respondeu, o cálculo de frete fora do
ar, o intermediador de pagamento lento.

## Quando não usar

- **Quando nada da tela funciona sem o que falhou**, a página de erro inteira é
  a resposta honesta: o `Result` do 500, do sem conexão ou da manutenção
  ([erros.md](https://ds.rivocode.com.br/padroes/erros.md)).
- **Quando o dado que falhou é a condição da ação**, a ação para: emitir a nota
  sem a resposta da prefeitura não é degradar, é emitir errado.
- **Quando a falha é da ação, e não da consulta**, é o "deu errado" dos quatro
  momentos, no botão e no `Alert`: [erros.md](https://ds.rivocode.com.br/padroes/erros.md).

## As peças

- `QueryBoundary` por região, cada um com o seu `isError`, `onRetry` e o texto
  do pedaço.
- `DataTable` e `QueryBoundary` com `isRefetchError`: o dado velho fica na tela
  com o aviso de que não está atualizado.
- `Alert` no lugar do pedaço que falhou, com a frase do que continua.
- `Banner`: a falha que atravessa a tela inteira (sem conexão, serviço de fora
  instável), uma faixa só, no topo.
- `useNetworkStatus`: online ou offline.
- `Result` com a ilustração `Offline`: quando nada funciona sem rede.

## Comportamento

- **Cada região carrega e falha sozinha.** Um `QueryBoundary` por consulta, e
  não um em volta da página. O gráfico que falhou mostra o erro do tamanho do
  gráfico, com "Tentar de novo", e a tabela ao lado segue com os dados dela.
- **Dado indisponível não vira estado vazio.** "Não foi possível carregar o
  estoque" é uma coisa; "Nenhum produto em estoque" é outra, e trocar uma pela
  outra faz a pessoa agir sobre o que não é verdade. Na célula de uma tabela, o
  valor que não veio é "Indisponível", e não zero nem traço.
- **O dado velho fica, com a data.** Revalidação que falhou mantém o que já
  estava, com "Atualizado às 14:02. Não foi possível atualizar agora." O
  `isRefetchError` com dado na mão faz isso nas peças de consulta.
- **A ação que depende do que falhou para; o resto não.** Sem o frete, o
  carrinho continua editável, e só o "Finalizar compra" espera, com o motivo.
- **No máximo umas cinco mensagens por página.** Se mais que isso falhou, a
  falha é de outra camada: troque as cinco por um `Banner` no topo ("O
  faturamento está fora do ar. Os números desta página podem estar
  desatualizados.") e deixe as regiões quietas, com o dado velho ou o espaço
  reservado.
- **Sem conexão, o que já está na tela continua legível**, e o que precisa de
  rede diz isso no próprio controle. Ao voltar a conexão, a tela revalida
  sozinha, sem pedir para recarregar.

```tsx
<div className="grid gap-8 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
  <QueryBoundary
    data={revenue.data}
    isLoading={revenue.isPending}
    isError={revenue.isError}
    onRetry={revenue.refetch}
    errorTitle="Não foi possível carregar o faturamento"
    errorMessage="O resto do painel continua atualizado. Tente de novo em alguns minutos."
  >
    {(data) => <RevenueChart data={data} />}
  </QueryBoundary>
  <QueryBoundary
    data={orders.data}
    isLoading={orders.isPending}
    isError={orders.isError}
    onRetry={orders.refetch}
    errorTitle="Não foi possível carregar os pedidos"
    errorMessage="O sistema de pedidos não respondeu."
  >
    {(list) => <RecentOrders orders={list} />}
  </QueryBoundary>
</div>
```

## Texto

- O pedaço que falhou diz o que não veio e o que continua: "Não foi possível
  carregar o faturamento. O resto do painel continua atualizado."
- Quem falhou, quando isso muda o que a pessoa faz: "O sistema da operadora
  não respondeu", "A busca por CEP está fora do ar. Preencha o endereço à mão."
- O dado velho diz a hora: "Atualizado às 14:02".
- O "Indisponível" da célula não é "0" nem "-": zero é um valor, e traço quer
  dizer "não se aplica".

## Acessibilidade

- Cada região que falha anuncia o erro dela uma vez, e não a página inteira em
  coro: cinco `role="alert"` disparando juntos atropelam o leitor de tela, e é
  mais um motivo do limite de cinco mensagens.
- O "Tentar de novo" de cada região tem nome que diz qual: "Tentar carregar o
  faturamento de novo", ou o título da região ligado ao botão.
- A região que falhou guarda o espaço dela, para a tela não pular quando a
  segunda tentativa der certo.

## No celular e no nativo

No celular a conexão cai mais, e entra e sai no meio do uso. O
`useNetworkStatus` é do web; no app, o estado da rede vem da biblioteca de rede
do projeto. O `QueryBoundary` e o `DataList` do `@rivocode/ui-native` portam o
`isError`, o `isRefetchError` e o `onRetry` com os mesmos nomes, e o `Banner`
também existe lá. O que ficou guardado no aparelho continua
aberto sem rede, e diz de quando é.

## Os blocos que o aplicam

- [Sem conexão](https://ds.rivocode.com.br/blocos#sem-conexao)
- [Manutenção programada](https://ds.rivocode.com.br/blocos#manutencao-programada)
