# Impor & Modul Virtual

TailwindPHP menyelesaikan aturan `@import` sebelum kompilasi. Impor dapat mengarah ke modul virtual bawaan (`tailwindcss` dan lainnya), ke file di disk melalui opsi `importPaths`, atau ke apa pun yang dikembalikan oleh resolver kustom.

## Modul virtual

`@import "tailwindcss"` adalah titik masuk yang digunakan sebagian besar proyek. Ini diperluas menjadi empat baris di bawah — deklarasi urutan layer ditambah tiga sub-impor, masing-masing ditetapkan ke cascade layer-nya:

```css
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);
```

Setiap sub-impor juga merupakan modul virtual yang dapat Anda impor sendiri. Modul virtual yang tersedia adalah:

| Modul | Isi |
|--------|----------|
| `tailwindcss` | Bundel lengkap: tema + Preflight + utilitas. |
| `tailwindcss/theme.css` | Hanya variabel tema (warna, dasar spasi, breakpoint, dll.). |
| `tailwindcss/preflight.css` | Reset dasar Preflight. |
| `tailwindcss/utilities.css` | Layer utilitas. |
| `tw-animate-css` | Utilitas animasi `tw-animate-css`. |

Mengimpor bagian-bagiannya secara terpisah memungkinkan Anda melewati Preflight atau mengubah urutan layer (lihat di bawah).

## Animasi dengan tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) adalah pustaka animasi TailwindCSS v4 — pengganti langsung untuk `tailwindcss-animate`. Pustaka ini tersedia sebagai modul virtual bawaan, sehingga mengimpornya bersama layer utilitas membuat kelas animasi masuk/keluar dikompilasi seperti utilitas lainnya:

```css
@import "tw-animate-css";
@import "tailwindcss/utilities.css";
```

Utilitas animasi mencakup:

- **Masuk / keluar** — `animate-in`, `animate-out`
- **Pudar** — `fade-in`, `fade-out`
- **Perbesar** — `zoom-in`, `zoom-out`
- **Putar** — `spin-in`, `spin-out`
- **Buram** — `blur-in`, `blur-out`
- **Geser** — `slide-in-from-top` / `-bottom` / `-left` / `-right` beserta `slide-out-to-*` yang sesuai, serta `-start` / `-end` yang memperhatikan RTL
- **Pengaturan waktu** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate`, dan `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Status pemutaran** — `running`, `paused`
- **Animasi komponen** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up`, dan `caret-blink`

Kelas-kelas ini dapat ditumpuk dengan varian Tailwind seperti utilitas lainnya, sehingga cocok langsung untuk pola dialog dan dropdown shadcn/ui.

## Opsi `importPaths`

Untuk menyelesaikan `@import` terhadap sistem file, teruskan `importPaths` dalam bentuk array `generate()`. Opsi ini menerima satu jalur, sebuah direktori, atau array berisi keduanya.

```php
use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);
```

### Impor bertingkat

Impor di dalam file yang dimuat diselesaikan secara relatif terhadap file tersebut. Jika `/path/to/styles.css` berisi `@import "./components/buttons.css"`, jalur diselesaikan terhadap `/path/to/`:

```css
/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

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

### Deduplicasi

Mengimpor file atau modul virtual yang sama lebih dari sekali tidak melakukan apa pun setelah impor pertama — baris `@import "tailwindcss"` berulang, atau dua file yang sama-sama mengimpor parsial yang sama, otomatis dideduplikasi. Ini juga mencegah impor melingkar.

## Resolver kustom

Untuk sistem file virtual, basis data, atau sumber non-sistem file lainnya, teruskan fungsi yang dapat dipanggil sebagai `importPaths`. Fungsi ini menerima URI impor dan direktori dasar yang menjadi acuan penyelesaian impor, lalu mengembalikan CSS atau `null`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);
```

Saat `$uri` adalah `null` (pemanggilan pertama, dengan argumen kedua `null` juga), kembalikan CSS entri. Untuk URI lainnya, kembalikan isi CSS-nya, atau `null` untuk menggunakan pencarian sistem file sebagai cadangan; impor akan dilewati secara diam-diam jika tidak ada yang ditemukan.

## Preflight

Preflight adalah reset dasar yang opinionated dari Tailwind, dibangun di atas [modern-normalize](https://github.com/sindresorhus/modern-normalize). Fitur ini merapikan inkonsistensi lintas browser agar utilitas berperilaku konsisten. Di antaranya, fitur ini menghapus margin default, menghilangkan gaya heading dan daftar, membuat gambar menjadi block-level, mereset gaya border agar hanya `border-width` yang menggambar border, serta membuat tombol mewarisi font.

Preflight disertakan di dalam `@import "tailwindcss"` — jika Anda mengimpor bundel lengkap, Preflight sudah tersedia:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);
```

### Memperluas Preflight

Tambahkan gaya dasar Anda sendiri di atas Preflight dengan `@layer base`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);
```

### Menonaktifkan Preflight

Saat mengintegrasikannya ke proyek yang sudah ada, impor hanya bagian yang Anda perlukan dan abaikan baris Preflight:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);
```

## Modifier impor

Saat mengimpor file Tailwind satu per satu, modifier ditempatkan pada impor yang dipengaruhinya:

```css
/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);
```

## Impor referensi

`@import "…" reference` memuat file hanya untuk definisinya: nilai `@theme`, definisi `@utility` dan `@custom-variant` di dalamnya dapat digunakan, tetapi file tersebut tidak menghasilkan CSS miliknya sendiri. Ini sama dengan membungkus isi file dalam `@media reference { … }`, yang juga dapat Anda tulis langsung:

```css
@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}
```

`bg-brand` lalu dikompilasi menjadi `background-color: var(--color-brand, #f00);` dan tidak ada deklarasi `--color-brand` yang dihasilkan.

Dua batasan pada rilis saat ini ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Tempatkan impor referensi dan blok `@media reference` **setelah** `@import` dari `tailwindcss` atau `tailwindcss/utilities.css`. Jika ditempatkan sebelumnya, seluruh output akan kosong.
- `reference` pada modul virtual bawaan (`@import "tailwindcss" reference;`) belum berpengaruh: tema, Preflight, dan utilitas tetap dihasilkan.

Lanjutkan ke [Tema](https://tailwindphp.inline0.dev/id/docs/usage/theme) untuk variabel tema, atau [@source](https://tailwindphp.inline0.dev/id/docs/usage/source) untuk mengatur file yang dipindai guna mencari nama kelas.