@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,97 +1,115 @@
-# Form
+# Forms
 
-## Intent
+Form guidance for the `swiftui-layout-components` skill.
 
-Use `Form` for structured settings, grouped inputs, and action rows. This pattern keeps layout, spacing, and accessibility consistent for data entry screens.
+## When to use Form
 
-## Core patterns
+Settings, grouped inputs and action rows belong in a `Form`. It gives
+consistent layout, spacing and accessibility without hand tuning.
 
-- Wrap the form in a `NavigationStack` only when it is presented in a sheet or standalone view without an existing navigation context.
-- Group related controls into `Section` blocks.
-- Use `.scrollContentBackground(.hidden)` plus a custom background color when you need design-system colors.
-- Apply `.formStyle(.grouped)` for grouped styling when appropriate.
-- Use `@FocusState` to manage keyboard focus in input-heavy forms.
+- Add a `NavigationStack` around it only when it is presented in a sheet or
+  stands alone with no navigation context.
+- For design-system colors, hide the default background with
+  `.scrollContentBackground(.hidden)` and supply your own.
+- `.formStyle(.grouped)` where the grouped look fits.
+- `@FocusState` for moving between fields.
 
-## Example: settings-style form
+## Settings form
 
 ```swift
-@MainActor
-struct SettingsView: View {
-  @Environment(Theme.self) private var theme
-
-  var body: some View {
-    NavigationStack {
-      Form {
-        Section("General") {
-          NavigationLink("Display") { DisplaySettingsView() }
-          NavigationLink("Haptics") { HapticsSettingsView() }
+struct NotificationSettings: View {
+    @AppStorage("alerts.digest") private var dailyDigest = true
+    @AppStorage("alerts.sound") private var playSound = false
+
+    var body: some View {
+        Form {
+            Section("Alerts") {
+                Toggle("Daily Digest", isOn: $dailyDigest)
+                Toggle("Play Sound", isOn: $playSound)
+            }
+            .listRowBackground(Color.cardSurface)
+
+            Section {
+                Button { openSystemSettings() } label: {
+                    Label("System Notification Settings", systemImage: "gear")
+                }
+                .buttonStyle(.plain)
+            }
+            .listRowBackground(Color.cardSurface)
         }
-
-        Section("Account") {
-          Button("Edit profile") { /* open sheet */ }
-            .buttonStyle(.plain)
-        }
-        .listRowBackground(theme.primaryBackgroundColor)
-      }
-      .navigationTitle("Settings")
-      .navigationBarTitleDisplayMode(.inline)
-      .scrollContentBackground(.hidden)
-      .background(theme.secondaryBackgroundColor)
+        .navigationTitle("Notifications")
+        .navigationBarTitleDisplayMode(.inline)
+        .scrollContentBackground(.hidden)
+        .background(Color.screenBackground)
     }
-  }
+
+    private func openSystemSettings() {}
 }
 ```
 
-## Example: modal form with validation
+`Color.cardSurface` and `Color.screenBackground` stand for your design-system
+colors.
+
+## Modal form with validation
 
 ```swift
-@MainActor
-struct AddRemoteServerView: View {
-  @Environment(\.dismiss) private var dismiss
-  @Environment(Theme.self) private var theme
-
-  @State private var server: String = ""
-  @State private var isValid = false
-  @FocusState private var isServerFieldFocused: Bool
-
-  var body: some View {
-    NavigationStack {
-      Form {
-        TextField("Server URL", text: $server)
-          .keyboardType(.URL)
-          .textInputAutocapitalization(.never)
-          .autocorrectionDisabled()
-          .focused($isServerFieldFocused)
-          .listRowBackground(theme.primaryBackgroundColor)
-
-        Button("Add") {
-          guard isValid else { return }
-          dismiss()
+struct AddFeedSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    @State private var address = ""
+    @FocusState private var addressFocused: Bool
+
+    private var isValid: Bool {
+        guard let url = URL(string: address) else { return false }
+        return url.scheme == "https" && url.host() != nil
+    }
+
+    var body: some View {
+        NavigationStack {
+            Form {
+                Section("Feed Address") {
+                    TextField("https://", text: $address)
+                        .keyboardType(.URL)
+                        .textInputAutocapitalization(.never)
+                        .autocorrectionDisabled()
+                        .focused($addressFocused)
+                }
+                Section {
+                    Button("Add Feed") {
+                        guard isValid else { return }
+                        subscribe()
+                        dismiss()
+                    }
+                    .disabled(!isValid)
+                }
+            }
+            .scrollDismissesKeyboard(.immediately)
+            .navigationTitle("New Feed")
+            .toolbar {
+                ToolbarItem(placement: .cancellationAction) {
+                    Button("Cancel") { dismiss() }
+                }
+            }
+            .onAppear { addressFocused = true }
         }
-        .disabled(!isValid)
-        .listRowBackground(theme.primaryBackgroundColor)
-      }
-      .formStyle(.grouped)
-      .navigationTitle("Add Server")
-      .navigationBarTitleDisplayMode(.inline)
-      .scrollContentBackground(.hidden)
-      .background(theme.secondaryBackgroundColor)
-      .scrollDismissesKeyboard(.immediately)
-      .toolbar { CancelToolbarItem() }
-      .onAppear { isServerFieldFocused = true }
     }
-  }
+
+    private func subscribe() {}
 }
 ```
 
-## Design choices to keep
+The submit button is disabled until the input is valid and checks again when
+tapped; the field is focused as soon as the sheet appears.
+
+## Design choices
 
-- Prefer `Form` over custom stacks for settings and input screens.
-- Keep rows tappable by using `.contentShape(Rectangle())` and `.buttonStyle(.plain)` on row buttons.
-- Use list row backgrounds to keep section styling consistent with your theme.
+- A `Form` beats a custom stack for settings and data entry.
+- Rows with buttons stay fully tappable with `.contentShape(Rectangle())` and
+  `.buttonStyle(.plain)`.
+- `.listRowBackground(_:)` matches rows to the theme.
 
 ## Pitfalls
 
-- Avoid heavy custom layouts inside a `Form`; it can lead to spacing issues.
-- If you need highly custom layouts, prefer `ScrollView` + `VStack`.
-- Don't mix multiple background strategies; pick either default Form styling or custom colors.
+- Heavy custom layouts inside a `Form` fight its spacing; for very custom
+  screens use `ScrollView` with a `VStack`.
+- Choose one background approach: the default form styling or your own
+  colors, not a mix of both.

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

@@ -1,230 +1,165 @@
 # Grids
 
-## Contents
-- Intent
-- Choosing the right grid type
-- Column strategies
-- Cell sizing and aspect ratio
-- Example: adaptive icon grid
-- Example: fixed 3-column media grid
-- Example: sectioned grid
-- Selection and interaction patterns
-- Performance guardrails
-- Accessibility and polish
-- Pitfalls
+Grid guidance for the `swiftui-layout-components` skill.
 
-## Intent
+## When a grid is the right shape
 
-Use grids for dense visual collections where row-based layouts waste space or
-make scanning harder.
+Reach for a grid when items are visual and a one-per-row list would waste
+width or slow scanning: icon pickers, photo and video galleries, template
+choosers, settings tiles, dashboards of cards. On iOS the everyday choice is a
+`LazyVGrid` in a vertical `ScrollView`. `Grid` is for a handful of items that
+do not scroll, or when you need to compose rows explicitly.
 
-Good fits:
+## Picking the grid type
 
-- icon pickers
-- media galleries
-- template choosers
-- settings tiles
-- dashboards with repeatable cards
-
-Default to `LazyVGrid` for vertically scrolling collections on iOS. Reach for
-`Grid` when content is small and non-scrollable, or when you need explicit row
-composition rather than a large lazy container.
-
-## Choosing the right grid type
-
-### `LazyVGrid`
-
-Use for the common iPhone/iPad case: many items, vertical scrolling, and a
-column definition that should adapt to width.
-
-### `LazyHGrid`
-
-Use when horizontal scrolling is the dominant interaction and rows are easier to
-define than columns.
-
-### `Grid`
-
-Use when:
-
-- the item count is small
-- the content is mostly static
-- row/column relationships matter more than lazy loading
-- you need `GridRow` composition instead of a repeated collection layout
-
-For large scrolling datasets, `LazyVGrid` is usually the safer default.
+| Type | Pick it when |
+|------|--------------|
+| `LazyVGrid` | Many items, vertical scrolling, column count should follow width. The usual iPhone and iPad case, and the safe default for big data sets |
+| `LazyHGrid` | Horizontal scrolling is the main motion and rows are easier to describe than columns |
+| `Grid` + `GridRow` | Few, mostly static items where alignment across rows and columns matters more than laziness |
 
 ## Column strategies
 
-### Adaptive columns
-
-Use `.adaptive` when you want the number of columns to respond to available
-width.
-
-```swift
-let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
-```
-
-This is the best default for icon pickers, template choosers, and photo grids
-that should scale naturally across iPhone and iPad sizes.
+**Adaptive.** `GridItem(.adaptive(minimum: 110, maximum: 220))` fits as many
+columns as the width allows. Start here for photo grids, template choosers and
+icon pickers.
 
-### Flexible columns
+**Flexible.** Two or three `.flexible(minimum: 100)` items give a steady
+two-up or three-up rhythm regardless of device.
 
-Use multiple `.flexible` columns when you want a predictable column count.
+**Fixed.** `.fixed(width)` only when an exact width is required. It copes
+poorly with different screen sizes and with Dynamic Type.
 
-```swift
-let columns = [
-    GridItem(.flexible(minimum: 100)),
-    GridItem(.flexible(minimum: 100)),
-    GridItem(.flexible(minimum: 100)),
-]
-```
+## Sizing cells
 
-This works well when design requires a fixed 2-column or 3-column rhythm.
+A cell decides its own shape; it never asks the parent how big it is.
 
-### Fixed columns
+- Square tiles come from `.aspectRatio(1, contentMode: .fit)`.
+- `.frame(maxWidth: .infinity)` to fill the column.
+- Padding inside the cell instead of arithmetic on geometry.
 
-Use `.fixed` only when the design truly requires exact widths. Fixed columns are
-less resilient across device sizes and dynamic type changes.
+Avoid `GeometryReader` in lazy containers: it breaks lazy layout and adds
+measurement passes. If a cell truly must react to its size, use
+`.onGeometryChange(for:of:action:)`. Apple lists it for iOS 16.0+, macOS
+13.0+, tvOS 16.0+, watchOS 9.0+ and visionOS 1.0+ (back-deployed, so compile
+with the Xcode 16 SDK or newer).
 
-## Cell sizing and aspect ratio
-
-Grid cells should usually define their own shape without reading parent
-geometry.
-
-Preferred sizing tools:
-
-- `.aspectRatio(1, contentMode: .fit)` for square thumbnails
-- `.frame(maxWidth: .infinity)` when content should fill the available column
-- internal padding instead of outer geometry math
-
-Avoid `GeometryReader` inside lazy containers. It defeats lazy layout and adds
-extra measurement work.
-
-## Example: adaptive icon grid
+## Adaptive picker with selection
 
 ```swift
-let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
-
-LazyVGrid(columns: columns) {
-    ForEach(icons) { icon in
-        Button {
-            select(icon)
-        } label: {
-            ZStack(alignment: .bottomTrailing) {
-                Image(icon.previewName)
-                    .resizable()
-                    .aspectRatio(contentMode: .fit)
-                    .clipShape(.rect(cornerRadius: 6))
-
-                if icon.isSelected {
-                    Image(systemName: "checkmark.seal.fill")
-                        .padding(4)
-                        .tint(.green)
+struct WallpaperPicker: View {
+    let wallpapers: [Wallpaper]
+    @Binding var chosen: Wallpaper.ID?
+
+    var body: some View {
+        ScrollView {
+            LazyVGrid(columns: [GridItem(.adaptive(minimum: 104, maximum: 180))]) {
+                ForEach(wallpapers) { paper in
+                    Button { chosen = paper.id } label: {
+                        ZStack(alignment: .bottomTrailing) {
+                            Image(paper.assetName)
+                                .resizable()
+                                .aspectRatio(1, contentMode: .fit)
+                                .clipShape(.rect(cornerRadius: 10))
+                            if chosen == paper.id {
+                                Image(systemName: "checkmark.circle.fill")
+                                    .foregroundStyle(.white, .tint)
+                                    .padding(6)
+                            }
+                        }
+                    }
+                    .buttonStyle(.plain)
+                    .contentShape(Rectangle())
+                    .accessibilityLabel(paper.title)
+                    .accessibilityAddTraits(chosen == paper.id ? .isSelected : [])
                 }
             }
+            .padding()
         }
-        .buttonStyle(.plain)
-        .contentShape(Rectangle())
     }
 }
 ```
 
-Why this works:
-
-- adaptive columns scale across width classes
-- square-ish cells come from image aspect ratio, not geometry reads
-- the whole tile remains tappable
+Adaptive columns follow the size class, the image's aspect ratio (not geometry)
+makes the tile square, and the whole tile is the hit area.
 
-## Example: fixed 3-column media grid
+## Three-up media gallery
 
 ```swift
-LazyVGrid(
-    columns: [
-        .init(.flexible(minimum: 100), spacing: 4),
-        .init(.flexible(minimum: 100), spacing: 4),
-        .init(.flexible(minimum: 100), spacing: 4),
-    ],
-    spacing: 4
-) {
-    ForEach(items) { item in
-        ThumbnailView(item: item)
-            .aspectRatio(1, contentMode: .fit)
-            .clipShape(.rect(cornerRadius: 8))
+struct ClipGallery: View {
+    let clips: [Clip]
+    private let columns = [GridItem](
+        repeating: GridItem(.flexible(minimum: 96), spacing: 3),
+        count: 3
+    )
+
+    var body: some View {
+        ScrollView {
+            LazyVGrid(columns: columns, spacing: 3) {
+                ForEach(clips) { clip in
+                    ClipThumbnail(clip: clip)
+                        .aspectRatio(1, contentMode: .fill)
+                        .clipShape(.rect(cornerRadius: 4))
+                }
+            }
+        }
     }
 }
 ```
 
-Use this when the design language wants a consistent three-up gallery instead of
-an adaptive count.
-
-## Example: sectioned grid
+Use this when every row should show exactly three thumbnails.
 
-Sectioned grids work well for grouped content like categories or recents.
+## Sections in a grid
 
 ```swift
-LazyVGrid(columns: [GridItem(.adaptive(minimum: 140))]) {
-    ForEach(sections) { section in
+LazyVGrid(columns: [GridItem(.adaptive(minimum: 120))]) {
+    ForEach(shelves) { shelf in
         Section {
-            ForEach(section.items) { item in
-                Tile(item: item)
-            }
+            ForEach(shelf.books) { BookCover(book: $0) }
         } header: {
-            Text(section.title)
+            Text(shelf.name)
                 .font(.headline)
                 .frame(maxWidth: .infinity, alignment: .leading)
-                .padding(.top)
         }
     }
 }
 ```
 
-Keep headers visually lightweight. Dense grids lose scan efficiency when every
-section header is oversized or heavily decorated.
-
-## Selection and interaction patterns
-
-Grid interactions should stay obvious and forgiving.
-
-Useful defaults:
-
-- make the entire cell tappable with `.contentShape(Rectangle())`
-- show selection state in one consistent corner or border treatment
-- keep hover/focus/pressed states subtle but visible
-- avoid stacking too many overlays on every item
-
-For multi-select grids, prefer clear selection affordances instead of hidden
-state changes triggered only by long press.
+Grouping works well for categories or a recents row. Keep headers small; big
+headers slow down scanning.
 
-## Performance guardrails
+## Selection and interaction
 
-- Use `LazyVGrid` for large collections.
-- Keep overlay count low in every cell.
-- Downsample large images before display.
-- Avoid expensive formatting or filtering in cell bodies.
-- Prefer stable item identity in `ForEach`.
-- Precompute grouped or filtered collections before rendering.
+- The whole cell is the tap target (`.contentShape(Rectangle())`).
+- Mark selection the same way everywhere: one corner badge or one border style.
+- Pressed, hover and focus states should be quiet but visible.
+- Few overlays per cell.
+- Multi-select needs a visible affordance; do not hide it behind long press.
 
-If scrolling stutters, profile image decoding, per-cell overlays, and repeated
-state invalidation before changing the grid structure itself.
+## Performance
 
-## Accessibility and polish
+- `LazyVGrid` for large collections.
+- Downsample big images before display.
+- No expensive formatting or filtering inside cell bodies; precompute grouped
+  or filtered arrays.
+- Stable identity for every item.
+- Janky scrolling? Measure first: image decoding, overlays on each cell and
+  state that invalidates too often are the usual causes, and fixing them is
+  cheaper than rebuilding the grid.
 
-- Maintain clear visual grouping and consistent spacing.
-- Test with Dynamic Type even if cells are primarily visual.
-- Ensure VoiceOver labels describe the item and selection state.
-- Use meaningful focus order on iPad and keyboard-driven flows.
-- Avoid tiny hit targets even when cells are visually dense.
+## Accessibility
 
-A dense grid should still feel calm and legible, not like a wall of competing
-badges and borders.
+- Group clearly and space consistently.
+- Try the largest Dynamic Type sizes, even for image-heavy cells.
+- VoiceOver labels name the item and say whether it is selected.
+- On iPad and with a keyboard, focus should move in a sensible order.
+- Keep hit targets comfortably large.
 
 ## Pitfalls
 
-- Avoid heavy overlays in every grid cell; it can be expensive.
-- Don't nest grids inside other grids without a clear reason.
-- Don't put filtering logic inline in `ForEach`.
-- Don't use fixed columns where adaptive columns better match the product goal.
-- **Never place `GeometryReader` inside lazy containers** (`LazyVGrid`,
-  `LazyHGrid`, `LazyVStack`, `LazyHStack`). It forces eager measurement and
-  defeats lazy loading. Use `.aspectRatio` for sizing, or `.onGeometryChange`
-  (iOS 18+) if you need to read dimensions.
+- A heavy overlay stack on every cell.
+- Grids nested inside grids without a reason.
+- Filtering inline in `ForEach`.
+- Fixed columns where adaptive ones fit the goal.
+- `GeometryReader` in `LazyVGrid`, `LazyHGrid`, `LazyVStack` or `LazyHStack`;
+  use `.aspectRatio`, or `.onGeometryChange` (iOS 16.0+) when a size must be read.