Stepper

Componente de navegação por etapas (wizard / progress steps). Exibe uma sequência ordenada de etapas via `mk-stepper` + `mk-step`.

O mk-stepper exibe uma sequência ordenada de etapas, indicando quais já foram concluídas, qual é a atual e quais ainda estão pendentes. Usa uma API de composição: cada etapa é declarada como um mk-step filho, e a etapa atual é controlada pela prop current do contêiner (índice 0-based), que é a fonte de verdade. Use-o em fluxos de cadastro, checkout e qualquer processo dividido em etapas sequenciais.

Padrão

As etapas anteriores à atual aparecem como concluídas (com um check); a atual fica destacada; as posteriores, pendentes.

import { MkStepper, MkStep } from '@db1/makuco-ui-react';
import { useState } from 'react';

function Cadastro() {
  const [etapa, setEtapa] = useState(1);

  return (
    <MkStepper current={etapa} onMkStepChange={(e) => setEtapa(e.detail.index)}>
      <MkStep label="Conta" description="Dados de acesso" />
      <MkStep label="Endereço" description="Onde você mora" />
      <MkStep label="Pagamento" description="Forma de cobrança" />
      <MkStep label="Confirmação" description="Revise e finalize" />
    </MkStepper>
  );
}

<mk-stepper [current]="etapa" (mkStepChange)="etapa = $event.detail.index">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Endereço" description="Onde você mora"></mk-step>
  <mk-step label="Pagamento" description="Forma de cobrança"></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Orientação vertical

Use orientation="vertical" para empilhar as etapas — ideal para barras laterais ou telas estreitas.

<MkStepper current={2} orientation="vertical">
  <MkStep label="Conta" description="Dados de acesso" />
  <MkStep label="Endereço" description="Onde você mora" />
  <MkStep label="Pagamento" description="Forma de cobrança" />
  <MkStep label="Confirmação" description="Revise e finalize" />
</MkStepper>

<mk-stepper orientation="vertical" [current]="2">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Endereço" description="Onde você mora"></mk-step>
  <mk-step label="Pagamento" description="Forma de cobrança"></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Variante dot

A variante dot exibe marcadores circulares compactos no lugar dos números — útil quando o espaço é limitado.

<MkStepper current={2} variant="dot">
  <MkStep label="Carrinho" />
  <MkStep label="Entrega" />
  <MkStep label="Pagamento" />
  <MkStep label="Confirmação" />
</MkStepper>

<mk-stepper variant="dot" [current]="2">
  <mk-step label="Carrinho"></mk-step>
  <mk-step label="Entrega"></mk-step>
  <mk-step label="Pagamento"></mk-step>
  <mk-step label="Confirmação"></mk-step>
</mk-stepper>

Navegável

Com clickable, o usuário pode voltar para etapas concluídas ou permanecer na atual. Etapas pendentes nunca são clicáveis. Cada navegação emite mkStepChange — atualize current em resposta.

<MkStepper current={etapa} clickable onMkStepChange={(e) => setEtapa(e.detail.index)}>
  <MkStep label="Conta" description="Dados de acesso" />
  <MkStep label="Endereço" description="Onde você mora" />
  <MkStep label="Pagamento" description="Forma de cobrança" />
  <MkStep label="Confirmação" description="Revise e finalize" />
</MkStepper>

<mk-stepper clickable [current]="etapa" (mkStepChange)="etapa = $event.detail.index">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Endereço" description="Onde você mora"></mk-step>
  <mk-step label="Pagamento" description="Forma de cobrança"></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Com erro

A prop error no mk-step é uma flag visual ortogonal: marca a etapa com a cor de erro e um ícone de alerta, podendo coexistir com qualquer status (inclusive a etapa atual).

<MkStepper current={1}>
  <MkStep label="Conta" description="Dados de acesso" />
  <MkStep label="Pagamento" description="Cartão recusado" error />
  <MkStep label="Confirmação" description="Revise e finalize" />
</MkStepper>

<mk-stepper [current]="1">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Pagamento" description="Cartão recusado" error></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Fluxo não linear

A prop completed no mk-step força o estado "concluída" independentemente do índice, útil quando uma etapa posterior já foi finalizada fora da ordem sequencial.

<MkStepper current={1}>
  <MkStep label="Conta" description="Dados de acesso" />
  <MkStep label="Endereço" description="Onde você mora" />
  <MkStep label="Documentos" description="Já enviados" completed />
  <MkStep label="Confirmação" description="Revise e finalize" />
</MkStepper>

<mk-stepper [current]="1">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Endereço" description="Onde você mora"></mk-step>
  <mk-step label="Documentos" description="Já enviados" completed></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Etapa desabilitada

Marque um mk-step com disabled para impedir a navegação até ele, mesmo com clickable ativo.

<MkStepper current={3} clickable>
  <MkStep label="Conta" description="Dados de acesso" />
  <MkStep label="Endereço" description="Onde você mora" />
  <MkStep label="Pagamento" description="Indisponível" disabled />
  <MkStep label="Confirmação" description="Revise e finalize" />
</MkStepper>

<mk-stepper clickable [current]="3">
  <mk-step label="Conta" description="Dados de acesso"></mk-step>
  <mk-step label="Endereço" description="Onde você mora"></mk-step>
  <mk-step label="Pagamento" description="Indisponível" disabled></mk-step>
  <mk-step label="Confirmação" description="Revise e finalize"></mk-step>
</mk-stepper>

Props — mk-stepper

Prop	Tipo	Padrão	Descrição
`current`	`number`	`0`	Índice da etapa atual (0-based). É a fonte de verdade do estado — atualize ao receber `mkStepChange`.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Dispõe as etapas em linha ou empilhadas verticalmente.
`variant`	`"numbered" \| "dot"`	`"numbered"`	`"numbered"` exibe o número da etapa (ou um check quando concluída); `"dot"` exibe um marcador circular compacto.
`clickable`	`boolean`	`false`	Permite navegar clicando em etapas concluídas ou na atual. Etapas pendentes nunca são clicáveis.
`label`	`string`	`"Progresso"`	Rótulo acessível aplicado ao elemento `nav`.

Props — mk-step

Prop	Tipo	Padrão	Descrição
`label`	`string`	`""`	Rótulo principal da etapa, exibido ao lado ou abaixo do indicador.
`description`	`string`	—	Texto auxiliar opcional, exibido abaixo do rótulo.
`disabled`	`boolean`	`false`	Impede a navegação até esta etapa quando o contêiner está com `clickable` ativo.
`completed`	`boolean`	`false`	Força o estado "concluída" independentemente do índice, sobrepondo o status calculado pelo contêiner. Útil em fluxos não lineares.
`error`	`boolean`	`false`	Flag visual ortogonal: marca a etapa com a cor de erro e um ícone de alerta. Pode coexistir com qualquer status, inclusive a etapa atual.

Eventos

Evento	Componente	Payload	Descrição
`mkStepChange`	`mk-stepper`	`{ index: number }`	Emitido quando o usuário navega para outra etapa, por clique ou teclado (Enter/Espaço). Só dispara quando `clickable` está ativo e a etapa de destino é concluída ou a atual, não está desabilitada e difere da etapa atual.

Slots

Componente	Slot	Descrição
`mk-stepper`	(default)	Deve conter instâncias de `mk-step`, na ordem das etapas.

Acessibilidade

O mk-stepper renderiza um <nav> com aria-label (prop label) envolvendo uma lista semântica (<ol role="list">); cada mk-step recebe role="listitem".
A etapa atual recebe aria-current="step".
O estado de cada etapa (concluída, atual, pendente ou erro) é anunciado por leitores de tela via um texto visualmente oculto, evitando depender apenas de cor (WCAG 1.4.1).
Quando navegável, cada controle de etapa interativo recebe role="button" e tabindex="0".
Etapas desabilitadas recebem aria-disabled="true" e não são focáveis.
Indicadores puramente visuais (número, check, alerta, ponto e conector) recebem aria-hidden="true".
As transições respeitam prefers-reduced-motion.

Tecla	Comportamento
`Tab`	Move o foco entre as etapas interativas.
`Enter` / `Espaço`	Ativa a etapa focada, navegando para ela.

Stepper

On this page