# Imports et modules virtuels

TailwindPHP résout les règles `@import` avant la compilation. Les imports peuvent cibler des modules virtuels intégrés (`tailwindcss` et autres), des fichiers sur disque via l’option `importPaths`, ou tout contenu renvoyé par un résolveur personnalisé.

## Modules virtuels

`@import "tailwindcss"` est le point d’entrée utilisé par la plupart des projets. Il se développe en quatre lignes : la déclaration de l’ordre des couches, puis les trois sous-imports, chacun affecté à sa couche de cascade :

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

Chaque sous-import est lui-même un module virtuel que vous pouvez importer séparément. Voici les modules virtuels disponibles :

| Module | Contenu |
|--------|----------|
| `tailwindcss` | Le bundle complet : thème + Preflight + utilitaires. |
| `tailwindcss/theme.css` | Uniquement les variables de thème (couleurs, base d’espacement, points de rupture, etc.). |
| `tailwindcss/preflight.css` | La réinitialisation de base Preflight. |
| `tailwindcss/utilities.css` | La couche des utilitaires. |
| `tw-animate-css` | Les utilitaires d’animation `tw-animate-css`. |

Importer les différentes parties séparément permet d’ignorer Preflight ou de réorganiser les couches (voir ci-dessous).

## Animations avec tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) est une bibliothèque d’animations TailwindCSS v4, conçue comme un remplacement direct de `tailwindcss-animate`. Elle est fournie sous forme de module virtuel intégré ; son import avec la couche des utilitaires permet donc de compiler ses classes d’animation d’entrée et de sortie comme n’importe quel autre utilitaire :

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

Les utilitaires d’animation couvrent les éléments suivants :

- **Entrée / sortie** — `animate-in`, `animate-out`
- **Fondu** — `fade-in`, `fade-out`
- **Zoom** — `zoom-in`, `zoom-out`
- **Rotation** — `spin-in`, `spin-out`
- **Flou** — `blur-in`, `blur-out`
- **Glissement** — `slide-in-from-top` / `-bottom` / `-left` / `-right` et les variantes `slide-out-to-*` correspondantes, ainsi que `-start` / `-end` compatibles avec RTL
- **Temporalité** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` et `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **État de lecture** — `running`, `paused`
- **Animations de composants** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` et `caret-blink`

Ces classes s’empilent avec les variantes Tailwind comme tout autre utilitaire, ce qui les rend parfaitement adaptées aux modèles de boîtes de dialogue et de menus déroulants shadcn/ui.

## L’option `importPaths`

Pour résoudre `@import` à partir du système de fichiers, passez `importPaths` dans la forme tableau de `generate()`. Elle accepte un chemin unique, un répertoire ou un tableau de l’un ou l’autre.

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

### Imports imbriqués

Les imports contenus dans un fichier chargé sont résolus par rapport à ce fichier. Si `/path/to/styles.css` contient `@import "./components/buttons.css"`, le chemin est résolu par rapport à `/path/to/` :

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

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

### Déduplication

L’importation répétée d’un même fichier ou module virtuel est sans effet après la première fois : les lignes `@import "tailwindcss"` répétées, ou deux fichiers important la même partie, sont dédupliqués automatiquement. Cela protège également contre les imports circulaires.

## Résolveur personnalisé

Pour les systèmes de fichiers virtuels, les bases de données ou toute source autre que le système de fichiers, passez une fonction appelable en tant que `importPaths`. Elle reçoit l’URI d’import et le répertoire de base utilisé pour le résoudre, puis renvoie CSS ou `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
    },
]);
```

Lorsque `$uri` vaut `null` (au premier appel, avec également un deuxième argument `null`), renvoyez le CSS d’entrée. Pour toute autre URI, renvoyez son contenu CSS ou `null` pour revenir à la recherche dans le système de fichiers, qui ignore silencieusement l’import si aucun résultat n’est trouvé.

## Preflight

Preflight est la réinitialisation de base opinionnée de Tailwind, construite sur [modern-normalize](https://github.com/sindresorhus/modern-normalize). Elle lisse les incohérences entre navigateurs pour que les utilitaires se comportent de manière prévisible. Elle supprime notamment les marges par défaut, retire la mise en forme des titres et des listes, affiche les images comme des blocs, réinitialise les styles de bordure pour que seul `border-width` dessine une bordure et fait hériter aux boutons les polices.

Preflight est inclus dans `@import "tailwindcss"` : si vous importez le bundle complet, il est déjà disponible :

```php
use TailwindPHP\tw;

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

### Étendre Preflight

Ajoutez vos propres styles de base par-dessus Preflight avec `@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; }
        }
    ',
]);
```

### Désactiver Preflight

Pour intégrer l’outil à un projet existant, importez uniquement les parties nécessaires et omettez la ligne 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);
    ',
]);
```

## Modificateurs d’import

Lorsque vous importez individuellement les fichiers de Tailwind, les modificateurs s’ajoutent aux imports concernés :

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

## Imports de référence

`@import "…" reference` charge un fichier uniquement pour ses définitions : les valeurs `@theme` ainsi que les définitions `@utility` et `@custom-variant` qu’il contient sont utilisables, mais le fichier ne génère aucune déclaration CSS. Cela revient à envelopper le contenu du fichier dans `@media reference { … }`, ce que vous pouvez aussi écrire directement :

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

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

`bg-brand` est alors compilé en `background-color: var(--color-brand, #f00);` et aucune déclaration `--color-brand` n’est émise.

Deux limites de la version actuelle ([#14](https://github.com/inline0/tailwindphp/issues/14)) :

- Placez les imports de référence et les blocs `@media reference` **après** le `@import` de `tailwindcss` ou de `tailwindcss/utilities.css`. Placés avant, ils produisent une sortie vide.
- `reference` n’a pas encore d’effet sur les modules virtuels intégrés (`@import "tailwindcss" reference;`) : le thème, Preflight et les utilitaires sont toujours émis.

Poursuivez avec [Thème](https://tailwindphp.inline0.dev/fr/docs/usage/theme) pour les variables de thème, ou [@source](https://tailwindphp.inline0.dev/fr/docs/usage/source) pour définir les fichiers analysés à la recherche de noms de classes.