req-139: Refinamento de Densidade e Proporção no Galleries, Overlay de Configuração Rápida, Highlight de Cards e Controle de Alinhamento Vertical de Imagens

Aspect Ratio Excessivamente Wide nos Modos Compactos: Em monitores widescreen (1200px a 1920px+), 4 itens por linha no modo Médio deixavam os cards muito largos e "esticados", com…

Descrição do Problema / Contexto

Após os testes de homologação do BATCH-140 e BATCH-141, foram identificadas oportunidades de melhoria ergonômica e estética no gerenciamento de fotos do módulo galleries, além de uma nova funcionalidade de diagramação:

Aspect Ratio Excessivamente Wide nos Modos Compactos: Em monitores widescreen (1200px a 1920px+), 4 itens por linha no modo Médio deixavam os cards muito largos e "esticados", com altura desproporcional. É necessário aumentar a densidade (6 por linha no Médio e 10 por linha no Pequeno) e elevar a altura das miniaturas em aproximadamente 30% para restaurar um aspect ratio equilibrado.
Edição de Legenda e Link Inacessível nos Modos Compactos: Nos modos Médio e Pequeno, os campos de legenda e link ficavam ocultos para economizar espaço. Falta um ponto de entrada (botão de engrenagem no overlay do hover) para permitir que o usuário edite a legenda e configure o link daquela imagem diretamente, sem ter que voltar obrigatoriamente para o modo Grande.
Falta de Feedback Visual Claro (Highlight) no Hover: Para usuários menos experientes, ao passar o mouse sobre as miniaturas, o card não possuía um realce evidente de foco além do aparecimento dos controles, dificultando a identificação imediata do elemento ativo antes do clique ou arraste.
Alinhamento Visual do Overlay com o Padrão do admin-arquivos: O overlay do admin-arquivos utiliza uma sombra/backdrop suave com contraste aprimorado que agradou esteticamente. O módulo galleries deve adotar exatamente o mesmo tratamento visual e de transição suave.
Novo Controle de Alinhamento Vertical das Imagens (Crop / Object-Position): As galerias utilizam object-cover nas fotos. Muitas imagens com proporções diferentes têm seus rostos ou elementos centrais cortados no topo ou na base. É necessário adicionar um controle de exibição para definir o alinhamento vertical da imagem (Centro/Meio, Topo/Acima, Fundo/Abaixo) no CRUD e refletir essa propriedade em todos os 4 templates de modelo de galeria e no widget público.

Escopo Detalhado das Alterações

1. Densidade e Proporção das Miniaturas no `galleries`

Arquivo CSS / Injeção (gestor/modulos/galleries/galleries.js):
- Modo Médio (.view-medium):
- Largura dos cards: width: calc(16.666% - 8px); (6 itens por linha no desktop).
- Altura da miniatura .gallery-item-thumb: aumentar em ~30% (de ~85px para ~110px).
- Altura do card e aspect ratio ajustados proporcionalmente.
- Modo Pequeno (.view-small):
- Largura dos cards: width: calc(10% - 6px); (10 itens por linha no desktop).
- Altura da miniatura .gallery-item-thumb: aumentar em ~30% (de ~50px para ~65px).
- Manter regras de responsividade com flex-wrap: wrap e redução elegante em telas menores (ex: tablets).

2. Overlay de Configuração Rápida (Engrenagem) e Edição nos Modos Compactos

Overlay nos Modos Médio e Pequeno:
- Adicionar ao overlay de ações de cada card um botão com ícone de engrenagem (.gallery-item-settings / <i class="cog icon"></i>).
Modal / Painel de Edição Rápida:
- Ao clicar na engrenagem:
- Abrir um modal simples ou popup com os campos: Legenda da Imagem (caption) e Configuração de Link (tipo de link, destino/página, target).
- Ao confirmar ou alterar, atualizar o objeto correspondente no array items em memória.
- Disparar scheduleWidgetPreview() para sincronizar imediatamente o preview da galeria.
- Adicionar variáveis i18n para tooltips e títulos do modal em pt-br e en.

3. Highlight Nítido e Consistência Visual do Overlay

Highlight no Hover (.gallery-item:hover):
- Aplicar borda destacada e sombra azulada suave: border-color: #2185d0; box-shadow: 0 4px 14px rgba(33, 133, 208, 0.22);.
Estilo do Overlay (Idêntico ao admin-arquivos):
- background: rgba(0, 0, 0, 0.55); border-radius: 4px;
- Botões de ação em formato de pílula/circular com contraste nítido, ícones brancos e hover luminoso.
- opacity: 0 por padrão com pointer-events: none, passando para opacity: 1 e pointer-events: auto no :hover.
- Manter dimensões dos cards 100% estáticas (zero layout shift).

4. Controle de Alinhamento Vertical das Imagens (Top / Center / Bottom)

CRUD de Galerias (resources/{pt-br,en}/pages/galleries-{adicionar,editar,clonar}/):
- Na seção "Controles de Exibição", adicionar o campo dropdown Alinhamento Vertical da Imagem (#gallery-image-position):
- center: "Centro (Padrão)" / "Center (Default)"
- top: "Topo / Acima" / "Top"
- bottom: "Fundo / Abaixo" / "Bottom"
JavaScript do CRUD (gestor/modulos/galleries/galleries.js):
- Na serialização de getSchemaFromForm(): capturar out.image_position = $('#gallery-image-position').val() || 'center';.
- Na hidratação hydrateGalleryControls(): popular $('#gallery-image-position').val(schema.image_position || 'center');.
- No listener de change: acionar serializeAndPreview().
Backend do Widget (gestor/modulos/galleries/galleries.widget.php):
- Em galleries_widget_resolver_globais(): mapear a variável image_position:
- Valor puro: $schema['image_position'] ?? 'center'.
- Classe utilitária Tailwind correspondente: object-center, object-top, object-bottom.
Templates de Modelo de Galeria (resources/{pt-br,en}/templates/):
- Atualizar os 4 templates (galleries-carousel, galleries-grid, galleries-masonry, galleries-slider):
- Injetar o alinhamento nas tags <img> via style="... object-position: @[[image_position]]@;" ou classes Tailwind correspondentes.
Widget JS (gestor/modulos/galleries/galleries.widget.js):
- Garantir que o preview no editor HTML e o runtime público renderizem a posição correta.

Critérios de Aceite e Validação

Lint e Validação Estática:
- php -l em todos os arquivos PHP do módulo galleries.
- node --check em galleries.js e galleries.widget.js.
- Validação de JSON em galleries.json.
Suíte de Testes Automatizados:
- Adicionar testes unitários/integração para o novo campo image_position no galleries.widget.php e nos seletores de visualização.
- composer test e npx vitest run 100% verdes, sem regressões.
Validação Visual e Manual (Playwright & Navegador):
- Abrir galeria com 15+ fotos:
  - Confirmar 6 colunas no modo Médio e 10 colunas no modo Pequeno, com fotos proporcionalmente mais altas.
  - Passar o mouse e validar o highlight do card e o overlay com engrenagem.
  - Clicar na engrenagem no modo Pequeno/Médio e editar a legenda/link de uma foto; conferir se a alteração persiste e reflete no preview.
  - Alterar o Alinhamento Vertical para "Topo" e "Fundo" e verificar se as imagens do carrossel/grid alteram o corte vertical no preview e na página pública.

# req-139: Refinamento de Densidade e Proporção no Galleries, Overlay de Configuração Rápida, Highlight de Cards e Controle de Alinhamento Vertical de Imagens
## Descrição do Problema / Contexto
Após os testes de homologação do `BATCH-140` e `BATCH-141`, foram identificadas oportunidades de melhoria ergonômica e estética no gerenciamento de fotos do módulo `galleries`, além de uma nova funcionalidade de diagramação:
1. **Aspect Ratio Excessivamente Wide nos Modos Compactos**:
   Em monitores widescreen (1200px a 1920px+), 4 itens por linha no modo Médio deixavam os cards muito largos e "esticados", com altura desproporcional. É necessário aumentar a densidade (6 por linha no Médio e 10 por linha no Pequeno) e elevar a altura das miniaturas em aproximadamente 30% para restaurar um aspect ratio equilibrado.
2. **Edição de Legenda e Link Inacessível nos Modos Compactos**:
   Nos modos Médio e Pequeno, os campos de legenda e link ficavam ocultos para economizar espaço. Falta um ponto de entrada (botão de engrenagem no overlay do hover) para permitir que o usuário edite a legenda e configure o link daquela imagem diretamente, sem ter que voltar obrigatoriamente para o modo Grande.
3. **Falta de Feedback Visual Claro (Highlight) no Hover**:
   Para usuários menos experientes, ao passar o mouse sobre as miniaturas, o card não possuía um realce evidente de foco além do aparecimento dos controles, dificultando a identificação imediata do elemento ativo antes do clique ou arraste.
4. **Alinhamento Visual do Overlay com o Padrão do `admin-arquivos`**:
   O overlay do `admin-arquivos` utiliza uma sombra/backdrop suave com contraste aprimorado que agradou esteticamente. O módulo `galleries` deve adotar exatamente o mesmo tratamento visual e de transição suave.
5. **Novo Controle de Alinhamento Vertical das Imagens (Crop / Object-Position)**:
   As galerias utilizam `object-cover` nas fotos. Muitas imagens com proporções diferentes têm seus rostos ou elementos centrais cortados no topo ou na base. É necessário adicionar um controle de exibição para definir o alinhamento vertical da imagem (`Centro/Meio`, `Topo/Acima`, `Fundo/Abaixo`) no CRUD e refletir essa propriedade em todos os 4 templates de modelo de galeria e no widget público.
---
## Escopo Detalhado das Alterações
### 1. Densidade e Proporção das Miniaturas no `galleries`
* **Arquivo CSS / Injeção (`gestor/modulos/galleries/galleries.js`)**:
  * **Modo Médio (`.view-medium`)**:
    * Largura dos cards: `width: calc(16.666% - 8px);` (6 itens por linha no desktop).
    * Altura da miniatura `.gallery-item-thumb`: aumentar em ~30% (de ~85px para ~110px).
    * Altura do card e aspect ratio ajustados proporcionalmente.
  * **Modo Pequeno (`.view-small`)**:
    * Largura dos cards: `width: calc(10% - 6px);` (10 itens por linha no desktop).
    * Altura da miniatura `.gallery-item-thumb`: aumentar em ~30% (de ~50px para ~65px).
  * Manter regras de responsividade com `flex-wrap: wrap` e redução elegante em telas menores (ex: tablets).
---
### 2. Overlay de Configuração Rápida (Engrenagem) e Edição nos Modos Compactos
* **Overlay nos Modos Médio e Pequeno**:
  * Adicionar ao overlay de ações de cada card um botão com ícone de engrenagem (`.gallery-item-settings` / `<i class="cog icon"></i>`).
* **Modal / Painel de Edição Rápida**:
  * Ao clicar na engrenagem:
    * Abrir um modal simples ou popup com os campos: **Legenda da Imagem** (`caption`) e **Configuração de Link** (tipo de link, destino/página, target).
    * Ao confirmar ou alterar, atualizar o objeto correspondente no array `items` em memória.
    * Disparar `scheduleWidgetPreview()` para sincronizar imediatamente o preview da galeria.
  * Adicionar variáveis i18n para tooltips e títulos do modal em `pt-br` e `en`.
---
### 3. Highlight Nítido e Consistência Visual do Overlay
* **Highlight no Hover (`.gallery-item:hover`)**:
  * Aplicar borda destacada e sombra azulada suave: `border-color: #2185d0; box-shadow: 0 4px 14px rgba(33, 133, 208, 0.22);`.
* **Estilo do Overlay (Idêntico ao `admin-arquivos`)**:
  * `background: rgba(0, 0, 0, 0.55); border-radius: 4px;`
  * Botões de ação em formato de pílula/circular com contraste nítido, ícones brancos e hover luminoso.
  * `opacity: 0` por padrão com `pointer-events: none`, passando para `opacity: 1` e `pointer-events: auto` no `:hover`.
  * Manter dimensões dos cards 100% estáticas (zero layout shift).
---
### 4. Controle de Alinhamento Vertical das Imagens (Top / Center / Bottom)
* **CRUD de Galerias (`resources/{pt-br,en}/pages/galleries-{adicionar,editar,clonar}/`)**:
  * Na seção "Controles de Exibição", adicionar o campo dropdown **Alinhamento Vertical da Imagem** (`#gallery-image-position`):
    * `center`: "Centro (Padrão)" / "Center (Default)"
    * `top`: "Topo / Acima" / "Top"
    * `bottom`: "Fundo / Abaixo" / "Bottom"
* **JavaScript do CRUD (`gestor/modulos/galleries/galleries.js`)**:
  * Na serialização de `getSchemaFromForm()`: capturar `out.image_position = $('#gallery-image-position').val() || 'center';`.
  * Na hidratação `hydrateGalleryControls()`: popular `$('#gallery-image-position').val(schema.image_position || 'center');`.
  * No listener de `change`: acionar `serializeAndPreview()`.
* **Backend do Widget (`gestor/modulos/galleries/galleries.widget.php`)**:
  * Em `galleries_widget_resolver_globais()`: mapear a variável `image_position`:
    * Valor puro: `$schema['image_position'] ?? 'center'`.
    * Classe utilitária Tailwind correspondente: `object-center`, `object-top`, `object-bottom`.
* **Templates de Modelo de Galeria (`resources/{pt-br,en}/templates/`)**:
  * Atualizar os 4 templates (`galleries-carousel`, `galleries-grid`, `galleries-masonry`, `galleries-slider`):
    * Injetar o alinhamento nas tags `<img>` via `style="... object-position: @[[image_position]]@;"` ou classes Tailwind correspondentes.
* **Widget JS (`gestor/modulos/galleries/galleries.widget.js`)**:
  * Garantir que o preview no editor HTML e o runtime público renderizem a posição correta.
---
## Critérios de Aceite e Validação
1. **Lint e Validação Estática**:
   * `php -l` em todos os arquivos PHP do módulo `galleries`.
   * `node --check` em `galleries.js` e `galleries.widget.js`.
   * Validação de JSON em `galleries.json`.
2. **Suíte de Testes Automatizados**:
   * Adicionar testes unitários/integração para o novo campo `image_position` no `galleries.widget.php` e nos seletores de visualização.
   * `composer test` e `npx vitest run` 100% verdes, sem regressões.
3. **Validação Visual e Manual (Playwright & Navegador)**:
   * Abrir galeria com 15+ fotos:
     * Confirmar 6 colunas no modo Médio e 10 colunas no modo Pequeno, com fotos proporcionalmente mais altas.
     * Passar o mouse e validar o highlight do card e o overlay com engrenagem.
     * Clicar na engrenagem no modo Pequeno/Médio e editar a legenda/link de uma foto; conferir se a alteração persiste e reflete no preview.
     * Alterar o Alinhamento Vertical para "Topo" e "Fundo" e verificar se as imagens do carrossel/grid alteram o corte vertical no preview e na página pública.