# Stepper

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

Componente de progresso em etapas que exibe uma linha do tempo horizontal de passos com animações. Permite ao usuário visualizar e navegar entre etapas de um fluxo sequencial. Suporta passos ocultos, desabilitados e diferentes estados visuais (sucesso, aviso).

> **Nota:** O seletor `s-steps` e o pacote `steps` estão descontinuados. Use `s-stepper` e o pacote `stepper` em novos projetos. O seletor antigo será removido na versão 20.0.0.

## Quando usar

- Formulários multi-etapa (wizard) com progresso visível
- Onboarding de novos usuários com passos sequenciais
- Processos de checkout ou cadastro com etapas bem definidas
- Fluxos onde o usuário pode navegar de volta para corrigir etapas anteriores

## Quando não usar

- Fluxos com apenas 2 passos — prefira botões Anterior/Próximo simples
- Navegação geral da aplicação — prefira tabs ou breadcrumbs
- Processos sem sequência clara entre etapas

## Instalação

```typescript
import { StepperModule } from '@seniorsistemas/angular-components/stepper';

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

## Uso básico

```html
<s-stepper
  [steps]="etapas"
  [activeIndex]="etapaAtiva"
  (stepSelected)="onEtapaSelecionada($event)"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `steps` | `Step[]` | — | Sim | Lista de etapas exibidas no stepper |
| `activeIndex` | `number` | `0` | Sim | Índice (0-based) da etapa atualmente ativa. Controlado externamente |
| `id` | `string` | `'s-steps-{n}'` | Não | Identificador único do componente no DOM |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `stepSelected` | `EventEmitter<StepSelectionEvent>` | Emitido quando o usuário clica em uma etapa habilitada e não ativa |

### Tipos

```typescript
interface Step {
  id: any;
  label: string;        // Texto exibido abaixo do indicador. Obrigatório.
  state?: StepState;    // Estado visual do passo
  disabled?: boolean;   // Impede clique e aplica estilo desabilitado
  hidden?: boolean;     // Remove o passo da renderização
  tooltip?: string;     // Texto do tooltip ao passar o mouse
  ariaLabel?: string;   // Label acessível alternativo
  ariaControls?: string; // ID do painel controlado por este passo
}

enum StepState {
  Default = 'default',
  Success = 'success',
  Warning = 'warning',
}

interface StepSelectionEvent {
  step: Step;    // Objeto Step selecionado
  index: number; // Índice da etapa selecionada
  event: Event;  // Evento de clique original
}
```

## Exemplos

### Fluxo básico com 4 etapas

```html
<s-stepper
  [steps]="etapas"
  [activeIndex]="etapaAtual"
  (stepSelected)="onSelecionar($event)"
></s-stepper>
```

```typescript
etapas: Step[] = [
  { id: '1', label: 'Dados Pessoais' },
  { id: '2', label: 'Endereço' },
  { id: '3', label: 'Contato' },
  { id: '4', label: 'Confirmação' },
];

onSelecionar(event: StepSelectionEvent): void {
  this.etapaAtual = event.index;
}
```

### Com estados visuais

```typescript
etapas: Step[] = [
  { id: '1', label: 'Dados Pessoais', state: StepState.Success },
  { id: '2', label: 'Endereço', state: StepState.Warning },
  { id: '3', label: 'Documentos', state: StepState.Success },
  { id: '4', label: 'Confirmação' },
];
```

### Modo linear (passos futuros bloqueados)

```typescript
etapas: Step[] = [
  { id: '1', label: 'Concluído', state: StepState.Success },
  { id: '2', label: 'Em Andamento' },
  { id: '3', label: 'Bloqueado', disabled: true },
  { id: '4', label: 'Bloqueado', disabled: true },
];
```

### Com tooltips explicativos

```typescript
etapas: Step[] = [
  { id: '1', label: 'Cadastro', state: StepState.Success, tooltip: 'Etapa concluída' },
  { id: '2', label: 'Validação', tooltip: 'Valide seu e-mail e telefone' },
  { id: '3', label: 'Aprovação', disabled: true, tooltip: 'Aguardando validação' },
];
```

### Com botões de navegação

```html
<s-stepper [steps]="etapas" [activeIndex]="etapaAtual" (stepSelected)="onSelecionar($event)"></s-stepper>

<div style="display: flex; gap: 8px; margin-top: 16px; justify-content: flex-end;">
  <button [disabled]="etapaAtual === 0" (click)="voltar()">Voltar</button>
  <button [disabled]="etapaAtual === etapas.length - 1" (click)="avancar()">Avançar</button>
</div>
```

## Acessibilidade

- O componente possui `role="tablist"` e `aria-orientation="horizontal"`
- Cada passo é renderizado com `role="tab"` e `aria-selected`
- O atributo `ariaLabel` permite fornecer um nome alternativo mais descritivo para leitores de tela
- O atributo `ariaControls` vincula o passo ao painel de conteúdo correspondente
- Passos visitados (índice menor que `activeIndex`) recebem ícone de check automaticamente
- A barra de progresso entre os passos é animada ao mudar o `activeIndex`

## Componentes relacionados

- [`Steps`](../steps/README.md) — alias depreciado para este componente
- [`Accordion`](../accordion/README.md) — organização de conteúdo em seções expansíveis