Form
Enviar cobrança
Resumo de erros
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
| Prop | Tipo |
|---|---|
formobrigatória0.4.0O retorno do `useZodForm` ou do `useForm`. | UseFormReturn<Entry, unknown, Saida> |
onSubmitobrigatória0.4.0Chamado 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.mdO 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.
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `title`, `description`, `list` e `link` (cada erro). | Partial<Record<"description" | "link" | "list" | "title", string>> | sem padrão |
descriptionUma frase embaixo do titulo, para o que vale para o formulario inteiro. | ReactNode | sem padrão |
focusOnErrorLeva o foco ao resumo a cada envio que termina com erro, inclusive o erro do servidor posto por `setError("root.serverError")` no `onSubmit`. | boolean | true |
labelsOs 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 |
validationCountQuantas 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. | number | 0 |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
FormField
/form-field.mdUma 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>
| Prop | Tipo |
|---|---|
nameobrigatória0.4.0O caminho do campo no schema. | Name |
control0.4.0So quando o campo vive fora de um `<Form>`. | Control<Values> |
description0.4.0 | ReactNode |
label0.4.0 | ReactNode |
necessityA 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.