# OpenGlass UI: Kompletny przewodnik po bibliotece Liquid Glass dla React

> Architektura i implementacja OpenGlass UI: 40 natywnych komponentów, renderery CSS, SVG SDF oraz WebGL2, konfiguracja tokenów, SSR w Next.js i zgodność z WCAG 2.2.

OpenGlass UI to nowoczesna biblioteka komponentów React i webowych, stworzona w celu implementacji estetyki „płynnego szkła” (Liquid Glass) w interfejsach cyfrowych. W odróżnieniu od prymitywnych implementacji CSS opartych na prostym `backdrop-filter: blur()`, OpenGlass UI łączy prawdziwe fizyczne modele refrakcji światła, obsługę pól odległości znakowanej (SDF, Signed Distance Fields), akcelerację sprzętową przez WebGL2 oraz natywną dostępność zgodną ze standardem WCAG 2.2.

Niniejszy przewodnik obejmuje architekturę biblioteki, zasady trójpoziomowego renderingu, praktyczną integrację z Next.js App Router, system tokenów designu oraz reguły optymalizacji wydajności.

---

## 1. Koncepcja Liquid Glass i możliwości OpenGlass UI

### 1.1. Filozofia płynnego szkła: połączenie natywnego DOM i efektów optycznych

Klasyczny glassmorphism jest często krytykowany za wysokie obciążenie procesora i słabą czytelność tekstu. OpenGlass UI rozwiązuje ten problem dzięki ścisłemu rozdzieleniu warstw:
- **Szkielet semantyczny:** Wszystkie 40 komponentów biblioteki zostało zbudowanych wyłącznie na natywnych tagach HTML (`<button>`, `<input>`, `<dialog>`), co zapewnia zachowanie nawigacji klawiaturowej oraz wsparcie dla czytników ekranu.
- **Materiały optyczne:** Warstwa materiału wizualnego dostosowuje się do tła przy użyciu adaptacyjnego kontrastu, tonowania, fazek (bevel) i odbić.
- **Hierarchia degradacji (Graceful Degradation):** Jeśli urządzenie nie obsługuje obliczeń sprzętowych lub użytkownik włączył tryb zmniejszonej przejrzystości w systemie, biblioteka niezauważalnie przełącza się na nieprzezroczyste materiały CSS bez deformacji markupu.

### 1.2. Macierz porównawcza trzech rendererów: CSS, refrakcja SVG i WebGL2

OpenGlass UI oferuje trzy uzupełniające się potoki graficzne w zależności od złożoności powierzchni:

```mermaid
flowchart TD
    A["GlassSurface запит на рендеринг"] --> B{"Тип джерела та цільова форма"}
    B -->|"Довільний DOM / Контроли / Текст"| C["1. CSS Renderer (За замовчуванням: швидкий blur, border, shadow)"]
    B -->|"Замкнена геометрія DOM (Прямокутник, капсула)"| D["2. SVG / SDF Renderer (Справжнє заломлення світла через Displacement Map)"]
    B -->|"Динамічне медіа (Відео, Canvas, Зображення)"| E["3. WebGL2 Renderer (Апаратні лінзи з дисперсією IOR у реальному часі)"]
```

| Renderer | Możliwości optyczne | Obciążenie GPU | Obsługa przez przeglądarki | Optymalny zakres zastosowań |
| :--- | :--- | :--- | :--- | :--- |
| **CSS (Auto)** | Tonowanie, rozmycie, obramowania, cienie | Minimalne | 99.8% (Wszystkie współczesne platformy) | Przyciski, pola formularzy, karty, nawigacja, listy |
| **SDF / SVG** | Refrakcja światła wzdłuż konturu figury (IOR) | Umiarkowane | Wszystkie przeglądarki z obsługą filtrów SVG | Okna modalne, pływające panele Dock, zakładki |
| **WebGL2** | Realistyczna dyspersja chromatyczna, soczewki | Wysokie | Wymagana obsługa WebGL2 | Odtwarzacze mediów, interaktywne soczewki nad 3D/wideo |

---

## 2. Architektura pakietów i instalacja

### 2.1. Struktura modułowa: fasada open-glass-ui i wewnętrzne pakiety

Publiczna fasada `open-glass-ui` łączy cztery wewnętrzne pakiety workspace, wyraźnie rozdzielając obowiązki komponentów:

```mermaid
flowchart LR
    A["open-glass-ui (Публічний npm-фасад)"] --> B["@open-glass-ui/core (Геометрія, математика SDF, токени без React)"]
    A --> C["@open-glass-ui/renderers (CSS-матеріали, шейдери WebGL2, SVG-хелпери)"]
    A --> D["@open-glass-ui/react (Провайдери стану, хуки, життєвий цикл SSR)"]
    A --> E["@open-glass-ui/recipes (40 готових UI-компонентів на нативному DOM)"]
```

> [!WARNING]
> Bezpośrednie importowanie komponentów z pakietów wewnętrznych (np. `@open-glass-ui/core` lub `@open-glass-ui/recipes`) jest surowo zabronione. Korzystaj wyłącznie z publicznych podścieżek fasady:
> - `open-glass-ui` — główne komponenty React, providery i hooki.
> - `open-glass-ui/webgl` — podsystem akcelerowanych sprzętowo powierzchni WebGL2.
> - `open-glass-ui/core` — czyste utility matematyki motywu, kalkulacji kontrastu i kolorów dla komponentów serwerowych.

### 2.2. Instalacja zależności i podstawowa konfiguracja stylów

Zainstaluj bibliotekę za pomocą wybranego menedżera pakietów:

```bash
npm install open-glass-ui
# або
pnpm add open-glass-ui
```

Podłącz globalne style w punkcie wejścia aplikacji (np. w `src/app/layout.tsx` lub `src/main.tsx`):

```typescript
// Обов'язковий імпорт базових CSS-матеріалів:
import "open-glass-ui/styles.css";
import { Button, Glass, GlassSystemProvider } from "open-glass-ui";

export function RootApplication() {
  return (
    <GlassSystemProvider
      renderer="auto"
      quality="auto"
      motion="system"
      theme={{
        appearance: "system",
        defaultAppearance: "dark",
        theme: { preset: "neutral", contrast: "high", radius: "balanced" },
      }}
    >
      <main className="min-h-screen bg-slate-950 p-8">
        <Glass material="regular" interactive>
          <Button variant="primary">Розпочати роботу</Button>
        </Glass>
      </main>
    </GlassSystemProvider>
  );
}
```

---

## 3. Konfiguracja systemu motywów: palety, kontrast i tokeny CSS

### 3.1. Zarządzanie motywami: presety, tryby appearance i promienie zaokrąglenia

Motyw w OpenGlass UI opiera się na trzech powiązanych wymiarach:
1. **Wygląd (Appearance):** Przyjmuje wartości `light`, `dark` lub `system`. Dla wartości `system` serwer zwraca bezpieczny `defaultAppearance`, a po stronie klienta przechwytywane jest zapytanie media `prefers-color-scheme`.
2. **Paleta kolorów (Presets):** Dostępne są gotowe, dopracowane schematy (`neutral`, `cobalt`, `teal`, `violet`, `coral`, `amber`) lub własne wartości poprzez parametry `accent`, `secondary`, `tertiary`.
3. **Promień zaokrąglenia (Radius):** Warianty `sharp` (minimalny), `balanced` (standardowy, 12–16px) oraz `soft` (organiczny, 24–28px).

### 3.2. Macierz semantycznych tokenów --ogui-* i weryfikacja kontrastu (WCAG)

Wszystkie komponenty są stylizowane poprzez stabilne zmienne CSS:

```css
/* Базові поверхні та межі */
--ogui-color-background: #090d16;
--ogui-color-surface: rgba(15, 23, 42, 0.65);
--ogui-color-border: rgba(255, 255, 255, 0.12);
--ogui-color-text: #f8fafc;
--ogui-color-muted: #94a3b8;

/* Акцентні стани та фокус */
--ogui-color-accent: #38bdf8;
--ogui-color-accent-ink: #031525;
--ogui-color-focus: #0284c7;

/* Радіуси та оптичні властивості матеріалу */
--ogui-radius-control: 8px;
--ogui-radius-surface: 16px;
--ogui-material-blur: 16px;
--ogui-material-bevel: 1px;
```

> 💡 **Reguła weryfikacji kontrastu:** Używaj eksportowanej funkcji `contrastRatio(colorA, colorB)` z `open-glass-ui/core`. Kontrast tekstu musi wynosić co najmniej 4.5:1 dla zwykłego tekstu oraz 3:1 dla dużych nagłówków zgodnie ze standardem WCAG 2.2 AA.

---

## 4. Katalog komponentów: przegląd 40 przepisów na natywnym DOM

### 4.1. Kategorie gotowych komponentów: kontrolki, nakładki, nawigacja i formularze

Pakiet zawiera 40 gotowych komponentów z natywnym markupiem:

| Kategoria | Komponenty w składzie biblioteki |
| :--- | :--- |
| **Elementy akcji i kontrolki** | `Button`, `IconButton`, `ToggleButton`, `SegmentedControl`, `Switch`, `Slider`, `Stepper` |
| **Nawigacja i kontenery** | `Toolbar`, `Dock`, `Tabs`, `Breadcrumbs`, `Pagination`, `Menu`, `MenuItem` |
| **Nakładki i okna wyskakujące** | `Dialog`, `Drawer`, `Popover`, `Tooltip`, `Toast`, `Alert`, `Banner` |
| **Formularze i wprowadzanie danych** | `TextField`, `Textarea`, `NumberField`, `SearchField`, `Select`, `Checkbox`, `RadioGroup`, `FileDropzone` |
| **Prezentacja informacji** | `Card`, `Stat`, `Badge`, `Avatar`, `AvatarGroup`, `Accordion`, `Progress`, `Meter`, `Spinner`, `Skeleton`, `MediaControls` |

### 4.2. Standardy dostępności (a11y): etykiety ARIA, zarządzanie fokusem i stanami

Przy korzystaniu z komponentów OpenGlass UI należy bezwzględnie przestrzegać zasad dostępności:
- **Obowiązkowy `aria-label` dla ikon:** `IconButton` oraz `SegmentedControl` wymagają jawnego opis tekstowego dla czytników ekranu.
- **Zwrot fokusu w dialogach:** W `Dialog` i `Drawer` fokus przy zamknięciu automatycznie wraca do elementu wywołującego.
- **Podwójne kodowanie stanów:** Nie oznaczaj stanu wyboru, błędu ani blokady wyłącznie przez przezroczystość lub kolor. Zawsze towarzyszy temu zmiana ikony lub tekstowa plakietka (badge).

---

## 5. Praca z rendererami: od bazowego CSS do opcjonalnego WebGL2

### 5.1. Deklaratywna refrakcja SVG/SDF dla zamkniętych figur geometrycznych

Dla pływających kart lub paneli sterowania można włączyć prawdziwą refrakcję światła przy użyciu pól odległości znakowanej (SDF):

```typescript
import React from "react";
import { Glass, SdfFilterDefinition, useSdfFilter } from "open-glass-ui";

const panelGeometry = {
  kind: "rounded-rect",
  width: 360,
  height: 200,
  cornerRadius: 24,
} as const;

export function RefractedControlPanel({ children }: { children: React.ReactNode }) {
  const filter = useSdfFilter({
    id: "main-panel-filter",
    width: 360,
    height: 200,
    geometry: panelGeometry,
    quality: "medium",
  });

  return (
    <div className="relative inline-block">
      <SdfFilterDefinition filter={filter} />
      <Glass 
        renderer="sdf-svg" 
        filterId={filter.filterId} 
        geometry={panelGeometry}
        material="regular"
      >
        <div className="p-6 text-slate-100">
          {children}
        </div>
      </Glass>
    </div>
  );
}
```

### 5.2. Sprzętowe soczewki optyczne w WebGL2 nad wideo i canvas

Jeśli na stronie odtwarzane jest wideo, grafika interaktywna lub scena 3D, moduł `open-glass-ui/webgl` pozwala nałożyć sprzętową soczewkę z fizycznym wskaźnikiem refrakcji (IOR):

```typescript
"use client";

import React, { useRef } from "react";
import { GlassProvider } from "open-glass-ui";
import { WebGLGlassSurface } from "open-glass-ui/webgl";

const opticalMaterial = {
  thickness: 0.62,
  ior: 1.48,           // Показник заломлення (коефіцієнт скла)
  dispersion: 0.015,   // Хроматична дисперсія по краях
  edgeStrength: 0.5,
  bevel: 0.7,
  frost: 0.2,
};

export function InteractiveVideoLens() {
  const videoRef = useRef<HTMLVideoElement>(null);

  return (
    <GlassProvider>
      <div className="relative overflow-hidden rounded-2xl">
        <video 
          ref={videoRef} 
          src="/ambient-flow.mp4" 
          autoPlay 
          loop 
          muted 
          playsInline 
          className="w-full h-auto block"
        />
        <WebGLGlassSurface
          sourceRef={videoRef}
          continuous
          maxDevicePixelRatio={2}
          lenses={[
            {
              x: 180,
              y: 120,
              width: 240,
              height: 120,
              radius: 0.4,
              material: opticalMaterial,
            },
          ]}
        />
      </div>
    </GlassProvider>
  );
}
```

---

## 6. Integracja z Next.js App Router i renderingiem po stronie serwera (SSR)

### 6.1. Hydratacja bez konfliktów: izolacja granic klienckich i utility core

OpenGlass UI została zaprojektowana z myślą o współczesnym renderingu po stronie serwera. Serwer nigdy nie próbuje odwoływać się do `window`, `document` ani kontekstu WebGL.

Utwórz provider korzeniowy w komponencie klienckim:

```typescript
// src/components/providers/GlassRootProvider.tsx
"use client";

import React from "react";
import "open-glass-ui/styles.css";
import { GlassSystemProvider } from "open-glass-ui";

export function GlassRootProvider({ children }: { children: React.ReactNode }) {
  return (
    <GlassSystemProvider
      renderer="auto"
      quality="auto"
      theme={{
        appearance: "system",
        defaultAppearance: "dark",
      }}
    >
      {children}
    </GlassSystemProvider>
  );
}
```

Czyste funkcje do obliczania kolorów lub schematów motywów importuj w Server Components z `open-glass-ui/core`:

```typescript
// src/app/page.tsx (Server Component)
import { createGlassTheme } from "open-glass-ui/core";
import { GlassRootProvider } from "@/components/providers/GlassRootProvider";

export default function Page() {
  const staticTheme = createGlassTheme({ preset: "neutral", contrast: "high" });

  return (
    <GlassRootProvider>
      <h1 className="text-2xl font-bold">Серверний рендеринг готовий</h1>
    </GlassRootProvider>
  );
}
```

### 6.2. Unikanie rozbieżności markupu i praca z prefers-color-scheme

Aby zapobiec ostrzeżeniom o niedopasowaniu hydratacji (Hydration Mismatch):
- Nie używaj operatorów ternarnych zależnych od `window.innerWidth` podczas pierwszego renderu.
- Używaj propa `defaultAppearance="dark"` w celu stabilizacji początkowego HTML między serwerem a klientem.

---

## 7. Wydajność i optymalizacja potoku graficznego

### 7.1. Redukcja obciążenia GPU: ograniczenie DPR i selektywne stosowanie szkła

Masowe nakładanie warstw z rozmyciem tła może przeciążyć nawet dedykowaną kartę graficzną. Przestrzegaj następujących rekomendacji:
- **Ogranicz Device Pixel Ratio:** Zawsze ustawiaj `maxDevicePixelRatio={2}` w konfiguracjach powierzchni WebGL. Rendering na ekranach Retina z DPR 3+ zużywa czterokrotnie więcej pamięci wideo bez zauważalnej różnicy w jakości.
- **Punktowe nakładanie materiału:** Stosuj szkło tylko dla górnych warstw nawigacji (Header, Dock, Modal). Zwykłe listy treści powinny mieć klasyczne nieprzezroczyste lub półprzezroczyste tło CSS.
- **Aktualizacja pozycji kursora:** Dla interaktywnych efektów śledzenia myszy zmieniaj zmienne CSS lub `transform` przez `ref`, unikając wywoływania `setState` dla każdego piksela ruchu.

### 7.2. Cacheowanie map odległości (SDF) i optymalizacja zmiany rozmiaru (Resize)

Generowanie map SDF dla filtrów SVG jest operacją zasobożerną. Hook `useSdfFilter` automatycznie cacheuje mapy według hasha parametrów geometrycznych. Przy zmianie rozmiaru okna przeglądarki biblioteka automatycznie przełącza się na niską jakość renderingu, przywracając maksymalną ostrość dopiero po zakończeniu resize’u.

---

## 8. Macierz typowych problemów i najczęściej zadawane pytania (FAQ)

### 8.1. Diagnostyka awarii renderingu, spadku kontrastu i wycieków pamięci

| Objaw / Błąd | Przyczyna źródłowa | Rozwiązanie inżynierskie |
| :--- | :--- | :--- |
| Efekt szkła nieobecny (białe/szare tło) | Nie podłączono pliku stylów `styles.css` | Dodaj `import "open-glass-ui/styles.css";` w katalogu głównym projektu |
| Tekst staje się nieczytelny na jasnych zdjęciach | Użyto zbyt przezroczystego materiału `clear` | Przełącz prop na `material="regular"` lub `material="frosted"`, aby utworzyć matowe podłoże |
| Spadek płynności scrollowania na urządzeniach mobilnych | Duża liczba zagnieżdżonych powierzchni z rendererem `sdf-svg` | Pozostaw `renderer="auto"` (CSS) dla masowych elementów interfejsu |
| Błąd `WebGL context lost` | Przekroczono limit aktywnych kontekstów canvas | Ogranicz liczbę aktywnych soczewek do 6 na jedno źródło `WebGLGlassSurface` |

### 8.2. Odpowiedzi na częste pytania deweloperów dotyczące OpenGlass UI

> ❓ **Czy biblioteka jest kompatybilna z Tailwind CSS?**  
> Tak. OpenGlass UI nie blokuje utilitów Tailwind. Możesz bezpiecznie łączyć klasy typu `className="flex items-center gap-4 p-6"` z propsami `material` i `interactive`.

> ❓ **Czy biblioteka jest gotowa do użycia w środowisku produkcyjnym?**  
> Obecnie biblioteka ma status pre-release. Jej architektura i publiczne API są już ustabilizowane, jednak przed aktualizacją wersji minor zaleca się uważne przeglądanie dziennika zmian (Changelog).

> ❓ **Jak zachowuje się interfejs, jeśli użytkownik ma włączony wymuszony wysoki kontrast w Windows?**  
> Biblioteka wykrywa preferencje systemowe i odpowiednio modyfikuje materiały, zapewniając pełną czytelność i zgodność z normami dostępności, nawet w trybach wysokiego kontrastu.