# Директиви

Директиви — це правила at-rule з префіксом `@`, які ви пишете у вхідному файлі CSS, щоб поєднувати, розширювати й впорядковувати результат роботи Tailwind. На цій сторінці описано `@apply`, `@utility`, `@variant`, `@custom-variant` і `@layer`. Про `@theme` читайте в розділі [Тема](https://tailwindphp.inline0.dev/uk/docs/usage/theme); про `@plugin` — у розділі [Плагіни](https://tailwindphp.inline0.dev/uk/docs/plugins); а про `@source` — у розділі [@source](https://tailwindphp.inline0.dev/uk/docs/usage/source).

## `@apply`

`@apply` вбудовує оголошення наявних утиліт у ваш селектор. Використовуйте її, щоб застосувати стилі утиліт до семантичного класу, зокрема у вкладених селекторах і медіазапитах.

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

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

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');
```

Варіанти працюють у списку `@apply`: `@apply bg-blue-500 hover:bg-blue-600;` розгортає стан `:hover`, а адаптивні префікси, як-от `@apply px-4 md:px-6 lg:px-8;`, генерують відповідні правила `@media`. Також підтримується модифікатор важливості (`@apply !flex;`). Вкладені селектори підтримуються, тож правило на кшталт `.card { h2 { @apply text-xl font-bold; } }` застосовує утиліти до вкладеного `h2`.

`@apply` — це інструкція: `@apply px-4 { … }` із тілом спричиняє помилку. `@apply`, що містить лише ідентифікатори з дефісами (`@apply --my-mixin;`), є міксином CSS із чернетки міксинів [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), а не списком утиліт, тому TailwindPHP його не розпізнає; міксин і утиліти в одному `@apply` спричиняють помилку (`You cannot use @apply with both mixins and utilities…`). Наразі правила міксинів відкидаються, а не передаються далі до результату ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` реєструє власну утиліту, яка бере участь у рушії Tailwind: вона потрапляє до шару `utilities` і приймає варіанти, як і будь-яка вбудована утиліта. Статична утиліта має фіксоване тіло:

```css
@utility content-auto {
    content-visibility: auto;
}
```

Оскільки це справжня утиліта, варіанти автоматично поєднуються (`hover:content-auto`, `md:content-auto`). У тілі можна використовувати `@apply` і вкладені селектори:

```css
@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}
```

У назві функціональної утиліти використовується суфікс `-*`, а відповідне значення отримується за допомогою `--value()`:

```css
@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}
```

`--value()` зіставляє значення кандидата з кожним джерелом по черзі: простором імен теми (`--gutter-*`), довільним значенням із типом даних (`[length]`) або базовим типом значення (`integer`, `number`, `percentage`, `ratio`). Оголошення, значення `--value()` якого не вдалося зіставити, відкидається, тож послідовність оголошень утворює ланцюжок резервних значень:

| Клас | Результат |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

`--modifier()` зіставляє частину після `/` так само: якщо в тілі є `line-height: --modifier(integer);`, то `gutter-4/7` також генерує `line-height: 7`. Назви утиліт відповідають правилам TailwindCSS v4.3.3: не більше одного `/`, `%` лише в кінці після цифри, а крапки — тільки між цифрами.

## `@variant`

`@variant` застосовує варіант до оголошень у вашому CSS, не визначаючи утиліту:

```css
.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}
```

```css
.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}
```

Варіанти можна комбінувати (`@variant hover:focus`), перелічувати через коми, вкладати один в одного й указувати в них власні `@custom-variant`. Вважатиметься, що директива верхнього рівня `@variant` без тіла або з `@slot` є `@custom-variant` для зворотної сумісності.

## `@custom-variant`

`@custom-variant` визначає новий варіант, який можна додати як префікс до будь-якої утиліти. У скороченій формі вказується назва варіанта, а в дужках — селектор або правило at-rule.

У варіанті зі списком селекторів для позначення елемента використовується `&`:

```css
@custom-variant hocus (&:hover, &:focus);
```

`hocus:bg-blue-500` генерує правила і для `:hover`, і для `:focus`. Форма з атрибутом працює так само:

```css
@custom-variant loading (&[data-loading="true"]);
```

Варіант правила at-rule огортає відповідні утиліти цим правилом:

```css
@custom-variant tablet (@media (min-width: 600px));
```

Власні варіанти поєднуються з вбудованими: `sm:hocus:bg-blue-500` вкладає селектор `hocus` у медіазапит `sm`. Для складніших випадків використовуйте форму блоку, де `@slot` позначає місце вставлення оголошень утиліти:

```css
@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}
```

## `@layer`

`@layer` керує порядком каскаду за допомогою нативних каскадних шарів CSS. Окрема інструкція `@layer` оголошує порядок шарів; перевагу завжди мають пізніші шари, незалежно від специфічності селектора. Канонічний порядок Tailwind такий:

```css
@layer theme, base, components, utilities;
```

Саме це `@import "tailwindcss"` налаштовує всередині. Ви можете оголосити власний порядок або розбити його на кілька інструкцій (спочатку `@layer reset, base;`, потім `@layer components, utilities;`), а правила призначити іменованому шару за допомогою блоку:

```php
use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');
```

Додавання базових стилів через `@layer base` розміщує їх нижче за `components` і `utilities`, тож утилітарний клас завжди перевизначає стандартні стилі елемента. Те саме стосується `@layer components { … }` для класів компонентів, які мають бути нижче за утиліти. Про анонімні шари й модифікатори `layer()` в `@import` читайте в розділі [Імпорти](https://tailwindphp.inline0.dev/uk/docs/usage/imports).

## Наступні кроки

- [Тема](https://tailwindphp.inline0.dev/uk/docs/usage/theme) — токени `@theme` і функції теми.
- [Імпорти](https://tailwindphp.inline0.dev/uk/docs/usage/imports) — `@import`, віртуальні модулі й модифікатори `layer()`.
- [Плагіни](https://tailwindphp.inline0.dev/uk/docs/plugins) — директива `@plugin` і API плагіна.
- [@source](https://tailwindphp.inline0.dev/uk/docs/usage/source) — налаштування файлів і класів для сканування.