# Direktivy

Direktivy jsou pravidla at-rule s předponou `@`, která zapisujete do vstupního CSS, abyste skládali, rozšiřovali a řadili výstup Tailwind. Tato stránka se věnuje direktivám `@apply`, `@utility`, `@variant`, `@custom-variant` a `@layer`. Direktivu `@theme` popisuje část [Téma](https://tailwindphp.inline0.dev/cs/docs/usage/theme), `@plugin` část [Pluginy](https://tailwindphp.inline0.dev/cs/docs/plugins) a `@source` část [@source](https://tailwindphp.inline0.dev/cs/docs/usage/source).

## `@apply`

`@apply` vkládá deklarace existujících utilit do vašeho selektoru. Umožňuje připojit styly utilit k sémantické třídě, a to i ve vnořených selektorech a mediálních dotazech.

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

Varianty fungují v seznamu `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` rozbalí stav `:hover` a responzivní předpony jako `@apply px-4 md:px-6 lg:px-8;` vytvoří odpovídající pravidla `@media`. Respektuje se také modifikátor důležitosti (`@apply !flex;`). Podporovány jsou i vnořené selektory, takže pravidlo jako `.card { h2 { @apply text-xl font-bold; } }` použije utility na vnořený prvek `h2`.

`@apply` je příkaz: `@apply px-4 { … }` s tělem vyvolá chybu. `@apply` obsahující pouze pomlčkové identifikátory (`@apply --my-mixin;`) je mixin CSS z návrhu mixinů [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), nikoli seznam utilit, takže ho TailwindPHP nerozpozná; uvedení mixinu a utilit v témže `@apply` vyvolá chybu (`You cannot use @apply with both mixins and utilities…`). Pravidla mixinu se nyní z výstupu zahazují, místo aby se předávala dál ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` registruje vlastní utilitu, která se zapojuje do enginu Tailwind — řadí se do vrstvy `utilities` a přijímá varianty stejně jako vestavěné utility. Statická utilita má pevně dané tělo:

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

Protože jde o skutečnou utilitu, varianty se automaticky skládají (`hover:content-auto`, `md:content-auto`). Tělo může samo používat `@apply` a vnořené selektory:

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

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

Funkční utilita používá v názvu příponu `-*` a načítá odpovídající hodnotu pomocí `--value()`:

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

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

`--value()` postupně ověřuje hodnotu kandidáta vůči jednotlivým zdrojům: obor názvů tématu (`--gutter-*`), libovolná hodnota s datovým typem (`[length]`) nebo samotný typ hodnoty (`integer`, `number`, `percentage`, `ratio`). Deklarace, jejíž `--value()` se nepodaří rozpoznat, se zahodí, takže řada deklarací tvoří záložní řetězec:

| Třída | Výstup |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

`--modifier()` rozpoznává část za `/` stejným způsobem: obsahuje-li tělo `line-height: --modifier(integer);`, `gutter-4/7` také vygeneruje `line-height: 7`. Názvy utilit se řídí pravidly TailwindCSS v4.3.3: nejvýše jeden `/`, `%` pouze na konci za číslicí a tečky pouze mezi číslicemi.

## `@variant`

`@variant` použije variantu na deklarace uvnitř vašeho vlastního CSS, aniž by definovala utilitu:

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

Varianty lze skládat (`@variant hover:focus`), oddělovat čárkami, vnořovat do sebe a uvádět v nich vlastní `@custom-variant`. Příkaz `@variant` nejvyšší úrovně bez těla nebo s `@slot` se kvůli zpětné kompatibilitě považuje za `@custom-variant`.

## `@custom-variant`

`@custom-variant` definuje novou variantu, kterou lze připojit jako předponu k libovolné utilitě. Stručný zápis uvádí název varianty a selektor nebo pravidlo at-rule v závorkách.

Varianta se seznamem selektorů používá `&` pro prvek:

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

`hocus:bg-blue-500` pak vytvoří pravidla `:hover` i `:focus`. Stejně funguje i zápis s atributem:

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

Varianta s pravidlem at-rule zabalí odpovídající utility do tohoto pravidla:

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

Vlastní varianty lze skládat s vestavěnými — `sm:hocus:bg-blue-500` vnoří selektor `hocus` do mediálního dotazu `sm`. Složitější případy řešte blokovou formou, kde `@slot` označuje místo vložení deklarací utility:

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

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

## `@layer`

`@layer` řídí pořadí kaskády pomocí nativních vrstev kaskády CSS. Samostatný příkaz `@layer` deklaruje pořadí vrstev; pozdější vrstvy mají přednost bez ohledu na specifičnost selektoru. Kanonické pořadí Tailwind je:

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

Přesně toto `@import "tailwindcss"` nastavuje interně. Můžete deklarovat vlastní pořadí nebo je rozdělit do více příkazů (`@layer reset, base;` a poté `@layer components, utilities;`) a přiřadit pravidla do pojmenované vrstvy pomocí bloku:

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

Přidáním základních stylů pomocí `@layer base` je zařadíte pod `components` a `utilities`, takže třída utility vždy přepíše výchozí styly prvků. Totéž platí pro `@layer components { … }` u tříd komponent, které mají být pod utilitami. Anonymní vrstvy a modifikátory `layer()` na `@import` popisuje část [Importy](https://tailwindphp.inline0.dev/cs/docs/usage/imports).

## Další kroky

- [Téma](https://tailwindphp.inline0.dev/cs/docs/usage/theme) — tokeny `@theme` a funkce tématu.
- [Importy](https://tailwindphp.inline0.dev/cs/docs/usage/imports) — `@import`, virtuální moduly a modifikátory `layer()`.
- [Pluginy](https://tailwindphp.inline0.dev/cs/docs/plugins) — direktiva `@plugin` a rozhraní pluginu API.
- [@source](https://tailwindphp.inline0.dev/cs/docs/usage/source) — určuje, které soubory a třídy se prohledávají.