# Checkbox

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

Componente de caixa de seleção com suporte a três estados: marcado, desmarcado e indeterminado. Implementa `ControlValueAccessor` para integração com Reactive Forms e Template-driven Forms do Angular.

## Quando usar

- Aceite de termos e condições
- Seleção de múltiplos itens independentes em uma lista
- Ativação ou desativação de funcionalidades opcionais
- Checkbox "selecionar todos" com estado indeterminado para controlar grupos

## Quando não usar

- Quando apenas uma opção de um grupo pode ser selecionada — use `RadioButton` em vez disso
- Quando o valor é um toggle visual de estado ativo/inativo — use `Switch` em vez disso
- Para seleção hierárquica com múltiplos níveis — use `CheckboxList`

## Instalação

```typescript
import { CheckboxComponent } from '@seniorsistemas/angular-components/checkbox';

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

## Uso básico

```html
<s-checkbox label="Aceito os termos de uso" [(checked)]="aceito" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `label` | `string` | `''` | não | Texto exibido ao lado do checkbox |
| `checked` | `boolean` | `false` | não | Estado atual (two-way binding via `[(checked)]`) |
| `disabled` | `boolean` | `false` | não | Desabilita o checkbox (two-way binding via `[(disabled)]`) |
| `indeterminate` | `boolean` | `false` | não | Estado indeterminado (traço) — descartado na primeira interação |
| `ariaLabel` | `string` | `undefined` | não | Rótulo acessível para leitores de tela |
| `ariaLabelledBy` | `string` | `undefined` | não | ID do elemento que descreve o checkbox |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `checkedChange` | `OutputEmitterRef<boolean>` | Emitido quando o valor é alterado pelo usuário |

## Exemplos

### Uso com ngModel

```html
<s-checkbox label="Receber newsletter" [(checked)]="receberNewsletter"></s-checkbox>
```

### Uso com Reactive Forms

```html
<form [formGroup]="form">
  <s-checkbox formControlName="newsletter" label="Receber newsletter"></s-checkbox>
  <s-checkbox formControlName="termos" label="Aceito os termos de uso"></s-checkbox>
  <s-checkbox formControlName="notificacoes" label="Ativar notificações" [disabled]="true"></s-checkbox>
</form>
```

### Padrão "selecionar todos" com estado indeterminado

```html
<s-checkbox
  label="Selecionar todos"
  [checked]="todosMarcados"
  [indeterminate]="algunsMarcados"
  (checkedChange)="alternarTodos()">
</s-checkbox>

<div style="margin-left: 28px;">
  @for (item of itens; track item.id) {
    <s-checkbox
      [label]="item.label"
      [checked]="item.checked"
      (checkedChange)="alternarItem(item.id)">
    </s-checkbox>
  }
</div>
```

### Desabilitado (somente leitura)

```html
<s-checkbox label="Opção obrigatória" [checked]="true" [disabled]="true"></s-checkbox>
```

## Acessibilidade

- O elemento recebe `role="checkbox"` com `aria-checked` (`true`, `false` ou `"mixed"` para indeterminado)
- Totalmente navegável por teclado: **Tab** para focar, **Space** para alternar
- Use `ariaLabel` quando não houver `label` visível (ex.: checkbox em cabeçalho de tabela)

## Componentes relacionados

- [`CheckboxList`](../checkbox-list/README.md) — quando a seleção é hierárquica com múltiplos níveis de pai/filho
- [`Switch`](../switch/README.md) — alternador visual de estado ativo/inativo