# NavigationButton

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

Componente de navegação por etapas que exibe o passo atual com botões de avançar e retroceder. Ao clicar no label central, abre um dropdown (TieredMenu) para seleção direta de qualquer etapa. Implementa `ControlValueAccessor` para integração com Angular Forms.

## Quando usar

- Navegação entre períodos (meses, trimestres, anos) em relatórios e dashboards
- Paginação de etapas onde o usuário pode avançar, retroceder ou pular diretamente
- Fluxos de wizard com etapas sequenciais nomeadas

## Quando não usar

- Quando o usuário precisa ver o progresso visual de todas as etapas simultaneamente — prefira [`Stepper`](../stepper/README.md) ou [`Steps`](../steps/README.md)
- Navegação por páginas numeradas — prefira paginação convencional

## Instalação

```typescript
import { NavigationButtonModule } from '@seniorsistemas/angular-components/navigation-button';

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

## Uso básico

```html
<s-navigation-button
    [steps]="etapas"
    (stepChanged)="onEtapaMudou($event)"
></s-navigation-button>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `steps` | `NavigationButtonItem[]` | — | Sim | Lista de etapas de navegação. |
| `defaultValue` | `unknown` | `undefined` | Não | Valor padrão a ser selecionado na inicialização. |
| `tooltip` | `string` | `undefined` | Não | Tooltip global exibido no label central (sobrescrito pelo tooltip individual do item). |
| `changeOnInit` | `boolean` | `false` | Não | Quando `true`, emite `stepChanged` na inicialização com a etapa inicial. |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `stepChanged` | `EventEmitter<NavigationButtonStepChangedInfo>` | Emitido quando o usuário navega para uma nova etapa, com informações da etapa anterior e atual. |

### Tipos

```typescript
interface NavigationButtonItem {
    label: string;      // Texto exibido no botão e no dropdown
    value: unknown;     // Valor associado à etapa
    tooltip?: string;   // Tooltip exibido ao passar o mouse no label (sobrescreve o global)
}

interface NavigationButtonStepChangedInfo {
    previous: NavigationButtonItem | null;  // Etapa anterior (null na inicialização)
    current: NavigationButtonItem;          // Etapa atual
}
```

## Exemplos

### Navegação entre períodos mensais

```typescript
etapas: NavigationButtonItem[] = [
    { label: 'Janeiro', value: 'jan' },
    { label: 'Fevereiro', value: 'feb' },
    { label: 'Março', value: 'mar' },
    { label: 'Abril', value: 'apr' },
];
```

```html
<s-navigation-button
    [steps]="etapas"
    (stepChanged)="onPeriodoMudou($event)"
></s-navigation-button>
```

### Com tooltip e valor padrão

```html
<s-navigation-button
    [steps]="etapas"
    [defaultValue]="'apr'"
    tooltip="Clique para selecionar um período"
    (stepChanged)="onPeriodoMudou($event)"
></s-navigation-button>
```

### Com tooltips individuais por etapa

```typescript
etapasComTooltip: NavigationButtonItem[] = [
    { label: 'Etapa 1', value: 'step1', tooltip: 'Dados pessoais' },
    { label: 'Etapa 2', value: 'step2', tooltip: 'Endereço' },
    { label: 'Etapa 3', value: 'step3', tooltip: 'Contato' },
    { label: 'Etapa 4', value: 'step4', tooltip: 'Revisão' },
];
```

```html
<s-navigation-button
    [steps]="etapasComTooltip"
    (stepChanged)="onEtapaMudou($event)"
></s-navigation-button>
```

### Integração com Reactive Forms

```typescript
form = new FormGroup({
    periodo: new FormControl('feb'),
});
```

```html
<form [formGroup]="form">
    <s-navigation-button
        formControlName="periodo"
        [steps]="etapas"
        tooltip="Selecione um período"
        (stepChanged)="onPeriodoMudou($event)"
    ></s-navigation-button>
</form>
<div>Valor selecionado: {{ form.get('periodo')?.value }}</div>
```

### Emitindo evento na inicialização

```html
<s-navigation-button
    [steps]="etapas"
    [changeOnInit]="true"
    (stepChanged)="onEtapaMudou($event)"
></s-navigation-button>
```

## Acessibilidade

- O botão ← retrocede para a etapa anterior e é desabilitado automaticamente na primeira etapa
- O botão → avança para a próxima etapa e é desabilitado automaticamente na última
- Clicar no label central abre um dropdown (TieredMenu) com todas as etapas para seleção direta
- Implementa `ControlValueAccessor` — compatível com `formControlName` e `ngModel`

## Componentes relacionados

- [`Stepper`](../stepper/README.md) — indicador de progresso em etapas com clique em cada passo visível
- [`Steps`](../steps/README.md) — navegação visual entre etapas com todos os passos exibidos
- [`GridMenu`](../grid-menu/README.md) — seleção de módulo ou contexto em formato de grade