Human Request: Resolução de Framework CSS e Variáveis de Destaques de Modelo Modificado (req-027)

Esta especificação define o lote corretivo de trabalho req-027 (BATCH-027) para o Engenheiro Executor. O escopo abrange a resolução de dois problemas de runtime identificados após a entrega do BATCH-026:

1. Bug 1: Inicialização do Framework CSS (framework_css indefinido): Ao carregar um registro com template modificado (sufixado por -modificado), o AJAX de carga do template (loadTemplate) é bloqueado de forma intencional para preservar o código do banco. Porém, isso faz com que a variável global de estilo gestor.html_editor.framework_css não seja inicializada síncronamente, quebrando o visualizador dinâmico de widget (live widget-preview).

2. Bug 2: Mapeamento de Variáveis Vazio em Destaques (Highlights): No módulo de Destaques (publisher-highlights), a carga das variáveis e a montagem das colunas de associação de campos dependem da resposta do AJAX do template. Sem disparar a carga do template na inicialização de registros -modificado, as colunas de mapeamento de campos e variáveis de itens ficam em branco.

1. Detalhamento e Soluções Propostas

1.1 Resolução do Framework CSS via Atributo de Dados (data-framework)

• Problema: A função window.previewExternalHtmlConteudo() usa a variável gestor.html_editor.framework_css para injetar as CDNs de frameworks CSS (Tailwind v3, Tailwind v4, etc.) no iframe. Quando o AJAX template-load não é chamado, esta variável fica undefined.

• Solução:

  1. No backend PHP dos três módulos (menus.php, galleries.php, publisher-highlights.php), nas funções de geração das opções do select de modelos (menus_template_options, galleries_template_options e publisher_highlights_template_options), a consulta de banco que lê os templates deve carregar a coluna framework_css.

  2. No loop de montagem do select, injetar a propriedade como atributo customizado no elemento <option> (ex: <option value="menus-horizontal-navbar" data-framework="tailwindcss" ...>).

  3. A opção gerada dinamicamente com o sufixo -modificado deve herdar o mesmo atributo data-framework do seu template base.

  4. No frontend JavaScript (menus.js, galleries.js, publisher-highlights.js), no evento ready (inicialização) e no listener de change do dropdown #template_id, extrair o valor do atributo de dados do elemento <option> atualmente selecionado e atribuí-lo diretamente a gestor.html_editor.framework_css.

     • Exemplo de leitura em JS: var framework = $('#template_id option:selected').data('framework') || '';

1.2 Extração Client-side de Variáveis de Destaques (publisher-highlights.js)

• Problema: A aba lateral de variáveis necessita que a variável global availableItemVars (array contendo os nomes dos placeholders [[item#X]] presentes no HTML) esteja populada para construir os botões de ligação e mapeamento.

• Solução:

  1. No JavaScript publisher-highlights.js, no carregamento de um template -modificado, aplicar uma expressão regular sobre o HTML customizado carregado do banco de dados (que reside em initialHtml e no editor CodeMirror) para extrair todos os placeholders que casem com o padrão /\[\[item#([a-zA-Z0-9_\-]+)\]\]/g.

  2. O array de correspondências únicas deve ser atribuído à variável global availableItemVars.

  3. Chamar as funções de sincronização visual renderItemVars() e syncEditorVariables() imediatamente no carregamento inicial para povoar a aba lateral de variáveis de forma instantânea.

  4. Ao trocar de template e voltar para a versão -modificado, repetir este fluxo de extração local a partir de initialHtml para manter a consistência.

2. Especificações de Alteração de Código

2.1 Módulo de Menus

[MODIFY] menus.php

1. Função menus_template_options:

   • Garantir que a query do banco de dados de templates inclua a coluna framework_css.

   • No loop foreach($templates as $template):

     • Obter o framework: $framework = $template['framework_css'] ?? '';.

     • Injetar o atributo data-framework nas tags <option> geradas: $template_id_options .= '<option value="'.$template['id'].'" data-framework="'.$framework.'"'.$selected_original.'>'.$template['nome'].'</option>';

     • Injetar também na tag do -modificado: $template_id_options .= '<option value="'.$template['id'].'-modificado" data-framework="'.$framework.'" selected>'.$template['nome'].' - (Modificado)</option>';

[MODIFY] menus.js

1. Inicialização do Ready:

   • Após definir o valor do dropdown no page load e antes de checar se termina com -modificado, ler e definir o framework CSS de forma síncrona:

     var initialFramework = $('#template_id option:selected').data('framework') || '';
     if (typeof gestor !== 'undefined' && gestor.html_editor) {
         gestor.html_editor.framework_css = initialFramework;
     }

2. Listener do Dropdown de Template:

   • No listener $template.on('change', function () { ... }), logo no início, re-detectar e atualizar o framework CSS:

     var currentFramework = $('#template_id option:selected').data('framework') || '';
     if (typeof gestor !== 'undefined' && gestor.html_editor) {
         gestor.html_editor.framework_css = currentFramework;
     }

2.2 Módulo de Galerias

[MODIFY] galleries.php

1. Função galleries_template_options:

   • Incluir framework_css na query de templates de galerias.

   • Injetar o atributo data-framework na tag original e na tag -modificado de forma idêntica à especificação do Menus.

[MODIFY] galleries.js

1. Inicialização do Ready:

   • Identificar o data-framework da opção selecionada no carregamento inicial e atribuir a gestor.html_editor.framework_css.

2. Listener do Dropdown de Template:

   • Identificar o data-framework do template selecionado no evento change e atualizar gestor.html_editor.framework_css.

2.3 Módulo de Destaques (Publisher Highlights)

[MODIFY] publisher-highlights.php

1. Função publisher_highlights_template_options:

   • Incluir framework_css na query de templates de destaques.

   • Injetar o atributo data-framework na tag original e na tag -modificado de forma idêntica à especificação dos módulos anteriores.

[MODIFY] publisher-highlights.js

1. Inicialização do Ready:

   • Identificar o data-framework do template selecionado no page load e definir gestor.html_editor.framework_css.

2. Listener do Dropdown de Template:

   • Identificar o data-framework do template selecionado no evento change e atualizar gestor.html_editor.framework_css.

3. Lógica de Extração Client-side de Variáveis:

   • Criar uma função auxiliar para extrair variáveis do HTML e sincronizar a aba do editor:

     function extractVariablesFromHtml(htmlContent) {
         var vars = [];
         var regex = /\[\[item#([a-zA-Z0-9_\-]+)\]\]/g;
         var match;
         while ((match = regex.exec(htmlContent)) !== null) {
             var varName = match[1];
             if (vars.indexOf(varName) === -1) {
                 vars.push(varName);
             }
         }
         availableItemVars = vars;
         renderItemVars();
         syncEditorVariables();
     }

   • No carregamento da página (evento ready), caso o template inicial termine em -modificado:

     if (startTid.endsWith('-modificado')) {
         extractVariablesFromHtml(initialHtml);
         setTimeout(function () { scheduleWidgetPreview(true); }, 600);
     }

   • No listener do select $template.on('change'), caso o usuário re-selecione a opção -modificado:

     if (tid.endsWith('-modificado')) {
         if (typeof window.html_editor_set_html === 'function') window.html_editor_set_html(initialHtml);
         if (typeof window.html_editor_set_css === 'function') window.html_editor_set_css(initialCss);
         extractVariablesFromHtml(initialHtml);
         setTimeout(function () { scheduleWidgetPreview(true, true); }, 150);
     }

3. Plano de Verificação

3.1 Testes Automatizados (Estáticos)

• Verificar sintaxe dos arquivos alterados:

  • node --check gestor/modulos/menus/menus.js

  • node --check gestor/modulos/galleries/galleries.js

  • node --check gestor/modulos/publisher-highlights/publisher-highlights.js

  • php -l gestor/modulos/menus/menus.php

  • php -l gestor/modulos/galleries/galleries.php

  • php -l gestor/modulos/publisher-highlights/publisher-highlights.php

3.2 Verificação Manual

1. Validação de visualização de modelo modificado:

   • Abrir a tela de edição de um registro com modelo modificado nos módulos de Menus, Galerias e Destaques.

   • Verificar se o pré-visualizador de widget carrega e exibe o template corretamente com a estilização correta do framework (Tailwind ou outro cadastrado).

2. Validação de mapeamento de variáveis de destaques:

   • Abrir a tela de edição de Destaques com modelo modificado.

   • Verificar na aba lateral "Variáveis" que os botões de variáveis correspondentes aos placeholders [[item#X]] do HTML salvo no banco são populados instantaneamente.

3. Validação de alternância:

   • Trocar para o modelo padrão e confirmar que as variáveis recarregam a partir do template padrão.

   • Mudar de volta para -modificado e confirmar que as variáveis do HTML inicial reaparecem na aba.