Introdução

Um contêiner de layout estrutural que agrupa controles de formulário relacionados sob um <fieldset> nativo, completo com uma legenda acessível, texto de ajuda de suporte e mensagens de erro de validação. Ele serve como uma âncora semântica essencial para formulários complexos de entrada de usuário, propagando automaticamente os estados desabilitado, inválido e obrigatório para os controles de campo aninhados.

O componente Fieldset está totalmente integrado como um bloco fieldset no Page Builder, permitindo que autores de conteúdo e desenvolvedores estruturem facilmente seções de perfil de múltiplas entradas, formulários de endereço ou módulos de faturamento diretamente no CMS.

Uso via CMS Page Builder (JSON)

Estes exemplos ilustram como os editores de conteúdo vinculam e estruturam grupos de fieldset dentro dos esquemas de página JSON (content/pages/*.json).

1. Grupo de Informações de Conta Padrão

Um grupo de perfil de usuário padrão com campos de nome aninhados obrigatórios. Possui uma legenda ativa e texto de status de ajuda.

{
  "type": "fieldset",
  "legend": "Account Information",
  "helperText": "Configure your primary account details.",
  "required": true,
  "children": [
    {
      "type": "field",
      "label": "Full Name",
      "placeholder": "Jane Doe",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Email Address",
      "placeholder": "jane@example.com",
      "interactive": true
    }
  ]
}

2. Grupo Inválido com Mensagem de Erro

Mostra como o Fieldset exibe mensagens de erro de validação quando um requisito de agrupamento é violado. Inserir um errorText aciona automaticamente estados inválidos em todos os campos filhos.

{
  "type": "fieldset",
  "legend": "Billing Credentials",
  "helperText": "Enter your card billing details.",
  "errorText": "A valid postal code is required.",
  "children": [
    {
      "type": "field",
      "label": "Cardholder Name",
      "placeholder": "Jane Doe",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Postal Code",
      "placeholder": "90210",
      "invalid": true,
      "interactive": true
    }
  ]
}

3. Bloco de Opções de Faturamento Desabilitado

Demonstra uma seção de parâmetros de envio totalmente desabilitada. Desativar o Fieldset pai bloqueia automaticamente cada elemento aninhado.

{
  "type": "fieldset",
  "legend": "Shipping Address",
  "helperText": "Unavailable during local holidays.",
  "disabled": true,
  "children": [
    {
      "type": "field",
      "label": "Street",
      "placeholder": "123 Main St",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Apt #",
      "placeholder": "4B",
      "interactive": true
    }
  ]
}

Referência de Configuração CMS

Esses campos mapeiam diretamente para as propriedades de bloco do Sveltia CMS em public/admin/config.yml ou as configurações do Page Builder:

Notas do Desenvolvedor e Acessibilidade

• Sem Hidratação (Somente Estático): Fieldset é um componente de layout semântico designado como componente Somente Estático (Tier 3). Ele é renderizado inteiramente como HTML padrão do lado do servidor e está isento de scripts de hidratação do lado do cliente.
• Propagação de Contexto: Ele utiliza provedores de contexto para propagar os estados disabled, invalid e required para baixo. Blocos de componentes filhos diretos (como Field e Textarea) ouvem automaticamente esse contexto e herdam as propriedades do grupo, eliminando declarações de chave duplicadas.
• Conformidade WAI-ARIA: Fieldset compila estritamente para contêineres HTML semânticos <fieldset> contendo elementos <legend> diretos, satisfazendo os requisitos de título acessíveis do navegador.