# Architektūra

TailwindPHP yra tikslus 1:1 perkėlimas. Kodų bazė atkartoja pačios TailwindCSS struktūrą – tie patys failų pavadinimai ir išdėstymas. Dalys, kurių *neįmanoma* tiesiogiai perkelti (PHP neturi Rust ar V8), atskirtos į `src/_tailwindphp/`. Šiame puslapyje aprašomi kompiliavimo konvejeris, šaltinio kodų išdėstymas, `lightningcss` realizacija ir nukrypimų dokumentavimo tvarka.

## Proceso eiga

CSS generavimas vyksta keliais etapais. Atskiro kūrimo žingsnio nėra – kiekvienas `tw::generate()` iškvietimas vykdo visą konvejerį.

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

**Analizavimas.** `css-parser.php` analizuoja CSS įvestį – `@import`, `@theme`, `@utility`, `@layer` ir neapdorotas taisykles – į `ast.php` mazgų abstrakčią sintaksės medį (stiliaus taisykles, at taisykles ir deklaracijas). Šiame etape išsprendžiamos ir pakeičiamos `@import` direktyvos, skirtos virtualiems moduliams (`tailwindcss`, `tailwindcss/preflight`, …), bei failų keliai.

**Dizaino sistemos kūrimas.** `theme.php` išanalizuotuose `@theme` blokuose ir numatytosiose reikšmėse suranda temos reikšmes (spalvas, tarpus, lūžio taškus). `design-system.php` yra centrinis registras, susiejantis temą su `utilities.php` ir `variants.php` apibrėžtomis utilitų bei variantų paieškomis.

**Turinio nuskaitymas.** `candidate.php` pateiktame turinyje (HTML, šablonuose) aptinka galimus klasių pavadinimus ir išskaido kiekvieną į dalis: bazinį utilitą, variantus, modifikatorius, savavališkas reikšmes ir svarbos žymą.

**Kompiliavimas.** `compile.php` kiekvieną galimą kandidatą paverčia AST mazgais, ieškodama jo dizaino sistemoje ir pritaikydama variantus bei modifikatorius. Kandidatai, neatitinkantys realaus utilito, atmetami.

**Serializavimas ir optimizavimas.** `ast.php` `toCss()` pereina medį (naudodama pagalbines funkcijas iš `walk.php`) ir išveda CSS eilutę. Taikomos `_tailwindphp/LightningCss.php` esančios transformacijos, atitinkančios `lightningcss`, kad išvestis sutaptų su ta, kurią TailwindCSS sukuria po Rust papildomo apdorojimo etapo.

**Minifikavimas.** Įjungus `minify`, `toCss()` serializavimo metu išveda minifikuotą CSS. Savarankišką `tw::minify()` eilutės apdorojimą atlieka `_tailwindphp/CssMinifier.php`. Žr. [Spartinimas talpykloje ir minifikavimas](https://tailwindphp.inline0.dev/lt/docs/advanced/caching).

## Šaltinio kodo išdėstymas

`src/` atkartoja TailwindCSS. Vienintelis struktūrinis pakeitimas: TailwindCSS `utilities.ts` yra 6,000+ eilučių, todėl priežiūros patogumui jis suskaidytas į `src/utilities/` – po vieną failą kiekvienai kategorijai.

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

## lightningcss atitikmuo

TailwindCSS CSS papildomą apdorojimą – įdėjimą, medijos užklausų tvarkymą ir reikšmių supaprastinimą – patiki [lightningcss](https://lightningcss.dev/), analizatoriui, transformatoriui ir minifikatoriui, parašytam Rust kalba. PHP negali įkelti Rust bibliotekos, todėl `src/_tailwindphp/LightningCss.php` iš naujo realizuoja transformacijas, kuriomis iš tiesų remiasi TailwindPHP; testų rinkinio aprėpiamais atvejais išvestis sutampa baitas į baitą.

Patvirtintos transformacijos:

| Transformacija | Ką ji daro |
|-----------|--------------|
| Įdėjimo išskleidimas | Išsprendžia `&` selektorius pagal nuorodos `:is(…)` taisykles ir išskleidžia įdėtines taisykles (`handleNesting()` faile `ast.php`, TailwindCSS etapo perkėlimas); `transformNesting` išskleidžia po pirmojo deklaracijas turinčio lygmens likusį įdėjimą |
| Sąlyginių at taisyklių išskleidimas | Vietoje išskleidžia įdėtines `@media`, `@supports`, `@container` ir `@starting-style`, išlaikydamas pradinę tvarką; sujungiami tik tiesiogiai greta esantys vienodų sąlygų elementai |
| Deklaracijų tvarka | Deklaracijos perrikiuojamos pagal lightningcss deklaracijų tvarkyklės grandinę, todėl savybės išvedamos tokia tvarka kaip nuorodoje (`reorderDeclarations`) |
| `calc()` supaprastinimas | Supaprastinamos `calc()` išraiškos (`simplifyCalcExpressions`) |
| Nulių pradžioje šalinimas | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Tarpai transformavimo funkcijose | Normalizuojami tarpai transformavimo funkcijų viduje (`normalizeTransformFunctions`) |
| Tinklelio reikšmių normalizavimas | Tarp reikšmių su `/` pridedami tarpai, o sveikieji skaičiai be vienetų paverčiami px, kai naudojamas `grid-template-*` (`normalizeGridValues`) |
| Spalvų normalizavimas | Normalizuojama spalvų sintaksė, o `color-mix()` apskaičiuojama į `oklab()` (`normalizeColors`, `evaluateColorMix`) |
| URL kabutės | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Tiekėjo prefiksai | Autoprefixer atitinkantis prefiksų pridėjimas (`addVendorPrefixes`) |

Šis failas sąmoningai laikomas `_tailwindphp/` ir pažymėtas `@port-deviation:replacement` – jis atstoja išorinę priklausomybę, o ne perkelia TailwindCSS šaltinio kodą.

## Perkėlimo nukrypimų žymos

Kiekvieno realizacijos failo dokumentacijos bloke yra `@port-deviation:*` žymos, nurodančios, kur ir kodėl PHP realizacija skiriasi nuo pradinės TypeScript versijos. Lyginant PHP su TailwindCSS šaltinio kodu, neturi kilti abejonių, ar skirtumas atsirado tyčia.

| Žyma | Reikšmė |
|--------|---------|
| `@port-deviation:none` | Tiesioginis 1:1 perkėlimas be reikšmingų nukrypimų |
| `@port-deviation:async` | PHP vietoj async/await naudoja sinchroninį kodą |
| `@port-deviation:storage` | Skirtingos duomenų struktūros (PHP masyvas, o JS Map/Set) |
| `@port-deviation:types` | Vietoj TypeScript tipų naudojamos PHPDoc anotacijos |
| `@port-deviation:sourcemaps` | Šaltinio žemėlapio sekimas praleistas |
| `@port-deviation:enum` | Vietoj TypeScript išvardijimų naudojamos PHP konstantos |
| `@port-deviation:errors` | Kitoks klaidų tvarkymo būdas |
| `@port-deviation:replacement` | PHP realizacija pakeičia išorinę biblioteką (e.g. lightningcss) |
| `@port-deviation:helper` | Tik PHP skirtas pagalbinis įrankis, kurio nėra pradinėje versijoje |
| `@port-deviation:performance` | Tik PHP skirta optimizacija, išlaikanti identišką išvestį |
| `@port-deviation:omitted` | Visas modulis arba funkcija neperkelta (nepatenka į apimtį) |

Apie `@port-deviation:performance` žymas ir pariteto užtikrinimą skaitykite skiltyje [Našumas ir testavimas](https://tailwindphp.inline0.dev/lt/docs/advanced/performance).