# Arhitektūra

TailwindPHP ir 1:1 ports. Koda bāze atspoguļo paša TailwindCSS struktūru — tie paši failu nosaukumi, tā pati organizācija — un nodala daļas, kuras *nevar* tieši pārnest (PHP nav Rust, nav V8), zem `src/_tailwindphp/`. Šajā lapā aplūkots kompilācijas konveijers, avota izkārtojums, `lightningcss` atkārtota ieviešana un konvencija, ko izmanto atšķirību dokumentēšanai.

## Darbplūsma

CSS ģenerēšana notiek vairākos posmos. Atsevišķa būvēšanas soļa nav — katrs `tw::generate()` izsaukums izpilda visu konveijeru.

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

**Parsēšana.** `css-parser.php` nolasa CSS ievadi — `@import`, `@theme`, `@utility`, `@layer`, neapstrādātus noteikumus — un izveido abstraktu sintakses koku no `ast.php` mezgliem (stila noteikumi, at-rule direktīvas, deklarācijas). Šajā posmā tiek atrisinātas un aizstātas `@import` direktīvas virtuālajiem moduļiem (`tailwindcss`, `tailwindcss/preflight`, …) un failu ceļi.

**Dizaina sistēmas izveide.** `theme.php` atrisina tēmas vērtības (krāsas, atstarpes, pārtraukuma punkti), izmantojot parsētos `@theme` blokus un noklusējuma vērtības. `design-system.php` ir centrālais reģistrs, kas sasaista tēmu ar utilītu un variantu meklēšanu, kas definēta `utilities.php` un `variants.php`.

**Satura skenēšana.** `candidate.php` izvelk klašu nosaukumu kandidātus no norādītā satura (HTML, veidnes) un sadala katru tā sastāvdaļās — bāzes utilīta, varianti, modifikatori, patvaļīgas vērtības, svarīguma karodziņš.

**Kompilēšana.** `compile.php` pārvērš katru kandidātu AST mezglos, meklējot to dizaina sistēmā un piemērojot tā variantus un modifikatorus. Kandidāti, kurus nevar atrisināt kā īstas utilītas, tiek atmesti.

**Serializēšana un optimizēšana.** `ast.php` `toCss()` šķērso koku (palīgfunkcijas atrodas `walk.php`) un izvada CSS virkni. Tiek piemērotas `_tailwindphp/LightningCss.php` transformācijas, kas ir ekvivalentas `lightningcss`, lai izvade atbilstu tam, ko izveido TailwindCSS pēc sava Rust pēcapstrādes posma.

**Minificēšana.** Ja `minify` ir iespējots, `toCss()` serializēšanas laikā izvada minificētu CSS. `_tailwindphp/CssMinifier.php` nodrošina atsevišķo `tw::minify()` virknes apstrādi. Skatiet [Kešatmiņa un minificēšana](https://tailwindphp.inline0.dev/lv/docs/advanced/caching).

## Avota izkārtojums

`src/` atspoguļo TailwindCSS. Vienīgā strukturālā izmaiņa: TailwindCSS `utilities.ts` ir 6,000+ rindu gara, tāpēc tā uzturēšanas ērtībai sadalīta `src/utilities/`, katrai kategorijai izveidojot atsevišķu failu.

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

TailwindCSS deleģē savu CSS pēcapstrādi — ligzdošanu, multivides vaicājumu apstrādi, vērtību vienkāršošanu — [lightningcss](https://lightningcss.dev/) — parserim, transformētājam un minificētājam, kas rakstīts Rust. PHP nevar ielādēt Rust bibliotēku, tāpēc `src/_tailwindphp/LightningCss.php` atkārtoti ievieš transformācijas, uz kurām faktiski paļaujas TailwindPHP, radot baitu līmenī identisku izvadi gadījumos, ko aptver testu kopa.

Apstiprinātās transformācijas ietver:

| Transformācija | Ko tā dara |
|-----------|--------------|
| Ligzdošanas saplacināšana | Atrisina `&` atlasītājus, izmantojot atsauces `:is(…)` noteikumus, un saplacina ligzdotos noteikumus (`handleNesting()` failā `ast.php`, TailwindCSS posma ports); `transformNesting` pazemina atlikušās ligzdošanas līmeni zem pirmā deklarācijas līmeņa |
| Nosacījumu at-rule direktīvu saplacināšana | Saplacina ligzdotās `@media`, `@supports`, `@container` un `@starting-style` vietā, saglabājot avota secību, un apvieno tikai tieši blakus esošus elementus ar identiskiem nosacījumiem |
| Deklarāciju secība | Pārkārto deklarācijas atbilstoši lightningcss deklarāciju apstrādes ķēdei, lai rekvizīti izvadē būtu atsauces secībā (`reorderDeclarations`) |
| `calc()` vienkāršošana | Vienkāršo `calc()` izteiksmes (`simplifyCalcExpressions`) |
| Sākuma nulles noņemšana | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Atstarpes transformācijas funkcijās | Normalizē atstarpes transformācijas funkcijās (`normalizeTransformFunctions`) |
| Režģa vērtību normalizēšana | Pievieno atstarpes ap `/` span vērtībās, veselus skaitļus bez vienībām pārvērš par px, ja izmantots `grid-template-*` (`normalizeGridValues`) |
| Krāsu normalizēšana | Normalizē krāsu sintaksi un aprēķina `color-mix()` līdz `oklab()` (`normalizeColors`, `evaluateColorMix`) |
| URL pēdiņas | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Piegādātāju prefiksi | Autoprefixer ekvivalenta prefiksu pievienošana (`addVendorPrefixes`) |

Šis fails apzināti ievietots karantīnā zem `_tailwindphp/` un marķēts kā `@port-deviation:replacement` — tas aizstāj ārēju atkarību, nevis pārnes TailwindCSS pirmkodu.

## Porta atšķirību marķieri

Katrā realizācijas failā docblock komentārā ir `@port-deviation:*` marķieri, kas norāda, kur un kāpēc PHP realizācija atšķiras no sākotnējās TypeScript versijas. Mērķis ir panākt, lai, salīdzinot PHP ar TailwindCSS pirmkodu, lasītājam nebūtu jāmin, vai atšķirība ir apzināta.

| Marķieris | Nozīme |
|--------|---------|
| `@port-deviation:none` | Tiešs 1:1 ports bez būtiskām atšķirībām |
| `@port-deviation:async` | PHP izmanto sinhrono kodu async/await vietā |
| `@port-deviation:storage` | Atšķirīgas datu struktūras (PHP masīvs, nevis JS Map/Set) |
| `@port-deviation:types` | PHPDoc anotācijas TypeScript tipu vietā |
| `@port-deviation:sourcemaps` | Avota kartes izsekošana izlaista |
| `@port-deviation:enum` | PHP konstantes TypeScript uzskaitījumu vietā |
| `@port-deviation:errors` | Atšķirīga kļūdu apstrādes pieeja |
| `@port-deviation:replacement` | PHP realizācija, kas aizstāj ārēju bibliotēku (e.g. lightningcss) |
| `@port-deviation:helper` | PHP specifisks palīgrīks, kura nav oriģinālā |
| `@port-deviation:performance` | PHP specifiska optimizācija, kas saglabā identisku izvadi |
| `@port-deviation:omitted` | Viss modulis/funkcionalitāte nav pārnesta (ārpus tvēruma) |

Informāciju par `@port-deviation:performance` marķieriem un to, kā tiek nodrošināta atbilstība, skatiet [Veiktspēja un testēšana](https://tailwindphp.inline0.dev/lv/docs/advanced/performance).