Importazioni e moduli virtuali

TailwindPHP risolve le regole @import prima della compilazione. Le importazioni possono puntare ai moduli virtuali integrati (tailwindcss e simili), a file su disco tramite l'opzione importPaths oppure a qualsiasi contenuto restituito da un resolver personalizzato.

Moduli virtuali

@import "tailwindcss" è il punto di ingresso usato dalla maggior parte dei progetti. Si espande nelle quattro righe seguenti: la dichiarazione dell'ordine dei livelli e le tre sottoimportazioni, ciascuna assegnata al proprio livello di cascata:

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

Ogni sottoimportazione è a sua volta un modulo virtuale che puoi importare autonomamente. I moduli virtuali disponibili sono:

Importare separatamente le parti consente di escludere Preflight o riordinare i livelli (vedi sotto).

Animazioni con tw-animate-css

tw-animate-css è una libreria di animazioni TailwindCSS v4, sostitutiva immediata di tailwindcss-animate. È fornita come modulo virtuale integrato: importandola insieme al livello delle utility, le classi di animazione di entrata e uscita vengono compilate come qualsiasi altra utility:

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

Le utility di animazione includono:

• Entrata / uscita — animate-in, animate-out
• Dissolvenza — fade-in, fade-out
• Zoom — zoom-in, zoom-out
• Rotazione — spin-in, spin-out
• Sfocatura — blur-in, blur-out
• Scorrimento — slide-in-from-top / -bottom / -left / -right e il corrispondente slide-out-to-*, oltre a -start / -end compatibili con RTL
• Tempi — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate e fill-mode-none / -forwards / -backwards / -both
• Stato di riproduzione — running, paused
• Animazioni dei componenti — accordion-down / accordion-up, collapsible-down / collapsible-up e caret-blink

Queste classi si combinano con le varianti Tailwind come qualsiasi altra utility, adattandosi perfettamente ai pattern di dialogo e menu a discesa di shadcn/ui.

L'opzione importPaths

Per risolvere @import nel filesystem, passa importPaths nella forma array di generate(). Accetta un singolo percorso, una directory o un array di entrambi.

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

Importazioni annidate

Le importazioni all'interno di un file caricato vengono risolte relativamente a quel file. Se /path/to/styles.css contiene @import "./components/buttons.css", il percorso viene risolto rispetto a /path/to/:

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

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

Deduplicazione

Importare più volte lo stesso file o modulo virtuale non ha effetto dopo la prima importazione: le righe @import "tailwindcss" ripetute o due file che importano la stessa parte vengono deduplicati automaticamente. Questo protegge anche dalle importazioni circolari.

Resolver personalizzato

Per filesystem virtuali, database o qualsiasi origine non basata sul filesystem, passa una funzione richiamabile come importPaths. Riceve l'URI di importazione e la directory di base rispetto alla quale risolvere l'importazione e restituisce CSS o 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
    },
]);

Quando $uri è null (la prima chiamata, anche con un secondo argomento null), restituisci il file di ingresso CSS. Per qualsiasi altro URI, restituisci il relativo contenuto CSS oppure null per ripiegare sulla ricerca nel filesystem, che ignora silenziosamente l'importazione se non trova nulla.

Preflight

Preflight è il reset di base con impostazioni specifiche di Tailwind, basato su modern-normalize. Uniforma le differenze tra browser, così le utility si comportano in modo prevedibile. Tra le altre cose, rimuove i margini predefiniti, elimina gli stili di intestazioni ed elenchi, rende le immagini elementi block, reimposta gli stili dei bordi così che solo border-width disegni un bordo e fa ereditare i font ai pulsanti.

Preflight è incluso in @import "tailwindcss": se importi il bundle completo, è già disponibile:

use TailwindPHP\tw;

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

Estendere Preflight

Aggiungi i tuoi stili di base sopra Preflight con @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; }
        }
    ',
]);

Disattivare Preflight

Quando lo integri in un progetto esistente, importa solo le parti necessarie ed escludi la riga di 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 di importazione

Quando importi separatamente i file di Tailwind, applica i modificatori alle importazioni interessate:

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

Importazioni di riferimento

@import "…" reference carica un file solo per le sue definizioni: i valori @theme, le definizioni @utility e @custom-variant al suo interno sono disponibili, ma il file non emette alcun CSS proprio. È come racchiudere il contenuto del file in @media reference { … }, cosa che puoi anche scrivere direttamente:

@import "tailwindcss/utilities.css";

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

bg-brand viene quindi compilato in background-color: var(--color-brand, #f00); e non viene emessa alcuna dichiarazione --color-brand.

Due limitazioni della versione attuale (#14):

• Inserisci le importazioni di riferimento e i blocchi @media reference dopo @import di tailwindcss o tailwindcss/utilities.css. Se li inserisci prima, l'output risulta completamente vuoto.
• reference sui moduli virtuali integrati (@import "tailwindcss" reference;) non ha ancora effetto: il tema, Preflight e le utility vengono comunque emessi.

Continua con Tema per le variabili del tema oppure con @source per controllare quali file vengono analizzati alla ricerca di nomi di classi.