@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-gestures/references/gesture-patterns.md

@@ -1,435 +1,353 @@
-# Gesture Patterns  -  Advanced Reference
+# Gesture Patterns
 
-Extended patterns for SwiftUI gesture handling. See the main `SKILL.md` for
-core APIs and common mistakes.
+Worked interactions for the `swiftui-gestures` skill. The SKILL.md explains the
+gesture types, composition and `@GestureState`; this file assumes that
+material.
 
 ## Contents
 
-- [Pinch-to-Zoom with MagnifyGesture](#pinch-to-zoom-with-magnifygesture)
-- [Combined Rotate + Scale](#combined-rotate--scale)
-- [Drag-to-Reorder](#drag-to-reorder)
-- [Gesture Velocity Calculations](#gesture-velocity-calculations)
-- [Long-Press then Drag](#long-press-then-drag-sequenced-gesture-with-state-enum)
-- [SwiftUI + UIKit Gesture Interop](#swiftui--uikit-gesture-interop)
-- [Accessibility Considerations](#accessibility-considerations)
+- [Pinch-to-zoom with MagnifyGesture](#pinch-to-zoom-with-magnifygesture)
+- [Combined rotate and scale](#combined-rotate-and-scale)
+- [Drag-to-reorder](#drag-to-reorder)
+- [Gesture velocity calculations](#gesture-velocity-calculations)
+- [Long-press then drag](#long-press-then-drag)
+- [SwiftUI and UIKit gesture interop](#swiftui-and-uikit-gesture-interop)
+- [Accessibility considerations](#accessibility-considerations)
 
-## Pinch-to-Zoom with MagnifyGesture
+## Pinch-to-zoom with MagnifyGesture
 
-Full implementation with clamped scale, double-tap reset, and smooth animation:
+A zoomable image that can also be panned once it is enlarged, and double-tapped
+back to its original size.
 
 ```swift
-struct PinchToZoomView: View {
-    @State private var currentScale = 1.0
-    @State private var currentOffset = CGSize.zero
-    @GestureState private var gestureScale = 1.0
-    @GestureState private var dragOffset = CGSize.zero
+struct ZoomableImage: View {
+    let image: Image
 
-    private let minScale = 0.5
-    private let maxScale = 5.0
+    private let smallestZoom: CGFloat = 0.5
+    private let largestZoom: CGFloat = 5.0
+
+    @State private var zoom: CGFloat = 1
+    @State private var pan = CGSize.zero
+    @GestureState private var livePinch: CGFloat = 1
+    @GestureState private var livePan = CGSize.zero
 
     var body: some View {
-        Image("photo")
+        image
             .resizable()
             .scaledToFit()
-            .scaleEffect(currentScale * gestureScale)
-            .offset(
-                x: currentOffset.width + dragOffset.width,
-                y: currentOffset.height + dragOffset.height
-            )
-            .gesture(magnifyGesture)
-            .simultaneousGesture(panGesture)
+            .scaleEffect(zoom * livePinch)
+            .offset(x: pan.width + livePan.width, y: pan.height + livePan.height)
+            .gesture(pinch)
+            .simultaneousGesture(drag)
             .onTapGesture(count: 2) {
                 withAnimation(.spring) {
-                    currentScale = 1.0
-                    currentOffset = .zero
+                    zoom = 1
+                    pan = .zero
                 }
             }
     }
 
-    private var magnifyGesture: some Gesture {
+    private var pinch: some Gesture {
         MagnifyGesture()
-            .updating($gestureScale) { value, state, _ in
-                state = value.magnification
-            }
-            .onEnded { value in
-                let newScale = currentScale * value.magnification
+            .updating($livePinch) { current, live, _ in live = current.magnification }
+            .onEnded { final in
+                let proposed = zoom * final.magnification
                 withAnimation(.spring) {
-                    currentScale = min(max(newScale, minScale), maxScale)
+                    zoom = min(max(proposed, smallestZoom), largestZoom)
                 }
             }
     }
 
-    private var panGesture: some Gesture {
+    private var drag: some Gesture {
         DragGesture()
-            .updating($dragOffset) { value, state, _ in
-                guard currentScale > 1.0 else { return }
-                state = value.translation
+            .updating($livePan) { current, live, _ in
+                if zoom > 1 { live = current.translation }
             }
-            .onEnded { value in
-                guard currentScale > 1.0 else { return }
-                currentOffset.width += value.translation.width
-                currentOffset.height += value.translation.height
+            .onEnded { final in
+                guard zoom > 1 else { return }
+                pan.width += final.translation.width
+                pan.height += final.translation.height
             }
     }
 }
 ```
 
-## Combined Rotate + Scale
+Panning only applies while `zoom` is above 1, so at normal size a drag does
+nothing and the image cannot wander off screen. The double tap uses
+`onTapGesture(count:)`, which is the legitimate use of that modifier.
 
-Simultaneous rotation and magnification for image editing:
+## Combined rotate and scale
 
 ```swift
-struct RotateScaleView: View {
-    @State private var currentAngle = Angle.zero
-    @State private var currentScale = 1.0
-    @GestureState private var gestureAngle = Angle.zero
-    @GestureState private var gestureScale = 1.0
+struct TurnAndScaleSticker: View {
+    @State private var angle: Angle = .zero
+    @State private var size: CGFloat = 1
+    @GestureState private var liveAngle = Angle.zero
+    @GestureState private var liveSize: CGFloat = 1
 
     var body: some View {
-        Image("sticker")
-            .resizable()
-            .scaledToFit()
-            .frame(width: 200, height: 200)
-            .rotationEffect(currentAngle + gestureAngle)
-            .scaleEffect(currentScale * gestureScale)
-            .gesture(
-                RotateGesture()
-                    .updating($gestureAngle) { value, state, _ in
-                        state = value.rotation
-                    }
-                    .onEnded { value in
-                        currentAngle += value.rotation
-                    }
-                    .simultaneously(with:
-                        MagnifyGesture()
-                            .updating($gestureScale) { value, state, _ in
-                                state = value.magnification
-                            }
-                            .onEnded { value in
-                                currentScale *= value.magnification
-                                currentScale = min(max(currentScale, 0.3), 5.0)
-                            }
-                    )
-            )
+        let sticker = Image(systemName: "star.fill")
+        return sticker
+            .font(.system(size: 80))
+            .rotationEffect(angle + liveAngle)
+            .scaleEffect(size * liveSize)
+            .gesture(twist.simultaneously(with: stretch))
+    }
+
+    private var twist: some Gesture {
+        RotateGesture()
+            .updating($liveAngle) { current, live, _ in live = current.rotation }
+            .onEnded { final in angle += final.rotation }
+    }
+
+    private var stretch: some Gesture {
+        MagnifyGesture()
+            .updating($liveSize) { current, live, _ in live = current.magnification }
+            .onEnded { final in size = min(max(size * final.magnification, 0.3), 5.0) }
     }
 }
 ```
 
-## Drag-to-Reorder
+## Drag-to-reorder
 
-Drag gesture with haptic feedback for list reordering:
+A short press lifts a row; dragging then moves it. The press and the drag are
+sequenced so a normal scroll does not start a reorder.
 
 ```swift
-struct ReorderableList: View {
-    @State private var items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
-    @State private var draggingItem: String?
-    @State private var dragOffset = CGSize.zero
+struct ReorderableStack: View {
+    @State private var stops = ["Depot", "Market", "School", "Clinic", "Harbour"]
+    @State private var lifted: String?
+    @State private var lift = CGFloat.zero
+
+    private let rowPitch: CGFloat = 50
 
     var body: some View {
-        VStack {
-            ForEach(items, id: \.self) { item in
-                ItemRow(title: item, isDragging: draggingItem == item)
-                    .offset(y: draggingItem == item ? dragOffset.height : 0)
-                    .zIndex(draggingItem == item ? 1 : 0)
-                    .gesture(
-                        LongPressGesture(minimumDuration: 0.3)
-                            .sequenced(before: DragGesture())
-                            .onChanged { value in
-                                switch value {
-                                case .first(true):
-                                    withAnimation(.spring) {
-                                        draggingItem = item
-                                    }
-                                case .second(true, let drag):
-                                    dragOffset = drag?.translation ?? .zero
-                                    updateOrder(for: item, translation: dragOffset.height)
-                                default:
-                                    break
-                                }
-                            }
-                            .onEnded { _ in
-                                withAnimation(.spring) {
-                                    draggingItem = nil
-                                    dragOffset = .zero
-                                }
-                            }
-                    )
+        VStack(alignment: .center, spacing: 0) {
+            ForEach(stops, id: \.self) { stop in
+                Text(stop)
+                    .frame(maxWidth: .infinity, minHeight: rowPitch)
+                    .background(lifted == stop ? Color.accentColor.opacity(0.2) : Color.clear)
+                    .shadow(radius: lifted == stop ? 6 : 0)
+                    .scaleEffect(lifted == stop ? 1.05 : 1)
+                    .offset(y: lifted == stop ? lift : 0)
+                    .zIndex(lifted == stop ? 1 : 0)
+                    .gesture(reorder(stop))
             }
         }
     }
 
-    private func updateOrder(for item: String, translation: CGFloat) {
-        guard let sourceIndex = items.firstIndex(of: item) else { return }
-        let rowHeight: CGFloat = 50
-        let offset = Int(translation / rowHeight)
-        let destinationIndex = min(max(sourceIndex + offset, 0), items.count - 1)
-        if sourceIndex != destinationIndex {
-            withAnimation(.spring) {
-                items.move(
-                    fromOffsets: IndexSet(integer: sourceIndex),
-                    toOffset: destinationIndex > sourceIndex
-                        ? destinationIndex + 1 : destinationIndex
-                )
+    private func reorder(_ stop: String) -> some Gesture {
+        let liftThenSlide = LongPressGesture(minimumDuration: 0.35).sequenced(before: DragGesture())
+        return liftThenSlide
+            .onChanged { phase in
+                switch phase {
+                case .first(true):
+                    withAnimation(.spring) { lifted = stop }
+                case .second(true, let drag?):
+                    lift = drag.translation.height
+                default:
+                    return
+                }
+            }
+            .onEnded { _ in
+                commitMove(of: stop)
+                withAnimation(.spring) {
+                    lifted = nil
+                    lift = 0
+                }
             }
-        }
     }
-}
-
-struct ItemRow: View {
-    let title: String
-    let isDragging: Bool
 
-    var body: some View {
-        Text(title)
-            .frame(maxWidth: .infinity, minHeight: 46)
-            .background(isDragging ? Color.blue.opacity(0.2) : Color(.secondarySystemBackground))
-            .clipShape(.rect(cornerRadius: 8))
-            .shadow(radius: isDragging ? 4 : 0)
-            .scaleEffect(isDragging ? 1.05 : 1.0)
+    private func commitMove(of stop: String) {
+        guard let from = stops.firstIndex(of: stop) else { return }
+        let steps = Int((lift / rowPitch).rounded())
+        let to = min(max(from + steps, 0), stops.count - 1)
+        guard to != from else { return }
+        stops.move(fromOffsets: IndexSet(integer: from), toOffset: to > from ? to + 1 : to)
     }
 }
 ```
 
-## Gesture Velocity Calculations
+`move(fromOffsets:toOffset:)` inserts before the destination offset, which is
+why a downward move adds one.
+
+## Gesture velocity calculations
 
-Use `DragGesture.Value.velocity` (iOS 17+) or compute from
-`predictedEndTranslation` for flick gestures:
+`DragGesture.Value.velocity` (iOS 17 and later) reports points per second as a
+`CGSize`. A sheet-like panel that dismisses on a long drag or a fast flick:
 
 ```swift
-struct FlickDismissView: View {
-    @State private var offset = CGSize.zero
-    @State private var isDismissed = false
+struct FlickToClosePanel: View {
+    @Binding var isShown: Bool
+    @State private var pull: CGFloat = 0
 
-    private let dismissThreshold: CGFloat = 200
-    private let velocityThreshold: CGFloat = 800
+    private let closeDistance: CGFloat = 200
+    private let closeSpeed: CGFloat = 800
 
     var body: some View {
-        if !isDismissed {
-            CardView()
-                .offset(y: offset.height)
-                .opacity(opacity)
-                .gesture(
-                    DragGesture()
-                        .onChanged { value in
-                            if value.translation.height > 0 {
-                                offset = value.translation
-                            }
-                        }
-                        .onEnded { value in
-                            let velocity = value.velocity.height
-                            let distance = value.translation.height
-
-                            if distance > dismissThreshold
-                                || velocity > velocityThreshold
-                            {
-                                withAnimation(.spring) {
-                                    isDismissed = true
-                                }
-                            } else {
-                                withAnimation(.spring) {
-                                    offset = .zero
-                                }
-                            }
+        let panel = RoundedRectangle(cornerRadius: 24)
+        return panel
+            .fill(.background)
+            .frame(height: 360)
+            .offset(y: pull)
+            .opacity(1 - min(pull / closeDistance, 1) * 0.5)
+            .gesture(
+                DragGesture()
+                    .onChanged { drag in pull = max(drag.translation.height, 0) }
+                    .onEnded { drag in
+                        if pull > closeDistance || drag.velocity.height > closeSpeed {
+                            isShown = false
+                        } else {
+                            withAnimation(.spring) { pull = 0 }
                         }
-                )
-        }
-    }
-
-    private var opacity: Double {
-        let progress = min(offset.height / dismissThreshold, 1.0)
-        return 1.0 - (progress * 0.5)
+                    }
+            )
     }
 }
 ```
 
-Velocity from predicted end translation (pre-iOS 17 fallback):
+Only downward movement counts; upward drags clamp to 0. The panel fades toward
+half opacity as it approaches the threshold.
+
+Before iOS 17 there is no `velocity`. Estimate momentum from how far the
+system predicts the drag would coast:
 
 ```swift
-DragGesture()
-    .onEnded { value in
-        // Approximate velocity from predicted vs actual
-        let predictedDelta = CGSize(
-            width: value.predictedEndTranslation.width - value.translation.width,
-            height: value.predictedEndTranslation.height - value.translation.height
-        )
-        let speed = sqrt(
-            predictedDelta.width * predictedDelta.width
-            + predictedDelta.height * predictedDelta.height
-        )
-        if speed > 500 { handleFlick() }
-    }
+let coastX = drag.predictedEndTranslation.width - drag.translation.width
+let coastY = drag.predictedEndTranslation.height - drag.translation.height
+let momentum = (coastX * coastX + coastY * coastY).squareRoot()
+let isFlick = momentum > 500
 ```
 
-## Long-Press then Drag (Sequenced Gesture with State Enum)
+## Long-press then drag
 
-Model complex gesture states with an enum for clarity:
+Model the combined gesture as an explicit state machine held in `@GestureState`.
 
 ```swift
-enum DragState {
-    case inactive
-    case pressing
-    case dragging(translation: CGSize)
-
-    var translation: CGSize {
-        switch self {
-        case .inactive, .pressing: return .zero
-        case .dragging(let t): return t
-        }
+enum PressDrag {
+    case idle
+    case armed
+    case moving(CGSize)
+
+    var offset: CGSize {
+        if case .moving(let amount) = self { return amount }
+        return .zero
     }
 
-    var isActive: Bool {
-        switch self {
-        case .inactive: return false
-        case .pressing, .dragging: return true
-        }
+    var engaged: Bool {
+        if case .idle = self { return false }
+        return true
     }
 }
 
-struct LongPressDragView: View {
-    @GestureState private var dragState = DragState.inactive
-    @State private var position = CGSize.zero
+struct PressThenDragChip: View {
+    @GestureState private var phase = PressDrag.idle
+    @State private var spot = CGPoint(x: 150, y: 150)
 
     var body: some View {
-        Circle()
-            .fill(dragState.isActive ? .red : .blue)
-            .frame(width: 80, height: 80)
-            .shadow(radius: dragState.isActive ? 8 : 0)
-            .offset(
-                x: position.width + dragState.translation.width,
-                y: position.height + dragState.translation.height
-            )
-            .animation(.spring, value: dragState.isActive)
+        let chip = Circle()
+        return chip
+            .fill(phase.engaged ? .orange : .blue)
+            .frame(width: 70, height: 70)
+            .scaleEffect(phase.engaged ? 1.2 : 1)
+            .position(x: spot.x + phase.offset.width, y: spot.y + phase.offset.height)
+            .animation(.spring, value: phase.engaged)
             .gesture(
-                LongPressGesture(minimumDuration: 0.5)
+                LongPressGesture(minimumDuration: 0.6)
                     .sequenced(before: DragGesture())
-                    .updating($dragState) { value, state, _ in
-                        switch value {
-                        case .first(true):
-                            state = .pressing
-                        case .second(true, let drag):
-                            state = .dragging(
-                                translation: drag?.translation ?? .zero
-                            )
-                        default:
-                            state = .inactive
+                    .updating($phase) { step, machine, _ in
+                        if case .second(true, let drag) = step {
+                            machine = .moving(drag?.translation ?? .zero)
+                        } else if case .first(true) = step {
+                            machine = .armed
+                        } else {
+                            machine = .idle
                         }
                     }
-                    .onEnded { value in
-                        guard case .second(true, let drag?) = value else {
-                            return
-                        }
-                        position.width += drag.translation.width
-                        position.height += drag.translation.height
+                    .onEnded { outcome in
+                        guard case .second(true, let drag?) = outcome else { return }
+                        spot.x += drag.translation.width
+                        spot.y += drag.translation.height
                     }
             )
     }
 }
 ```
 
-## SwiftUI + UIKit Gesture Interop
+## SwiftUI and UIKit gesture interop
 
-### UIGestureRecognizerRepresentable (iOS 18+)
+### A UIKit recognizer inside SwiftUI (iOS 18+)
 
-Bridge UIKit gesture recognizers into SwiftUI:
+`UIGestureRecognizerRepresentable` brings any `UIGestureRecognizer` into a
+SwiftUI view and is attached with `.gesture(_:)`.
 
 ```swift
-struct PinchGestureView: UIGestureRecognizerRepresentable {
-    @Binding var scale: CGFloat
+struct IncrementalPinch: UIGestureRecognizerRepresentable {
+    var onStep: (CGFloat) -> Void
 
     func makeUIGestureRecognizer(context: Context) -> UIPinchGestureRecognizer {
         UIPinchGestureRecognizer()
     }
 
-    func handleUIGestureRecognizerAction(
-        _ recognizer: UIPinchGestureRecognizer,
-        context: Context
-    ) {
-        switch recognizer.state {
-        case .changed:
-            scale = recognizer.scale
-        case .ended:
-            scale = recognizer.scale
-            recognizer.scale = 1.0
-        default:
-            break
+    func handleUIGestureRecognizerAction(_ recognizer: UIPinchGestureRecognizer, context: Context) {
+        if recognizer.state == .changed { onStep(recognizer.scale) }
+        if recognizer.state == .changed || recognizer.state == .ended {
+            recognizer.scale = 1   // report each step, not the running total
         }
     }
 }
 
-// Usage in SwiftUI
-struct ContentView: View {
-    @State private var scale: CGFloat = 1.0
-
-    var body: some View {
-        Image("photo")
-            .scaleEffect(scale)
-            .gesture(PinchGestureView(scale: $scale))
-    }
-}
+// Usage
+mapLayer.gesture(IncrementalPinch { step in zoom *= step })
 ```
 
-### Using SwiftUI gestures in UIKit via UIHostingController
+### SwiftUI gestures inside UIKit
+
+Host the SwiftUI view with `UIHostingController`; its gestures work unchanged.
 
 ```swift
-class GestureHostingController: UIViewController {
+final class CanvasViewController: UIViewController {
+    private let planName = "floorplan"
+
     override func viewDidLoad() {
         super.viewDidLoad()
-
-        let swiftUIView = InteractiveCard()
-        let hostingController = UIHostingController(rootView: swiftUIView)
-        addChild(hostingController)
-        view.addSubview(hostingController.view)
-        hostingController.view.frame = view.bounds
-        hostingController.didMove(toParent: self)
-    }
-}
-
-struct InteractiveCard: View {
-    @GestureState private var dragOffset = CGSize.zero
-
-    var body: some View {
-        RoundedRectangle(cornerRadius: 16)
-            .fill(.blue.gradient)
-            .frame(width: 200, height: 300)
-            .offset(dragOffset)
-            .gesture(
-                DragGesture()
-                    .updating($dragOffset) { value, state, _ in
-                        state = value.translation
-                    }
-            )
+        let content = ZoomableImage(image: Image(planName))
+        let host = UIHostingController(rootView: content)
+        addChild(host)
+        view.addSubview(host.view)
+        host.view.frame = view.bounds
+        host.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        host.didMove(toParent: self)
     }
 }
 ```
 
-### Coordinating UIKit and SwiftUI gestures
+### Letting both sides recognize
 
-When mixing gesture recognizers, use `simultaneousGesture` on the SwiftUI side
-and `UIGestureRecognizerDelegate` on the UIKit side to prevent conflicts:
+When a SwiftUI gesture and a UIKit recognizer overlap, allow both on each side:
+use `.simultaneousGesture` in SwiftUI, and have the UIKit delegate agree to run
+together.
 
 ```swift
-// In your UIViewRepresentable coordinator
-func gestureRecognizer(
-    _ gestureRecognizer: UIGestureRecognizer,
-    shouldRecognizeSimultaneouslyWith other: UIGestureRecognizer
-) -> Bool {
-    true  // allow both UIKit and SwiftUI gestures to fire
+extension CanvasViewController: UIGestureRecognizerDelegate {
+    func gestureRecognizer(
+        _ recognizer: UIGestureRecognizer,
+        shouldRecognizeSimultaneouslyWith partner: UIGestureRecognizer
+    ) -> Bool {
+        true
+    }
 }
 ```
 
-## Accessibility Considerations
+## Accessibility considerations
 
-Always provide accessible alternatives for gesture-driven interactions:
+Every gesture-only interaction needs an alternative for VoiceOver, Switch
+Control and keyboard users. Expose the same effect as accessibility actions:
 
 ```swift
-Image("draggable")
-    .offset(offset)
-    .gesture(dragGesture)
-    .accessibilityAction(.default) { showAccessibleUI() }
-    .accessibilityAction(named: "Move up") {
-        withAnimation { offset.height -= 50 }
-    }
-    .accessibilityAction(named: "Move down") {
-        withAnimation { offset.height += 50 }
-    }
+Text(stop)
+    .gesture(reorder(stop))
+    .accessibilityAction(.default) { openDetails(for: stop) }
+    .accessibilityAction(named: "Move earlier") { shift(stop, by: -1) }
+    .accessibilityAction(named: "Move later") { shift(stop, by: 1) }
 ```