# Импорт и виртуальные модули

TailwindPHP разрешает правила `@import` до компиляции. Импорт может указывать на встроенные виртуальные модули (`tailwindcss` и другие), файлы на диске через параметр `importPaths` или любой результат, возвращаемый пользовательским резолвером.

## Виртуальные модули

`@import "tailwindcss"` — точка входа для большинства проектов. Он разворачивается в четыре строки ниже: объявление порядка слоёв и три подимпорта, каждый в своём каскадном слое:

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

Каждый подимпорт — самостоятельный виртуальный модуль, который можно импортировать отдельно. Доступны следующие виртуальные модули:

| Модуль | Содержимое |
|--------|----------|
| `tailwindcss` | Полный набор: тема + Preflight + утилиты. |
| `tailwindcss/theme.css` | Только переменные темы (цвета, базовые интервалы, контрольные точки и т. д.). |
| `tailwindcss/preflight.css` | Базовый сброс Preflight. |
| `tailwindcss/utilities.css` | Слой утилит. |
| `tw-animate-css` | Анимационные утилиты `tw-animate-css`. |

Раздельный импорт частей позволяет пропустить Preflight или изменить порядок слоёв (см. ниже).

## Анимации с tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) — библиотека анимаций TailwindCSS v4, готовая к замене `tailwindcss-animate`. Она входит во встроенный виртуальный модуль, поэтому при импорте вместе со слоем утилит её классы анимации появления и исчезновения компилируются как любые другие утилиты:

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

Анимационные утилиты охватывают:

- **Появление / исчезновение** — `animate-in`, `animate-out`
- **Затухание** — `fade-in`, `fade-out`
- **Масштабирование** — `zoom-in`, `zoom-out`
- **Вращение** — `spin-in`, `spin-out`
- **Размытие** — `blur-in`, `blur-out`
- **Скольжение** — `slide-in-from-top` / `-bottom` / `-left` / `-right` и соответствующие `slide-out-to-*`, а также учитывающие RTL `-start` / `-end`
- **Время** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` и `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Состояние воспроизведения** — `running`, `paused`
- **Анимации компонентов** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` и `caret-blink`

Эти классы сочетаются с вариантами Tailwind так же, как любые другие утилиты, поэтому подходят для шаблонов диалогов и выпадающих меню shadcn/ui.

## Параметр `importPaths`

Чтобы разрешать `@import` относительно файловой системы, передайте `importPaths` в массивную форму `generate()`. Параметр принимает один путь, каталог или массив из таких значений.

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

### Вложенные импорты

Импорты внутри загруженного файла разрешаются относительно этого файла. Если `/path/to/styles.css` содержит `@import "./components/buttons.css"`, путь разрешается относительно `/path/to/`:

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

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

### Удаление дубликатов

Повторный импорт одного файла или виртуального модуля после первого ничего не меняет: повторяющиеся строки `@import "tailwindcss"` и два файла, импортирующие одну и ту же частичную таблицу стилей, автоматически очищаются от дубликатов. Это также защищает от циклических импортов.

## Пользовательский резолвер

Для виртуальных файловых систем, баз данных и любых источников, отличных от файловой системы, передайте вызываемый объект как `importPaths`. Он получает URI импорта и базовый каталог, относительно которого разрешается импорт, и возвращает CSS или `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
    },
]);
```

Когда `$uri` равен `null` (первый вызов, также с аргументом `null`), верните входной CSS. Для любого другого URI верните содержимое CSS или `null`, чтобы перейти к поиску в файловой системе; если ничего не найдено, импорт будет молча пропущен.

## Предварительная проверка

Preflight — это сброс базовых стилей Tailwind с заданными принципами, построенный на основе [modern-normalize](https://github.com/sindresorhus/modern-normalize). Он сглаживает различия между браузерами, обеспечивая предсказуемую работу утилит. В частности, он удаляет стандартные внешние отступы, сбрасывает оформление заголовков и списков, делает изображения блочными, сбрасывает стили границ, чтобы границу рисовал только `border-width`, и позволяет кнопкам наследовать шрифты.

Preflight входит в `@import "tailwindcss"`: если вы импортируете полный набор, он уже включён:

```php
use TailwindPHP\tw;

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

### Расширение Preflight

Добавьте собственные базовые стили поверх Preflight с помощью `@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; }
        }
    ',
]);
```

### Отключение Preflight

При интеграции в существующий проект импортируйте только нужные части и пропустите строку 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);
    ',
]);
```

## Модификаторы импорта

При раздельном импорте файлов Tailwind модификаторы указываются в тех импортах, на которые они влияют:

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

## Импорт ссылкой

`@import "…" reference` загружает файл только ради его определений: доступны значения `@theme` и определения `@utility` и `@custom-variant` внутри файла, но сам файл не выводит CSS. Это эквивалентно обёртыванию содержимого файла в `@media reference { … }`; такую запись также можно указать напрямую:

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

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

Затем `bg-brand` компилируется в `background-color: var(--color-brand, #f00);`, и объявление `--color-brand` не выводится.

Два ограничения текущего выпуска ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Размещайте импорты ссылкой и блоки `@media reference` **после** `@import` для `tailwindcss` или `tailwindcss/utilities.css`. Если поставить их перед ним, весь результат будет пустым.
- `reference` во встроенных виртуальных модулях (`@import "tailwindcss" reference;`) пока ничего не меняет: тема, Preflight и утилиты всё равно выводятся.

Продолжите с разделом [Тема](https://tailwindphp.inline0.dev/ru/docs/usage/theme) о переменных темы или [@source](https://tailwindphp.inline0.dev/ru/docs/usage/source), чтобы настроить сканирование файлов на имена классов.