Roteador e dados
O link do seu roteador com o desenho da casa, e a consulta nos quatro finais.
A biblioteca desenha a tela, e não cria rota nem busca dado: isso é do seu aplicativo, e a escolha da ferramenta também. Esta página mostra como ligar as peças ao roteador que você usar (React Router, TanStack Router ou o do Next) e a uma camada de dados, com o TanStack Query de exemplo.
Nenhum deles é dependência do @rivocode/ui, e nem vai ser. As peças
recebem um link por render e o estado da consulta por prop (data,
isLoading, isError, onRetry), então funcionam com qualquer roteador e com
fetch na mão. O que está aqui é só a ligação, que cabe em poucas linhas no
seu projeto. O rivocode-ui create já entrega a casca ligada ao roteador que
você escolher, como na Instalação.
O padrão, em qualquer roteador
O Button, o MenuLinkItem e o SidebarMenuItem recebem o link do roteador
pelo render. A tag continua sendo de link, e o desenho é o da peça. Sem o
render, o item da barra lateral é um <a href> comum, e cada clique
recarrega a página inteira.
O Link do roteador e o da biblioteca têm o mesmo nome, e por isso um deles é
renomeado na importação.
Com o React Router
npm install react-router
import { Link as RouterLink, useLocation } from 'react-router'
import { Button, MenuLinkItem, SidebarMenuItem } from '@rivocode/ui'
const { pathname } = useLocation()
<Button render={<RouterLink to="/pedidos/novo" />}>Novo pedido</Button>
<MenuLinkItem render={<RouterLink to="/pedidos" />}>Pedidos</MenuLinkItem>
<SidebarMenuItem render={<RouterLink to="/pedidos" />} active={pathname === '/pedidos'}>
Pedidos
</SidebarMenuItem>
Cada tela entra na rota com lazy, e só é baixada quando alguém a abre:
import { createBrowserRouter } from 'react-router'
export const router = createBrowserRouter([
{
path: '/',
Component: Shell,
children: [
{
path: 'pedidos',
lazy: async () => ({ Component: (await import('../features/pedidos/pedidos-page')).PedidosPage }),
},
],
},
])
Com o Next
O Link de next/link entra pelo mesmo render, num arquivo de cliente, e o
usePathname diz o item ativo:
'use client'
import RouterLink from 'next/link'
import { usePathname } from 'next/navigation'
import { SidebarMenuItem } from '@rivocode/ui'
const pathname = usePathname()
<SidebarMenuItem render={<RouterLink href="/pedidos" />} active={pathname === '/pedidos'}>
Pedidos
</SidebarMenuItem>
Com o TanStack Router
npm install @tanstack/react-router
O link da casa, com a rota tipada
O createLink do Router embrulha o Link da biblioteca. O resultado tem o
desenho daqui e o to do Router: rota que não existe é erro de tipo, e os
parâmetros da rota são cobrados.
import { createLink, type LinkComponent } from '@tanstack/react-router'
import { Link } from '@rivocode/ui'
const RivoLink = createLink(Link)
export const AppLink: LinkComponent<typeof Link> = (props) => (
<RivoLink preload="intent" {...props} />
)
Crie esse arquivo uma vez no projeto e use o AppLink no lugar do Link. As
props da peça continuam valendo ao lado das do Router:
<AppLink to="/pedidos/$id" params={{ id: '4816' }}>Pedido 4816</AppLink>
<AppLink to="/pedidos" tone="neutral" underline="hover">Pedidos</AppLink>
O preload="intent" começa a carregar a rota quando o ponteiro passa por
cima do link, antes do clique. Tire-o se a rota for cara de carregar.
Botão, item de menu e barra lateral que navegam
O mesmo render do padrão, com o Link do TanStack Router:
import { Link as RouterLink } from '@tanstack/react-router'
import { Button, SidebarMenuItem } from '@rivocode/ui'
<Button render={<RouterLink to="/pedidos/novo" />}>Novo pedido</Button>
<SidebarMenuItem render={<RouterLink to="/pedidos" />} active>
Pedidos
</SidebarMenuItem>
Dados com o TanStack Query
O exemplo é o TanStack Query, mas o contrato é de prop: SWR, Apollo ou um
useEffect com fetch entregam os mesmos data, isLoading e isError.
npm install @tanstack/react-query
Os quatro finais de uma consulta
O QueryBoundary desenha o carregando, o erro, o vazio e o dado. A consulta
entrega os três primeiros, e o filho em função recebe o dado já sem o
undefined:
import { useQuery } from '@tanstack/react-query'
import { QueryBoundary } from '@rivocode/ui'
const query = useQuery({ queryKey: ['pedidos'], queryFn: fetchOrders })
<QueryBoundary
data={query.data}
isLoading={query.isLoading}
isError={query.isError}
isFetching={query.isFetching}
isRefetchError={query.isRefetchError}
onRetry={() => query.refetch()}
empty={{
title: 'Nenhum pedido por aqui',
description: 'Quando a loja vender pela primeira vez, o pedido aparece nesta lista.',
}}
>
{(orders) => <OrderList orders={orders} />}
</QueryBoundary>
Em isLoading vai o isLoading, e não o isFetching. O isLoading só é
verdadeiro na primeira busca, quando ainda não há nada para mostrar. O
isFetching também é verdadeiro quando a consulta busca de novo em segundo
plano, e por isso tem prop própria: com ele, o dado fica na tela, a região ganha
aria-busy e uma barra fina corre no topo, em vez de o esqueleto cobrir o que a
pessoa já estava lendo. O isRefetchError faz o mesmo pela falha: a busca que
revalida falhou, o dado anterior fica, e um aviso acima dele oferece nova
tentativa.
Tabela e gráfico
O DataTable e o ChartContainer já têm os quatro finais embutidos, com os
mesmos nomes de prop, então a consulta entra direto neles:
<DataTable
data={query.data}
isLoading={query.isLoading}
isError={query.isError}
onRetry={() => query.refetch()}
rowKey={(order) => order.id}
columns={columns}
/>
Paginação no servidor
O DataTable pagina sozinho quando recebe a lista inteira. Quando é o
servidor que pagina, a página atual vira parte da chave da consulta, e o
Pagination troca de página:
import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { DataTable, Pagination } from '@rivocode/ui'
const [page, setPage] = useState(1)
const query = useQuery({
queryKey: ['pedidos', page],
queryFn: () => fetchOrders(page),
placeholderData: keepPreviousData,
})
<div aria-busy={query.isFetching}>
<DataTable
data={query.data?.items}
isLoading={query.isLoading}
isError={query.isError}
onRetry={() => query.refetch()}
rowKey={(order) => order.id}
columns={columns}
/>
</div>
{query.data && (
<Pagination page={page} pageCount={query.data.pageCount} onPageChange={setPage} />
)}
O keepPreviousData segura a página anterior na tela enquanto a próxima
chega, em vez de piscar o esqueleto a cada clique. O aria-busy avisa o
leitor de tela de que a tabela está sendo atualizada.
Salvar e avisar
Na escrita, o useMutation liga o loading do Button e o useToast avisa
o resultado. Invalidar a chave faz a lista buscar de novo:
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { Button, useToast } from '@rivocode/ui'
const toast = useToast()
const queryClient = useQueryClient()
const { mutate: registerOrder, isPending: registering } = useMutation({
mutationFn: createOrder,
onSuccess: (order) => {
toast.add({ title: `Pedido ${order.number} registrado`, type: 'success' })
queryClient.invalidateQueries({ queryKey: ['pedidos'] })
},
onError: () => toast.add({ title: 'O pedido não foi registrado', type: 'danger' }),
})
<Button loading={registering} onClick={() => registerOrder()}>
Registrar pedido
</Button>
No React Native
O TanStack Query funciona igual, e o QueryBoundary do @rivocode/ui-native
tem os mesmos nomes de prop. Os roteadores da web não são para o celular: no
Expo quem navega é o Expo Router, e as peças nativas navegam por onPress, porque ali
não há âncora para trocar:
import { router } from 'expo-router'
import { Link } from '@rivocode/ui-native'
<Link href="/pedidos" onPress={() => router.push('/pedidos')}>Ver pedidos</Link>