# Panel

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

Componente container com cabeçalho, corpo e rodapé opcionais. Suporta colapso com animação, diferentes níveis de severidade visual na borda e templates customizáveis para cada seção via `sTemplate`.

## Quando usar

- Agrupar seções de conteúdo relacionado com título em formulários ou dashboards
- Seções opcionais que podem ser ocultadas pelo usuário (modo colapsável)
- Destacar áreas com estado de alerta, erro ou sucesso via severidade visual

## Quando não usar

- Para múltiplas seções expansíveis e exclusivas — use `Accordion`
- Para agrupamento de campos de formulário com borda — use `Fieldset`
- Para containers sem necessidade de cabeçalho ou severidade — use `Card`

## Instalação

```typescript
import { PanelModule } from '@seniorsistemas/angular-components/panel';

@NgModule({ imports: [PanelModule] })
export class MeuModulo {}
```

## Uso básico

```html
<s-panel header="Título do Painel">
  <p>Conteúdo do painel via ng-content.</p>
</s-panel>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `header` | `string` | `undefined` | Não | Texto exibido no cabeçalho. Quando omitido, o cabeçalho não é renderizado |
| `description` | `string` | `undefined` | Não | Texto descritivo exibido abaixo do título no cabeçalho |
| `toggleable` | `boolean` | `false` | Não | Exibe botão +/- no cabeçalho para colapsar/expandir o conteúdo |
| `collapsed` | `boolean` | `false` | Não | Define o estado inicial como colapsado. Requer `toggleable: true` |
| `severity` | `Severities` | `'default'` | Não | Aplica uma borda colorida lateral ao painel |
| `borderButtonOptions` | `BorderButtonOptions` | `undefined` | Não | Configuração do botão animado exibido na borda quando `severity` não é `'default'` |
| `class` | `string` | `''` | Não | Classes CSS adicionais aplicadas ao elemento raiz |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `collapsedChange` | `EventEmitter<boolean>` | Emitido ao colapsar ou expandir o painel. Emite o novo estado booleano |

### Tipos

```typescript
type Severities = 'default' | 'info' | 'warn' | 'error' | 'success';

type PanelTemplateTypes = 'header' | 'body' | 'footer';

interface BorderButtonOptions {
  visible?: (severity: Severities) => boolean;
  label?: (severity: Severities) => string;
  tooltip?: (severity: Severities) => string;
  icon?: (severity: Severities) => string;
  disabled?: (severity: Severities) => boolean;
  onClick?: () => void;
}
```

## Exemplos

### Painel básico com cabeçalho

```html
<s-panel header="Dados do Funcionário">
  <p>Conteúdo do painel via ng-content.</p>
</s-panel>
```

### Painel com descrição

```html
<s-panel
  header="Dados do Funcionário"
  description="Informações cadastrais e situação atual do vínculo empregatício.">
  <p>Conteúdo do painel.</p>
</s-panel>
```

### Painel colapsável

```html
<s-panel
  header="Dados Adicionais"
  [toggleable]="true"
  [collapsed]="false"
  (collapsedChange)="onColapsou($event)"
>
  <p>Clique no +/- para colapsar ou expandir.</p>
</s-panel>
```

### Painel com severidade

```html
<s-panel header="Atenção" severity="warn">
  <p>Painel com borda de aviso.</p>
</s-panel>

<s-panel header="Erro Crítico" severity="error">
  <p>Painel com borda de erro.</p>
</s-panel>
```

### Com template customizado no cabeçalho

```html
<s-panel [toggleable]="true">
  <ng-template sTemplate="header">
    <div style="display: flex; justify-content: space-between; align-items: center; width: 100%;">
      <span style="font-weight: 600;">Header Customizado</span>
      <span class="badge">Novo</span>
    </div>
  </ng-template>
  <p>Conteúdo do painel.</p>
</s-panel>
```

### Com template de body e footer

```html
<s-panel header="Painel com Footer">
  <ng-template sTemplate="body">
    <p>Conteúdo via sTemplate="body".</p>
  </ng-template>
  <ng-template sTemplate="footer">
    <div style="display: flex; justify-content: flex-end; gap: 8px;">
      <s-button label="Cancelar" priority="secondary"></s-button>
      <s-button label="Salvar" priority="primary"></s-button>
    </div>
  </ng-template>
</s-panel>
```

## Acessibilidade

- O botão de toggle (+/-) é um elemento `<button>` nativo, acessível via teclado e leitores de tela
- A animação de colapso usa Angular Animations e não afeta a navegação por teclado
- O cabeçalho customizado via `sTemplate="header"` deve garantir contraste e semântica adequados pelo implementador

## Componentes relacionados

- [`Accordion`](../accordion/README.md) — painéis expansíveis com múltiplos itens mutuamente exclusivos
- [`Card`](../card/README.md) — container com suporte a banner e templates
- [`Fieldset`](../fieldset/README.md) — agrupamento de campos de formulário