# Importações e módulos virtuais

TailwindPHP resolve regras `@import` antes da compilação. As importações podem apontar para módulos virtuais integrados (`tailwindcss` e outros), para arquivos no disco por meio da opção `importPaths` ou para qualquer conteúdo retornado por um resolvedor personalizado.

## Módulos virtuais

`@import "tailwindcss"` é o ponto de entrada usado pela maioria dos projetos. Ele se expande para as quatro linhas abaixo — a declaração da ordem das camadas e as três subimportações, cada uma atribuída à sua camada de 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);
```

Cada subimportação também é um módulo virtual que você pode importar separadamente. Os módulos virtuais disponíveis são:

| Módulo | Conteúdo |
|--------|----------|
| `tailwindcss` | O pacote completo: tema + Preflight + utilidades. |
| `tailwindcss/theme.css` | Apenas variáveis do tema (cores, espaçamento base, pontos de interrupção etc.). |
| `tailwindcss/preflight.css` | A redefinição base do Preflight. |
| `tailwindcss/utilities.css` | A camada de utilidades. |
| `tw-animate-css` | As utilidades de animação `tw-animate-css`. |

Importar as partes individualmente permite ignorar o Preflight ou reordenar as camadas (veja abaixo).

## Animações com tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) é uma biblioteca de animações TailwindCSS v4 — uma substituição direta para `tailwindcss-animate`. Ela vem como módulo virtual integrado; portanto, importá-la junto com a camada de utilidades faz com que suas classes de animação de entrada e saída sejam compiladas como qualquer outra utilidade:

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

As utilidades de animação incluem:

- **Entrada / saída** — `animate-in`, `animate-out`
- **Aparecimento gradual** — `fade-in`, `fade-out`
- **Zoom** — `zoom-in`, `zoom-out`
- **Rotação** — `spin-in`, `spin-out`
- **Desfoque** — `blur-in`, `blur-out`
- **Deslizamento** — `slide-in-from-top` / `-bottom` / `-left` / `-right` e o correspondente `slide-out-to-*`, além de `-start` / `-end` compatíveis com RTL
- **Temporização** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` e `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Estado de reprodução** — `running`, `paused`
- **Animações de componentes** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` e `caret-blink`

Essas classes podem ser combinadas com variantes Tailwind como qualquer outra utilidade, o que as torna ideais para padrões de diálogo e menus suspensos do shadcn/ui.

## A opção `importPaths`

Para resolver `@import` usando o sistema de arquivos, passe `importPaths` no formato de array de `generate()`. Ele aceita um único caminho, um diretório ou um array de qualquer um deles.

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

### Importações aninhadas

As importações dentro de um arquivo carregado são resolvidas em relação a esse arquivo. Se `/path/to/styles.css` contiver `@import "./components/buttons.css"`, o caminho será resolvido em relação a `/path/to/`:

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

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

### Desduplicação

Importar o mesmo arquivo ou módulo virtual mais de uma vez não faz nada após a primeira importação — linhas `@import "tailwindcss"` repetidas ou dois arquivos que importam a mesma parte são desduplicados automaticamente. Isso também protege contra importações circulares.

## Resolvedor personalizado

Para sistemas de arquivos virtuais, bancos de dados ou qualquer fonte que não seja o sistema de arquivos, passe uma função como `importPaths`. Ela recebe o URI da importação e o diretório base usado para resolvê-la, e retorna 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
    },
]);
```

Quando `$uri` for `null` (a primeira chamada, também com um segundo argumento `null`), retorne a entrada CSS. Para qualquer outro URI, retorne seu conteúdo CSS ou `null` para recorrer à busca no sistema de arquivos, que ignora a importação silenciosamente quando nada é encontrado.

## Preflight

Preflight é a redefinição base opinativa de Tailwind, criada sobre [modern-normalize](https://github.com/sindresorhus/modern-normalize). Ela reduz inconsistências entre navegadores para que as utilidades se comportem de maneira previsível. Entre outras coisas, remove margens padrão, remove os estilos de títulos e listas, define imagens como elementos de bloco, redefine estilos de borda para que apenas `border-width` desenhe uma borda e permite que os botões herdem as fontes.

O Preflight vem incluído em `@import "tailwindcss"` — se você importar o pacote completo, ele já estará disponível:

```php
use TailwindPHP\tw;

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

### Estendendo o Preflight

Adicione seus próprios estilos base sobre o Preflight com `@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; }
        }
    ',
]);
```

### Desativando o Preflight

Ao integrar a ferramenta a um projeto existente, importe apenas as partes necessárias e omita a linha do 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 importação

Ao importar arquivos de Tailwind individualmente, coloque os modificadores nas importações que eles afetam:

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

## Importações de referência

`@import "…" reference` carrega um arquivo apenas para obter suas definições: valores de `@theme`, definições de `@utility` e de `@custom-variant` dentro dele podem ser usadas, mas o arquivo não emite nenhum CSS próprio. É equivalente a envolver o conteúdo do arquivo em `@media reference { … }`, o que você também pode escrever diretamente:

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

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

`bg-brand` então é compilado como `background-color: var(--color-brand, #f00);` e nenhuma declaração `--color-brand` é emitida.

Duas limitações da versão atual ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Coloque importações de referência e blocos `@media reference` **após** o `@import` de `tailwindcss` ou `tailwindcss/utilities.css`. Se forem colocados antes, toda a saída ficará vazia.
- `reference` nos módulos virtuais integrados (`@import "tailwindcss" reference;`) ainda não tem efeito: o tema, o Preflight e as utilidades continuam sendo emitidos.

Continue com [Tema](https://tailwindphp.inline0.dev/pt/docs/usage/theme) para ver as variáveis do tema ou com [@source](https://tailwindphp.inline0.dev/pt/docs/usage/source) para controlar quais arquivos são analisados em busca de nomes de classes.