BaseFieldset

Agrupa controles que respondem a uma mesma pergunta: várias caixas de seleção ou alguns interruptores. É um <fieldset> nativo com <legend>, ajuda, erro e aviso do grupo.

Documentos anexados *(obrigatório)

Planilha orçamentária

Cronograma físico-financeiro

ART do responsável técnico

Marque os que já estão no processo SEI.

Avisos por e-mail (opcional)

Medição enviada para aprovação

Aditivo aprovado

Uso

• Use quando duas ou mais caixas ou interruptores só fazem sentido juntos e precisam de um título comum: "Documentos anexados", "Avisos por e-mail".
• A legenda é a pergunta ou o assunto do grupo; o rótulo de cada controle é a resposta, curto e sem pontuação final.
• Para escolher uma opção entre várias, use BaseRadioGroup, que já é um fieldset com o comportamento de rádio.
• Para um período (vigência, prazo de execução), use BaseDateRange, que tem rótulo visível para início e fim e valida a ordem das datas.
• Não coloque um único campo num fieldset: use BaseField. E não coloque BaseFieldset dentro de BaseField, que criaria um segundo rótulo apontando para nenhum campo.
• orientation="horizontal" só para duas ou três opções curtas. Na horizontal, a legenda fica a 6 px das opções, como o rótulo de um BaseField, e as opções têm no mínimo a altura de um campo de texto, então o grupo se alinha aos campos ao lado numa BaseFormGrid.
• hide-label só quando um título visível logo acima já diz o que o grupo é. A legenda continua para o leitor de tela.

Anatomia

1. Legenda: o título do grupo, vinda de label, com o asterisco de required ou o "(opcional)" de optional.
2. Controles: as caixas de seleção ou os interruptores colocados no slot.
3. Mensagem: abaixo dos controles, com a ajuda (helper-text), o erro (invalid-text) ou o aviso (warn-text) do grupo.

Orientação

Dias da vistoria semanal

Segunda

Quarta

Sexta

Legenda oculta

Anexos da medição 29

Anexos da medição 29

Fotos da obra

Boletim de medição assinado

O título acima já nomeia o grupo; a legenda fica só para o leitor de tela, que a ouve ao entrar na primeira caixa.

Estados

Inválido *(obrigatório)

Planilha orçamentária

Cronograma físico-financeiro

Marque pelo menos um documento antes de enviar

Aviso

Planilha orçamentária

ART do responsável técnico

Sem a ART o contrato não pode ser assinado

Desabilitado

Planilha orçamentária

ART do responsável técnico

Os documentos ficam travados depois da assinatura.

• Inválido sempre mostra ícone e texto sob o grupo. Sem invalid-text, aparece "Revise as opções deste grupo"; prefira uma mensagem que diga o que corrigir. Cada BaseCheckbox dentro recebe do grupo o aria-invalid e a borda de erro: não repita invalid nem dê texto de erro a cada caixa.
• BaseSwitch não tem estado inválido. Num grupo de interruptores marcado invalid, a mensagem sob o grupo é o único sinal, e ela é lida quando cada interruptor recebe o foco.
• Aviso só aparece com warn-text. Com invalid e warn ao mesmo tempo, vale o erro.
• Desabilitado desliga todos os controles de uma vez pelo disabled nativo do fieldset. Diga na ajuda por que o grupo não pode mudar.
• Não há estado somente leitura: o HTML não tem readonly para caixa de seleção nem para interruptor. Mostre o valor como texto ou use disabled com o motivo.

Faça e não faça

Faça	Não faça
Agrupe "Planilha orçamentária", "Cronograma" e "ART" sob "Documentos anexados"	Pôr um único campo num fieldset; use o BaseField
Use o BaseRadioGroup para escolher uma só opção	Montar um grupo de rádios à mão dentro do BaseFieldset
Diga na legenda o assunto do grupo, como "Avisos por e-mail"	Repetir o assunto no rótulo de cada caixa

Estilo

Propriedade	Token
Legenda	--tj-text-secondary, --tj-text-sm, semibold; desabilitado --tj-text-placeholder
Obrigatório	* em --tj-support-error-text
Opcional	"(opcional)" em --tj-text-helper, peso regular
Ajuda	--tj-text-helper, --tj-text-sm
Erro	ícone e texto --tj-support-error-text, medium; borda das caixas --tj-support-error-text
Aviso	ícone e texto --tj-support-warning-text, medium; borda das caixas --tj-support-warning-text
Espaço legenda → opções	6 px (--tj-space-1 × 1,5), o mesmo do rótulo de BaseField
Espaço entre opções	--tj-space-2 na vertical; na horizontal --tj-space-6 entre colunas e --tj-space-3 entre linhas
Ícone → texto da mensagem	6 px (--tj-space-1 × 1,5)
Altura na horizontal	no mínimo --tj-control-md, alinhada a um campo de texto
Moldura	nenhuma: sem borda nem recuo, como no Carbon

Diferença em relação ao protótipo v3: lá o grupo era um <fieldset class="tj-field"> montado à mão em cada tela; aqui a legenda, as mensagens e o espaço vêm do componente, com os mesmos tokens do BaseRadioGroup. O par de campos do protótipo (.tj-pair) virou o BaseDateRange.

Código

<BaseFieldset label="Documentos anexados" :invalid="showError" invalid-text="Marque pelo menos um documento antes de enviar" required>
  <BaseCheckbox v-model="spreadsheet" label="Planilha orçamentária" />
  <BaseCheckbox v-model="technicalResponsibility" label="ART do responsável técnico" />
</BaseFieldset>

Propriedades

Propriedade	Tipo	Padrão	Descrição
label	string	obrigatória	Pergunta ou assunto do grupo, vira a legenda
orientation	'vertical' | 'horizontal'	'vertical'	Controles em coluna ou em linha
helperText	string	—	Ajuda abaixo dos controles
invalid	boolean	false	Erro do grupo, no lugar da ajuda; cada caixa recebe aria-invalid e a borda vermelha
invalidText	string	—	Mensagem de erro enquanto invalid. Padrão: "Revise as opções deste grupo"
warn	boolean	false	Mostra o aviso no lugar da ajuda; sem warnText não aparece
warnText	string	—	Mensagem de aviso enquanto warn
required	boolean	false	Marca a legenda como obrigatória, para "marque pelo menos um", e o leitor de tela ouve em palavras. Não ponha required nos controles (o navegador exigiria todos): a tela valida o grupo e liga invalid com invalidText
optional	boolean	false	Marca o grupo como opcional na legenda, para formulários em que quase tudo é obrigatório
disabled	boolean	false	Desabilita todos os controles do grupo
hideLabel	boolean	false	Legenda só para leitor de tela

Slot padrão: os controles do grupo. O componente não emite eventos; cada controle tem o próprio v-model.

Acessibilidade

Segue o padrão de agrupamento do WAI-ARIA (papel group) com os elementos nativos, como recomenda a técnica H71 do WCAG.

• O grupo é um <fieldset> com <legend>: o leitor de tela anuncia a legenda ao entrar no grupo, antes do primeiro controle.
• Ajuda, erro e aviso do grupo entram no aria-describedby de cada caixa e de cada interruptor, depois da ajuda própria do controle, como no BaseRadioGroup. Assim a mensagem é lida quando o controle recebe o foco, mesmo em leitores que não anunciam a descrição de um grupo (VoiceOver, TalkBack) ou quando o usuário pula direto para um controle.
• Com invalid, cada BaseCheckbox recebe aria-invalid="true" do grupo e ouve o motivo na mesma descrição. A cor nunca é o único sinal: erro e aviso têm ícone e texto.
• O HTML não tem required para um grupo ("marque pelo menos um"), então a legenda diz "(obrigatório)" em texto escondido, e o * visível fica escondido do leitor de tela.
• Teclado: cada caixa ou interruptor entra na ordem do Tab e muda com Espaço. O fieldset não recebe foco nem muda a ordem.
• disabled usa o atributo nativo do fieldset: todos os controles saem da ordem do Tab e são anunciados como indisponíveis.
• Testado com axe em todos os estados e em combinações (obrigatório com legenda escondida, desabilitado com ajuda, erro e aviso juntos), com caixas e com interruptores. O axe roda sem layout, então o contraste das cores é conferido na documentação renderizada, em tema claro e escuro.