LiquidGlass

¿Qué es LiquidGlass?

LiquidGlass es una biblioteca ligera en JavaScript/TypeScript que renderiza efectos de cristal realistas sobre cualquier elemento HTML mediante shaders WebGL. Aplica refracción, desenfoque, aberración cromática, reflejos especulares y comportamientos de iluminación relacionados al capturar el contenido DOM detrás de cada elemento de cristal y componerlo en tiempo real.

La biblioteca está diseñada para funcionar con fondos de página arbitrarios (imágenes, videos, lienzos o HTML simple). Utiliza un pipeline de renderizado multipaso y puede manejar múltiples capas de cristal, configuración por elemento y actualizaciones dinámicas en la página.

Características principales

• Renderizado de cristal basado en shaders WebGL para elementos HTML: Genera el aspecto de cristal procesando el contenido DOM detrás del elemento de cristal y componiéndolo como salida de shader.
• Pipeline multipaso en tiempo real: Soporta efectos como refracción, control de intensidad de desenfoque, aberración cromática en bordes y comportamientos de iluminación especular/borde.
• Configuración por elemento y global: Configura cada elemento de cristal individualmente mediante data-config (JSON) o establece valores predeterminados globales con la opción defaults.
• Composición de cristal en capas: Soporta configuraciones de cristal sobre cristal mediante su enfoque de composición.
• Opciones de posicionamiento interactivo: Puede inyectar comportamiento de panel “flotante” arrastrable cuando está habilitado (p. ej., floating: true), e incluye un modo button para retroalimentación de shader en hover/presión.
• Controles de superficie realistas: Parámetros incluyen cornerRadius, zRadius (profundidad de bisel), bevelMode (modo de curvatura de forma), brightness, saturation, shadowOpacity y reflexión fresnel.

Cómo usar LiquidGlass

1. Instalar o importar: Instala vía npm (npm install @ybouane/liquidglass) o importa directamente desde el CDN (https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js).
2. Crear un contenedor raíz posicionado: El elemento root pasado a LiquidGlass.init() debe ser un contenedor con position: relative.
3. Agregar elementos de cristal dentro del raíz: Cada elemento de cristal debe ser un hijo directo del raíz. Al inicializar, LiquidGlass inyecta un <canvas> como primer hijo del elemento de cristal para la salida de shader.
4. Inicializar: Crea la instancia con LiquidGlass.init({ root: document.querySelector('#my-root'), glassElements: document.querySelectorAll('.glass') }) y limpia después con instance.destroy().
5. Configurar efectos: Proporciona ajustes por elemento mediante element.dataset.config = JSON.stringify({ ... }) (p. ej., cantidad de desenfoque, refracción, radio de esquinas). Usa el patrón de playground para ajustar parámetros visualmente.

Casos de uso

• Tarjetas y paneles “de cristal” personalizados: Aplica estilos de cristal esmerilado, oscuro o regular a un elemento de tarjeta ajustando blurAmount, brightness, cornerRadius y zRadius.
• Lente estilo lupa interactiva: Usa bevelMode: 1 junto con cornerRadius y zRadius coincidentes para obtener un efecto de lente semiesférico/cúpula (y opcionalmente habilita floating).
• Retroalimentación UI en hover/presión: Establece button: true para que el elemento de cristal reaccione a la interacción del usuario: el hover ilumina y la presión aplana el bisel mientras profundiza la sombra.
• Composiciones de cristal en capas: Construye UI multicapa donde diferentes elementos de cristal se superponen, aprovechando la composición de LiquidGlass para efectos apilados.
• Cristal sobre fondos ricos: Coloca elementos de cristal sobre fondos que pueden ser imágenes, videos, lienzos o contenido HTML regular, manteniendo esos fondos dentro de los hijos muestreados del raíz.

Preguntas frecuentes

¿Necesito una estructura DOM específica?
Sí. El root debe ser un contenedor posicionado (position: relative), y cada elemento de cristal debe ser un hijo directo del raíz. Los elementos de cristal anidados se rechazan en la inicialización con una advertencia en consola.

¿Qué captura LiquidGlass para el efecto de cristal?
El shader muestrea los hijos del raíz, por lo que el contenido como imágenes de fondo debe estar en un elemento hermano dentro del raíz. El propio raíz no se captura.

¿LiquidGlass crea algún elemento DOM por mí?
Inyecta un <canvas> como primer hijo del elemento de cristal para renderizar la salida de shader. Por esto, evita depender de selectores CSS :first-child para el elemento de cristal.

¿Puedo usar múltiples raíces LiquidGlass en la misma página?
Las limitaciones indican que múltiples raíces LiquidGlass no pueden compartir refracción. Además, los elementos de cristal en una raíz no pueden ver lo que renderizan los elementos de cristal en otra raíz.

¿Hay consideraciones de rendimiento?
Sí. La biblioteca depende de la rasterización DOM en tiempo real y un pipeline WebGL multipaso, y capturar DOM en un canvas se describe como costoso.

Alternativas

• Efectos de cristal solo con CSS (backdrop-filter / técnicas basadas en desenfoque): Enfoques más simples y puramente basados en CSS pueden aproximar cristal esmerilado, pero normalmente no proporcionan el mismo comportamiento de refracción/aberración cromática/especular.
• Frameworks de shaders WebGL o implementaciones personalizadas de Three.js/WebGL: Si necesitas control total, puedes implementar pases de shaders personalizados tú mismo; esto desplaza el trabajo de una abstracción de biblioteca a tu propio pipeline de renderizado.
• Otras pipelines de efectos DOM-a-canvas/tiempo real: Soluciones adyacentes que rasterizan DOM a texturas pueden usarse para crear efectos en espacio de pantalla, pero el flujo de trabajo y la configuración diferirán del setup de elementos de cristal basado en DOM de LiquidGlass.
• Activos de diseño estáticos: Para casos donde no se requieren interacciones ni actualizaciones en tiempo real, imágenes de cristal pre-renderizadas o componentes exportados pueden reducir el costo en tiempo de ejecución, a expensas de cambios dinámicos en refracción/parámetros.