swift-code-reviewer-skill 1.1.1 → 1.2.1

package/skills/swiftui-expert-skill/references/list-patterns.md

@@ -0,0 +1,394 @@
+# SwiftUI List Patterns Reference
+
+## Table of Contents
+
+- [ForEach Identity and Stability](#foreach-identity-and-stability)
+- [Enumerated Sequences](#enumerated-sequences)
+- [List with Custom Styling](#list-with-custom-styling)
+- [List with Pull-to-Refresh](#list-with-pull-to-refresh)
+- [Empty States with ContentUnavailableView (iOS 17+)](#empty-states-with-contentunavailableview-ios-17)
+- [Custom List Backgrounds](#custom-list-backgrounds)
+- [Table](#table)
+- [Summary Checklist](#summary-checklist)
+
+## ForEach Identity and Stability
+
+**Always provide stable identity for `ForEach`.** Never use `.indices` for dynamic content.
+
+```swift
+// Good - stable identity via Identifiable
+extension User: Identifiable {
+    var id: String { userId }
+}
+
+ForEach(users) { user in
+    UserRow(user: user)
+}
+
+// Good - stable identity via keypath
+ForEach(users, id: \.userId) { user in
+    UserRow(user: user)
+}
+
+// Wrong - indices create static content
+ForEach(users.indices, id: \.self) { index in
+    UserRow(user: users[index])  // Can crash on removal!
+}
+
+// Wrong - unstable identity
+ForEach(users, id: \.self) { user in
+    UserRow(user: user)  // Only works if User is Hashable and stable
+}
+```
+
+**Critical**: Ensure **constant number of views per element** in `ForEach`:
+
+```swift
+// Good - consistent view count
+ForEach(items) { item in
+    ItemRow(item: item)
+}
+
+// Bad - variable view count breaks identity
+ForEach(items) { item in
+    if item.isSpecial {
+        SpecialRow(item: item)
+        DetailRow(item: item)
+    } else {
+        RegularRow(item: item)
+    }
+}
+```
+
+**Avoid inline filtering:**
+
+```swift
+// Bad - unstable identity, changes on every update
+ForEach(items.filter { $0.isEnabled }) { item in
+    ItemRow(item: item)
+}
+
+// Good - prefilter and cache
+@State private var enabledItems: [Item] = []
+
+var body: some View {
+    ForEach(enabledItems) { item in
+        ItemRow(item: item)
+    }
+    .onChange(of: items) { _, newItems in
+        enabledItems = newItems.filter { $0.isEnabled }
+    }
+}
+```
+
+**Avoid `AnyView` in list rows:**
+
+```swift
+// Bad - hides identity, increases cost
+ForEach(items) { item in
+    AnyView(item.isSpecial ? SpecialRow(item: item) : RegularRow(item: item))
+}
+
+// Good - Create a unified row view
+ForEach(items) { item in
+    ItemRow(item: item)
+}
+
+struct ItemRow: View {
+    let item: Item
+
+    var body: some View {
+        if item.isSpecial {
+            SpecialRow(item: item)
+        } else {
+            RegularRow(item: item)
+        }
+    }
+}
+```
+
+**Why**: Stable identity is critical for performance and animations. Unstable identity causes excessive diffing, broken animations, and potential crashes.
+
+### Identifiable ID Must Be Truly Unique
+
+Non-unique IDs cause SwiftUI to treat different items as identical, leading to duplicate rendering or missing views:
+
+```swift
+// Bug -- two articles with the same URL show identical content
+struct Article: Identifiable {
+    let title: String
+    let url: URL
+    var id: String { url.absoluteString }  // Not unique if URLs repeat!
+}
+
+// Fix -- use a genuinely unique identifier
+struct Article: Identifiable {
+    let id: UUID
+    let title: String
+    let url: URL
+}
+```
+
+**Classes get a default `ObjectIdentifier`-based `id`** when conforming to `Identifiable` without providing one. This is only unique for the object's lifetime and can be recycled after deallocation.
+
+## Enumerated Sequences
+
+**Always convert enumerated sequences to arrays. To be able to use them in a ForEach.**
+
+```swift
+let items = ["A", "B", "C"]
+
+// Correct
+ForEach(Array(items.enumerated()), id: \.offset) { index, item in
+    Text("\(index): \(item)")
+}
+
+// Wrong - Doesn't compile, enumerated() isn't an array
+ForEach(items.enumerated(), id: \.offset) { index, item in
+    Text("\(index): \(item)")
+}
+```
+
+## List with Custom Styling
+
+```swift
+// Remove default background and separators
+List(items) { item in
+    ItemRow(item: item)
+        .listRowInsets(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
+        .listRowSeparator(.hidden)
+}
+.listStyle(.plain)
+.scrollContentBackground(.hidden)
+.background(Color.customBackground)
+.environment(\.defaultMinListRowHeight, 1)  // Allows custom row heights
+```
+
+## List with Pull-to-Refresh
+
+```swift
+List(items) { item in
+    ItemRow(item: item)
+}
+.refreshable {
+    await loadItems()
+}
+```
+
+## Empty States with ContentUnavailableView (iOS 17+)
+
+Use `ContentUnavailableView` for empty list/search states. The built-in `.search` variant is auto-localized:
+
+```swift
+List {
+    ForEach(searchResults) { item in
+        ItemRow(item: item)
+    }
+}
+.overlay {
+    if searchResults.isEmpty, !searchText.isEmpty {
+        ContentUnavailableView.search(text: searchText)
+    }
+}
+```
+
+For non-search empty states, use a custom instance:
+
+```swift
+ContentUnavailableView(
+    "No Articles",
+    systemImage: "doc.richtext.fill",
+    description: Text("Articles you save will appear here.")
+)
+```
+
+## Custom List Backgrounds
+
+Use `.scrollContentBackground(.hidden)` to replace the default list background:
+
+```swift
+List(items) { item in
+    ItemRow(item: item)
+}
+.scrollContentBackground(.hidden)
+.background(Color.customBackground)
+```
+
+Without `.scrollContentBackground(.hidden)`, a custom `.background()` has no visible effect on `List`.
+
+## Table
+
+> **Availability:** iOS 16.0+, iPadOS 16.0+, visionOS 1.0+
+
+A multi-column data container that presents rows of `Identifiable` data with sortable, selectable columns. On compact size classes (iPhone, iPad Slide Over), columns after the first are automatically hidden.
+
+### Basic Table
+
+```swift
+struct Person: Identifiable {
+    let givenName: String
+    let familyName: String
+    let emailAddress: String
+    let id = UUID()
+    var fullName: String { givenName + " " + familyName }
+}
+
+struct PeopleTable: View {
+    @State private var people: [Person] = [ /* ... */ ]
+
+    var body: some View {
+        Table(people) {
+            TableColumn("Given Name", value: \.givenName)
+            TableColumn("Family Name", value: \.familyName)
+            TableColumn("E-Mail Address", value: \.emailAddress)
+        }
+    }
+}
+```
+
+### Table with Selection
+
+Bind to a single `ID` for single-selection, or a `Set<ID>` for multi-selection:
+
+```swift
+struct SelectableTable: View {
+    @State private var people: [Person] = [ /* ... */ ]
+    @State private var selectedPeople = Set<Person.ID>()
+
+    var body: some View {
+        Table(people, selection: $selectedPeople) {
+            TableColumn("Given Name", value: \.givenName)
+            TableColumn("Family Name", value: \.familyName)
+            TableColumn("E-Mail Address", value: \.emailAddress)
+        }
+        Text("\(selectedPeople.count) people selected")
+    }
+}
+```
+
+### Sortable Table
+
+Provide a binding to `[KeyPathComparator]` and re-sort the data in `.onChange(of:)`:
+
+```swift
+struct SortableTable: View {
+    @State private var people: [Person] = [ /* ... */ ]
+    @State private var sortOrder = [KeyPathComparator(\Person.givenName)]
+
+    var body: some View {
+        Table(people, sortOrder: $sortOrder) {
+            TableColumn("Given Name", value: \.givenName)
+            TableColumn("Family Name", value: \.familyName)
+            TableColumn("E-Mail Address", value: \.emailAddress)
+        }
+        .onChange(of: sortOrder) { _, newOrder in
+            people.sort(using: newOrder)
+        }
+    }
+}
+```
+
+**Important:** The table does **not** sort data itself — you must re-sort the collection when `sortOrder` changes.
+
+### Adaptive Table for Compact Size Classes
+
+On iPhone or iPad in Slide Over, only the first column is shown. Customize it to display combined information:
+
+```swift
+struct AdaptiveTable: View {
+    @Environment(\.horizontalSizeClass) private var horizontalSizeClass
+    private var isCompact: Bool { horizontalSizeClass == .compact }
+
+    @State private var people: [Person] = [ /* ... */ ]
+    @State private var sortOrder = [KeyPathComparator(\Person.givenName)]
+
+    var body: some View {
+        Table(people, sortOrder: $sortOrder) {
+            TableColumn("Given Name", value: \.givenName) { person in
+                VStack(alignment: .leading) {
+                    Text(isCompact ? person.fullName : person.givenName)
+                    if isCompact {
+                        Text(person.emailAddress)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+            }
+            TableColumn("Family Name", value: \.familyName)
+            TableColumn("E-Mail Address", value: \.emailAddress)
+        }
+        .onChange(of: sortOrder) { _, newOrder in
+            people.sort(using: newOrder)
+        }
+    }
+}
+```
+
+### Table with Static Rows
+
+Use `init(of:columns:rows:)` when rows are known at compile time:
+
+```swift
+struct Purchase: Identifiable {
+    let price: Decimal
+    let id = UUID()
+}
+
+struct TipTable: View {
+    let currencyStyle = Decimal.FormatStyle.Currency(code: "USD")
+
+    var body: some View {
+        Table(of: Purchase.self) {
+            TableColumn("Base price") { purchase in
+                Text(purchase.price, format: currencyStyle)
+            }
+            TableColumn("With 15% tip") { purchase in
+                Text(purchase.price * 1.15, format: currencyStyle)
+            }
+            TableColumn("With 20% tip") { purchase in
+                Text(purchase.price * 1.2, format: currencyStyle)
+            }
+        } rows: {
+            TableRow(Purchase(price: 20))
+            TableRow(Purchase(price: 50))
+            TableRow(Purchase(price: 75))
+        }
+    }
+}
+```
+
+### Table Styles
+
+```swift
+// Inset (no borders)
+Table(people) { /* columns */ }
+    .tableStyle(.inset)
+
+// Hide column headers
+Table(people) { /* columns */ }
+    .tableColumnHeaders(.hidden)
+```
+
+### Platform Behavior
+
+| Platform | Behavior |
+|----------|----------|
+| **iPadOS (regular)** | Full multi-column layout; headers and all columns visible |
+| **iPadOS (compact)** | Only the first column shown; headers hidden |
+| **iPhone (all sizes)** | Only the first column shown; headers hidden; list-like appearance |
+
+> **Best Practice:** Prefer handling the compact size class by showing combined info in the first column. This provides a seamless transition when the size class changes (e.g., entering/exiting Slide Over on iPad).
+
+## Summary Checklist
+
+- [ ] ForEach uses stable identity (never `.indices` for dynamic content)
+- [ ] Identifiable IDs are truly unique across all items
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach (prefilter and cache instead)
+- [ ] No `AnyView` in list rows
+- [ ] Don't convert enumerated sequences to arrays
+- [ ] Use `.refreshable` for pull-to-refresh
+- [ ] Use `ContentUnavailableView` for empty states (iOS 17+)
+- [ ] Use `.scrollContentBackground(.hidden)` for custom list backgrounds
+- [ ] `Table` adapts for compact size classes (first column shows combined info)
+- [ ] `Table` sorting re-sorts data in `.onChange(of: sortOrder)` (table doesn't sort itself)
+- [ ] `Table` data conforms to `Identifiable`

package/skills/swiftui-expert-skill/references/macos-scenes.md

@@ -0,0 +1,318 @@
+# macOS Scenes Reference
+
+> SwiftUI scene types for macOS apps — `Settings`, `MenuBarExtra`, `WindowGroup`, `Window`, `UtilityWindow`, and `DocumentGroup`. Covers macOS-only scenes and cross-platform scenes with macOS-specific behavior.
+
+## Table of Contents
+
+- [Quick Lookup Table](#quick-lookup-table)
+- [Settings (macOS-only)](#settings-macos-only)
+- [MenuBarExtra (macOS-only)](#menubarextra-macos-only)
+- [WindowGroup (macOS behavior)](#windowgroup-macos-behavior)
+- [Window](#window)
+- [UtilityWindow (macOS-only)](#utilitywindow-macos-only)
+- [DocumentGroup](#documentgroup)
+- [Platform Conditionals](#platform-conditionals)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Lookup Table
+
+| API | Availability | macOS-Only? | macOS-Specific Behavior |
+|-----|-------------|:-----------:|------------------------|
+| `WindowGroup` | macOS 11.0+ | No | Multiple window instances, tabbed interface, automatic Window menu commands |
+| `Window` | macOS 13.0+ | No | App quits when sole window closes; adds itself to Windows menu |
+| `UtilityWindow` | macOS 15.0+ | Yes | Floating tool palette; receives `FocusedValues` from active main window |
+| `Settings` | macOS 11.0+ | Yes | Presents preferences window (Cmd+,) |
+| `MenuBarExtra` | macOS 13.0+ | Yes | Persistent icon/menu in the system menu bar |
+| `DocumentGroup` | macOS 11.0+ | No | Document-based menu bar commands (File > New/Open/Save); multiple document windows |
+
+---
+
+## Settings (macOS-only)
+
+Presents the app's preferences window, accessible via **Cmd+,** or the app menu. SwiftUI automatically enables the Settings menu item and manages the window lifecycle.
+
+```swift
+Settings {
+    TabView {
+        Tab("General", systemImage: "gear") { GeneralSettingsView() }
+        Tab("Advanced", systemImage: "star") { AdvancedSettingsView() }
+    }
+    .scenePadding()
+    .frame(maxWidth: 350, minHeight: 100)
+}
+```
+
+Use `TabView` with `Tab` items for multi-pane preferences. Each tab's content is typically a `Form` with `@AppStorage`-backed controls.
+
+### SettingsLink (macOS 14.0+)
+
+A button that opens the Settings scene. Use for in-app navigation to preferences.
+
+```swift
+struct SidebarFooter: View {
+    var body: some View {
+        SettingsLink {
+            Label("Preferences", systemImage: "gear")
+        }
+    }
+}
+```
+
+### openSettings environment action (macOS 14.0+)
+
+Programmatically open (or bring to front) the Settings window.
+
+```swift
+struct OpenSettingsButton: View {
+    @Environment(\.openSettings) private var openSettings
+
+    var body: some View {
+        Button("Open Settings") {
+            openSettings()
+        }
+    }
+}
+```
+
+---
+
+## MenuBarExtra (macOS-only)
+
+Renders a persistent control in the system menu bar. Two styles available:
+- **`.menu`** (default) — standard dropdown menu
+- **`.window`** — popover panel with custom SwiftUI views
+
+### Menu-style (dropdown)
+
+```swift
+MenuBarExtra("My Utility", systemImage: "hammer") {
+    Button("Action One") { /* ... */ }
+    Button("Action Two") { /* ... */ }
+    Divider()
+    Button("Quit") { NSApplication.shared.terminate(nil) }
+}
+```
+
+### Window-style (popover panel)
+
+```swift
+MenuBarExtra("Status", systemImage: "chart.bar") {
+    DashboardView()
+        .frame(width: 240)
+}
+.menuBarExtraStyle(.window)
+```
+
+**Variations:**
+- **Toggleable** — pass `isInserted:` with an `@AppStorage` binding to let users show/hide the extra: `MenuBarExtra("Status", systemImage: "chart.bar", isInserted: $showMenuBarExtra)`
+- **Menu-bar-only app** — use `MenuBarExtra` as the sole scene + set `LSUIElement = true` in Info.plist to hide the Dock icon. The app auto-terminates if the user removes the extra from the menu bar.
+
+---
+
+## WindowGroup (macOS behavior)
+
+On macOS, `WindowGroup` supports:
+- **Multiple window instances** — users can open many windows from File > New Window
+- **Tabbed interface** — users can merge windows into tabs
+- **Automatic Window menu** — commands for window management appear automatically
+
+```swift
+@main
+struct Mail: App {
+    var body: some Scene {
+        // Basic multi-window support
+        WindowGroup {
+            MailViewer()
+        }
+
+        // Data-presenting window opened programmatically
+        WindowGroup("Message", for: Message.ID.self) { $messageID in
+            MessageDetail(messageID: messageID)
+        }
+    }
+}
+
+// Open a specific window programmatically
+struct NewMessageButton: View {
+    var message: Message
+    @Environment(\.openWindow) private var openWindow
+
+    var body: some View {
+        Button("Open Message") {
+            openWindow(value: message.id)
+        }
+    }
+}
+```
+
+> **Key difference from `Window`:** `WindowGroup` keeps the app running even after all windows are closed. `Window` (as sole scene) quits the app when closed.
+
+---
+
+## Window
+
+A single, unique window scene. The system ensures only one instance exists.
+
+```swift
+@main
+struct Mail: App {
+    var body: some Scene {
+        WindowGroup {
+            MailViewer()
+        }
+
+        // Supplementary singleton window
+        Window("Connection Doctor", id: "connection-doctor") {
+            ConnectionDoctor()
+        }
+    }
+}
+
+// Open programmatically — brings to front if already open
+struct OpenDoctorButton: View {
+    @Environment(\.openWindow) private var openWindow
+
+    var body: some View {
+        Button("Connection Doctor") {
+            openWindow(id: "connection-doctor")
+        }
+    }
+}
+```
+
+### Window as sole scene
+
+If `Window` is the only scene, the app quits when the window closes:
+
+```swift
+@main
+struct VideoCall: App {
+    var body: some Scene {
+        Window("VideoCall", id: "main") {
+            CameraView()
+        }
+    }
+}
+```
+
+> **Recommendation:** In most cases, prefer `WindowGroup` for the primary scene. Use `Window` for supplementary singleton windows.
+
+---
+
+## UtilityWindow (macOS-only)
+
+A specialized floating window for tool palettes and inspector panels. Available since macOS 15.0.
+
+**Key behaviors:**
+- Receives `FocusedValues` from the focused main scene (like menu bar commands)
+- Floats above main windows (default level: `.floating`)
+- Hides when the app is no longer active
+- Only becomes focused when explicitly needed (e.g., clicking the title bar)
+- Dismissible with the Escape key
+- Not minimizable by default
+- Automatically adds a show/hide item to the View menu
+
+```swift
+@main
+struct PhotoBrowser: App {
+    var body: some Scene {
+        WindowGroup {
+            PhotoGallery()
+        }
+
+        UtilityWindow("Photo Info", id: "photo-info") {
+            PhotoInfoViewer()
+        }
+    }
+}
+
+struct PhotoInfoViewer: View {
+    // Automatically updates based on whichever main window is focused
+    @FocusedValue(PhotoSelection.self) private var selectedPhotos
+
+    var body: some View {
+        if let photos = selectedPhotos {
+            Text("\(photos.count) photos selected")
+        } else {
+            Text("No selection")
+                .foregroundStyle(.secondary)
+        }
+    }
+}
+```
+
+> **Tip:** Remove the automatic View menu item with `.commandsRemoved()` and place a `WindowVisibilityToggle` elsewhere in your commands.
+
+---
+
+## DocumentGroup
+
+Document-based apps with automatic file management. On macOS, provides:
+- **Document-based menu bar commands** (File > New, Open, Save, Revert)
+- **Multiple document windows** simultaneously
+- On iOS, shows a document browser instead
+
+```swift
+DocumentGroup(newDocument: TextFile()) { config in
+    ContentView(document: config.$document)
+}
+```
+
+The document type must conform to `FileDocument` (value type) or `ReferenceFileDocument` (reference type). Key requirements:
+
+```swift
+struct TextFile: FileDocument {
+    static var readableContentTypes: [UTType] { [.plainText] }
+    var text: String = ""
+    init() {}
+    init(configuration: ReadConfiguration) throws {
+        text = String(data: configuration.file.regularFileContents ?? Data(), encoding: .utf8) ?? ""
+    }
+    func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
+        FileWrapper(regularFileWithContents: Data(text.utf8))
+    }
+}
+```
+
+For multiple document types, add additional `DocumentGroup` scenes — use `DocumentGroup(viewing:)` for read-only formats.
+
+---
+
+## Platform Conditionals
+
+Always wrap macOS-only scenes in `#if os(macOS)`:
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+
+        #if os(macOS)
+        Settings {
+            SettingsView()
+        }
+
+        MenuBarExtra("Status", systemImage: "bolt") {
+            StatusMenu()
+        }
+        #endif
+    }
+}
+```
+
+---
+
+## Best Practices
+
+- **Use `Settings`** for preferences — prefer this over a custom preferences window
+- **Use `MenuBarExtra`** for menu bar items — prefer this over managing AppKit's `NSStatusItem` directly
+- **Use `WindowGroup`** as the primary scene — reserve `Window` for supplementary singletons
+- **Use `UtilityWindow`** for inspectors/palettes — it handles floating, focus, and visibility automatically
+- **Use `DocumentGroup`** for document-based apps — it provides the full File menu and document lifecycle
+- **Gate macOS-only scenes** with `#if os(macOS)` for multiplatform projects
+- **Use `openWindow(id:)`** to open windows programmatically — it brings existing windows to front