Importuri și module virtuale

TailwindPHP rezolvă regulile @import înainte de compilare. Importurile pot indica spre module virtuale integrate (tailwindcss și altele), spre fișiere de pe disc prin opțiunea importPaths sau spre orice returnează un rezolvator personalizat.

Module virtuale

@import "tailwindcss" este punctul de intrare folosit de majoritatea proiectelor. Se extinde în cele patru linii de mai jos — declarația ordinii straturilor și cele trei subimporturi, fiecare alocat stratului său de cascadă:

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

Fiecare subimport este la rândul său un modul virtual care poate fi importat separat. Modulele virtuale disponibile sunt:

Importarea separată a componentelor vă permite să omiteți Preflight sau să reordonați straturile (vedeți mai jos).

Animații cu tw-animate-css

tw-animate-css este o bibliotecă de animații TailwindCSS v4 — un înlocuitor direct pentru tailwindcss-animate. Este inclusă ca modul virtual integrat, astfel încât importarea alături de stratul de utilitare permite compilarea claselor de animație de intrare/ieșire la fel ca orice alt utilitar:

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

Utilitarele de animație includ:

• Intrare / ieșire — animate-in, animate-out
• Estompare — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Rotire — spin-in, spin-out
• Estompare — blur-in, blur-out
• Glisare — slide-in-from-top / -bottom / -left / -right și variantele corespunzătoare slide-out-to-*, plus -start / -end, compatibile RTL
• Temporizare — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate și fill-mode-none / -forwards / -backwards / -both
• Stare de redare — running, paused
• Animații de componentă — accordion-down / accordion-up, collapsible-down / collapsible-up și caret-blink

Aceste clase se combină cu variantele Tailwind ca orice alt utilitar, ceea ce le face potrivite pentru tiparele de dialog și meniu derulant shadcn/ui.

Opțiunea importPaths

Pentru a rezolva @import folosind sistemul de fișiere, transmiteți importPaths în forma tablou a lui generate(). Acceptă o singură cale, un director sau un tablou cu oricare dintre acestea.

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',
]);

Importuri imbricate

Importurile dintr-un fișier încărcat sunt rezolvate relativ la acel fișier. Dacă /path/to/styles.css conține @import "./components/buttons.css", calea este rezolvată în raport cu /path/to/:

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

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

Eliminarea duplicatelor

Importarea aceluiași fișier sau modul virtual de mai multe ori nu are efect după prima importare — liniile @import "tailwindcss" repetate sau două fișiere care importă aceeași componentă parțială sunt eliminate automat ca duplicate. Astfel sunt prevenite și importurile circulare.

Rezolvator personalizat

Pentru sisteme de fișiere virtuale, baze de date sau orice sursă care nu folosește sistemul de fișiere, transmiteți un apelabil ca importPaths. Acesta primește URI-ul importului și directorul de bază în raport cu care este rezolvat importul și returnează CSS sau 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
    },
]);

Când $uri este null (primul apel, care are și un al doilea argument null), returnați intrarea CSS. Pentru orice alt URI, returnați conținutul său CSS sau null pentru a reveni la căutarea în sistemul de fișiere, care omite importul fără notificare dacă nu găsește nimic.

Preflight

Preflight este resetarea de bază cu opinii ferme a Tailwind, construită pe modern-normalize. Uniformizează diferențele dintre browsere, astfel încât utilitarele să se comporte previzibil. Printre altele, elimină marginile implicite, elimină stilurile titlurilor și listelor, afișează imaginile ca elemente de bloc, resetează stilurile bordurilor astfel încât doar border-width să deseneze o bordură și permite butoanelor să moștenească fonturile.

Preflight este inclus în @import "tailwindcss" — dacă importați pachetul complet, îl aveți deja:

use TailwindPHP\tw;

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

Extinderea Preflight

Adăugați propriile stiluri de bază peste Preflight cu @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; }
        }
    ',
]);

Dezactivarea Preflight

Când integrați într-un proiect existent, importați doar componentele de care aveți nevoie și omiteți linia 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);
    ',
]);

Modificatori de import

Când importați separat fișierele Tailwind, adăugați modificatorii la importurile asupra cărora au efect:

/* 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);

Importuri de referință

@import "…" reference încarcă un fișier doar pentru definițiile sale: valorile @theme și definițiile @utility și @custom-variant din acesta pot fi folosite, dar fișierul nu generează propriul CSS. Este echivalent cu încadrarea conținutului fișierului în @media reference { … }, lucru pe care îl puteți scrie și direct:

@import "tailwindcss/utilities.css";

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

bg-brand se compilează apoi în background-color: var(--color-brand, #f00); și nu este emisă nicio declarație --color-brand.

Două limitări în versiunea actuală (#14):

• Puneți importurile de referință și blocurile @media reference după @import din tailwindcss sau tailwindcss/utilities.css. Dacă le plasați înainte, întregul rezultat va fi gol.
• reference nu are încă efect asupra modulelor virtuale integrate (@import "tailwindcss" reference;): tema, Preflight și utilitarele sunt în continuare emise.

Continuați cu Temă pentru variabilele temei sau cu @source pentru a controla fișierele scanate în căutarea numelor de clase.