michaelschiemer/docs/components/migration-guide.md

# Component Migration Guide

Anleitung zur Migration von Templates auf die neue Component-Syntax.

## Übersicht

Dieser Guide hilft dabei, bestehende Templates von direkter CSS-Klassen-Verwendung auf die neue `<x-*>` Component-Syntax zu migrieren.

## Schritt-für-Schritt Migration

### Schritt 1: Template analysieren

Verwende den Linter um Probleme zu finden:

```bash
php console.php design:lint-templates src/Application/Admin/templates/admin-index.view.php
```

### Schritt 2: Button-Migration

**Pattern 1: Einfacher Button**

```html
<!-- Vorher -->
<button class="btn btn--primary">Save</button>

<!-- Nachher -->
<x-button variant="primary">Save</x-button>
```

**Pattern 2: Button als Link**

```html
<!-- Vorher -->
<a href="/admin" class="btn btn--secondary">Back</a>

<!-- Nachher -->
<x-button variant="secondary" href="/admin">Back</x-button>
```

**Pattern 3: Button mit Größe**

```html
<!-- Vorher -->
<button class="btn btn--primary btn--sm">Small Button</button>

<!-- Nachher -->
<x-button variant="primary" size="sm">Small Button</x-button>
```

**Pattern 4: Disabled Button**

```html
<!-- Vorher -->
<button class="btn btn--primary" disabled>Processing</button>

<!-- Nachher -->
<x-button variant="primary" disabled>Processing</x-button>
```

**Pattern 5: Admin-Button**

```html
<!-- Vorher -->
<button class="admin-btn admin-btn--secondary">Click</button>

<!-- Nachher -->
<x-button variant="secondary">Click</x-button>
```

### Schritt 3: Card-Migration

**Pattern 1: Einfache Card**

```html
<!-- Vorher -->
<div class="card">
    <p>Content</p>
</div>

<!-- Nachher -->
<x-card>
    <p>Content</p>
</x-card>
```

**Pattern 2: Card mit Header**

```html
<!-- Vorher -->
<div class="admin-card">
    <div class="admin-card__header">
        <h2 class="admin-card__title">Title</h2>
    </div>
    <div class="admin-card__body">
        <p>Content</p>
    </div>
</div>

<!-- Nachher -->
<x-card title="Title">
    <p>Content</p>
</x-card>
```

**Pattern 3: Card mit Variante**

```html
<!-- Vorher -->
<div class="admin-card admin-card--success">
    <p>Success message</p>
</div>

<!-- Nachher -->
<x-card variant="success">
    <p>Success message</p>
</x-card>
```

### Schritt 4: Badge-Migration

**Pattern 1: Einfache Badge**

```html
<!-- Vorher -->
<span class="badge badge--success">Active</span>

<!-- Nachher -->
<x-badge variant="success">Active</x-badge>
```

**Pattern 2: Admin-Badge**

```html
<!-- Vorher -->
<span class="admin-badge admin-badge--error">Error</span>

<!-- Nachher -->
<x-badge variant="error">Error</x-badge>
```

**Pattern 3: Pill Badge**

```html
<!-- Vorher -->
<span class="badge badge--info badge--pill">Beta</span>

<!-- Nachher -->
<x-badge variant="info" pill>Beta</x-badge>
```

## Häufige Patterns

### In Loops

```html
<!-- Vorher -->
<for items="{{$actions}}" as="action">
    <a href="{{$action['url']}}" class="btn btn--primary">
        {{$action['label']}}
    </a>
</for>

<!-- Nachher -->
<for items="{{$actions}}" as="action">
    <x-button variant="primary" href="{{$action['url']}}">
        {{$action['label']}}
    </x-button>
</for>
```

### Mit Bedingungen

```html
<!-- Vorher -->
<button class="btn btn--primary" if="{{can_edit}}">Edit</button>

<!-- Nachher -->
<x-button variant="primary" if="{{can_edit}}">Edit</x-button>
```

### Mit zusätzlichen Attributen

```html
<!-- Vorher -->
<button class="btn btn--secondary" data-toggle="modal" aria-label="Open">
    Open Modal
</button>

<!-- Nachher -->
<x-button variant="secondary" data-toggle="modal" aria-label="Open">
    Open Modal
</x-button>
```

## Troubleshooting

### Problem: Component wird nicht gerendert

**Lösung:** Stelle sicher, dass die Component registriert ist:
- Component-Klasse existiert in `src/Framework/View/Components/`
- Component hat `#[ComponentName('...')]` Attribut
- Component implementiert `StaticComponent` Interface

### Problem: Attribute werden nicht übernommen

**Lösung:** 
- Prüfe ob das Attribut in der Component-Klasse unterstützt wird
- Verwende `class` Attribut für zusätzliche CSS-Klassen falls nötig

### Problem: Alte Syntax funktioniert noch

**Lösung:** 
- Die alte `<component name="...">` Syntax wird noch unterstützt, sollte aber migriert werden
- Verwende den Linter um alte Syntax zu finden

## Migration-Checkliste

- [ ] Template mit Linter analysiert
- [ ] Alle Buttons migriert
- [ ] Alle Cards migriert
- [ ] Alle Badges migriert
- [ ] Template getestet
- [ ] Keine Linter-Fehler mehr

## Automatische Migration (Zukünftig)

Ein `--fix` Flag für automatische Migration ist geplant, aber noch nicht implementiert. Bitte migriere Templates manuell nach diesem Guide.