@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-layout-components/references/list.md

@@ -1,90 +1,87 @@
-# List and Section
+# Lists
 
-## Intent
+List recipes for the `swiftui-layout-components` skill.
 
-Use `List` for feed-style content and settings-style rows where built-in row reuse, selection, and accessibility matter.
+## When to use List
 
-## Core patterns
+`List` is the default for long vertical runs of similar rows. `Section`
+headers break the rows into groups.
 
-- Prefer `List` for long, vertically scrolling content with repeated rows.
-- Use `Section` headers to group related rows.
-- Use `ScrollPosition` with `.scrollPosition($scrollPosition)` for scroll-to-top or jump-to-id.
-- Use `.listStyle(.plain)` for modern feed layouts.
-- Use `.listStyle(.grouped)` for multi-section discovery/search pages where section grouping helps.
-- Apply `.scrollContentBackground(.hidden)` + a custom background when you need a themed surface.
-- Use `.listRowInsets(...)` and `.listRowSeparator(.hidden)` to tune row spacing and separators.
-- Use `.environment(\.defaultMinListRowHeight, ...)` to control dense list layouts.
+- `.listStyle(.grouped)` suits discovery or search pages with several sections.
+- `.environment(\.defaultMinListRowHeight, 1)` removes the minimum row height
+  for very dense layouts.
+- Stable row ids keep insert and delete animations and scroll positioning
+  correct.
 
-## Example: feed list with scroll-to-top
+## Feed with scroll to top
 
 ```swift
-@MainActor
-struct TimelineListView: View {
-  @Environment(\.selectedTabScrollToTop) private var selectedTabScrollToTop
-  @State private var scrollPosition = ScrollPosition(idType: String.self)
-
-  var body: some View {
-    List {
-      ForEach(items) { item in
-        TimelineRow(item: item)
-          .id(item.id)
-          .listRowInsets(.init(top: 12, leading: 16, bottom: 12, trailing: 16))
-          .listRowSeparator(.hidden)
-      }
+struct ActivityFeed: View {
+    let events: [ActivityEvent]
+    @Environment(\.jumpToTop) private var jumpToTop
+    @State private var position = ScrollPosition(idType: ActivityEvent.ID.self)
+
+    var body: some View {
+        List {
+            ForEach(events) { event in
+                ActivityRow(event: event)
+                    .id(event.id)
+                    .listRowInsets(EdgeInsets(top: 10, leading: 16, bottom: 10, trailing: 16))
+                    .listRowSeparator(.hidden)
+            }
+        }
+        .listStyle(.plain)
+        .scrollPosition($position)
+        .onChange(of: jumpToTop) {
+            withAnimation { position.scrollTo(edge: .top) }
+        }
     }
-    .listStyle(.plain)
-    .environment(\.defaultMinListRowHeight, 1)
-    .scrollPosition($scrollPosition)
-    .onChange(of: selectedTabScrollToTop) {
-      withAnimation {
-        scrollPosition.scrollTo(edge: .top)
-      }
-    }
-  }
 }
 ```
 
-## Example: settings-style list
+`jumpToTop` stands for any signal, such as a counter the tab bar bumps when
+its tab is tapped again, passed down through a custom environment value.
+
+## Settings list
 
 ```swift
-@MainActor
-struct SettingsView: View {
-  var body: some View {
-    List {
-      Section("General") {
-        NavigationLink("Display") { DisplaySettingsView() }
-        NavigationLink("Haptics") { HapticsSettingsView() }
-      }
-      Section("Account") {
-        Button("Sign Out", role: .destructive) {}
-      }
+struct PrivacySettings: View {
+    var body: some View {
+        List {
+            Section("Data") {
+                NavigationLink("Location", value: PrivacyPage.location)
+                NavigationLink("Contacts", value: PrivacyPage.contacts)
+            }
+            Section {
+                Button("Delete Account", role: .destructive) { confirmDeletion() }
+            }
+        }
+        .listStyle(.insetGrouped)
     }
-    .listStyle(.insetGrouped)
-  }
+
+    private func confirmDeletion() {}
 }
 ```
 
-## Design choices to keep
+## Swipe actions on rows
 
-- Use `List` for dynamic feeds, settings, and any UI where row semantics help.
-- Use stable IDs for rows to keep animations and scroll positioning reliable.
-- Prefer `.contentShape(Rectangle())` on rows that should be tappable end-to-end.
-- Use `.refreshable` for pull-to-refresh feeds when the data source supports it.
+Swipe actions are a `List` row feature; the full guide with an example is in
+the parent skill under [Swipe actions](../SKILL.md#swipe-actions). Short version: put
+`.swipeActions(edge:allowsFullSwipe:content:)` on the row inside `ForEach`,
+use `role: .destructive` for delete, `.tint(_:)` for other actions, and
+mirror the actions in a context menu.
 
-## iOS 26 Scroll Edge Effects
-
-Apply edge effects to lists for modern scroll behavior:
+## Edge effect (iOS 26)
 
 ```swift
-List {
-    // rows
-}
-.scrollEdgeEffectStyle(.soft, for: .top)
+List(items) { ItemRow(item: $0) }
+    .scrollEdgeEffectStyle(.soft, for: .top)
 ```
 
-See `scrollview.md` for the full scroll edge effect and `backgroundExtensionEffect()` API reference.
+The full edge-effect API is covered in the
+[scroll view reference](scrollview.md).
 
 ## Pitfalls
 
-- Avoid heavy custom layouts inside a `List` row; use `ScrollView` + `LazyVStack` instead.
-- Be careful mixing `List` and nested `ScrollView`; it can cause gesture conflicts.
+- Heavy custom layouts inside rows; switch to `ScrollView` with `LazyVStack`.
+- A `ScrollView` nested in a `List` fights over gestures.

package/pipeline/skills/shared/external/swiftui-layout-components/references/scrollview.md

@@ -1,192 +1,152 @@
-# ScrollView and Lazy stacks
+# Scroll Views
 
-## Contents
+Scroll view guidance for the `swiftui-layout-components` skill.
 
-- [Intent](#intent)
-- [Core patterns](#core-patterns)
-- [Example: vertical custom feed](#example-vertical-custom-feed)
-- [ScrollPosition capabilities](#scrollposition-capabilities)
-- [Example: horizontal chips](#example-horizontal-chips)
-- [Example: adaptive grid](#example-adaptive-grid)
-- [Design choices to keep](#design-choices-to-keep)
-- [iOS 26 Scroll Edge Effects](#ios-26-scroll-edge-effects)
-- [Pitfalls](#pitfalls)
+## When to use ScrollView
 
-## Intent
+Pair `ScrollView` with `LazyVStack`, `LazyHStack` or `LazyVGrid` when you need
+a custom layout, mixed content, or horizontal or grid scrolling.
 
-Use `ScrollView` with `LazyVStack`, `LazyHStack`, or `LazyVGrid` when you need custom layout, mixed content, or horizontal/ grid-based scrolling.
+- Chat and custom feeds: `ScrollView` + `LazyVStack`.
+- Chips, tags, avatars, media strips: `ScrollView(.horizontal)` + `LazyHStack`.
+- Grids: `LazyVGrid`, with adaptive columns as the first choice.
+- Jumping to an item, to an edge or to a point: `ScrollPosition`.
+- An input bar that stays above the keyboard: `safeAreaInset(edge:)`.
 
-## Core patterns
-
-- Prefer `ScrollView` + `LazyVStack` for chat-like or custom feed layouts.
-- Use `ScrollView(.horizontal)` + `LazyHStack` for chips, tags, avatars, and media strips.
-- Use `LazyVGrid` for icon/media grids; prefer adaptive columns when possible.
-- Use `ScrollPosition` for programmatic scrolling: scroll-to-id, scroll-to-edge, and point-based offsets.
-- Use `safeAreaInset(edge:)` for input bars that should stick above the keyboard.
-
-## Example: vertical custom feed
+## Conversation screen
 
 ```swift
-@MainActor
-struct ConversationView: View {
-  @State private var scrollPosition = ScrollPosition(edge: .bottom)
-
-  var body: some View {
-    ScrollView {
-      LazyVStack {
-        ForEach(messages) { message in
-          MessageRow(message: message)
+struct SupportChat: View {
+    let lines: [ChatLine]
+    @State private var draft = ""
+    @State private var position = ScrollPosition(edge: .bottom)
+
+    var body: some View {
+        ScrollView {
+            LazyVStack(alignment: .leading) {
+                ForEach(lines) { ChatLineView(line: $0) }
+            }
+            .scrollTargetLayout()
+            .padding(.horizontal)
         }
-      }
-      .scrollTargetLayout()
-      .padding(.horizontal, .layoutPadding)
-    }
-    .scrollPosition($scrollPosition)
-    .safeAreaInset(edge: .bottom) {
-      MessageInputBar()
-    }
-    .onChange(of: messages.last?.id) {
-      withAnimation { scrollPosition.scrollTo(edge: .bottom) }
-    }
-  }
-}
-```
-
-## ScrollPosition capabilities
-
-`ScrollPosition` (iOS 18+) replaces `ScrollViewReader` for programmatic scrolling. It is declarative, supports bidirectional position tracking, and does not require a closure wrapper.
-
-**Setup:** Declare state and attach to the scroll view. Apply `.scrollTargetLayout()` to the inner layout container so SwiftUI can track individual view identities.
-
-```swift
-@State private var scrollPosition = ScrollPosition(idType: Message.ID.self)
-
-ScrollView {
-    LazyVStack {
-        ForEach(messages) { message in
-            MessageRow(message: message)
+        .scrollPosition($position)
+        .onChange(of: lines.last?.id) {
+            withAnimation { position.scrollTo(edge: .bottom) }
+        }
+        .safeAreaInset(edge: .bottom) {
+            HStack {
+                TextField("Reply", text: $draft)
+                Button("Send", systemImage: "paperplane.fill") { send() }
+            }
+            .padding()
+            .background(.bar)
         }
     }
-    .scrollTargetLayout()
+
+    private func send() {}
 }
-.scrollPosition($scrollPosition)
 ```
 
-**Scroll to a specific item:**
+## ScrollPosition
 
-```swift
-scrollPosition.scrollTo(id: message.id, anchor: .top)
-```
+`ScrollPosition` arrived in iOS 18 and takes over from `ScrollViewReader`. It
+is a value you bind, it works in both directions, and there is no reader
+closure to wrap your content in.
 
-**Scroll to an edge:**
+1. Store it: `@State private var position = ScrollPosition(idType: Track.ID.self)`.
+2. Put `.scrollTargetLayout()` on the lazy stack so item identities are tracked.
+3. Bind it on the scroll view: `.scrollPosition($position)`.
 
-```swift
-scrollPosition.scrollTo(edge: .bottom)
-```
-
-**Read the current position:**
+| Goal | Call |
+|------|------|
+| Scroll to an item | `position.scrollTo(id: track.id, anchor: .top)` |
+| Scroll to an edge | `position.scrollTo(edge: .bottom)` |
+| Read the item at the anchor | `position.viewID(type: Track.ID.self)` |
+| Know the user moved it | `position.isPositionedByUser` |
 
 ```swift
-if let currentID = scrollPosition.viewID(type: Message.ID.self) {
-    // The view with this ID is currently at the scroll anchor
+.onChange(of: position.isPositionedByUser) { _, byUser in
+    showJumpToLatest = byUser
 }
 ```
 
-**Detect user-initiated scrolls:**
+Keep ids stable; if they change, the position jumps. Wrap `scrollTo(id:)` in
+`withAnimation` when the move should be visible.
 
-```swift
-.onChange(of: scrollPosition.isPositionedByUser) { _, byUser in
-    if byUser {
-        // User scrolled manually -- show "scroll to bottom" button
-    }
-}
-```
-
-## Example: horizontal chips
+## More shapes
 
 ```swift
 ScrollView(.horizontal, showsIndicators: false) {
-  LazyHStack {
-    ForEach(chips) { chip in
-      ChipView(chip: chip)
+    LazyHStack(spacing: 8) {
+        ForEach(tags) { TagChip(tag: $0) }
     }
-  }
+    .padding(.horizontal)
 }
-```
-
-## Example: adaptive grid
-
-```swift
-let columns = [GridItem(.adaptive(minimum: 120))]
 
 ScrollView {
-  LazyVGrid(columns: columns) {
-    ForEach(items) { item in
-      GridItemView(item: item)
+    LazyVGrid(columns: [GridItem(.adaptive(minimum: 120))]) {
+        ForEach(albums) { AlbumTile(album: $0) }
     }
-  }
-  .padding()
+    .padding()
 }
 ```
 
-## Design choices to keep
-
-- Use `Lazy*` stacks when item counts are large or unknown.
-- Use non-lazy stacks for small, fixed-size content to avoid lazy overhead.
-- Keep IDs stable for `ScrollPosition` tracking; changing IDs causes position jumps.
-- Prefer explicit animations (`withAnimation`) when scrolling to an ID.
+Choose lazy stacks for large or unknown counts, plain stacks for small fixed
+content where lazy bookkeeping is wasted.
 
-## iOS 26 Scroll Edge Effects
+## Scroll edge effects (iOS 26)
 
-### scrollEdgeEffectStyle
-
-Configure the visual treatment at scroll view edges (iOS 26+):
+`.scrollEdgeEffectStyle(_:for:)` sets the effect per edge:
 
 ```swift
-ScrollView {
-    content
-}
-.scrollEdgeEffectStyle(.soft, for: .top)   // Soft fading edge at top
-.scrollEdgeEffectStyle(.hard, for: .bottom) // Hard cutoff at bottom
+ScrollView { ArticleBody() }
+    .scrollEdgeEffectStyle(.soft, for: .top)
+    .scrollEdgeEffectStyle(.hard, for: .bottom)
 ```
 
-`ScrollEdgeEffectStyle` values:
-- `.automatic` -- platform default
-- `.soft` -- soft fading edge effect
-- `.hard` -- hard cutoff with dividing line
+| `ScrollEdgeEffectStyle` | Look |
+|-------------------------|------|
+| `.automatic` | Platform default |
+| `.soft` | Content fades out at the edge |
+| `.hard` | Sharp cutoff with a dividing line |
 
-Use `scrollEdgeEffectHidden(_:for:)` to hide the edge effect entirely.
+`.scrollEdgeEffectHidden(true, for: .top)` removes the effect on that edge.
+Apply these modifiers to the scroll view itself, not to views inside it.
 
-### backgroundExtensionEffect
+### Background extension
 
-Duplicates, mirrors, and blurs the view to extend behind safe area edges (iOS 26+):
+`.backgroundExtensionEffect()` (iOS 26) copies a view, mirrors it and blurs it
+into the area behind safe-area edges, for example a hero image under the
+sidebar of a split view:
 
 ```swift
 NavigationSplitView {
-    sidebar
+    SidebarList()
 } detail: {
-    BannerView()
+    Image("coastline")
+        .resizable()
+        .aspectRatio(contentMode: .fill)
         .backgroundExtensionEffect()
 }
 ```
 
-Use sparingly -- Apple recommends only a single instance for visual clarity and performance. The modifier clips the view to prevent mirror overlap.
+Apple advises a single instance per screen for clarity and performance. The
+modifier clips the view so the mirrored copies do not overlap it.
 
-### safeAreaBar
+### Safe area bars
 
-Attach a bar view to the safe area edge, integrating with scroll edge effects (iOS 26+):
+`.safeAreaBar(edge:)` (iOS 26) attaches a bar that takes part in the scroll
+edge effect, unlike a plain inset:
 
 ```swift
-content
-    .safeAreaBar(edge: .top) {
-        FilterBar()
-    }
+ScrollView { ResultsGrid() }
+    .safeAreaBar(edge: .top) { FilterStrip() }
 ```
 
 ## Pitfalls
 
-- Avoid nesting scroll views of the same axis; it causes gesture conflicts.
-- Don't combine `List` and `ScrollView` in the same hierarchy without a clear reason.
-- Overuse of `LazyVStack` for tiny content can add unnecessary complexity.
-- Apply `scrollEdgeEffectStyle` on the ScrollView, not on inner content.
-- Use `backgroundExtensionEffect()` on only one view per screen.
+- Two scroll views on the same axis, one inside the other.
+- `List` and `ScrollView` combined without a strong reason.
+- `LazyVStack` for three rows: extra machinery for nothing.
+- `scrollEdgeEffectStyle` placed on inner content instead of the scroll view.
+- More than one `backgroundExtensionEffect()` on a screen.