# Directive

Directivele sunt reguli at prefixate cu `@`, pe care le scrieți în fișierul de intrare CSS pentru a compune, extinde și ordona rezultatul Tailwind. Această pagină prezintă `@apply`, `@utility`, `@variant`, `@custom-variant` și `@layer`. `@theme` este prezentată în [Temă](https://tailwindphp.inline0.dev/ro/docs/usage/theme); `@plugin` în [Pluginuri](https://tailwindphp.inline0.dev/ro/docs/plugins); iar `@source` în [@source](https://tailwindphp.inline0.dev/ro/docs/usage/source).

## `@apply`

`@apply` încorporează declarațiile utilitarelor existente în propriul selector. Folosiți-o pentru a atașa stiluri utilitare unei clase semantice, inclusiv în selectori imbricați și interogări 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;
    }
');
```

Variantele funcționează într-o listă `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` extinde starea `:hover`, iar prefixele responsive precum `@apply px-4 md:px-6 lg:px-8;` emit regulile `@media` corespunzătoare. Este respectat și modificatorul important (`@apply !flex;`). Selectorii imbricați sunt acceptați, așadar o regulă precum `.card { h2 { @apply text-xl font-bold; } }` aplică utilitare selectorului imbricat `h2`.

`@apply` este o instrucțiune: `@apply px-4 { … }` cu un corp provoacă o eroare. Un `@apply` care conține doar identificatori cu cratimă (`@apply --my-mixin;`) este un mixin CSS din proiectul de mixinuri [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), nu o listă de utilitare, așa că TailwindPHP nu îl rezolvă; includerea unui mixin și a utilitarelor în același `@apply` provoacă o eroare (`You cannot use @apply with both mixins and utilities…`). Regulile mixinurilor sunt eliminate momentan din rezultat, în loc să fie păstrate ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` înregistrează un utilitar personalizat care participă la motorul Tailwind — este sortat în stratul `utilities` și acceptă variante ca orice utilitar integrat. Un utilitar static are un corp fix:

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

Fiind un utilitar real, variantele se combină automat (`hover:content-auto`, `md:content-auto`). Corpul poate folosi la rândul său `@apply` și selectori imbricați:

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

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

Un utilitar funcțional folosește un sufix `-*` în nume și citește valoarea potrivită cu `--value()`:

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

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

`--value()` rezolvă valoarea candidatului pe rând pentru fiecare sursă: un spațiu de nume al temei (`--gutter-*`), o valoare arbitrară cu tip de date (`[length]`) sau un tip de valoare simplu (`integer`, `number`, `percentage`, `ratio`). O declarație al cărei `--value()` nu poate fi rezolvat este eliminată, astfel încât stivuirea declarațiilor creează o secvență de valori de rezervă:

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

`--modifier()` rezolvă partea de după un `/` în același mod: cu `line-height: --modifier(integer);` în corp, `gutter-4/7` emite și `line-height: 7`. Numele utilitarelor respectă regulile TailwindCSS v4.3.3: cel mult un `/`, `%` doar la final, după o cifră, iar punctele doar între cifre.

## `@variant`

`@variant` aplică o variantă declarațiilor din propriul CSS, fără a defini un utilitar:

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

Variantele pot fi stivuite (`@variant hover:focus`), enumerate cu virgule, imbricate unele în altele și pot denumi propriile `@custom-variant`. O regulă `@variant` de nivel superior, fără corp sau cu `@slot`, este tratată ca `@custom-variant` pentru compatibilitate inversă.

## `@custom-variant`

`@custom-variant` definește o variantă nouă pe care o puteți adăuga ca prefix oricărui utilitar. Forma compactă numește varianta și specifică un selector sau o regulă at între paranteze.

O variantă cu listă de selectori folosește `&` pentru element:

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

`hocus:bg-blue-500` emite apoi atât regulile `:hover`, cât și `:focus`. Forma cu atribut funcționează la fel:

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

O variantă cu regulă at învelește utilitarele selectate în acea regulă at:

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

Variantele personalizate se combină cu cele integrate — `sm:hocus:bg-blue-500` imbrică selectorul `hocus` în interogarea media `sm`. Pentru cazuri mai complexe, folosiți forma cu bloc, unde `@slot` indică locul în care sunt inserate declarațiile utilitarului:

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

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

## `@layer`

`@layer` controlează ordinea cascadei folosind straturile native de cascadă CSS. O instrucțiune simplă `@layer` declară ordinea straturilor; straturile ulterioare au prioritate, indiferent de specificitatea selectorului. Ordinea canonică a Tailwind este:

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

Acesta este exact aranjamentul configurat intern de `@import "tailwindcss"`. Puteți declara propria ordine sau o puteți împărți în mai multe instrucțiuni (`@layer reset, base;` apoi `@layer components, utilities;`) și puteți atribui reguli unui strat cu nume folosind un bloc:

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

Adăugarea stilurilor de bază prin `@layer base` le menține sub `components` și `utilities`, astfel încât o clasă utilitară suprascrie întotdeauna valorile implicite ale elementului. Același lucru este valabil pentru `@layer components { … }`, destinat claselor de componente care trebuie să rămână sub utilitare. Straturile anonime și modificatorii `layer()` pentru `@import` sunt prezentați în [Importuri](https://tailwindphp.inline0.dev/ro/docs/usage/imports).

## Pașii următori

- [Temă](https://tailwindphp.inline0.dev/ro/docs/usage/theme) — `@theme` tokenuri și funcțiile temei.
- [Importuri](https://tailwindphp.inline0.dev/ro/docs/usage/imports) — `@import`, module virtuale și modificatori `layer()`.
- [Pluginuri](https://tailwindphp.inline0.dev/ro/docs/plugins) — directiva `@plugin` și API pluginului.
- [@source](https://tailwindphp.inline0.dev/ro/docs/usage/source) — controlați fișierele și clasele scanate.