LiquidGlass

O que é LiquidGlass?

LiquidGlass é uma biblioteca leve em JavaScript/TypeScript que renderiza efeitos realistas de vidro sobre qualquer elemento HTML usando shaders WebGL. Ela aplica refração, blur, aberração cromática, realces especulares e comportamentos de iluminação relacionados, capturando o conteúdo DOM atrás de cada elemento de vidro e compondo em tempo real.

A biblioteca é projetada para funcionar com fundos de página arbitrários (imagens, vídeos, canvases ou HTML simples). Ela usa um pipeline de renderização multi-pass e pode lidar com múltiplas camadas de vidro, configuração por elemento e atualizações dinâmicas na página.

Principais Recursos

• Renderização de vidro baseada em shaders WebGL para elementos HTML: Gera a aparência de vidro processando o conteúdo DOM atrás do elemento de vidro e compondo como saída de shader.
• Pipeline multi-pass em tempo real: Suporta efeitos como refração, controle de intensidade de blur, franjas cromáticas nas bordas e comportamentos de iluminação especular/rim.
• Configuração por elemento e global: Configure cada elemento de vidro individualmente via data-config (JSON) ou defina padrões globais pela opção defaults.
• Composição de vidro em camadas: Suporta configurações glass-on-glass via sua abordagem de composição.
• Opções de posicionamento interativo: Pode injetar comportamento de painel “flutuante” arrastável quando ativado (ex.: floating: true), e inclui modo button para feedback de shader em hover/press.
• Controles de superfície realistas: Parâmetros incluem cornerRadius, zRadius (profundidade do bevel), bevelMode (modo de curvatura da forma), brightness, saturation, shadowOpacity e reflexão fresnel.

Como Usar LiquidGlass

1. Instale ou importe: Instale via npm (npm install @ybouane/liquidglass) ou importe diretamente do CDN (https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js).
2. Crie um contêiner raiz posicionado: O elemento root passado para LiquidGlass.init() deve ser um contêiner com position: relative.
3. Adicione elementos de vidro dentro da raiz: Cada elemento de vidro deve ser um filho direto da raiz. Na inicialização, LiquidGlass injeta um <canvas> como primeiro filho do elemento de vidro para saída de shader.
4. Inicialize: Crie a instância com LiquidGlass.init({ root: document.querySelector('#my-root'), glassElements: document.querySelectorAll('.glass') }) e limpe depois com instance.destroy().
5. Configure efeitos: Forneça configurações por elemento via element.dataset.config = JSON.stringify({ ... }) (ex.: quantidade de blur, refração, raio de cantos). Use o padrão playground para ajustar parâmetros visualmente.

Casos de Uso

• Cartões e painéis “de vidro” personalizados: Aplique estilo de vidro fosco, escuro ou regular a um elemento de cartão ajustando blurAmount, brightness, cornerRadius e zRadius.
• Lente estilo lupa interativa: Use bevelMode: 1 com cornerRadius e zRadius correspondentes para efeito de lente meia-esfera/domo (e opcionalmente ative floating).
• Feedback UI de hover/press: Defina button: true para que o elemento de vidro reaja à interação do usuário — hover ilumina e pressiona achata o bevel enquanto aprofunda a sombra.
• Composições glass-on-glass em camadas: Construa UI multilayer onde elementos de vidro se sobrepõem, aproveitando a composição do LiquidGlass para efeitos empilhados.
• Vidro sobre fundos ricos: Posicione elementos de vidro sobre fundos que podem ser imagens, vídeos, canvases ou conteúdo HTML regular, mantendo esses fundos dentro dos filhos amostrados da raiz.

FAQ

Preciso de uma estrutura DOM específica?
Sim. A root deve ser um contêiner posicionado (position: relative), e cada elemento de vidro deve ser filho direto da raiz. Elementos de vidro aninhados são rejeitados na inicialização com aviso no console.

O que o LiquidGlass captura para o efeito de vidro?
O shader amostra os filhos da root, então conteúdo como imagens de fundo deve estar em um elemento irmão dentro da root. A própria root não é capturada.

O LiquidGlass cria elementos DOM para mim?
Ele injeta um <canvas> como primeiro filho do elemento de vidro para renderizar a saída de shader. Por isso, evite seletores CSS :first-child no elemento de vidro.

Posso usar múltiplas roots LiquidGlass na mesma página?
As limitações indicam que múltiplas roots LiquidGlass não podem compartilhar refração. Além disso, elementos de vidro em uma root não veem o que elementos de vidro em outra root estão renderizando.

Há considerações de performance?
Sim. A biblioteca depende de rasterização DOM em tempo real e pipeline WebGL multi-pass, e capturar DOM em canvas é descrito como caro.

Alternativas

• Efeitos de vidro apenas com CSS (backdrop-filter / técnicas baseadas em blur): Abordagens mais simples e puramente baseadas em CSS podem aproximar vidro fosco, mas geralmente não oferecem o mesmo comportamento de refração/aberação cromática/especular.
• Frameworks de shaders WebGL ou implementações personalizadas em Three.js/WebGL: Se precisar de controle total, pode implementar passes de shaders personalizados; isso transfere o trabalho de uma abstração de biblioteca para seu próprio pipeline de renderização.
• Outros pipelines de efeitos DOM-para-canvas/em tempo real: Soluções adjacentes que rasterizam DOM em texturas podem criar efeitos em espaço de tela, mas o fluxo de trabalho e configuração diferem da configuração de elemento de vidro baseado em DOM do LiquidGlass.
• Ativos de design estáticos: Para casos em que interações e atualizações em tempo real não são necessárias, imagens de vidro pré-renderizadas ou componentes exportados podem reduzir o custo em tempo de execução, às custas de mudanças dinâmicas em refração/parâmetros.