# Direktiivit

Direktiivit ovat syöte-CSSeen kirjoitettavia `@`-etuliitteisiä at-sääntöjä, joilla yhdistellään, laajennetaan ja järjestetään Tailwindn tulostetta. Tämä sivu käsittelee direktiivejä `@apply`, `@utility`, `@variant`, `@custom-variant` ja `@layer`. `@theme` käsitellään sivulla [Teema](https://tailwindphp.inline0.dev/fi/docs/usage/theme), `@plugin` sivulla [Laajennukset](https://tailwindphp.inline0.dev/fi/docs/plugins) ja `@source` sivulla [@source](https://tailwindphp.inline0.dev/fi/docs/usage/source).

## `@apply`

`@apply` lisää olemassa olevien apuohjelmien määrittelyt omaan valitsimeesi. Sillä voit liittää apuohjelmatyylejä semanttiseen luokkaan myös sisäkkäisissä valitsimissa ja mediakyselyissä.

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

Variantit toimivat `@apply`-listassa: `@apply bg-blue-500 hover:bg-blue-600;` laajentaa tilan `:hover`, ja responsiiviset etuliitteet, kuten `@apply px-4 md:px-6 lg:px-8;`, tuottavat vastaavat `@media`-säännöt. Myös tärkeystunnistetta tuetaan (`@apply !flex;`). Sisäkkäiset valitsimet ovat tuettuja, joten esimerkiksi sääntö `.card { h2 { @apply text-xl font-bold; } }` käyttää apuohjelmia sisäkkäiseen `h2`-elementtiin.

`@apply` on käsky: `@apply px-4 { … }` rungollinen muoto aiheuttaa virheen. `@apply`, jossa luetellaan vain tavuviivallisia tunnisteita (`@apply --my-mixin;`), on luonnostyöryhmän [CSS mixins -luonnoksen](https://drafts.csswg.org/css-mixins-1/#apply-rule) mukainen CSS-sekoite, ei apuohjelmaluettelo. Siksi TailwindPHP ei löydä sitä, ja sekoitteen ja apuohjelmien sijoittaminen samaan `@apply`-sääntöön aiheuttaa virheen (`You cannot use @apply with both mixins and utilities…`). Sekoitteiden säännöt pudotetaan tällä hetkellä tulosteesta sen sijaan, että ne välitettäisiin sellaisinaan eteenpäin ([#12](https://github.com/inline0/tailwindphp/issues/12)).

## `@utility`

`@utility` rekisteröi mukautetun apuohjelman, joka toimii Tailwindn moottorissa. Se järjestetään `utilities`-kerrokseen ja hyväksyy variantteja sisäänrakennettujen apuohjelmien tapaan. Staattisella apuohjelmalla on kiinteä runko:

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

Koska kyseessä on todellinen apuohjelma, variantit yhdistyvät automaattisesti (`hover:content-auto`, `md:content-auto`). Rungossa voidaan käyttää myös `@apply`-direktiiviä ja sisäkkäisiä valitsimia:

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

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

Funktionaalisen apuohjelman nimessä käytetään `-*`-päätettä, ja se lukee täsmäävän arvon komennolla `--value()`:

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

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

`--value()` etsii ehdokkaan arvon vuorotellen jokaisesta lähteestä: teeman nimiavaruudesta (`--gutter-*`), mielivaltaisesta arvosta, jolla on tietotyyppi (`[length]`), tai paljaasta arvotyypistä (`integer`, `number`, `percentage`, `ratio`). Määrittely pudotetaan, jos sen `--value()` ei ratkea. Näin useita määrittelyjä pinoamalla saadaan varaketju:

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

`--modifier()` ratkaisee `/`-merkin jälkeisen osan samalla tavalla: kun rungossa on `line-height: --modifier(integer);`, `gutter-4/7` tuottaa myös `line-height: 7`. Apuohjelmien nimet noudattavat TailwindCSS v4.3.3 -sääntöjä: enintään yksi `/`, `%` vain lopussa numeron jälkeen ja pisteitä vain numeroiden välissä.

## `@variant`

`@variant` soveltaa muunnelman omassa CSS-elementissäsi oleviin määrityksiin määrittelemättä apuohjelmaa:

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

Muunnelmia voi pinota (`@variant hover:focus`), luetella pilkuilla, sisäkkäistää ja käyttää omien `@custom-variant`-elementtiesi niminä. Ylimmän tason `@variant` ilman runkoa tai `@slot`-arvolla tulkitaan muodoksi `@custom-variant` taaksepäinyhteensopivuuden vuoksi.

## `@custom-variant`

`@custom-variant` määrittää uuden muunnelman, jonka voi lisätä minkä tahansa apuohjelman eteen. Tiiviissä muodossa annetaan muunnelman nimi sekä valitsija tai sulkeissa oleva at-sääntö.

Valitsijaluettelon muunnelmassa elementin kohdalla käytetään merkintää `&`:

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

`hocus:bg-blue-500` tuottaa sitten sekä säännöt `:hover` että `:focus`. Attribuuttimuoto toimii samalla tavalla:

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

At-sääntömuunnelma käärii vastaavat apuohjelmat kyseiseen at-sääntöön:

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

Mukautettuja muunnelmia voi pinota sisäänrakennettujen kanssa: `sm:hocus:bg-blue-500` sisäkkäistää valitsijan `hocus` mediahakukyselyn `sm` sisään. Monimutkaisempiin tapauksiin voit käyttää lohkomuotoa, jossa `@slot` osoittaa kohdan, johon apuohjelman määritykset lisätään:

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

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

## `@layer`

`@layer` hallitsee kaskadin järjestystä natiivien CSS-kaskadikerrosten avulla. Pelkkä `@layer`-lauseke määrittää kerrosten järjestyksen; myöhemmät kerrokset voittavat valitsimen spesifisyydestä riippumatta. Tailwind-järjestys on:

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

Juuri tämän `@import "tailwindcss"` määrittää sisäisesti. Voit määrittää oman järjestyksen tai jakaa sen useaan lausekkeeseen (`@layer reset, base;` ja sitten `@layer components, utilities;`) sekä sijoittaa säännöt nimettyyn kerrokseen lohkon avulla:

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

Perustyylien lisääminen `@layer base`-määrityksellä pitää ne kerrosten `components` ja `utilities` alapuolella, joten apuohjelmaluokka ohittaa aina elementin oletustyylit. Sama koskee `@layer components { … }`-määritystä komponenttiluokille, joiden tulee olla apuohjelmien alapuolella. Nimettömiä kerroksia ja `@import`-elementin `layer()`-muuntimia käsitellään [Imports](https://tailwindphp.inline0.dev/fi/docs/usage/imports)-osiossa.

## Seuraavat vaiheet

- [Theme](https://tailwindphp.inline0.dev/fi/docs/usage/theme) — `@theme`-tokenit ja teeman funktiot.
- [Imports](https://tailwindphp.inline0.dev/fi/docs/usage/imports) — `@import`, virtuaalimoduulit ja `layer()`-muuntimet.
- [Plugins](https://tailwindphp.inline0.dev/fi/docs/plugins) — `@plugin`-direktiivi ja laajennuksen API.
- [@source](https://tailwindphp.inline0.dev/fi/docs/usage/source) — määritä, mitä tiedostoja ja luokkia skannataan.