# Select

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

Componente de seleção dropdown genérico com suporte a seleção simples e múltipla, filtro, agrupamento, virtual scroll e acessibilidade ARIA completa. Implementa `ControlValueAccessor` para integração com Angular Forms.

## Quando usar

- Selecionar uma ou mais opções de uma lista fixa de itens
- Substituir `<select>` nativo com estilo customizado e recursos avançados
- Listas longas que precisam de busca textual (`filter`)
- Opções organizadas por categoria (`group`)
- Listas com muitos itens que exigem virtualização (`virtualScroll`)

## Quando não usar

- Listas com poucas opções sempre visíveis — prefira `SelectButton` ou `RadioButtonGroup`
- Busca com carregamento dinâmico de resultados — prefira `Autocomplete`
- Entrada de múltiplos valores livres — prefira `Chips`

## Instalação

```typescript
import { SelectComponent } from '@seniorsistemas/angular-components/select';

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

## Uso básico

```html
<s-select
  formControlName="pais"
  [options]="paises"
  optionLabel="nome"
  optionValue="codigo"
  placeholder="Selecione um país" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `options` | `T[]` | — | Sim | Lista de opções disponíveis para seleção |
| `placeholder` | `string` | `''` | Não | Texto exibido quando nenhuma opção está selecionada |
| `optionLabel` | `keyof T` | `undefined` | Não | Chave do objeto usada como texto de exibição. Obrigatório quando `options` são objetos |
| `optionValue` | `keyof T` | `undefined` | Não | Chave do objeto cujo valor será emitido ao formulário |
| `multiple` | `boolean` | `false` | Não | Habilita seleção de múltiplas opções com checkboxes |
| `filter` | `boolean` | `false` | Não | Exibe campo de busca textual no topo do dropdown |
| `filterBy` | `keyof T \| (keyof T)[]` | `undefined` | Não | Campo(s) usados para filtragem textual. Padrão: `optionLabel` |
| `showClear` | `boolean` | `false` | Não | Exibe botão X para limpar a seleção atual |
| `checkmark` | `boolean` | `false` | Não | Exibe ícone de checkmark ao lado da opção selecionada |
| `group` | `boolean` | `false` | Não | Habilita agrupamento. As opções devem ter estrutura `{ name, items[] }` |
| `virtualScroll` | `boolean` | `false` | Não | Virtualiza a lista para melhor performance com grandes volumes |
| `virtualScrollItemSize` | `number` | `37` | Não | Altura fixa de cada item em pixels para cálculo do virtual scroll |
| `emptyMessage` | `string \| null` | `null` | Não | Mensagem exibida quando nenhuma opção corresponde ao filtro |
| `disabled` | `boolean` (model) | `false` | Não | Controla o estado desabilitado via two-way binding |
| `showOptions` | `boolean` (model) | `false` | Não | Controla a visibilidade do painel via two-way binding |
| `ariaLabel` | `string` | `''` | Não | Label de acessibilidade do componente |
| `ariaLabelledBy` | `string` | `''` | Não | ID do elemento externo que descreve o componente |

### Tipos

```typescript
// Estrutura para opções agrupadas
interface GroupedOption {
  name: string;   // label do grupo
  items: T[];     // opções filhas
}
```

## Exemplos

### Seleção simples

```html
<form [formGroup]="form">
  <s-select
    formControlName="pais"
    [options]="paises"
    optionLabel="nome"
    optionValue="nome"
    placeholder="Selecione um país"
    [showClear]="true"
    ariaLabel="Selecione um país"
  ></s-select>
</form>
```

### Com filtro de busca

```html
<s-select
  formControlName="pais"
  [options]="paises"
  optionLabel="nome"
  optionValue="nome"
  placeholder="Buscar país..."
  [filter]="true"
  [showClear]="true"
></s-select>
```

### Seleção múltipla

```html
<s-select
  formControlName="paises"
  [options]="paises"
  optionLabel="nome"
  optionValue="nome"
  placeholder="Selecione países..."
  [multiple]="true"
  [filter]="true"
  [showClear]="true"
></s-select>
```

### Opções agrupadas

```html
<s-select
  formControlName="pais"
  [options]="paisesPorContinente"
  optionLabel="nome"
  optionValue="nome"
  placeholder="Selecione por continente..."
  [group]="true"
  ariaLabel="Selecione um país por continente"
></s-select>
```

## Acessibilidade

- O componente implementa o padrão ARIA `combobox` com `role="combobox"`, `aria-expanded` e `aria-haspopup`
- Navegação pelo teclado: `ArrowDown`/`ArrowUp` para mover entre opções, `Enter`/`Espaço` para selecionar, `Escape` para fechar
- Com `filter` aberto: `ArrowDown` move o foco para a lista, `Escape` retorna foco ao campo de busca
- Os inputs `ariaLabel` e `ariaLabelledBy` permitem associar descrições externas para leitores de tela
- Ao fechar o dropdown, o foco retorna automaticamente ao elemento trigger

## Componentes relacionados

- [`SelectButton`](../select-button/README.md) — quando as opções devem estar sempre visíveis como botões
- [`Autocomplete`](../autocomplete/README.md) — quando a lista é carregada dinamicamente via busca