# Architektúra

Az TailwindPHP 1:1 arányú port. A kódbázis az TailwindCSS saját felépítését követi – azonos fájlnevek, azonos szervezés –, és külön kezeli azokat a részeket, amelyeket *nem lehet* közvetlenül átültetni (az PHP nem rendelkezik Rust-del és V8-del) az `src/_tailwindphp/` alatt. Ez az oldal bemutatja a fordítási folyamatot, a forráskód elrendezését, az `lightningcss` újraimplementálását és az eltérések dokumentálására használt konvenciót.

## A folyamat

Az CSS előállítása egymást követő szakaszokból áll. Nincs külön összeállítási lépés; az `tw::generate()` minden meghívása lefuttatja a teljes folyamatot.

```
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
```

**Feldolgozás.** Az `css-parser.php` beolvassa az CSS bemenetet – `@import`, `@theme`, `@utility`, `@layer`, nyers szabályok – és `ast.php` csomópontokból (stílusszabályok, at-szabályok, deklarációk) álló absztrakt szintaxisfát készít belőle. Ebben a szakaszban oldja fel és helyettesíti a virtuális modulokhoz tartozó `@import` direktívákat (`tailwindcss`, `tailwindcss/preflight`, …) és a fájlútvonalakat.

**A dizáj nrendszer felépítése.** Az `theme.php` feloldja a téma értékeit (színek, térközök, töréspontok) a feldolgozott `@theme` blokkok és az alapértelmezések alapján. Az `design-system.php` a központi nyilvántartás, amely összekapcsolja a témát az `utilities.php` és `variants.php` által definiált segédosztály- és változatkeresésekkel.

**A tartalom átvizsgálása.** Az `candidate.php` kinyeri a megadott tartalomból (HTML, sablonok) az osztálynevekre jelölt elemeket, majd részeikre bontja őket: alaposztály, változatok, módosítók, tetszőleges értékek és fontos jelölő.

**Fordítás.** Az `compile.php` dizájnrendszerbeli kereséssel, a változatok és módosítók alkalmazásával AST-csomópontokká alakítja az egyes jelölteket. Azokat a jelölteket elveti, amelyek nem valós segédosztályra oldódnak fel.

**Szerializálás és optimalizálás.** Az `ast.php` `toCss()` végigjárja a fát (a segédfüggvények az `walk.php` alatt találhatók), és előállítja az CSS karakterláncot. A `_tailwindphp/LightningCss.php` alatt az `lightningcss`-nek megfelelő átalakítások futnak le, hogy a kimenet megfeleljen annak, amit az TailwindCSS a Rust utófeldolgozási lépése után állít elő.

**Minimalizálás.** Ha az `minify` engedélyezve van, az `toCss()` szerializálás közben minimalizált CSS kimenetet állít elő. Az önálló `tw::minify()` karakterlánc-átalakítást az `_tailwindphp/CssMinifier.php` végzi. Lásd: [Gyorsítótárazás és minimalizálás](https://tailwindphp.inline0.dev/hu/docs/advanced/caching).

## Forráskód elrendezése

`src/` a TailwindCSS mintáját követi. Az egyetlen szerkezeti változás: TailwindCSS `utilities.ts` eleme 6,000+ soros, ezért a karbantarthatóság érdekében `src/utilities/` részre van bontva, kategóriánként egy fájllal.

```
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
```

## A lightningcss megfelelője

A TailwindCSS a CSS utófeldolgozását – beágyazás, média lekérdezések kezelése, értékek egyszerűsítése – a [lightningcss](https://lightningcss.dev/) végzi, amely Rust nyelven írt elemző, átalakító és tömörítő. A PHP nem tud Rust könyvtárat betölteni, ezért a `src/_tailwindphp/LightningCss.php` újra megvalósítja azokat az átalakításokat, amelyekre TailwindPHP ténylegesen támaszkodik; a tesztcsomag által lefedett esetekben bájtról bájtra azonos kimenetet ad.

Az igazolt átalakítások:

| Átalakítás | Működés |
|-----------|--------------|
| Beágyazások kilapítása | Feloldja a `&` szelektorokat a referencia `:is(…)` szabályai szerint, majd kilapítja a beágyazott szabályokat (`handleNesting()` a `ast.php` nyelven, a TailwindCSS lépés portja); a `transformNesting` alacsonyabb szintre alakítja az első deklarációt hordozó szint alatti beágyazásokat |
| Feltételes at-szabályok kilapítása | Helyben kilapítja a beágyazott `@media`, `@supports`, `@container` és `@starting-style` szabályokat, megőrzi a forrás sorrendjét, és csak az azonos feltételű, közvetlenül szomszédos testvéreket vonja össze |
| Deklarációk rendezése | A deklarációkat a lightningcss deklarációkezelő lánca szerint rendezi, így a tulajdonságok a referencia sorrendjében jelennek meg (`reorderDeclarations`) |
| `calc()` egyszerűsítése | Egyszerűsíti a `calc()` kifejezéseket (`simplifyCalcExpressions`) |
| Kezdő nullák eltávolítása | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Transzformációs függvények szóközei | Egységesíti a szóközöket a transzformációs függvényeken belül (`normalizeTransformFunctions`) |
| Rácsértékek normalizálása | Szóközöket tesz a `/` köré a span értékekben; a csupasz egész számokat px értékké alakítja a `grid-template-*` esetén (`normalizeGridValues`) |
| Színek normalizálása | Normalizálja a szintaxist, és `color-mix()` értékét `oklab()` formára számítja ki (`normalizeColors`, `evaluateColorMix`) |
| URL idézőjelezése | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Gyártóspecifikus előtagok | A Autoprefixer megfelelő előtagolás (`addVendorPrefixes`) |

Ez a fájl szándékosan a `_tailwindphp/` alá van elkülönítve, és `@port-deviation:replacement` jelölést kapott – külső függőséget helyettesít, nem a TailwindCSS forrásának portja.

## Porteltérések jelölései

Minden implementációs fájl dokumentációs blokkjában `@port-deviation:*` jelölések mutatják meg, hol és miért tér el a PHP implementáció a TypeScript eredetitől. Így a PHP és a TailwindCSS forrását összehasonlító olvasónak nem kell azon töprengenie, hogy szándékos-e az eltérés.

| Jelölés | Jelentés |
|--------|---------|
| `@port-deviation:none` | Közvetlen, 1:1 port, jelentős eltérések nélkül |
| `@port-deviation:async` | A PHP aszinkron kód helyett szinkron kódot használ |
| `@port-deviation:storage` | Eltérő adatszerkezetek (PHP tömb a JS Map/Set helyett) |
| `@port-deviation:types` | PHPDoc-megjegyzések TypeScript típusok helyett |
| `@port-deviation:sourcemaps` | A forrástérkép-követés kimaradt |
| `@port-deviation:enum` | PHP konstansok TypeScript felsorolások helyett |
| `@port-deviation:errors` | Eltérő hibakezelési megközelítés |
| `@port-deviation:replacement` | PHP implementáció váltja fel a külső könyvtárat (e.g. lightningcss) |
| `@port-deviation:helper` | PHP-specifikus, az eredetiben nem szereplő segédfüggvény |
| `@port-deviation:performance` | PHP-specifikus optimalizálás, amely megőrzi a kimenet azonosságát |
| `@port-deviation:omitted` | Teljes modul vagy funkció kimaradt a portból (nem tartozik a hatókörbe) |

A `@port-deviation:performance` jelölésekről és a paritás biztosításáról lásd a [Teljesítmény és tesztelés](https://tailwindphp.inline0.dev/hu/docs/advanced/performance) oldalt.