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:

@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:

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

Animasi dengan tw-animate-css

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:

@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.

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/:

/* /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:

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. 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:

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:

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:

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:

/* 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:

@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):

• 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 untuk variabel tema, atau @source untuk mengatur file yang dipindai guna mencari nama kelas.