# Direttive

Le direttive sono at-rule precedute da `@` che scrivi nel file di input CSS per comporre, estendere e ordinare l'output di Tailwind. Questa pagina tratta `@apply`, `@utility`, `@variant`, `@custom-variant` e `@layer`. `@theme` è descritta in [Tema](https://tailwindphp.inline0.dev/it/docs/usage/theme); `@plugin` in [Plugin](https://tailwindphp.inline0.dev/it/docs/plugins); e `@source` in [@source](https://tailwindphp.inline0.dev/it/docs/usage/source).

## `@apply`

`@apply` integra le dichiarazioni delle utility esistenti nel tuo selettore. Usala per applicare stili di utility a una classe semantica, anche all'interno di selettori annidati e media query.

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

Le varianti funzionano in un elenco `@apply`: `@apply bg-blue-500 hover:bg-blue-600;` espande lo stato `:hover` e prefissi responsive come `@apply px-4 md:px-6 lg:px-8;` generano le regole `@media` corrispondenti. È supportato anche il modificatore important (`@apply !flex;`). Sono supportati i selettori annidati, quindi una regola come `.card { h2 { @apply text-xl font-bold; } }` applica le utility al selettore `h2` annidato.

`@apply` è un'istruzione: `@apply px-4 { … }` con un blocco genera un errore. Un `@apply` che elenca solo identificatori con trattino (`@apply --my-mixin;`) è un mixin CSS della bozza dei mixin [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), non un elenco di utility, quindi TailwindPHP non lo risolve; inserire un mixin e utility nello stesso `@apply` genera un errore (`You cannot use @apply with both mixins and utilities…`). Attualmente le regole mixin vengono eliminate dall'output anziché essere mantenute ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` registra un'utility personalizzata che partecipa al motore di Tailwind: viene ordinata nel livello `utilities` e accetta varianti come quelle integrate. Un'utility statica ha un blocco fisso:

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

Essendo una vera utility, le varianti si combinano automaticamente (`hover:content-auto`, `md:content-auto`). Il blocco può usare a sua volta `@apply` e selettori annidati:

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

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

Un'utility funzionale usa un suffisso `-*` nel nome e legge il valore corrispondente con `--value()`:

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

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

`--value()` risolve il valore del candidato confrontandolo, in ordine, con ciascuna fonte: uno spazio dei nomi del tema (`--gutter-*`), un valore arbitrario con un tipo di dato (`[length]`) oppure un tipo di valore semplice (`integer`, `number`, `percentage`, `ratio`). Una dichiarazione il cui `--value()` non viene risolto viene eliminata, quindi dichiarazioni in sequenza creano una catena di fallback:

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

`--modifier()` risolve la parte dopo un `/` allo stesso modo: con `line-height: --modifier(integer);` nel body, `gutter-4/7` emette anche `line-height: 7`. I nomi delle utility seguono le regole TailwindCSS v4.3.3: al massimo un `/`, `%` solo alla fine dopo una cifra e punti solo tra cifre.

## `@variant`

`@variant` applica una variante alle dichiarazioni nel tuo CSS, senza definire un'utility:

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

Le varianti possono essere concatenate (`@variant hover:focus`), elencate con virgole, annidate e possono indicare i tuoi `@custom-variant`. Un `@variant` di primo livello senza body, o con `@slot`, viene trattato come `@custom-variant` per compatibilità con le versioni precedenti.

## `@custom-variant`

`@custom-variant` definisce una nuova variante da anteporre a qualsiasi utility. La forma compatta indica il nome della variante e fornisce un selettore o una at-rule tra parentesi.

Una variante con elenco di selettori usa `&` per l'elemento:

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

`hocus:bg-blue-500` emette quindi sia le regole `:hover` sia `:focus`. La forma con attributo funziona allo stesso modo:

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

Una variante at-rule racchiude le utility corrispondenti in quella at-rule:

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

Le varianti personalizzate si concatenano con quelle integrate: `sm:hocus:bg-blue-500` annida il selettore `hocus` nella media query `sm`. Per i casi più complessi, usa la forma a blocco, dove `@slot` indica il punto in cui inserire le dichiarazioni dell'utility:

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

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

## `@layer`

`@layer` controlla l'ordine della cascata usando i livelli di cascata nativi di CSS. Un'istruzione `@layer` senza blocco dichiara l'ordine dei livelli; quelli successivi prevalgono indipendentemente dalla specificità del selettore. L'ordine canonico di Tailwind è:

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

È esattamente ciò che `@import "tailwindcss"` configura internamente. Puoi dichiarare un tuo ordine oppure suddividerlo in più istruzioni (`@layer reset, base;` poi `@layer components, utilities;`) e assegnare le regole a un livello con nome usando un blocco:

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

Aggiungere stili di base con `@layer base` li mantiene al di sotto di `components` e `utilities`, così una classe utility prevale sempre sui valori predefiniti dell'elemento. Lo stesso vale per `@layer components { … }`, per le classi dei componenti che devono stare sotto le utility. I livelli anonimi e i modificatori `layer()` su `@import` sono trattati in [Importazioni](https://tailwindphp.inline0.dev/it/docs/usage/imports).

## Passaggi successivi

- [Tema](https://tailwindphp.inline0.dev/it/docs/usage/theme) — `@theme` token e funzioni del tema.
- [Importazioni](https://tailwindphp.inline0.dev/it/docs/usage/imports) — `@import`, moduli virtuali e modificatori `layer()`.
- [Plugin](https://tailwindphp.inline0.dev/it/docs/plugins) — la direttiva `@plugin` e API del plugin.
- [@source](https://tailwindphp.inline0.dev/it/docs/usage/source) — controlla quali file e classi vengono analizzati.