# Imports und virtuelle Module

TailwindPHP löst `@import`-Regeln vor der Kompilierung auf. Imports können auf integrierte virtuelle Module (`tailwindcss` und weitere), auf Dateien über die Option `importPaths` oder auf beliebige Inhalte verweisen, die du von einem benutzerdefinierten Resolver zurückgibst.

## Virtuelle Module

`@import "tailwindcss"` ist der Einstiegspunkt, den die meisten Projekte verwenden. Es wird zu den vier folgenden Zeilen erweitert – der Deklaration der Schichtenreihenfolge und den drei Unter-Imports, die jeweils ihrer Kaskadenschicht zugewiesen sind:

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

Jeder Unter-Import ist selbst ein virtuelles Modul, das du einzeln importieren kannst. Verfügbare virtuelle Module:

| Modul | Inhalt |
|--------|----------|
| `tailwindcss` | Das vollständige Paket: Theme + Preflight + Utilities. |
| `tailwindcss/theme.css` | Nur Theme-Variablen (Farben, Basisabstände, Breakpoints usw.). |
| `tailwindcss/preflight.css` | Der Preflight-Basisreset. |
| `tailwindcss/utilities.css` | Die Utilities-Schicht. |
| `tw-animate-css` | Die `tw-animate-css`-Animations-Utilities. |

Wenn du die Teile einzeln importierst, kannst du Preflight überspringen oder die Schichten neu anordnen (siehe unten).

## Animationen mit tw-animate-css

[tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) ist eine Animationsbibliothek für TailwindCSS v4 – ein direkter Ersatz für `tailwindcss-animate`. Sie wird als integriertes virtuelles Modul bereitgestellt. Importierst du sie zusammen mit der Utilities-Schicht, werden ihre Ein- und Austrittsanimationsklassen wie jedes andere Utility kompiliert:

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

Die Animations-Utilities umfassen:

- **Ein- und Austritt** — `animate-in`, `animate-out`
- **Einblenden** — `fade-in`, `fade-out`
- **Zoom** — `zoom-in`, `zoom-out`
- **Drehen** — `spin-in`, `spin-out`
- **Unschärfe** — `blur-in`, `blur-out`
- **Gleiten** — `slide-in-from-top` / `-bottom` / `-left` / `-right` und die entsprechenden `slide-out-to-*` sowie RTL-fähige `-start` / `-end`
- **Zeitsteuerung** — `duration-*`, `delay-*`, `repeat-1` / `repeat-infinite`, `direction-normal` / `-reverse` / `-alternate` und `fill-mode-none` / `-forwards` / `-backwards` / `-both`
- **Wiedergabestatus** — `running`, `paused`
- **Komponentenanimationen** — `accordion-down` / `accordion-up`, `collapsible-down` / `collapsible-up` und `caret-blink`

Diese Klassen lassen sich wie jedes andere Utility mit Tailwind-Varianten kombinieren und eignen sich dadurch direkt für Dialog- und Dropdown-Muster aus shadcn/ui.

## Die Option `importPaths`

Damit `@import` im Dateisystem aufgelöst wird, übergib `importPaths` in der Array-Form von `generate()`. Akzeptiert werden ein einzelner Pfad, ein Verzeichnis oder ein Array daraus.

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

### Verschachtelte Imports

Imports in einer geladenen Datei werden relativ zu dieser Datei aufgelöst. Wenn `/path/to/styles.css` `@import "./components/buttons.css"` enthält, wird der Pfad relativ zu `/path/to/` aufgelöst:

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

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

### Deduplizierung

Wird dieselbe Datei oder dasselbe virtuelle Modul mehrmals importiert, bleiben alle weiteren Imports nach dem ersten wirkungslos. Wiederholte `@import "tailwindcss"`-Zeilen oder zwei Dateien, die beide dasselbe Teilmodul importieren, werden automatisch dedupliziert. So werden auch zirkuläre Imports verhindert.

## Benutzerdefinierter Resolver

Für virtuelle Dateisysteme, Datenbanken oder andere Quellen, die kein Dateisystem sind, übergib eine aufrufbare Funktion als `importPaths`. Sie erhält die Import-URI und das Basisverzeichnis, relativ zu dem der Import aufgelöst wird, und gibt CSS oder `null` zurück:

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

Wenn `$uri` `null` ist (beim ersten Aufruf, auch mit `null` als zweitem Argument), gib die CSS-Datei zurück. Bei jeder anderen URI gib ihren Inhalt als CSS zurück oder `null`, damit die Suche im Dateisystem übernimmt. Wird nichts gefunden, wird der Import stillschweigend übersprungen.

## Preflight

Preflight ist Tailwinds meinungsstarker Basisreset und baut auf [modern-normalize](https://github.com/sindresorhus/modern-normalize) auf. Er gleicht Unterschiede zwischen Browsern aus, damit Utilities sich zuverlässig verhalten. Unter anderem entfernt er Standardabstände, hebt die Standardstile von Überschriften und Listen auf, setzt Bilder auf Blockebene, setzt Rahmenstile zurück, sodass nur `border-width` einen Rahmen zeichnet, und lässt Buttons die Schriftarten erben.

Preflight ist in `@import "tailwindcss"` enthalten. Wenn du das vollständige Paket importierst, ist es bereits dabei:

```php
use TailwindPHP\tw;

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

### Preflight erweitern

Füge mit `@layer base` eigene Basisstile zu Preflight hinzu:

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

### Preflight deaktivieren

Wenn du Preflight in ein bestehendes Projekt integrierst, importiere nur die benötigten Teile und lass die Preflight-Zeile weg:

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

## Import-Modifikatoren

Wenn du Tailwinds Dateien einzeln importierst, gehören Modifikatoren zu den Imports, auf die sie sich auswirken:

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

## Referenz-Imports

`@import "…" reference` lädt eine Datei ausschließlich für ihre Definitionen: `@theme`-Werte sowie Definitionen für `@utility` und `@custom-variant` darin können verwendet werden, aber die Datei gibt selbst keine CSS aus. Das entspricht dem Umschließen des Dateiinhalts mit `@media reference { … }`, was du auch direkt schreiben kannst:

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

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

`bg-brand` wird dann zu `background-color: var(--color-brand, #f00);` kompiliert und es wird keine `--color-brand`-Deklaration ausgegeben.

Zwei Einschränkungen der aktuellen Version ([#14](https://github.com/inline0/tailwindphp/issues/14)):

- Platziere Referenz-Imports und `@media reference`-Blöcke **nach** dem `@import` von `tailwindcss` oder `tailwindcss/utilities.css`. Stehen sie davor, ist die gesamte Ausgabe leer.
- `reference` auf den integrierten virtuellen Modulen (`@import "tailwindcss" reference;`) hat noch keine Wirkung: Theme, Preflight und Utilities werden weiterhin ausgegeben.

Mach mit [Theme](https://tailwindphp.inline0.dev/de/docs/usage/theme) für Theme-Variablen oder mit [@source](https://tailwindphp.inline0.dev/de/docs/usage/source) weiter, um festzulegen, welche Dateien nach Klassennamen durchsucht werden.