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"

<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

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

CSS-Anpassungen

Vorher:

.admin-search {
    /* Styles */
}

Nachher:

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

<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>

// 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;
    });
});

.dropdown-menu {
    display: none;
}

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

Nachher: Popover API

<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>

// 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');
        });
    }
});

[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

// 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);
}

.content {
    transition: opacity 0.3s;
}

Nachher: View Transitions API

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

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

.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

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
• Popover Component Dokumentation
• View Transitions Dokumentation