Identificación del Problema: Fallos de Superposición en Modo Oscuro

Al implementar interfaces en JeecgBoot, la transición al modo oscuro suele desencadenar anomalías visuales relacionadas con las capas de la interfaz. Los síntomas más frecuentes incluyen:

• Opacidad incorrecta en máscaras de modales: El fondo semitransparente no se renderiza adecuadamente o desaparece por completo.
• Desorden en los menús desplegables: Los componentes dropdown quedan ocultos detrás de otros elementos del DOM.
• Conflictos de estilo en módulos complejos: Especialmente notorio en integraciones de chat o paneles flotantes.

Análisis del Código Fuente: Arquitectura de Temas

Para abordar estos defectos, es fundamental comprender cómo el framework gestiona los estilos globales y las variables de entorno.

1. Configuración Inicial del Tema

La lógica central de alternancia se encuentra en los archivos de configurcaión de Vite y los stores de la aplicación. A continuación, se muestra una versión refactorizada del mecanismo de alternancia:

import { appSettings } from '@/config';

export const activeColor = appSettings.primaryHue;
export const currentTheme = appSettings.displayMode;

export function toggleThemeMode(selectedMode: 'light' | 'dark' = 'light') {
  const rootElement = document.documentElement;
  const isDark = selectedMode === 'dark';
  
  rootElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
  rootElement.classList.toggle('dark-mode', isDark);
}

2. Conflictos por Valores Estáticos

En módulos como el asistente virtual, es común encontrar propiedades de apilamiento definidas de manera rígida, lo cual rompe la jerarquía al cambiar el contexto del tema:

.assistant-dialog-wrapper {
  z-index: 9999 !important;
}
.assistant-message-bubble {
  z-index: 9999 !important;
}

Procedimiento de Resolución en Tres Fases

Fase 1: Validación del Estado del Tema

Verifique que el DOM raíz refleje correctamente el estado actual. Ejecute el siguiente fragmento en la consola del navegador:

const rootEl = document.documentElement;
console.log(rootEl.dataset.theme);
console.log(rootEl.classList.contains('dark-mode'));

Si el atributo data-theme no coincide con la clase CSS aplicada, el mecanismo de conmutación está fallando a nivel de estado global.

Fase 2: Depuración de Carga de CSS en Producción

El entorno de producción utiliza una estrategia de inyección dinámica de hojas de estilo. Revise el plugin de Vite responsable de esta tarea:

const isProduction = import.meta.env.PROD;
const isDarkActive = useAppStore().currentTheme === 'dark';

if (isProduction && isDarkActive) {
  if (!isDarkStylesLoaded && !extractedCss) {
    loadDarkThemeStyles();
  }
}

Asegúrese de que la condición evalúe correctamente el estado de la tienda antes de intentar inyectar los estilos oscuros.

Fase 3: Refactorización de la Gestión de Capas (Z-Index)

Para componentes con alta complejidad visual, adopte un sistema basado en variables CSS:

Definición de variables globales:

:root {
  --layer-dialog: 1000;
  --layer-popover: 1050;
  --layer-notification: 1100;
}

Eliminación de valores absolutos:

/* Enfoque incorrecto */
.assistant-dialog-wrapper {
  z-index: 9999 !important;
}

/* Enfoque optimizado */
.assistant-dialog-wrapper {
  z-index: var(--layer-dialog);
}

Ajuste de opacidad contextual:

.custom-modal-overlay {
  background: rgba(0, 0, 0, 0.4);
}
.dark-mode .custom-modal-overlay {
  background: rgba(0, 0, 0, 0.7);
}

Caso Práctico: Corrección en el Módulo de Chat

Al depurar el componente de mensajería, se identificó un menú desplegable con estilos en línea que forazban una capa incorrecta.

Implementación original problemática:

<a-dropdown 
  placement="topLeft" 
  :trigger="['click']" 
  overlayClassName="msg-options-menu"
  :overlayStyle="{ 'z-index': 9999 }">

Implementación corregida:

<a-dropdown 
  placement="bottomRight" 
  :trigger="['hover']" 
  overlayClassName="msg-options-menu"
  class="dropdown-layer-managed">

Esta modificación delega la responsabilidad del apilamiento a las clases CSS globales, garantizando compatibilidad total con las transiciones de tema y evitando colisiones con las máscaras de los modales subyacentes.