# Roteador e dados

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](/instalacao).

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

```sh
npm install react-router
```

```tsx
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:

```tsx
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:

```tsx
'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

```sh
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.

```tsx
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:

```tsx
<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:

```tsx
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`.

```sh
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`:

```tsx
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:

```tsx
<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:

```tsx
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:

```tsx
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:

```tsx
import { router } from 'expo-router'
import { Link } from '@rivocode/ui-native'

<Link href="/pedidos" onPress={() => router.push('/pedidos')}>Ver pedidos</Link>
```
