# Імпорти та віртуальні модулі

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-*`, а також варіанти `-start` / `-end` з підтримкою RTL
- **Часові параметри** — `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). Воно усуває розбіжності між браузерами, щоб утиліти працювали передбачувано. Зокрема, Preflight прибирає стандартні зовнішні відступи, скидає стилі заголовків і списків, задає зображенням блочно-рівневий режим, скидає стилі рамок, щоб рамку малював лише `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/uk/docs/usage/theme), щоб дізнатися про змінні теми, або з [@source](https://tailwindphp.inline0.dev/uk/docs/usage/source), щоб керувати файлами, у яких виконується пошук назв класів.