# Mimari

TailwindPHP bir 1:1 uyarlamasıdır. Kod tabanı, TailwindCSS'ın kendi yapısını (aynı dosya adları ve aynı düzenleme) izler; doğrudan uyarlanması *mümkün olmayan* kısımları (PHP'te Rust ve V8 yoktur) `src/_tailwindphp/` altında ayrı tutar. Bu sayfada derleme hattı, kaynak düzeni, `lightningcss` uygulaması ve farklılıkları belgeleme yaklaşımı anlatılır.

## İşlem hattı

CSS üretimi bir aşamalar dizisinden oluşur. Ayrı bir derleme adımı yoktur; `tw::generate()` için yapılan her çağrı tüm hattı çalıştırır.

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

**Ayrıştırma.** `css-parser.php`, CSS girdisini — `@import`, `@theme`, `@utility`, `@layer` ve ham kuralları — `ast.php` düğümlerinden oluşan bir soyut sözdizimi ağacına (stil kuralları, at kuralları, bildirimler) dönüştürür. Sanal modüller (`tailwindcss`, `tailwindcss/preflight`, …) için `@import` yönergeleri ve dosya yolları bu aşamada çözümlenip yerine konur.

**Tasarım sistemini oluşturma.** `theme.php`, ayrıştırılmış `@theme` bloklarından ve varsayılanlardan tema değerlerini (renkler, boşluklar, kesme noktaları) çözümler. `design-system.php`, temayı `utilities.php` ve `variants.php` içinde tanımlanan yardımcı sınıf ve varyant aramalarıyla ilişkilendiren merkezi kayıt defteridir.

**İçeriği tarama.** `candidate.php`, sağlanan içerikten (HTML, şablonlar) sınıf adı adaylarını çıkarır ve her birini bileşenlerine ayırır: temel yardımcı sınıf, varyantlar, değiştiriciler, keyfî değerler ve important işareti.

**Derleme.** `compile.php`, her adayı tasarım sisteminde arayıp varyantlarını ve değiştiricilerini uygulayarak AST düğümlerine dönüştürür. Gerçek bir yardımcı sınıfa karşılık gelmeyen adaylar atılır.

**Serileştirme ve optimizasyon.** `ast.php` öğesinin `toCss()` bileşeni ağacı dolaşır (`walk.php` içindeki yardımcılarla) ve CSS dizgesini üretir. Çıktının, TailwindCSS tarafından Rust son işleme aşamasından sonra üretilenle eşleşmesi için `_tailwindphp/LightningCss.php` içindeki `lightningcss` eşdeğeri dönüşümler uygulanır.

**Küçültme.** `minify` etkinleştirildiğinde `toCss()`, serileştirme sırasında küçültülmüş CSS üretir. Bağımsız `tw::minify()` dize aşamasını `_tailwindphp/CssMinifier.php` sağlar. Bkz. [Önbelleğe alma ve küçültme](https://tailwindphp.inline0.dev/tr/docs/advanced/caching).

## Kaynak düzeni

`src/`, TailwindCSS yapısını yansıtır. Tek yapısal değişiklik şu: TailwindCSS öğesinin `utilities.ts` bölümü 6,000 satırı aştığından, sürdürülebilirlik için her kategoriye bir dosya düşecek şekilde `src/utilities/` dosyasına ayrılmıştır.

```
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 karşılığı

TailwindCSS, iç içe yerleştirme, medya sorgusu işleme ve değer basitleştirme gibi CSS son işleme görevlerini [lightningcss](https://lightningcss.dev/)'e devreder; bu, Rust ile yazılmış bir ayrıştırıcı/dönüştürücü/küçültücüdür. PHP, Rust kitaplığını yükleyemediğinden, `src/_tailwindphp/LightningCss.php`, TailwindPHP'in gerçekten kullandığı dönüşümleri yeniden uygular ve test paketinin kapsadığı durumlarda bayt bayt aynı çıktıyı üretir.

Doğrulanan dönüşümler şunlardır:

| Dönüşüm | Yaptığı iş |
|-----------|--------------|
| İç içe yerleştirmeyi düzleştirme | `ast.php` içindeki başvuru `:is(…)` kurallarına göre `&` seçicilerini çözümler ve iç içe kuralları düzleştirir (TailwindCSS geçişinin bir uyarlaması olan `handleNesting()`); `transformNesting`, bildirim taşıyan ilk düzeyin altında kalan iç içe yerleştirmeyi alt düzeylere dönüştürür |
| Koşullu at kurallarını düzleştirme | İç içe `@media`, `@supports`, `@container` ve `@starting-style` kurallarını kaynak sırasını koruyarak yerinde düzleştirir ve yalnızca koşulları aynı olan, doğrudan bitişik kardeşleri birleştirir |
| Bildirim sıralaması | Özelliklerin başvurudaki sırayla çıkması için bildirimleri lightningcss bildirim işleyicisi zincirine göre yeniden sıralar (`reorderDeclarations`) |
| `calc()` basitleştirmesi | `calc()` ifadelerini basitleştirir (`simplifyCalcExpressions`) |
| Baştaki sıfırı kaldırma | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Dönüştürme işlevlerinde boşluk | Dönüştürme işlevlerinin içindeki boşlukları normalleştirir (`normalizeTransformFunctions`) |
| Grid değerlerini normalleştirme | Aralık değerlerindeki `/` çevresine boşluk ekler; `grid-template-*` için yalın tamsayıları px'e dönüştürür (`normalizeGridValues`) |
| Renkleri normalleştirme | Renk söz dizimini normalleştirir ve `color-mix()` değerini `oklab()` olarak değerlendirir (`normalizeColors`, `evaluateColorMix`) |
| URL tırnaklama | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Üretici önekleri | Autoprefixer eşdeğeri önek ekleme (`addVendorPrefixes`) |

Bu dosya bilerek `_tailwindphp/` altında karantinaya alınmış ve `@port-deviation:replacement` olarak işaretlenmiştir — TailwindCSS kaynak kodunu uyarlamak yerine harici bir bağımlılığı temsil eder.

## Uyarlama sapması işaretleri

Her uygulama dosyasının belge bloğunda, PHP uygulamasının TypeScript özgün sürümünden nerede ve neden ayrıldığını belirten `@port-deviation:*` işaretleri bulunur. Amaç, PHP ile TailwindCSS kaynak kodunu karşılaştıran okuyucunun bir farkın kasıtlı olup olmadığını sorgulamak zorunda kalmamasıdır.

| İşaret | Anlamı |
|--------|---------|
| `@port-deviation:none` | Önemli bir sapma olmadan doğrudan 1:1 uyarlaması |
| `@port-deviation:async` | PHP, async/await yerine eşzamanlı kod kullanır |
| `@port-deviation:storage` | Farklı veri yapıları (PHP dizisi, JS Map/Set) |
| `@port-deviation:types` | TypeScript türleri yerine PHPDoc açıklamaları |
| `@port-deviation:sourcemaps` | Kaynak haritası takibi yoktur |
| `@port-deviation:enum` | PHP sabitleri, TypeScript enum'ları yerine kullanılır |
| `@port-deviation:errors` | Farklı hata işleme yaklaşımı |
| `@port-deviation:replacement` | Harici kitaplığın yerine geçen PHP uygulaması (e.g. lightningcss) |
| `@port-deviation:helper` | Özgün sürümde bulunmayan, PHP'e özgü yardımcı |
| `@port-deviation:performance` | Özdeş çıktıyı koruyan, PHP'e özgü optimizasyon |
| `@port-deviation:omitted` | Modülün/özelliğin tamamı uyarlanmamıştır (kapsam dışı) |

`@port-deviation:performance` işaretleri ve eşdeğerliğin nasıl sağlandığı için bkz. [Performans ve test](https://tailwindphp.inline0.dev/tr/docs/advanced/performance).