# Direktif

Direktif adalah at-rule berprefiks `@` yang Anda tulis dalam CSS input untuk menyusun, memperluas, dan mengatur urutan output Tailwind. Halaman ini membahas `@apply`, `@utility`, `@variant`, `@custom-variant`, dan `@layer`. `@theme` dibahas di [Tema](https://tailwindphp.inline0.dev/id/docs/usage/theme); `@plugin` di [Plugin](https://tailwindphp.inline0.dev/id/docs/plugins); dan `@source` di [@source](https://tailwindphp.inline0.dev/id/docs/usage/source).

## `@apply`

`@apply` menyematkan deklarasi utilitas yang sudah ada ke dalam selector Anda sendiri. Gunakan untuk menerapkan gaya utilitas pada kelas semantik, termasuk di dalam selector bersarang dan kueri media.

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');
```

Varian berfungsi dalam daftar `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` memperluas status `:hover`, dan prefiks responsif seperti `@apply px-4 md:px-6 lg:px-8;` menghasilkan aturan `@media` yang sesuai. Modifier penting juga diterapkan (`@apply !flex;`). Selector bersarang didukung, sehingga aturan seperti `.card { h2 { @apply text-xl font-bold; } }` menerapkan utilitas pada `h2` yang bersarang.

`@apply` adalah pernyataan: `@apply px-4 { … }` dengan isi akan memunculkan error. `@apply` yang hanya mencantumkan ident dashed (`@apply --my-mixin;`) adalah mixin CSS dari draf mixin [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), bukan daftar utilitas, sehingga TailwindPHP tidak dapat menyelesaikannya; mencampur mixin dan utilitas dalam `@apply` yang sama akan memunculkan error (`You cannot use @apply with both mixins and utilities…`). Saat ini aturan mixin dihilangkan dari output, bukan diteruskan ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` mendaftarkan utilitas kustom yang menjadi bagian dari mesin Tailwind — utilitas ini diurutkan ke dalam lapisan `utilities` dan menerima varian seperti utilitas bawaan. Utilitas statis memiliki isi tetap:

```css
@utility content-auto {
    content-visibility: auto;
}
```

Karena ini utilitas sungguhan, varian dapat digabungkan secara otomatis (`hover:content-auto`, `md:content-auto`). Isinya dapat menggunakan `@apply` dan selector bersarang:

```css
@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}
```

Utilitas fungsional menggunakan sufiks `-*` pada namanya dan membaca nilai yang cocok dengan `--value()`:

```css
@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}
```

`--value()` menyelesaikan nilai kandidat terhadap setiap sumber secara berurutan: namespace tema (`--gutter-*`), nilai arbitrer dengan tipe data (`[length]`), atau tipe nilai polos (`integer`, `number`, `percentage`, `ratio`). Deklarasi yang nilai `--value()`-nya tidak terselesaikan akan dihilangkan, sehingga menyusun deklarasi akan membentuk rangkaian fallback:

| Kelas | Output |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

`--modifier()` menyelesaikan bagian setelah `/` dengan cara yang sama: dengan `line-height: --modifier(integer);` di dalam body, `gutter-4/7` juga menghasilkan `line-height: 7`. Nama utilitas mengikuti aturan TailwindCSS v4.3.3: paling banyak satu `/`, `%` hanya di akhir setelah digit, dan titik hanya di antara digit.

## `@variant`

`@variant` menerapkan varian pada deklarasi di dalam CSS Anda sendiri, tanpa mendefinisikan utilitas:

```css
.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}
```

```css
.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}
```

Varian dapat ditumpuk (`@variant hover:focus`), dipisahkan dengan koma, disarangkan satu di dalam yang lain, dan dapat menyebut `@custom-variant` buatan Anda sendiri. `@variant` tingkat atas tanpa body, atau dengan `@slot`, diperlakukan sebagai `@custom-variant` demi kompatibilitas ke belakang.

## `@custom-variant`

`@custom-variant` mendefinisikan varian baru yang dapat Anda tambahkan sebagai awalan pada utilitas apa pun. Bentuk ringkasnya mencantumkan nama varian dan selector atau at-rule di dalam tanda kurung.

Varian daftar selector menggunakan `&` untuk elemen tersebut:

```css
@custom-variant hocus (&:hover, &:focus);
```

`hocus:bg-blue-500` lalu menghasilkan aturan `:hover` dan `:focus`. Bentuk atribut bekerja dengan cara yang sama:

```css
@custom-variant loading (&[data-loading="true"]);
```

Varian at-rule membungkus utilitas yang cocok di dalam at-rule tersebut:

```css
@custom-variant tablet (@media (min-width: 600px));
```

Varian kustom dapat ditumpuk dengan varian bawaan — `sm:hocus:bg-blue-500` menyarangkan selector `hocus` di dalam kueri media `sm`. Untuk kasus yang lebih kompleks, gunakan bentuk blok dengan `@slot` sebagai penanda tempat deklarasi utilitas disisipkan:

```css
@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}
```

## `@layer`

`@layer` mengatur urutan cascade menggunakan cascade layer CSS bawaan. Pernyataan `@layer` tanpa isi mendeklarasikan urutan layer; layer yang muncul belakangan akan menang, terlepas dari spesifisitas selector. Urutan kanonis Tailwind adalah:

```css
@layer theme, base, components, utilities;
```

Inilah yang disiapkan `@import "tailwindcss"` secara internal. Anda dapat mendeklarasikan urutan sendiri, atau membaginya ke beberapa pernyataan (`@layer reset, base;` lalu `@layer components, utilities;`), dan menetapkan aturan ke layer bernama dengan sebuah blok:

```php
use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');
```

Menambahkan gaya dasar melalui `@layer base` menempatkannya di bawah `components` dan `utilities`, sehingga kelas utilitas selalu mengesampingkan nilai default elemen Anda. Hal yang sama berlaku untuk `@layer components { … }` bagi kelas komponen yang seharusnya berada di bawah utilitas. Layer anonim dan modifier `layer()` pada `@import` dibahas di [Impor](https://tailwindphp.inline0.dev/id/docs/usage/imports).

## Langkah berikutnya

- [Tema](https://tailwindphp.inline0.dev/id/docs/usage/theme) — `@theme` token dan fungsi tema.
- [Impor](https://tailwindphp.inline0.dev/id/docs/usage/imports) — `@import`, modul virtual, dan modifier `layer()`.
- [Plugin](https://tailwindphp.inline0.dev/id/docs/plugins) — direktif `@plugin` dan API plugin.
- [@source](https://tailwindphp.inline0.dev/id/docs/usage/source) — atur file dan kelas yang dipindai.