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

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

| Modulo | Contenuto |
|--------|----------|
| `tailwindcss` | Bundle completo: tema + Preflight + utility. |
| `tailwindcss/theme.css` | Solo variabili del tema (colori, spaziatura di base, punti di interruzione ecc.). |
| `tailwindcss/preflight.css` | Reset di base Preflight. |
| `tailwindcss/utilities.css` | Livello delle utility. |
| `tw-animate-css` | Utility di animazione `tw-animate-css`. |

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

## Animazioni con tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/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:

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

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

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

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

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

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](https://github.com/sindresorhus/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:

```php
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`:

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

### Disattivare Preflight

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

## Modificatori di importazione

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

```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);
```

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

```css
@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](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/it/docs/usage/theme) per le variabili del tema oppure con [@source](https://tailwindphp.inline0.dev/it/docs/usage/source) per controllare quali file vengono analizzati alla ricerca di nomi di classi.