# CheckboxList

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

Componente de lista de checkboxes com suporte a hierarquia multinível. Gerencia automaticamente os estados indeterminado e marcado do nó pai com base nos filhos selecionados. Implementa `ControlValueAccessor` para integração completa com Angular Forms.

## Quando usar

- Seleção múltipla de opções agrupadas por categoria (ex.: frutas, verduras, legumes)
- Permissões agrupadas por módulo com seleção em cascata
- Filtros com múltiplos níveis de refinamento
- Estruturas organizacionais hierárquicas com seleção em árvore

## Quando não usar

- Para seleção de itens simples sem hierarquia — use `Checkbox` individual ou um grupo de checkboxes
- Para seleção única em uma lista — use `RadioButton` ou `RadioButtonGroup`
- Quando os dados não têm relação hierárquica entre si

## Instalação

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

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

## Uso básico

```html
<form [formGroup]="form">
  <s-checkbox-list [data]="estrutura" formControlName="selecao"></s-checkbox-list>
</form>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `data` | `CheckboxListData` | — | **sim** | Estrutura de dados da árvore de checkboxes |

### Tipos

```typescript
interface CheckboxListData {
  label: string;                     // Texto do checkbox (obrigatório)
  children?: CheckboxListData[];     // Filhos da hierarquia (opcional)
  renderType?: 'inline' | 'block';  // Layout dos filhos — padrão: 'inline'
}

interface CheckboxListState {
  checked: boolean;                  // Se o nó está marcado
  indeterminate?: boolean;           // Se o nó está em estado parcial
  disabled?: boolean;                // Se o nó está desabilitado
  children?: CheckboxListChildren;   // Estado dos filhos (chave = label do filho)
}

type CheckboxListChildren = Record<string, CheckboxListState>;
```

## Exemplos

### Lista simples com pai e filhos

```typescript
// Component
estrutura: CheckboxListData = {
  label: 'Opções',
  children: [
    { label: 'Opção 1' },
    { label: 'Opção 2' },
    { label: 'Opção 3' },
  ],
};

form = new FormGroup({
  selecao: new FormControl(null),
});
```

```html
<form [formGroup]="form">
  <s-checkbox-list [data]="estrutura" formControlName="selecao"></s-checkbox-list>
</form>
```

### Com estado inicial (todos marcados)

```typescript
estadoInicial: CheckboxListState = {
  checked: true,
  children: {
    'Opção 1': { checked: true, children: {} },
    'Opção 2': { checked: true, children: {} },
    'Opção 3': { checked: true, children: {} },
  },
};

form = new FormGroup({
  selecao: new FormControl(this.estadoInicial),
});
```

### Hierarquia de dois níveis

```typescript
estrutura: CheckboxListData = {
  label: 'Categorias',
  children: [
    {
      label: 'Frutas',
      children: [{ label: 'Maçã' }, { label: 'Banana' }, { label: 'Laranja' }],
    },
    {
      label: 'Verduras',
      children: [{ label: 'Alface' }, { label: 'Espinafre' }],
    },
  ],
};
```

### Com itens desabilitados

```typescript
estadoComDesabilitados: CheckboxListState = {
  checked: false,
  indeterminate: true,
  children: {
    'Opção 1': { checked: true, disabled: true, children: {} },
    'Opção 2': { checked: false, children: {} },
    'Opção 3': { checked: true, disabled: true, children: {} },
  },
};
```

## Acessibilidade

- Cada checkbox recebe `role="checkbox"` com `aria-checked` correto (incluindo `"mixed"` para indeterminado)
- Navegação por **Tab** entre checkboxes; **Space** para marcar/desmarcar
- A propagação automática de estados pai/filho é refletida nos atributos ARIA em tempo real

## Componentes relacionados

- [`Checkbox`](../checkbox/README.md) — checkbox individual sem hierarquia, para casos simples