Pular para o conteúdo
Feedback

QueryBoundary

/componentes/query-boundary.mdmarkdown cru, para quem lê com agent em vez de olho

Com dados

Últimos pedidos

Conteúdo carregado
  • Mariana TelesEnviado
  • Henrique BastosSeparando

Carregando com o molde da tela

Últimos pedidos

Carregando…

Revalidando com o dado na tela

Últimos pedidos

Conteúdo carregado
x
  • Mariana TelesEnviado
  • Henrique BastosSeparando

A revalidação falhou, e o dado fica

Últimos pedidos

Conteúdo carregado
  • Mariana TelesEnviado
  • Henrique BastosSeparando

Resposta que não é lista

Conteúdo carregado

Nenhum pedido no período

Amplie o intervalo de datas para ver pedidos mais antigos.

Os quatro finais

Carregando…

Uma folha, e não uma lista

Conteúdo carregado
Cliente
Mariana Teles
E-mail
mariana.teles@exemplo.com
Cidade
Curitiba, PR
Importar
import { QueryBoundary } from '@rivocode/ui'

Quando usar

Os quatro finais de uma consulta (carregando, erro, vazio e dados) em volta de qualquer conteúdo.

O DataTable e o ChartContainer já os têm embutidos, e o resto da tela não: cada cartão de resumo, cada folha de detalhes e cada lista desenhada à mão reescreve a mesma escada de if. Esta peça é essa escada, com os mesmos nomes de prop das duas: isLoading, isError, onRetry, errorTitle, errorMessage e empty.

<QueryBoundary
  data={query.data}
  isLoading={query.isLoading}
  isError={query.isError}
  onRetry={query.refetch}
  empty={{
    title: 'Nenhum pedido por aqui',
    description: 'Quando a loja vender pela primeira vez, o pedido aparece nesta lista.',
  }}
>
  {(orders) => orders.map((order) => <p key={order.id}>{order.customer}</p>)}
</QueryBoundary>

Não conhece React Query, e isso é de propósito: entram três booleanos e uma resposta, e funciona igual com fetch na mão, com SWR ou com server component.

A ordem é a mesma das duas irmãs: erro vence carregando, e vazio só vale depois que a resposta chegou. Sem isso, uma nova busca sobre um erro pisca "nenhum resultado" antes de mostrar o problema.

O filho pode ser função

Como função, ela só é chamada depois que o dado chegou, e recebe o data sem o undefined, que é exatamente o ! que toda tela escrevia aqui. Como nó, serve a quem não precisa do dado para desenhar:

<QueryBoundary data={customer}>
  {(customer) => <DescriptionItem label="Cliente">{customer.name}</DescriptionItem>}
</QueryBoundary>

Com filho em função, data indefinido continua sendo espera mesmo com isLoading={false}. Não há o que entregar à função, e é a regra do DataTable. Com filho em nó, isLoading manda sozinho quando você o passa: o nó não depende do dado para existir.

A função não atravessa a fronteira de um server component: ela não é serializável. De um server component, passe o filho como nó.

Os filhos saem como você os escreveu, sem embrulho. A peça não põe uma <div> em volta do que ela devolve: uma moldura invisível quebraria o grid ou o flex de quem está por fora, e o defeito só apareceria no navegador.

A espera

O padrão são três linhas de Skeleton, e elas seguram altura sem prometer forma nenhuma. skeletonRows muda quantas, o mesmo nome do DataTable.

Quando a forma do que vem importa (e ela quase sempre importa), passe o seu molde em skeleton:

<QueryBoundary
  isLoading={query.isLoading}
  skeleton={
    <div className="flex flex-col gap-2">
      <Skeleton className="h-4 w-40" />
      <Skeleton className="h-4 w-24" />
    </div>
  }
>

Não é Spinner de propósito, e é a mesma escolha das duas irmãs: o giro no meio do vazio não reserva altura, então a página pula quando o conteúdo chega. O Spinner continua sendo o certo para a espera que não tem forma: o botão que envia, a ação que não desenha nada.

O nó do carregando sai com aria-busy="true". O Skeleton se esconde do leitor de tela de propósito, e é no contêiner que o aviso de carregamento pertence.

A espera se anuncia em voz alta. aria-busy num nó sem papel não é lido por leitor de tela nenhum: ele descreve o estado de uma região, e só chega a quem já está dentro dela. Quem esperava ouvia silêncio, e a chegada do dado, que troca a tela inteira, também não dizia nada. As irmãs publicam a mesma região viva (role="status" aria-live="polite", marcada com data-rc-status), que diz "Carregando…" enquanto a consulta não volta e "Conteúdo carregado" quando ela volta. Ela existe antes de o texto mudar e é o mesmo nó do primeiro ao último estado: região que nasce já com o texto dentro não dispara anúncio nenhum.

Dado velho enquanto revalida

isLoading e isError descrevem a primeira busca, e o caso mais comum de tela real é outro: já há dado na tela e uma nova busca está correndo, porque a janela voltou ao foco, a chave foi invalidada ou o intervalo venceu. Para ele existem duas props, com os nomes do TanStack Query:

<QueryBoundary
  data={query.data}
  isLoading={query.isLoading}
  isError={query.isError}
  isFetching={query.isFetching}
  isRefetchError={query.isRefetchError}
  onRetry={() => query.refetch()}
>
  {(orders) => orders.map((order) => <p key={order.id}>{order.customer}</p>)}
</QueryBoundary>

isFetching não troca nada do que a pessoa está lendo. Com dado na mão, os filhos ficam, a região que os envolve ganha aria-busy="true" e uma barra fina corre logo acima dela, com o nome "Atualizando…" para o leitor de tela. Não há esqueleto por cima do dado, e a região viva que diz "Carregando…" fica calada: revalidação acontece a cada volta de foco, e anunciá-la toda vez seria ruído. A região é uma caixa em volta dos filhos, e ela veste o className da peça, ou o classNames.content quando ele vem: numa coluna que precisa de altura (min-h-0 flex-1, a lista de um chat), a altura chega aos filhos por ali. Sem dado, isFetching é a primeira busca, e quem desenha é o carregando de sempre. Por isso ele pode receber o isFetching do TanStack Query direto, sem conta, e serve igual para o isValidating do SWR.

Passar isFetching, verdadeiro ou falso, põe os filhos numa caixa: é ela que leva o aria-busy e segura a barra. A caixa é a mesma do começo ao fim, para os filhos não remontarem a cada busca, e sem a prop ela não existe: quem não revalida continua sem embrulho nenhum. Se o filho era item de grid ou flex-1, vista a caixa por classNames.content.

isRefetchError mantém o dado e avisa acima dele. Quando a busca que revalida falha, o que estava na tela continua sendo a melhor informação que existe: apagá-lo para mostrar o erro tira da pessoa o que ela estava usando e não lhe dá nada no lugar. Com dado na mão, isRefetchError vence o isError: os filhos ficam, e um aviso em tom de atenção (warning, e não danger, porque a tela segue utilizável) diz "Não foi possível atualizar" e que os dados abaixo são da última busca que deu certo, com o botão do onRetry. Sem dado, ele vira o erro de sempre, que ocupa o lugar dos filhos.

Sem isRefetchError, nada mudou: isError continua vencendo tudo e apagando a tela, inclusive com dado. É o que faz da prop uma escolha, e não uma quebra.

labels.refreshing (padrão "Atualizando…") é o nome da barra, e labels.refetchError e labels.stale são o título e a linha do aviso de dado velho.

As irmãs falam a mesma língua. DataTable, VirtualList, ChartContainer, EventCalendar e Gantt aceitam o mesmo isFetching e o mesmo isRefetchError, com as mesmas chaves de labels, a mesma barra e o mesmo aviso, e no React Native o DataList e o ChartContainer também. A peça que já resolve os quatro finais não precisa de um QueryBoundary em volta para manter o dado na revalidação.

Quem decide o vazio

A peça decide sozinha, pelo data: lista de tamanho zero e null são vazio, e undefined é "ainda não chegou". Sem isLoading, é ele quem liga o carregando.

Para a resposta que não é uma lista ({ items: [], total: 0 } é a paginada de sempre), quem responde é isEmpty, que vence a contagem quando vem:

<QueryBoundary data={page} isEmpty={page.total === 0} empty={{ ... }}>

Se empty chegar sem que nada consiga decidir, a peça avisa no console em desenvolvimento. O estado vazio que nunca aparece é silencioso: os filhos desenham sobre o nada, e ninguém descobre até um cliente abrir a tela sem dados.

Sem empty, não há estado vazio. A resposta vazia cai nos filhos, e eles desenham o vazio deles. A exceção é o null com filho em função: sem dado para entregar e sem vazio configurado, a peça não desenha nada.

A descrição é obrigatória pelo mesmo motivo do DataTable: "nenhum resultado" transfere para a pessoa o trabalho de descobrir por quê, e ela quase nunca descobre.

O vazio de página leva desenho. empty.illustration recebe o mesmo que a illustration do EmptyState, e vence o icon: a lista que ocupa a página ou a seção e ainda não tem nada mostra o EmptyList; o vazio pequeno, dentro de um cartão estreito, fica no icon. Em produto da RivoCode, o desenho é o Bacalhau, na pose que a página dele dá para cada vazio.

import { EmptyList } from '@rivocode/ui/illustrations'

<QueryBoundary
  data={query.data}
  isLoading={query.isLoading}
  isError={query.isError}
  onRetry={query.refetch}
  empty={{
    illustration: <EmptyList size="md" />,
    title: 'Os pedidos aparecem aqui',
    description: 'Quando a loja vender pela primeira vez, o pedido aparece nesta lista.',
  }}
>
  {(orders) => orders.map((order) => <p key={order.id}>{order.customer}</p>)}
</QueryBoundary>

O erro de página também leva desenho. errorIllustration recebe o desenho do erro que toma a página ou a seção, e troca o aviso vermelho pelo Result de perigo: o desenho no topo, o errorTitle, a errorMessage e o botão do onRetry embaixo. O erro pequeno, dentro de um cartão estreito, continua no aviso, sem desenho. Em produto da RivoCode, o desenho é o Bacalhau triste, pose="sad" motion="shake".

import { ServerError } from '@rivocode/ui/illustrations'

<QueryBoundary
  data={query.data}
  isLoading={query.isLoading}
  isError={query.isError}
  onRetry={query.refetch}
  errorTitle="Não foi possível carregar as conversas"
  errorIllustration={<ServerError size="md" />}
>
  {(chats) => chats.map((chat) => <p key={chat.id}>{chat.contact}</p>)}
</QueryBoundary>

O nome é o mesmo no DataTable e no ChartContainer, e no React Native no QueryBoundary, na DataList e no ChartContainer.

Os textos que a peça escreve

errorTitle (padrão "Não foi possível carregar") e errorMessage (padrão "Tente de novo em alguns minutos.") são o par do estado de erro, com os mesmos nomes e o mesmo papel que têm no DataTable e no ChartContainer: uma tela que carrega três blocos precisa dizer qual deles falhou, e um produto que não fala português precisa dizer isso em outra língua.

labels.retry (padrão "Tentar de novo") é o nome do botão que executa o onRetry, e existe pelo mesmo motivo: sem ele, a tela traduzida saía com o título em inglês e o botão em português, que é pior do que tudo em português. A chave e o padrão são os mesmos nas peças de consulta, e labels.loading e labels.loaded trocam o que o leitor de tela ouve quando a consulta sai e quando volta.

Sem onRetry não há botão de nova tentativa. Aviso com botão que não leva a lugar nenhum é pior que aviso sem botão.

Movimento

O Alert do erro e o EmptyState do vazio entram pelo movimento deles. O conteúdo que você entrega não ganha entrada daqui: sem isFetching, a moldura não embrulha os seus filhos numa caixa, porque uma caixa a mais muda o layout de quem usa (o filho que era flex-1, o item de grade). Quem tem caixa própria entra sozinho: o DataTable esmaece o corpo, e o gráfico se desenha.

Partes

classNames veste cada final: loading, error, empty. O className veste os três de uma vez, que é onde mora a moldura que reserva a altura (className="min-h-40"). E não veste os filhos, que são seus.

As três partes da revalidação têm nome próprio: content é a caixa dos filhos, que só existe com isFetching; refreshing, a barra fina do topo; e stale, o aviso de dado velho. O className não chega a nenhuma delas.

Quando não usar

Não embrulhe DataTable nem ChartContainer. As duas já recebem os quatro finais, com estas mesmas props, e desenham a espera no formato do que elas mesmas mostram: linhas falsas de tabela, barras falsas de gráfico. Por fora, uma moldura só teria um esqueleto genérico para oferecer, e os dois estados de erro empilhados apareceriam juntos no dia em que a consulta falhasse.

Para o estado vazio sozinho (uma tela que nunca carrega nada, um resultado que já está na mão), use EmptyState. Para o aviso de erro que não é o fim de uma consulta, Alert. Para a marca de lugar solta dentro de um bloco que já tem os outros finais tratados, Skeleton. Esta peça existe para os quatro juntos, e na ordem; um só deles não paga o embrulho.

Ela também não captura exceção de renderização: QueryBoundary mostra o erro que a consulta reportou em isError, e não o que estourou dentro dos filhos. Para esse, o que existe é o error boundary do React.

No React Native

Traduz com os mesmos nomes de prop e a mesma ordem: erro vence carregando, e vazio só vale depois que a resposta chegou. O children também aceita função aqui, que é o que justifica a peça existir: ela entrega o dado já sem undefined, e mata o ! que a tela escrevia.

Quatro diferenças de tipo, todas porque texto no nativo mora dentro de um Text: errorTitle, errorMessage, empty.title e empty.description são string. O empty.icon atravessa, e aceita também a função do EmptyState nativo, que entrega a cor e o tamanho. É a mesma nota que o ChartContainer já carrega.

A revalidação também porta: isFetching deixa os filhos na tela, diz busy ao leitor de tela e pulsa uma barra fina no topo, e isRefetchError mantém o dado com o aviso de atenção acima dele. A caixa dos filhos é uma View, que só existe com isFetching, e ela é flex-1: ocupa a altura que o pai dá, e o filho flex-1 - a ScrollArea da tela - continua ocupando também. Dentro de uma rolagem ela fica da altura do conteúdo; num pai de altura fixa com irmãos embaixo, ela os empurra para o fim, e classNames={{ content: "flex-none" }} a devolve à altura do conteúdo.

classNames porta com os nomes do web: loading, error e empty, e as três da revalidação, content, refreshing e stale. O className continua vestindo os três finais, como no web, e a parte veste só o seu: a moldura que reserva a altura vale igual para os três, mas o erro que pede borda não pode levar a borda para o esqueleto. Sem seletor de descendente no React Native, a parte é o único jeito de vestir um final sem vestir os outros.

O esqueleto genérico fica na peça, e não vem de quem chama: sem ele, isLoading sem skeleton colapsaria a tela para altura zero e ela pularia quando o dado chegasse. No celular isso dói mais, porque não há barra de rolagem nem indicador de rede para explicar a espera.

API

PropTipoPadrão
classNames

Classe por parte: `loading`, `error`, `empty`, e as tres da revalidacao - `content` (a caixa dos filhos, so com `isFetching`), `refreshing` (a barra) e `stale` (o aviso de dado velho).

Partial<Record<"content" | "empty" | "error" | "loading" | "refreshing" | "stale", string>>sem padrão
data

A resposta da consulta.

Datasem padrão
empty

O que aparece quando a consulta volta vazia.

{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; illustration?: ReactNode; }sem padrão
errorIllustration

O desenho do erro de pagina ou de secao: o `ServerError` de `@rivocode/ui/illustrations`, ou o Bacalhau `pose="sad" motion="shake"` em produto da RivoCode.

ReactNodesem padrão
errorMessageReactNode"Tente de novo em alguns minutos."
errorTitle

O titulo do aviso de erro.

ReactNode"Não foi possível carregar"
isEmpty

Diz o vazio no lugar do `data`, para a resposta que nao e uma lista: `isEmpty={page.total === 0}`.

booleansem padrão
isErrorbooleansem padrão
isFetching

Ha uma busca correndo, inclusive a que revalida o dado que ja esta na tela - o `isFetching` do TanStack Query, o `isValidating` do SWR.

booleansem padrão
isLoadingbooleansem padrão
isRefetchError

A ultima busca falhou, mas o dado anterior continua valido - o `isRefetchError` do TanStack Query.

booleansem padrão
labels

Os textos da peca, para trocar o idioma: `retry` e o botao que executa o `onRetry`, "Tentar de novo" sem ele - a mesma chave em todas as pecas que resolvem os quatro finais.

Partial<QueryBoundaryLabels>sem padrão
onRetry

Sem isto, o erro nao oferece nova tentativa.

(() => void)sem padrão
skeleton

O desenho da espera, no formato do que vem depois - a lista de tres linhas, o cartao, a folha de campos.

ReactNodesem padrão
skeletonRows

Quantas linhas falsas a espera generica mostra.

number3

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@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.