Componentes

Field

beta

A anatomia de um campo: rótulo, controle, texto de apoio e erro. Existe para que nenhuma tela remonte essa relação por conta própria.

Ainda não é estável porque Rota não varrida pelo sensor. Ausência de medição não é aprovação. O contrato de maturidade explica o que cada requisito exige.

@voxmente/ui/components/ui/field

Orientação

A anatomia de um campo de formulário: rótulo, controle, texto de apoio e erro, já ligados entre si. Existe para que nenhuma tela remonte essa relação por conta própria — e erre.

Quando usar

Qualquer controle de formulário que tenha rótulo. Input, Select, Textarea, Checkbox, Switch: todos entram por aqui.
O campo precisa de texto de apoio explicando o formato esperado antes de o usuário errar.
O campo tem estado de erro e o erro precisa ser anunciado, não só pintado de vermelho.

Quando não usar

Para agrupar campos relacionados — isso é FieldSet com FieldLegend, que é outra parte da mesma família.
Para leitura. Pares de rótulo e valor de um registro salvo são Description List, não formulário desabilitado.
Para um controle sem rótulo visível nem acessível: aí o problema é a falta do rótulo, e o Field não conserta isso sozinho.

Playground

Orientaçãoorientation

Rótulochildren

Inválidodata-invalid

Desabilitadodata-disabled

<Field>
  <FieldLabel htmlFor="campo">Nome do aluno</FieldLabel>
  <Input id="campo" />
</Field>

Anatomia

As partes deste componente e como se aninham. A árvore vem das demonstrações desta página, então descreve um exemplo que renderiza.

FieldSet
  └─ FieldLegend
  └─ FieldGroup
    └─ Field
      └─ FieldLabel
    └─ Field
      └─ FieldLabel

Uso

Field é a unidade que junta rótulo, controle e ajuda. Não é um input — é a moldura em volta de um.

`vertical` é o padrão. `horizontal` põe rótulo e controle lado a lado — serve para checkbox e switch, não para texto longo. `responsive` empilha no mobile e alinha a partir do breakpoint do `FieldGroup`.

Notificar responsáveis

Envia um resumo da sessão por e-mail ao final da aula.

Grupo com legenda

`FieldSet` + `FieldLegend` substituem fieldset/legend crus. `FieldGroup` controla o espaçamento entre os Fields — nunca use `gap` manual entre eles.

Dados da turma

Outros controles

Field envolve qualquer controle — não só `Input`. `Textarea`, `Select` e `Slider` seguem a mesma moldura de rótulo e ajuda.

Switch e checkbox

Ativar/desativar usa `Switch` em `orientation="horizontal"`, com o rótulo à esquerda. Para múltiplas opções independentes, use `Checkbox` — o exemplo de orientação acima já mostra o par.

Lembrete de sessão

Avisa a família uma hora antes da aula marcada.

Layout responsivo

`orientation="responsive"` empilha rótulo e controle no mobile e alinha lado a lado a partir do breakpoint do `FieldGroup` que envolve o Field — o `@container` fica no grupo, não na tela. Use quando o mesmo formulário aparece em coluna estreita e larga.

Desabilitado

Field não tem prop `disabled`. Quem desabilita é o controle (`disabled` no `Input`, `Switch` etc.); o esmaecimento do rótulo e do cartão vem de `data-disabled` posto à mão no elemento pai — o Field não lê o estado do filho sozinho.

Cartão selecionável

`FieldLabel` envolvendo um `Field` vira cartão clicável: borda, hover e o estado marcado ficam por conta do CSS do próprio Label — não estilize a mão.

Trilha guiada

O professor define a ordem das lições.

Exploração livre

O aluno escolhe a lição a cada sessão.

Erro de validação

`FieldError` some sozinho quando não há erro nem `children`. Passe `errors` no formato do React Hook Form — mais de uma mensagem vira lista. `data-invalid` é atributo, não prop tipada: marque em cada `Field` que falhou. Ele não propaga de um `FieldSet` para os Fields dentro — validar o grupo não colore os campos sozinho, marque cada um.

Separador

`FieldSeparator` divide seções dentro de um `FieldGroup`. Com `children`, o texto flutua sobre a linha.

Acessibilidade

O que o componente já garante, e o que continua sendo responsabilidade da tela.

O Field aplica role="group": rótulo, apoio e erro são anunciados como uma unidade.
FieldError tem role="alert", então o erro é anunciado quando aparece, sem o usuário precisar voltar ao campo.
O vínculo entre rótulo e controle continua sendo responsabilidade de quem monta: FieldLabel precisa de htmlFor apontando para o id do controle.

Em contexto de produto

Onde isto aparece numa tela real da Vox Mente, e não numa vitrine.

No login, os dois campos usam o texto de apoio para dizer o que a plataforma espera antes de o usuário errar a primeira tentativa.

Ver o bloco de autenticação

Componentes relacionados

Vizinhos que resolvem o problema parecido. Os links são resolvidos contra o registro.

Referência da API

Extraída do TypeScript de @voxmente/ui a cada build. Se divergir do código, o código mudou.

Field

Prop	Tipo	Padrão
orientation	"horizontal" \| "vertical" \| "responsive" \| null	"vertical"

Também aceita as props de React, incluindo className e os atributos de DOM.

FieldError

Prop	Tipo	Padrão
errors	({ message?: string \| undefined; } \| undefined)[]	—

Também aceita as props de React, incluindo className e os atributos de DOM.

FieldLegend

Prop	Tipo	Padrão
variant	"label" \| "legend"	"legend"

Também aceita as props de React, incluindo className e os atributos de DOM.

FieldContent, FieldDescription, FieldGroup, FieldLabel, FieldSeparator, FieldSet, FieldTitle não têm props próprias — aceitam apenas as props herdadas, incluindo className e os atributos de DOM.

Origem do dado

Anatomia: exemplo desta página
Demonstrações e playground: componente real de @voxmente/ui
Referência da API: TypeScript do pacote
Cor, espaçamento e raio das demonstrações: tokens de theme.css