# HelpPopover

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

Diretiva que exibe um popover de ajuda ao clicar no elemento hospedeiro. Suporta conteúdo como texto simples ou `TemplateRef`, com cabeçalho, rodapé, ícone, botão de fechar e posicionamento automático.

## Quando usar

- Explicar campos de formulário com regras complexas de preenchimento
- Fornecer contexto adicional sobre funcionalidades sem sobrecarregar a interface
- Quando o conteúdo de ajuda é extenso demais para um tooltip simples

## Quando não usar

- Mensagens curtas ao passar o mouse — prefira [`Tooltip`](../tooltip/README.md)
- Ícone de informação simples ao lado de um label — prefira [`InfoSign`](../info-sign/README.md)

## Instalação

```typescript
import { HelpPopoverModule } from '@seniorsistemas/angular-components/help-popover';

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

## Uso básico

```html
<button [sHelpPopover]="'Informe aqui o seu CPF'" popoverPosition="right">?</button>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `sHelpPopover` | `string \| TemplateRef<any> \| null` | `null` | Sim | Conteúdo do popover. Aceita texto simples ou `TemplateRef` Angular. |
| `closeButton` | `boolean` | `true` | Não | Exibe o botão de fechar (X) no cabeçalho. |
| `popoverIcon` | `string` | `''` | Não | Classe Font Awesome do ícone exibido no cabeçalho (ex: `'fas fa-info-circle'`). |
| `popoverHeader` | `string` | `''` | Não | Texto exibido no cabeçalho do popover. |
| `popoverFooter` | `string` | `''` | Não | Texto exibido no rodapé do popover. |
| `popoverButtonText` | `string` | `''` | Não | Texto do botão de ação no rodapé. Ao clicar, emite `buttonClicked`. |
| `popoverPosition` | `HelpPopoverPosition` | `'bottom'` | Não | Posição do popover em relação ao elemento. Reposiciona automaticamente se não houver espaço. |
| `popoverArrowPosition` | `HelpPopoverArrowPosition` | `'beginning'` | Não | Alinhamento da seta indicadora em relação ao lado do popover. |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `buttonClicked` | `EventEmitter<void>` | Emitido quando o usuário clica no botão de ação do rodapé. |

### Tipos

```typescript
type HelpPopoverPosition = 'top' | 'right' | 'bottom' | 'left';
type HelpPopoverArrowPosition = 'beginning' | 'middle' | 'end';
```

## Exemplos

### Popover básico com texto simples

```html
<button
    [sHelpPopover]="'Informe o CPF sem pontos e traços. Apenas números.'"
    popoverHeader="CPF"
    popoverIcon="fas fa-info-circle"
    popoverPosition="right"
>
    ?
</button>
```

### Popover com template customizado

```html
<ng-template #ajudaTemplate>
    <div>
        <p><strong>Formatos aceitos:</strong></p>
        <ul>
            <li>JPG / JPEG</li>
            <li>PNG</li>
        </ul>
    </div>
</ng-template>

<button [sHelpPopover]="ajudaTemplate" popoverHeader="Upload de imagem">
    Ajuda
</button>
```

### Popover com rodapé e botão de ação

```html
<button
    [sHelpPopover]="'Esta funcionalidade permite exportar dados.'"
    popoverHeader="Exportar dados"
    popoverFooter="Disponível nos planos Pro e Enterprise."
    popoverButtonText="Ver planos"
    (buttonClicked)="abrirPlanos()"
>
    Mais informações
</button>
```

### Acionamento programático

```html
<span
    [sHelpPopover]="'Este campo aceita apenas números inteiros positivos.'"
    popoverHeader="Formato do campo"
    popoverPosition="right"
    #popoverRef="sHelpPopover"
>
    Quantidade em estoque
</span>
<button (click)="popoverRef.show()">?</button>
```

## Acessibilidade

- O popover é aberto ao clicar no elemento hospedeiro e fechado ao clicar fora
- Use `popoverHeader` para fornecer contexto sobre o conteúdo do popover
- Pode ser acionado programaticamente via `#ref="sHelpPopover"` e `ref.show()`
- Reposiciona automaticamente quando não há espaço na posição configurada

## Componentes relacionados

- [`InfoSign`](../info-sign/README.md) — ícone de informação simples com tooltip ao passar o mouse
- [`Tooltip`](../tooltip/README.md) — dica contextual leve ao passar o mouse sobre um elemento