# Table

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

Módulo de tabela que estende o `p-table` do PrimeNG com componentes e diretivas para formatação localizada de colunas, paginação customizada e navegação por teclado.

## Quando usar

- Listagens de dados com formatação automática e localizada (datas, moedas, números, booleanos)
- Tabelas que precisam de paginação customizada com ações de exportação
- Listagens onde a navegação por teclado entre células é necessária
- Tabelas com linhas expansíveis (row expand)

## Quando não usar

- Exibição de dados simples sem necessidade de formatação — use `<table>` nativo ou `p-table` diretamente
- Listas de itens sem estrutura tabular — prefira listas ou cards

## Instalação

```typescript
import { TableModule } from '@seniorsistemas/angular-components/table';

@NgModule({ imports: [TableModule] })
export class MeuModule {}
```

## Uso básico

```html
<p-table [value]="dados" [columns]="colunas">
  <ng-template pTemplate="header">
    <tr>
      @for (col of colunas; track col.header) {
        <th [style]="col.style">{{ col.header }}</th>
      }
    </tr>
  </ng-template>
  <ng-template pTemplate="body" let-row>
    <tr>
      <s-table-columns [columns]="colunas" [rowValue]="row" />
    </tr>
  </ng-template>
</p-table>
```

## Componentes e Diretivas

### `s-table-columns`

Renderiza as células de uma linha com formatação automática por tipo de coluna.

| Input | Tipo | Padrão | Obrigatório | Descrição |
|-------|------|--------|:-----------:|-----------|
| `columns` | `Column[]` | `[]` | Sim | Lista de configurações das colunas a serem renderizadas |
| `rowValue` | `any` | — | Sim | Objeto da linha com os valores a serem exibidos |
| `locale` | `TableColumnLocaleOptions \| null` | `null` | Não | Opções de localização (calendário e número) para formatação |

### `s-table-paging`

Componente de paginação customizado com suporte a ações extras e exportação.

| Input | Tipo | Padrão | Obrigatório | Descrição |
|-------|------|--------|:-----------:|-----------|
| `totalRecords` | `number` | — | Sim | Total de registros para exibição no rodapé |
| `table` | `Table` | — | Sim | Referência à instância do `p-table` |
| `exportFileName` | `string` | `undefined` | Não | Nome do arquivo ao exportar |
| `exportable` | `boolean` | `true` | Não | Habilita opções de exportação |
| `enableExportSelectedRecords` | `boolean` | `true` | Não | Habilita exportação dos registros selecionados |
| `customActions` | `CustomAction[]` | `undefined` | Não | Ações adicionais no menu do rodapé |
| `loadAllRecords` | `() => Promise<any[]>` | `undefined` | Não | Função para carregar todos os registros para exportação |
| `loadCurrentPageRecords` | `() => any[]` | `undefined` | Não | Função para obter os registros da página atual |
| `loadSelectedRecords` | `() => any[]` | `undefined` | Não | Função para obter os registros selecionados |
| `exportNumberFormat` | `ExportNumberFormat` (signal input) | `undefined` | Não | Fixa o formato numérico da exportação (`raw` ou `localized`), removendo a escolha do menu |

#### Exportação: dado bruto x dado localizado

Por padrão (sem `exportNumberFormat` definido), cada opção de exportação do menu (página atual, selecionados, tudo) abre um submenu com duas escolhas:

- **Dado bruto** — exporta os valores numéricos das colunas `NUMBER`/`CURRENCY` exatamente como estão na origem (ex.: `1234.5`), sem nenhuma formatação. Indicado para integração com outros sistemas.
- **Dado localizado** — exporta os mesmos valores com o separador decimal do locale ativo do usuário (ex.: `1234,5` em pt-BR). Indicado para visualização/reimportação em planilhas do próprio usuário.

Se a coluna tiver `numberFormatOptions` configurado, o dado localizado usa esse formato (sem símbolo de moeda/percentual e sem separador de milhar, pra garantir que o valor continue sendo reconhecido como número ao reabrir em outra planilha).

Para eliminar a escolha do usuário e sempre exportar num formato fixo, defina `[exportNumberFormat]="'raw'"` ou `[exportNumberFormat]="'localized'"` — o menu volta a ter uma única ação por escopo.

### `[sNavigation]` (diretiva)

Habilita navegação por teclado entre células e linhas da tabela.

```html
<p-table sNavigation ...>
```

### `[sRowToggler]` (diretiva)

Controla a expansão de linhas na tabela PrimeNG.

### Tipos

```typescript
interface Column {
  header: string;                  // Cabeçalho da coluna. Obrigatório.
  attributes: string[];            // Propriedades do objeto a exibir. Obrigatório.
  type: EnumColumnFieldType;       // Tipo de formatação. Obrigatório.
  style?: object;                  // Estilos CSS da célula
  separator?: string;              // Separador entre múltiplos atributos (padrão: ' - ')
  scale?: number | ((row) => number); // Casas decimais para NUMBER/CURRENCY
  dateFormat?: string;             // Formato de data customizado
  tooltip?: string | ((row) => string); // Tooltip da célula
  badgeConfigs?: BadgeConfigs[];   // Configuração de badges para ENUM
  sequence?: number;               // Ordem de exibição da coluna
  prefix?: string;                 // Prefixo de tradução para ENUM/BOOLEAN
  enumPrefix?: string;             // Prefixo de tradução específico para ENUM
  numberFormatOptions?: Intl.NumberFormatOptions | ((row) => Intl.NumberFormatOptions);
}

enum EnumColumnFieldType {
  STRING  = 'string',   // Texto simples
  NUMBER  = 'number',   // Número formatado com locale
  CURRENCY = 'currency', // Valor monetário com símbolo
  DATE    = 'date',     // Data formatada com locale
  BOOLEAN = 'boolean',  // Sim/Não traduzido
  ENUM    = 'enum',     // Valor traduzido via i18n
  TOKENS  = 'tokens',   // Lista de tokens coloridos
  LINK    = 'link',     // Texto clicável
}

enum ExportNumberFormat {
  Raw = 'raw',             // Valor numérico original, sem formatação
  Localized = 'localized', // Valor com separador decimal do locale ativo
}
```

## Exemplos

### Tabela com formatação localizada

```typescript
const colunas: Column[] = [
  { header: 'Nome', attributes: ['nome'], type: EnumColumnFieldType.STRING, style: {} },
  { header: 'Cargo', attributes: ['cargo'], type: EnumColumnFieldType.STRING, style: {} },
  { header: 'Salário', attributes: ['salario'], type: EnumColumnFieldType.CURRENCY, style: { textAlign: 'right' } },
  { header: 'Ativo', attributes: ['ativo'], type: EnumColumnFieldType.BOOLEAN, style: { textAlign: 'center' } },
  { header: 'Admissão', attributes: ['admissao'], type: EnumColumnFieldType.DATE, style: {} },
];
```

```html
<p-table [value]="funcionarios" [columns]="colunas" styleClass="p-datatable-sm p-datatable-striped">
  <ng-template pTemplate="header">
    <tr>
      @for (col of colunas; track col.header) {
        <th [style]="col.style">{{ col.header }}</th>
      }
    </tr>
  </ng-template>
  <ng-template pTemplate="body" let-row>
    <tr>
      <s-table-columns [columns]="colunas" [rowValue]="row" />
    </tr>
  </ng-template>
</p-table>
```

### Com paginação customizada

```html
<p-table #tabela [value]="dados" [columns]="colunas" [lazy]="true" (onLazyLoad)="carregar($event)">
  <!-- cabeçalho e corpo -->
  <ng-template pTemplate="footer">
    <tr>
      <td [attr.colspan]="colunas.length">
        <s-table-paging
          [table]="tabela"
          [totalRecords]="totalRegistros"
          exportFileName="relatorio"
          [loadAllRecords]="carregarTodos"
        ></s-table-paging>
      </td>
    </tr>
  </ng-template>
</p-table>
```

### Exportação com formato numérico fixo (sem menu de escolha)

```html
<s-table-paging
  [table]="tabela"
  [totalRecords]="totalRegistros"
  exportFileName="relatorio"
  [exportNumberFormat]="'localized'"
></s-table-paging>
```

### Com navegação por teclado

```html
<p-table sNavigation [value]="dados" [columns]="colunas">
  <!-- cabeçalho e corpo -->
</p-table>
```

## Acessibilidade

- A diretiva `[sNavigation]` adiciona suporte completo a navegação por teclado: `ArrowUp`/`ArrowDown` para linhas, `ArrowLeft`/`ArrowRight` para células
- As colunas do tipo `BOOLEAN` são traduzidas automaticamente via i18n (`yes`/`no`)
- O `s-table-paging` exibe o total de registros em texto legível por leitores de tela

## Componentes relacionados

- [`Paginator`](../paginator/README.md) — paginação standalone