Campo de formulário

Estrutura do campo: label, obrigatório (*), dica e mensagem de erro na ordem a11y correta. Integra-se ao react-hook-form (via Controller ou register) e esquemas Zod (@semec/ds/react/validacao). Liga o campo filho pelo contexto (`FormFieldContext`): `id` (gerado com `useId` se faltar), `aria-describedby` (sem erro, a dica; com erro, a dica sai e ele aponta só para a mensagem de erro) e `aria-invalid`. Suporta três padrões de erro: inline, resumo no topo com ErrorSummary e falha de servidor com Alert. Inclui padrão para legenda auxiliar de ação/download em botões de envio. No código: form-field — src/components/form-field.tsx · Formulários

Quando usar

Para estruturar todo campo interativo de formulário (Input, Textarea, Select, Combobox, DatePicker, Checkbox, RadioGroup, Switch, FileUpload, InputOTP, Slider). Ele garante que rótulo, indicador obrigatório (*), texto de apoio e mensagem de erro estejam na ordem semântica correta e ligados via acessibilidade sem esforço manual.

Quando não usar

Para botões de ação isolados ou links de navegação avulsos fora do contexto de campo rotulável. Não use FormField para exibir alertas globais de página — para isso utilize Alert, ErrorSummary ou ErrorState.

Acessibilidade

  • Associação semântica completa: id, label (htmlFor / aria-labelledby), hint e error (aria-describedby) e aria-invalid chegam automaticamente ao controle filho.
  • Três padrões de erro: 1. Erro inline no campo (via prop error, anunciado ao focar o campo); 2. Resumo consolidado no topo via ErrorSummary (com foco automático e links âncora para os campos); 3. Erro de submissão do servidor (Alert destructive no topo ou campos específicos).
  • role="alert": por padrão a mensagem inline não usa role="alert" para não poluir ou interromper leitores de tela quando há múltiplos campos inválidos (o resumo assume o anúncio imediato, AUD-22). Em campos avulsos, pode ser ativado com errorRole="alert".
  • Contraste da mensagem de erro: utiliza var(--feedback-danger) / --pv-red-700 (#b91c1c), garantindo 5,98:1 sobre fundo branco (superando o critério WCAG AA de 4.5:1).
  • Legenda auxiliar de ação / download: botões de envio que geram efeitos secundários (ex.: download de PDF ou envio assíncrono) devem conter legenda explicativa complementar abaixo do botão (ex.: text-xs text-muted-foreground) associada ao botão ou visualmente orientada.

Padrão Canônico com React Hook Form e Zod

O FormField integra-se de forma transparente com react-hook-form tanto via register quanto via Controller, recebendo a mensagem de erro direto de errors[field]?.message:

Preview

Variantes e composição

Prop / grupoValores
propslabel · htmlFor · required · hint · error (mensagem; implica invalid) · invalid (sem mensagem) · errorRole ("alert" | undefined) · id
hooksuseFormField · useFormFieldControl (para campos próprios)
padrões1. Inline (FormField error) · 2. Resumo topo (ErrorSummary) · 3. Servidor (Alert destructive) · Legenda de ação no botão

Uso

Fonte do componente