# Dyrektywy

Dyrektywy to reguły at-rule z prefiksem `@`, zapisywane w wejściowym CSS, służące do komponowania, rozszerzania i porządkowania wyników Tailwind. Ta strona omawia `@apply`, `@utility`, `@variant`, `@custom-variant` i `@layer`. `@theme` opisano w sekcji [Motyw](https://tailwindphp.inline0.dev/pl/docs/usage/theme); `@plugin` w sekcji [Wtyczki](https://tailwindphp.inline0.dev/pl/docs/plugins); a `@source` w sekcji [@source](https://tailwindphp.inline0.dev/pl/docs/usage/source).

## `@apply`

`@apply` umieszcza deklaracje istniejących narzędzi we własnym selektorze. Użyj go, aby przypisać style narzędzi do klasy semantycznej, także wewnątrz zagnieżdżonych selektorów i zapytań o media.

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

Warianty działają w liście `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` rozwija stan `:hover`, a responsywne prefiksy, takie jak `@apply px-4 md:px-6 lg:px-8;`, emitują odpowiednie reguły `@media`. Obsługiwany jest też modyfikator important (`@apply !flex;`). Obsługiwane są zagnieżdżone selektory, więc reguła taka jak `.card { h2 { @apply text-xl font-bold; } }` stosuje narzędzia do zagnieżdżonego `h2`.

`@apply` jest instrukcją: `@apply px-4 { … }` z treścią powoduje błąd. Reguła `@apply` zawierająca wyłącznie identyfikatory z łącznikiem (`@apply --my-mixin;`) to mixin CSS z wersji roboczej [CSS mixinów](https://drafts.csswg.org/css-mixins-1/#apply-rule), a nie lista narzędzi, więc TailwindPHP jej nie rozpoznaje; umieszczenie mixina i narzędzi w tej samej regule `@apply` powoduje błąd (`You cannot use @apply with both mixins and utilities…`). Reguły mixinów są obecnie pomijane w wynikach, zamiast być przekazywane dalej ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` rejestruje własne narzędzie uczestniczące w działaniu silnika Tailwind — jest sortowane w warstwie `utilities` i obsługuje warianty tak jak narzędzia wbudowane. Narzędzie statyczne ma stałą treść:

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

Ponieważ jest to prawdziwe narzędzie, warianty łączą się automatycznie (`hover:content-auto`, `md:content-auto`). Treść może sama korzystać z `@apply` i zagnieżdżonych selektorów:

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

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

Narzędzie funkcyjne używa sufiksu `-*` w nazwie i odczytuje dopasowaną wartość za pomocą `--value()`:

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

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

`--value()` sprawdza wartość kandydata kolejno w każdym źródle: przestrzeni nazw motywu (`--gutter-*`), dowolnej wartości z typem danych (`[length]`) albo prostym typie wartości (`integer`, `number`, `percentage`, `ratio`). Deklaracja, której `--value()` nie zostanie rozpoznane, jest pomijana, więc zestawienie deklaracji tworzy łańcuch wartości zapasowych:

| Klasa | Wynik |
|---|---|
| `gutter-wide` | `padding-inline: var(--gutter-wide);` |
| `gutter-[5px]` | `padding-inline: 5px;` |
| `gutter-4` | `padding-inline: calc(var(--spacing) * 4);` |

`--modifier()` rozpoznaje część po `/` w ten sam sposób: gdy treść zawiera `line-height: --modifier(integer);`, `gutter-4/7` również emituje `line-height: 7`. Nazwy narzędzi podlegają regułom TailwindCSS v4.3.3: najwyżej jeden `/`, `%` wyłącznie na końcu po cyfrze, a kropki tylko między cyframi.

## `@variant`

`@variant` stosuje wariant do deklaracji we własnym CSS, nie definiując narzędzia:

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

Warianty można łączyć (`@variant hover:focus`), rozdzielać przecinkami, zagnieżdżać w sobie i tworzyć z nazw własnych `@custom-variant`. Górna reguła `@variant` bez treści lub zawierająca `@slot` jest traktowana jako `@custom-variant` dla zgodności wstecznej.

## `@custom-variant`

`@custom-variant` definiuje nowy wariant, który można dodawać jako prefiks do dowolnego narzędzia. Zwięzła forma podaje nazwę wariantu oraz selektor lub regułę at-rule w nawiasach.

Wariant listy selektorów używa `&` dla elementu:

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

`hocus:bg-blue-500` emituje następnie zarówno reguły `:hover`, jak i `:focus`. Forma atrybutowa działa tak samo:

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

Wariant at-rule obejmuje dopasowane narzędzia tą regułą at-rule:

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

Własne warianty można łączyć z wbudowanymi — `sm:hocus:bg-blue-500` zagnieżdża selektor `hocus` w zapytaniu o media `sm`. W bardziej złożonych przypadkach użyj formy blokowej, w której `@slot` wskazuje miejsce wstawienia deklaracji narzędzia:

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

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

## `@layer`

`@layer` kontroluje kolejność kaskady za pomocą natywnych warstw kaskady CSS. Samodzielna instrukcja `@layer` deklaruje kolejność warstw; późniejsze warstwy mają pierwszeństwo niezależnie od specyficzności selektora. Kanoniczna kolejność Tailwind to:

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

Właśnie to `@import "tailwindcss"` konfiguruje wewnętrznie. Możesz zadeklarować własną kolejność albo rozdzielić ją na kilka instrukcji (`@layer reset, base;`, a następnie `@layer components, utilities;`) i przypisać reguły do nazwanej warstwy za 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; }
    }
');
```

Dodanie stylów bazowych przez `@layer base` umieszcza je poniżej `components` i `utilities`, dzięki czemu klasa narzędzia zawsze nadpisuje domyślne style elementu. To samo dotyczy `@layer components { … }` w przypadku klas komponentów, które powinny znajdować się pod narzędziami. Anonimowe warstwy i modyfikatory `layer()` w `@import` opisano w sekcji [Importy](https://tailwindphp.inline0.dev/pl/docs/usage/imports).

## Następne kroki

- [Motyw](https://tailwindphp.inline0.dev/pl/docs/usage/theme) — tokeny `@theme` i funkcje motywu.
- [Importy](https://tailwindphp.inline0.dev/pl/docs/usage/imports) — `@import`, moduły wirtualne i modyfikatory `layer()`.
- [Wtyczki](https://tailwindphp.inline0.dev/pl/docs/plugins) — dyrektywa `@plugin` i API wtyczek API.
- [@source](https://tailwindphp.inline0.dev/pl/docs/usage/source) — kontrola plików i klas skanowanych przez narzędzie.