
# Tailwind CSS

Blockstudio menyertakan dukungan bawaan untuk Tailwind CSS v4. Saat diaktifkan, setiap halaman frontend dikompilasi di sisi server melalui [TailwindPHP](https://github.com/dnnsjsk/tailwindphp) dengan caching berbasis file otomatis. Di editor blok, skrip Tailwind CDN yang dibundel menyediakan pratinjau langsung saat Anda mengedit.

Tanpa langkah build, tanpa CLI, tanpa Node.js yang diperlukan.

## Cara Kerjanya

Blockstudio menggunakan dua strategi kompilasi terpisah bergantung pada konteksnya:

### Frontend (Sisi Server)

Pada setiap permintaan frontend, Blockstudio menangkap HTML halaman lengkap melalui buffer output, mengekstrak semua kandidat kelas CSS, hanya mengompilasi CSS yang benar-benar digunakan, lalu menyisipkan hasilnya sebagai tag `<style>` sebaris sebelum `</head>`.

Alur kompilasi:

1. WordPress merender seluruh HTML halaman ke dalam buffer output
2. `TailwindPHP::extractCandidates()` memindai HTML dan mengekstrak semua kandidat nama kelas CSS potensial (regex cepat, tanpa kompilasi)
3. Kandidat yang diurutkan di-hash bersama konfigurasi CSS untuk membuat kunci cache
4. Saat **cache hit**: CSS hasil kompilasi dibaca dari disk dan disisipkan
5. Saat **cache miss**: `TailwindPHP::generate()` mengompilasi CSS, menulisnya ke direktori cache, lalu menyisipkannya

CSS hasil kompilasi disisipkan sebagai berikut:

```html
<style id="blockstudio-tailwind">
  /* compiled CSS */
</style>
```

Ini mencakup preflight Tailwind (reset CSS) dan semua kelas utilitas yang cocok.

### Editor (Sisi Klien)

Di dalam editor blok, skrip Tailwind CDN yang dibundel (build browser dari Tailwind CSS v4) berjalan di sisi klien. Skrip ini menyediakan pratinjau langsung seketika saat Anda mengetik nama kelas, tanpa bolak-balik ke server. CDN hanya dimuat di editor dan tidak pernah disajikan di frontend.

Saat `assets.reset.enabled` aktif, Blockstudio juga memulihkan utilitas tampilan dan posisi umum milik Tailwind di dalam kanvas editor. Ini mencegah kelas tingkat wrapper seperti `flex`, `grid`, `absolute`, `fixed`, dan `sticky` ditimpa oleh aturan wrapper blok editor WordPress, sehingga tata letak berbasis utilitas lebih sesuai dengan frontend.

## Mengaktifkan Tailwind

Tambahkan konfigurasi `tailwind` ke `blockstudio.json` Anda:

```json title="blockstudio.json"
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true
  }
}
```

Atau aktifkan melalui filter:

```php title="functions.php"
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
```

Saat `enabled` bernilai `true`, setiap halaman frontend akan memiliki Tailwind CSS yang dikompilasi dan disisipkan secara otomatis. Anda dapat menggunakan kelas utilitas Tailwind di mana saja: dalam templat blok, templat tema, filter `the_content`, atau HTML apa pun yang muncul di output halaman.

### Output frontend

CSS hasil kompilasi disisipkan sebaris secara default, sehingga mempertahankan output yang digunakan versi sebelumnya. Situs dengan banyak aturan bersama dapat memilih stylesheet dengan hash konten:

```json title="blockstudio.json"
{
  "tailwind": {
    "enabled": true,
    "output": "link"
  }
}
```

`"output": "link"` mengeluarkan file cache `tailwind/{content-hash}.css` yang sudah ada sebagai `<link rel="stylesheet">`. URL berubah saat identitas runtime, kandidat, mesin, atau input CSS berubah, sehingga browser dan cache edge dapat menyimpan URL lama dengan aman. Atur server web atau CDN untuk mengirim header `Cache-Control: public, immutable` berumur panjang bagi cakupan cache ini.

Root cache default berada di lokasi publik di bawah `wp-content`. Jika `cache.path` mengarah ke volume absolut privat, Blockstudio akan kembali menggunakan CSS sebaris kecuali filter `blockstudio/files/url` yang sudah ada menyediakan URL publik untuk cakupan `tailwind`:

```php title="functions.php"
add_filter(
    'blockstudio/files/url',
    function (string $url, string $path, string $scope): string {
        if ('tailwind' !== $scope) {
            return $url;
        }

        return 'https://static.example.com/blockstudio/' . basename($path);
    },
    10,
    3
);
```

## Helper komposisi templat

Blockstudio menyediakan mesin TailwindPHP bundel yang sama untuk templat PHP. Tidak diperlukan salinan di sisi tema ataupun implementasi fallback:

```php title="functions.php"
$classes = bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4

$button = bs_tw_variants([
    'base' => 'inline-flex items-center',
    'variants' => [
        'size' => [
            'sm' => 'h-8 px-3',
            'lg' => 'h-12 px-6',
        ],
    ],
    'defaultVariants' => [
        'size' => 'sm',
    ],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);
```

`bs_tw_merge()` menerima nilai kelas bertingkat dan menyelesaikan konflik Tailwind
utility. `bs_tw_variants()` mengembalikan fungsi yang dapat dipanggil bergaya CVA dan mendukung base,
variants, default variants, compound variants, `class`, dan `className`.

## Konfigurasi

Tailwind v4 menggunakan pendekatan konfigurasi yang mengutamakan CSS. Alih-alih file konfigurasi JavaScript, Anda menulis konfigurasi langsung sebagai CSS menggunakan direktif `@theme`.

```json title="blockstudio.json"
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
  }
}
```

Nilai `config` adalah string CSS yang ditambahkan setelah direktif `@import "tailwindcss"`. Anda dapat menggunakan sintaks Tailwind v4 CSS valid apa pun di sini:

```json title="blockstudio.json"
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
  }
}
```

Untuk konfigurasi beberapa baris, pendekatan filter lebih praktis:

```php title="functions.php"
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@theme {
    --color-primary: #3b82f6;
    --color-secondary: #10b981;
    --font-family-heading: 'Inter', sans-serif;
    --breakpoint-xs: 30rem;
}

@layer base {
    body {
        font-family: var(--font-family-sans);
    }
}

@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .btn-primary { @apply bg-blue-500 text-white hover:bg-blue-600; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
```

### Kelas Utility Kustom

Untuk mendefinisikan alias kelas yang dapat digunakan kembali, gunakan `@layer utilities` dengan direktif `@apply` milik Tailwind langsung dalam string konfigurasi Anda:

```json title="blockstudio.json"
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; } @layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .section { @apply py-16 px-4 max-w-7xl mx-auto; } }"
  }
}
```

Ini mengompilasi kelas-kelas tersebut bersama semua utility Tailwind standar. Kelas ini berfungsi di frontend (kompilasi sisi server) maupun di editor (pratinjau CDN).

Blockstudio mempertahankan urutan lapisan cascade kanonis milik Tailwind:
`theme`, `base`, `components`, lalu `utilities`. Ini sesuai dengan Tailwind CSS, sehingga
aturan pada lapisan yang lebih akhir dapat menimpa lapisan sebelumnya sesuai harapan.

## Jenis Field Kelas

Untuk menggunakan kelas Tailwind pada field `classes` sebuah blok dengan dukungan pelengkapan otomatis, atur `tailwind: true` pada field tersebut:

```json title="block.json"
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}
```

Saat `tailwind` bernilai `true`:

- Field menyediakan saran pelengkapan otomatis dari daftar kelas lengkap Tailwind
- Skrip Tailwind CDN dimuat di editor untuk pratinjau langsung
- Kelas disimpan sebagai string yang dipisahkan spasi dalam atribut blok

Gunakan nilai kelas di templat Anda:

```php title="index.php"
<div class="<?php echo $a['classes']; ?>">
  <!-- block content -->
</div>
```

## Referensi Pengaturan

| Opsi | Jenis | Default | Deskripsi |
| --------- | ------- | ------- | ----------------------------------------------- |
| `enabled` | boolean | `false` | Aktifkan kompilasi Tailwind CSS di frontend |
| `config` | string | `""` | String konfigurasi Tailwind v4-first CSS |

### Mengatur melalui JSON

```json title="blockstudio.json"
{
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: pink; }"
  }
}
```

### Mengatur melalui Filter

```php title="functions.php"
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');

add_filter('blockstudio/settings/tailwind/config', function () {
    return '@theme { --color-brand: pink; }';
});
```

## Caching

Blockstudio menggunakan strategi caching khusus yang dirancang untuk arsitektur berbasis utility milik Tailwind.

### Cara Kerja Cache

Alih-alih melakukan hash pada seluruh HTML halaman (yang akan membatalkan cache pada setiap permintaan karena nonce, stempel waktu, dan konten dinamis lainnya), Blockstudio hanya mengekstrak kandidat kelas CSS dari HTML. Kandidat ini diurutkan dan di-hash bersama konfigurasi CSS untuk menghasilkan kunci cache yang stabil.

Artinya:

- Dua halaman yang menggunakan kumpulan kelas Tailwind yang sama berbagi file CSS yang tersimpan dalam cache, meskipun HTML keduanya sepenuhnya berbeda
- Konten dinamis seperti nonce, bilah pengguna yang masuk, jumlah komentar, dan stempel waktu tidak membatalkan cache
- Cache hanya diinvalidasi saat kumpulan kelas CSS pada halaman berubah atau konfigurasi Tailwind berubah

Saat runtime menggunakan [sumber penemuan logis](https://blockstudio.dev/id/docs/dev/discovery-sources/),
sumber yang dipilih dan konteks runtime juga menjadi bagian dari namespace cache. CSS terakhir yang berhasil diisolasi di antara pratinjau dan tidak dapat bocor dari satu
pilihan sumber ke pilihan lainnya.

### Lokasi Cache

File cache disimpan di:

```
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
```

`cache.path` yang dikonfigurasi, identitas multisite saat ini, dan identitas runtime lengkap menentukan prefiks yang tepat. Setiap file diberi nama menggunakan hash MD5:
`{hash}.css`.

### Menghapus Cache

Hapus isi direktori cache untuk memaksa kompilasi ulang:

```php
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
```

Atau melalui WP-CLI:

```bash
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
```

Permintaan frontend berikutnya akan mengompilasi ulang dan menyimpan CSS ke cache secara otomatis.

## Filter

### `blockstudio/tailwind/css`

Ubah input CSS sebelum kompilasi. String input CSS diawali dengan `@import "tailwindcss";`, diikuti konfigurasi apa pun. Gunakan filter ini untuk menambahkan direktif CSS, aturan `@layer` kustom, atau impor plugin.

```php
add_filter('blockstudio/tailwind/css', function (string $css): string {
    // Add a custom utility
    $css .= "\n@utility container-narrow { max-width: 48rem; margin-inline: auto; }";

    return $css;
});
```

Input CSS lengkap yang dikompilasi akan terlihat seperti ini:

```css
/* Base import */
@import 'tailwindcss';

/* Config from settings (if set) */
@theme {
  --color-brand: pink;
}

/* Anything added via the blockstudio/tailwind/css filter */
```

## Output Buffer

Kompilasi Tailwind terhubung ke sistem output buffer milik Blockstudio. Buffer menangkap HTML halaman lengkap setelah WordPress selesai merender, sehingga Tailwind dapat memindai semua kelas dari setiap sumber: templat blok, templat tema, output plugin, filter `the_content`, dan area widget.

Filter kompilasi berjalan pada prioritas `999999` di hook `blockstudio/buffer/output`, sehingga memproses HTML akhir setelah semua modifikasi lain. Buffer dimulai pada aksi `template_redirect`, sehingga hanya berjalan pada permintaan frontend, bukan di admin, REST API, atau konteks AJAX.

Pem-buffer-an seluruh dokumen memungkinkan hal ini, sehingga fitur tersebut aktif secara default. Situs yang tidak menggunakan Tailwind maupun aset blok dapat menonaktifkannya:

```php
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
```

Mengembalikan `false` melewati buffer sepenuhnya, yang juga menonaktifkan kompilasi Tailwind serta pemindahan gaya dan skrip blok ke dalam head dan footer.

## Arsitektur

```
Frontend Request
  │
  ├─ WordPress renders HTML into output buffer
  │
  ├─ blockstudio/buffer/output filter (priority 999999)
  │   │
  │   ├─ Settings::get('tailwind/enabled') → false? Return HTML unchanged
  │   │
  │   ├─ build_css_input()
  │   │   ├─ @import "tailwindcss"
  │   │   ├─ + tailwind/config setting
  │   │   └─ + blockstudio/tailwind/css filter
  │   │
  │   ├─ TailwindPHP::extractCandidates($html)
  │   │   └─ Returns array of CSS class names found in HTML
  │   │
  │   ├─ Cache key = md5(sorted candidates + css input)
  │   │
  │   ├─ Cache hit?
  │   │   ├─ Yes → Read CSS from the shared runtime `tailwind/{hash}.css` scope
  │   │   └─ No  → TailwindPHP::generate() → Write to cache file
  │   │
  │   └─ Inject inline CSS, or link the content-hashed cache file when tailwind.output is "link"
  │
  └─ Browser receives HTML with compiled CSS


Editor Request
  │
  ├─ Admin loads block editor
  │
  ├─ Block with classes field (tailwind: true) detected
  │   └─ Block_Registry::set_tailwind_active(true)
  │
  ├─ Admin passes isTailwindActive + tailwindUrl to JS
  │
  └─ useTailwind() hook
      ├─ Injects Tailwind CDN script into document
      ├─ Creates hidden template div with HTML content
      ├─ Creates style tag for config
      └─ CDN compiles CSS in-browser for live preview
```

## Contoh Lengkap

Penyiapan lengkap yang berfungsi dengan warna tema kustom dan blok yang menggunakannya:

```json title="blockstudio.json"
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "tailwind": {
    "enabled": true,
    "config": "@theme { --color-brand: #6366f1; --color-brand-light: #a5b4fc; --color-surface: #f8fafc; } @layer utilities { .section-padding { @apply py-20 px-6; } .content-width { @apply max-w-5xl mx-auto; } .heading-xl { @apply text-4xl font-bold tracking-tight; } }"
  }
}
```

```json title="hero/block.json"
{
  "name": "my-theme/hero",
  "title": "Hero Section",
  "blockstudio": {
    "attributes": [
      {
        "id": "title",
        "type": "text",
        "label": "Title",
        "default": "Welcome"
      },
      {
        "id": "wrapperClasses",
        "type": "classes",
        "label": "Wrapper Classes",
        "tailwind": true,
        "default": "section-padding bg-surface"
      },
      {
        "id": "titleClasses",
        "type": "classes",
        "label": "Title Classes",
        "tailwind": true,
        "default": "heading-xl text-brand"
      }
    ]
  }
}
```

```php title="hero/index.php"
<section class="<?php echo $a['wrapperClasses']; ?>">
  <div class="content-width">
    <h1 class="<?php echo $a['titleClasses']; ?>">
      <?php echo esc_html($a['title']); ?>
    </h1>
  </div>
</section>
```

Ini dirender di frontend dengan semua utility Tailwind dan warna tema kustom dikompilasi ke dalam satu tag `<style>` sebaris.

> **[Membangun Pustaka Blok](https://blockstudio.dev/id/guides/block-library/)**
>
> Token desain, utility kustom, dan penyiapan lengkap Tailwind v4 untuk tema produksi.
