Pular para o conteúdo
Formulário

Form

/componentes/form.mdmarkdown cru, para quem lê com agent em vez de olho

Enviar cobrança

Para onde vai a cobrança

Resumo de erros

Importar
import { Form } from '@rivocode/ui/form'

Quando usar

O <form> e o contexto do React Hook Form numa peça só, para o FormField achar o control sozinho. Vive em @rivocode/ui/form.

Vai com noValidate: quem valida é o schema, e o balão nativo do navegador apareceria em inglês, fora do tema e antes da nossa mensagem.

O onSubmit recebe os valores já validados e convertidos. Use com o useZodForm, que liga o resolver e separa o tipo de entrada do de saída.

Formulário que não cabe numa tela leva o FormErrorSummary como primeiro filho: ao enviar com erro, ele lista no topo cada campo que falta, com link para o campo, e mostra o erro do servidor posto em root. É opcional, e a página dele diz por quê.

Formulário de editar o que já existe, como configurações e cadastro, leva o FormSaveBar como último filho: a barra de salvar que entra quando há mudança, com "Descartar mudanças" e "Salvar mudanças", e diz a hora do salvo. A página da SaveBar conta os quatro estados e o useUnsavedChanges, que avisa ao sair com mudança pendente.

Quando não usar

Perguntas que vêm uma por vez, como onboarding, pesquisa ou triagem, são Questionnaire, que valida antes de avançar. Etapas em que a escolha de uma muda a seguinte são Steps com useWizard. O Form é o formulário que cabe numa tela.

Campo que não envia nada, como o filtro de uma listagem, não precisa de Form nem de schema: um SearchInput com estado próprio basta. E para corrigir um valor sem sair da tela, é Editable, que salva ao sair do campo.

No React Native

Traduz, no caminho próprio @rivocode/ui-native/form, com o mesmo arranjo do web e pela mesma razão: o react-hook-form é peer opcional. O useZodForm é idêntico, linha por linha, porque não há navegador nele.

O que muda é quem dispara o envio. No React Native não existe <form>, não existe type="submit" e não existe Enter que envie: nada é implícito. Então o Form entrega o envio a quem desenha o botão (children pode ser uma função que recebe { submit, isSubmitting }), e continua aceitando JSX comum para quando o botão mora fora, numa barra fixa no rodapé da tela.

E muda a ponte com o controle. No web o Field da Base UI liga rótulo, ajuda e erro a qualquer controle que esteja dentro, pelo contexto; aqui o contexto é mais estreito: o Field nativo leva aos campos de digitar (Input, Textarea, InputGroup, MaskedInput) o rótulo, como accessibilityLabel quando quem chama não passou outro, o erro, como dica, e a validação do validate. O campo que o FormField entrega leva mesmo assim duas coisas a mais, accessibilityLabel e invalid, e os adaptadores as põem no controle: as peças que se nomeiam por label não leem o contexto, e sem isso ficariam sem nome nenhum para o leitor de tela. O label do FormField é obrigatório aqui pela mesma razão.

O adaptador entrega o rótulo no nome que a peça lê. As peças nativas se nomeiam por label, e o forValue, o forChecked e o forDate o entregam assim; o forText o entrega como accessibilityLabel, porque o Input e o Textarea são o TextInput da plataforma. O forValue leva os dois, porque serve também a campo de texto com valor próprio, como o CurrencyInput.

O FormErrorSummary atravessa com a lista, o rótulo de cada campo, o erro do servidor em root e os textos do web. Ele não toma o foco, porque no celular o leitor de tela não segue o foco para uma caixa que não é controle: anuncia o resumo inteiro a cada envio que termina com erro (announceOnError, no lugar do focusOnError). O validationCount do web vem junto: no passo do assistente, que valida com trigger() sem enviar, cada número novo mostra os erros e anuncia o resumo de novo. Cada item é um link que chama o form.setFocus do campo, que funciona nos de digitar entregues pelo forText; nos de folha, o toque não abre a folha.

Os adaptadores são cinco. forValue, forChecked e forDate têm o nome e o trabalho do web. O forDate agora converte o vazio para null e fala ISO, que é o que o DatePicker e o DateRangePicker nativos pedem. O quarto é só daqui: forText, para Input e Textarea, porque o TextInput chama onChangeText com a string crua e não com um evento: espalhar o campo nele guardaria no formulário um objeto de evento que não existe. Ele leva o ref junto, e aí o form.setFocus() funciona de verdade: TextInput tem focus(). E traduz o disabled do campo para editable={false}, porque o TextInput não lê disabled. O quinto também é só daqui: forFiles, para o FileUpload, que é o forValue sem o label, porque ali o label é o texto do botão, e o rótulo do campo chega pelo Field.

API

PropTipo
formobrigatória0.4.0

O retorno do `useZodForm` ou do `useForm`.

UseFormReturn<Entry, unknown, Saida>
onSubmitobrigatória0.4.0

Chamado com os valores ja validados e convertidos pelo schema.

SubmitHandler<Saida>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Partes

Form se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

FormErrorSummary

/form-error-summary.md

O resumo de erros do formulário, no padrão do GOV.UK e da WCAG 3.3.1: ao enviar com erro, um bloco no topo diz quantos campos faltam e lista cada um, com o rótulo e a mensagem, e cada item é um link que leva o foco ao controle do campo. Vive em @rivocode/ui/form, e se põe como primeiro filho do Form.

<Form form={form} onSubmit={save}>
  <FormErrorSummary />
  <FormField name="name" label="Nome do cliente">
    {(field) => <Input {...field} placeholder="Ex.: Ateliê Ramos Ltda." />}
  </FormField>
  <FormField name="document" label="CPF ou CNPJ">
    {(field) => <MaskedInput {...forValue(field)} mask="cpfCnpj" />}
  </FormField>
  <Button type="submit" loading={form.formState.isSubmitting}>Salvar cliente</Button>
</Form>

Ele lê o estado do React Hook Form, e não guarda nada. Antes do primeiro envio não aparece, mesmo com campo já tocado e errado: o erro de cada campo já mora embaixo dele, e um bloco vermelho no topo enquanto a pessoa ainda preenche é acusação antes da hora. Depois do envio, a lista acompanha o que falta: cada campo corrigido sai dela, e o bloco some quando não falta nada.

A ordem é a da tela, e não a do schema. O rótulo vem do label do FormField, e é por isso que ele acompanha a mensagem: o erro de campo da casa diz o formato aceito ("Use o formato 00.000.000/0000-00"), e no topo da página, longe do campo, a frase sozinha não diria de quem é.

O erro do servidor

O que não é de um campo ("Este CNPJ já está cadastrado") entra pelo setError em root, e aparece no topo do resumo, sem link, porque não há campo para onde ir. O título passa a dizer "Não foi possível enviar".

async function save(values: Customer) {
  const answer = await api.createCustomer(values)
  if (answer.status === 409) {
    form.setError('root.serverError', {
      message: 'Este CNPJ já está cadastrado para outro cliente. Busque por ele na lista.',
    })
  }
}

O foco

A cada envio que termina com erro, inclusive o do servidor, o foco vai para o resumo, e o leitor de tela lê o título e a lista na hora. O React Hook Form leva o foco ao primeiro campo errado, como sempre fez, e o resumo o toma logo depois. Quem segue o link chega ao controle, com a página rolada até ele; no DatePicker e no DateTimePicker, ao campo de digitar a data. focusOnError={false} deixa o foco onde o formulário o pôs, para a tela que já move o foco por conta própria.

No passo do assistente

O resumo espera um envio (submitCount), e o passo do assistente valida com trigger() sem enviar. Conte as validações do passo em validationCount: maior que zero, os erros de campo aparecem sem envio, e cada número novo leva o foco ao resumo de novo, como um envio com erro faria. O número só cresce.

const [validationCount, setValidationCount] = useState(0)

<FormErrorSummary
  validationCount={validationCount}
  labels={{ title: (n) => (n === 1 ? 'Corrija 1 campo para continuar' : `Corrija ${n} campos para continuar`) }}
/>
<Button
  type="button"
  onClick={() =>
    wizard.next(async () => {
      const ok = await form.trigger([...FIELDS[wizard.step]])
      if (!ok) setValidationCount((n) => n + 1)
      return ok
    })
  }
>
  Continuar
</Button>

O título padrão diz "para enviar"; no passo do meio, troque por labels.title. No React Native a prop é a mesma, e cada número novo anuncia o resumo.

Num formulário em seções de Accordion, passe hiddenUntilFound em cada AccordionItem: o campo da seção fechada continua montado, e o link do resumo abre a seção antes de levar o foco a ele.

Por que é opcional

O Form não desenha o resumo sozinho. Formulário de dois campos, como o de entrar, tem os dois erros à vista embaixo de cada campo, e o resumo seria a mesma coisa dita duas vezes. Ele paga a conta no formulário que não cabe numa tela, onde o erro do terceiro campo fica fora da vista e o botão de enviar "não faz nada". E quem decide onde fica o topo é a tela: dentro de um Card, abaixo do PageHeader, acima das abas.

Quando não usar

O erro de um campo é do FormField, embaixo dele, e o resumo não o substitui: ele aponta, e o campo explica. Aviso que não vem de envio (o cartão que vence amanhã, o banco fora do ar) é Alert, que fica na tela, ou Banner, no topo da página inteira. E a confirmação de que deu certo é useToast ou Result, nunca este bloco.

PropTipoPadrão
classNames

Classe por parte: `title`, `description`, `list` e `link` (cada erro).

Partial<Record<"description" | "link" | "list" | "title", string>>sem padrão
description

Uma frase embaixo do titulo, para o que vale para o formulario inteiro.

ReactNodesem padrão
focusOnError

Leva o foco ao resumo a cada envio que termina com erro, inclusive o erro do servidor posto por `setError("root.serverError")` no `onSubmit`.

booleantrue
labels

Os textos da peca, para trocar o idioma: `title` recebe quantos campos tem erro e devolve o titulo; com zero, o erro e so do servidor.

Partial<FormErrorSummaryLabels>sem padrão
validationCount

Quantas vezes o formulario foi validado sem enviar, contado por quem valida: e o `submitCount` do passo do assistente, que cobra os campos com `trigger()` e nao envia.

number0

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

Uma linha de formulário inteira: rótulo, controle, ajuda e erro, ligados entre si. Vive em @rivocode/ui/form.

O controle vem por função, e não por clonagem do filho, porque cada controle do catálogo recebe valor de um jeito e adivinhar qual falha na tela, não no tipo:

<FormField name="email" label="E-mail">
  {(campo) => <Input {...campo} />}
</FormField>

Para Input e Textarea, espalhar o campo basta. Para Select, Checkbox e DatePicker, os adaptadores fazem a ponte.

Ele não inventa id nenhum: quem liga o rótulo ao controle é o Field da Base UI, pelo contexto.

necessity vai ao rótulo como no FieldLabel: optional escreve "(opcional)", e required desenha o asterisco. O schema não é lido, de propósito: quem decide é a tela, que sabe qual é a minoria do formulário.

<FormField name="complemento" label="Complemento" necessity="optional">
  {(campo) => <Input {...campo} placeholder="Ex.: Sala 4" />}
</FormField>
PropTipo
nameobrigatória0.4.0

O caminho do campo no schema.

Name
control0.4.0

So quando o campo vive fora de um `<Form>`.

Control<Values>
description0.4.0ReactNode
label0.4.0ReactNode
necessity

A marca do rotulo, a mesma do `FieldLabel`: `optional` escreve "(opcional)", e `required` desenha o asterisco.

FieldNecessity

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.