LiquidGlass

Che cos'è LiquidGlass?

LiquidGlass è una libreria leggera JavaScript/TypeScript che rende effetti vetro realistici sopra qualsiasi elemento HTML usando shader WebGL. Applica rifrazione, blur, aberrazione cromatica, riflessi speculari e comportamenti di illuminazione correlati catturando il contenuto DOM dietro ogni elemento vetro e componendolo in tempo reale.

La libreria è progettata per funzionare con sfondi di pagina arbitrari (immagini, video, canvas o HTML semplice). Utilizza un pipeline di rendering multi-passo e gestisce più layer vetro, configurazione per elemento e aggiornamenti dinamici sulla pagina.

Caratteristiche Principali

• Rendering vetro basato su shader WebGL per elementi HTML: Genera l'aspetto vetro elaborando il contenuto DOM dietro l'elemento vetro e componendolo come output shader.
• Pipeline multi-passo in tempo reale: Supporta effetti come rifrazione, controllo intensità blur, frange cromatiche ai bordi e comportamenti di illuminazione speculare/rim.
• Configurazione per elemento e globale: Configura ogni elemento vetro individualmente via data-config (JSON) o imposta valori globali predefiniti con l'opzione defaults.
• Compositing vetro stratificato: Supporta setup vetro-su-vetro tramite il suo approccio di compositing.
• Opzioni di posizionamento interattivo: Può iniettare comportamento pannello "galleggiante" trascinabile quando abilitato (es. floating: true), e include una modalità button per feedback shader su hover/premi.
• Controlli superficie realistici: Parametri includono cornerRadius, zRadius (profondità bevel), bevelMode (modalità curvatura forma), brightness, saturation, shadowOpacity e riflessione fresnel.

Come Usare LiquidGlass

1. Installa o importa: Installa via npm (npm install @ybouane/liquidglass) o importa direttamente dal CDN (https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js).
2. Crea un container root posizionato: L'elemento root passato a LiquidGlass.init() deve essere un container con position: relative.
3. Aggiungi elementi vetro dentro il root: Ogni elemento vetro deve essere un figlio diretto del root. All'inizializzazione, LiquidGlass inietta un <canvas> come primo figlio dell'elemento vetro per l'output shader.
4. Inizializza: Crea l'istanza con LiquidGlass.init({ root: document.querySelector('#my-root'), glassElements: document.querySelectorAll('.glass') }) e pulisci in seguito con instance.destroy().
5. Configura effetti: Fornisci impostazioni per elemento via element.dataset.config = JSON.stringify({ ... }) (es. quantità blur, rifrazione, raggio angoli). Usa il pattern playground per regolare i parametri visivamente.

Casi d'Uso

• Card e pannelli "vetro" personalizzati: Applica stile vetro satinato, scuro o regolare a un elemento card regolando blurAmount, brightness, cornerRadius e zRadius.
• Lente interattiva stile ingranditore: Usa bevelMode: 1 con cornerRadius e zRadius corrispondenti per un effetto lente emisferica/cupola (e opzionalmente abilita floating).
• Feedback UI hover/premi: Imposta button: true così l'elemento vetro reagisce all'interazione utente—hover illumina e premi appiattisce il bevel mentre approfondisce l'ombra.
• Composizioni vetro-su-vetro stratificate: Costruisci UI multi-layer dove diversi elementi vetro si sovrappongono, sfruttando il compositing di LiquidGlass per effetti impilati.
• Vetro su sfondi ricchi: Posiziona elementi vetro sopra sfondi che possono essere immagini, video, canvas o contenuto HTML regolare, mantenendo quegli sfondi tra i figli campionati del root.

FAQ

Serve una struttura DOM specifica?
Sì. Il root deve essere un container posizionato (position: relative), e ogni elemento vetro deve essere un figlio diretto del root. Gli elementi vetro annidati vengono rifiutati all'inizializzazione con un warning in console.

Cosa cattura LiquidGlass per l'effetto vetro?
Lo shader campiona i figli del root, quindi contenuti come immagini di sfondo devono essere in un elemento fratello dentro il root. Il root stesso non viene catturato.

LiquidGlass crea elementi DOM per me?
Inietta un <canvas> come primo figlio dell'elemento vetro per rendere l'output shader. Per questo, evita di affidarti a selettori CSS :first-child per l'elemento vetro.

Posso usare più root LiquidGlass sulla stessa pagina?
Le limitazioni indicano che più root LiquidGlass non possono condividere rifrazione. Inoltre, gli elementi vetro in un root non vedono cosa rendono gli elementi vetro in un altro root.

Ci sono considerazioni di performance?
Sì. La libreria si basa su rasterizzazione DOM in tempo reale e un pipeline WebGL multi-passo, e la cattura DOM in un canvas è descritta come costosa.

Alternative

• Effetti vetro solo CSS (backdrop-filter / tecniche basate su blur): Approcci più semplici e puramente CSS possono simulare il vetro satinato, ma tipicamente non offrono lo stesso comportamento di rifrazione/aberration cromatica/specular pipeline.
• Framework shader WebGL o implementazioni personalizzate Three.js/WebGL: Se serve il controllo totale, puoi realizzare passaggi shader personalizzati; questo sposta il lavoro dall'astrazione della libreria alla tua pipeline di rendering.
• Altri pipeline DOM-to-canvas/effetti real-time: Soluzioni adiacenti che rasterizzano il DOM in texture possono creare effetti screen-space, ma workflow e configurazione differiscono dalla configurazione elemento vetro DOM-based di LiquidGlass.
• Asset di design statici: Per casi senza interazioni e aggiornamenti real-time, immagini vetro pre-renderizzate o componenti esportati riducono i costi runtime, a scapito di rifrazione dinamica/cambi parametri.