# Uma tela ou várias: o wizard

Wizard não é o padrão. O padrão é **um formulário só**, em seções; passos só
quando uma etapa depende da anterior.

## O problema

Quebrar quinze campos em três telas de cinco não diminui o trabalho, só esconde
o tamanho dele e tira a visão do conjunto. E o wizard mal feito cobra de novo:
perde o que foi digitado ao voltar, pede duas vezes o mesmo dado e confirma em
cima da revisão.

## Quando usar

A pergunta não é quantos campos existem, é **quantas decisões independentes** a
pessoa toma.

| Forma | Quando | Peça |
|---|---|---|
| Um formulário só | os campos se respondem juntos, e a pessoa já sabe tudo | `Card` com `Field` |
| Passos | há decisão que muda os campos seguintes, ou a pessoa precisa buscar dado no meio | `Steps` + `WizardFooter` |
| Folha lateral | a tarefa é acessória e o contexto de trás importa | `Sheet` |
| Diálogo | uma decisão, curta, que não pode ser dispensada por engano | `Dialog` |

Responda as quatro perguntas antes de quebrar em passos; wizard só se pelo menos
uma for "sim".

1. **Uma resposta muda o que se pergunta depois?** Pessoa física ou jurídica
   troca os campos; o tipo de serviço decide as alíquotas.
2. **A pessoa precisa sair para buscar um dado no meio?** O código do serviço
   na prefeitura, o comprovante no e-mail.
3. **Uma etapa tem custo próprio ao ser confirmada?** Consultar o CNPJ na
   Receita, reservar o horário, gerar o QR.
4. **A tarefa é longa e rara, e a pessoa se perde sem mapa?** Abrir a empresa
   no sistema pela primeira vez, configurar a emissão.

## Quando não usar

- **Tudo "não" é formulário único, mesmo com trinta campos**, em seções com
  `Fieldset` e título. Campo que poucos usam vai para um `Collapsible` ("Mais
  opções"), e não para um passo a mais.
- **Perguntas uma por vez, com ramificação pela resposta** (triagem, pesquisa,
  o agente pedindo esclarecimento) é o `Questionnaire`, e não o `Steps`.
- **Passo que só se chama "Passo 2"** não era um passo, era uma rolagem.

## As peças

- `Steps`: a régua, com `onStepChange` para voltar a um passo já feito.
- `WizardFooter`: Voltar e o avanço, sempre no mesmo lugar.
- `useWizard`: o passo da vez, `next`, `back`, `goTo`, `isFirst`, `isLast`.
- `useZodForm` com os campos de todas as etapas.
- `Result`: o desfecho, no lugar do formulário.

## Comportamento

- **Um formulário só por baixo dos passos.** Um `useZodForm` com os campos de
  todas as etapas, e cada passo mostra a parte dele. Formulário por passo perde
  o que foi digitado ao voltar.
- **Valida o passo antes de avançar, e só ele.** `next(() => form.trigger([...]))`
  do `useWizard` cobra os campos daquele passo; o "Próximo" fica travado
  enquanto a checagem assíncrona roda, e dois toques andam um passo só.
- **Voltar nunca perde nada**, e os passos já feitos são clicáveis no `Steps`
  pelo `onStepChange`. Pular para a frente não: o passo seguinte depende do
  anterior.
- **Voltar um passo e errar o envio nunca perdem nada**: o formulário fica na
  memória enquanto a tela está aberta.
- **Rascunho entre visitas é decisão do projeto, e não da biblioteca.** Guardar
  no navegador para sobreviver a recarregar a página expõe o que foi digitado:
  o `localStorage` fica na máquina, sem criptografia, e qualquer script da
  página o lê. Se o produto quiser, guarde só o que não for sensível (nunca
  senha, cartão, documento, dado de saúde ou financeiro), com
  `useLocalStorage`, e limpe no sucesso do envio. Na dúvida, não guarde.
- **A última etapa é revisão**, com cada parte resumida e um "Alterar" que volta
  ao passo dela. O botão final diz o efeito e leva `loading` enquanto envia.
  Depois dele, o desfecho é o `Result`.
- **Sem confirmação em cima da revisão.** A revisão já é a confirmação.
- **Não peça duas vezes o que a pessoa já disse.** O e-mail do passo Cliente
  volta preenchido no passo Envio, e o endereço de cobrança nasce igual ao de
  entrega, com um `Checkbox` marcado "O endereço de cobrança é o mesmo da
  entrega" que, desmarcado, abre os campos. É a WCAG 3.3.7, nível A: digitar de
  novo só para senha nova e para dado que deixou de valer.

```tsx
const STEPS = [
  { id: 'cliente', title: 'Cliente' },
  { id: 'servico', title: 'Serviço' },
  { id: 'revisao', title: 'Revisão' },
]
const FIELDS = [['document', 'name'], ['service', 'amount'], []] as const

const form = useZodForm(schema, { defaultValues: EMPTY })
const wizard = useWizard(STEPS)
const [validationCount, setValidationCount] = useState(0)

async function checkStep() {
  const ok = await form.trigger([...FIELDS[wizard.step]])
  if (!ok) setValidationCount((n) => n + 1)
  return ok
}

<Steps steps={STEPS} step={wizard.step} onStepChange={wizard.goTo} />
<FormErrorSummary validationCount={validationCount} />
<WizardFooter>
  {!wizard.isFirst && <Button variant="secondary" onClick={wizard.back}>Voltar</Button>}
  {wizard.isLast ? (
    <Button key="submit" type="submit" loading={form.formState.isSubmitting}>Emitir nota</Button>
  ) : (
    <Button key="next" type="button" onClick={() => wizard.next(checkStep)}>
      Continuar
    </Button>
  )}
</WizardFooter>
```

O `key` diferente nos dois botões faz o React criar outro botão no último
passo, em vez de trocar o tipo do mesmo. O `useWizard` já troca o passo só
depois que o clique termina; a chave é a segunda trava, para assistente escrito
sem ele.

O formulário é um só para os três passos, então voltar da Revisão ao Cliente
encontra tudo como estava.

## Texto

- Cada passo é **nomeável por substantivo**: "Cliente", "Serviço", "Revisão".
- O botão final diz o efeito: "Emitir nota", e não "Concluir".
- O avanço dos passos do meio é "Continuar"; o recuo é "Voltar", e nunca
  "Cancelar", que soa como desistir de tudo.

## Acessibilidade

- O `Steps` marca o passo atual com `aria-current="step"`. Com `onStepChange`,
  os já feitos são botões de verdade; o atual, os futuros e os feitos sem
  `onStepChange` não são botão nenhum, nem desabilitado: não param no `Tab`.
- Ao trocar de passo, leve o foco ao título do passo novo, senão o leitor de
  tela continua lendo o rodapé.
- O erro de validação do passo aparece no campo, e o resumo dos erros no topo
  do passo quando houver mais de um (`FormErrorSummary`). O resumo espera um
  envio, e o passo não envia: conte cada `trigger()` que falhou em
  `validationCount`, e cada número novo mostra os erros e leva o foco ao resumo
  (no nativo, anuncia). O título padrão diz "para enviar"; no passo do meio,
  troque por `labels.title` ("Corrija 2 campos para continuar").

## No celular e no nativo

No celular o `Steps` vira "2 de 4" com o nome do passo, e o `WizardFooter`
gruda embaixo (`sticky`), com Voltar e o avanço sempre no mesmo lugar. O fundo
dele é o de quem está em volta: dentro do `Card`, do `Dialog` ou da `Sheet` ele
pinta a superfície deles sozinho, e solto na página pinta o fundo da página.
Cartão montado à mão não diz o fundo, e o rodapé sai no da página: use o `Card`.
Na mesa o avanço fica sempre à direita, mesmo no primeiro passo, sem o Voltar. No
`@rivocode/ui-native` o `Steps` é só esse modo estreito, sem `onStepChange`, e o
`useWizard()` atravessa inteiro.

## Os blocos que o aplicam

Nenhum bloco do site é um wizard ainda. O Cadastro de paciente, em
<https://ds.rivocode.com.br/blocos>, é o formulário único em seções: a resposta
quando a checagem dá "não" nas quatro perguntas.
