# Директиви

Директивите са правила at-rule с префикс `@`, които записвате във входния CSS, за да съставяте, разширявате и подреждате изхода на Tailwind. Тази страница разглежда `@apply`, `@utility`, `@variant`, `@custom-variant` и `@layer`. `@theme` е описано в [Тема](https://tailwindphp.inline0.dev/bg/docs/usage/theme); `@plugin` — в [Приставки](https://tailwindphp.inline0.dev/bg/docs/plugins); а `@source` — в [@source](https://tailwindphp.inline0.dev/bg/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/bg/docs/usage/imports).

## Следващи стъпки

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