swift-code-reviewer-skill 1.2.0 → 1.3.0

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

@@ -0,0 +1,357 @@
+# macOS Views & Components Reference
+
+> macOS-specific SwiftUI views, file operations, drag & drop, and AppKit interop. Covers `HSplitView`, `VSplitView`, `Table`, `PasteButton`, file dialogs, cross-app drag & drop, and `NSViewRepresentable`.
+
+## Table of Contents
+
+- [Quick Lookup Table](#quick-lookup-table)
+- [HSplitView & VSplitView (macOS-only)](#hsplitview--vsplitview-macos-only)
+- [Table](#table)
+- [PasteButton & CopyButton](#pastebutton--copybutton)
+- [File Operations](#file-operations)
+- [Drag, Drop & Pasteboard](#drag-drop--pasteboard)
+- [AppKit Interop](#appkit-interop)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Lookup Table
+
+### Views
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `HSplitView` | macOS 10.15+ | Yes | Horizontal resizable split layout with user-draggable dividers |
+| `VSplitView` | macOS 10.15+ | Yes | Vertical resizable split layout with user-draggable dividers |
+| `Table` | macOS 12.0+ | No | Full multi-column layout with sorting; on iOS compact, columns collapse |
+| `PasteButton` | macOS 10.15+ | No | System button that reads clipboard; does NOT auto-validate on macOS |
+| `CopyButton` | macOS 15.0+ | Yes | System button that copies `Transferable` content to clipboard |
+
+### File Operations
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `fileImporter()` | macOS 11.0+ | No | Native NSOpenPanel with column/list/gallery view, sidebar, tags, QuickLook |
+| `fileExporter()` | macOS 11.0+ | No | Native NSSavePanel with format dropdown, tags field |
+| `fileMover()` | macOS 11.0+ | No | Native macOS move panel with Finder-like navigation |
+| `fileDialogMessage(_:)` | macOS 13.0+ | Yes | Custom message text in file dialogs |
+| `fileDialogConfirmationLabel(_:)` | macOS 13.0+ | Yes | Custom confirm button text in file dialogs |
+| `fileExporterFilenameLabel(_:)` | macOS 13.0+ | Yes | Custom filename field label in file exporter |
+
+### Drag, Drop & Pasteboard
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `onDrag(_:)` / `draggable(_:)` | macOS 11.0+ | No | Drag image follows cursor; items draggable between apps |
+| `onDrop(of:delegate:)` / `dropDestination(for:action:)` | macOS 11.0+ | No | Accepts drops from any macOS app including Finder |
+
+### AppKit Interop
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `NSViewRepresentable` | macOS 10.15+ | Yes | Wrap an AppKit `NSView` in SwiftUI |
+| `NSViewControllerRepresentable` | macOS 10.15+ | Yes | Wrap an AppKit `NSViewController` in SwiftUI |
+| `NSHostingController` | macOS 10.15+ | Yes | Host SwiftUI inside an AppKit view controller |
+| `NSHostingView` | macOS 10.15+ | Yes | Host SwiftUI inside an AppKit `NSView` hierarchy |
+
+---
+
+## HSplitView & VSplitView (macOS-only)
+
+Resizable split layouts with user-draggable dividers. Use for IDE-style panes where all panels are equal peers. `VSplitView` works identically but splits vertically (use `minHeight` instead).
+
+```swift
+HSplitView {
+    FileTreeView()
+        .frame(minWidth: 200)
+    CodeEditorView()
+        .frame(minWidth: 400)
+    PreviewPane()
+        .frame(minWidth: 200)
+}
+```
+
+> **When to use which:**
+> - **`NavigationSplitView`** — sidebar-based navigation (sidebar drives content/detail)
+> - **`HSplitView`/`VSplitView`** — IDE-style layouts where all panes are equal peers
+
+---
+
+## Table
+
+For `Table` basics (creation, selection, sorting, adaptive compact layout), see `list-patterns.md`. This section covers macOS-specific table styling.
+
+### Table styles
+
+```swift
+// Bordered with visible grid lines (macOS-only)
+Table(people) { /* columns */ }
+    .tableStyle(.bordered)
+
+// Bordered with alternating row backgrounds
+Table(people) { /* columns */ }
+    .tableStyle(.bordered(alternatesRowBackgrounds: true))
+
+// Inset (no borders)
+Table(people) { /* columns */ }
+    .tableStyle(.inset)
+
+// Hide column headers
+Table(people) { /* columns */ }
+    .tableColumnHeaders(.hidden)
+```
+
+---
+
+## PasteButton & CopyButton
+
+### PasteButton
+
+System button that reads clipboard content via `Transferable`. On macOS, it does NOT auto-validate pasteboard changes (unlike iOS).
+
+```swift
+struct ClipboardView: View {
+    @State private var pastedText = ""
+
+    var body: some View {
+        HStack {
+            PasteButton(payloadType: String.self) { strings in
+                pastedText = strings[0]
+            }
+            Divider()
+            Text(pastedText)
+            Spacer()
+        }
+    }
+}
+```
+
+### CopyButton (macOS 15.0+, macOS-only)
+
+System button that copies `Transferable` content to the clipboard.
+
+```swift
+struct CopyableContent: View {
+    let shareableText = "Hello, world!"
+
+    var body: some View {
+        HStack {
+            Text(shareableText)
+            CopyButton(item: shareableText)
+        }
+    }
+}
+```
+
+---
+
+## File Operations
+
+### fileImporter
+
+On macOS, presents a native `NSOpenPanel` with column/list/gallery view, sidebar favorites, tags, and QuickLook.
+
+```swift
+.fileImporter(
+    isPresented: $showImporter,
+    allowedContentTypes: [.pdf],
+    allowsMultipleSelection: false
+) { result in
+    if case .success(let urls) = result, let url = urls.first {
+        guard url.startAccessingSecurityScopedResource() else { return }
+        defer { url.stopAccessingSecurityScopedResource() }
+        // use url
+    }
+}
+```
+
+> **Important:** Always call `startAccessingSecurityScopedResource()` on returned URLs, and `stopAccessingSecurityScopedResource()` when done. These are security-scoped bookmarks — access fails without this.
+
+### fileExporter
+
+On macOS, presents a native `NSSavePanel` with format dropdown and tags.
+
+```swift
+.fileExporter(
+    isPresented: $showExporter,
+    document: document,
+    contentType: .plainText,
+    defaultFilename: "MyFile.txt"
+) { result in
+    // handle Result<URL, Error>
+}
+```
+
+### File dialog customization (macOS-only)
+
+Customize text in file dialogs with these macOS-specific modifiers:
+
+```swift
+// Custom message and confirm button on file importer
+.fileImporter(
+    isPresented: $showImporter,
+    allowedContentTypes: [.image]
+) { result in
+    // handle result
+}
+.fileDialogMessage("Select an image to use as your profile photo")
+.fileDialogConfirmationLabel("Use This Photo")
+
+// Custom filename label on file exporter
+.fileExporter(
+    isPresented: $showExporter,
+    document: myDocument,
+    contentType: .png
+) { result in
+    // handle result
+}
+.fileExporterFilenameLabel("Export As:")
+```
+
+---
+
+## Drag, Drop & Pasteboard
+
+On macOS, drag and drop works **across applications** (e.g., drag from your app to Finder, Mail, or other apps).
+
+### Modern approach (Transferable)
+
+```swift
+// Drag source
+struct DraggableCard: View {
+    let item: MyItem
+
+    var body: some View {
+        Text(item.title)
+            .draggable(item)  // Requires Transferable conformance
+    }
+}
+
+// Drop target
+struct DropZone: View {
+    @State private var droppedItems: [MyItem] = []
+
+    var body: some View {
+        VStack {
+            ForEach(droppedItems) { item in
+                Text(item.title)
+            }
+        }
+        .dropDestination(for: MyItem.self) { items, location in
+            droppedItems.append(contentsOf: items)
+            return true
+        }
+        .frame(width: 300, height: 200)
+        .border(.secondary)
+    }
+}
+```
+
+### Legacy approach (NSItemProvider)
+
+```swift
+// Drag source
+Image(systemName: "doc")
+    .onDrag {
+        NSItemProvider(object: fileURL as NSURL)
+    }
+
+// Drop target
+Text("Drop files here")
+    .onDrop(of: [.fileURL], isTargeted: nil) { providers in
+        // handle providers
+        return true
+    }
+```
+
+---
+
+## AppKit Interop
+
+### NSViewRepresentable (macOS-only)
+
+Wraps an AppKit `NSView` for use in SwiftUI. Implement `makeNSView(context:)` and `updateNSView(_:context:)`.
+
+```swift
+struct WebView: NSViewRepresentable {
+    let url: URL
+    func makeNSView(context: Context) -> WKWebView { WKWebView() }
+    func updateNSView(_ nsView: WKWebView, context: Context) {
+        nsView.load(URLRequest(url: url))
+    }
+}
+```
+
+### NSViewRepresentable with Coordinator
+
+Use a Coordinator to forward delegate/target-action callbacks to SwiftUI.
+
+```swift
+struct SearchField: NSViewRepresentable {
+    @Binding var text: String
+
+    func makeNSView(context: Context) -> NSSearchField {
+        let field = NSSearchField()
+        field.delegate = context.coordinator
+        return field
+    }
+    func updateNSView(_ nsView: NSSearchField, context: Context) {
+        nsView.stringValue = text
+    }
+    func makeCoordinator() -> Coordinator { Coordinator(text: $text) }
+
+    class Coordinator: NSObject, NSSearchFieldDelegate {
+        var text: Binding<String>
+        init(text: Binding<String>) { self.text = text }
+        func controlTextDidChange(_ obj: Notification) {
+            if let field = obj.object as? NSSearchField {
+                text.wrappedValue = field.stringValue
+            }
+        }
+    }
+}
+```
+
+> **Warning:** Never set `frame`/`bounds` directly on the managed `NSView` — SwiftUI owns the layout.
+
+### NSViewControllerRepresentable (macOS-only)
+
+Wraps an AppKit `NSViewController` for use in SwiftUI.
+
+```swift
+struct MapViewWrapper: NSViewControllerRepresentable {
+    func makeNSViewController(context: Context) -> MapViewController {
+        MapViewController()
+    }
+
+    func updateNSViewController(_ nsViewController: MapViewController, context: Context) {
+        // Update the controller when SwiftUI state changes
+    }
+}
+```
+
+### NSHostingController & NSHostingView (macOS-only)
+
+Host SwiftUI content inside AppKit (reverse direction — AppKit app embedding SwiftUI views).
+
+```swift
+// Host SwiftUI as a view controller
+let hostingController = NSHostingController(rootView: MySwiftUIView())
+window.contentViewController = hostingController
+
+// Host SwiftUI directly as an NSView
+let hostingView = NSHostingView(rootView: MySwiftUIView())
+someNSView.addSubview(hostingView)
+```
+
+---
+
+## Best Practices
+
+- **Use `NavigationSplitView`** for sidebar-driven navigation — reserve `HSplitView`/`VSplitView` for IDE-style equal peer panes
+- **Make `Table` adaptive** — handle compact size classes by showing combined info in the first column
+- **Always call `startAccessingSecurityScopedResource()`** on URLs from `fileImporter` — they are security-scoped
+- **Use `Transferable`** for drag & drop (modern) — fall back to `NSItemProvider` only for legacy compatibility
+- **Use `NSViewRepresentable` with Coordinator** when you need delegate callbacks from AppKit views
+- **Never set `frame`/`bounds`** directly on views managed by `NSViewRepresentable` — SwiftUI owns the layout
+- **Prefer native SwiftUI** over AppKit interop when possible — only use `NSViewRepresentable` for features SwiftUI doesn't provide

package/skills/swiftui-expert-skill/references/macos-window-styling.md

@@ -0,0 +1,303 @@
+# macOS Window & Toolbar Styling Reference
+
+> Window configuration, toolbar styles, sizing, positioning, and navigation patterns specific to macOS SwiftUI apps.
+
+## Table of Contents
+
+- [Quick Lookup Table](#quick-lookup-table)
+- [Toolbar Styles](#toolbar-styles)
+- [Window Style](#window-style)
+- [Window Sizing](#window-sizing)
+- [MenuBarExtra Style (macOS-only)](#menubarextra-style-macos-only)
+- [Navigation Layout (macOS behavior)](#navigation-layout-macos-behavior)
+- [Commands & Keyboard](#commands--keyboard)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Lookup Table
+
+| API | Availability | macOS-Only? | Usage |
+|-----|-------------|:-----------:|-------|
+| `windowToolbarStyle(_:)` | macOS 11.0+ | Yes | Sets toolbar style: `.unified`, `.unifiedCompact`, `.expanded` |
+| `windowStyle(_:)` | macOS 11.0+ | No | Supports `.hiddenTitleBar` for chromeless windows |
+| `windowResizability(_:)` | macOS 13.0+ | No | Controls resize handle and green zoom button behavior |
+| `defaultSize(width:height:)` | macOS 13.0+ | No | Initial frame size when user creates a new window |
+| `defaultPosition(_:)` | macOS 13.0+ | No | Initial window position on screen |
+| `windowIdealPlacement(_:)` | macOS 15.0+ | No | Closure with display geometry for precise window positioning |
+| `menuBarExtraStyle(_:)` | macOS 13.0+ | Yes | Sets MenuBarExtra to `.menu` or `.window` style |
+| `NavigationSplitView` | macOS 13.0+ | No | Columns always visible side-by-side on macOS; translucent sidebar |
+| `Inspector` | macOS 14.0+ | No | Trailing-edge sidebar panel; resizable by dragging |
+
+---
+
+## Toolbar Styles
+
+### windowToolbarStyle (macOS-only)
+
+Controls how the toolbar and title bar are displayed. Applied to a scene.
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+        // Title bar and toolbar in a single row
+        .windowToolbarStyle(.unified)
+    }
+}
+```
+
+**Available styles:**
+
+| Style | Description |
+|-------|-------------|
+| `.automatic` | System default |
+| `.unified` | Title bar and toolbar in a single combined row |
+| `.unifiedCompact` | Same as unified but with reduced vertical height |
+| `.expanded` | Title bar displayed above the toolbar (more toolbar space) |
+
+```swift
+// Unified compact — minimal chrome
+.windowToolbarStyle(.unifiedCompact)
+
+// Expanded — title bar above toolbar
+.windowToolbarStyle(.expanded)
+
+// Unified with title hidden
+.windowToolbarStyle(.unified(showsTitle: false))
+```
+
+### Toolbar content
+
+```swift
+struct ContentView: View {
+    @State private var searchText = ""
+
+    var body: some View {
+        NavigationSplitView {
+            SidebarView()
+        } detail: {
+            DetailView()
+        }
+        .toolbar {
+            ToolbarItem(placement: .automatic) {
+                Button(action: addItem) {
+                    Label("Add", systemImage: "plus")
+                }
+            }
+        }
+        .searchable(text: $searchText, placement: .sidebar)
+    }
+}
+```
+
+---
+
+## Window Style
+
+### windowStyle
+
+Set the visual style of a window. Use `.hiddenTitleBar` for chromeless, immersive windows.
+
+```swift
+// Standard title bar (default)
+WindowGroup {
+    ContentView()
+}
+.windowStyle(.titleBar)
+
+// Hidden title bar — chromeless window
+WindowGroup {
+    ContentView()
+}
+.windowStyle(.hiddenTitleBar)
+```
+
+> **Use case:** `.hiddenTitleBar` is useful for media players, custom-chrome apps, or immersive experiences where the standard title bar is unwanted.
+
+---
+
+## Window Sizing
+
+### windowResizability, defaultSize, defaultPosition
+
+These modifiers work together to configure window sizing and placement:
+
+```swift
+WindowGroup {
+    ContentView()
+        .frame(minWidth: 600, minHeight: 400)
+}
+.defaultSize(width: 900, height: 600)
+.defaultPosition(.center)
+.windowResizability(.contentMinSize)
+```
+
+**`windowResizability` options:**
+
+| Value | Behavior |
+|-------|----------|
+| `.automatic` | System decides resize behavior |
+| `.contentSize` | Fixed to content size; no user resize; zoom button disabled |
+| `.contentMinSize` | Resizable with minimum based on content's `minWidth`/`minHeight` |
+
+**`defaultPosition` options:** `.center`, `.topLeading`, `.top`, `.topTrailing`, `.leading`, `.trailing`, `.bottomLeading`, `.bottom`, `.bottomTrailing`
+
+**Guidelines:**
+- Set `minWidth`/`minHeight` via `.frame()` on content, enforce with `.contentMinSize`
+- Use `.defaultSize()` for initial dimensions (larger than minimums)
+- `defaultSize` also accepts `CGSize`
+
+### windowIdealPlacement (macOS 15.0+)
+
+For precise programmatic positioning, use a closure with display geometry:
+
+```swift
+.windowIdealPlacement { context in
+    let screen = context.defaultDisplay.visibleArea
+    return WindowPlacement(x: screen.midX, y: screen.midY,
+                           width: screen.width / 2, height: screen.height)
+}
+```
+
+---
+
+## MenuBarExtra Style (macOS-only)
+
+Choose between dropdown menu and popover panel for `MenuBarExtra`.
+
+```swift
+// Dropdown menu (default)
+MenuBarExtra("Status", systemImage: "chart.bar") {
+    Button("Action") { /* ... */ }
+}
+.menuBarExtraStyle(.menu)
+
+// Popover panel with custom SwiftUI content
+MenuBarExtra("Status", systemImage: "chart.bar") {
+    DashboardView()
+}
+.menuBarExtraStyle(.window)
+```
+
+---
+
+## Navigation Layout (macOS behavior)
+
+### NavigationSplitView
+
+On macOS, `NavigationSplitView` displays columns side-by-side (never overlaid). The sidebar gets a translucent material background. Columns support variable-width resizing by the user.
+
+```swift
+NavigationSplitView {
+    List(items, selection: $selectedId) { item in
+        Text(item.name)
+    }
+    .navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 300)
+} detail: {
+    DetailView(id: selectedId)
+}
+.navigationSplitViewStyle(.balanced)
+```
+
+Use the three-column variant (`sidebar` / `content` / `detail`) for master-detail-detail layouts. Customize column widths with `.navigationSplitViewColumnWidth(min:ideal:max:)`.
+
+### Inspector (macOS 14.0+)
+
+A trailing-edge panel for supplementary information. On macOS, it appears as a sidebar-style panel that can be resized by dragging its edge.
+
+```swift
+struct ContentView: View {
+    @State private var showInspector = false
+
+    var body: some View {
+        MainContent()
+            .inspector(isPresented: $showInspector) {
+                InspectorView()
+                    .inspectorColumnWidth(min: 200, ideal: 250, max: 400)
+            }
+            .toolbar {
+                ToolbarItem {
+                    Button {
+                        showInspector.toggle()
+                    } label: {
+                        Label("Inspector", systemImage: "info.circle")
+                    }
+                }
+            }
+    }
+}
+```
+
+---
+
+## Commands & Keyboard
+
+### Commands, CommandGroup, CommandMenu
+
+Define menu bar commands. On macOS, these populate the menu bar directly. On iOS, they create key commands.
+
+```swift
+.commands {
+    CommandMenu("Tools") {
+        Button("Run Analysis") { /* ... */ }
+            .keyboardShortcut("r", modifiers: [.command, .shift])
+    }
+    CommandGroup(after: .newItem) {
+        Button("New From Template...") { /* ... */ }
+    }
+}
+```
+
+**`CommandGroup` placement options:** `.replacing(_:)` replaces a system group, `.before(_:)` / `.after(_:)` inserts adjacent to it. Common placements: `.newItem`, `.saveItem`, `.help`, `.toolbar`, `.sidebar`.
+
+### KeyboardShortcut
+
+On macOS, shortcuts are displayed alongside menu items and in button tooltips on hover.
+
+```swift
+Button("Save") {
+    save()
+}
+.keyboardShortcut("s", modifiers: .command)
+
+Button("Delete") {
+    delete()
+}
+.keyboardShortcut(.delete, modifiers: .command)
+```
+
+### openWindow
+
+Programmatically open a window. If the target window is already open, brings it to the front.
+
+```swift
+struct ToolbarActions: View {
+    @Environment(\.openWindow) private var openWindow
+
+    var body: some View {
+        Button("Connection Doctor") {
+            openWindow(id: "connection-doctor")
+        }
+
+        Button("Show Message") {
+            openWindow(value: message.id)  // Type-matched to WindowGroup
+        }
+    }
+}
+```
+
+---
+
+## Best Practices
+
+- **Use `.unified` or `.unifiedCompact`** for most apps — `.expanded` only when you need many toolbar items
+- **Set min frame sizes on content** and use `.windowResizability(.contentMinSize)` to enforce them
+- **Always provide `defaultSize`** so new windows start at a reasonable size
+- **Use `NavigationSplitView`** for sidebar navigation — not `HSplitView`
+- **Use `Inspector`** for supplementary panels — it integrates with the toolbar automatically
+- **Define `Commands`** for all repeatable actions — users expect keyboard shortcuts on macOS
+- **Use `#if os(macOS)`** to wrap macOS-only window configuration in multiplatform projects