# Importy a virtuální moduly

TailwindPHP před kompilací zpracovává pravidla `@import`. Importy mohou odkazovat na vestavěné virtuální moduly (`tailwindcss` a další), na soubory na disku prostřednictvím možnosti `importPaths` nebo na cokoli, co vrátí vlastní resolver.

## Virtuální moduly

`@import "tailwindcss"` je vstupní bod používaný většinou projektů. Rozbalí se na čtyři řádky níže — deklaraci pořadí vrstev a tři dílčí importy, každý přiřazený ke své vrstvě kaskády:

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

Každý dílčí import je samostatný virtuální modul, který lze importovat samostatně. Dostupné virtuální moduly:

| Modul | Obsah |
|--------|----------|
| `tailwindcss` | Kompletní balíček: téma + Preflight + utility. |
| `tailwindcss/theme.css` | Pouze proměnné tématu (barvy, základní rozestupy, body změny atd.). |
| `tailwindcss/preflight.css` | Základní reset Preflight. |
| `tailwindcss/utilities.css` | Vrstva utilit. |
| `tw-animate-css` | Animační utility `tw-animate-css`. |

Samostatným importem jednotlivých částí můžete vynechat Preflight nebo změnit pořadí vrstev (viz níže).

## Animace pomocí tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) je animační knihovna TailwindCSS v4 — přímá náhrada za `tailwindcss-animate`. Je součástí vestavěného virtuálního modulu; importováním spolu s vrstvou utilit se proto její třídy pro animace při vstupu a odchodu kompilují stejně jako jakékoli jiné utility:

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

Animační utility zahrnují:

- **Vstup / odchod** — `animate-in`, `animate-out`
- **Zeslabení** — `fade-in`, `fade-out`
- **Přiblížení** — `zoom-in`, `zoom-out`
- **Otáčení** — `spin-in`, `spin-out`
- **Rozostření** — `blur-in`, `blur-out`
- **Posunutí** — `slide-in-from-top` / `-bottom` / `-left` / `-right` a odpovídající `slide-out-to-*`, plus varianty `-start` / `-end` pro jazyky se směrem zprava doleva
- **Časování** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` a `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Stav přehrávání** — `running`, `paused`
- **Animace komponent** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` a `caret-blink`

Tyto třídy lze stejně jako jiné utility kombinovat s variantami Tailwind, takže se hodí přímo pro vzory dialogových oken a rozbalovacích nabídek shadcn/ui.

## Možnost `importPaths`

Chcete-li `@import` vyhledávat v souborovém systému, předejte `importPaths` v poli `generate()`. Přijímá cestu k souboru, adresář nebo pole obojího.

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

### Vnořené importy

Importy uvnitř načteného souboru se řeší vzhledem k tomuto souboru. Pokud `/path/to/styles.css` obsahuje `@import "./components/buttons.css"`, cesta se vyhodnotí vzhledem k `/path/to/`:

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

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

### Odstranění duplicit

Opakovaný import téhož souboru nebo virtuálního modulu se po prvním načtení ignoruje — duplicitní řádky `@import "tailwindcss"` i dva soubory importující stejnou část se automaticky odstraní. Zároveň se tím předchází kruhovým importům.

## Vlastní resolver

Pro virtuální souborové systémy, databáze nebo jakýkoli zdroj mimo souborový systém předejte jako `importPaths` volatelnou funkci. Dostane URI importu a základní adresář, vůči němuž se import řeší, a vrátí CSS nebo `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
    },
]);
```

Když je `$uri` rovno `null` (při prvním volání, také s argumentem `null`), vraťte vstupní CSS. U jakéhokoli jiného URI vraťte jeho obsah CSS, nebo `null` pro návrat k vyhledávání v souborovém systému, které import tiše přeskočí, pokud nic nenajde.

## Preflight

Preflight je svébytný základní reset od Tailwind, postavený na [modern-normalize](https://github.com/sindresorhus/modern-normalize). Vyhlazuje rozdíly mezi prohlížeči, aby utility fungovaly předvídatelně. Mimo jiné odstraňuje výchozí okraje, ruší stylování nadpisů a seznamů, nastavuje obrázky jako blokové prvky, resetuje styly okrajů, takže okraj vykresluje pouze `border-width`, a umožňuje tlačítkům dědit písmo.

Preflight je součástí `@import "tailwindcss"` — pokud importujete celý balíček, už ho máte:

```php
use TailwindPHP\tw;

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

### Rozšíření Preflight

Přidejte vlastní základní styly nad Preflight pomocí `@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; }
        }
    ',
]);
```

### Zakázání Preflight

Při začleňování do existujícího projektu importujte jen potřebné části a vynechte řádek Preflight:

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

## Modifikátory importu

Při samostatném importu souborů Tailwind přiřaďte modifikátory k importům, kterých se týkají:

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

## Referenční importy

`@import "…" reference` načte soubor pouze kvůli jeho definicím: lze použít hodnoty `@theme`, `@utility` a definice `@custom-variant` v něm, ale soubor sám nevygeneruje žádné CSS. Je to stejné, jako kdybyste obsah souboru obalili do `@media reference { … }`, což můžete zapsat i přímo:

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

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

`bg-brand` se pak zkompiluje na `background-color: var(--color-brand, #f00);` a žádná deklarace `--color-brand` se nevygeneruje.

Dvě omezení aktuální verze ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Referenční importy a bloky `@media reference` umístěte **za** `@import` `tailwindcss` nebo `tailwindcss/utilities.css`. Pokud je umístíte před něj, celý výstup bude prázdný.
- `reference` na vestavěných virtuálních modulech (`@import "tailwindcss" reference;`) zatím nemá žádný účinek: téma, Preflight i utility se stále generují.

Pokračujte tématem [Theme](https://tailwindphp.inline0.dev/cs/docs/usage/theme), kde najdete proměnné tématu, nebo direktivou [@source](https://tailwindphp.inline0.dev/cs/docs/usage/source), která určuje, které soubory se prohledávají kvůli názvům tříd.