# Paginator

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente standalone de paginação que exibe botões de navegação de páginas, seletor de itens por página e atalhos para a primeira e última página. Emite o evento `pageChange` a cada mudança de página ou de tamanho de página.

## Quando usar

- Listagens e tabelas com dados paginados no servidor ou no cliente
- Sempre que o volume de registros tornar impraticável exibir tudo de uma vez
- Quando o usuário precisa controlar quantos itens são exibidos por página

## Quando não usar

- Para listas com poucos itens que cabem em uma única tela — exiba todos sem paginação
- Quando a navegação é por rolagem infinita (infinite scroll) — use um mecanismo de scroll virtual

## Instalação

```typescript
import { PaginatorComponent } from '@seniorsistemas/angular-components/paginator';

@Component({
  standalone: true,
  imports: [PaginatorComponent],
})
export class MeuComponent {}
```

## Uso básico

```html
<s-paginator
  [totalRecords]="total"
  [(rows)]="tamanhoPagina"
  (pageChange)="onPaginaMudou($event)"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `totalRecords` | `number` | — | Sim | Número total de registros disponíveis para paginação |
| `rows` | `number` | `10` | Não | Número de itens por página. Suporta two-way binding via `[(rows)]` |
| `rowsPerPageOptions` | `number[]` | `[10, 20, 50, 100, 200]` | Não | Opções disponíveis no seletor de itens por página |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `pageChange` | `OutputEmitterRef<PageChange>` | Emitido sempre que a página atual ou o número de itens por página muda |

### Tipos

```typescript
interface PageChange {
  page: number;       // Índice da página atual (base 0)
  pageCount: number;  // Total de páginas
  rows: number;       // Número de itens por página
  first: number;      // Índice do primeiro registro da página atual
}
```

## Exemplos

### Paginação básica

```html
<s-paginator
  [totalRecords]="120"
  [rows]="10"
  [rowsPerPageOptions]="[10, 20, 50, 100, 200]"
  (pageChange)="onPageChange($event)"
></s-paginator>
```

### Com two-way binding nas linhas

```html
<s-paginator
  [totalRecords]="totalRegistros"
  [(rows)]="itensPorPagina"
  (pageChange)="carregarPagina($event)"
></s-paginator>
```

### Grande volume de dados

```html
<s-paginator
  [totalRecords]="1000"
  [rows]="20"
  [rowsPerPageOptions]="[10, 20, 50, 100, 200]"
  (pageChange)="onPageChange($event)"
></s-paginator>
```

### Com opções personalizadas de itens por página

```html
<s-paginator
  [totalRecords]="80"
  [rows]="10"
  [rowsPerPageOptions]="[5, 10, 25]"
  (pageChange)="onPageChange($event)"
></s-paginator>
```

## Acessibilidade

- Os botões de navegação (primeira página, anterior, próxima, última) são elementos `<button>` nativos com estados desabilitados declarados via `disabled`
- Os botões de número de página são clicáveis via teclado (Tab + Enter/Space)
- O seletor de itens por página usa o componente `Select` com suporte a navegação por teclado

## Componentes relacionados

- [`Table`](../table/README.md) — tabela de dados que integra o Paginator para navegação entre páginas
- [`Select`](../select/README.md) — componente de seleção usado internamente para o seletor de itens por página