# Tuonnit ja virtuaalimoduulit

TailwindPHP ratkaisee `@import`-säännöt ennen käännöstä. Tuonnit voivat osoittaa sisäänrakennettuihin virtuaalimoduuleihin (`tailwindcss` ja muut), levyllä oleviin tiedostoihin `importPaths`-asetuksella tai mukautetun ratkaisimen palauttamiin kohteisiin.

## Virtuaalimoduulit

`@import "tailwindcss"` on useimpien projektien käyttämä aloituspiste. Se laajenee alla olevaksi neljäksi riviksi: kerrosten järjestysmäärittelyksi ja kolmeksi alituonniksi, joista kukin sijoitetaan omaan kaskadikerrokseensa:

```css
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);
```

Jokainen alituonti on itsessään virtuaalimoduuli, jonka voi tuoda erikseen. Käytettävissä olevat virtuaalimoduulit ovat:

| Moduuli | Sisältö |
|--------|----------|
| `tailwindcss` | Koko paketti: teema + Preflight + apuohjelmat. |
| `tailwindcss/theme.css` | Vain teeman muuttujat (värit, välistyksen perusarvo, taitepisteet jne.). |
| `tailwindcss/preflight.css` | Preflight-perusnollaus. |
| `tailwindcss/utilities.css` | Apuohjelmakerros. |
| `tw-animate-css` | `tw-animate-css`-animaatioapuohjelmat. |

Osien tuominen erikseen mahdollistaa Preflightin ohittamisen tai kerrosten järjestyksen muuttamisen (katso alta).

## Animaatiot: tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) on TailwindCSS-animaatiokirjasto v4, joka korvaa `tailwindcss-animate`-kirjaston suoraan. Se toimitetaan sisäänrakennettuna virtuaalimoduulina, joten sen tuominen apuohjelmakerroksen rinnalla saa sen sisään- ja poistumisanimaatioluokat kääntymään muiden apuohjelmien tavoin:

```css
@import "tw-animate-css";
@import "tailwindcss/utilities.css";
```

Animaatioapuohjelmiin kuuluvat:

- **Sisään / ulos** — `animate-in`, `animate-out`
- **Häivytys** — `fade-in`, `fade-out`
- **Zoomaus** — `zoom-in`, `zoom-out`
- **Pyöritys** — `spin-in`, `spin-out`
- **Sumennus** — `blur-in`, `blur-out`
- **Liuku** — `slide-in-from-top` / `-bottom` / `-left` / `-right` ja vastaava `slide-out-to-*` sekä RTL-suunnan huomioivat `-start` / `-end`
- **Ajoitus** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` sekä `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Toistotila** — `running`, `paused`
- **Komponenttianimaatiot** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` ja `caret-blink`

Nämä luokat pinoutuvat Tailwind-muunnelmien kanssa kuten muutkin apuohjelmat, joten ne sopivat suoraan shadcn/ui-dialogeihin ja pudotusvalikkokuvioihin.

## `importPaths`-asetus

Ratkaise `@import` tiedostojärjestelmän perusteella välittämällä `importPaths` taulukkomuotoiseen `generate()`-asetukseen. Se hyväksyy yksittäisen polun, hakemiston tai taulukon niistä.

```php
use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);
```

### Sisäkkäiset tuonnit

Ladatun tiedoston sisäiset tuonnit ratkaistaan suhteessa kyseiseen tiedostoon. Jos `/path/to/styles.css` sisältää `@import "./components/buttons.css"`, polku ratkaistaan suhteessa kohteeseen `/path/to/`:

```css
/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

@theme {
    --color-brand: #3b82f6;
}
```

### Kaksoiskappaleiden poisto

Saman tiedoston tai virtuaalimoduulin tuominen useammin kuin kerran ei vaikuta ensimmäisen tuonnin jälkeen: toistuvat `@import "tailwindcss"`-rivit tai kaksi samaa osatiedostoa tuovaa tiedostoa poistetaan automaattisesti kaksoiskappaleina. Tämä suojaa myös kehäviittauksilta.

## Mukautettu ratkaisija

Virtuaalisia tiedostojärjestelmiä, tietokantoja tai muita kuin tiedostojärjestelmäpohjaisia lähteitä varten välitä kutsuttava funktio muodossa `importPaths`. Se saa tuonnin URI:n ja hakemiston, johon nähden tuonti ratkaistaan, ja palauttaa arvon CSS tai `null`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);
```

Kun `$uri` on `null` (ensimmäisellä kutsukerralla, jolloin myös toinen argumentti on `null`), palauta merkinnän CSS sisältö. Muun URI:n kohdalla palauta sen CSS sisältö tai `null`, jolloin jatketaan tiedostojärjestelmähakua ja tuonti ohitetaan hiljaisesti, jos mitään ei löydy.

## Preflight

Preflight on Tailwind-työkalun mielipiteellinen perusnollaus, joka perustuu [modern-normalize](https://github.com/sindresorhus/modern-normalize)-kirjastoon. Se tasoittaa selainten välisiä epäjohdonmukaisuuksia, jotta apuohjelmat toimivat ennakoitavasti. Se muun muassa poistaa oletusmarginaalit, poistaa otsikoiden ja luetteloiden tyylit, muuttaa kuvat lohkotason elementeiksi, nollaa reunatyylit niin, että vain `border-width` piirtää reunan, ja saa painikkeet perimään fontin.

Preflight sisältyy `@import "tailwindcss"`-pakettiin. Jos tuot koko paketin, se on jo käytössä:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);
```

### Preflightin laajentaminen

Lisää omat perustyylisi Preflightin päälle määrityksellä `@layer base`:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);
```

### Preflightin poistaminen käytöstä

Kun integroit työkalun olemassa olevaan projektiin, tuo vain tarvitsemasi osat ja jätä Preflight-rivi pois:

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);
```

## Tuontimuuntimet

Kun tuot Tailwind-tiedostoja erikseen, lisää muuntimet niihin tuonteihin, joihin ne vaikuttavat:

```css
/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);
```

## Viitetuonnit

`@import "…" reference` lataa tiedoston vain sen määrityksiä varten: `@theme`-arvot sekä sen sisältämät `@utility`- ja `@custom-variant`-määritykset ovat käytettävissä, mutta tiedosto ei tuota omaa CSS-tulostetta. Tämä vastaa tiedoston sisällön käärimistä muotoon `@media reference { … }`, minkä voit myös kirjoittaa suoraan:

```css
@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}
```

`bg-brand` kääntyy sitten muotoon `background-color: var(--color-brand, #f00);`, eikä `--color-brand`-määritystä tuoteta.

Nykyisessä julkaisussa on kaksi rajoitusta ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Sijoita viitetuonnit ja `@media reference`-lohkot **kohteen `@import` jälkeen**, eli `tailwindcss`- tai `tailwindcss/utilities.css`-määrityksen jälkeen. Jos sijoitat ne sitä ennen, tuloste jää tyhjäksi.
- Sisäänrakennettujen virtuaalimoduulien (`@import "tailwindcss" reference;`) `reference` ei vielä vaikuta: teema, Preflight ja apuohjelmat tuotetaan silti.

Jatka [Theme](https://tailwindphp.inline0.dev/fi/docs/usage/theme)-osioon teeman muuttujia varten tai [@source](https://tailwindphp.inline0.dev/fi/docs/usage/source)-osioon luokkien nimien skannattavien tiedostojen hallintaa varten.