# Sidebar

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

Componente de painel lateral deslizante que aparece sobre o conteúdo vindo do lado direito da tela. Suporta templates customizados para cabeçalho, corpo e rodapé via `sTemplate`, bloqueio automático de scroll e confirmação de fechamento.

## Quando usar

- Exibir detalhes de um item selecionado sem sair da página atual
- Formulários simples de edição rápida sem necessidade de uma nova rota
- Painéis de filtros avançados em listas e tabelas
- Configurações ou propriedades de um elemento da interface
- Fluxos complementares que não devem interromper o contexto principal

## Quando não usar

- Confirmações de ações destrutivas — prefira `ConfirmDialog`
- Conteúdo crítico que exige atenção exclusiva do usuário — prefira `Dialog` modal
- Navegação principal da aplicação — prefira um menu lateral (`nav`) fixo

## Instalação

```typescript
import { SidebarModule } from '@seniorsistemas/angular-components/sidebar';

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

## Uso básico

```html
<s-sidebar [(visible)]="sidebarAberta" header="Detalhes">
  <p>Conteúdo do painel lateral.</p>
</s-sidebar>

<button (click)="sidebarAberta = true">Abrir Sidebar</button>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `visible` | `ModelSignal<boolean>` | `false` | Não | Controla a visibilidade da sidebar. Suporta `[(visible)]` |
| `closable` | `boolean` | `true` | Não | Exibe o botão de fechar (X) no cabeçalho |
| `dismissible` | `boolean` | `true` | Não | Fechar ao clicar no backdrop (área escurecida fora do painel) |
| `closeOnEscape` | `boolean` | `true` | Não | Fechar ao pressionar a tecla Escape |
| `header` | `string` | `undefined` | Não | Texto exibido no cabeçalho padrão. Substituível via `sTemplate="header"` |
| `largeSized` | `boolean` | `false` | Não | Aumenta a largura da sidebar para acomodar mais conteúdo |
| `cache` | `boolean` | `false` | Não | Mantém o conteúdo no DOM quando fechada, preservando estado interno |
| `registerConfirmClose` | `() => boolean` | `() => true` | Não | Função chamada antes de fechar; retornar `false` bloqueia o fechamento |

## Exemplos

### Sidebar básica

```html
<s-sidebar [(visible)]="visible" header="Filtros Avançados" [closable]="true">
  <p>Conteúdo do painel.</p>
</s-sidebar>
<s-button label="Abrir" (clicked)="visible = true"></s-button>
```

### Sidebar grande

```html
<s-sidebar [(visible)]="visible" header="Edição de Registro" [largeSized]="true">
  <!-- formulário complexo -->
</s-sidebar>
```

### Com templates customizados

```html
<s-sidebar [(visible)]="visible">
  <ng-template sTemplate="header">
    <div style="display: flex; align-items: center; gap: 8px;">
      <i class="fa fa-filter"></i>
      <span>Filtros Avançados</span>
    </div>
  </ng-template>
  <ng-template sTemplate="body">
    <!-- conteúdo do painel -->
  </ng-template>
  <ng-template sTemplate="footer">
    <s-button label="Aplicar" priority="primary" (clicked)="visible = false"></s-button>
  </ng-template>
</s-sidebar>
```

### Com confirmação de fechamento

```typescript
confirmClose = (): boolean => {
  return window.confirm('Deseja realmente fechar? As alterações serão perdidas.');
};
```

```html
<s-sidebar [(visible)]="visible" [registerConfirmClose]="confirmClose">
  <!-- formulário com alterações não salvas -->
</s-sidebar>
```

## Acessibilidade

- A sidebar utiliza `cdkTrapFocus` para aprisionar o foco dentro do painel enquanto aberta
- Pressionar `Escape` fecha a sidebar quando `closeOnEscape = true`
- O painel entra e sai com animação de deslizamento (300ms) vindo da direita
- Ao abrir, o scroll da página é bloqueado automaticamente e restaurado ao fechar

## Componentes relacionados

- [`Dialog`](../dialog/README.md) — modal centralizado para confirmações e conteúdo crítico
- [`SlideInBar`](../slide-in-bar/README.md) — painel que expande/colapsa embutido no layout