Questionnaire
Onboarding, uma pergunta por vez
O agente pergunta, a pessoa responde
{
"perguntas": [
"especialidade",
"periodo"
]
}Pergunta desabilitada e erro
import { Questionnaire } from '@rivocode/ui'Quando usar
Um formulário que faz uma pergunta por vez. Guarda as respostas, diz em que pergunta a pessoa está, valida antes de avançar e cuida do voltar, do pular e do enviar. Serve para o agente de IA que precisa de um esclarecimento antes de agir, para o onboarding, para a pesquisa curta, para a triagem e para a configuração inicial.
<Questionnaire aria-label="Configurar a conta" onSubmit={(answers) => save(answers)}>
<QuestionnaireProgress />
<QuestionnaireItem name="equipe" required>
<QuestionnaireTitle>Quantas pessoas vão usar a conta?</QuestionnaireTitle>
<QuestionnaireDescription>Dá para convidar mais gente depois.</QuestionnaireDescription>
<QuestionnaireChoices>
<QuestionnaireChoice value="solo">Só eu</QuestionnaireChoice>
<QuestionnaireChoice value="pequena">De 2 a 10 pessoas</QuestionnaireChoice>
</QuestionnaireChoices>
<QuestionnaireError />
</QuestionnaireItem>
<QuestionnaireItem name="avisos" multiple>
<QuestionnaireTitle>Por onde você quer receber os avisos?</QuestionnaireTitle>
<QuestionnaireChoices>
<QuestionnaireChoice value="email">E-mail</QuestionnaireChoice>
<QuestionnaireChoice value="whatsapp">WhatsApp</QuestionnaireChoice>
</QuestionnaireChoices>
<QuestionnaireInput placeholder="Outro canal" />
</QuestionnaireItem>
<QuestionnaireFooter>
<QuestionnairePrevious />
<QuestionnaireSkip />
<QuestionnaireNext />
<QuestionnaireSubmit />
</QuestionnaireFooter>
</Questionnaire>
Uma pergunta por vez
Cada QuestionnaireItem é um <fieldset>, e o QuestionnaireTitle é a
<legend> dele: o leitor de tela anuncia a pergunta junto com cada opção. Só a
pergunta aberta aparece; as outras ficam escondidas e inert, fora do Tab e
fora da leitura. A troca desliza para o lado da direção, com a curva e a
duração dos tokens de movimento, e sem deslize quando o sistema pede para
reduzir movimento.
A ordem é a ordem em que os itens aparecem na árvore. defaultItem abre em
outra pergunta; item e onItemChange controlam a pergunta aberta pelo
name, para quem quer guardar o passo na URL.
QuestionnaireProgress escreve "Pergunta 2 de 5" e a barra do Progress com o
mesmo valor. Ao avançar, o foco vai para o primeiro controle da pergunta nova.
Obrigatória e opcional
requirednão deixa avançar sem resposta, e o "Pular" some.- Sem
required, a pergunta vale de dois jeitos: com resposta, ou pulada de propósito pelo "Pular". Avançar sem nenhum dos dois também mostra erro, porque em pesquisa pular por engano e pular por escolha são coisas diferentes. O título ganha a marca "Opcional".
Quando a validação falha, o QuestionnaireError do item diz o motivo (sem ele
na árvore, a frase sai sozinha no fim do item), o item fica descrito por ela, e
o foco vai para o primeiro controle. No envio, a validação passa por todas as
perguntas e volta para a primeira que falhou.
onStatusChange de cada item conta quando ele muda entre unanswered,
answered e skipped. disabled mostra a pergunta sem deixar responder: ela
fica fora da validação e das respostas.
As respostas
As opções são <input> nativos, e o name do item é o name deles: sem
multiple são radios, com multiple são caixas de marcar. O
QuestionnaireInput também leva o name do item. Por isso o formulário é um
formulário de verdade, e o onSubmit recebe a mesma resposta de duas formas:
<Questionnaire
onSubmit={(answers, data) => {
answers.equipe // "pequena"
answers.avisos // ["email", "SMS"]
data.getAll('avisos') // o mesmo, pelo FormData
}}
/>
Pergunta pulada fica ausente dos dois, e não com texto vazio. Pular também
limpa o que já estava marcado nela, e a limpeza passa pelo onChange de cada
controle: um QuestionnaireInput controlado recebe o texto vazio como se a
pessoa tivesse apagado, e o estado de quem controla acompanha a tela.
Respostas que já vêm marcadas
defaultAnswers traz as respostas de antes, no mesmo formato do onSubmit:
texto na escolha única e no campo livre, lista no multiple. Valor que não é
de nenhuma opção vai para o QuestionnaireInput do item, como resposta
"outra". Vale na montagem, como o defaultValue de um campo, e a pergunta
preenchida assim já conta como respondida no progresso e na validação.
onAnswersChange entrega as respostas a cada mudança e a cada pulo, para
guardar o rascunho enquanto a pessoa responde. Juntos, os dois retomam um
questionário interrompido:
<Questionnaire
defaultAnswers={draft ?? undefined}
onAnswersChange={(answers) => saveDraft(answers)}
onSubmit={(answers) => send(answers)}
/>
Não há answers controlado no web: as respostas moram nos <input> do
formulário, e o FormData do onSubmit sai deles. Quem precisa controlar um
campo controla o QuestionnaireInput ou a QuestionnaireChoice com checked.
No servidor, a pergunta aberta já sai no HTML: item, defaultItem ou, sem
nenhum dos dois, a primeira na ordem da página, com os botões dela.
Sozinho no item, o QuestionnaireInput é a resposta livre, e o nome dele é o
título da pergunta. Ao lado de opções ele é a resposta "outra", e o nome falado
é "Outra resposta": numa pergunta de escolha única, escrever nele desmarca a
opção, e marcar uma opção apaga o texto; com multiple, o texto entra na lista
junto com as marcadas.
O teclado
Cada opção tem um atalho: A, B, C, ou 1, 2, 3 com
shortcuts="numbers". A letra aparece na própria opção e vai para o
aria-keyshortcuts do input. O atalho vale com o foco dentro do questionário e
para enquanto se digita num campo: escrever "abc" no campo livre não marca
nada. shortcuts={false} desliga.
Ctrl+Enter (ou ⌘+Enter) valida e avança, e na última pergunta envia. No campo livre, Enter faz o mesmo.
Com um agente de IA
É a forma de o agente pedir esclarecimento sem sair da conversa: o ToolCall
mostra o que ele quer, e o questionário colhe a resposta. Quando a pessoa
envia, a chamada vira done com as respostas de saída.
const [answers, setAnswers] = useState<QuestionnaireAnswers | null>(null)
<ToolCall
name="pedir_esclarecimento"
title="Preciso de duas respostas antes de agendar"
status={answers ? 'done' : 'approval'}
output={answers ?? undefined}
/>
{!answers && (
<Questionnaire shortcuts="numbers" onSubmit={(sent) => setAnswers(sent)}>
<QuestionnaireItem name="periodo" required>
<QuestionnaireTitle>Qual período a paciente prefere?</QuestionnaireTitle>
<QuestionnaireChoices>
<QuestionnaireChoice value="manha">Manhã</QuestionnaireChoice>
<QuestionnaireChoice value="tarde">Tarde</QuestionnaireChoice>
</QuestionnaireChoices>
</QuestionnaireItem>
<QuestionnaireFooter>
<QuestionnaireSubmit>Responder ao agente</QuestionnaireSubmit>
</QuestionnaireFooter>
</Questionnaire>
)}
shortcuts="numbers" combina com o campo de prompt ao lado: letra é o que a
pessoa digita na conversa, e o atalho só vale com o foco no questionário.
Os textos
Todos saem em português e todos se trocam por labels: progress (recebe a
posição e o total), previous, skip, next, submit, required,
unanswered, other e optional. Os botões também aceitam filho, que vale
só para aquele botão.
Partes
QuestionnaireProgress: o texto e a barra; aceita oclassNamesdoProgress(label,value,track,indicator).QuestionnaireItem,QuestionnaireTitle,QuestionnaireDescription: a pergunta.QuestionnaireChoices,QuestionnaireChoice: as opções.classNamesda opção alcançacontrol(a linha inteira),key,label,descriptioneindicator.QuestionnaireInput: a resposta livre, ou a "outra".QuestionnaireError: a frase do erro, no lugar que você escolher.QuestionnaireFootercomQuestionnairePrevious,QuestionnaireSkip,QuestionnaireNexteQuestionnaireSubmit: os botões são oButtonda casa. O "Voltar" encosta à esquerda, o "Próxima" some na última pergunta e o "Enviar" só existe nela.
Quando não usar
- Todas as perguntas cabem numa tela: use o
Form, com umFormFieldpor pergunta. Esconder quatro perguntas curtas atrás de quatro cliques troca uma olhada por uma sequência, e quem quer revisar antes de enviar não vê nada. - Etapas longas, cada uma com vários campos: use
Stepscom ouseWizard. O questionário é uma pergunta por tela; um cadastro em que cada passo tem endereço, telefone e documento é assistente, e a régua doStepsmostra os passos pelo nome. - Uma escolha só, dentro de outra tela:
RadioGroupouCheckboxGroup. Um questionário de uma pergunta é um grupo de opções com progresso "1 de 1". - Confirmar uma ação do agente: o
ToolCallemapprovaljá tem Aprovar e Recusar. O questionário é para quando a resposta não cabe num sim ou não.
No React Native
Traduz, uma pergunta por vez e com os mesmos estados: obrigatória não avança sem resposta, opcional vale por resposta ou por pular, e o envio volta para a primeira pergunta que falhou. A regra de validação e os textos moram num arquivo só, compartilhado pelos dois pacotes, e labels troca os mesmos nomes.
A API é a do toque: tudo é controlado (item e onItemChange, value e onValueChange), e as perguntas vêm por items, cada uma com type single, multiple ou text, e other para o campo de resposta outra. Não há atalho de letra, porque não há teclado físico; a troca de pergunta e o erro saem pelo anúncio do leitor de tela do sistema, e a pergunta nova entra com os tokens de movimento.
O defaultAnswers e o onAnswersChange do web não fazem falta aqui: as respostas já são o value controlado, e o rascunho se retoma passando o salvo como valor inicial do estado.
API
| Prop | Tipo | Padrão |
|---|---|---|
defaultAnswersAs respostas que ja vem marcadas, pela chave de cada item: texto na escolha unica e no campo livre, lista no `multiple`. | QuestionnaireAnswers | sem padrão |
defaultItemA pergunta aberta no comeco, sem controlar. | string | sem padrão |
itemA pergunta aberta, pelo `name` do item. | string | sem padrão |
labelsOs textos da peca: botoes, progresso e erros, para outra lingua ou outro tom. | Partial<QuestionnaireLabels> | sem padrão |
onAnswersChangeChamado a cada resposta que muda e a cada pergunta pulada, com o mesmo formato do `onSubmit`. | ((answers: QuestionnaireAnswers) => void) | sem padrão |
onItemChangeChamado a cada troca de pergunta, com o `name` da nova. | ((item: string) => void) | sem padrão |
onSubmitChamado quando a ultima pergunta valida e todas as anteriores tambem. | ((answers: QuestionnaireAnswers, data: FormData) => void) | sem padrão |
ref | Ref<HTMLFormElement> | sem padrão |
shortcutsO atalho de cada opcao: `letters` marca a primeira com A, `numbers` com 1. | false | QuestionnaireShortcuts | "letters" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.