Pular para o conteúdo

Roteador e dados

O link do seu roteador com o desenho da casa, e a consulta nos quatro finais.

/roteador-e-dados.mdmarkdown cru, para quem lê com agent em vez de olho

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

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