# Arhitektuur

TailwindPHP on 1:1 port. Koodibaas peegeldab TailwindCSS enda struktuuri — samad failinimed, sama korraldus — ja eraldab kataloogi `src/_tailwindphp/` need osad, mida *ei saa* otse portida (PHP-il pole Rust ega V8). Sellel lehel käsitletakse kompileerimistoru, lähtekoodi paigutust, `lightningcss` taasloomist ja kõrvalekallete dokumenteerimise tava.

## Töötlusahel

CSS loomine koosneb etappidest. Eraldi ehitusetappi pole – iga `tw::generate()` kutse käivitab kogu töövoo.

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

**Parsimine.** `css-parser.php` loeb sisendiks antud CSS-i – `@import`, `@theme`, `@utility`, `@layer` ja toorreeglid – ning loob abstraktse süntaksipuu, mis koosneb `ast.php` sõlmedest (stiilireeglid, at-reeglid ja deklaratsioonid). Selles etapis lahendatakse ja asendatakse virtuaalmoodulite `@import` direktiivid (`tailwindcss`, `tailwindcss/preflight`, …) ning failiteed.

**Disainisüsteemi loomine.** `theme.php` lahendab teemaväärtused (värvid, vahed ja murdepunktid) parsitud `@theme` plokkide ja vaikeväärtuste põhjal. `design-system.php` on keskne register, mis seob teema utiliitide ja variantide otsingutega, mis on määratletud failides `utilities.php` ja `variants.php`.

**Sisu skannimine.** `candidate.php` eraldab etteantud sisust (HTML, mallid) võimalike klassinimede kandidaadid ja parsib igaühe osadeks: põhiutiliit, variandid, muutjad, suvalised väärtused ja olulisuse lipp.

**Kompileerimine.** `compile.php` teisendab iga kandidaadi AST-sõlmedeks, otsides selle disainisüsteemist ning rakendades variante ja muutjaid. Kandidaadid, mis ei vasta ühelegi päriselt olemasolevale utiliidile, jäetakse kõrvale.

**Serialiseerimine ja optimeerimine.** `ast.php` `toCss()` läbib puu (abifunktsioonid asuvad failis `walk.php`) ja väljastab CSS-stringi. Rakendatakse `lightningcss`-iga samaväärseid teisendusi kataloogis `_tailwindphp/LightningCss.php`, et väljund vastaks sellele, mida TailwindCSS toodab pärast Rust järeltöötlusetappi.

**Vähendamine.** Kui `minify` on lubatud, väljastab `toCss()` serialiseerimise ajal vähendatud CSS-i. Eraldiseisvat `tw::minify()`-stringi etappi toetab `_tailwindphp/CssMinifier.php`. Vt [Vahemällu salvestamine ja vähendamine](https://tailwindphp.inline0.dev/et/docs/advanced/caching).

## Lähtekoodi paigutus

`src/` järgib TailwindCSS ülesehitust. Ainus struktuurimuudatus: TailwindCSS failis `utilities.ts` on üle 6,000 rea, seega on see hooldatavuse huvides jagatud kategooriate kaupa failideks `src/utilities/`.

```
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-i samaväärne teostus

TailwindCSS delegeerib oma CSS järeltöötluse – pesastamise, meediapäringute käsitlemise ja väärtuste lihtsustamise – teegile [lightningcss](https://lightningcss.dev/), mis on keeles Rust kirjutatud parser, teisendaja ja vähendaja. PHP ei saa laadida Rust teeki, seega taasloob `src/_tailwindphp/LightningCss.php` teisendused, millele TailwindPHP tegelikult toetub, ning väljastab testikomplektiga kaetud juhtudel baiditäpselt sama tulemuse.

Kinnitatud teisendused hõlmavad järgmist:

| Teisendus | Mida see teeb |
|-----------|--------------|
| Pesastuse tasandamine | Lahendab `&` selektorid viite `:is(…)` reeglitega ja tasandab pesastatud reeglid (`handleNesting()` failis `ast.php`, TailwindCSS läbimise port); `transformNesting` alandab esimese deklaratsioone sisaldava taseme alla jääva pesastuse |
| Tingimuslike at-reeglite tasandamine | Tasandab pesastatud `@media`, `@supports`, `@container` ja `@starting-style` oma asukohas, säilitades lähtekoodi järjekorra, ning ühendab ainult vahetult kõrvuti asuvad identsete tingimustega õedreeglid |
| Deklaratsioonide järjestamine | Järjestab deklaratsioonid lightningcss-i deklaratsioonikäsitlejate ahela järgi, et omadused ilmuksid viitega samas järjekorras (`reorderDeclarations`) |
| `calc()` lihtsustamine | Lihtsustab `calc()` avaldisi (`simplifyCalcExpressions`) |
| Eesoleva nulli eemaldamine | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Teisendusfunktsioonide tühikud | Normaliseerib tühikud teisendusfunktsioonides (`normalizeTransformFunctions`) |
| Ruudustikuväärtuste normaliseerimine | Lisab span-väärtustes `/` ümber tühikud, muudab paljad täisarvud px-ühikusse `grid-template-*` jaoks (`normalizeGridValues`) |
| Värvide normaliseerimine | Normaliseerib värvisüntaksi ja arvutab `color-mix()` väärtuseks `oklab()` (`normalizeColors`, `evaluateColorMix`) |
| URL jutumärgid | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Tootjaprefiksid | Autoprefixer-iga samaväärne prefiksite lisamine (`addVendorPrefixes`) |

See fail on tahtlikult paigutatud eraldatult kataloogi `_tailwindphp/` ja märgitud `@port-deviation:replacement` — see tähistab välist sõltuvust, mitte TailwindCSS lähtekoodi porti.

## Pordierinevuste markerid

Iga teostusfaili dokumendiplokis on `@port-deviation:*` markerid, mis selgitavad, kus ja miks PHP teostus erineb TypeScript algsest. Eesmärk on, et lugeja ei peaks PHP ja TailwindCSS lähtekoodi võrreldes kunagi mõtlema, kas erinevus on tahtlik.

| Marker | Tähendus |
|--------|---------|
| `@port-deviation:none` | Otsene 1:1 port ilma oluliste erinevusteta |
| `@port-deviation:async` | PHP kasutab async/await asemel sünkroonset koodi |
| `@port-deviation:storage` | Erinevad andmestruktuurid (PHP massiiv võrreldes JS Map/Set-iga) |
| `@port-deviation:types` | TypeScript tüüpide asemel PHPDoc-i annotatsioonid |
| `@port-deviation:sourcemaps` | Lähtekaardi jälgimine on välja jäetud |
| `@port-deviation:enum` | PHP konstandid TypeScript enumite asemel |
| `@port-deviation:errors` | Teistsugune vigade käsitlemise viis |
| `@port-deviation:replacement` | PHP teostus asendab välise teegi (e.g. lightningcss) |
| `@port-deviation:helper` | Ainult PHP jaoks mõeldud abifunktsioon, mida algses versioonis pole |
| `@port-deviation:performance` | Ainult PHP jaoks mõeldud optimeerimine, mis säilitab identse väljundi |
| `@port-deviation:omitted` | Kogu moodul või funktsioon pole porditud (ei kuulu töö ulatusse) |

`@port-deviation:performance` markerite ja paarsuse tagamise kohta leiate teavet jaotisest [Jõudlus ja testimine](https://tailwindphp.inline0.dev/et/docs/advanced/performance).