@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-patterns/references/deprecated-migration.md

@@ -1,1242 +1,935 @@
-# Deprecated API Migration Guide
+# Deprecated API Migration
 
-A comprehensive mapping of deprecated-to-modern SwiftUI and iOS APIs from iOS 15 through iOS 26. Each section shows the old pattern, the modern replacement, and migration notes. Target iOS 26 with Swift 6.3; backward-compatible to iOS 16 unless noted.
+A map from older SwiftUI and iOS patterns (iOS 15 era through iOS 26) to their
+current replacements. Each entry shows the old form, the new form, and notes.
+Code is written for iOS 26 and Swift 6.3. Every entry names the release its
+replacement needs, so check that against the project's deployment target
+before migrating; nothing here assumes a single baseline.
+
+Several old APIs here (`NavigationView`, `foregroundColor`, `cornerRadius`,
+`ActionSheet`, the `Alert` struct, `presentationMode`, `tabItem`, the
+`.navigationBar` toolbar placements) carry `deprecated: 100000.0` in the SDK.
+Apple's documentation lists them as deprecated, but the compiler does not warn,
+so a clean build does not mean they are gone; search for them.
 
 ## Contents
-- NavigationView to NavigationStack
-- NavigationView Sidebar to NavigationSplitView
-- ObservableObject / `@Published` / `@StateObject` to `@Observable` / `@State`
-- `@ObservedObject` to let / `@Bindable`
-- `@EnvironmentObject` to `@Environment`
-- foregroundColor to foregroundStyle
-- .onChange single-value to two-value
-- ActionSheet to confirmationDialog
-- Alert (Legacy) to modern .alert
-- AnyView to `@ViewBuilder`
-- .onAppear + Task to .task
-- presentationMode to dismiss
-- GeometryReader to Layout / containerRelativeFrame
-- PreviewProvider to #Preview
-- XCTest to Swift Testing
-- EditButton/.onDelete to .swipeActions
-- UIApplication.shared.open to openURL
-- `@FetchRequest` to @Query (SwiftData)
-- some vs any return types
-- .sheet(item:) for sheet presentation
-- Color.resolve(in:) usage
-- ForEach with Identifiable
-- Toolbar placement updates
-
-## NavigationView to NavigationStack
-
-NavigationView was deprecated in iOS 16. Use NavigationStack for push-based navigation with a single column, or NavigationSplitView for multi-column layouts.
-
-### Before (Deprecated)
 
-```swift
-struct ContentView: View {
-    var body: some View {
-        NavigationView {
-            List(items) { item in
-                NavigationLink(destination: DetailView(item: item)) {
-                    Text(item.title)
-                }
-            }
-            .navigationTitle("Items")
+1. [NavigationView to NavigationStack](#1-navigationview-to-navigationstack)
+2. [NavigationView Sidebar to NavigationSplitView](#2-navigationview-sidebar-to-navigationsplitview)
+3. [ObservableObject and @StateObject to @Observable and @State](#3-observableobject-and-stateobject-to-observable-and-state)
+4. [@ObservedObject to let or @Bindable](#4-observedobject-to-let-or-bindable)
+5. [@EnvironmentObject to @Environment](#5-environmentobject-to-environment)
+6. [foregroundColor to foregroundStyle](#6-foregroundcolor-to-foregroundstyle)
+7. [Single-Value onChange to Two-Value onChange](#7-single-value-onchange-to-two-value-onchange)
+8. [ActionSheet to confirmationDialog](#8-actionsheet-to-confirmationdialog)
+9. [Legacy Alert to alert with Actions](#9-legacy-alert-to-alert-with-actions)
+10. [AnyView to @ViewBuilder and Concrete Types](#10-anyview-to-viewbuilder-and-concrete-types)
+11. [onAppear with Task to .task](#11-onappear-with-task-to-task)
+12. [presentationMode to dismiss](#12-presentationmode-to-dismiss)
+13. [GeometryReader Overuse to containerRelativeFrame and Layout](#13-geometryreader-overuse-to-containerrelativeframe-and-layout)
+14. [PreviewProvider to the #Preview Macro](#14-previewprovider-to-the-preview-macro)
+15. [XCTest to Swift Testing](#15-xctest-to-swift-testing)
+16. [onDelete and EditButton to swipeActions](#16-ondelete-and-editbutton-to-swipeactions)
+17. [UIApplication.shared.open to openURL](#17-uiapplicationsharedopen-to-openurl)
+18. [@FetchRequest to @Query](#18-fetchrequest-to-query)
+19. [Type-Erased Returns to some and any](#19-type-erased-returns-to-some-and-any)
+20. [sheet(isPresented:) with an Optional to sheet(item:)](#20-sheetispresented-with-an-optional-to-sheetitem)
+21. [UIColor Interop to Asset Colors and Color.resolve](#21-uicolor-interop-to-asset-colors-and-colorresolve)
+22. [ForEach over a Range to Identifiable Data](#22-foreach-over-a-range-to-identifiable-data)
+23. [Toolbar Placements navigationBar to topBar](#23-toolbar-placements-navigationbar-to-topbar)
+24. [cornerRadius to clipShape](#24-cornerradius-to-clipshape)
+25. [tabItem to Tab (iOS 18)](#25-tabitem-to-tab-ios-18)
+26. [showsIndicators to scrollIndicators](#26-showsindicators-to-scrollindicators)
+
+## 1. NavigationView to NavigationStack
+
+`NavigationView` has been superseded since iOS 16 and is marked for deprecation
+(no compiler warning). Use `NavigationStack` (iOS 16+)
+for one column of pushed screens and `NavigationSplitView` for several columns.
+
+Before:
+
+```swift
+NavigationView {
+    List(courses) { course in
+        NavigationLink(destination: CourseDetail(course: course)) {
+            Text(course.title)
         }
-        .navigationViewStyle(.stack)
     }
 }
+.navigationViewStyle(.stack)
 ```
 
-### After (Modern)
+After:
 
 ```swift
-struct ContentView: View {
-    @State private var path: [Item] = []
+@State private var path: [Course] = []
 
-    var body: some View {
-        NavigationStack(path: $path) {
-            List(items) { item in
-                NavigationLink(value: item) {
-                    Text(item.title)
-                }
-            }
-            .navigationTitle("Items")
-            .navigationDestination(for: Item.self) { item in
-                DetailView(item: item)
-            }
-        }
+NavigationStack(path: $path) {
+    List(courses) { course in
+        NavigationLink(course.title, value: course)
     }
+    .navigationDestination(for: Course.self) { CourseDetail(course: $0) }
 }
 ```
 
-### Migration Notes
-
-NavigationStack gives you programmatic control over the navigation path via a binding. Value-based NavigationLink separates the trigger from the destination, keeping list rows lightweight. The `.navigationViewStyle(.stack)` modifier is no longer needed.
-
----
+- The path binding gives code full control over what is pushed.
+- A value-based `NavigationLink` separates the trigger from the destination, so
+  rows stay cheap.
+- `.navigationViewStyle(.stack)` is no longer needed.
 
-## NavigationView Sidebar to NavigationSplitView
+## 2. NavigationView Sidebar to NavigationSplitView
 
-### Before (Deprecated)
+Before:
 
 ```swift
-struct SidebarApp: View {
-    var body: some View {
-        NavigationView {
-            SidebarList()
-            DetailPlaceholder()
-        }
-        .navigationViewStyle(.columns)
-    }
+NavigationView {
+    TeamSidebar()
+    Text("Choose a team")
 }
+.navigationViewStyle(.columns)
 ```
 
-### After (Modern)
+After (iOS 16+):
 
 ```swift
-struct SidebarApp: View {
-    @State private var selectedCategory: Category?
-    @State private var selectedItem: Item?
+@State private var team: Team?
+@State private var player: Player?
 
-    var body: some View {
-        NavigationSplitView {
-            List(categories, selection: $selectedCategory) { category in
-                Label(category.name, systemImage: category.icon)
-            }
-            .navigationTitle("Categories")
-        } content: {
-            if let category = selectedCategory {
-                List(category.items, selection: $selectedItem) { item in
-                    Text(item.title)
-                }
-            } else {
-                ContentUnavailableView("Select a Category",
-                                       systemImage: "sidebar.left")
-            }
-        } detail: {
-            if let item = selectedItem {
-                DetailView(item: item)
-            } else {
-                ContentUnavailableView("Select an Item",
-                                       systemImage: "doc.text")
-            }
-        }
+NavigationSplitView {
+    List(teams, selection: $team) { NavigationLink($0.name, value: $0) }
+} content: {
+    if let team {
+        List(team.players, selection: $player) { NavigationLink($0.name, value: $0) }
+    } else {
+        ContentUnavailableView("No team selected", systemImage: "sidebar.left")
+    }
+} detail: {
+    if let player {
+        PlayerCard(player: player)
+    } else {
+        ContentUnavailableView("No player selected", systemImage: "doc.text")
     }
 }
 ```
 
-### Migration Notes
-
-NavigationSplitView explicitly models two-column and three-column layouts. Column visibility is controlled via `NavigationSplitViewVisibility` and `columnVisibility` bindings. On compact size classes the split view collapses into a NavigationStack automatically.
+- The split view states its two- or three-column layout explicitly.
+- Column visibility is a `NavigationSplitViewVisibility` value passed through
+  the `columnVisibility:` binding.
+- In compact size classes it collapses into a stack on its own.
 
----
+## 3. ObservableObject and @StateObject to @Observable and @State
 
-## ObservableObject / `@Published` / `@StateObject` to `@Observable` / `@State`
+The Observation framework (iOS 17+) replaces observation built on Combine. An
+`@Observable` class records which properties each view reads.
 
-The Observation framework (iOS 17+) replaces Combine-based observation. Classes annotated with `@Observable` track property access automatically -- no `@Published` wrappers needed.
-
-### Before (Superseded)
+Before:
 
 ```swift
-class UserSettings: ObservableObject {
-    @Published var username: String = ""
-    @Published var notificationsEnabled: Bool = true
-    @Published var theme: Theme = .system
-
-    func resetToDefaults() {
-        username = ""
-        notificationsEnabled = true
-        theme = .system
-    }
+final class ReaderSettings: ObservableObject {
+    @Published var fontSize = 16.0
+    @Published var isNightMode = false
+    @Published var typeface = "Serif"
+
+    func restoreDefaults() { fontSize = 16; isNightMode = false; typeface = "Serif" }
 }
 
-struct SettingsView: View {
-    @StateObject private var settings = UserSettings()
+struct ReaderSettingsView: View {
+    @StateObject private var settings = ReaderSettings()
 
     var body: some View {
         Form {
-            TextField("Username", text: $settings.username)
-            Toggle("Notifications", isOn: $settings.notificationsEnabled)
-            Picker("Theme", selection: $settings.theme) {
-                ForEach(Theme.allCases) { theme in
-                    Text(theme.rawValue).tag(theme)
-                }
+            Slider(value: $settings.fontSize, in: 12...32)
+            Toggle("Night mode", isOn: $settings.isNightMode)
+            Picker("Typeface", selection: $settings.typeface) {
+                Text("Serif").tag("Serif")
+                Text("Sans").tag("Sans")
             }
         }
     }
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-@Observable
-class UserSettings {
-    var username: String = ""
-    var notificationsEnabled: Bool = true
-    var theme: Theme = .system
-
-    func resetToDefaults() {
-        username = ""
-        notificationsEnabled = true
-        theme = .system
-    }
+@MainActor @Observable
+final class ReaderSettings {
+    var fontSize = 16.0
+    var isNightMode = false
+    var typeface = "Serif"
+
+    func restoreDefaults() { fontSize = 16; isNightMode = false; typeface = "Serif" }
 }
 
-struct SettingsView: View {
-    @State private var settings = UserSettings()
+struct ReaderSettingsView: View {
+    @State private var settings = ReaderSettings()
 
     var body: some View {
         Form {
-            TextField("Username", text: $settings.username)
-            Toggle("Notifications", isOn: $settings.notificationsEnabled)
-            Picker("Theme", selection: $settings.theme) {
-                ForEach(Theme.allCases) { theme in
-                    Text(theme.rawValue).tag(theme)
-                }
+            Slider(value: $settings.fontSize, in: 12...32)
+            Toggle("Night mode", isOn: $settings.isNightMode)
+            Picker("Typeface", selection: $settings.typeface) {
+                Text("Serif").tag("Serif")
+                Text("Sans").tag("Sans")
             }
         }
     }
 }
 ```
 
-### Migration Notes
+Steps:
 
-- Replace `ObservableObject` conformance with the `@Observable` macro.
-- Remove all `@Published` property wrappers -- observation is automatic.
-- Replace `@StateObject` with `@State` for owned instances.
-- Computed properties that depend on stored properties are tracked automatically.
-- The view only re-evaluates when properties it actually reads change, so fine-grained observation is free.
-- **Requires iOS 17+ minimum deployment target.** `ObservableObject` is not formally deprecated (no compiler warning) -- it is superseded. Do not rewrite working `ObservableObject` code if the project targets iOS 16 or earlier.
+1. Replace the `ObservableObject` conformance with the `@Observable` macro.
+2. Delete every `@Published`; tracking is automatic.
+3. Change owned instances from `@StateObject` to `@State`. The body stays as it was:
+   `$settings.fontSize` and the other bindings still work.
 
----
+Notes:
 
-## `@ObservedObject` to let / `@Bindable`
+- Computed properties built on stored ones are tracked without extra work.
+- A view re-evaluates only when a property it actually read changes, at no
+  extra cost.
+- Needs an iOS 17 deployment target.
+- `ObservableObject` is superseded, not formally deprecated, and the compiler
+  does not warn about it. On projects that target iOS 16 or earlier, leave
+  working `ObservableObject` code alone.
 
-### Before (Superseded)
+## 4. @ObservedObject to let or @Bindable
+
+Before:
 
 ```swift
-struct ProfileEditor: View {
-    @ObservedObject var profile: ProfileModel
+struct MemberCard: View {
+    @ObservedObject var member: Member
 
     var body: some View {
-        TextField("Name", text: $profile.name)
-        Toggle("Public", isOn: $profile.isPublic)
+        TextField("Nickname", text: $member.nickname)
+        Toggle("Visible", isOn: $member.isVisible)
     }
 }
 ```
 
-### After (Modern)
-
-When you only need to read properties, use a plain `let`:
+After, read only:
 
 ```swift
-struct ProfileDisplay: View {
-    let profile: ProfileModel  // @Observable class
-
-    var body: some View {
-        Text(profile.name)
-        Text(profile.isPublic ? "Public" : "Private")
-    }
+struct MemberBadge: View {
+    let member: Member
+    var body: some View { Text(member.nickname) }
 }
 ```
 
-When you need to create bindings, use `@Bindable`:
+After, with bindings:
 
 ```swift
-struct ProfileEditor: View {
-    @Bindable var profile: ProfileModel
+struct MemberCard: View {
+    @Bindable var member: Member
 
     var body: some View {
-        TextField("Name", text: $profile.name)
-        Toggle("Public", isOn: $profile.isPublic)
+        TextField("Nickname", text: $member.nickname)
+        Toggle("Visible", isOn: $member.isVisible)
     }
 }
 ```
 
-### Migration Notes
-
-With `@Observable`, you no longer need `@ObservedObject` to subscribe to changes. A plain `let` constant already triggers view updates when read properties change. Use `@Bindable` only when you need two-way bindings via `$` syntax.
+With `@Observable` types, `@ObservedObject` has no role. A plain `let` already
+updates the view for every property it reads; `@Bindable` is only for `$`
+bindings.
 
----
+## 5. @EnvironmentObject to @Environment
 
-## `@EnvironmentObject` to `@Environment`
-
-### Before (Superseded)
+Before:
 
 ```swift
-// Injection
-ContentView()
-    .environmentObject(authManager)
-
-// Usage
-struct ContentView: View {
-    @EnvironmentObject var auth: AuthManager
+RootView().environmentObject(session)
 
-    var body: some View {
-        if auth.isLoggedIn {
-            HomeView()
-        } else {
-            LoginView()
-        }
-    }
+struct GateView: View {
+    @EnvironmentObject var session: Session
+    var body: some View { session.isSignedIn ? AnyView(HomeView()) : AnyView(SignInView()) }
 }
 ```
 
-### After (Modern)
+After (iOS 17+):
 
 ```swift
-// Injection
-ContentView()
-    .environment(authManager)
+RootView().environment(session)
 
-// Usage
-struct ContentView: View {
-    @Environment(AuthManager.self) private var auth
+struct GateView: View {
+    @Environment(Session.self) private var session
 
     var body: some View {
-        if auth.isLoggedIn {
-            HomeView()
-        } else {
-            LoginView()
-        }
+        if session.isSignedIn { HomeView() } else { SignInView() }
     }
 }
 ```
 
-### Migration Notes
-
-With `@Observable`, use `.environment(_:)` (the type-keyed overload) instead of `.environmentObject(_:)`. Read with `@Environment(Type.self)`. If you need bindings from an environment-injected object, pull it into a local `@Bindable`:
+Bindings from an environment object come from a local `@Bindable` copy:
 
 ```swift
-struct ContentView: View {
-    @Environment(AuthManager.self) private var auth
-
-    var body: some View {
-        @Bindable var auth = auth
-        Toggle("Remember Me", isOn: $auth.rememberMe)
-    }
+var body: some View {
+    @Bindable var session = session
+    Toggle("Stay signed in", isOn: $session.staySignedIn)
 }
 ```
 
----
-
-## foregroundColor(_:) to foregroundStyle(_:)
-
-`foregroundColor(_:)` was deprecated in iOS 17. Its replacement, `foregroundStyle(_:)`, accepts any `ShapeStyle` -- not just `Color` -- enabling gradients, hierarchical styles, and materials directly.
-
-### Before (Deprecated)
-
-```swift
-Text("Hello")
-    .foregroundColor(.red)
-
-Text("Secondary")
-    .foregroundColor(.secondary)
-```
+## 6. foregroundColor to foregroundStyle
 
-### After (Modern)
+`foregroundColor(_:)` is marked for deprecation and renamed to
+`foregroundStyle(_:)`; the compiler does not warn yet. `foregroundStyle(_:)`
+(iOS 15+) takes any `ShapeStyle`, so gradients, hierarchical styles and
+materials work directly.
 
 ```swift
-Text("Hello")
-    .foregroundStyle(.red)
-
-Text("Secondary")
-    .foregroundStyle(.secondary)
-
-// Gradient -- not possible with foregroundColor
-Text("Gradient")
-    .foregroundStyle(
-        .linearGradient(colors: [.blue, .purple],
-                        startPoint: .leading, endPoint: .trailing)
-    )
+Text("Overdue").foregroundStyle(.red)
+Text("Updated 2 min ago").foregroundStyle(.secondary)
+Text("Premium")
+    .foregroundStyle(.linearGradient(colors: [.orange, .pink],
+                                     startPoint: .leading, endPoint: .trailing))
 ```
 
-### Migration Notes
+- Passing a `Color` is a drop-in replacement.
+- Also accepts `.tint`, `.selection` and the hierarchical `.primary`,
+  `.secondary`, `.tertiary`, `.quaternary`. A gradient was never possible with
+  `foregroundColor`.
+- `foregroundStyle(_:_:)` and `foregroundStyle(_:_:_:)` set two or three
+  hierarchy levels for child content in one call.
+- `NSAttributedString.Key.foregroundColor` is unrelated: it is the Foundation
+  and UIKit attribute key used with `NSAttributedString`, Core Text and PDF
+  rendering. It is not deprecated and has no SwiftUI counterpart.
 
-`foregroundStyle(_:)` is a drop-in replacement when passing a `Color`. The broader `ShapeStyle` conformance also accepts gradients, `.tint`, `.selection`, and hierarchical styles (`.primary`, `.secondary`, `.tertiary`, `.quaternary`). Multi-level variants `foregroundStyle(_:_:)` and `foregroundStyle(_:_:_:)` set hierarchical styles for child content in one call.
+## 7. Single-Value onChange to Two-Value onChange
 
-**Not to be confused with** `NSAttributedString.Key.foregroundColor` -- that is a UIKit/Foundation attributed-string key used for Core Text, `NSAttributedString`, and PDF rendering. It is not deprecated and has no SwiftUI equivalent.
-
----
-
-## .onChange(of:perform:) to Two-Value onChange
-
-The single-value `onChange` closure was deprecated in iOS 17. The new signature provides both the old and new values.
-
-### Before (Deprecated)
+The `onChange(of:perform:)` form whose closure takes one value is deprecated in
+iOS 17.
 
 ```swift
-.onChange(of: searchText) { newValue in
-    performSearch(newValue)
-}
-```
-
-### After (Modern)
+// Before
+.onChange(of: volume) { newVolume in player.setVolume(newVolume) }
 
-```swift
-.onChange(of: searchText) { oldValue, newValue in
-    performSearch(newValue)
+// After (iOS 17+)
+.onChange(of: volume) { oldVolume, newVolume in
+    if newVolume > oldVolume { showBoostHint = true }
+    player.setVolume(newVolume)
 }
+.onChange(of: volume) { _, newVolume in player.setVolume(newVolume) }
+.onChange(of: volume, initial: true) { _, newVolume in player.setVolume(newVolume) }
 ```
 
-If you only need the new value, use `_` for the old value:
-
-```swift
-.onChange(of: searchText) { _, newValue in
-    performSearch(newValue)
-}
-```
+- The closure receives the old and new values; write `_` for an old value you
+  do not use.
+- Comparing old and new inline removes the need for a helper state property.
+- `initial: true` also runs the closure when the view first appears.
 
-### Migration Notes
+## 8. ActionSheet to confirmationDialog
 
-The two-value variant lets you compare old and new values inline without maintaining extra state. The `initial` parameter is also available if you need the callback to fire on first appearance:
+Before:
 
 ```swift
-.onChange(of: searchText, initial: true) { _, newValue in
-    performSearch(newValue)
+.actionSheet(isPresented: $isAsking) {
+    ActionSheet(title: Text("Photo"), message: Text("Choose an action"), buttons: [
+        .default(Text("Save")) { save() },
+        .destructive(Text("Delete")) { delete() },
+        .cancel()
+    ])
 }
 ```
 
----
-
-## ActionSheet to confirmationDialog
-
-### Before (Deprecated)
+After (iOS 15+):
 
 ```swift
-.actionSheet(isPresented: $showingOptions) {
-    ActionSheet(
-        title: Text("Choose an action"),
-        message: Text("Select one of the options below"),
-        buttons: [
-            .default(Text("Share")) { shareItem() },
-            .destructive(Text("Delete")) { deleteItem() },
-            .cancel()
-        ]
-    )
-}
-```
-
-### After (Modern)
-
-```swift
-.confirmationDialog("Choose an action",
-                     isPresented: $showingOptions,
-                     titleVisibility: .visible) {
-    Button("Share") { shareItem() }
-    Button("Delete", role: .destructive) { deleteItem() }
-    Button("Cancel", role: .cancel) {}
+.confirmationDialog("Photo", isPresented: $isAsking, titleVisibility: .visible) {
+    Button("Save", action: save)
+    Button("Delete", role: .destructive, action: delete)
+    Button("Cancel", role: .cancel) { }
 } message: {
-    Text("Select one of the options below")
+    Text("Choose an action")
 }
 ```
 
-### Migration Notes
+- Regular `Button` views with roles replace the `ActionSheet.Button` array.
+- `titleVisibility` controls the title; on iOS it is hidden by default.
+- A cancel button is added for you when you leave it out.
 
-`.confirmationDialog` uses standard SwiftUI `Button` views with roles instead of an array of `ActionSheet.Button`. The `titleVisibility` parameter controls whether the title appears (it is hidden by default on iOS). A cancel-role button is added automatically if you omit one.
+## 9. Legacy Alert to alert with Actions
 
----
-
-## Alert (Legacy) to Modern .alert with Actions
-
-### Before (Deprecated)
+Before:
 
 ```swift
-.alert(isPresented: $showingAlert) {
-    Alert(
-        title: Text("Delete Item?"),
-        message: Text("This action cannot be undone."),
-        primaryButton: .destructive(Text("Delete")) { deleteItem() },
-        secondaryButton: .cancel()
-    )
+.alert(isPresented: $confirmLeave) {
+    Alert(title: Text("Leave group?"),
+          message: Text("You can rejoin later."),
+          primaryButton: .destructive(Text("Leave")) { leaveGroup() },
+          secondaryButton: .cancel())
 }
 ```
 
-### After (Modern)
+After (iOS 15+):
 
 ```swift
-.alert("Delete Item?", isPresented: $showingAlert) {
-    Button("Delete", role: .destructive) { deleteItem() }
-    Button("Cancel", role: .cancel) {}
+.alert("Leave group?", isPresented: $confirmLeave) {
+    Button("Leave", role: .destructive, action: leaveGroup)
+    Button("Cancel", role: .cancel) { }
 } message: {
-    Text("This action cannot be undone.")
+    Text("You can rejoin later.")
 }
 ```
 
-With a data item:
+Passing the data being confirmed:
 
 ```swift
-.alert("Delete Item?", isPresented: $showingAlert, presenting: itemToDelete) { item in
-    Button("Delete", role: .destructive) { delete(item) }
-} message: { item in
-    Text("Delete \"\(item.title)\"? This cannot be undone.")
+.alert("Remove device?", isPresented: $confirmRemoval, presenting: pendingDevice) { device in
+    Button("Remove \(device.name)", role: .destructive) { remove(device) }
+} message: { device in
+    Text("\(device.name) will be signed out.")
 }
 ```
 
-### Migration Notes
-
-The modern alert API accepts a `presenting` parameter to pass data directly into the alert closures, eliminating the need for separate optional state tracking.
+With `presenting:`, both closures receive the item, so no separate optional
+state has to be tracked.
 
----
+## 10. AnyView to @ViewBuilder and Concrete Types
 
-## AnyView to `@ViewBuilder` and Concrete Types
-
-### Before (Deprecated Pattern)
+Before:
 
 ```swift
-func destination(for route: Route) -> AnyView {
-    switch route {
-    case .home: return AnyView(HomeView())
-    case .profile: return AnyView(ProfileView())
-    case .settings: return AnyView(SettingsView())
+func screen(for step: CheckoutStep) -> AnyView {
+    switch step {
+    case .cart: AnyView(CartView())
+    case .address: AnyView(AddressView())
+    case .payment: AnyView(PaymentView())
     }
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
 @ViewBuilder
-func destination(for route: Route) -> some View {
-    switch route {
-    case .home: HomeView()
-    case .profile: ProfileView()
-    case .settings: SettingsView()
+func screen(for step: CheckoutStep) -> some View {
+    switch step {
+    case .cart: CartView()
+    case .address: AddressView()
+    case .payment: PaymentView()
     }
 }
 ```
 
-### Migration Notes
-
-`AnyView` erases type information, preventing SwiftUI from efficiently diffing and transitioning views. `@ViewBuilder` preserves concrete types, enabling the framework to optimize identity and transitions. Avoid `AnyView` unless interfacing with APIs that genuinely require heterogeneous view storage. In iOS 26, `AnyView` continues to work but remains a performance anti-pattern.
-
----
-
-## .onAppear + Manual Task to .task
+- `AnyView` hides the concrete type, which blocks efficient diffing and
+  transitions. `@ViewBuilder` keeps the types, so SwiftUI can preserve identity
+  and animate between branches.
+- Keep `AnyView` for APIs that really must store views of different types in
+  one collection.
+- On iOS 26 `AnyView` still works and is still a performance anti-pattern.
 
-### Before (Deprecated Pattern)
+## 11. onAppear with Task to .task
 
 ```swift
-struct FeedView: View {
-    @State private var posts: [Post] = []
-
-    var body: some View {
-        List(posts) { post in
-            PostRow(post: post)
-        }
-        .onAppear {
-            Task {
-                posts = try await fetchPosts()
-            }
-        }
-    }
+// Before
+.onAppear {
+    Task { receipts = try await ledger.receipts() }
 }
-```
-
-### After (Modern)
 
-```swift
-struct FeedView: View {
-    @State private var posts: [Post] = []
-
-    var body: some View {
-        List(posts) { post in
-            PostRow(post: post)
-        }
-        .task {
-            do {
-                posts = try await fetchPosts()
-            } catch {
-                // handle error
-            }
-        }
-    }
+// After
+.task {
+    do { receipts = try await ledger.receipts() }
+    catch { loadError = error }
 }
-```
-
-### Migration Notes
 
-`.task` automatically cancels the async work when the view disappears, preventing retain cycles and stale updates. Use `.task(id:)` to re-run the task when a dependency changes:
-
-```swift
-.task(id: selectedCategory) {
-    posts = try? await fetchPosts(for: selectedCategory)
+// Re-run when a dependency changes
+.task(id: selectedMonth) {
+    receipts = (try? await ledger.receipts(in: selectedMonth)) ?? []
 }
 ```
 
----
+`.task` cancels its work when the view disappears, which avoids retain cycles
+and updates to views that are gone. `.task(id:)` restarts when the id changes.
 
-## `@Environment(\.presentationMode)` to `@Environment(\.dismiss)`
-
-### Before (Deprecated)
+## 12. presentationMode to dismiss
 
 ```swift
-struct DetailView: View {
-    @Environment(\.presentationMode) var presentationMode
+// Before
+@Environment(\.presentationMode) var presentationMode
+Button("Close") { presentationMode.wrappedValue.dismiss() }
 
-    var body: some View {
-        Button("Done") {
-            presentationMode.wrappedValue.dismiss()
-        }
-    }
-}
+// After (iOS 15+)
+@Environment(\.dismiss) private var dismiss
+Button("Close") { dismiss() }
 ```
 
-### After (Modern)
+- `dismiss` is a `DismissAction` that you call directly; there is no
+  `wrappedValue`.
+- It closes sheets, full-screen covers and pushed navigation destinations.
 
-```swift
-struct DetailView: View {
-    @Environment(\.dismiss) private var dismiss
+## 13. GeometryReader Overuse to containerRelativeFrame and Layout
 
-    var body: some View {
-        Button("Done") {
-            dismiss()
-        }
-    }
-}
-```
-
-### Migration Notes
-
-`dismiss` is a callable `DismissAction`. Call it directly -- no `.wrappedValue` needed. Works for sheets, full-screen covers, and navigation push destinations.
-
----
+`GeometryReader` has a performance cost and makes layout harder to compose.
+The `Layout` protocol arrived in iOS 16 and `containerRelativeFrame` in iOS 17
+for sizing relative to a container.
 
-## GeometryReader Overuse to Layout Protocol and containerRelativeFrame
-
-GeometryReader has performance costs and complicates layout. iOS 16 introduced the Layout protocol, and iOS 17 added `containerRelativeFrame` for proportional sizing.
-
-### Before (Deprecated Pattern)
+Before:
 
 ```swift
 GeometryReader { proxy in
     HStack(spacing: 0) {
-        SidePanel()
-            .frame(width: proxy.size.width * 0.3)
-        MainContent()
-            .frame(width: proxy.size.width * 0.7)
+        MapPanel().frame(width: proxy.size.width * 0.65)
+        DetailsPanel().frame(width: proxy.size.width * 0.35)
     }
 }
 ```
 
-### After (Modern) -- containerRelativeFrame (iOS 17+)
+After, iOS 17+:
 
 ```swift
 HStack(spacing: 0) {
-    SidePanel()
-        .containerRelativeFrame(.horizontal) { length, _ in
-            length * 0.3
-        }
-    MainContent()
-        .containerRelativeFrame(.horizontal) { length, _ in
-            length * 0.7
-        }
+    MapPanel().containerRelativeFrame(.horizontal) { width, _ in width * 0.65 }
+    DetailsPanel().containerRelativeFrame(.horizontal) { width, _ in width * 0.35 }
 }
 ```
 
-### After (Modern) -- Custom Layout (iOS 16+)
+After, iOS 16+ with a custom layout:
 
 ```swift
-struct ProportionalHStack: Layout {
-    var ratios: [CGFloat]
+struct WeightedRow: Layout {
+    var weights: [CGFloat]
 
     func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
         proposal.replacingUnspecifiedDimensions()
     }
 
-    func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
-        guard subviews.count == ratios.count else { return }
+    func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize,
+                       subviews: Subviews, cache: inout ()) {
+        guard weights.count == subviews.count else { return }
+        let total = weights.reduce(0, +)
         var x = bounds.minX
-        for (index, subview) in subviews.enumerated() {
-            let width = bounds.width * ratios[index]
+        for (subview, weight) in zip(subviews, weights) {
+            let width = bounds.width * weight / total
             subview.place(at: CGPoint(x: x, y: bounds.minY),
                           proposal: ProposedViewSize(width: width, height: bounds.height))
             x += width
         }
     }
 }
-
-// Usage
-ProportionalHStack(ratios: [0.3, 0.7]) {
-    SidePanel()
-    MainContent()
-}
 ```
 
-### Migration Notes
-
-GeometryReader is still appropriate when you genuinely need to read the proposed size and cannot express the layout declaratively. For proportional sizing, prefer `containerRelativeFrame`. For custom arrangements, prefer the Layout protocol. Both avoid the bottom-up sizing behavior that makes GeometryReader tricky to compose.
+- `GeometryReader` is still right when you truly must read the proposed size
+  and cannot state the layout declaratively.
+- Proportional sizing: `containerRelativeFrame`. Custom arrangements: the
+  `Layout` protocol. Both avoid the bottom-up sizing of `GeometryReader` that
+  makes composition difficult.
 
----
+## 14. PreviewProvider to the #Preview Macro
 
-## UIHostingController Previews to #Preview Macro
-
-### Before (Deprecated)
+Before:
 
 ```swift
-struct ContentView_Previews: PreviewProvider {
+struct BoardingPassView_Previews: PreviewProvider {
     static var previews: some View {
-        ContentView()
-            .previewDevice("iPhone 15 Pro")
-
-        ContentView()
+        BoardingPassView(pass: .sample)
+            .previewDevice("iPhone 16 Pro")
             .preferredColorScheme(.dark)
     }
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-#Preview("Light Mode") {
-    ContentView()
+#Preview("Light") {
+    BoardingPassView(pass: .sample)
 }
 
-#Preview("Dark Mode") {
-    ContentView()
+#Preview("Dark") {
+    BoardingPassView(pass: .sample)
         .preferredColorScheme(.dark)
 }
 ```
 
-Widget and UIKit previews:
+Widgets and UIKit:
 
 ```swift
-#Preview("Timeline Entry", as: .systemSmall) {
-    MyWidget()
+#Preview("Small", as: .systemSmall) {
+    StepsWidget()
 } timeline: {
-    SimpleEntry(date: .now)
+    StepsEntry(date: .now, steps: 4_200)
 }
 
-#Preview("UIKit Controller") {
-    let vc = MyViewController()
-    vc.title = "Preview"
-    return vc
+#Preview {
+    let controller = ScannerViewController()
+    controller.title = "Scanner"
+    return controller
 }
 ```
 
-### Migration Notes
-
-The `#Preview` macro (iOS 17+) is less boilerplate and supports naming each preview directly. It works with SwiftUI views, UIKit view controllers, and WidgetKit timelines. Delete the entire `PreviewProvider` struct and replace with `#Preview` blocks.
-
----
+- `#Preview` needs Xcode 15 and less boilerplate, and names each preview
+  directly. SwiftUI view previews work with any deployment target; the UIKit
+  and WidgetKit forms need iOS 17.
+- Migration: delete the whole `PreviewProvider` struct and write `#Preview`
+  blocks in its place.
 
-## XCTest to Swift Testing
+## 15. XCTest to Swift Testing
 
-Swift Testing (Xcode 16+) provides a modern, expressive test framework that coexists with XCTest.
+Swift Testing needs Xcode 16 and runs alongside XCTest.
 
-### Before (XCTest)
+Before:
 
 ```swift
-import XCTest
-@testable import MyApp
+final class FareCalculatorTests: XCTestCase {
+    var calculator: FareCalculator!
 
-final class CartTests: XCTestCase {
-    var cart: Cart!
-
-    override func setUp() {
-        cart = Cart()
-    }
-
-    override func tearDown() {
-        cart = nil
-    }
+    override func setUp() { calculator = FareCalculator(currency: "EUR") }
+    override func tearDown() { calculator = nil }
 
-    func testAddItem() throws {
-        cart.add(Item(name: "Widget", price: 9.99))
-        XCTAssertEqual(cart.items.count, 1)
-        XCTAssertEqual(cart.total, 9.99, accuracy: 0.01)
+    func testBaseFare() {
+        XCTAssertEqual(calculator.fare(km: 10), 12.5, accuracy: 0.001)
     }
 
-    func testEmptyCartTotal() {
-        XCTAssertEqual(cart.total, 0)
-    }
-
-    func testDiscountCodes() throws {
-        let codes = ["SAVE10", "SAVE20", "SAVE50"]
-        for code in codes {
-            cart.applyDiscount(code: code)
-            XCTAssertTrue(cart.hasDiscount)
+    func testFaresArePositive() {
+        for km in [1, 5, 50] {
+            XCTAssertTrue(calculator.fare(km: km) > 0)
         }
     }
 }
 ```
 
-### After (Swift Testing)
+After:
 
 ```swift
 import Testing
-@testable import MyApp
 
-@Suite("Cart Tests")
-struct CartTests {
-    let cart = Cart()
-
-    @Test("Adding an item updates count and total")
-    func addItem() {
-        cart.add(Item(name: "Widget", price: 9.99))
-        #expect(cart.items.count == 1)
-        #expect(cart.total.isApproximatelyEqual(to: 9.99))
-    }
+@Suite("Fare calculator")
+struct FareCalculatorTests {
+    let calculator = FareCalculator(currency: "EUR")
 
-    @Test("Empty cart has zero total")
-    func emptyCartTotal() {
-        #expect(cart.total == 0)
+    @Test("Base fare for ten kilometres")
+    func baseFare() {
+        #expect(abs(calculator.fare(km: 10) - 12.5) < 0.001)
     }
 
-    @Test("Discount codes", arguments: ["SAVE10", "SAVE20", "SAVE50"])
-    func discountCodes(code: String) {
-        cart.applyDiscount(code: code)
-        #expect(cart.hasDiscount)
+    @Test("Fares are positive", arguments: [1, 5, 50])
+    func positive(km: Int) {
+        #expect(calculator.fare(km: km) > 0)
     }
 }
 ```
 
-### Migration Notes
+Steps:
 
-- Replace `XCTestCase` subclass with a plain struct annotated with `@Suite`.
-- Replace `setUp` / `tearDown` with an initializer and deinit (or just inline setup).
-- Replace `XCTAssert*` macros with `#expect(...)` and `#require(...)`.
-- Use `@Test("description", arguments:)` for parameterized tests instead of manual loops.
-- Swift Testing and XCTest targets can coexist in the same project during migration.
-- Use `@Test(.disabled("reason"))` instead of `XCTSkip`.
+1. Replace the `XCTestCase` subclass with a struct marked `@Suite`.
+2. Move `setUp` work into `init` or into stored property defaults. For
+   teardown, make the suite a `final class` or an `actor` and use `deinit`; a
+   plain struct cannot have one.
+3. Replace `XCTAssert*` calls with `#expect(...)`, and use `#require(...)` where
+   the test cannot continue without a value.
+4. Replace loops with `@Test("description", arguments:)`.
 
----
+Notes:
 
-## List EditButton to .swipeActions, .onMove, .onDelete
+- XCTest and Swift Testing targets can live in the same project during the
+  move.
+- `@Test(.disabled("reason"))` takes the place of skipping with `XCTSkip`;
+  `.enabled(if:)` covers conditional skips.
 
-### Before (Deprecated Pattern)
+## 16. onDelete and EditButton to swipeActions
 
-```swift
-struct ItemList: View {
-    @State private var items = ["A", "B", "C"]
+Before:
 
-    var body: some View {
-        NavigationView {
-            List {
-                ForEach(items, id: \.self) { item in
-                    Text(item)
-                }
-                .onDelete { items.remove(atOffsets: $0) }
-                .onMove { items.move(fromOffsets: $0, toOffset: $1) }
-            }
-            .navigationTitle("Items")
-            .toolbar { EditButton() }
-        }
+```swift
+NavigationView {
+    List {
+        ForEach(alarms) { AlarmRow(alarm: $0) }
+            .onDelete { alarms.remove(atOffsets: $0) }
+            .onMove { alarms.move(fromOffsets: $0, toOffset: $1) }
     }
+    .toolbar { EditButton() }
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-struct ItemList: View {
-    @State private var items = ["A", "B", "C"]
-
-    var body: some View {
-        NavigationStack {
-            List {
-                ForEach(items, id: \.self) { item in
-                    Text(item)
-                        .swipeActions(edge: .trailing, allowsFullSwipe: true) {
-                            Button("Delete", role: .destructive) {
-                                if let index = items.firstIndex(of: item) {
-                                    items.remove(at: index)
-                                }
-                            }
-                        }
-                        .swipeActions(edge: .leading) {
-                            Button("Pin", systemImage: "pin") {
-                                pinItem(item)
-                            }
-                            .tint(.orange)
-                        }
+NavigationStack {
+    List {
+        ForEach(alarms) { alarm in
+            AlarmRow(alarm: alarm)
+                .swipeActions(edge: .trailing, allowsFullSwipe: true) {
+                    Button("Delete", role: .destructive) { remove(alarm) }
+                }
+                .swipeActions(edge: .leading) {
+                    Button("Snooze") { snooze(alarm) }.tint(.orange)
                 }
-                .onMove { items.move(fromOffsets: $0, toOffset: $1) }
-            }
-            .navigationTitle("Items")
-            .toolbar { EditButton() }
         }
+        .onMove { alarms.move(fromOffsets: $0, toOffset: $1) }
     }
+    .toolbar { EditButton() }
 }
 ```
 
-### Migration Notes
-
-`.swipeActions` (iOS 15+) gives you per-row, multi-action swipe menus with custom tints and roles. `EditButton` and `.onMove` still work fine for reorder mode. The main migration is replacing `.onDelete` with a `.swipeActions` destructive button for richer swipe UX.
+- `.swipeActions` (iOS 15+) supports several actions per row, each with its own
+  tint and role.
+- `EditButton` and `.onMove` are still fine for reordering. The main change is
+  turning `.onDelete` into a destructive swipe action.
 
----
-
-## UIApplication.shared.open to `@Environment(\.openURL)`
-
-### Before (Deprecated Pattern)
+## 17. UIApplication.shared.open to openURL
 
 ```swift
-Button("Open Website") {
-    if let url = URL(string: "https://example.com") {
-        UIApplication.shared.open(url)
-    }
-}
-```
-
-### After (Modern)
+// Before
+Button("Terms") { UIApplication.shared.open(termsURL) }
 
-```swift
-struct LinkButton: View {
-    @Environment(\.openURL) private var openURL
+// After
+@Environment(\.openURL) private var openURL
+Button("Terms") { openURL(termsURL) }
 
-    var body: some View {
-        Button("Open Website") {
-            openURL(URL(string: "https://example.com")!)
-        }
-    }
-}
-```
-
-With a completion handler:
-
-```swift
-openURL(url) { accepted in
-    if !accepted {
-        // handle failure to open URL
+// Handling failure
+Button("Terms") {
+    openURL(termsURL) { opened in
+        if !opened { showLinkError = true }
     }
 }
 ```
 
-### Migration Notes
+- `openURL` works on every Apple platform, and it can be replaced in the
+  environment to intercept or test link handling.
+- Keep `UIApplication.shared` out of SwiftUI views.
 
-`@Environment(\.openURL)` works on all Apple platforms, not just iOS. It can be overridden in the environment for testing or to intercept URL opens. Avoid reaching for `UIApplication.shared` in SwiftUI views.
+## 18. @FetchRequest to @Query
 
----
+Once the models move from Core Data to SwiftData, the `@Query` macro (iOS 17+)
+supersedes `@FetchRequest`.
 
-## `@FetchRequest` to #Query (SwiftData)
-
-Core Data's `@FetchRequest` is superseded by SwiftData's `@Query` macro when you migrate to SwiftData models.
-
-### Before (Core Data)
+Before:
 
 ```swift
-struct ItemListView: View {
-    @FetchRequest(
-        sortDescriptors: [NSSortDescriptor(keyPath: \CDItem.timestamp, ascending: false)],
-        predicate: NSPredicate(format: "isCompleted == NO")
-    ) private var items: FetchedResults<CDItem>
-
-    var body: some View {
-        List(items) { item in
-            Text(item.title ?? "")
-        }
-    }
-}
+@FetchRequest(
+    sortDescriptors: [NSSortDescriptor(keyPath: \CDExpense.date, ascending: false)],
+    predicate: NSPredicate(format: "amount > %f", 100.0)
+)
+private var expenses: FetchedResults<CDExpense>
 ```
 
-### After (SwiftData)
+After:
 
 ```swift
-struct ItemListView: View {
-    @Query(
-        filter: #Predicate<Item> { !$0.isCompleted },
-        sort: \.timestamp,
-        order: .reverse
-    ) private var items: [Item]
-
-    var body: some View {
-        List(items) { item in
-            Text(item.title)
-        }
-    }
-}
+@Query(filter: #Predicate<Expense> { $0.amount > 100 },
+       sort: \.date, order: .reverse)
+private var expenses: [Expense]
 ```
 
-### Migration Notes
-
-`@Query` uses type-safe `#Predicate` instead of string-based `NSPredicate`. Sort descriptors use key paths directly. The model container is injected via `.modelContainer(for:)` on an ancestor view. SwiftData models are plain Swift classes with the `@Model` macro rather than NSManagedObject subclasses.
-
----
+- `#Predicate` is checked by the compiler, unlike a format string, and sorting
+  takes key paths directly.
+- An ancestor view supplies the container with `.modelContainer(for:)`.
+- SwiftData models are ordinary Swift classes marked `@Model`, not
+  `NSManagedObject` subclasses.
 
-## Opaque return types to some/any clarifications (Swift 5.7+)
+## 19. Type-Erased Returns to some and any
 
-### Before
+Before:
 
 ```swift
-func makeView() -> AnyView {
-    AnyView(Text("Hello"))
-}
+func makeHeader() -> AnyView { AnyView(Text("Inbox")) }
 
-protocol DataSource {
-    func fetch() -> AnyPublisher<[Item], Error>
+protocol MessageSource {
+    func messages() -> AnyPublisher<[Message], Error>
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-func makeView() -> some View {
-    Text("Hello")
-}
+func makeHeader() -> some View { Text("Inbox") }
 
-protocol DataSource {
-    func fetch() async throws -> [Item]
+protocol MessageSource: Sendable {
+    func messages() async throws -> [Message]
 }
 
-// When you need a protocol-typed variable:
-let source: any DataSource = RemoteDataSource()
-```
-
-### Migration Notes
-
-Use `some` for opaque return types when the concrete type is fixed. Use `any` for existentials when you need to store heterogeneous conformances. Prefer `async throws` over Combine publishers for new code. Swift 5.7+ allows `some` in parameter position too:
-
-```swift
-func display(_ view: some View) { ... }
+let source: any MessageSource = RemoteMessageSource()
 ```
 
----
+- `some` marks an opaque result whose concrete type is fixed. `any` marks an
+  existential that can hold different conforming types.
+- In new code, prefer `async throws` to Combine publishers.
+- Since Swift 5.7, `some` works in parameter position:
+  `func present(_ content: some View)`.
 
-## .sheet(item:) with Optional Identifiable to Modern Pattern
+## 20. sheet(isPresented:) with an Optional to sheet(item:)
 
-### Before (Fragile Pattern)
+Before, two pieces of state that can disagree:
 
 ```swift
-@State private var selectedItem: Item?
-@State private var showingSheet = false
-
-Button {
-    selectedItem = item
-    showingSheet = true
-} label: {
-    ItemRow(item: item)
-}
-.buttonStyle(.plain)
-.sheet(isPresented: $showingSheet) {
-    if let item = selectedItem {
-        DetailView(item: item)
-    }
+@State private var editingNote: Note?
+@State private var isEditing = false
+
+.sheet(isPresented: $isEditing) {
+    if let editingNote { NoteEditor(note: editingNote) }
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-@State private var selectedItem: Item?
+@State private var editingNote: Note?
 
-Button {
-    selectedItem = item
-} label: {
-    ItemRow(item: item)
-}
-.buttonStyle(.plain)
-.sheet(item: $selectedItem) { item in
-    DetailView(item: item)
+.sheet(item: $editingNote) { note in
+    NoteEditor(note: note)
 }
 ```
 
-### Migration Notes
+- `.sheet(item:)` removes the chance of the flag and the value falling out of
+  step.
+- The sheet appears when the binding becomes non-nil and closes when it
+  returns to nil; the closure receives the unwrapped value.
 
-Using `.sheet(item:)` eliminates the dual-state problem where `showingSheet` and `selectedItem` can become out of sync. The sheet presents when the binding becomes non-nil and dismisses when it becomes nil. The unwrapped value is passed directly into the closure.
+## 21. UIColor Interop to Asset Colors and Color.resolve
 
----
+Building a `Color` from components, directly or through
+`Color(uiColor: UIColor(red:green:blue:alpha:))`, is still fine. Better
+options exist for the two common needs:
 
-## UIColor / Color(UIColor:) to Color ShaderLibrary (iOS 17+)
-
-### Before
+- Fixed brand colors: an asset catalog color such as `Color("Ocean")` is always
+  the first choice; it carries light, dark and high-contrast variants.
+- Reading actual components at runtime: `Color.resolve(in:)` (iOS 17+) returns
+  a `Color.Resolved` with `red`, `green`, `blue` and `opacity` for the current
+  environment. That covers most of the reasons code used to drop into
+  `UIColor`.
 
 ```swift
-let color = UIColor(red: 0.2, green: 0.5, blue: 0.8, alpha: 1.0)
-let swiftUIColor = Color(uiColor: color)
-```
-
-### After (Modern)
-
-Color initialization from components is still fine, but for dynamic colors prefer:
+struct ContrastBadge: View {
+    @Environment(\.self) private var environment
+    let tint: Color
 
-```swift
-// Custom colors via asset catalogs (always preferred)
-let brand = Color("BrandBlue")
-
-// Resolved colors for interop (iOS 17+)
-@Environment(\.self) var environment
-
-let resolved = Color.blue.resolve(in: environment)
-// resolved.red, resolved.green, resolved.blue, resolved.opacity
+    var body: some View {
+        let resolved = tint.resolve(in: environment)
+        let lightBackground = (resolved.red + resolved.green + resolved.blue) / 3 > 0.6
+        Text("New")
+            .padding(6)
+            .background(tint)
+            .foregroundStyle(lightBackground ? .black : .white)
+    }
+}
 ```
 
-### Migration Notes
-
-`Color.resolve(in:)` (iOS 17+) gives you concrete RGBA values in the current environment, replacing many UIColor interop needs. For custom runtime color manipulations, use resolved colors. For static brand colors, use asset catalogs.
+Use resolved colors for runtime manipulation and asset catalogs for static
+brand colors.
 
----
+## 22. ForEach over a Range to Identifiable Data
 
-## ForEach with Range to ForEach with Identifiable / indices
-
-### Before (Fragile Pattern)
+Before:
 
 ```swift
-ForEach(0..<items.count) { index in
-    Text(items[index].name)
+ForEach(0..<songs.count) { index in
+    Text(songs[index].title)
 }
 ```
 
-### After (Modern)
+After:
 
 ```swift
-// Identifiable models
-ForEach(items) { item in
-    Text(item.name)
+ForEach(songs) { song in
+    Text(song.title)
 }
 
-// When you need the index
-ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
-    Text("\(index + 1). \(item.name)")
+ForEach(Array(songs.enumerated()), id: \.element.id) { position, song in
+    Text("\(position + 1). \(song.title)")
 }
 
-// Subranges with bindable access
-ForEach($items) { $item in
-    TextField("Name", text: $item.name)
+ForEach($songs) { $song in
+    TextField("Title", text: $song.title)
 }
 ```
 
-### Migration Notes
-
-Constant-range `ForEach(0..<n)` is only safe when the range never changes. For dynamic data, always use identifiable collections. `ForEach($items)` provides direct bindings to each element without index arithmetic.
-
----
-
-## .toolbar placement consolidation (iOS 26)
+- `ForEach(0..<n)` is safe only when the range is constant. Data that can
+  change needs an identifiable collection. The Before code draws a compiler
+  warning: "non-constant range: argument must be an integer literal".
+- `ForEach($items)` hands out a binding per element without index arithmetic.
 
-### Before
+## 23. Toolbar Placements navigationBar to topBar
 
 ```swift
-.toolbar {
-    ToolbarItem(placement: .navigationBarLeading) {
-        Button("Back") { dismiss() }
-    }
-    ToolbarItem(placement: .navigationBarTrailing) {
-        Button("Edit") { isEditing.toggle() }
-    }
-    ToolbarItem(placement: .bottomBar) {
-        Button("Add") { addItem() }
-    }
-}
-```
-
-### After (Modern)
+// Before
+ToolbarItem(placement: .navigationBarLeading) { closeButton }
+ToolbarItem(placement: .navigationBarTrailing) { saveButton }
 
-```swift
-.toolbar {
-    ToolbarItem(placement: .topBarLeading) {
-        Button("Back") { dismiss() }
-    }
-    ToolbarItem(placement: .topBarTrailing) {
-        Button("Edit") { isEditing.toggle() }
-    }
-    ToolbarItem(placement: .bottomBar) {
-        Button("Add") { addItem() }
-    }
-}
+// After
+ToolbarItem(placement: .topBarLeading) { closeButton }
+ToolbarItem(placement: .topBarTrailing) { saveButton }
+ToolbarItem(placement: .bottomBar) { statusText }
 ```
 
-### Migration Notes
+- `.topBarLeading` and `.topBarTrailing` arrived with the iOS 17 SDK and are
+  back-deployed to iOS 14, so they work wherever the old names did. The
+  `.navigationBar` names are marked for deprecation in their favour. `.bottomBar` is
+  unchanged.
+- The new names behave the same in `NavigationStack` and `NavigationSplitView`.
+  Prefer them for consistency across platforms.
 
-`.navigationBarLeading` and `.navigationBarTrailing` were renamed to `.topBarLeading` and `.topBarTrailing` (iOS 16+). The new names work consistently across NavigationStack and NavigationSplitView contexts. Prefer the new names for cross-platform consistency.
+## 24. cornerRadius to clipShape
 
----
-
-## cornerRadius to clipShape(.rect(cornerRadius:))
-
-`.cornerRadius(_:)` was deprecated in iOS 17.
-
-### Before (Deprecated)
-
-```swift
-RoundedRectangle(cornerRadius: 12)
-    .cornerRadius(12)
-
-Image("photo")
-    .cornerRadius(8)
-```
-
-### After (Modern)
+`.cornerRadius(_:)` is marked for deprecation (no compiler warning yet); Apple
+points to `clipShape` instead.
 
 ```swift
-RoundedRectangle(cornerRadius: 12)
+Rectangle()
+    .fill(.blue)
+    .frame(width: 80, height: 80)
     .clipShape(.rect(cornerRadius: 12))
 
-Image("photo")
-    .clipShape(.rect(cornerRadius: 8))
-```
-
-### Migration Notes
+Image("cover")
+    .resizable()
+    .scaledToFill()
+    .clipShape(.rect(cornerRadius: 20))
 
-`clipShape(.rect(cornerRadius:))` uses `RoundedRectangle` under the hood and also supports `cornerRadii` for per-corner control (iOS 16+):
-
-```swift
-.clipShape(.rect(cornerRadii: .init(topLeading: 12, bottomTrailing: 12)))
+Color.orange
+    .clipShape(.rect(cornerRadii: .init(topLeading: 16, bottomTrailing: 16)))
 ```
 
----
+- `.rect(cornerRadius:)` is a `RoundedRectangle`.
+- `.rect(cornerRadii:)` is an `UnevenRoundedRectangle` with a radius per corner.
+- Both shape shorthands need iOS 17. On iOS 16, write
+  `.clipShape(RoundedRectangle(cornerRadius: 12))`.
 
-## tabItem to Tab (iOS 18+)
+## 25. tabItem to Tab (iOS 18)
 
-The `tabItem` modifier approach was superseded by the `Tab` type inside `TabView` (iOS 18+).
-
-### Before (Legacy)
+The `Tab` type inside `TabView` (iOS 18+) supersedes the `.tabItem` modifier.
 
 ```swift
+// Before
 TabView {
-    HomeView()
-        .tabItem {
-            Label("Home", systemImage: "house")
-        }
-    SettingsView()
-        .tabItem {
-            Label("Settings", systemImage: "gear")
-        }
+    TodayView().tabItem { Label("Today", systemImage: "sun.max") }
+    HistoryView().tabItem { Label("History", systemImage: "clock") }
 }
-```
-
-### After (Modern  -  iOS 18+)
 
-```swift
-TabView {
-    Tab("Home", systemImage: "house") {
-        HomeView()
-    }
-    Tab("Settings", systemImage: "gear") {
-        SettingsView()
+// After
+TabView(selection: $selectedTab) {
+    Tab("Today", systemImage: "sun.max", value: .today) { TodayView() }
+    Tab("History", systemImage: "clock", value: .history) { HistoryView() }
+    TabSection("Collections") {
+        Tab("Favorites", systemImage: "star", value: AppTab.favorites) { FavoritesView() }
     }
 }
 ```
 
-### Migration Notes
-
-`Tab` provides a cleaner API and is required for the new tab sidebar on iPadOS 18+. The `tabItem` modifier still works but does not support the sidebar presentation. Use `Tab` with a `value` parameter and `@State` selection for programmatic tab switching. `TabSection` groups tabs in the sidebar.
-
----
+- The iPadOS 18 tab sidebar needs `Tab`. `.tabItem` still compiles but its
+  tabs cannot appear in the sidebar.
+- Programmatic switching: give each `Tab` a `value` and bind the selection to
+  `@State`.
+- `TabSection` groups tabs in the sidebar. Inside it, name the selection type
+  (`AppTab.favorites`, where `selectedTab` is an `AppTab`); a bare `.favorites`
+  leaves `TabSection`'s generic parameter uninferred and fails to compile.
 
-## scrollIndicators(.hidden) Replaces showsIndicators Parameter
+## 26. showsIndicators to scrollIndicators
 
-The `showsIndicators` parameter on `ScrollView` is available but the `scrollIndicators` modifier (iOS 16+) is preferred for consistency.
-
-### Before
+`ScrollView(_:showsIndicators:)` still exists, but the `.scrollIndicators`
+modifier (iOS 16+) is the consistent way to control indicators.
 
 ```swift
-ScrollView(.vertical, showsIndicators: false) {
-    content
-}
-```
-
-### After (Modern)
+// Before
+ScrollView(.vertical, showsIndicators: false) { timeline }
 
-```swift
-ScrollView {
-    content
-}
-.scrollIndicators(.hidden)
+// After
+ScrollView { timeline }
+    .scrollIndicators(.hidden)
 ```
 
-### Migration Notes
-
-`.scrollIndicators(_:axes:)` accepts `.automatic`, `.visible`, `.hidden`, and `.never`. It also works on `List` and `TextEditor`. The `axes` parameter lets you control horizontal and vertical indicators independently.
+- `.scrollIndicators(_:axes:)` accepts `.automatic`, `.visible`, `.hidden` and
+  `.never`.
+- It also affects other scrollable views, such as `List` and `TextEditor`.
+- The `axes` parameter sets horizontal and vertical indicators separately.