SetupSteps
Lista de passos de configuração com estado, ação e progresso, para resolver de relance.
O SetupSteps mostra uma configuração em etapas: cada passo tem um estado, um texto de apoio e, quando falta fazer algo, uma ação. Um cabeçalho traz o progresso ("2 de 3") e, quando tudo está feito, o bloco recolhe numa linha "tudo pronto". É genérico: não conhece provedor algum. Quem usa monta os passos. No Admin ele guia a Cloudflare e, depois, a Fonte de Pedidos.
import { SetupSteps } from "@rastreio-x/ui";
import type { SetupStep } from "@rastreio-x/ui";
Padrão
A barra de segmentos e a lista mostram o estado de cada passo. Só passos pending e error exibem a ação.
Estados
Quatro estados, cada um com ícone e texto para leitor de tela: done (Concluído), pending (Pendente), error (Com erro) e blocked (Bloqueado). Em blocked, o detail explica o motivo.
| Estado | Ícone | Ação aparece | Quando usar |
|---|---|---|---|
done | Círculo com visto | Não | O passo está resolvido. |
pending | Círculo tracejado | Sim | É a vez da pessoa. |
error | Círculo com X | Sim | O passo falhou e dá para tentar de novo. |
blocked | Círculo com exclamação | Não | Depende de um passo anterior. |
Tudo pronto
Com todos os passos done, o bloco recolhe numa linha com o título e doneLabel (padrão: "tudo pronto"). O botão "Ver passos" reabre a lista e "Recolher" volta.
Em tela estreita
O layout é o mesmo no desktop e em 390 px: a ação desce para baixo do texto, sem esconder nada.
No Admin
Na área da plataforma, cada passo concluído libera o seguinte, e a lista é montada a cada render a partir do estado real (conexão, zonas, DNS).
Anatomia
| Parte | Origem | Observação |
|---|---|---|
| Título | title | Também é o nome da região quando for texto. |
| Contagem | automática | "N de M", dos passos done. |
| Barra | automática | Um segmento por passo, com a cor do estado. |
| Passo | steps[] | id, status, title, detail? e action?. |
| Ação | steps[].action | Normalmente um Button; só em pending e error. |
Propriedades
Cada item de steps segue o tipo SetupStep:
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identifica o passo; vira data-testid com testId. |
status | "done" | "pending" | "error" | "blocked" | Estado do passo. |
title | ReactNode | O que fazer, em frase curta. |
detail | ReactNode | Uma linha de apoio; em blocked, o motivo. |
action | ReactNode | A ação do passo, mostrada em pending e error. |
Animações
O SetupSteps não anima: os passos mudam de estado e o bloco recolhe e expande sem transição, e o arquivo não importa Motion. Se você animar a entrada de um novo passo, respeite prefers-reduced-motion.
Acessibilidade
- O bloco é uma
sectionnomeada pelo título (quando é texto) e a lista é umaol: a ordem dos passos é lida. - Cada passo leva o estado em texto oculto ("Concluído", "Pendente", "Com erro", "Bloqueado"), então a cor e o ícone nunca são o único sinal.
- "Ver passos" e "Recolher" são botões com
aria-expanded. - A barra de segmentos é decorativa (
aria-hidden); o progresso está em texto, na contagem. - O foco passa pelas ações dos passos na ordem da lista.
Boas práticas
Faça
Evite
- Uma ação por passo, com rótulo de verbo em Title Case curto: "Conectar Fonte".
- Em
error, diga o que falhou emdetaile ofereça tentar de novo. - Use
blockedem vez de remover o passo: a pessoa entende o caminho todo. - Não use para progresso de carregamento; para isso há
ProgressBar.