@etus/ui 0.1.0

package/src/components/navigation/Pagination/README.md

@@ -0,0 +1,635 @@
+# Pagination
+
+## Visão Geral
+
+O Pagination permite navegacao entre multiplas paginas de conteudo. E essencial para listas longas, resultados de busca, tabelas de dados e qualquer interface que precise dividir conteudo em partes gerenciaveis.
+
+### Classificacao Atomica
+- **Categoria**: Molecules
+- **Subcategoria**: Navigation
+
+### Casos de Uso Comuns
+- Listas de resultados de busca
+- Tabelas de dados paginadas
+- Galerias de imagens
+- Feeds de noticias ou posts
+- Catalogos de produtos
+
+### Relacao com Outros Componentes
+- **Table/DataTable**: Frequentemente usado junto
+- **List**: Para listas paginadas
+- **Button**: Base para os controles
+- **Select**: Para selecao de pagina direta
+
+## Design Specs
+
+### Subcomponentes
+
+- **Pagination**: Container `<nav>` principal
+- **PaginationContent**: Lista de items `<ul>`
+- **PaginationItem**: Item individual `<li>`
+- **PaginationLink**: Link para pagina especifica
+- **PaginationPrevious**: Botao "anterior"
+- **PaginationNext**: Botao "proximo"
+- **PaginationEllipsis**: Indicador de paginas omitidas
+
+### Variantes de PaginationLink
+
+| Estado | Descricao | Classes |
+|--------|-----------|---------|
+| `isActive` | Pagina atual | `variant="outline"` |
+| `default` | Outras paginas | `variant="ghost"` |
+
+### Tamanhos
+
+Baseado nos tamanhos do Button:
+- **icon**: Apenas numero, `size="icon"`
+- **default**: Com texto "Previous"/"Next", `size="default"`
+
+### Estados
+
+- **Default**: Links normais
+- **Active**: Pagina atual destacada
+- **Disabled**: Sem mais paginas (first/last)
+- **Hover**: `hover:bg-accent`
+- **Focus**: Focus ring visivel
+
+### Tokens de Design
+
+#### Cores
+- Background: Transparente ou `bg-background`
+- Active: `variant="outline"` com border
+- Text: Herda do Button
+- Ellipsis: `text-muted-foreground`
+
+#### Espacamento
+- Container: `mx-auto w-full justify-center`
+- Items gap: `gap-1`
+- Previous/Next padding: `gap-1 px-2.5`
+
+#### Tipografia
+- Numbers: Herda do Button `text-sm`
+- Labels: `text-sm` ("Previous", "Next")
+
+#### Icones
+- Previous: `ChevronLeftIcon`
+- Next: `ChevronRightIcon`
+- Ellipsis: `MoreHorizontalIcon` em `size-4`
+- Ellipsis container: `size-9`
+
+### Consideracoes de Responsividade
+- **Mobile**: Oculta texto "Previous"/"Next" em `sm:hidden/block`
+- **Desktop**: Mostra texto completo
+- Numero de paginas pode ser reduzido em telas menores
+
+## API
+
+### Componentes Exportados
+
+#### Pagination
+Container principal da navegacao.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `React.ComponentProps<"nav">` | - | Props nativas |
+
+#### PaginationContent
+Lista que contem os items.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `React.ComponentProps<"ul">` | - | Props nativas |
+
+#### PaginationItem
+Container de item individual.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `...props` | `React.ComponentProps<"li">` | - | Props nativas |
+
+#### PaginationLink
+Link para pagina especifica.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `isActive` | `boolean` | `false` | Se e a pagina atual |
+| `size` | `"default" \| "icon"` | `"icon"` | Tamanho do botao |
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `React.ComponentProps<"a">` | - | Props nativas |
+
+#### PaginationPrevious
+Link para pagina anterior.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `PaginationLinkProps` | - | Props do PaginationLink |
+
+#### PaginationNext
+Link para proxima pagina.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `PaginationLinkProps` | - | Props do PaginationLink |
+
+#### PaginationEllipsis
+Indicador de paginas omitidas.
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `''` | Classes adicionais |
+| `...props` | `React.ComponentProps<"span">` | - | Props nativas |
+
+### Interfaces TypeScript
+
+```typescript
+import { Button, buttonVariants } from "@/components/ui/button"
+
+type PaginationLinkProps = {
+  isActive?: boolean
+} & Pick<React.ComponentProps<typeof Button>, "size"> &
+  React.ComponentProps<"a">
+
+type PaginationProps = React.ComponentProps<"nav">
+
+type PaginationContentProps = React.ComponentProps<"ul">
+
+type PaginationItemProps = React.ComponentProps<"li">
+
+type PaginationEllipsisProps = React.ComponentProps<"span">
+```
+
+### Comparacao com Referencias
+
+| Feature | ETUS | MUI | Ant Design | Chakra | Mantine |
+|---------|------|-----|------------|--------|---------|
+| Compound Components | Sim | Nao | Nao | Nao | Nao |
+| Ellipsis | Sim | Sim | Sim | Sim | Sim |
+| Size Variants | Sim | Sim | Sim | Sim | Sim |
+| Custom Ranges | Manual | Sim | Sim | Nao | Sim |
+| Page Size Select | Manual | Sim | Sim | Nao | Sim |
+| Jump to Page | Manual | Sim | Sim | Nao | Nao |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="navigation"`: Implicito no `<nav>`
+- `aria-label="pagination"`: Identifica a navegacao
+- `aria-current="page"`: Na pagina atual
+- `aria-label`: Em Previous/Next para contexto
+- `aria-hidden="true"`: No ellipsis
+- Screen reader text: "More pages" no ellipsis
+
+### Navegacao por Teclado
+- `Tab`: Navega entre links de pagina
+- `Shift + Tab`: Navegacao reversa
+- `Enter`: Ativa link focado
+- `Space`: Ativa link focado
+
+### Contraste e Legibilidade
+- Contraste WCAG AA
+- Focus ring visivel
+- Pagina ativa claramente distinguivel
+
+### Tecnologias Assistivas
+- Navegacao anunciada como "pagination"
+- Pagina atual anunciada
+- Botoes Previous/Next com labels claros
+
+### Conformidade WCAG
+- **Nivel alvo**: WCAG 2.1 AA
+- **Criterios**:
+  - 1.3.1 Info and Relationships
+  - 2.1.1 Keyboard
+  - 2.4.4 Link Purpose
+  - 4.1.2 Name, Role, Value
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+} from "@etus/ui"
+
+function BasicPagination() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#" />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">1</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#" isActive>2</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">3</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+### Com Ellipsis
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@etus/ui"
+
+function PaginationWithEllipsis() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#" />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">1</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">4</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#" isActive>5</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">6</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">10</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+### Controlado com State
+
+```tsx
+import { useState } from "react"
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@etus/ui"
+
+function ControlledPagination({ totalPages = 10 }) {
+  const [currentPage, setCurrentPage] = useState(1)
+
+  const getPageNumbers = () => {
+    const pages = []
+    const showEllipsisStart = currentPage > 3
+    const showEllipsisEnd = currentPage < totalPages - 2
+
+    if (showEllipsisStart) {
+      pages.push(1)
+      pages.push("ellipsis-start")
+    }
+
+    for (let i = Math.max(1, currentPage - 1); i <= Math.min(totalPages, currentPage + 1); i++) {
+      if (!pages.includes(i)) pages.push(i)
+    }
+
+    if (showEllipsisEnd) {
+      pages.push("ellipsis-end")
+      pages.push(totalPages)
+    }
+
+    return pages
+  }
+
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious
+            href="#"
+            onClick={(e) => {
+              e.preventDefault()
+              setCurrentPage((p) => Math.max(1, p - 1))
+            }}
+            aria-disabled={currentPage === 1}
+            className={currentPage === 1 ? "pointer-events-none opacity-50" : ""}
+          />
+        </PaginationItem>
+
+        {getPageNumbers().map((page, idx) =>
+          typeof page === "string" ? (
+            <PaginationItem key={page}>
+              <PaginationEllipsis />
+            </PaginationItem>
+          ) : (
+            <PaginationItem key={page}>
+              <PaginationLink
+                href="#"
+                isActive={currentPage === page}
+                onClick={(e) => {
+                  e.preventDefault()
+                  setCurrentPage(page)
+                }}
+              >
+                {page}
+              </PaginationLink>
+            </PaginationItem>
+          )
+        )}
+
+        <PaginationItem>
+          <PaginationNext
+            href="#"
+            onClick={(e) => {
+              e.preventDefault()
+              setCurrentPage((p) => Math.min(totalPages, p + 1))
+            }}
+            aria-disabled={currentPage === totalPages}
+            className={currentPage === totalPages ? "pointer-events-none opacity-50" : ""}
+          />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+### Com React Router
+
+```tsx
+import { Link, useSearchParams } from "react-router-dom"
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+} from "@etus/ui"
+
+function RouterPagination({ totalPages }: { totalPages: number }) {
+  const [searchParams] = useSearchParams()
+  const currentPage = Number(searchParams.get("page")) || 1
+
+  const createPageUrl = (page: number) => `?page=${page}`
+
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious asChild>
+            <Link
+              to={createPageUrl(Math.max(1, currentPage - 1))}
+              aria-disabled={currentPage === 1}
+            >
+              Previous
+            </Link>
+          </PaginationPrevious>
+        </PaginationItem>
+
+        {Array.from({ length: totalPages }, (_, i) => i + 1).map((page) => (
+          <PaginationItem key={page}>
+            <PaginationLink asChild isActive={currentPage === page}>
+              <Link to={createPageUrl(page)}>{page}</Link>
+            </PaginationLink>
+          </PaginationItem>
+        ))}
+
+        <PaginationItem>
+          <PaginationNext asChild>
+            <Link
+              to={createPageUrl(Math.min(totalPages, currentPage + 1))}
+              aria-disabled={currentPage === totalPages}
+            >
+              Next
+            </Link>
+          </PaginationNext>
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+### Com Informacao de Resultados
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+} from "@etus/ui"
+
+function PaginationWithInfo({
+  currentPage,
+  totalPages,
+  totalItems,
+  itemsPerPage,
+  onPageChange,
+}) {
+  const startItem = (currentPage - 1) * itemsPerPage + 1
+  const endItem = Math.min(currentPage * itemsPerPage, totalItems)
+
+  return (
+    <div className="flex items-center justify-between">
+      <p className="text-sm text-muted-foreground">
+        Showing <span className="font-medium">{startItem}</span> to{" "}
+        <span className="font-medium">{endItem}</span> of{" "}
+        <span className="font-medium">{totalItems}</span> results
+      </p>
+
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious
+              href="#"
+              onClick={(e) => {
+                e.preventDefault()
+                onPageChange(currentPage - 1)
+              }}
+              aria-disabled={currentPage === 1}
+            />
+          </PaginationItem>
+          {/* Page numbers */}
+          <PaginationItem>
+            <PaginationNext
+              href="#"
+              onClick={(e) => {
+                e.preventDefault()
+                onPageChange(currentPage + 1)
+              }}
+              aria-disabled={currentPage === totalPages}
+            />
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao de paginas
+- Estado ativo correto
+- Navegacao funcionando
+
+#### Testes de Integracao
+- Mudanca de pagina
+- URL updates (com router)
+- Dados atualizados
+
+#### Testes de Acessibilidade
+- aria-current na pagina ativa
+- Navegacao por teclado
+- Labels corretos
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect, vi } from "vitest"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+} from "./Pagination"
+
+describe("Pagination", () => {
+  it("renders navigation with correct role", () => {
+    render(
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationLink href="#">1</PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    )
+
+    expect(screen.getByRole("navigation")).toHaveAttribute(
+      "aria-label",
+      "pagination"
+    )
+  })
+
+  it("marks active page with aria-current", () => {
+    render(
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationLink href="#">1</PaginationLink>
+          </PaginationItem>
+          <PaginationItem>
+            <PaginationLink href="#" isActive>2</PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    )
+
+    expect(screen.getByText("2")).toHaveAttribute("aria-current", "page")
+  })
+
+  it("has correct aria-labels on prev/next", () => {
+    render(
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious href="#" />
+          </PaginationItem>
+          <PaginationItem>
+            <PaginationNext href="#" />
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    )
+
+    expect(screen.getByLabelText("Go to previous page")).toBeInTheDocument()
+    expect(screen.getByLabelText("Go to next page")).toBeInTheDocument()
+  })
+
+  it("navigates pages on click", async () => {
+    const onPageChange = vi.fn()
+
+    render(
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationLink
+              href="#"
+              onClick={(e) => {
+                e.preventDefault()
+                onPageChange(3)
+              }}
+            >
+              3
+            </PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    )
+
+    await userEvent.click(screen.getByText("3"))
+    expect(onPageChange).toHaveBeenCalledWith(3)
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Componentes compostos para flexibilidade maxima
+- Usa buttonVariants para consistencia visual
+- aria-current="page" para pagina ativa
+- Ellipsis e aria-hidden com texto sr-only
+
+## Referências
+
+- [WAI-ARIA Pagination](https://www.w3.org/WAI/ARIA/apg/patterns/pagination/)
+- [Shadcn/ui Pagination](https://ui.shadcn.com/docs/components/pagination)
+- [MDN: aria-current](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)

package/src/components/navigation/Pagination/index.ts

@@ -0,0 +1,17 @@
+export * from './Pagination'
+export {
+  paginationContentVariants,
+  paginationEllipsisVariants,
+  paginationNextVariants,
+  paginationPreviousVariants,
+  paginationVariants,
+} from './Pagination.variants'
+export type {
+  PaginationContentProps,
+  PaginationEllipsisProps,
+  PaginationItemProps,
+  PaginationLinkProps,
+  PaginationNextProps,
+  PaginationPreviousProps,
+  PaginationProps,
+} from './Pagination.types'