# Importy i moduły wirtualne

TailwindPHP rozwiązuje reguły `@import` przed kompilacją. Importy mogą wskazywać wbudowane moduły wirtualne (`tailwindcss` i podobne), pliki na dysku za pomocą opcji `importPaths` albo dowolną wartość zwracaną przez własny resolver.

## Moduły wirtualne

`@import "tailwindcss"` to punkt wejścia używany w większości projektów. Rozwija się do czterech poniższych wierszy — deklaracji kolejności warstw i trzech importów podrzędnych, z których każdy jest przypisany do swojej warstwy kaskady:

```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żdy import podrzędny jest osobnym modułem wirtualnym, który można importować samodzielnie. Dostępne moduły wirtualne:

| Moduł | Zawartość |
|--------|----------|
| `tailwindcss` | Pełny pakiet: motyw + Preflight + utilities. |
| `tailwindcss/theme.css` | Wyłącznie zmienne motywu (kolory, podstawowe odstępy, punkty przerwania itp.). |
| `tailwindcss/preflight.css` | Bazowy reset Preflight. |
| `tailwindcss/utilities.css` | Warstwa utilities. |
| `tw-animate-css` | Narzędzia animacji `tw-animate-css`. |

Osobny import poszczególnych części pozwala pominąć Preflight lub zmienić kolejność warstw (zobacz poniżej).

## Animacje z tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) to biblioteka animacji TailwindCSS v4 — gotowy zamiennik `tailwindcss-animate`. Jest wbudowana jako moduł wirtualny, więc importowanie jej wraz z warstwą utilities pozwala kompilować klasy animacji wejścia i wyjścia tak jak każde inne narzędzie:

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

Narzędzia animacji obejmują:

- **Wejście / wyjście** — `animate-in`, `animate-out`
- **Zanikanie** — `fade-in`, `fade-out`
- **Powiększanie** — `zoom-in`, `zoom-out`
- **Obrót** — `spin-in`, `spin-out`
- **Rozmycie** — `blur-in`, `blur-out`
- **Przesunięcie** — `slide-in-from-top` / `-bottom` / `-left` / `-right` i odpowiadające im `slide-out-to-*`, a także uwzględniające RTL `-start` / `-end`
- **Czas** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` oraz `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Stan odtwarzania** — `running`, `paused`
- **Animacje komponentów** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` i `caret-blink`

Te klasy można łączyć z wariantami Tailwind jak każde inne narzędzie, dzięki czemu idealnie pasują do wzorców dialogów i list rozwijanych shadcn/ui.

## Opcja `importPaths`

Aby rozwiązywać `@import` względem systemu plików, przekaż `importPaths` w tablicowej formie `generate()`. Akceptuje pojedynczą ścieżkę, katalog lub tablicę takich elementów.

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

### Zagnieżdżone importy

Importy w załadowanym pliku są rozwiązywane względem tego pliku. Jeśli `/path/to/styles.css` zawiera `@import "./components/buttons.css"`, ścieżka jest rozwiązywana względem `/path/to/`:

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

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

### Usuwanie duplikatów

Po pierwszym zaimportowaniu kolejne importy tego samego pliku lub modułu wirtualnego nic nie robią — powtórzone wiersze `@import "tailwindcss"` lub dwa pliki importujące tę samą część są automatycznie deduplikowane. Zapobiega to także importom cyklicznym.

## Własny resolver

W przypadku wirtualnych systemów plików, baz danych lub innych źródeł spoza systemu plików przekaż funkcję jako `importPaths`. Otrzymuje ona URI importu i katalog bazowy, względem którego rozwiązywany jest import, a następnie zwraca CSS lub `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
    },
]);
```

Gdy `$uri` ma wartość `null` (przy pierwszym wywołaniu, także z argumentem `null`), zwróć wejściowy CSS. Dla każdego innego URI zwróć jego zawartość CSS albo `null`, aby przejść do wyszukiwania w systemie plików, które po cichu pomija import, jeśli niczego nie znajdzie.

## Preflight

Preflight to stanowczy bazowy reset Tailwind, oparty na [modern-normalize](https://github.com/sindresorhus/modern-normalize). Wyrównuje niespójności między przeglądarkami, aby narzędzia działały przewidywalnie. Między innymi usuwa domyślne marginesy, usuwa style nagłówków i list, wyświetla obrazy jako elementy blokowe, resetuje style obramowań tak, aby samo `border-width` rysowało obramowanie, i sprawia, że przyciski dziedziczą krój pisma.

Preflight jest częścią `@import "tailwindcss"` — jeśli importujesz pełny pakiet, masz go już dostępnego:

```php
use TailwindPHP\tw;

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

### Rozszerzanie Preflight

Dodaj własne style bazowe na wierzchu Preflight za 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; }
        }
    ',
]);
```

### Wyłączanie Preflight

Podczas integracji z istniejącym projektem importuj tylko potrzebne części i pomiń wiersz 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);
    ',
]);
```

## Modyfikatory importu

Podczas osobnego importowania plików Tailwind modyfikatory należy dodawać do importów, na które mają wpływać:

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

## Importy referencyjne

`@import "…" reference` ładuje plik wyłącznie w celu udostępnienia definicji: dostępne są wartości `@theme` oraz definicje `@utility` i `@custom-variant`, ale plik nie emituje własnego CSS. Działa to tak samo jak umieszczenie zawartości pliku wewnątrz `@media reference { … }`, co również można zapisać bezpośrednio:

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

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

`bg-brand` kompiluje się następnie do `background-color: var(--color-brand, #f00);` i nie jest emitowana żadna deklaracja `--color-brand`.

Dwa ograniczenia bieżącej wersji ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Umieść importy referencyjne i bloki `@media reference` **za** `@import` elementu `tailwindcss` lub `tailwindcss/utilities.css`. Umieszczenie ich przed nim powoduje pusty wynik.
- `reference` wbudowanych modułów wirtualnych (`@import "tailwindcss" reference;`) jeszcze nie działa: motyw, Preflight i utilities nadal są emitowane.

Przejdź dalej do sekcji [Motyw](https://tailwindphp.inline0.dev/pl/docs/usage/theme), aby poznać zmienne motywu, lub do [@source](https://tailwindphp.inline0.dev/pl/docs/usage/source), aby określić, które pliki są skanowane w poszukiwaniu nazw klas.