@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-navigation/SKILL.md

@@ -1,264 +1,289 @@
 ---
 name: swiftui-navigation
-description: "Implement SwiftUI navigation patterns including NavigationStack, NavigationSplitView, sheet presentation, tab-based navigation, and deep linking. Use when building push navigation, programmatic routing, multi-column layouts, modal sheets, tab bars, universal links, or custom URL scheme handling."
+description: "SwiftUI navigation: NavigationStack typed paths, routers, NavigationSplitView, sheets, TabView and Tab API, universal links, URL schemes, Handoff. Use when implementing or reviewing push or programmatic navigation, multi-column layouts, modal sheets, tab bars or deep linking."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # SwiftUI Navigation
 
-Navigation patterns for SwiftUI apps targeting iOS 26+ with Swift 6.3. Covers push navigation, multi-column layouts, sheet presentation, tab architecture, and deep linking. Patterns are backward-compatible to iOS 17 unless noted.
+Examples target iOS 26 and Swift 6.3. Unless a line says otherwise, each
+pattern also runs on iOS 17.
 
-## Contents
+Other skills own the neighbours: app architecture and state management are in
+`swiftui-patterns`, stacks, grids and components in
+`swiftui-layout-components`.
 
-- [NavigationStack (Push Navigation)](#navigationstack-push-navigation)
-- [NavigationSplitView (Multi-Column)](#navigationsplitview-multi-column)
-- [Sheet Presentation](#sheet-presentation)
-- [Tab-Based Navigation](#tab-based-navigation)
-- [Deep Links](#deep-links)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+## NavigationStack
 
-## NavigationStack (Push Navigation)
-
-Use `NavigationStack` with a `NavigationPath` binding for programmatic, type-safe push navigation. Define routes as a `Hashable` enum and map them with `.navigationDestination(for:)`.
+Bind `NavigationStack(path:)` to a `NavigationPath` (or a typed array) in state,
+describe destinations with a `Hashable` enum or value type, and map each type
+once with `.navigationDestination(for:)`.
 
 ```swift
-struct ContentView: View {
+struct TrailListView: View {
     @State private var path = NavigationPath()
+    let trails: [Trail]
 
     var body: some View {
         NavigationStack(path: $path) {
-            List(items) { item in
-                NavigationLink(value: item) {
-                    ItemRow(item: item)
+            List(trails) { trail in
+                NavigationLink(value: trail) {
+                    TrailRow(trail: trail)
                 }
             }
-            .navigationDestination(for: Item.self) { item in
-                DetailView(item: item)
+            .navigationDestination(for: Trail.self) { trail in
+                TrailDetailView(trail: trail)
             }
-            .navigationTitle("Items")
+            .navigationTitle("Trails")
         }
     }
 }
 ```
 
-**Programmatic navigation:**
-
-```swift
-path.append(item)        // Push
-path.removeLast()        // Pop one
-path = NavigationPath()  // Pop to root
-```
+Driving the stack from code:
 
-**Router pattern:** For apps with complex navigation, use a router object that owns the path and sheet state. Each tab gets its own router instance injected via `.environment()`. Centralize destination mapping with a single `.navigationDestination(for:)` block or a shared `withAppRouter()` modifier.
+| Goal | Code |
+| --- | --- |
+| Push | `path.append(trail)` |
+| Back one level | `path.removeLast()` |
+| Back to root | `path = NavigationPath()` |
 
-See [references/navigationstack.md](references/navigationstack.md) for full router examples including per-tab stacks, centralized destination mapping, and generic tab routing.
+For anything bigger than one screen, move path and sheet state into a router
+object. Give each tab its own router instance and hand it down with
+`.environment()`. Keep the destination switch in one place: a single
+`.navigationDestination(for:)` block or a shared modifier such as
+`withAppRouter()`. The router, per-tab and centralised-mapping patterns are in
+[references/navigationstack.md](references/navigationstack.md).
 
-## NavigationSplitView (Multi-Column)
+## NavigationSplitView
 
-Use `NavigationSplitView` for sidebar-detail layouts on iPad and Mac. Falls back to stack navigation on iPhone.
+`NavigationSplitView` gives a sidebar and detail on iPad and Mac and collapses
+into a push stack on iPhone.
 
 ```swift
-struct MasterDetailView: View {
-    @State private var selectedItem: Item?
+struct LibraryView: View {
+    @State private var chosen: Album?
+    let albums: [Album]
 
     var body: some View {
         NavigationSplitView {
-            List(items, selection: $selectedItem) { item in
-                NavigationLink(value: item) { ItemRow(item: item) }
+            List(albums, selection: $chosen) { album in
+                NavigationLink(album.title, value: album)
             }
-            .navigationTitle("Items")
+            .navigationTitle("Albums")
         } detail: {
-            if let item = selectedItem {
-                ItemDetailView(item: item)
+            if let chosen {
+                AlbumDetailView(album: chosen)
             } else {
-                ContentUnavailableView("Select an Item", systemImage: "sidebar.leading")
+                ContentUnavailableView("No album selected", systemImage: "sidebar.leading")
             }
         }
     }
 }
 ```
 
-### Custom Split Column (Manual HStack)
+### A hand-built second column
 
-For custom multi-column layouts (e.g., a dedicated notification column independent of selection), use a manual `HStack` split with `horizontalSizeClass` checks:
+When the extra column does not follow the selection, for example an activity
+feed that should sit beside whatever the main area shows, build the split
+yourself with an `HStack(spacing: 0)`.
 
 ```swift
-@MainActor
-struct AppView: View {
-  @Environment(\.horizontalSizeClass) private var horizontalSizeClass
-  @AppStorage("showSecondaryColumn") private var showSecondaryColumn = true
-
-  var body: some View {
-    HStack(spacing: 0) {
-      primaryColumn
-      if shouldShowSecondaryColumn {
-        Divider().edgesIgnoringSafeArea(.all)
-        secondaryColumn
-      }
+struct WorkspaceView: View {
+    @Environment(\.horizontalSizeClass) private var sizeClass
+    @AppStorage("showsActivityColumn") private var showsActivity = true
+
+    var body: some View {
+        HStack(spacing: 0) {
+            MainContentView()
+            if sizeClass == .regular && showsActivity {
+                Divider().ignoresSafeArea()
+                ActivityColumnView()
+                    .environment(\.isSecondaryColumn, true)
+                    .frame(maxWidth: 360)
+            }
+        }
     }
-  }
-
-  private var shouldShowSecondaryColumn: Bool {
-    horizontalSizeClass == .regular
-      && showSecondaryColumn
-  }
-
-  private var primaryColumn: some View {
-    TabView { /* tabs */ }
-  }
-
-  private var secondaryColumn: some View {
-    NotificationsTab()
-      .environment(\.isSecondaryColumn, true)
-      .frame(maxWidth: .secondaryColumnWidth)
-  }
 }
-```
-
-Use the manual HStack split when you need full control or a non-standard secondary column. Use `NavigationSplitView` when you want a standard system layout with minimal customization.
-
-## Sheet Presentation
-
-Prefer `.sheet(item:)` over `.sheet(isPresented:)` when state represents a selected model. Sheets should own their actions and call `dismiss()` internally.
 
-```swift
-@State private var selectedItem: Item?
-
-.sheet(item: $selectedItem) { item in
-    EditItemSheet(item: item)
+extension EnvironmentValues {
+    @Entry var isSecondaryColumn = false
 }
 ```
 
-**Presentation sizing (iOS 18+):** Control sheet dimensions with `.presentationSizing`:
+The column only appears in a regular horizontal size class and when the user
+has left the toggle on. Choose the manual layout when you need full control or
+a column the system split view has no slot for; choose `NavigationSplitView`
+when the standard sidebar-content-detail shape fits with small tweaks.
 
-```swift
-.sheet(item: $selectedItem) { item in
-    EditItemSheet(item: item)
-        .presentationSizing(.form)  // .form, .page, .fitted, .automatic
-}
-```
+## Sheets
+
+- When a sheet shows a particular model, use `.sheet(item:)`; keep
+  `.sheet(isPresented:)` for pure on/off states.
+- A sheet owns its buttons and closes itself with `dismiss()`.
+- `.presentationSizing(_:)` (iOS 18+) sets the size instead of fixed frames.
 
-`PresentationSizing` values:
-- `.automatic` -- platform default
-- `.page` -- roughly paper size, for informational content
-- `.form` -- slightly narrower than page, for form-style UI
-- `.fitted` -- sized by the content's ideal size
+| `PresentationSizing` | Result |
+| --- | --- |
+| `.automatic` | Platform default |
+| `.page` | Roughly paper-sized, for reading material |
+| `.form` | Slightly narrower than `.page`, for data entry |
+| `.fitted` | The content's ideal size |
 
-Fine-tuning: `.fitted(horizontal:vertical:)` constrains fitting axes; `.sticky(horizontal:vertical:)` grows but does not shrink in specified dimensions.
+`.fitted(horizontal:vertical:)` restricts fitting to the axes you pass, and
+`.sticky(horizontal:vertical:)` lets a sheet grow along those axes but never
+shrink back.
 
-**Dismissal confirmation (macOS 15+ / iOS 26+):** Use `.dismissalConfirmationDialog("Discard?", shouldPresent: hasUnsavedChanges)` to prevent accidental dismissal of sheets with unsaved changes.
+To stop a sheet with unsaved edits from being swiped away on iOS, use
+`.interactiveDismissDisabled(hasEdits)` and confirm from your own Close button.
+`.dismissalConfirmationDialog(_:shouldPresent:)` does this on macOS 15+ only;
+the SDK marks it unavailable on iOS.
 
-**Enum-driven sheet routing:** Define a `SheetDestination` enum that is `Identifiable`, store it on the router, and map it with a shared view modifier. This lets any child view present sheets without prop-drilling. See [references/sheets.md](references/sheets.md) for the full centralized sheet routing pattern.
+For larger apps, describe every modal as a case of an `Identifiable` enum held
+on the router, and map the cases to views in one shared modifier. Any child can
+then open a sheet by setting router state, with no bindings passed down. See
+[references/sheets.md](references/sheets.md).
 
-## Tab-Based Navigation
+## Tabs
 
-Use the `Tab` API with a selection binding for scalable tab architecture. Each tab should wrap its content in an independent `NavigationStack`.
+Use the `Tab` type with a typed selection, and give every tab its own
+`NavigationStack`.
 
 ```swift
-struct MainTabView: View {
-    @State private var selectedTab: AppTab = .home
+enum HomeTab: Hashable { case today, explore, compose, profile }
+
+struct RootTabs: View {
+    @State private var current: HomeTab = .today
+    @State private var composing = false
 
     var body: some View {
-        TabView(selection: $selectedTab) {
-            Tab("Home", systemImage: "house", value: .home) {
-                NavigationStack { HomeView() }
+        TabView(selection: Binding(get: { current }, set: select)) {
+            Tab("Today", systemImage: "sun.max", value: .today) {
+                NavigationStack { TodayView() }
+            }
+            Tab("Explore", systemImage: "map", value: .explore) {
+                NavigationStack { ExploreView() }
             }
-            Tab("Search", systemImage: "magnifyingglass", value: .search) {
-                NavigationStack { SearchView() }
+            Tab("New", systemImage: "plus.circle", value: .compose) {
+                Color.clear
             }
-            Tab("Profile", systemImage: "person", value: .profile) {
+            Tab("Me", systemImage: "person", value: .profile) {
                 NavigationStack { ProfileView() }
             }
         }
+        .sheet(isPresented: $composing) { ComposerView() }
+    }
+
+    private func select(_ next: HomeTab) {
+        if next == .compose {
+            composing = true
+        } else {
+            current = next
+        }
     }
 }
 ```
 
-**Custom binding with side effects:** Route selection changes through a function to intercept special tabs (e.g., compose) that should trigger an action instead of changing selection.
+The custom binding sends every change through `select`, so a tab like
+"New" can run an action instead of becoming the selected tab.
+
+### iOS 26 additions
 
-### iOS 26 Tab Additions
+- `Tab(role: .search)` turns the tab bar into a search field while that tab is
+  active.
+- `.tabBarMinimizeBehavior(_:)` with `.onScrollDown`, `.onScrollUp` or `.never`.
+  iPhone only.
+- `.tabViewSidebarHeader { }` and `.tabViewSidebarFooter { }` customise the
+  sidebar on iPadOS and macOS.
+- `.tabViewBottomAccessory { }` pins a view just above the tab bar, such as a
+  mini player.
+- `TabSection` collects tabs under a sidebar heading; mark it with
+  `.tabPlacement(.sidebarOnly)` to keep it out of the compact bar.
 
-- **`Tab(role: .search)`** -- replaces the tab bar with a search field when active
-- **`.tabBarMinimizeBehavior(_:)`** -- `.onScrollDown`, `.onScrollUp`, `.never` (iPhone only)
-- **`.tabViewSidebarHeader/Footer`** -- customize sidebar sections on iPadOS/macOS
-- **`.tabViewBottomAccessory { }`** -- attach content below the tab bar (e.g., Now Playing bar)
-- **`TabSection`** -- group tabs into sidebar sections with `.tabPlacement(.sidebarOnly)`
+More in [references/tabview.md](references/tabview.md).
 
-See [references/tabview.md](references/tabview.md) for full TabView patterns including custom bindings, dynamic tabs, and sidebar customization.
+## Deep links
 
-## Deep Links
+### Universal links
 
-### Universal Links
+A universal link is an ordinary HTTPS URL that opens the app when installed.
+It needs two things:
 
-Universal links let iOS open your app for standard HTTPS URLs. They require:
-1. An Apple App Site Association (AASA) file at `/.well-known/apple-app-site-association`
-2. An Associated Domains entitlement (`applinks:example.com`)
+1. An `apple-app-site-association` file served from
+   `/.well-known/apple-app-site-association` on the domain.
+2. The Associated Domains entitlement listing `applinks:example.com`.
 
-Handle in SwiftUI with `.onOpenURL` and `.onContinueUserActivity`:
+Handle both entry points on the root content of the `WindowGroup`:
 
 ```swift
 @main
-struct MyApp: App {
+struct HikerApp: App {
     @State private var router = Router()
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
+            RootTabs()
                 .environment(router)
-                .onOpenURL { url in router.handle(url: url) }
+                .onOpenURL { link in _ = router.handle(url: link) }
                 .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
-                    guard let url = activity.webpageURL else { return }
-                    router.handle(url: url)
+                    if let link = activity.webpageURL {
+                        _ = router.handle(url: link)
+                    }
                 }
         }
     }
 }
 ```
 
-### Custom URL Schemes
-
-Register schemes in `Info.plist` under `CFBundleURLTypes`. Handle with `.onOpenURL`. Prefer universal links over custom schemes for publicly shared links -- they provide web fallback and domain verification.
-
-### Handoff (NSUserActivity)
-
-Advertise activities with `.userActivity()` and receive them with `.onContinueUserActivity()`. Declare activity types in `Info.plist` under `NSUserActivityTypes`. Set `isEligibleForHandoff = true` and provide a `webpageURL` as fallback.
-
-See [references/deeplinks.md](references/deeplinks.md) for full examples of AASA configuration, router URL handling, custom URL schemes, and NSUserActivity continuation.
-
-## Common Mistakes
-
-1. Using deprecated `NavigationView` -- use `NavigationStack` or `NavigationSplitView`
-2. Sharing one `NavigationPath` across all tabs -- each tab needs its own path
-3. Using `.sheet(isPresented:)` when state represents a model -- use `.sheet(item:)` instead
-4. Storing view instances in `NavigationPath` -- store lightweight `Hashable` route data
-5. Nesting `@Observable` router objects inside other `@Observable` objects
-6. Prefer `Tab(value:)` with `TabView(selection:)` over the older `.tabItem { }` API
-7. Assuming `tabBarMinimizeBehavior` works on iPad -- it is iPhone only
-8. Handling deep links in multiple places -- centralize URL parsing in the router
-9. Hard-coding sheet frame dimensions -- use `.presentationSizing(.form)` instead
-10. Missing `@MainActor` on router classes -- required for Swift 6 concurrency safety
-
-## Review Checklist
-
-- [ ] `NavigationStack` used (not `NavigationView`)
-- [ ] Each tab has its own `NavigationStack` with independent path
-- [ ] Route enum is `Hashable` with stable identifiers
-- [ ] `.navigationDestination(for:)` maps all route types
-- [ ] `.sheet(item:)` preferred over `.sheet(isPresented:)`
-- [ ] Sheets own their dismiss logic internally
-- [ ] Router object is `@MainActor` and `@Observable`
-- [ ] Deep link URLs parsed and validated before navigation
-- [ ] Universal links have AASA and Associated Domains configured
-- [ ] Tab selection uses `Tab(value:)` with binding
+### Custom URL schemes
+
+List the scheme under `CFBundleURLTypes` in Info.plist and handle it in
+`.onOpenURL`. For links people share publicly, prefer universal links: they
+have a web fallback and the domain is verified.
+
+### Handoff
+
+Publish the current activity with `.userActivity()` and pick it up with
+`.onContinueUserActivity()`. Every activity type must appear in the Info.plist
+`NSUserActivityTypes` array. Set `isEligibleForHandoff = true` and supply a
+`webpageURL` for devices without the app.
+
+Details, AASA format and scheme parsing: [references/deeplinks.md](references/deeplinks.md).
+
+## Common mistakes
+
+- Reaching for `NavigationView`. It is deprecated; use `NavigationStack` or
+  `NavigationSplitView`.
+- Letting every tab share one `NavigationPath`. Each tab keeps its own history.
+- Driving a model-backed sheet with `.sheet(isPresented:)` instead of
+  `.sheet(item:)`.
+- Putting views in the path. The path holds small `Hashable` route values.
+- Holding an `@Observable` router as a property of another `@Observable` object.
+- Building tabs with the older `.tabItem { }` instead of `Tab(value:)` with
+  `TabView(selection:)`.
+- Expecting `tabBarMinimizeBehavior` to do anything on iPad. It is iPhone only.
+- Parsing URLs in several views. The router is the one place that parses them.
+- Giving sheets fixed frame sizes instead of `.presentationSizing(.form)`.
+- Leaving `@MainActor` off the router class, which Swift 6 concurrency checking
+  needs.
+
+## Review checklist
+
+- [ ] `NavigationStack` everywhere, no `NavigationView`
+- [ ] Each tab has its own `NavigationStack` and its own path
+- [ ] The route enum is `Hashable` and its identifiers are stable
+- [ ] `.navigationDestination(for:)` handles every route type that can be pushed
+- [ ] `.sheet(item:)` is used for model-backed sheets
+- [ ] Sheets handle their own dismissal
+- [ ] The router is `@MainActor` and `@Observable`
+- [ ] Incoming URLs are parsed and validated before any navigation happens
+- [ ] Universal links have the AASA file and Associated Domains in place
+- [ ] Tab selection uses `Tab(value:)` with a selection binding
 
 ## References
 
-- NavigationStack and router patterns: [references/navigationstack.md](references/navigationstack.md)
-- Sheet presentation and routing: [references/sheets.md](references/sheets.md)
-- TabView patterns and iOS 26 API: [references/tabview.md](references/tabview.md)
-- Deep links, universal links, and Handoff: [references/deeplinks.md](references/deeplinks.md)
-- Architecture and state management: see `swiftui-patterns` skill
-- Layout and components: see `swiftui-layout-components` skill
+- [references/navigationstack.md](references/navigationstack.md): routers, per-tab stacks, centralised destinations, data-driven tabs
+- [references/sheets.md](references/sheets.md): enum sheet routing, sizing, dismissal confirmation
+- [references/tabview.md](references/tabview.md): tab architecture, custom selection binding, dynamic tabs, iOS 26 tab API
+- [references/deeplinks.md](references/deeplinks.md): router URL handling, universal links and AASA, custom schemes, Handoff