# SelectButton

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

Componente para seleção de uma ou múltiplas opções através de botões visuais agrupados. Alternativa visual ao `select` ou `radio button` quando as opções são poucas e devem estar sempre visíveis. Implementa `ControlValueAccessor` para integração com Angular Forms.

## Quando usar

- Filtros de período (hoje, semana, mês) em dashboards
- Alternância entre modos de visualização (lista, grade, mapa)
- Seleção de tipo ou categoria com opções mutuamente exclusivas e poucas alternativas (até 5)
- Filtros com múltiplos critérios aplicáveis simultaneamente (`multiple: true`)

## Quando não usar

- Listas com muitas opções — prefira `Select` com dropdown
- Seleção única com rótulos descritivos longos — prefira `RadioButtonGroup`
- Entrada de valores livres — prefira `Chips`

## Instalação

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

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

## Uso básico

```html
<s-select-button
  formControlName="periodo"
  [items]="periodos"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `items` | `SelectButtonItem[]` | — | Sim | Lista de itens exibidos como botões de seleção |
| `multiple` | `boolean` | `false` | Não | Permite selecionar múltiplos itens simultaneamente |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `itemSelected` | `EventEmitter<SelectButtonItem[]>` | Emitido após a seleção ser atualizada. Emite o array completo de itens ativos |
| `itemClicked` | `EventEmitter<SelectButtonItem>` | Emitido quando um item habilitado é clicado, antes da atualização da seleção |

### Tipos

```typescript
interface SelectButtonItem {
  label: string;     // Texto exibido no botão. Obrigatório.
  value: any;        // Valor associado. Obrigatório.
  disabled?: boolean; // Desabilita o item individualmente.
}
```

## Exemplos

### Seleção única — filtro de período

```html
<form [formGroup]="form">
  <s-select-button
    formControlName="periodo"
    [items]="periodos"
    [multiple]="false"
    (itemSelected)="onPeriodoChange($event)"
  ></s-select-button>
</form>
```

```typescript
periodos: SelectButtonItem[] = [
  { label: 'Hoje', value: 'today' },
  { label: 'Esta semana', value: 'week' },
  { label: 'Este mês', value: 'month' },
  { label: 'Este ano', value: 'year' },
];
```

### Seleção múltipla

```html
<form [formGroup]="form">
  <s-select-button
    formControlName="frameworks"
    [items]="frameworks"
    [multiple]="true"
    (itemSelected)="onSelecionados($event)"
    (itemClicked)="onClicado($event)"
  ></s-select-button>
</form>
```

### Com item desabilitado individualmente

```html
<s-select-button
  formControlName="status"
  [items]="statusItems"
></s-select-button>
```

```typescript
statusItems: SelectButtonItem[] = [
  { label: 'Ativo', value: 'active' },
  { label: 'Inativo', value: 'inactive' },
  { label: 'Bloqueado', value: 'blocked', disabled: true },
];
```

### Com valor pré-selecionado via FormControl

```typescript
form = new FormGroup({
  selection: new FormControl([{ label: 'Angular', value: 'angular' }])
});
```

## Acessibilidade

- Cada item do grupo é renderizado como um `<button>` com `role="button"`
- Itens desabilitados recebem o atributo `disabled` nativo e não respondem a foco ou clique
- O estado de seleção é indicado visualmente por classes CSS; recomenda-se associar `aria-pressed` via customização para leitores de tela
- O componente inteiro pode ser desabilitado via `FormControl.disable()` ou `setDisabledState`

## Componentes relacionados

- [`Select`](../select/README.md) — quando há muitas opções ou o espaço é limitado
- [`RadioButtonGroup`](../radio-button-group/README.md) — seleção única com layout vertical/horizontal