# Importaciones y módulos virtuales

TailwindPHP resuelve las reglas `@import` antes de la compilación. Las importaciones pueden apuntar a módulos virtuales integrados (`tailwindcss` y otros), a archivos en disco mediante la opción `importPaths` o a cualquier contenido que devuelva un resolutor personalizado.

## Módulos virtuales

`@import "tailwindcss"` es el punto de entrada que usa la mayoría de los proyectos. Se expande en las cuatro líneas siguientes: la declaración del orden de capas y las tres subimportaciones, cada una asignada a su capa de cascada:

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

Cada subimportación es, a su vez, un módulo virtual que puedes importar por separado. Los módulos virtuales disponibles son:

| Módulo | Contenido |
|--------|----------|
| `tailwindcss` | El paquete completo: tema + Preflight + utilidades. |
| `tailwindcss/theme.css` | Solo las variables del tema (colores, espaciado base, puntos de ruptura, etc.). |
| `tailwindcss/preflight.css` | El restablecimiento base de Preflight. |
| `tailwindcss/utilities.css` | La capa de utilidades. |
| `tw-animate-css` | Las utilidades de animación de `tw-animate-css`. |

Importar las partes por separado te permite omitir Preflight o reordenar las capas (consulta más abajo).

## Animaciones con tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) es una biblioteca de animaciones TailwindCSS v4, un reemplazo directo de `tailwindcss-animate`. Se incluye como módulo virtual integrado, así que al importarla junto con la capa de utilidades, sus clases de animación de entrada y salida se compilan como cualquier otra utilidad:

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

Las utilidades de animación incluyen:

- **Entrada / salida** — `animate-in`, `animate-out`
- **Desvanecimiento** — `fade-in`, `fade-out`
- **Zoom** — `zoom-in`, `zoom-out`
- **Giro** — `spin-in`, `spin-out`
- **Desenfoque** — `blur-in`, `blur-out`
- **Deslizamiento** — `slide-in-from-top` / `-bottom` / `-left` / `-right` y los correspondientes `slide-out-to-*`, además de `-start` / `-end` compatibles con RTL
- **Temporización** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` y `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Estado de reproducción** — `running`, `paused`
- **Animaciones de componentes** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` y `caret-blink`

Estas clases se combinan con variantes Tailwind como cualquier otra utilidad, por lo que encajan directamente en patrones de diálogo y menú desplegable de shadcn/ui.

## La opción `importPaths`

Para resolver `@import` en el sistema de archivos, pasa `importPaths` en el formato de matriz de `generate()`. Acepta una ruta, un directorio o una matriz de cualquiera de ellos.

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

### Importaciones anidadas

Las importaciones dentro de un archivo cargado se resuelven en relación con ese archivo. Si `/path/to/styles.css` contiene `@import "./components/buttons.css"`, la ruta se resuelve con respecto a `/path/to/`:

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

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

### Deduplicación

Importar el mismo archivo o módulo virtual más de una vez no tiene efecto después de la primera vez: las líneas `@import "tailwindcss"` repetidas, o dos archivos que importan el mismo parcial, se deduplican automáticamente. Esto también evita las importaciones circulares.

## Resolutor personalizado

Para sistemas de archivos virtuales, bases de datos o cualquier origen que no sea el sistema de archivos, pasa una función como `importPaths`. Recibe la URI de importación y el directorio base desde el que se resuelve la importación, y devuelve 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
    },
]);
```

Cuando `$uri` es `null` (la primera llamada, también con un segundo argumento `null`), devuelve la entrada CSS. Para cualquier otra URI, devuelve su contenido CSS o `null` para recurrir a la búsqueda en el sistema de archivos, que omite la importación en silencio si no encuentra nada.

## Preflight

Preflight es el restablecimiento base con criterios definidos de Tailwind, basado en [modern-normalize](https://github.com/sindresorhus/modern-normalize). Suaviza las inconsistencias entre navegadores para que las utilidades se comporten de forma predecible. Entre otras cosas, elimina los márgenes predeterminados, quita el estilo de los encabezados y las listas, convierte las imágenes en elementos de bloque, restablece los estilos de borde para que solo `border-width` dibuje un borde y permite que los botones hereden las fuentes.

Preflight viene incluido en `@import "tailwindcss"`; si importas el paquete completo, ya lo tienes:

```php
use TailwindPHP\tw;

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

### Ampliar Preflight

Añade tus propios estilos base sobre 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; }
        }
    ',
]);
```

### Desactivar Preflight

Al integrarlo en un proyecto existente, importa solo las partes que necesites y omite la línea de 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);
    ',
]);
```

## Modificadores de importación

Al importar los archivos de Tailwind por separado, los modificadores se añaden a las importaciones que afectan:

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

## Importaciones de referencia

`@import "…" reference` carga un archivo solo para usar sus definiciones: los valores de `@theme` y las definiciones de `@utility` y `@custom-variant` que contiene están disponibles, pero el archivo no genera ningún CSS propio. Equivale a envolver el contenido del archivo en `@media reference { … }`, algo que también puedes escribir directamente:

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

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

`bg-brand` se compila entonces como `background-color: var(--color-brand, #f00);` y no se emite ninguna declaración de `--color-brand`.

Dos limitaciones de la versión actual ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Coloca las importaciones de referencia y los bloques `@media reference` **después** de `@import` de `tailwindcss` o `tailwindcss/utilities.css`. Si los colocas antes, toda la salida queda vacía.
- `reference` en los módulos virtuales integrados (`@import "tailwindcss" reference;`) aún no tiene efecto: el tema, Preflight y las utilidades se siguen emitiendo.

Continúa con [Theme](https://tailwindphp.inline0.dev/es/docs/usage/theme) para consultar las variables del tema, o con [@source](https://tailwindphp.inline0.dev/es/docs/usage/source) para controlar qué archivos se analizan en busca de nombres de clase.