# Fieldset

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

Componente de agrupamento de campos de formulário com legenda, ícone e suporte a toggle (recolher/expandir) com animação. Aceita template customizado para o cabeçalho via `sTemplate="header"`.

## Quando usar

- Agrupar campos relacionados em formulários longos com separação visual por título
- Seções opcionais que podem ser recolhidas para reduzir a carga visual
- Formulários com múltiplas seções que precisam de diferenciação visual

## Quando não usar

- Agrupamentos sem necessidade de título — use `<div>` simples
- Múltiplos painéis onde apenas um pode estar aberto por vez — use [`Accordion`](../accordion/README.md)

## Instalação

```typescript
import { FieldsetModule } from '@seniorsistemas/angular-components/fieldset';

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

## Uso básico

```html
<s-fieldset legend="Dados Pessoais">
  <p>Conteúdo do fieldset</p>
</s-fieldset>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `legend` | `string` | `''` | — | Texto exibido como título do fieldset |
| `icon` | `string` | `''` | — | Classe de ícone exibida ao lado da legenda (ex: `'fas fa-cog'`) |
| `toggleable` | `boolean` | `false` | — | Habilita o botão +/- para recolher e expandir com animação |
| `destroyOnHide` | `boolean` | `true` | — | Remove o conteúdo do DOM ao recolher. Use `false` para preservar estado de formulários |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `beforeToggle` | `EventEmitter<FieldSetToggle>` | Emitido antes da animação de toggle iniciar |
| `afterToggle` | `EventEmitter<FieldSetToggle>` | Emitido após a animação de toggle concluir |

### Tipos

```typescript
type FieldSetToggle = {
  originalEvent: PointerEvent | KeyboardEvent;
  collapsed: boolean; // true = estava aberto e vai fechar; false = estava fechado e vai abrir
};
```

## Exemplos

### Fieldset básico

```html
<s-fieldset legend="Dados Pessoais">
  <div style="display: flex; flex-direction: column; gap: 12px;">
    <input type="text" placeholder="Nome completo" />
    <input type="text" placeholder="CPF" />
  </div>
</s-fieldset>
```

### Fieldset colapsável com ícone

```html
<s-fieldset
  legend="Informações de Contato"
  icon="fas fa-phone"
  [toggleable]="true"
  (beforeToggle)="onBeforeToggle($event)"
  (afterToggle)="onAfterToggle($event)"
>
  <input type="tel" placeholder="(00) 00000-0000" />
  <input type="email" placeholder="email@empresa.com" />
</s-fieldset>
```

### Colapsável preservando estado do formulário

```html
<s-fieldset legend="Dados Opcionais" [toggleable]="true" [destroyOnHide]="false">
  <input formControlName="complemento" placeholder="Complemento" />
</s-fieldset>
```

### Com cabeçalho customizado via template

```html
<s-fieldset [toggleable]="true">
  <ng-template sTemplate="header">
    <div style="display: flex; align-items: center; gap: 8px;">
      <span style="background: #fee2e2; width: 8px; height: 8px; border-radius: 50%;"></span>
      <span>Dados Bancários</span>
      <span style="font-size: 0.75rem; color: #dc2626;">(campos obrigatórios)</span>
    </div>
  </ng-template>
  <input type="text" placeholder="Banco" />
</s-fieldset>
```

### Múltiplos fieldsets em um formulário

```html
<div style="display: flex; flex-direction: column; gap: 16px;">
  <s-fieldset legend="Dados Pessoais" icon="fas fa-user" [toggleable]="true">
    <!-- campos -->
  </s-fieldset>
  <s-fieldset legend="Endereço" icon="fas fa-map-marker-alt" [toggleable]="true">
    <!-- campos -->
  </s-fieldset>
</div>
```

## Acessibilidade

- O botão de toggle é ativável por teclado (Enter e Space)
- A animação de recolher/expandir tem duração de 300ms (respeitando `prefers-reduced-motion` via CSS)
- O ícone decorativo não possui texto alternativo obrigatório

## Componentes relacionados

- [`Accordion`](../accordion/README.md) — painéis expansíveis onde apenas um pode estar aberto por vez
- [`DynamicForm`](../dynamic-form/README.md) — usa fieldset internamente para estruturar formulários dinâmicos