# Directives

Directives zijn de met `@` voorafgegane at-rules die je in je invoer-CSS schrijft om de uitvoer van Tailwind samen te stellen, uit te breiden en te ordenen. Deze pagina behandelt `@apply`, `@utility`, `@variant`, `@custom-variant` en `@layer`. `@theme` wordt behandeld in [Thema](https://tailwindphp.inline0.dev/nl/docs/usage/theme); `@plugin` in [Plugins](https://tailwindphp.inline0.dev/nl/docs/plugins); en `@source` in [@source](https://tailwindphp.inline0.dev/nl/docs/usage/source).

## `@apply`

`@apply` voegt de declaraties van bestaande utilities in je eigen selector in. Gebruik deze om utilitystijlen aan een semantische klasse te koppelen, ook binnen geneste selectors en mediaquery's.

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

Varianten werken in een lijst met `@apply` — `@apply bg-blue-500 hover:bg-blue-600;` breidt de `:hover`-status uit, en responsieve prefixen zoals `@apply px-4 md:px-6 lg:px-8;` genereren de bijbehorende regels `@media`. Ook de belangrijke modifier wordt ondersteund (`@apply !flex;`). Geneste selectors worden ondersteund, zodat een regel zoals `.card { h2 { @apply text-xl font-bold; } }` utilities toepast op de geneste `h2`.

`@apply` is een instructie: `@apply px-4 { … }` met een body geeft een fout. Een `@apply` met alleen streepjesnamen (`@apply --my-mixin;`) is een CSS-mixin uit het conceptvoorstel voor mixins van [CSS](https://drafts.csswg.org/css-mixins-1/#apply-rule), geen utilitylijst. Daarom kan TailwindPHP deze niet oplossen; een mixin en utilities in dezelfde `@apply` plaatsen geeft een fout (`You cannot use @apply with both mixins and utilities…`). Mixinregels worden momenteel uit de uitvoer verwijderd in plaats van doorgegeven ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` registreert een aangepaste utility die deelneemt aan de engine van Tailwind — deze wordt in de laag `utilities` geordend en accepteert varianten zoals elke ingebouwde utility. Een statische utility heeft een vaste body:

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

Omdat het een echte utility is, worden varianten automatisch gecombineerd (`hover:content-auto`, `md:content-auto`). De body mag zelf `@apply` en geneste selectors gebruiken:

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

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

Een functionele utility gebruikt een suffix `-*` in de naam en leest de overeenkomende waarde met `--value()`:

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

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

`--value()` probeert de waarde van de kandidaat achtereenvolgens met elke bron te vinden: een themanaamruimte (`--gutter-*`), een willekeurige waarde met een gegevenstype (`[length]`) of een kale waardetype-aanduiding (`integer`, `number`, `percentage`, `ratio`). Een declaratie waarvan `--value()` niet wordt gevonden, vervalt; zo vormen meerdere declaraties samen een terugvalketen:

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

`--modifier()` verwerkt het deel na een `/` op dezelfde manier: met `line-height: --modifier(integer);` in de body geeft `gutter-4/7` ook `line-height: 7` uit. Namen van hulpprogramma's volgen de TailwindCSS-v4.3.3-regels: maximaal één `/`, `%` alleen aan het einde na een cijfer, en punten alleen tussen cijfers.

## `@variant`

`@variant` past een variant toe op declaraties binnen je eigen CSS, zonder een hulpprogramma te definiëren:

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

Varianten kunnen worden gestapeld (`@variant hover:focus`), met komma's worden opgesomd, in elkaar worden genest en kunnen verwijzen naar je eigen `@custom-variant`s. Een `@variant` op het hoogste niveau zonder body, of met `@slot`, wordt voor achterwaartse compatibiliteit behandeld als `@custom-variant`.

## `@custom-variant`

`@custom-variant` definieert een nieuwe variant die je als prefix aan elk hulpprogramma kunt toevoegen. In de compacte vorm staat de naam van de variant met een selector of at-rule tussen haakjes.

Een variant met een selectorlijst gebruikt `&` voor het element:

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

`hocus:bg-blue-500` geeft vervolgens zowel de regels voor `:hover` als `:focus` uit. Een attribuutvorm werkt op dezelfde manier:

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

Een at-rule-variant plaatst de overeenkomende hulpprogramma's binnen die at-rule:

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

Aangepaste varianten kunnen worden gestapeld met ingebouwde varianten — `sm:hocus:bg-blue-500` nest de selector `hocus` binnen de mediaquery `sm`. Voor complexere gevallen gebruik je de blokvorm, waarbij `@slot` aangeeft waar de declaraties van het hulpprogramma worden ingevoegd:

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

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

## `@layer`

`@layer` bepaalt de cascadevolgorde met native CSS-cascadelagen. Een losse `@layer`-instructie legt de volgorde van de lagen vast; latere lagen winnen, ongeacht de specificiteit van de selector. De canonieke volgorde van Tailwind is:

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

Dit is precies wat `@import "tailwindcss"` intern instelt. Je kunt je eigen volgorde declareren of die over meerdere instructies verdelen (`@layer reset, base;` en daarna `@layer components, utilities;`), en regels aan een benoemde laag toewijzen met een blok:

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

Door basisstijlen toe te voegen via `@layer base` blijven ze onder `components` en `utilities` staan, zodat een hulpprogrammaklasse altijd de standaardstijlen van je element overschrijft. Hetzelfde geldt voor `@layer components { … }` voor componentklassen die onder hulpprogramma's moeten staan. Anonieme lagen en `layer()`-modifiers op `@import` worden behandeld bij [Imports](https://tailwindphp.inline0.dev/nl/docs/usage/imports).

## Volgende stappen

- [Thema](https://tailwindphp.inline0.dev/nl/docs/usage/theme) — `@theme`-tokens en de themafuncties.
- [Imports](https://tailwindphp.inline0.dev/nl/docs/usage/imports) — `@import`, virtuele modules en `layer()`-modifiers.
- [Plugins](https://tailwindphp.inline0.dev/nl/docs/plugins) — de `@plugin`-directive en de plugin-API.
- [@source](https://tailwindphp.inline0.dev/nl/docs/usage/source) — bepaal welke bestanden en klassen worden gescand.