QueryBoundary
Com dados
Últimos pedidos
- Mariana TelesEnviado
- Henrique BastosSeparando
Carregando com o molde da tela
Últimos pedidos
Revalidando com o dado na tela
Últimos pedidos
- Mariana TelesEnviado
- Henrique BastosSeparando
A revalidação falhou, e o dado fica
Últimos pedidos
Não foi possível atualizar
Os dados abaixo são da última busca que deu certo.
- Mariana TelesEnviado
- Henrique BastosSeparando
Resposta que não é lista
Nenhum pedido no período
Amplie o intervalo de datas para ver pedidos mais antigos.
Os quatro finais
Uma folha, e não uma lista
- Cliente
- Mariana Teles
- mariana.teles@exemplo.com
- Cidade
- Curitiba, PR
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
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse 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 |
dataA resposta da consulta. | Data | sem padrão |
emptyO que aparece quando a consulta volta vazia. | { title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; illustration?: ReactNode; } | sem padrão |
errorIllustrationO 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. | ReactNode | sem padrão |
errorMessage | ReactNode | "Tente de novo em alguns minutos." |
errorTitleO titulo do aviso de erro. | ReactNode | "Não foi possível carregar" |
isEmptyDiz o vazio no lugar do `data`, para a resposta que nao e uma lista: `isEmpty={page.total === 0}`. | boolean | sem padrão |
isError | boolean | sem padrão |
isFetchingHa uma busca correndo, inclusive a que revalida o dado que ja esta na tela - o `isFetching` do TanStack Query, o `isValidating` do SWR. | boolean | sem padrão |
isLoading | boolean | sem padrão |
isRefetchErrorA ultima busca falhou, mas o dado anterior continua valido - o `isRefetchError` do TanStack Query. | boolean | sem padrão |
labelsOs 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 |
onRetrySem isto, o erro nao oferece nova tentativa. | (() => void) | sem padrão |
skeletonO desenho da espera, no formato do que vem depois - a lista de tres linhas, o cartao, a folha de campos. | ReactNode | sem padrão |
skeletonRowsQuantas linhas falsas a espera generica mostra. | number | 3 |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.