# Tailwind CSS 3.3.2 Entegrasyonu

TYPO3 v13 projesi için Tailwind CSS 3.3.2 kurulum ve kullanım rehberi.

## Genel Bakış

Bu proje, **Tailwind CSS 3.3.2** kullanarak modern ve responsive tasarımlar oluşturmanıza olanak sağlar. Tailwind v3.3.2, kararlı ve geniş kullanıma sahip bir sürümdür:

- **JIT (Just-In-Time) Engine**: Sadece kullanılan class'ları derler
- **tailwind.config.js**: JavaScript-based konfigürasyon
- **@tailwind direktifleri**: CSS içinde `@tailwind base/components/utilities`
- **Content yapılandırması**: Hangi dosyaların taranacağını belirtme

## Dosya Yapısı

```
typo3v13/
├── tailwind.config.js        # Tailwind konfigürasyonu (content paths, theme)
├── package.json              # npm yapılandırması ve build scripts
├── public/
│   └── assets/
│       └── css/
│           ├── input.css     # Tailwind kaynak CSS (@tailwind direktifleri)
│           └── output.css    # Derlenmiş çıktı (Git'e commit edilir)
└── packages/
    └── */Resources/Private/  # Fluid template'ler (Tailwind burada ki class'ları tarar)
```

## Kurulum

### 1. Bağımlılıkları Yükleyin

```bash
cd packages/my_site_package
npm install
```

### 2. Build Komutları

**Geliştirme (Watch Mode):**

```bash
npm run dev
```

Bu komut dosya değişikliklerini izler ve otomatik olarak CSS'i yeniden derler.

**Production Build:**

```bash
npm run build
```

Bu komut minified (küçültülmüş) CSS çıktısı üretir.

## Kaynak CSS Konfigürasyonu

`src/input.css` dosyası Tailwind v4 konfigürasyonunu içerir:

### Import ve Content Detection

```css
@import "tailwindcss";

/* Content Sources - Tailwind bu path'lerdeki utility class'ları tarar */
@source "../Resources/Private/**/*.html";
@source "../ContentBlocks/**/*.html";

@custom-variant dark (&:where(.dark, .dark *));
```

> [!IMPORTANT]
> **@source direktifi zorunludur!**
>
> Tailwind v4, utility class'ları otomatik olarak taramak için `@source` direktifine ihtiyaç duyar. Bu olmadan, template'lerdeki class'lar derlenmez ve CSS'e eklenmez.

### Tema Konfigürasyonu

```css
@theme {
  /* Breakpoints */
  --breakpoint-sm: 540px;
  --breakpoint-md: 720px;
  --breakpoint-lg: 960px;
  --breakpoint-xl: 1140px;
  --breakpoint-2xl: 1320px;

  /* Renkler */
  --color-primary: #3758f9;
  --color-secondary: #13c296;
  --color-dark: #111928;
  /* ... diğer renkler */

  /* Gölgeler */
  --shadow-1: 0px 1px 3px 0px rgba(166, 175, 195, 0.4);
  /* ... diğer gölgeler */
}
```

### Base Stiller

```css
@layer base {
  body {
    font-family: "Inter", sans-serif;
  }
}
```

### Component Stiller

Custom component stilleri için `@apply` direktifini kullanabilirsiniz:

```css
.sticky {
  @apply fixed transition z-9999 bg-white/80 dark:bg-dark/80;
  backdrop-filter: blur(5px);
}
```

## TYPO3 Entegrasyonu

### TypoScript ile CSS Dahil Etme

`Configuration/TypoScript/setup.typoscript` dosyasında:

```typoscript
page.includeCSS {
  tailwind = EXT:my_site_package/Resources/Public/Css/tailwind.css
}
```

### Fluid Template'lerde Kullanım

```html
<div class="container mx-auto px-4">
  <h1 class="text-4xl font-bold text-dark dark:text-white">Başlık</h1>
  <p class="text-body-color mt-4">İçerik metni</p>
</div>
```

## Tema Renkleri

| Değişken             | Değer   | Kullanım                  |
| -------------------- | ------- | ------------------------- |
| `--color-primary`    | #3758f9 | Ana marka rengi, butonlar |
| `--color-secondary`  | #13c296 | İkincil aksiyonlar        |
| `--color-dark`       | #111928 | Koyu arka plan            |
| `--color-body-color` | #637381 | Metin rengi               |
| `--color-stroke`     | #dfe4ea | Kenar çizgileri           |

## Dark Mode

Dark mode `class` stratejisi ile çalışır. HTML elementine `.dark` class'ı ekleyerek aktifleştirilir:

```html
<html class="dark">
  <!-- dark mode aktif -->
</html>
```

Fluid template'lerde:

```html
<div class="bg-white dark:bg-dark text-dark dark:text-white">
  <!-- Hem light hem dark mode için stiller -->
</div>
```

## Responsive Tasarım

Özel breakpoint'ler tanımlanmıştır:

| Breakpoint | Genişlik | Prefix |
| ---------- | -------- | ------ |
| sm         | 540px    | `sm:`  |
| md         | 720px    | `md:`  |
| lg         | 960px    | `lg:`  |
| xl         | 1140px   | `xl:`  |
| 2xl        | 1320px   | `2xl:` |

Örnek kullanım:

```html
<div class="w-full md:w-1/2 lg:w-1/3">
  <!-- Mobilde tam genişlik, tablette yarım, masaüstünde 1/3 -->
</div>
```

## Geliştirme Workflow'u

1. Terminal açın ve site package dizinine gidin
2. `npm run dev` ile watch mode başlatın
3. `src/input.css` veya Fluid template'leri düzenleyin
4. Değişiklikler otomatik olarak derlenir
5. Tarayıcıyı yenileyin ve değişiklikleri görün

## Best Practices

1. **Utility-first yaklaşımı** kullanın - önce utility class'larla başlayın
2. **Custom component stilleri** için `@layer components` ve `@apply` kullanın
3. **Tema değerlerini** CSS variables üzerinden kullanın
4. **Production'da** minified build kullanın
5. **Derlenmiş CSS'i** Git'e commit edin (Docker/DDEV ortamında npm olmayabilir)

## Sorun Giderme

### Build Hatası

```bash
# Node.js bağımlılıklarını temizleyin ve yeniden yükleyin
rm -rf node_modules package-lock.json
npm install
```

### CSS Güncellenmiyor

1. Watch mode'un çalıştığından emin olun (`npm run dev`)
2. TYPO3 cache'ini temizleyin: `ddev typo3 cache:flush`
3. Tarayıcı cache'ini temizleyin (Ctrl+Shift+R)

### Class'lar Çalışmıyor

1. HTML dosyalarının content path'inde olduğundan emin olun
2. Tailwind, kullanılmayan class'ları otomatik olarak çıkarır
3. `src/input.css` dosyasını kontrol edin

### CSS 404 Hatası (DDEV)

TYPO3, `public/_assets/` dizininde extension'ların `Resources/Public` klasörlerine symlink oluşturur. `packages/` klasöründeki local extension'lar için bu symlink otomatik oluşmayabilir.

**Çözüm:**

```bash
ddev exec "cd /var/www/html/public/_assets && ln -sf ../../packages/my_site_package/Resources/Public <hash>"
```

Hash değerini browser DevTools'tan veya TYPO3 loglarından öğrenebilirsiniz.

## Error Sayfası Entegrasyonu

Error sayfaları (404, 403, 500) için Tailwind CSS kullanmak istiyorsanız, standalone template oluşturmanız gerekir çünkü error handler ayrı bir context'te çalışır.

### Error Template Örneği

`Resources/Private/Templates/Sites/Error.html`:

```html
<html
  xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
  data-namespace-typo3-fluid="true"
>
  <!DOCTYPE html>
  <html lang="tr">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>{statusCode} - Hata</title>

      <!-- Tailwind CSS doğrudan dahil edilmeli -->
      <link
        rel="stylesheet"
        href="{f:uri.resource(path: 'Css/tailwind.css', extensionName: 'my_site_package')}"
      />
    </head>
    <body class="bg-gray-50 min-h-screen flex items-center justify-center">
      <div class="container mx-auto px-4 py-16 text-center">
        <h1 class="text-8xl font-bold text-primary mb-4">{statusCode}</h1>
        <h2 class="text-2xl text-gray-700 mb-8">{reasonText}</h2>
        <a href="/" class="px-8 py-4 bg-primary text-white rounded-lg">
          Ana Sayfaya Dön
        </a>
      </div>
    </body>
  </html>
</html>
```

> [!NOTE]
> Error template'lerde `f:uri.resource` ViewHelper'ı kullanarak CSS'i doğrudan `<head>` içine dahil edin. Layout kullanmak sorunlara yol açabilir.
