swift-code-reviewer-skill 1.2.0 → 1.3.0

package/skills/swiftui-expert-skill/references/animation-transitions.md

@@ -0,0 +1,326 @@
+# SwiftUI Transitions
+
+Transitions for view insertion/removal, custom transitions, and the Animatable protocol.
+
+## Table of Contents
+- [Property Animations vs Transitions](#property-animations-vs-transitions)
+- [Basic Transitions](#basic-transitions)
+- [Asymmetric Transitions](#asymmetric-transitions)
+- [Custom Transitions](#custom-transitions)
+- [Identity and Transitions](#identity-and-transitions)
+- [The Animatable Protocol](#the-animatable-protocol)
+
+---
+
+## Property Animations vs Transitions
+
+**Property animations**: Interpolate values on views that exist before AND after state change.
+
+**Transitions**: Animate views being inserted or removed from the render tree.
+
+```swift
+// Property animation - same view, different properties
+Rectangle()
+    .frame(width: isExpanded ? 200 : 100, height: 50)
+    .animation(.spring, value: isExpanded)
+
+// Transition - view inserted/removed
+if showDetail {
+    DetailView()
+        .transition(.scale)
+}
+```
+
+---
+
+## Basic Transitions
+
+### Critical: Transitions Require Animation Context
+
+```swift
+// GOOD - animation outside conditional
+VStack {
+    Button("Toggle") { showDetail.toggle() }
+    if showDetail {
+        DetailView()
+            .transition(.slide)
+    }
+}
+.animation(.spring, value: showDetail)
+
+// GOOD - explicit animation
+Button("Toggle") {
+    withAnimation(.spring) {
+        showDetail.toggle()
+    }
+}
+if showDetail {
+    DetailView()
+        .transition(.scale.combined(with: .opacity))
+}
+
+// BAD - animation inside conditional (removed with view!)
+if showDetail {
+    DetailView()
+        .transition(.slide)
+        .animation(.spring, value: showDetail)  // Won't work on removal!
+}
+
+// BAD - no animation context
+Button("Toggle") {
+    showDetail.toggle()  // No animation
+}
+if showDetail {
+    DetailView()
+        .transition(.slide)  // Ignored - just appears/disappears
+}
+```
+
+### Built-in Transitions
+
+| Transition | Effect |
+|------------|--------|
+| `.opacity` | Fade in/out (default) |
+| `.scale` | Scale up/down |
+| `.slide` | Slide from leading edge |
+| `.move(edge:)` | Move from specific edge |
+| `.offset(x:y:)` | Move by offset amount |
+
+### Combining Transitions
+
+```swift
+// Parallel - both simultaneously
+.transition(.slide.combined(with: .opacity))
+
+// Chained
+.transition(.scale.combined(with: .opacity).combined(with: .offset(y: 20)))
+```
+
+---
+
+## Asymmetric Transitions
+
+Different animations for insertion vs removal.
+
+```swift
+// GOOD - different animations for insert/remove
+if showCard {
+    CardView()
+        .transition(
+            .asymmetric(
+                insertion: .scale.combined(with: .opacity),
+                removal: .move(edge: .bottom).combined(with: .opacity)
+            )
+        )
+}
+
+// BAD - same transition when different behaviors needed
+if showCard {
+    CardView()
+        .transition(.slide)  // Same both ways - may feel awkward
+}
+```
+
+---
+
+## Custom Transitions
+
+### Pre-iOS 17
+
+```swift
+struct BlurModifier: ViewModifier {
+    var radius: CGFloat
+    func body(content: Content) -> some View {
+        content.blur(radius: radius)
+    }
+}
+
+extension AnyTransition {
+    static func blur(radius: CGFloat) -> AnyTransition {
+        .modifier(
+            active: BlurModifier(radius: radius),
+            identity: BlurModifier(radius: 0)
+        )
+    }
+}
+
+// Usage
+.transition(.blur(radius: 10))
+```
+
+### iOS 17+ (Transition Protocol)
+
+```swift
+struct BlurTransition: Transition {
+    var radius: CGFloat
+
+    func body(content: Content, phase: TransitionPhase) -> some View {
+        content
+            .blur(radius: phase.isIdentity ? 0 : radius)
+            .opacity(phase.isIdentity ? 1 : 0)
+    }
+}
+
+// Usage
+.transition(BlurTransition(radius: 10))
+```
+
+### Good vs Bad Custom Transitions
+
+```swift
+// GOOD - reusable transition
+if showContent {
+    ContentView()
+        .transition(BlurTransition(radius: 10))
+}
+
+// BAD - inline logic (won't animate on removal!)
+if showContent {
+    ContentView()
+        .blur(radius: showContent ? 0 : 10)  // Not a transition
+        .opacity(showContent ? 1 : 0)
+}
+```
+
+---
+
+## Identity and Transitions
+
+View identity changes trigger transitions, not property animations.
+
+```swift
+// Triggers transition - different branches have different identities
+if isExpanded {
+    Rectangle().frame(width: 200, height: 50)
+} else {
+    Rectangle().frame(width: 100, height: 50)
+}
+
+// Triggers transition - .id() changes identity
+Rectangle()
+    .id(flag)  // Different identity when flag changes
+    .transition(.scale)
+
+// Property animation - same view, same identity
+Rectangle()
+    .frame(width: isExpanded ? 200 : 100, height: 50)
+    .animation(.spring, value: isExpanded)
+```
+
+---
+
+## The Animatable Protocol
+
+Enables custom property interpolation during animations.
+
+### Protocol Definition
+
+```swift
+protocol Animatable {
+    associatedtype AnimatableData: VectorArithmetic
+    var animatableData: AnimatableData { get set }
+}
+```
+
+### Basic Implementation
+
+```swift
+// GOOD - explicit animatableData
+struct ShakeModifier: ViewModifier, Animatable {
+    var shakeCount: Double
+
+    var animatableData: Double {
+        get { shakeCount }
+        set { shakeCount = newValue }
+    }
+
+    func body(content: Content) -> some View {
+        content.offset(x: sin(shakeCount * .pi * 2) * 10)
+    }
+}
+
+extension View {
+    func shake(count: Int) -> some View {
+        modifier(ShakeModifier(shakeCount: Double(count)))
+    }
+}
+
+// Usage
+Button("Shake") { shakeCount += 3 }
+    .shake(count: shakeCount)
+    .animation(.default, value: shakeCount)
+
+// BAD - missing animatableData (silent failure!)
+struct BadShakeModifier: ViewModifier {
+    var shakeCount: Double
+    // Missing animatableData! Uses EmptyAnimatableData
+
+    func body(content: Content) -> some View {
+        content.offset(x: sin(shakeCount * .pi * 2) * 10)
+    }
+}
+// Animation jumps to final value instead of interpolating
+```
+
+### Multiple Properties with AnimatablePair
+
+```swift
+// GOOD - AnimatablePair for two properties
+struct ComplexModifier: ViewModifier, Animatable {
+    var scale: CGFloat
+    var rotation: Double
+
+    var animatableData: AnimatablePair<CGFloat, Double> {
+        get { AnimatablePair(scale, rotation) }
+        set {
+            scale = newValue.first
+            rotation = newValue.second
+        }
+    }
+
+    func body(content: Content) -> some View {
+        content
+            .scaleEffect(scale)
+            .rotationEffect(.degrees(rotation))
+    }
+}
+
+// GOOD - nested AnimatablePair for 3+ properties
+struct ThreePropertyModifier: ViewModifier, Animatable {
+    var x: CGFloat
+    var y: CGFloat
+    var rotation: Double
+
+    var animatableData: AnimatablePair<AnimatablePair<CGFloat, CGFloat>, Double> {
+        get { AnimatablePair(AnimatablePair(x, y), rotation) }
+        set {
+            x = newValue.first.first
+            y = newValue.first.second
+            rotation = newValue.second
+        }
+    }
+
+    func body(content: Content) -> some View {
+        content
+            .offset(x: x, y: y)
+            .rotationEffect(.degrees(rotation))
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+### Do
+- Place transitions outside conditional structures
+- Use `withAnimation` or `.animation` outside the `if`
+- Implement `animatableData` explicitly for custom Animatable
+- Use `AnimatablePair` for multiple animated properties
+- Use asymmetric transitions when insert/remove need different effects
+
+### Don't
+- Put animation modifiers inside conditionals for transitions
+- Forget `animatableData` implementation (silent failure)
+- Use inline blur/opacity instead of proper transitions
+- Expect property animation when view identity changes

package/skills/swiftui-expert-skill/references/charts-accessibility.md

@@ -0,0 +1,135 @@
+# Swift Charts Accessibility, Fallback, and Resources
+
+## Table of Contents
+
+- [Accessibility](#accessibility)
+  - [Meaningful Labels](#meaningful-labels)
+  - [Custom Audio Graphs](#custom-audio-graphs)
+- [Composite Example](#composite-example)
+- [Fallback Strategies](#fallback-strategies)
+  - [Version Breakdown](#version-breakdown)
+- [WWDC Sessions](#wwdc-sessions)
+- [Summary Checklist](#summary-checklist)
+
+---
+
+## Accessibility
+
+Swift Charts provides built-in accessibility support. VoiceOver users get three rotor actions automatically:
+
+- **Describe Chart** — overview of axes and data series
+- **Audio Graph** — sonification where pitch represents data values
+- **Chart Detail** — interactive mode for exploring individual data points
+
+### Meaningful Labels
+
+**Always** use clear, descriptive strings in `.value(_, _)` calls. These labels are read by VoiceOver and used in the Audio Graph.
+
+```swift
+// Good — descriptive labels
+LineMark(
+    x: .value("Date", entry.date),
+    y: .value("Daily Steps", entry.count)
+)
+
+// Bad — generic labels
+LineMark(
+    x: .value("X", entry.date),
+    y: .value("Y", entry.count)
+)
+```
+
+### Custom Audio Graphs
+
+For advanced accessibility, conform your chart view to `AXChartDescriptorRepresentable` and implement `makeChartDescriptor()`. Attach it with `.accessibilityChartDescriptor(self)`.
+
+```swift
+struct StepsChart: View, AXChartDescriptorRepresentable {
+    let steps: [DailySteps]
+
+    var body: some View {
+        Chart(steps) { day in
+            LineMark(x: .value("Date", day.date), y: .value("Steps", day.count))
+        }
+        .accessibilityChartDescriptor(self)
+    }
+
+    func makeChartDescriptor() -> AXChartDescriptor {
+        guard let first = steps.first, let last = steps.last else {
+            return AXChartDescriptor(title: "Daily Step Count", summary: nil,
+                xAxis: AXNumericDataAxisDescriptor(title: "Date", range: 0...1, gridlinePositions: []) { "\($0)" },
+                yAxis: AXNumericDataAxisDescriptor(title: "Steps", range: 0...1, gridlinePositions: []) { "\($0)" },
+                additionalAxes: [], series: [])
+        }
+        let xAxis = AXDateDataAxisDescriptor(
+            title: "Date", range: first.date...last.date, gridlinePositions: [])
+        let yAxis = AXNumericDataAxisDescriptor(
+            title: "Steps", range: 0...Double(steps.map(\.count).max() ?? 0),
+            gridlinePositions: []) { "\(Int($0)) steps" }
+        let series = AXDataSeriesDescriptor(
+            name: "Daily Steps", isContinuous: true,
+            dataPoints: steps.map { .init(x: $0.date, y: Double($0.count)) })
+        return AXChartDescriptor(title: "Daily Step Count", summary: nil,
+            xAxis: xAxis, yAxis: yAxis, additionalAxes: [], series: [series])
+    }
+}
+```
+
+## Composite Example
+
+A scrollable bar chart with range selection combining multiple iOS 17+ APIs:
+
+```swift
+@State private var selectedRange: ClosedRange<Int>?
+
+Chart(weeklyRevenue) { week in
+    BarMark(x: .value("Week", week.index), y: .value("Revenue", week.revenue))
+        .foregroundStyle(by: .value("Region", week.region))
+}
+.chartScrollableAxes(.horizontal)
+.chartXVisibleDomain(length: 8)
+.chartXSelection(range: $selectedRange)
+.chartXAxis {
+    AxisMarks(values: .stride(by: 1)) {
+        AxisGridLine()
+        AxisValueLabel { Text("W\($0.as(Int.self) ?? 0)") }
+    }
+}
+```
+
+## Fallback Strategies
+
+Gate advanced APIs with `#available` and provide a fallback chart without the gated features. Because chart modifiers like `.chartXSelection` change the return type, you must duplicate the entire `Chart` — you cannot conditionally apply the modifier:
+
+### Version Breakdown
+
+- iOS 16+: `Chart`, custom axes, scales, `BarMark`, `LineMark`, `AreaMark`, `PointMark`, `RectangleMark`, `RuleMark`, `ChartProxy`, `chartOverlay`, `chartBackground`
+- iOS 17+: `SectorMark`, `chartXSelection`, `chartYSelection`, `chartAngleSelection`, `chartScrollableAxes`, visible-domain scrolling APIs, `chartGesture`
+- iOS 18+: `AreaPlot`, `BarPlot`, `LinePlot`, `PointPlot`, `RectanglePlot`, `RulePlot`, `SectorPlot`, function plotting
+- iOS 26+: `Chart3D`, `SurfacePlot`, Z-axis marks, 3D camera and pose APIs
+
+## WWDC Sessions
+
+- [Hello Swift Charts](https://developer.apple.com/videos/play/wwdc2022/10136/) (WWDC 2022) — introduction to the framework
+- [Swift Charts: Raise the bar](https://developer.apple.com/videos/play/wwdc2022/10137/) (WWDC 2022) — marks, composition, customization
+- [Design an effective chart](https://developer.apple.com/videos/play/wwdc2022/110340/) (WWDC 2022) — chart design principles
+- [Design app experiences with charts](https://developer.apple.com/videos/play/wwdc2022/110342/) (WWDC 2022) — integrating charts into app UX
+- [Explore pie charts and interactivity in Swift Charts](https://developer.apple.com/videos/play/wwdc2023/10037/) (WWDC 2023) — SectorMark, selection, scrolling
+- [Swift Charts: Vectorized and function plots](https://developer.apple.com/videos/play/wwdc2024/10155/) (WWDC 2024) — LinePlot, AreaPlot, function plotting
+- [Bring Swift Charts to the third dimension](https://developer.apple.com/videos/play/wwdc2025/313/) (WWDC 2025) — Chart3D, SurfacePlot, 3D marks
+
+## Summary Checklist
+
+- [ ] `import Charts` is present in files using chart types
+- [ ] Deployment target matches the APIs used (`Chart` on iOS 16+, selection and `SectorMark` on iOS 17+, plot types on iOS 18+, `Chart3D` on iOS 26+)
+- [ ] Chart data models use `Identifiable` (or `Chart(data, id:)` is provided)
+- [ ] All chart families are represented with the correct mark type
+- [ ] Axes use `AxisMarks` when default ticks are too dense or unclear
+- [ ] `chartXScale` or `chartYScale` is set when fixed domains matter
+- [ ] Chart-wide modifiers are applied to `Chart`, not individual marks
+- [ ] `foregroundStyle(by:)` used for categorical series (not manual per-mark colors)
+- [ ] Single-value selection uses `chartXSelection(value:)` or `chartYSelection(value:)`
+- [ ] Range selection uses `chartXSelection(range:)` or `chartYSelection(range:)`
+- [ ] `SectorMark` selection uses `chartAngleSelection(value:)`
+- [ ] iOS 17+, iOS 18+, and iOS 26+ APIs are guarded with `#available`
+- [ ] `.value()` labels are descriptive for VoiceOver and Audio Graph accessibility