Steps
No meio
Passo 2 de 3
Turma
import { Steps } from '@rivocode/ui'Quando usar
A régua de passos de um formulário longo. Anda junto com o useWizard().
No celular vira uma linha de texto com barra de progresso: quatro bolinhas com rótulo em 390px viram quatro palavras cortadas, e o que importa ali é saber quanto falta.
As duas formas estão sempre na página, e o CSS mostra uma de cada vez. O
className, o aria-label e os demais atributos valem para as duas, e a linha
do celular vira group quando recebe nome. O id, o ref e o data-testid
ficam só na lista da mesa, porque identidade não pode aparecer duas vezes na
página; referência por
aria-describedby continua lendo a lista mesmo escondida.
Só dá para voltar, nunca pular para frente. Passo adiante costuma depender do
que o anterior validou, e um clique que atravessa isso leva a pessoa a uma tela
que ela não sabe preencher. Por isso o onStepChange só é chamado com um passo
já concluído, e sem ele a régua inteira é só leitura. Só o passo que se clica
é <button>: o atual, os futuros e os concluídos sem onStepChange são div,
e não botão desabilitado - botão que nunca funciona é parada de Tab e nome
de botão para o leitor de tela, prometendo uma ação que não existe.
Com step={steps.length}, tudo concluído, a régua larga mostra todas as
bolinhas feitas e o celular para no último passo, com a barra cheia e o
"concluído" para o leitor de tela. Antes ele contava "Passo 5 de 4", sem
título, e a barra passava de 100%.
O par é step e onStepChange, o mesmo do Tour: passo de uma sequência,
contado de zero.
O estado, e o rodapé
useWizard(steps) conta e valida a passagem, e não desenha nada. Devolve um
WizardState: o índice step, o current da lista, os avisos isFirst e
isLast, e next, back e goTo.
O next aceita uma checagem que pode ser assíncrona. Devolva false e o passo
não anda. É por aqui que entra o trigger do React Hook Form, sem o assistente
precisar conhecer o React Hook Form:
const steps: Step[] = [
{ id: 'client', title: 'Cliente' },
{ id: 'items', title: 'Itens' },
{ id: 'review', title: 'Conferir' },
]
const wizard = useWizard(steps)
<Steps steps={steps} step={wizard.step} onStepChange={wizard.goTo} />
<WizardFooter>
<Button variant="ghost" onClick={wizard.back} disabled={wizard.isFirst}>
Voltar
</Button>
<Button onClick={() => wizard.next(() => form.trigger())}>
{wizard.isLast ? 'Fazer o pedido' : 'Continuar'}
</Button>
</WizardFooter>
O next troca o passo só depois que o clique termina. Dentro de um
<form>, o último passo costuma trocar o Continuar por um botão
type="submit". Se a troca acontecesse no meio do clique, o navegador
terminaria aquele clique como envio, e a pessoa pagaria sem ver a revisão. Dê
key diferente aos dois botões também, para o React criar outro elemento em
vez de mudar o tipo do mesmo.
WizardFooter põe voltar de um lado e avançar do outro, e o último filho vai
sempre para o fim: no primeiro passo, sem o Voltar, o Continuar fica à direita,
no mesmo lugar dos passos seguintes, e não pula para a esquerda. No celular
empilha na ordem invertida com os dois ocupando a largura toda, o botão que
continua embaixo, onde o polegar está, e gruda no pé da tela
(sticky bottom-0, na camada --rc-z-sticky, com um traço em cima): o
formulário rola por baixo e o avanço não sai de alcance. O fundo é o de quem
está em volta: o Card, o Dialog e a Sheet declaram a superfície deles em
--rc-ground, e o rodapé a pinta; solto na página, ele pinta o fundo da
página. Painel montado à mão com outro fundo declara o dele no className
([--rc-ground:var(--rc-surface)]), ou vira Card.
Quando não usar
Para o que já aconteceu com alguma coisa (a trilha de uma entrega, o histórico
de uma alteração), use Timeline. Esta régua é de assistente: olha para a frente,
sabe quantos passos faltam e existe para conduzir alguém até o fim de um
formulário. A linha do tempo olha para trás, e ninguém avança nela.
Dois ou três campos não pedem assistente. Quebrar em passos um formulário que cabe numa tela troca a rolagem por cliques, e esconde de quem preenche o tamanho do que ele aceitou fazer.
No React Native
Traduz, e o que porta é o modo estreito que o web já desenhava: a linha "Passo 2 de 4", o título do passo e a barra de progresso. A régua de bolinhas não atravessa porque ela já tinha sido medida e reprovada abaixo de 640px: cinco passos numa faixa de 390px dão 60px de rótulo por passo, e "Conferir os itens" vira "Confe…" cinco vezes seguidas. A descrição, que o modo estreito do web esconde por falta de largura, aparece: aqui o passo atual é o único na tela.
Por isso não há onStepChange: ele só existia na régua larga, e sem bolinha não há o que tocar. Voltar é o botão do WizardFooter, e pular passo continua sendo o goTo.
O useWizard() atravessa inteiro e idêntico: é useState e três contas de índice, sem DOM e sem media query. Deixar o passo para o router nativo seria trocar um estado de tela por cinco rotas, e um assistente não é navegação: os passos partilham um formulário só, o back do aparelho não pode perder o que já foi digitado, e "Conferir" não é um endereço que alguém deva abrir direto. Quem quiser uma rota por passo continua podendo, porque o goTo aceita o índice que o router mandar. O WizardFooter empilha sempre, na ordem escrita (voltar em cima, avançar embaixo, onde o polegar está), e o w-full de cada botão, que no web chega por seletor de filho, aqui é o alignItems: stretch padrão do React Native.
API
| Prop | Tipo |
|---|---|
stepobrigatóriaIndice do passo atual, contando de zero. | number |
stepsobrigatória0.4.0 | Step[] |
labelsOs textos da peca, para trocar o idioma: `position` e a contagem "Passo 2 de 5", que recebe o passo atual contando de 1 e o total; `done` e o que o leitor de tela ouve depois do titulo de um passo ja feito, "concluído" sem ele. | Partial<StepsLabels> |
onStepChangeRecebe o indice do passo ja concluido que foi clicado. | ((step: number) => void) |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.