Implement View Transition API for Website-Level DOM State Transitions

[maclong9]

Summary

Implements a comprehensive View Transition API that provides website-level configuration for smooth transitions between DOM states. This API integrates with WebUI's existing Swift-style architecture while leveraging modern CSS View Transitions API for enhanced user experience.

Features Implemented

Element-Level Transitions

• Core Modifier: .viewTransition() with full parameter support
• Convenience Methods: .fadeTransition(), .slideTransition(), .scaleTransition()
• Responsive Support: Works with .on { sm { ... } md { ... } } responsive blocks
• State Modifiers: Compatible with hover, focus, and other interaction states
• Global DSL: Declarative functions for use in responsive contexts

Document-Level Transitions

• Configuration: DocumentViewTransitionConfiguration for page-level settings
• CSS Generation: Automatic generation of View Transitions CSS with keyframes
• JavaScript Integration: Cross-document navigation with view transitions
• Enhanced Rendering: renderWithViewTransitions() method for seamless integration
• Website Defaults: Support for website-level default transition configuration

Comprehensive Type System

• 13 Transition Types: fade, slide (4 directions), scale (3 variants), flip (3 variants), none
• Timing Functions: Linear, ease variants, and custom cubic-bezier curves
• Configuration Options: Duration, delay, slide directions, scale origins, behaviors
• Swift 6 Ready: Full Sendable conformance for concurrency safety

Technical Architecture

StyleOperation Integration

Follows WebUI's established StyleOperation protocol patterns:

• ViewTransitionStyleOperation: Core implementation with Parameters struct
• CSS Class Generation: Generates appropriate Tailwind-compatible classes
• Responsive Integration: Full integration with ResponsiveBuilder system

Document Integration

Extends Document protocol with view transition support:

• Optional Configuration: Documents can optionally specify view transitions
• Automatic Integration: CSS and JS automatically included in enhanced rendering
• Website Inheritance: Documents can inherit default settings from Website

SwiftUI-Inspired API

Maintains consistency with WebUI's SwiftUI-like design:

• Method Chaining: .fadeTransition().padding().background()
• Parameter Labels: Clear, descriptive parameter names following Swift guidelines
• Optional Parameters: Sensible defaults with optional customization

Usage Examples

Basic Element Transitions

Text("Animated Text")
    .fadeTransition(duration: 300, timing: .easeInOut)

Stack()
    .slideTransition(.left, duration: 400)
    .scaleTransition(.scaleUp, origin: .center)

Responsive Transitions

Stack {
    Text("Content")
}
.on {
    sm { fadeTransition(duration: 200) }
    md { slideTransition(.up, duration: 300) }
    lg { scaleTransition(.scale, origin: .center, duration: 400) }
}

Document-Level Transitions

struct HomePage: Document {
    var metadata: Metadata {
        Metadata(title: "Home", description: "Welcome")
    }
    
    var body: some Markup {
        Text("Welcome Home")
    }
    
    var viewTransitions: DocumentViewTransitionConfiguration? {
        DocumentViewTransitionConfiguration(
            defaultTransition: .fade,
            duration: 300,
            timing: .easeInOut,
            enableCrossDocument: true
        )
    }
}

Website-Level Configuration

struct MyWebsite: Website {
    var defaultViewTransitions: DocumentViewTransitionConfiguration? {
        DocumentViewTransitionConfiguration(
            defaultTransition: .slideLeft,
            duration: 400,
            enableCrossDocument: true
        )
    }
    
    @WebsiteRouteBuilder
    var routes: [any Document] {
        HomePage()
        AboutPage()
    }
}

Testing

• 50+ Test Cases: Comprehensive coverage of all functionality
• Unit Tests: Parameter validation, CSS generation, edge cases
• Integration Tests: Element rendering, document integration, responsive behavior
• Type Tests: All enum values and edge case handling

Implementation Details

• Files Added: 6 new files (3 source, 3 test)
• Lines of Code: ~1,900 lines including comprehensive tests and documentation
• Documentation: Full DocC documentation following Swift guidelines
• Performance: Zero runtime overhead, compile-time CSS class generation

Browser Compatibility

• Modern Browsers: Leverages CSS View Transitions API where available
• Graceful Degradation: Falls back gracefully on unsupported browsers
• JavaScript Detection: Runtime feature detection for cross-document transitions

Related

• Addresses Implement View Transition API for Website-Level DOM State Transitions #85
• Builds on existing animation foundations (Implement animations #42)
• Complements component library patterns (Implement components library for common layouts and element patterns #41)

Breaking Changes

None - this is a purely additive API that doesn't modify existing functionality.

[maclong9]

Successfully merged View Transition API to main with all tests passing. The comprehensive API includes element-level and document-level transitions with SwiftUI-inspired syntax, 50+ tests, and full responsive support.