ADR-0009: Componente Visual Modular - FeatureGrid

Este documento especifica a decisão de design sobre a implementação do componente visual FeatureGrid para o layout "Site" do gerador estático gbr_ssg.

1. Contexto e Motivação

O componente FeatureGrid renderiza uma grade de cartões com diferenciais, funcionalidades ou proposições de valor. Como o modelo de dados PageMetadata atual armazena as seções do TOML como uma lista de dicionários de texto plano (Dict(String, String)), precisamos definir uma convenção declarativa clara e previsível no TOML para codificar múltiplos itens em uma única seção sem quebrar a assinatura atual do ssg_core.

2. Decisão Arquitetural

Optamos por utilizar a **Estratégia de Chaves Indexadas Sequenciais (item_N_title e item_N_description)** dentro do dicionário da seção.

1. *Estrutura Declarativa no TOML:* No Frontmatter TOML, os cartões da grade serão declarados com o prefixo item_N_: toml [[sections]] type = "feature_grid" title = "Por que escolher a Gleam-BR?" item_1_title = "Segurança Total" item_1_description = "Garantias em tempo de compilação sem exceções em runtime." item_2_title = "Poder da BEAM" item_2_description = "Concorrência com tolerância a falhas e alta escalabilidade." item_3_title = "Simplicidade Elegante" item_3_description = "Sintaxe limpa, previsível e sem surpresas."

2. **Parsing Recursivo (parse):** A função parse(section: Dict(String, String)) -> Result(FeatureGridProps, String) irá: - Extrair o campo opcional title da seção (Option(String)). - Executar uma iteração recursiva buscando as chaves item_1_title e item_1_description, incrementando o índice ($i = 1, 2, 3, \dots$) até encontrar o primeiro índice ausente. - Retornar a estrutura fortemente tipada FeatureGridProps(title: Option(String), items: List(FeatureItem)). - Se nenhum item item_1_... for encontrado, retorna um Error indicando que a grade necessita de pelo menos 1 item válido.

3. *Vantagens da Abordagem:* - *Zero Mudanças na Infraestrutura Core:* Preserva a assinatura Dict(String, String) em ssg_core, sem necessidade de refatorar o decodificador TOML genérico. - *Simplicidade Declarativa:* Fácil para redatores e editores entenderem e ampliarem o número de diferenciais no TOML.

3. Requisitos EARS

*Requisitos Ubíquos (Ubiquitous Requirements)* - *UBQ-01 (Extração de Grade Indexada):* O parser do FeatureGrid DEVE iterar pelas chaves indexadas sequencialmente (item_1_..., item_2_...) e construir a lista tipada List(FeatureItem). - *UBQ-02 (Responsividade da Grade):* O contêiner da grade DEVE aplicar regras CSS de Tailwind para adaptar o layout visual: 1 coluna em telas móbiles (grid-cols-1) e 3 colunas em telas médias e superiores (md:grid-cols-3). - *UBQ-03 (Título Opcional da Seção):* Se a chave title estiver ausente no dicionário da seção (resolvida para None), a renderização do título principal <h2 class="..."> DEVE ser omitida silenciosamente sem afetar a exibição da grade de cartões (fail-soft).