# Architektúra

TailwindPHP je port 1:1. Štruktúra kódovej základne kopíruje štruktúru TailwindCSS — rovnaké názvy súborov, rovnaké usporiadanie — a oddeľuje časti, ktoré *nemôžu* byť priamym portom (PHP nemá Rust ani V8), do `src/_tailwindphp/`. Táto stránka opisuje postupnosť fáz kompilácie, usporiadanie zdrojových súborov, opätovnú implementáciu `lightningcss` a konvenciu na dokumentovanie odchýlok.

## Proces spracovania

Generovanie CSS pozostáva zo série fáz. Samostatný krok zostavenia neexistuje — každé volanie `tw::generate()` spustí celý postup.

```
CSS input          (@import "tailwindcss"; @theme { … })
  │
  ▼
┌──────────────┐
│  Parse CSS   │  css-parser.php → ast.php nodes
└──────┬───────┘
       ▼  design system (theme, utilities, variants)
┌──────────────┐
│ Scan content │  candidate.php — extract class names from HTML
└──────┬───────┘
       ▼  candidates
┌──────────────┐
│   Compile    │  compile.php — candidate → AST, via design-system.php
└──────┬───────┘
       ▼  AST
┌──────────────┐
│   Optimize   │  _tailwindphp/LightningCss.php — nesting, @media, calc()
└──────┬───────┘
       ▼
┌──────────────┐
│  Serialize   │  ast.php toCss()   (minified when requested)
└──────┬───────┘
       ▼
CSS output
```

**Parsovanie.** `css-parser.php` načíta vstup CSS — `@import`, `@theme`, `@utility`, `@layer` a surové pravidlá — do abstraktného syntaktického stromu zloženého z uzlov `ast.php` (pravidlá štýlov, pravidlá at, deklarácie). Direktívy `@import` pre virtuálne moduly (`tailwindcss`, `tailwindcss/preflight`, …) a cesty k súborom sa v tejto fáze vyriešia a nahradia.

**Zostavenie dizajnového systému.** `theme.php` odvodí hodnoty témy (farby, rozostupy, body zlomu) z naparsovaných blokov `@theme` a predvolených hodnôt. `design-system.php` je centrálny register, ktorý prepája tému s vyhľadávaním pomocných tried a variantov definovaným v `utilities.php` a `variants.php`.

**Skenovanie obsahu.** `candidate.php` extrahuje kandidátov na názvy tried z dodaného obsahu (HTML, šablóny) a rozloží každého z nich na časti — základnú pomocnú triedu, varianty, modifikátory, ľubovoľné hodnoty a príznak dôležitosti.

**Kompilácia.** `compile.php` zmení každého kandidáta na uzly AST tak, že ho vyhľadá v dizajnovom systéme a uplatní jeho varianty a modifikátory. Kandidáti, ktorí nezodpovedajú skutočnej pomocnej triede, sa zahodia.

**Serializácia a optimalizácia.** `toCss()` v `ast.php` prechádza strom (pomocné funkcie sú v `walk.php`) a vytvára reťazec CSS. Uplatnia sa transformácie zodpovedajúce `lightningcss` v `_tailwindphp/LightningCss.php`, aby sa výstup zhodoval s tým, čo vytvorí TailwindCSS po prechode následného spracovania Rust.

**Minimalizácia.** Keď je povolené `minify`, `toCss()` počas serializácie vytvára minimalizované CSS. Samostatný priechod reťazcom `tw::minify()` zabezpečuje `_tailwindphp/CssMinifier.php`. Pozrite si časť [Ukladanie do vyrovnávacej pamäte a minimalizácia](https://tailwindphp.inline0.dev/sk/docs/advanced/caching).

## Usporiadanie zdrojových súborov

`src/` kopíruje usporiadanie TailwindCSS. Jediná štrukturálna zmena: TailwindCSS má súbor `utilities.ts` s viac než 6,000 riadkami, preto je kvôli jednoduchšej údržbe rozdelený do `src/utilities/`, pričom každá kategória má vlastný súbor.

```
src/
├── _tailwindphp/                # PHP-specific — NOT part of the TailwindCSS port
│   ├── LightningCss.php         # CSS transforms (lightningcss Rust library equivalent)
│   ├── CssMinifier.php          # CSS minification
│   └── lib/                     # Companion library ports (TailwindPHP\Lib\*)
│       ├── clsx/                # clsx port
│       ├── tailwind-merge/      # tailwind-merge port
│       └── cva/                 # CVA port
│
├── plugin/                      # Plugin system
│   └── plugins/
│       ├── typography-plugin.php  # @tailwindcss/typography port
│       └── forms-plugin.php       # @tailwindcss/forms port
│
├── utilities/                   # Split from TailwindCSS utilities.ts (one file per category)
│   ├── accessibility.php        # sr-only, forced-colors
│   ├── backgrounds.php          # bg-*, gradient-*, from-*, via-*, to-*
│   ├── borders.php              # border-*, rounded-*, divide-*, outline-*
│   ├── effects.php              # shadow-*, opacity-*, mix-blend-*
│   ├── filters.php              # blur-*, brightness-*, contrast-*, …
│   ├── flexbox.php              # flex-*, grid-*, gap-*, justify-*, align-*
│   ├── interactivity.php        # cursor-*, scroll-*, touch-*, select-*
│   ├── layout.php               # display, position, z-*, overflow-*, …
│   ├── masks.php                # mask-linear-*, mask-radial-*, mask-conic-*
│   ├── sizing.php               # w-*, h-*, min-*, max-*, size-*
│   ├── spacing.php              # m-*, p-*, space-*
│   ├── svg.php                  # fill-*, stroke-*
│   ├── tables.php               # border-collapse, table-layout
│   ├── transforms.php           # translate-*, rotate-*, scale-*, skew-*
│   ├── transitions.php          # transition-*, duration-*, ease-*, delay-*
│   └── typography.php           # font-*, text-*, leading-*, tracking-*
│
├── utils/                       # Helper functions (ported from utils/)
│
├── index.php                    # Main entry — compile(), cn(), variants(), merge(), join()
├── ast.php                      # AST nodes and toCss()
├── candidate.php                # Candidate parsing (class name → parts)
├── compile.php                  # Candidate to CSS compilation
├── css-functions.php            # theme(), --theme(), --spacing(), --alpha()
├── css-parser.php               # CSS parsing
├── design-system.php            # Central registry for utilities/variants
├── plugin.php                   # Plugin system (PluginInterface, PluginAPI, PluginManager)
├── theme.php                    # Theme value resolution
├── utilities.php                # Utility registration and lookup
├── value-parser.php             # CSS value parsing
├── variants.php                 # Variant handling (hover, focus, responsive, …)
└── walk.php                     # AST traversal
```

## Náhrada za lightningcss

TailwindCSS prenecháva následné spracovanie CSS — vnáranie, spracovanie mediálnych dotazov, zjednodušovanie hodnôt — nástroju [lightningcss](https://lightningcss.dev/), parseru, transformátoru a minifikátoru napísanému v Rust. PHP nedokáže načítať knižnicu Rust, preto `src/_tailwindphp/LightningCss.php` opätovne implementuje transformácie, na ktoré sa TailwindPHP skutočne spolieha, a pre prípady pokryté testovacou sadou vytvára výstup identický po bajtoch.

Potvrdené transformácie zahŕňajú:

| Transformácia | Čo robí |
|-----------|--------------|
| Zjednodušenie vnárania | Vyrieši selektory `&` pomocou pravidiel `:is(…)` referenčnej implementácie a sploští vnorené pravidlá (`handleNesting()` v `ast.php`, port priechodu TailwindCSS); `transformNesting` zníži úroveň zostávajúceho vnárania pod prvou úrovňou s deklaráciami |
| Sploštenie podmienených pravidiel at | Sploští vnorené `@media`, `@supports`, `@container` a `@starting-style` na mieste, zachová poradie v zdroji a zlúči iba priamo susediacich súrodencov s rovnakými podmienkami |
| Usporiadanie deklarácií | Usporiada deklarácie podľa reťazca obsluhy deklarácií v lightningcss, takže vlastnosti budú vo výstupnom poradí referenčnej implementácie (`reorderDeclarations`) |
| Zjednodušenie `calc()` | Zjednoduší výrazy `calc()` (`simplifyCalcExpressions`) |
| Odstránenie úvodných núl | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Medzery vo transformačných funkciách | Normalizuje medzery vo vnútri transformačných funkcií (`normalizeTransformFunctions`) |
| Normalizácia hodnôt mriežky | Pridá medzery okolo `/` v hodnotách span; zmení celé čísla bez jednotky na px pre `grid-template-*` (`normalizeGridValues`) |
| Normalizácia farieb | Normalizuje zápis farieb a vyhodnotí `color-mix()` na `oklab()` (`normalizeColors`, `evaluateColorMix`) |
| Zápis URL v úvodzovkách | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Predpony dodávateľov | Predpony zodpovedajúce Autoprefixer (`addVendorPrefixes`) |

Tento súbor je zámerne umiestnený do karantény pod `_tailwindphp/` a označený ako `@port-deviation:replacement` — zastupuje externú závislosť namiesto portovania zdrojového kódu TailwindCSS.

## Značky odchýlok portu

Každý implementačný súbor obsahuje v dokumentačnom bloku značky `@port-deviation:*`, ktoré uvádzajú, kde a prečo sa implementácia PHP odchyľuje od originálu TypeScript. Cieľom je, aby čitateľ pri porovnávaní PHP so zdrojovým kódom TailwindCSS nemusel hádať, či je rozdiel zámerný.

| Značka | Význam |
|--------|---------|
| `@port-deviation:none` | Priamy port 1:1 bez významných odchýlok |
| `@port-deviation:async` | PHP používa synchrónny kód namiesto async/await |
| `@port-deviation:storage` | Odlišné dátové štruktúry (pole PHP namiesto JS Map/Set) |
| `@port-deviation:types` | Anotácie PHPDoc namiesto typov TypeScript |
| `@port-deviation:sourcemaps` | Sledovanie source mapy sa vynecháva |
| `@port-deviation:enum` | Konštanty PHP namiesto enumerácií TypeScript |
| `@port-deviation:errors` | Odlišný spôsob spracovania chýb |
| `@port-deviation:replacement` | Implementácia PHP nahrádza externú knižnicu (e.g lightningcss) |
| `@port-deviation:helper` | Pomocná funkcia špecifická pre PHP, ktorá v origináli nie je |
| `@port-deviation:performance` | Optimalizácia špecifická pre PHP, ktorá zachováva identický výstup |
| `@port-deviation:omitted` | Celý modul alebo funkcia neboli portované (mimo rozsahu) |

Informácie o značkách `@port-deviation:performance` a o tom, ako sa vynucuje zhoda, nájdete v časti [Testovanie výkonu a testovanie](https://tailwindphp.inline0.dev/sk/docs/advanced/performance).