michaelschiemer/docs/guides/migrating-to-modern-features.md

# Migration Guide: Modern Web Features

Schritt-für-Schritt Migration zu modernen Baseline-Features.

## Übersicht

Dieser Guide beschreibt die Migration von Legacy-Implementierungen zu modernen Baseline-Features:

1. `<form role="search">` → `<search>` Element
2. Custom Dropdowns → Popover API
3. Custom Modals → Popover API (wo anwendbar)
4. Custom Transitions → View Transitions API

## 1. Search Element Migration

### Vorher: Form mit role="search"

```html
<form class="admin-search" role="search" action="/search" method="get">
    <label for="search-input" class="admin-visually-hidden">Search</label>
    <input
        type="search"
        id="search-input"
        name="q"
        class="admin-search__input"
        placeholder="Search..."
    />
    <button type="submit" class="admin-search__submit">Search</button>
</form>
```

### Nachher: Search Component

```html
<x-search 
    action="/search"
    method="get"
    name="q"
    placeholder="Search..."
    variant="header"
/>
```

### CSS-Anpassungen

**Vorher:**
```css
.admin-search {
    /* Styles */
}
```

**Nachher:**
```css
search.admin-search {
    /* Styles bleiben gleich, aber Selektor ändert sich */
}
```

### Breaking Changes

- CSS-Selektoren müssen von `.admin-search` zu `search.admin-search` geändert werden
- JavaScript-Selektoren müssen angepasst werden

## 2. Popover API Migration

### Vorher: Custom Dropdown

```html
<div class="dropdown" data-dropdown>
    <button class="dropdown-trigger" data-dropdown-trigger="menu">
        Menu
    </button>
    <ul class="dropdown-menu" data-dropdown-content="menu">
        <li><a href="/item1">Item 1</a></li>
        <li><a href="/item2">Item 2</a></li>
    </ul>
</div>
```

```javascript
// Custom JavaScript
document.querySelectorAll('[data-dropdown-trigger]').forEach(trigger => {
    trigger.addEventListener('click', (e) => {
        e.stopPropagation();
        const dropdown = trigger.closest('[data-dropdown]');
        const isOpen = dropdown.dataset.open === 'true';
        dropdown.dataset.open = !isOpen;
    });
});
```

```css
.dropdown-menu {
    display: none;
}

.dropdown[data-open="true"] .dropdown-menu {
    display: block;
}
```

### Nachher: Popover API

```html
<button popovertarget="menu-popover" aria-haspopup="true" aria-expanded="false">
    Menu
</button>

<x-popover id="menu-popover" type="auto" position="bottom-start">
    <ul role="menu">
        <li><a href="/item1">Item 1</a></li>
        <li><a href="/item2">Item 2</a></li>
    </ul>
</x-popover>
```

```javascript
// Minimales JavaScript nur für aria-expanded
document.querySelectorAll('[popovertarget]').forEach(trigger => {
    const popoverId = trigger.getAttribute('popovertarget');
    const popover = document.getElementById(popoverId);
    
    if (popover) {
        popover.addEventListener('toggle', (e) => {
            const isOpen = popover.matches(':popover-open');
            trigger.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
        });
    }
});
```

```css
[popover] {
    /* Popover Styles */
}

[popover]:not(:popover-open) {
    display: none;
}
```

### Breaking Changes

- `data-dropdown` Attribute werden entfernt
- Custom JavaScript für Dropdown-Management kann entfernt werden
- CSS-Selektoren ändern sich von `[data-open="true"]` zu `:popover-open`

## 3. View Transitions Migration

### Vorher: Custom Transitions

```javascript
// Custom Transition mit setTimeout
function navigateTo(url) {
    const content = document.querySelector('.content');
    content.style.transition = 'opacity 0.3s';
    content.style.opacity = '0';
    
    setTimeout(() => {
        window.location.href = url;
    }, 300);
}
```

```css
.content {
    transition: opacity 0.3s;
}
```

### Nachher: View Transitions API

```javascript
// View Transitions API
import { transitionNavigation } from './modules/admin/view-transitions.js';

function navigateTo(url) {
    transitionNavigation(() => {
        window.location.href = url;
    });
}
```

```css
.content {
    view-transition-name: content;
}

::view-transition-old(content),
::view-transition-new(content) {
    animation: fade 0.15s ease-out;
}
```

### Breaking Changes

- Custom Transition-Logik kann entfernt werden
- CSS-Transitions werden durch View Transitions ersetzt

## Schritt-für-Schritt Migration

### Schritt 1: Search Element

1. Ersetze alle `<form role="search">` durch `<x-search>` Komponente
2. Aktualisiere CSS-Selektoren von `.admin-search` zu `search.admin-search`
3. Teste alle Search-Formulare

### Schritt 2: Popover API

1. Identifiziere alle Custom Dropdowns
2. Ersetze durch `<x-popover>` Komponente
3. Entferne Custom Dropdown-Management JavaScript
4. Aktualisiere CSS-Selektoren
5. Teste alle Dropdowns

### Schritt 3: View Transitions

1. Identifiziere alle Custom Transitions
2. Ersetze durch View Transitions API
3. Definiere `view-transition-name` für wichtige Bereiche
4. Teste alle Transitions

## Fallback-Strategien

### View Transitions Fallback

```javascript
import { supportsViewTransitions, transitionNavigation } from './modules/admin/view-transitions.js';

function navigate(url) {
    if (supportsViewTransitions()) {
        transitionNavigation(() => {
            window.location.href = url;
        });
    } else {
        // Fallback ohne Transition
        window.location.href = url;
    }
}
```

### Popover Fallback

Die Popover API hat keinen direkten Fallback. Für nicht unterstützende Browser sollte ein Polyfill verwendet werden oder die Custom Dropdown-Implementierung beibehalten werden.

## Testing Checklist

- [ ] Alle Search-Formulare funktionieren
- [ ] Alle Dropdowns öffnen/schließen korrekt
- [ ] View Transitions funktionieren
- [ ] Keyboard-Navigation funktioniert
- [ ] Screen Reader Support funktioniert
- [ ] Mobile Responsiveness funktioniert
- [ ] Browser-Kompatibilität geprüft

## Weitere Ressourcen

- [Search Component Dokumentation](./components/search.md)
- [Popover Component Dokumentation](./components/popover.md)
- [View Transitions Dokumentation](./features/view-transitions.md)