@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-navigation/references/sheets.md

@@ -1,169 +1,204 @@
-# Sheets
+# Sheet Routing
 
-## Contents
+Part of the `swiftui-navigation` skill. Routing every modal through one place
+lets any view open a sheet without threading bindings through its parents, and
+it keeps working as screens are added.
 
-- [Intent](#intent)
-- [Core architecture](#core-architecture)
-- [Example: SheetDestination enum](#example-sheetdestination-enum)
-- [Example: withSheetDestinations modifier](#example-withsheetdestinations-modifier)
-- [Example: presenting from a child view](#example-presenting-from-a-child-view)
-- [Required wiring](#required-wiring)
-- [Example: sheets that need their own navigation](#example-sheets-that-need-their-own-navigation)
-- [Design choices to keep](#design-choices-to-keep)
-- [iOS 26 Presentation Sizing](#ios-26-presentation-sizing)
-- [Pitfalls](#pitfalls)
+## Building blocks
 
-## Intent
+- A `SheetDestination` enum, `Identifiable`, with one case per modal.
+- `presentedSheet: SheetDestination?` stored on the router.
+- A modifier, here `withSheetDestinations(sheet:)`, that turns a case into its
+  view.
+- The router in the environment, so children assign `presentedSheet` directly.
 
-Use a centralized sheet routing pattern so any view can present modals without prop-drilling. This keeps sheet state in one place and scales as the app grows.
-
-## Core architecture
-
-- Define a `SheetDestination` enum that describes every modal and is `Identifiable`.
-- Store the current sheet in a router object (`presentedSheet: SheetDestination?`).
-- Create a view modifier like `withSheetDestinations(...)` that maps the enum to concrete sheet views.
-- Inject the router into the environment so child views can set `presentedSheet` directly.
-
-## Example: SheetDestination enum
+## The destination enum
 
 ```swift
-enum SheetDestination: Identifiable, Hashable {
-  case composer
-  case editProfile
-  case settings
-  case report(itemID: String)
-
-  var id: String {
-    switch self {
-    case .composer, .editProfile:
-      // Use the same id to ensure only one editor-like sheet is active at a time.
-      return "editor"
-    case .settings:
-      return "settings"
-    case .report:
-      return "report"
+enum SheetDestination: Hashable, Identifiable {
+    case newTrip
+    case editTrip(Trip.ID)
+    case sharePhoto(Photo.ID)
+    case report(itemID: String)
+
+    var id: String {
+        if case .sharePhoto = self { return "share" }
+        if case .report = self { return "report" }
+        return "trip-editor"
     }
-  }
 }
 ```
 
-## Example: withSheetDestinations modifier
+`newTrip` and `editTrip` return the same `id`. They are two ways into one
+editor, so they can never be on screen together.
+
+## The mapping modifier
 
 ```swift
 extension View {
-  func withSheetDestinations(
-    sheet: Binding<SheetDestination?>
-  ) -> some View {
-    sheet(item: sheet) { destination in
-      Group {
-        switch destination {
-        case .composer:
-          ComposerView()
-        case .editProfile:
-          EditProfileView()
-        case .settings:
-          SettingsView()
-        case .report(let itemID):
-          ReportView(itemID: itemID)
+    func withSheetDestinations(sheet: Binding<SheetDestination?>) -> some View {
+        self.sheet(item: sheet) { modal in
+            Group {
+                switch modal {
+                case .newTrip: TripEditor(trip: nil)
+                case .editTrip(let id): TripEditor(tripID: id)
+                case .sharePhoto(let id): PhotoShareView(photoID: id)
+                case .report(let itemID): ReportForm(itemID: itemID)
+                }
+            }
         }
-      }
     }
-  }
 }
 ```
 
-## Example: presenting from a child view
+## Opening a sheet from deep in the tree
 
 ```swift
-struct StatusRow: View {
-  @Environment(RouterPath.self) private var router
-
-  var body: some View {
-    Button("Report") {
-      router.presentedSheet = .report(itemID: "123")
+struct CommentRow: View {
+    @Environment(Router.self) private var router
+    let comment: Comment
+
+    var body: some View {
+        Text(comment.body)
+            .contextMenu {
+                Button("Report", systemImage: "flag") {
+                    router.presentedSheet = .report(itemID: comment.id)
+                }
+            }
     }
-  }
 }
 ```
 
-## Required wiring
+## Wiring at the root
+
+1. The parent owns the router instance.
+2. It installs `withSheetDestinations(sheet: $router.presentedSheet)`; a plain
+   `sheet(item:)` does the same job.
+3. `.environment(router)` comes later in the chain than the sheet modifier, so
+   whatever the sheet shows can read the router as well.
 
-For the child view to work, a parent view must:
-- own the router instance,
-- attach `withSheetDestinations(sheet: $router.presentedSheet)` (or an equivalent `sheet(item:)` handler), and
-- inject it with `.environment(router)` after the sheet modifier so the modal content inherits it.
+```swift
+struct TripsRoot: View {
+    @State private var router = Router()
+
+    var body: some View {
+        NavigationStack(path: $router.path) { TripsList().withAppRouter() }
+            .withSheetDestinations(sheet: $router.presentedSheet)
+            .environment(router)
+    }
+}
+```
 
-This makes the child assignment to `router.presentedSheet` drive presentation at the root.
+With that in place, a child that sets `presentedSheet` makes the root present
+the sheet.
 
-## Example: sheets that need their own navigation
+## Sheets that push their own screens
 
-Wrap sheet content in a `NavigationStack` so it can push within the modal.
+Wrap the content in a stack with a close button when a sheet needs its own
+navigation.
 
 ```swift
 struct NavigationSheet<Content: View>: View {
-  var content: () -> Content
-
-  var body: some View {
-    NavigationStack {
-      content()
-        .toolbar { CloseToolbarItem() }
+    @ViewBuilder var content: Content
+    @Environment(\.dismiss) private var close
+
+    var body: some View {
+        NavigationStack {
+            content
+                .toolbar {
+                    ToolbarItem(placement: .cancellationAction) {
+                        Button("Close", systemImage: "xmark") { close() }
+                    }
+                }
+        }
     }
-  }
 }
 ```
 
-## Design choices to keep
+## Rules worth keeping
 
-- Centralize sheet routing so features can present modals without wiring bindings through many layers.
-- Use `sheet(item:)` to guarantee a single sheet is active and to drive presentation from the enum.
-- Group related sheets under the same `id` when they are mutually exclusive (e.g., editor flows).
-- Keep sheet views lightweight and composed from smaller views; avoid large monoliths.
+- Route sheets centrally so features do not pass bindings through layers.
+- `sheet(item:)` keeps exactly one sheet active, chosen by the enum.
+- Mutually exclusive sheets share an `id`.
+- Sheet views stay small and composed from pieces.
 
-## iOS 26 Presentation Sizing
+## Presentation sizing
 
-Control sheet dimensions with `presentationSizing(_:)` (iOS 18+):
+The section concerns iOS 26 layouts, but `presentationSizing(_:)` itself is
+available from iOS 18. Values: `.automatic`, `.page`, `.form`, `.fitted`.
+`.fitted(horizontal:vertical:)` fits only the axes you pass, and
+`.sticky(horizontal:vertical:)` lets the sheet grow along them without
+shrinking.
 
 ```swift
-.sheet(item: $selectedItem) { item in
-    EditItemSheet(item: item)
-        .presentationSizing(.form)
-}
+TripEditor(trip: nil)
+    .presentationSizing(.form.sticky(horizontal: false, vertical: true))
 ```
 
-`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
+## Confirming dismissal
 
-Modifier methods for fine-tuning:
-- `.fitted(horizontal:vertical:)` -- constrain fitting to specific axes
-- `.sticky(horizontal:vertical:)` -- grow but do not shrink in specified dimensions
-
-### Dismissal Confirmation (macOS 15+ / iOS 26+)
-
-Show a confirmation dialog when the user tries to dismiss a sheet with unsaved changes:
+On iOS, block the swipe with `.interactiveDismissDisabled(_:)` while there are
+unsaved edits, and ask from your own Close button with `confirmationDialog`:
 
 ```swift
-.sheet(item: $selectedItem) { item in
-    EditItemSheet(item: item)
-        .dismissalConfirmationDialog(
-            "Discard changes?",
-            shouldPresent: hasUnsavedChanges
-        ) {
-            Button("Discard", role: .destructive) { discardChanges() }
+struct TripEditorSheet: View {
+    let id: Trip.ID
+    let hasEdits: Bool
+    let draft: Draft
+    @State private var confirmsDiscard = false
+    @Environment(\.dismiss) private var dismiss
+
+    var body: some View {
+        NavigationStack {
+            TripEditor(tripID: id)
+                .toolbar {
+                    ToolbarItem(placement: .cancellationAction) {
+                        Button("Close", systemImage: "xmark") {
+                            if hasEdits { confirmsDiscard = true } else { dismiss() }
+                        }
+                        .confirmationDialog("Throw away your edits?", isPresented: $confirmsDiscard) {
+                            Button("Throw Away", role: .destructive) {
+                                draft.revert()
+                                dismiss()
+                            }
+                            Button("Save and Close") {
+                                draft.save()
+                                dismiss()
+                            }
+                        }
+                    }
+                }
         }
+        .interactiveDismissDisabled(hasEdits)
+    }
 }
 ```
 
-- Cancel action is included automatically and prevents dismissal
-- All other action buttons allow dismissal to proceed
-- Use `.keyboardShortcut(.defaultAction)` to set the default button
+On macOS 15 and later, `dismissalConfirmationDialog(_:shouldPresent:)` does
+this for you. The SDK marks it unavailable on iOS, iPadOS, tvOS, watchOS and
+visionOS, so it only compiles in a macOS target:
+
+```swift
+TripEditor(tripID: id)
+    .dismissalConfirmationDialog("Throw away your edits?", shouldPresent: hasEdits) {
+        Button("Throw Away", role: .destructive) { draft.revert() }
+        Button("Save and Close") { draft.save() }
+            .keyboardShortcut(.defaultAction)
+    }
+```
+
+The system adds Cancel on its own, and Cancel keeps the sheet open. Any other
+button lets the dismissal go ahead. `.keyboardShortcut(.defaultAction)` marks
+the default choice.
 
 ## Pitfalls
 
-- Avoid mixing `sheet(isPresented:)` and `sheet(item:)` for the same concern; prefer a single enum.
-- Do not store heavy state inside `SheetDestination`; pass lightweight identifiers or models.
-- If multiple sheets can appear from the same screen, give them distinct `id` values.
-- Use `presentationSizing(.form)` for form sheets instead of hard-coding frame dimensions.
-- Always pair `dismissalConfirmationDialog` with a `shouldPresent` condition; showing it when there are no changes is confusing.
+- Two presentation styles, `sheet(isPresented:)` plus `sheet(item:)`, for one
+  concern. A single enum is enough.
+- Carrying heavy state inside `SheetDestination`. Pass identifiers or small
+  models.
+- Reusing an `id` for sheets that may legitimately come from the same screen
+  one after another; give them distinct values.
+- Fixed frames instead of `presentationSizing(.form)`.
+- A dismissal dialog without a real `shouldPresent` condition. Asking when
+  nothing changed only confuses people.

package/pipeline/skills/shared/external/swiftui-navigation/references/tabview.md

@@ -1,178 +1,144 @@
-# TabView
+# TabView Architecture
 
-## Contents
+Part of the `swiftui-navigation` skill. Goal: tabs that scale across platforms,
+with one source of truth for what each tab is and shows, different tab sets and
+sidebar groupings per platform, tabs generated from data, and a hook that can
+intercept special tabs.
 
-- [Intent](#intent)
-- [Core architecture](#core-architecture)
-- [Example: custom binding with side effects](#example-custom-binding-with-side-effects)
-- [Example: direct binding without side effects](#example-direct-binding-without-side-effects)
-- [Design choices to keep](#design-choices-to-keep)
-- [Dynamic tabs pattern](#dynamic-tabs-pattern)
-- [iOS 26 Tab API](#ios-26-tab-api)
-- [Pitfalls](#pitfalls)
+## Building blocks
 
-## Intent
+- `AppTab` enum: identity, title, icon and a builder for its content.
+- `SidebarSections` enum: which tabs appear under which sidebar heading. Give
+  its `title` the type `LocalizedStringKey`. With a `String` title,
+  `TabSection(group.title)` makes `Tab(value:)` ambiguous and the view does not
+  compile.
+- `AppView`: owns the `TabView` and the selection, and routes selection changes
+  through `updateTab(with:)`.
 
-Use this pattern for a scalable, multi-platform tab architecture with:
-- a single source of truth for tab identity and content,
-- platform-specific tab sets and sidebar sections,
-- dynamic tabs sourced from data,
-- an interception hook for special tabs (e.g., compose).
-
-## Core architecture
-
-- `AppTab` enum defines identity, labels, icons, and content builder.
-- `SidebarSections` enum groups tabs for sidebar sections.
-- `AppView` owns the `TabView` and selection binding, and routes tab changes through `updateTab`.
-
-## Example: custom binding with side effects
-
-Use this when tab selection needs side effects, like intercepting a special tab to perform an action instead of changing selection.
+## Selection with side effects
 
 ```swift
-@MainActor
 struct AppView: View {
-  @Binding var selectedTab: AppTab
-
-  var body: some View {
-    TabView(selection: .init(
-      get: { selectedTab },
-      set: { updateTab(with: $0) }
-    )) {
-      ForEach(availableSections) { section in
-        TabSection(section.title) {
-          ForEach(section.tabs) { tab in
-            Tab(value: tab) {
-              tab.makeContentView(
-                homeTimeline: $timeline,
-                selectedTab: $selectedTab,
-                pinnedFilters: $pinnedFilters
-              )
-            } label: {
-              tab.label
-            }
-            .tabPlacement(tab.tabPlacement)
-          }
-        }
-        .tabPlacement(.sidebarOnly)
-      }
-    }
-  }
+    let sections: [SidebarSections]
+    @State private var scrollTarget: AppTab?
+    @State private var showsComposer = false
+    @State private var selectedTab: AppTab = .home
 
-  private func updateTab(with newTab: AppTab) {
-    if newTab == .post {
-      // Intercept special tabs (compose) instead of changing selection.
-      presentComposer()
-      return
+    private var selection: Binding<AppTab> {
+        Binding(get: { selectedTab }, set: updateTab(with:))
     }
-    selectedTab = newTab
-  }
-}
-```
-
-## Example: direct binding without side effects
 
-Use this when selection is purely state-driven.
-
-```swift
-@MainActor
-struct AppView: View {
-  @Binding var selectedTab: AppTab
-
-  var body: some View {
-    TabView(selection: $selectedTab) {
-      ForEach(availableSections) { section in
-        TabSection(section.title) {
-          ForEach(section.tabs) { tab in
-            Tab(value: tab) {
-              tab.makeContentView(
-                homeTimeline: $timeline,
-                selectedTab: $selectedTab,
-                pinnedFilters: $pinnedFilters
-              )
-            } label: {
-              tab.label
+    var body: some View {
+        TabView(selection: selection) {
+            ForEach(sections) { group in
+                TabSection(group.title) {
+                    ForEach(group.tabs) { entry in
+                        Tab(value: entry) {
+                            entry.makeContentView(scrollTarget: $scrollTarget)
+                        } label: {
+                            entry.label
+                        }
+                        .tabPlacement(entry.tabPlacement)
+                    }
+                }
+                .tabPlacement(.sidebarOnly)
             }
-            .tabPlacement(tab.tabPlacement)
-          }
         }
-        .tabPlacement(.sidebarOnly)
-      }
+        .sheet(isPresented: $showsComposer) { ComposerView() }
+    }
+
+    private func updateTab(with next: AppTab) {
+        if next == .post {
+            showsComposer = true
+            return
+        }
+        if next == selectedTab {
+            scrollTarget = next
+        }
+        selectedTab = next
     }
-  }
 }
 ```
 
-## Design choices to keep
+Choosing `.post` opens the composer and leaves the selection where it was.
+Choosing the current tab again asks it to scroll to the top.
 
-- Centralize tab identity and content in `AppTab` with `makeContentView(...)`.
-- Use `Tab(value:)` with `selection` binding for state-driven tab selection.
-- Route selection changes through `updateTab` to handle special tabs and scroll-to-top behavior.
-- Use `TabSection` + `.tabPlacement(.sidebarOnly)` for sidebar structure.
-- Use `.tabPlacement(.pinned)` in `AppTab.tabPlacement` for a single pinned tab; this is commonly used for iOS 26 `.searchable` tab content, but can be used for any tab.
+## Selection without side effects
 
-## Dynamic tabs pattern
+If selection is pure state, bind directly: `TabView(selection: $selectedTab)`
+with the same `TabSection` and `Tab` structure inside.
 
-- `SidebarSections` handles dynamic data tabs.
-- `AppTab.anyTimelineFilter(filter:)` wraps dynamic tabs in a single enum case.
-- The enum provides label/icon/title for dynamic tabs via the filter type.
+## Rules worth keeping
 
-## iOS 26 Tab API
+- `AppTab` is the single home for identity and content, through
+  `makeContentView(...)`.
+- Tabs use `Tab(value:)` together with a selection binding.
+- Selection goes through `updateTab(with:)`; that one function deals with
+  compose-style tabs and with re-tapping to scroll up.
+- Sidebar structure comes from `TabSection` plus `.tabPlacement(.sidebarOnly)`.
+- `.tabPlacement(.pinned)` keeps one tab fixed in place. It is typical for an
+  iOS 26 `.searchable` tab but works for any tab.
 
-iOS 26 expands the Tab API with minimize behavior, roles, and accessory placements.
+## Tabs generated from data
 
-### Tab Bar Minimization
+`SidebarSections` can hold tabs that come from user data, such as saved
+filters. Represent them with one case that carries a payload, for example
+`AppTab.savedFilter(SavedFilter)`, and read the title and icon from the filter.
 
 ```swift
-TabView(selection: $selectedTab) {
-    // tabs
-}
-.tabBarMinimizeBehavior(.onScrollDown) // iPhone only
-```
-
-`TabBarMinimizeBehavior` values:
-- `.automatic` -- determine behavior from context
-- `.onScrollDown` -- minimize when user scrolls down (iPhone only)
-- `.onScrollUp` -- minimize when user scrolls up (iPhone only)
-- `.never` -- never minimize the tab bar
+enum AppTab: Hashable, Identifiable {
+    case home, search, post, profile
+    case savedFilter(SavedFilter)
 
-### Tab Search Role
-
-Replace the tab bar with a search field when the search tab is active:
+    var id: String {
+        guard case .savedFilter(let filter) = self else { return String(describing: self) }
+        return "filter-\(filter.id)"
+    }
 
-```swift
-Tab(role: .search) {
-    SearchView()
+    @ViewBuilder var label: some View {
+        switch self {
+        case .savedFilter(let filter): Label(filter.name, systemImage: filter.symbol)
+        case .home: Label("Start", systemImage: "house")
+        case .search: Label("Search", systemImage: "magnifyingglass")
+        case .post: Label("Post", systemImage: "square.and.pencil")
+        case .profile: Label("Profile", systemImage: "person")
+        }
+    }
 }
 ```
 
-### Sidebar Customization
+## iOS 26 tab API
 
 ```swift
 TabView {
-    // tabs
+    Tab("Feed", systemImage: "list.bullet") { FeedView() }
+    Tab(role: .search) { SearchView() }
 }
-.tabViewSidebarHeader { SidebarHeaderView() }
-.tabViewSidebarFooter { SidebarFooterView() }
-.tabViewSidebarBottomBar { BottomBarView() }
+.tabBarMinimizeBehavior(.onScrollDown)
+.tabViewBottomAccessory { MiniPlayerBar() }
+.tabViewSidebarHeader { AccountHeader() }
+.tabViewSidebarFooter { StorageFooter() }
+.tabViewSidebarBottomBar { SettingsButton() }
 ```
 
-### Bottom Accessory
-
-Use `TabViewBottomAccessoryPlacement` for content below the tab bar:
-
-```swift
-TabView {
-    // tabs
-}
-.tabViewBottomAccessory { NowPlayingBar() }
-```
+- `TabBarMinimizeBehavior`: `.automatic` (decided by context), `.onScrollDown`,
+  `.onScrollUp` and `.never`. The two scroll behaviours apply on iPhone only.
+- `Tab(role: .search)` replaces the bar with a search field while that tab is
+  active.
+- Sidebar customisation: `.tabViewSidebarHeader { }`,
+  `.tabViewSidebarFooter { }` and `.tabViewSidebarBottomBar { }`.
+- `.tabViewBottomAccessory { }` shows content just above the tab bar; its
+  placement is described by `TabViewBottomAccessoryPlacement`.
 
 ## Pitfalls
 
-- Avoid adding ViewModels for tabs; keep state local or in `@Observable` services.
-- Do not nest `@Observable` objects inside other `@Observable` objects.
-- Ensure `AppTab.id` values are stable; dynamic cases should hash on stable IDs.
-- Special tabs (compose) should not change selection.
-- Prefer `Tab(value:)` with `TabView(selection:)` over the older `.tabItem { }` API for typed tab selection.
-- `tabBarMinimizeBehavior` only works on iPhone; it has no effect on iPad or Mac.
+- A view model per tab. Keep state local to views or in shared `@Observable`
+  services.
+- `@Observable` objects nested inside each other.
+- An `AppTab.id` that changes between launches; dynamic cases must hash on a
+  stable identifier.
+- Special tabs such as compose that change the selection.
+- `.tabItem { }` instead of `Tab(value:)` with `TabView(selection:)`, which
+  loses typed selection.
+- Expecting `tabBarMinimizeBehavior` to work on iPad or Mac; it does nothing
+  there.