# Questionnaire

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.

```tsx
<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

- **`required`** nã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:

```tsx
<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:

```tsx
<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.

```tsx
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 o `classNames` do
  `Progress` (`label`, `value`, `track`, `indicator`).
- `QuestionnaireItem`, `QuestionnaireTitle`, `QuestionnaireDescription`: a
  pergunta.
- `QuestionnaireChoices`, `QuestionnaireChoice`: as opções. `classNames` da
  opção alcança `control` (a linha inteira), `key`, `label`, `description` e
  `indicator`.
- `QuestionnaireInput`: a resposta livre, ou a "outra".
- `QuestionnaireError`: a frase do erro, no lugar que você escolher.
- `QuestionnaireFooter` com `QuestionnairePrevious`, `QuestionnaireSkip`,
  `QuestionnaireNext` e `QuestionnaireSubmit`: os botões são o `Button` da
  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 um `FormField` por
  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 `Steps` com o
  `useWizard`. O questionário é uma pergunta por tela; um cadastro em que cada
  passo tem endereço, telefone e documento é assistente, e a régua do `Steps`
  mostra os passos pelo nome.
- **Uma escolha só, dentro de outra tela**: `RadioGroup` ou `CheckboxGroup`.
  Um questionário de uma pergunta é um grupo de opções com progresso "1 de 1".
- **Confirmar uma ação do agente**: o `ToolCall` em `approval` já 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.

## Importação

```tsx
import { Questionnaire } from '@rivocode/ui'
```

## Exemplos

### Onboarding, uma pergunta por vez

```tsx
import {
  Questionnaire,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireFooter,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
  type QuestionnaireAnswers,
} from '@rivocode/ui'
import { Message, ToolCall } from '@rivocode/ui/ai'
import { useState } from 'react'

export function Onboarding() {
  const [answers, setAnswers] = useState<QuestionnaireAnswers | null>(null)

  return (
    <div className="flex w-full max-w-lg flex-col gap-4">
      <Questionnaire aria-label="Configurar a conta" onSubmit={(sent) => setAnswers(sent)}>
        <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>
            <QuestionnaireChoice value="grande">Mais de 10 pessoas</QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireItem name="avisos" multiple>
          <QuestionnaireTitle>Por onde você quer receber os avisos?</QuestionnaireTitle>
          <QuestionnaireDescription>Marque quantos quiser.</QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="email">E-mail</QuestionnaireChoice>
            <QuestionnaireChoice value="whatsapp">WhatsApp</QuestionnaireChoice>
            <QuestionnaireChoice value="app" description="Aparece no sino, no topo da tela">
              Notificação no app
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireInput placeholder="Outro canal" />
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireItem name="objetivo">
          <QuestionnaireTitle>O que você quer resolver primeiro?</QuestionnaireTitle>
          <QuestionnaireInput placeholder="Ex.: organizar os projetos do time" />
          <QuestionnaireError />
        </QuestionnaireItem>

        <QuestionnaireFooter>
          <QuestionnairePrevious />
          <QuestionnaireSkip />
          <QuestionnaireNext />
          <QuestionnaireSubmit />
        </QuestionnaireFooter>
      </Questionnaire>

      {answers && (
        <pre className="rounded-md border border-border bg-surface-raised p-3 font-mono text-xs text-fg-muted">
          {JSON.stringify(answers, null, 2)}
        </pre>
      )}
    </div>
  )
}
```

### O agente pergunta, a pessoa responde

```tsx
import {
  Questionnaire,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireFooter,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
  type QuestionnaireAnswers,
} from '@rivocode/ui'
import { Message, ToolCall } from '@rivocode/ui/ai'
import { useState } from 'react'

export function AgentAsks() {
  const [answers, setAnswers] = useState<QuestionnaireAnswers | null>(null)

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Message role="user">Marque o retorno da paciente Lívia Antunes para a semana que vem.</Message>
      <ToolCall
        name="pedir_esclarecimento"
        title="Preciso de duas respostas antes de agendar"
        status={answers ? 'done' : 'approval'}
        input={{ perguntas: ['especialidade', 'periodo'] }}
        output={answers ?? undefined}
      />
      {!answers && (
        <div className="rounded-lg border border-border bg-surface p-4">
          <Questionnaire
            aria-label="Esclarecimento para agendar a consulta"
            shortcuts="numbers"
            onSubmit={(sent) => setAnswers(sent)}
          >
            <QuestionnaireProgress />

            <QuestionnaireItem name="especialidade" required>
              <QuestionnaireTitle>O retorno é com qual especialidade?</QuestionnaireTitle>
              <QuestionnaireChoices>
                <QuestionnaireChoice value="cardiologia" description="Dra. Helena Prado">
                  Cardiologia
                </QuestionnaireChoice>
                <QuestionnaireChoice value="clinica-geral" description="Dr. Rafael Moura">
                  Clínica geral
                </QuestionnaireChoice>
              </QuestionnaireChoices>
              <QuestionnaireError />
            </QuestionnaireItem>

            <QuestionnaireItem name="periodo" required>
              <QuestionnaireTitle>Qual período a paciente prefere?</QuestionnaireTitle>
              <QuestionnaireDescription>
                Está na ficha dela; na dúvida, confirme com a recepção.
              </QuestionnaireDescription>
              <QuestionnaireChoices>
                <QuestionnaireChoice value="manha">Manhã</QuestionnaireChoice>
                <QuestionnaireChoice value="tarde">Tarde</QuestionnaireChoice>
              </QuestionnaireChoices>
              <QuestionnaireError />
            </QuestionnaireItem>

            <QuestionnaireFooter>
              <QuestionnairePrevious />
              <QuestionnaireNext />
              <QuestionnaireSubmit>Responder ao agente</QuestionnaireSubmit>
            </QuestionnaireFooter>
          </Questionnaire>
        </div>
      )}
    </div>
  )
}
```

### Pergunta desabilitada e erro

```tsx
import {
  Questionnaire,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireFooter,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
  type QuestionnaireAnswers,
} from '@rivocode/ui'
import { Message, ToolCall } from '@rivocode/ui/ai'
import { useState } from 'react'

export function States() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-8">
      <Questionnaire aria-label="Pergunta desabilitada">
        <QuestionnaireItem name="endereco" disabled>
          <QuestionnaireTitle>Qual endereço a loja vai usar?</QuestionnaireTitle>
          <QuestionnaireDescription>
            Libera depois que o domínio próprio for verificado.
          </QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="dominio">Domínio próprio</QuestionnaireChoice>
            <QuestionnaireChoice value="subdominio">Subdomínio gratuito</QuestionnaireChoice>
          </QuestionnaireChoices>
        </QuestionnaireItem>
      </Questionnaire>

      <Questionnaire aria-label="Pergunta com erro">
        <QuestionnaireItem name="aceite" required>
          <QuestionnaireTitle>Quem aprova as compras da equipe?</QuestionnaireTitle>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="dono">O dono da conta</QuestionnaireChoice>
            <QuestionnaireChoice value="financeiro">O gestor financeiro</QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireFooter>
          <QuestionnaireSubmit>Enviar sem responder</QuestionnaireSubmit>
        </QuestionnaireFooter>
      </Questionnaire>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `defaultAnswers` | `QuestionnaireAnswers` |  |  | - | As respostas que ja vem marcadas, pela chave de cada item: texto na escolha unica e no campo livre, lista no `multiple`. |
| `defaultItem` | `string` |  |  | - | A pergunta aberta no comeco, sem controlar. |
| `item` | `string` |  |  | - | A pergunta aberta, pelo `name` do item. |
| `labels` | `Partial<QuestionnaireLabels>` |  |  | - | Os textos da peca: botoes, progresso e erros, para outra lingua ou outro tom. |
| `onAnswersChange` | `((answers: QuestionnaireAnswers) => void)` |  |  | - | Chamado a cada resposta que muda e a cada pergunta pulada, com o mesmo formato do `onSubmit`. |
| `onItemChange` | `((item: string) => void)` |  |  | - | Chamado a cada troca de pergunta, com o `name` da nova. |
| `onSubmit` | `((answers: QuestionnaireAnswers, data: FormData) => void)` |  |  | - | Chamado quando a ultima pergunta valida e todas as anteriores tambem. |
| `ref` | `Ref<HTMLFormElement>` |  |  | - |  |
| `shortcuts` | `false \| QuestionnaireShortcuts` |  | `"letters"` | - | O atalho de cada opcao: `letters` marca a primeira com A, `numbers` com 1. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
