swift-code-reviewer-skill 1.2.0 → 1.3.0

package/skills/swiftui-expert-skill/references/view-structure.md

@@ -0,0 +1,389 @@
+# SwiftUI View Structure Reference
+
+## Table of Contents
+
+- [View Structure Principles](#view-structure-principles)
+- [Prefer Modifiers Over Conditional Views](#prefer-modifiers-over-conditional-views)
+- [Extract Subviews, Not Computed Properties](#extract-subviews-not-computed-properties)
+- [When @ViewBuilder Functions Are Acceptable](#when-viewbuilder-functions-are-acceptable)
+- [When to Extract Subviews](#when-to-extract-subviews)
+- [Container View Pattern](#container-view-pattern)
+- [ZStack vs overlay/background](#zstack-vs-overlaybackground)
+- [Compositing Group Before Clipping](#compositing-group-before-clipping)
+- [Reusable Styling with ViewModifier](#reusable-styling-with-viewmodifier)
+- [Skeleton Loading with Redacted Views](#skeleton-loading-with-redacted-views)
+- [UIViewRepresentable Essentials](#uiviewrepresentable-essentials)
+- [Summary Checklist](#summary-checklist)
+
+## View Structure Principles
+
+SwiftUI's diffing algorithm compares view hierarchies to determine what needs updating. Proper view composition directly impacts performance.
+
+## Prefer Modifiers Over Conditional Views
+
+**Prefer "no-effect" modifiers over conditionally including views.** When you introduce a branch, consider whether you're representing multiple views or two states of the same view.
+
+### Use Opacity Instead of Conditional Inclusion
+
+```swift
+// Good - same view, different states
+SomeView()
+    .opacity(isVisible ? 1 : 0)
+
+// Avoid - creates/destroys view identity
+if isVisible {
+    SomeView()
+}
+```
+
+**Why**: Conditional view inclusion can cause loss of state, poor animation performance, and breaks view identity. Using modifiers maintains view identity across state changes.
+
+### When Conditionals Are Appropriate
+
+Use conditionals when you truly have **different views**, not different states:
+
+```swift
+// Correct - fundamentally different views
+if isLoggedIn {
+    DashboardView()
+} else {
+    LoginView()
+}
+
+// Correct - optional content
+if let user {
+    UserProfileView(user: user)
+}
+```
+
+### Conditional View Modifier Extensions Break Identity
+
+A common pattern is an `if`-based `View` extension for conditional modifiers. This changes the view's return type between branches, which destroys view identity and breaks animations:
+
+```swift
+// Problematic -- different return types per branch
+extension View {
+    @ViewBuilder func `if`<T: View>(_ condition: Bool, transform: (Self) -> T) -> some View {
+        if condition {
+            transform(self)  // Returns T
+        } else {
+            self              // Returns Self
+        }
+    }
+}
+```
+
+Prefer applying the modifier directly with a ternary or always-present modifier:
+
+```swift
+// Good -- same view identity maintained
+Text("Hello")
+    .opacity(isHighlighted ? 1 : 0.5)
+
+// Good -- modifier always present, value changes
+Text("Hello")
+    .foregroundStyle(isError ? .red : .primary)
+```
+
+## Extract Subviews, Not Computed Properties
+
+### The Problem with @ViewBuilder Functions
+
+When you use `@ViewBuilder` functions or computed properties for complex views, the entire function re-executes on every parent state change:
+
+```swift
+// BAD - re-executes complexSection() on every tap
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            complexSection()  // Re-executes every tap!
+        }
+    }
+
+    @ViewBuilder
+    func complexSection() -> some View {
+        // Complex views that re-execute unnecessarily
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### The Solution: Separate Structs
+
+Extract to separate `struct` views. SwiftUI can skip their `body` when inputs don't change:
+
+```swift
+// GOOD - ComplexSection body SKIPPED when its inputs don't change
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            ComplexSection()  // Body skipped during re-evaluation
+        }
+    }
+}
+
+struct ComplexSection: View {
+    var body: some View {
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### Why This Works
+
+1. SwiftUI compares the `ComplexSection` struct (which has no properties)
+2. Since nothing changed, SwiftUI skips calling `ComplexSection.body`
+3. The complex view code never executes unnecessarily
+
+## When @ViewBuilder Functions Are Acceptable
+
+Use for small, simple sections (a few views, no expensive computation) that don't affect performance. `@ViewBuilder` functions work particularly well for static content that doesn't depend on any `@State` or `@Binding`, since SwiftUI won't need to diff them independently. Extract to a separate `struct` when the section is complex, depends on state, or needs to be skipped during re-evaluation.
+
+## When to Extract Subviews
+
+Extract complex views into separate subviews when:
+- The view has multiple logical sections or responsibilities
+- The view contains reusable components
+- The view body becomes difficult to read or understand
+- You need to isolate state changes for performance
+- The view is becoming large (keep views small for better performance)
+
+## Container View Pattern
+
+### Avoid Closure-Based Content
+
+Closures can't be compared, causing unnecessary re-renders:
+
+```swift
+// BAD - closure prevents SwiftUI from skipping updates
+struct MyContainer<Content: View>: View {
+    let content: () -> Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content()  // Always called, can't compare closures
+        }
+    }
+}
+
+// Usage forces re-render on every parent update
+MyContainer {
+    ExpensiveView()
+}
+```
+
+### Use @ViewBuilder Property Instead
+
+```swift
+// GOOD - view can be compared
+struct MyContainer<Content: View>: View {
+    @ViewBuilder let content: Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content  // SwiftUI can compare and skip if unchanged
+        }
+    }
+}
+
+// Usage - SwiftUI can diff ExpensiveView
+MyContainer {
+    ExpensiveView()
+}
+```
+
+## ZStack vs overlay/background
+
+Use `ZStack` to **compose multiple peer views** that should be layered together and jointly define layout.
+
+Prefer `overlay` / `background` when you’re **decorating a primary view**.  
+Not primarily because they don’t affect layout size, but because they **express intent and improve readability**: the view being modified remains the clear layout anchor.
+
+A key difference is **size proposal behavior**:
+- In `overlay` / `background`, the child view implicitly adopts the size proposed to the parent when it doesn’t define its own size, making decorative attachments feel natural and predictable.
+- In `ZStack`, each child participates independently in layout, and no implicit size inheritance exists. This makes it better suited for peer composition, but less intuitive for simple decoration.
+
+Use `ZStack` (or another container) when the “decoration” **must explicitly participate in layout sizing**—for example, when reserving space, extending tappable/visible bounds, or preventing overlap with neighboring views.
+
+### Examples
+
+```swift
+// GOOD - decoration via overlay (layout anchored to button)
+Button("Continue") { }
+    .overlay(alignment: .trailing) {
+        Image(systemName: "lock.fill").padding(.trailing, 8)
+    }
+
+// BAD - ZStack when overlay suffices (layout no longer anchored to button)
+ZStack(alignment: .trailing) {
+    Button("Continue") { }
+    Image(systemName: "lock.fill").padding(.trailing, 8)
+}
+
+// GOOD - background shape takes parent size
+HStack(spacing: 12) { Text("Inbox"); Text("Next") }
+    .background { Capsule().strokeBorder(.blue, lineWidth: 2) }
+```
+
+## Compositing Group Before Clipping
+
+**Always add `.compositingGroup()` before `.clipShape()` when clipping layered views (`.overlay` or `.background`).** Without it, each layer is antialiased separately and then composited. Where antialiased edges overlap — typically at rounded corners — you get visible color fringes (semi-transparent pixels of different colors blending together).
+
+```swift
+let shape = RoundedRectangle(cornerRadius: 16)
+
+// BAD - each layer antialiased separately, producing color fringes at corners
+Color.red
+    .overlay(.white, in: shape)
+    .clipShape(shape)
+    .frame(width: 200, height: 150)
+
+// GOOD - layers composited first, antialiasing applied once during clipping
+Color.red
+    .overlay(.white, in: .rect)
+    .compositingGroup()
+    .clipShape(shape)
+    .frame(width: 200, height: 150)
+```
+
+`.compositingGroup()` forces all child layers to be rendered into a single offscreen buffer before the clip is applied. This means antialiasing only happens once — on the final composited result — eliminating the fringe artifacts.
+
+## Reusable Styling with ViewModifier
+
+Extract repeated modifier combinations into a `ViewModifier` struct. Expose via a `View` extension for autocompletion:
+
+```swift
+private struct CardStyle: ViewModifier {
+    func body(content: Content) -> some View {
+        content
+            .padding()
+            .background(Color(.secondarySystemBackground))
+            .clipShape(.rect(cornerRadius: 12))
+    }
+}
+
+extension View {
+    func cardStyle() -> some View {
+        modifier(CardStyle())
+    }
+}
+```
+
+### Custom ButtonStyle
+
+Use the `ButtonStyle` protocol for reusable button designs. Use `PrimitiveButtonStyle` only when you need custom interaction handling (e.g., simultaneous gestures):
+
+```swift
+struct PrimaryButtonStyle: ButtonStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .bold()
+            .foregroundStyle(.white)
+            .padding(.horizontal, 16)
+            .padding(.vertical, 8)
+            .background(Color.accentColor)
+            .clipShape(Capsule())
+            .scaleEffect(configuration.isPressed ? 0.95 : 1)
+            .animation(.smooth, value: configuration.isPressed)
+    }
+}
+```
+
+### Discoverability with Static Member Lookup
+
+Make custom styles and modifiers discoverable via leading-dot syntax:
+
+```swift
+extension ButtonStyle where Self == PrimaryButtonStyle {
+    static var primary: PrimaryButtonStyle { .init() }
+}
+
+// Usage: .buttonStyle(.primary)
+```
+
+This pattern works for any SwiftUI style protocol (`ButtonStyle`, `ListStyle`, `ToggleStyle`, etc.).
+
+## Skeleton Loading with Redacted Views
+
+Use `.redacted(reason: .placeholder)` to show skeleton views while data loads. Use `.unredacted()` to opt out specific views:
+
+```swift
+VStack(alignment: .leading) {
+    Text(article?.title ?? String(repeating: "X", count: 20))
+        .font(.headline)
+    Text(article?.author ?? String(repeating: "X", count: 12))
+        .font(.subheadline)
+    Text("SwiftLee")
+        .font(.caption)
+        .unredacted()
+}
+.redacted(reason: article == nil ? .placeholder : [])
+```
+
+Apply `.redacted` on a container to redact all children at once.
+
+## UIViewRepresentable Essentials
+
+When bridging UIKit views into SwiftUI:
+
+- `makeUIView(context:)` is called **once** to create the UIKit view
+- `updateUIView(_:context:)` is called on **every SwiftUI redraw** to sync state
+- The representable struct itself is **recreated on every redraw** -- avoid heavy work in its init
+- Use a `Coordinator` for delegate callbacks and two-way communication
+
+```swift
+struct MapView: UIViewRepresentable {
+    let coordinate: CLLocationCoordinate2D
+
+    func makeUIView(context: Context) -> MKMapView {
+        let map = MKMapView()
+        map.delegate = context.coordinator
+        return map
+    }
+
+    func updateUIView(_ map: MKMapView, context: Context) {
+        map.setCenter(coordinate, animated: true)
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
+
+    class Coordinator: NSObject, MKMapViewDelegate { }
+}
+```
+
+## Summary Checklist
+
+- [ ] Prefer modifiers over conditional views for state changes
+- [ ] Avoid `if`-based conditional modifier extensions (they break view identity)
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for better performance
+- [ ] `@ViewBuilder` functions only for simple sections
+- [ ] Container views use `@ViewBuilder let content: Content`
+- [ ] Extract views when they have multiple responsibilities or become hard to read
+- [ ] Reusable styling extracted into `ViewModifier` or `ButtonStyle`
+- [ ] Custom styles exposed via static member lookup for discoverability
+- [ ] Use `.redacted(reason: .placeholder)` for skeleton loading states
+- [ ] `.compositingGroup()` before `.clipShape()` on layered views (overlay/background) to avoid antialiasing fringes
+- [ ] UIViewRepresentable: heavy work in make/update, not in struct init

package/skills/swiftui-ui-patterns/NOTICE.md

@@ -0,0 +1,18 @@
+# swiftui-ui-patterns — Attribution Notice
+
+Bundled into `swift-code-reviewer-skill` on 2026-04-21 from
+`~/.maestro/skills/swiftui-ui-patterns`.
+
+Primary author (best-effort attribution): **Thomas Ricouard ([@Dimillian](https://github.com/Dimillian))**
+Also credited: [@AvdLee](https://github.com/AvdLee), [@bocato](https://github.com/bocato)
+
+These three authors' public Swift/SwiftUI content — including IceCubesApp, SwiftLee,
+and their various open-source contributions — informed the skills bundled here.
+
+License: the upstream folder did not contain a LICENSE file at the time of vendoring.
+Content is reproduced here in good faith for reference alongside this MIT-licensed
+project. If you are an upstream author and want the attribution corrected, the license
+clarified, or the content removed, please open an issue at:
+https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues
+
+Changes from upstream: none (verbatim copy; `.DS_Store` files excluded).

package/skills/swiftui-ui-patterns/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: swiftui-ui-patterns
+description: Best practices and example-driven guidance for building SwiftUI views and components, including navigation hierarchies, custom view modifiers, and responsive layouts with stacks and grids. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens with VStack/HStack, managing @State or @Binding, building declarative iOS interfaces, or needing component-specific patterns and examples.
+---
+
+# SwiftUI UI Patterns
+
+## Quick start
+
+Choose a track based on your goal:
+
+### Existing project
+
+- Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
+- Find a nearby example in the repo with `rg "TabView\("` or similar, then read the closest SwiftUI view.
+- Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
+- Choose the relevant component reference from `references/components-index.md` and follow its guidance.
+- If the interaction reveals secondary content by dragging or scrolling the primary content away, read `references/scroll-reveal.md` before implementing gestures manually.
+- Build the view with small, focused subviews and SwiftUI-native data flow.
+
+### New project scaffolding
+
+- Start with `references/app-wiring.md` to wire TabView + NavigationStack + sheets.
+- Add a minimal `AppTab` and `RouterPath` based on the provided skeletons.
+- Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
+- Expand the route and sheet enums as new screens are added.
+
+## General rules to follow
+
+- Use modern SwiftUI state (`@State`, `@Binding`, `@Observable`, `@Environment`) and avoid unnecessary view models.
+- If the deployment target includes iOS 16 or earlier and cannot use the Observation API introduced in iOS 17, fall back to `ObservableObject` with `@StateObject` for root ownership, `@ObservedObject` for injected observation, and `@EnvironmentObject` only for truly shared app-level state.
+- Prefer composition; keep views small and focused.
+- Use async/await with `.task` and explicit loading/error states. For restart, cancellation, and debouncing guidance, read `references/async-state.md`.
+- Keep shared app services in `@Environment`, but prefer explicit initializer injection for feature-local dependencies and models. For root wiring patterns, read `references/app-wiring.md`.
+- Prefer the newest SwiftUI API that fits the deployment target and call out the minimum OS whenever a pattern depends on it.
+- Maintain existing legacy patterns only when editing legacy files.
+- Follow the project's formatter and style guide.
+- **Sheets**: Prefer `.sheet(item:)` over `.sheet(isPresented:)` when state represents a selected model. Avoid `if let` inside a sheet body. Sheets should own their actions and call `dismiss()` internally instead of forwarding `onCancel`/`onConfirm` closures.
+- **Scroll-driven reveals**: Prefer deriving a normalized progress value from scroll offset and driving the visual state from that single source of truth. Avoid parallel gesture state machines unless scroll alone cannot express the interaction.
+
+## State ownership summary
+
+Use the narrowest state tool that matches the ownership model:
+
+| Scenario | Preferred pattern |
+| --- | --- |
+| Local UI state owned by one view | `@State` |
+| Child mutates parent-owned value state | `@Binding` |
+| Root-owned reference model on iOS 17+ | `@State` with an `@Observable` type |
+| Child reads or mutates an injected `@Observable` model on iOS 17+ | Pass it explicitly as a stored property |
+| Shared app service or configuration | `@Environment(Type.self)` |
+| Legacy reference model on iOS 16 and earlier | `@StateObject` at the root, `@ObservedObject` when injected |
+
+Choose the ownership location first, then pick the wrapper. Do not introduce a reference model when plain value state is enough.
+
+## Cross-cutting references
+
+- `references/navigationstack.md`: navigation ownership, per-tab history, and enum routing.
+- `references/sheets.md`: centralized modal presentation and enum-driven sheets.
+- `references/deeplinks.md`: URL handling and routing external links into app destinations.
+- `references/app-wiring.md`: root dependency graph, environment usage, and app shell wiring.
+- `references/async-state.md`: `.task`, `.task(id:)`, cancellation, debouncing, and async UI state.
+- `references/previews.md`: `#Preview`, fixtures, mock environments, and isolated preview setup.
+- `references/performance.md`: stable identity, observation scope, lazy containers, and render-cost guardrails.
+
+## Anti-patterns
+
+- Giant views that mix layout, business logic, networking, routing, and formatting in one file.
+- Multiple boolean flags for mutually exclusive sheets, alerts, or navigation destinations.
+- Live service calls directly inside `body`-driven code paths instead of view lifecycle hooks or injected models/services.
+- Reaching for `AnyView` to work around type mismatches that should be solved with better composition.
+- Defaulting every shared dependency to `@EnvironmentObject` or a global router without a clear ownership reason.
+
+## Workflow for a new SwiftUI view
+
+1. Define the view's state, ownership location, and minimum OS assumptions before writing UI code.
+2. Identify which dependencies belong in `@Environment` and which should stay as explicit initializer inputs.
+3. Sketch the view hierarchy, routing model, and presentation points; extract repeated parts into subviews. For complex navigation, read `references/navigationstack.md`, `references/sheets.md`, or `references/deeplinks.md`. **Build and verify no compiler errors before proceeding.**
+4. Implement async loading with `.task` or `.task(id:)`, plus explicit loading and error states when needed. Read `references/async-state.md` when the work depends on changing inputs or cancellation.
+5. Add previews for the primary and secondary states, then add accessibility labels or identifiers when the UI is interactive. Read `references/previews.md` when the view needs fixtures or injected mock dependencies.
+6. Validate with a build: confirm no compiler errors, check that previews render without crashing, ensure state changes propagate correctly, and sanity-check that list identity and observation scope will not cause avoidable re-renders. Read `references/performance.md` if the screen is large, scroll-heavy, or frequently updated. For common SwiftUI compilation errors — missing `@State` annotations, ambiguous `ViewBuilder` closures, or mismatched generic types — resolve them before updating callsites. **If the build fails:** read the error message carefully, fix the identified issue, then rebuild before proceeding to the next step. If a preview crashes, isolate the offending subview, confirm its state initialisation is valid, and re-run the preview before continuing.
+
+## Component references
+
+Use `references/components-index.md` as the entry point. Each component reference should include:
+- Intent and best-fit scenarios.
+- Minimal usage pattern with local conventions.
+- Pitfalls and performance notes.
+- Paths to existing examples in the current repo.
+
+## Adding a new component reference
+
+- Create `references/<component>.md`.
+- Keep it short and actionable; link to concrete files in the current repo.
+- Update `references/components-index.md` with the new entry.