req-039: Aprimoramentos Visuais e Funcionais no Editor HTML Visual

Este documento detalha novas melhorias visuais, de usabilidade e funcionais no Editor HTML Visual (html-editor.js, html-editor-visual-controls.js e html-editor.php).

Este documento detalha novas melhorias visuais, de usabilidade e funcionais no Editor HTML Visual (html-editor.js, html-editor-visual-controls.js e html-editor.php).

1. Requisitos do Lote

1.1 Nova Seção "Fundo" (Background) no Styler

Criação da Seção: Adicionar uma nova seção accordion sob o nome "Fundo" no painel visual do styler (.he-styler-col-visual). Esta seção deve ser posicionada imediatamente após a seção "Aparência" (ou a seção "Aparência" deve ser reorganizada de forma que a cor de fundo seja migrada para "Fundo").
Migração de Controles: A cor de fundo (bgColor), que antes residia na seção "Aparência", deve ser migrada em 100% para esta nova seção "Fundo".
Botão de Imagem de Fundo: Adicionar controles específicos para configurar a imagem de fundo:
- Botão de seleção de imagem que aciona o ImagePicker utilizando a configuração padrão exposta por html_editor.imagepick.
- Exibição de preview com miniatura da imagem selecionada e botão para limpar/remover a imagem de fundo.
- Ao selecionar a imagem, aplicar o estilo inline background-image: url('<url>') no elemento selecionado.
Propriedades da Imagem de Fundo (Tailwind):
- Repetição: Grupos de botões para bg-repeat, bg-no-repeat, bg-repeat-x e bg-repeat-y (mutuamente exclusivos).
- Tamanho: Grupos de botões para bg-auto, bg-cover e bg-contain (mutuamente exclusivos).
- Posição: Grupos de botões para alinhamento rápido como bg-center, bg-top, bg-bottom, bg-left, bg-right (mutuamente exclusivos).

1.2 Botão Deselecionar e Toggle de Seleção

Botão na Toolbar: Inserir um novo botão na barra de ferramentas flutuante (#html-editor-floating-toolbar) com classe .he-tb-deselect (ou similar) e ícone apropriado (ex: times circle ou ban). Este botão deve possuir destaque visual diferente dos demais (ex: cor ou borda distinta) e, ao ser clicado, deselecionar o elemento ativo, limpando todos os overlays e estilizações.
Clique Alternador (Toggle): Modificar a escuta global de clique de seleção. Caso o elemento clicado seja exatamente o elemento que já está selecionado (el === this.selectedElement), o editor deve deselecioná-lo (chamando clearSelection()), funcionando como um alternador de estado de seleção.
Teclado: O comportamento de deseleção por tecla Esc deve ser integralmente preservado.

1.3 Preservação de Scroll no Histórico (Undo/Redo)

Captura do Viewport: A pilha de estados de histórico (undoStack e redoStack) deve ser estendida para além do código HTML. Cada snapshot do histórico deve salvar a posição do scroll vertical do iframe (scrollTop do preview iframe).
Restauração de Posicionamento: Ao executar Undo (Ctrl+Z) ou Redo (Ctrl+Y), após a atualização física do DOM, restaurar a posição exata de rolagem vertical salva no snapshot correspondente (window.scrollTo). Isso garante que o elemento modificado permaneça visível no viewport e evita saltos visuais desorientadores.

1.4 Quebra de Linha nos Breadcrumbs (Ancestrais e Filhos)

Estilo de Layout: Atualizar as propriedades CSS dos contêineres de breadcrumbs (#html-editor-selection-breadcrumb e #html-editor-selection-children) para permitir quebra de linha (flex-wrap: wrap, display: flex e remoção de restrições de white-space: nowrap/text-overflow: ellipsis).
Prevenção de Transbordo: No cálculo de coordenadas em updateSelectionUI(), se a coordenada left somada à largura física dos breadcrumbs exceder os limites da tela do iframe (window.innerWidth), ajustar dinamicamente a posição left para alinhar os breadcrumbs dentro dos limites visuais visíveis (clamp horizontal).

1.5 Elemento Fantasma (Ghost Element) no Modo de Inserção

Elemento Seguidor de Cursor: Quando o operador entrar no modo de inserção (após clicar no "+" e escolher um elemento ou widget no menu do pai), o editor visual no iframe deve criar um elemento fantasma (insertGhost) flutuante que segue o cursor do mouse (com offset de renderização de e.g. 15px).
Aparência: O elemento fantasma deve possuir opacidade reduzida (ex: 0.6), borda tracejada roxa ou cinza, estilo inline de pointer-events: none e position: absolute com alto z-index, representando visualmente o esqueleto do elemento a ser injetado. Ele deve ser removido ao efetuar o drop ou cancelar o modo de inserção.

1.6 Destaque de Contêiner Alvo nos Dropzones (Dashed Outline)

Outlining de Parent: Ao arrastar elementos ou mover-se no modo de inserção, se o cursor estiver sobre uma área de contêiner e o sistema não identificar uma posição exata de inserção horizontal (como antes ou depois de um irmão específico), o editor deve marcar o contêiner de destino inteiro com uma borda amarela tracejada de 4 lados (#html-editor-parent-highlight-overlay ou similar).
Indicação de Append: O destaque visual de contêiner de 4 lados substitui o placeholder em linha simples, indicando claramente que o novo elemento será inserido diretamente "dentro" do contêiner selecionado (como último filho).

1.7 Renderização de Esqueleto HTML em Widgets Inseridos

Visualização de Estrutura: Ao inserir um widget (menus, galleries, highlights, index), o contêiner virtual do wrapper .conn2flow-widget-inner deve deixar de ser vazio e passar a renderizar o esqueleto ou conteúdo do widget.
AJAX de Renderização: Criar um endpoint AJAX no core (html-editor.php -> html-editor-widget-render) que recebe a assinatura completa do widget (ex: menus->render({"grupo_slug": "teste"})), carrega a biblioteca de widgets do PHP (widgets.php) e chama o método widgets_get() para renderizar o esqueleto dinâmico e devolver o HTML correspondente.
Sincronização: O JS do iframe do visual editor deve realizar a chamada a este endpoint ao inserir ou atualizar um widget para popular o .conn2flow-widget-inner e renderizar o widget visualmente no preview.

# req-039: Aprimoramentos Visuais e Funcionais no Editor HTML Visual
Este documento detalha novas melhorias visuais, de usabilidade e funcionais no Editor HTML Visual (`html-editor.js`, `html-editor-visual-controls.js` e `html-editor.php`).
---
## 1. Requisitos do Lote
### 1.1 Nova Seção "Fundo" (Background) no Styler
- **Criação da Seção**: Adicionar uma nova seção accordion sob o nome "Fundo" no painel visual do styler (`.he-styler-col-visual`). Esta seção deve ser posicionada imediatamente após a seção "Aparência" (ou a seção "Aparência" deve ser reorganizada de forma que a cor de fundo seja migrada para "Fundo").
- **Migração de Controles**: A cor de fundo (`bgColor`), que antes residia na seção "Aparência", deve ser migrada em 100% para esta nova seção "Fundo".
- **Botão de Imagem de Fundo**: Adicionar controles específicos para configurar a imagem de fundo:
  - Botão de seleção de imagem que aciona o ImagePicker utilizando a configuração padrão exposta por `html_editor.imagepick`.
  - Exibição de preview com miniatura da imagem selecionada e botão para limpar/remover a imagem de fundo.
  - Ao selecionar a imagem, aplicar o estilo inline `background-image: url('<url>')` no elemento selecionado.
- **Propriedades da Imagem de Fundo (Tailwind)**:
  - **Repetição**: Grupos de botões para `bg-repeat`, `bg-no-repeat`, `bg-repeat-x` e `bg-repeat-y` (mutuamente exclusivos).
  - **Tamanho**: Grupos de botões para `bg-auto`, `bg-cover` e `bg-contain` (mutuamente exclusivos).
  - **Posição**: Grupos de botões para alinhamento rápido como `bg-center`, `bg-top`, `bg-bottom`, `bg-left`, `bg-right` (mutuamente exclusivos).
### 1.2 Botão Deselecionar e Toggle de Seleção
- **Botão na Toolbar**: Inserir um novo botão na barra de ferramentas flutuante (`#html-editor-floating-toolbar`) com classe `.he-tb-deselect` (ou similar) e ícone apropriado (ex: `times circle` ou `ban`). Este botão deve possuir destaque visual diferente dos demais (ex: cor ou borda distinta) e, ao ser clicado, deselecionar o elemento ativo, limpando todos os overlays e estilizações.
- **Clique Alternador (Toggle)**: Modificar a escuta global de clique de seleção. Caso o elemento clicado seja exatamente o elemento que já está selecionado (`el === this.selectedElement`), o editor deve deselecioná-lo (chamando `clearSelection()`), funcionando como um alternador de estado de seleção.
- **Teclado**: O comportamento de deseleção por tecla `Esc` deve ser integralmente preservado.
### 1.3 Preservação de Scroll no Histórico (Undo/Redo)
- **Captura do Viewport**: A pilha de estados de histórico (`undoStack` e `redoStack`) deve ser estendida para além do código HTML. Cada snapshot do histórico deve salvar a posição do scroll vertical do iframe (`scrollTop` do preview iframe).
- **Restauração de Posicionamento**: Ao executar `Undo` (Ctrl+Z) ou `Redo` (Ctrl+Y), após a atualização física do DOM, restaurar a posição exata de rolagem vertical salva no snapshot correspondente (`window.scrollTo`). Isso garante que o elemento modificado permaneça visível no viewport e evita saltos visuais desorientadores.
### 1.4 Quebra de Linha nos Breadcrumbs (Ancestrais e Filhos)
- **Estilo de Layout**: Atualizar as propriedades CSS dos contêineres de breadcrumbs (`#html-editor-selection-breadcrumb` e `#html-editor-selection-children`) para permitir quebra de linha (`flex-wrap: wrap`, `display: flex` e remoção de restrições de `white-space: nowrap`/`text-overflow: ellipsis`).
- **Prevenção de Transbordo**: No cálculo de coordenadas em `updateSelectionUI()`, se a coordenada `left` somada à largura física dos breadcrumbs exceder os limites da tela do iframe (`window.innerWidth`), ajustar dinamicamente a posição `left` para alinhar os breadcrumbs dentro dos limites visuais visíveis (clamp horizontal).
### 1.5 Elemento Fantasma (Ghost Element) no Modo de Inserção
- **Elemento Seguidor de Cursor**: Quando o operador entrar no modo de inserção (após clicar no "+" e escolher um elemento ou widget no menu do pai), o editor visual no iframe deve criar um elemento fantasma (`insertGhost`) flutuante que segue o cursor do mouse (com offset de renderização de e.g. 15px).
- **Aparência**: O elemento fantasma deve possuir opacidade reduzida (ex: `0.6`), borda tracejada roxa ou cinza, estilo inline de `pointer-events: none` e `position: absolute` com alto `z-index`, representando visualmente o esqueleto do elemento a ser injetado. Ele deve ser removido ao efetuar o drop ou cancelar o modo de inserção.
### 1.6 Destaque de Contêiner Alvo nos Dropzones (Dashed Outline)
- **Outlining de Parent**: Ao arrastar elementos ou mover-se no modo de inserção, se o cursor estiver sobre uma área de contêiner e o sistema não identificar uma posição exata de inserção horizontal (como antes ou depois de um irmão específico), o editor deve marcar o contêiner de destino inteiro com uma borda amarela tracejada de 4 lados (`#html-editor-parent-highlight-overlay` ou similar).
- **Indicação de Append**: O destaque visual de contêiner de 4 lados substitui o placeholder em linha simples, indicando claramente que o novo elemento será inserido diretamente "dentro" do contêiner selecionado (como último filho).
### 1.7 Renderização de Esqueleto HTML em Widgets Inseridos
- **Visualização de Estrutura**: Ao inserir um widget (menus, galleries, highlights, index), o contêiner virtual do wrapper `.conn2flow-widget-inner` deve deixar de ser vazio e passar a renderizar o esqueleto ou conteúdo do widget.
- **AJAX de Renderização**: Criar um endpoint AJAX no core (`html-editor.php` -> `html-editor-widget-render`) que recebe a assinatura completa do widget (ex: `menus->render({"grupo_slug": "teste"})`), carrega a biblioteca de widgets do PHP (`widgets.php`) e chama o método `widgets_get()` para renderizar o esqueleto dinâmico e devolver o HTML correspondente.
- **Sincronização**: O JS do iframe do visual editor deve realizar a chamada a este endpoint ao inserir ou atualizar um widget para popular o `.conn2flow-widget-inner` e renderizar o widget visualmente no preview.