Pagination

Pagination

Navegação entre páginas de uma lista, tabela ou histórico de ordens. Composta sobre o Button (mesma variante, mesmo foco, mesmo alvo de toque): Pagination não reimplementa nada visual, só organiza links de página dentro de uma estrutura semântica de navegação.

Quando usar

• Listas ou tabelas paginadas no servidor (histórico de operações, extrato, ordens). O componente não sabe quantas páginas existem nem qual é a atual: isso é responsabilidade de quem monta a lista de PaginationItem/PaginationLink.
• Quando cada página tem uma URL própria (os links são <a href> de verdade, não botões com onClick): isso é o que torna a paginação navegável, indexável e compatível com abrir-em-nova-aba.

Quando não usar

• Rolagem infinita ou "carregar mais": não há conceito de página aqui, use um botão comum (Button) ou um observer de scroll.
• Paginação de poucos itens sem necessidade de navegar direto para uma página específica: às vezes só PaginationPrevious/PaginationNext já bastam, sem números de página no meio.

Anatomia

<Pagination>                            <nav aria-label="pagination">
  <PaginationContent>                   <ul>
    <PaginationItem>                    <li>
      <PaginationPrevious href="..." />       Button ghost, com seta e "Anterior"
    <PaginationItem>
      <PaginationLink href="...">1</PaginationLink>    Button ghost (ou secondary se isActive)
    <PaginationItem>
      <PaginationEllipsis />            reticencia, decorativa (aria-hidden)
    <PaginationItem>
      <PaginationNext href="..." />           Button ghost, com "Proxima" e seta

Variantes

PaginationLink não usa cva própria: ela repassa variant/size para o buttonVariants do Button. A página atual (isActive) usa variant="secondary"; as demais usam variant="ghost". size aceita as mesmas chaves do Button (default, lg, icon); o padrão é icon (24x24, para números de página) e PaginationPrevious/PaginationNext usam default (para caber o texto ao lado do ícone).

Acessibilidade

• A raiz é sempre <nav aria-label="pagination">: um leitor de tela anuncia o bloco como uma região de navegação nomeada, não uma lista qualquer.
• A página atual recebe aria-current="page" em PaginationLink, além do destaque visual (variant="secondary"). É assim que o usuário de leitor de tela sabe qual página está aberta sem depender só da cor.
• PaginationPrevious/PaginationNext têm aria-label próprio ("Ir para a página anterior" / "Ir para a próxima página"): o texto visível ("Anterior"/"Próxima") some em telas pequenas (hidden sm:block), mas o nome acessível do link não depende dele.
• PaginationEllipsis é puramente decorativa: aria-hidden="true" e role="presentation", com um texto "Mais páginas" reservado para leitor de tela (sr-only) caso o ícone sozinho não seja suficiente em algum contexto de auditoria.