Skip to content
This repository was archived by the owner on Feb 21, 2026. It is now read-only.

Raven v0.5.0 - Phase 11: Modern Layout & Scroll APIs

Choose a tag to compare

View all tags
@briannadoubt briannadoubt released this 04 Feb 05:48
· 215 commits to main since this release
0.5.0
c8fdf8a

Raven v0.5.0 - Phase 11: Modern Layout & Scroll APIs

This major release brings Raven's SwiftUI API coverage from ~70% to ~80% with modern layout APIs, enhanced scroll features, and search functionality.

🌟 Highlights

  • Modern Layout APIs - containerRelativeFrame() and ViewThatFits
  • Scroll Enhancements - 3 new scroll control modifiers
  • Search Functionality - .searchable() with suggestions
  • 142+ Tests - Comprehensive test coverage
  • Complete Documentation - 1,200+ line Phase 11 guide

✨ New Features

Modern Layout APIs

1. containerRelativeFrame() (iOS 17+)

A modern alternative to GeometryReader for responsive layouts:

// Closure-based sizing
Image("hero")
    .containerRelativeFrame(.horizontal) { width, _ in
        width * 0.8
    }

// Grid-based sizing
Rectangle()
    .containerRelativeFrame(.horizontal, count: 3, span: 2, spacing: 10)

Features:

  • Closure-based sizing calculations
  • Grid-based responsive layouts
  • Axis control: .horizontal, .vertical, .all
  • CSS container queries implementation
  • Better performance than GeometryReader

2. ViewThatFits (iOS 16+)

Automatically selects the first layout variant that fits:

ViewThatFits(in: .horizontal) {
    // Desktop: Full navigation
    HStack {
        Image("logo")
        Text("My App Name")
        Spacer()
        Button("Sign In") { }
        Button("Sign Up") { }
    }
    
    // Mobile: Compact (fallback)
    VStack {
        HStack { Image("logo"); Text("My App") }
        HStack { Button("Sign In") { }; Button("Sign Up") { } }
    }
}

Features:

  • Responsive design without breakpoints
  • ViewBuilder support for multiple variants
  • Axis control for measurement
  • CSS container query selection
  • Fallback to last variant

Scroll Enhancements

1. scrollBounceBehavior() (iOS 17+)

Control scroll bounce/overscroll behavior:

ScrollView {
    // content
}
.scrollBounceBehavior(.basedOnSize)  // No bounce when content fits
.scrollBounceBehavior(.always, axes: .horizontal)  // Always bounce horizontally

BounceBehavior Options:

  • .automatic - Default browser behavior
  • .always - Always allow bounce
  • .basedOnSize - Bounce only when content exceeds container

2. scrollClipDisabled() (iOS 17+)

Allow content to extend beyond scroll bounds:

ScrollView {
    // Cards with shadows
    ForEach(items) { item in
        CardView(item)
            .shadow(radius: 10)  // Shadow visible outside scroll
    }
}
.scrollClipDisabled()

3. scrollTransition() (iOS 17+)

Scroll-driven animations with phases:

ScrollView {
    ForEach(items) { item in
        ItemCard(item)
            .scrollTransition { content, phase in
                content
                    .opacity(phase.isIdentity ? 1 : 0)
                    .scaleEffect(phase.isIdentity ? 1 : 0.8)
            }
    }
}

ScrollTransitionPhase:

  • .topLeading - Element entering from top
  • .identity - Element fully visible
  • .bottomTrailing - Element leaving at bottom

Common Patterns:

  • Fade in/out
  • Scale effects
  • Blur transitions
  • Slide animations

Search Functionality

searchable() Modifier (iOS 15+, enhanced iOS 17+)

Add search with optional suggestions:

List(filteredItems) { item in
    Text(item.name)
}
.searchable(
    text: $searchText,
    placement: .navigationBarDrawer,
    prompt: Text("Search items")
) {
    // Suggestions
    ForEach(suggestions) { suggestion in
        Text(suggestion.name)
            .searchCompletion(suggestion.name)
    }
}

Features:

  • Text binding for real-time search
  • Optional suggestions with ViewBuilder
  • Placement options: .automatic, .navigationBarDrawer, .sidebar, .toolbar
  • Native HTML search input
  • Built-in clear button
  • ARIA accessibility

📚 Documentation

New Documentation:

  • Documentation/Phase11.md (~1,200 lines)
    • Modern layout APIs guide with migration from GeometryReader
    • Scroll enhancements detailed guide
    • Search implementation patterns
    • Web implementation details
    • Browser compatibility matrix
    • Performance optimization tips
    • Complete real-world examples

Updated Documentation:

  • README.md - What's New in v0.5.0
  • CHANGELOG.md - Complete version history
  • API-Overview.md - All new APIs documented

Additional Guides:

  • ViewThatFits Implementation Guide
  • ViewThatFits Quick Reference
  • Container Queries Best Practices

🎯 Examples

11 Comprehensive Examples:

  1. Responsive Photo Grid - Grid adapts from 4 columns to 2 with search
  2. Adaptive Navigation - Navigation collapses based on available space
  3. Scrollable Card List - Cards with fade and scale scroll transitions
  4. Search Results Page - Searchable list with filtering and responsive grid
  5. Responsive Dashboard - Complete dashboard with adaptive layout
  6. Horizontal Gallery - Horizontal scrolling with scroll-driven animations
  7. Responsive Form - Form switches from two-column to single-column
  8. E-commerce Product Page - Complete page with search and animations
  9. Container Relative Frame Examples - Various sizing patterns
  10. ViewThatFits Examples - Adaptive layout patterns
  11. Combined Features - Integration with Phase 9 & 10

🧪 Testing

142+ Comprehensive Tests:

  • ContainerRelativeFrameTests: 23 tests
  • ViewThatFitsTests: 22 tests
  • ScrollBehaviorTests: 21 tests
  • ScrollTransitionTests: 21 tests
  • SearchableTests: 15 tests
  • Phase11VerificationTests: 40 integration tests

Test Coverage:

  • Unit tests for each new API
  • Integration tests for feature combinations
  • Real-world usage scenarios
  • Edge case handling
  • Browser compatibility verification

🌐 Web Implementation

Modern Web Standards:

  • CSS Container Queries - Responsive sizing and layout selection
  • CSS calc() - Mathematical expressions for sizing
  • IntersectionObserver API - Scroll position tracking
  • CSS overscroll-behavior - Bounce control
  • HTML Search Input - Native search with suggestions
  • CSS Transitions - GPU-accelerated animations

Browser Compatibility:

Feature Chrome Safari Firefox Edge
Container Queries 105+ 16+ 110+ 105+
IntersectionObserver 51+ 12.1+ 55+ 15+
Overscroll Behavior 63+ 16+ 59+ 18+
Search Input All All All All

Graceful Degradation:

  • Fallback to last variant for ViewThatFits
  • Default scroll behavior for older browsers
  • Progressive enhancement throughout

📊 Statistics

  • 22 files added/modified
  • 9,834 lines added
  • API Coverage: 70% → 80%
  • Tests: 142+ comprehensive tests
  • Test/Code Ratio: 1.21 (excellent)
  • Documentation: 1,200+ lines

🚀 Migration Guide

From GeometryReader to containerRelativeFrame()

Before:

GeometryReader { geometry in
    Image("hero")
        .frame(width: geometry.size.width * 0.8)
}

After:

Image("hero")
    .containerRelativeFrame(.horizontal) { width, _ in
        width * 0.8
    }

Benefits:

  • Simpler code
  • Better performance
  • Native CSS implementation
  • No layout coordination needed

🎓 Use Cases

Responsive Layouts:

  • Photo grids that adapt to screen size
  • Navigation bars that collapse on mobile
  • Dashboards with flexible columns
  • Forms that stack on narrow screens

Enhanced Scrolling:

  • Cards that fade in as you scroll
  • Parallax effects
  • Progressive disclosure
  • Bounce behavior customization

Search:

  • Filterable lists
  • Product search
  • Contact search
  • Document search

📦 Installation

```swift
dependencies: [
.package(url: "https://github.com/briannadoubt/Raven.git", from: "0.5.0")
]
```

🙏 Acknowledgments

This release represents a complete implementation of Phase 11 from the Raven roadmap, bringing modern iOS 16-17+ layout and scroll APIs to SwiftUI web development.

Built with ❤️ using Swift 6.2 and SwiftWasm

See the Documentation for complete guides and API reference.

Assets 2
Loading