Swiftui Animation

# SwiftUI Animation Advanced Reference

Detailed API reference for SwiftUI animation types, protocols, and patterns.
Covers material beyond the SKILL.md summary.

## Contents

- [CustomAnimation Protocol (iOS 17+)](#customanimation-protocol-ios-17)
- [Spring Type -- All Initializer Variants](#spring-type-all-initializer-variants)
- [UnitCurve Types (iOS 17+)](#unitcurve-types-ios-17)
- [PhaseAnimator Deep Patterns](#phaseanimator-deep-patterns)
- [KeyframeAnimator Multi-Track Examples](#keyframeanimator-multi-track-examples)
- [Transaction and TransactionKey](#transaction-and-transactionkey)
- [Scoped Implicit Animation](#scoped-implicit-animation)
- [All Transition Types (iOS 17+)](#all-transition-types-ios-17)
- [All Symbol Effect Types](#all-symbol-effect-types)
- [Reduce Motion Implementation Patterns](#reduce-motion-implementation-patterns)
- [Animation Performance Tips](#animation-performance-tips)

## CustomAnimation Protocol (iOS 17+)

Create entirely custom animation curves by conforming to `CustomAnimation`.

```swift
@preconcurrency protocol CustomAnimation: Hashable, Sendable
```

### Required Method

```swift
func animate<V: VectorArithmetic>(
    value: V,
    time: TimeInterval,
    context: inout AnimationContext<V>
) -> V?
```

Return the interpolated value at the given time. Return `nil` when the
animation is complete.

### Optional Methods

```swift
func velocity<V: VectorArithmetic>(
    value: V,
    time: TimeInterval,
    context: AnimationContext<V>
) -> V?

func shouldMerge<V: VectorArithmetic>(
    previous: Animation,
    value: V,
    time: TimeInterval,
    context: inout AnimationContext<V>
) -> Bool
```

### Full Example: Elastic Ease-In-Out

```swift
struct ElasticAnimation: CustomAnimation {
    let duration: TimeInterval

    func animate<V: VectorArithmetic>(
        value: V,
        time: TimeInterval,
        context: inout AnimationContext<V>
    ) -> V? {
        guard time <= duration else { return nil }
        let p = time / duration
        let s = sin((20 * p - 11.125) * ((2 * .pi) / 4.5))
        let progress: Double
        if p < 0.5 {
            progress = -(pow(2, 20 * p - 10) * s) / 2
        } else {
            progress = (pow(2, -20 * p + 10) * s) / 2 + 1
        }
        return value.scaled(by: progress)
    }
}
```

### Ergonomic Extension Pattern

Expose custom animations as static members on `Animation`.

```swift
extension Animation {
    static var elastic: Animation {
        elastic(duration: 0.35)
    }

    static func elastic(duration: TimeInterval) -> Animation {
        Animation(ElasticAnimation(duration: duration))
    }
}

// Usage
withAnimation(.elastic(duration: 0.5)) { isActive.toggle() }
```

### Supporting Types

| Type | Role |
|---|---|
| `AnimationContext<V>` | Carries environment and per-animation state |
| `AnimationState` | Key-value storage for persisted state |
| `AnimationStateKey` | Protocol for defining custom state keys |

## Spring Type -- All Initializer Variants

### Perceptual (Preferred)

```swift
Spring(duration: 0.5, bounce: 0.0)
```

- `duration` -- Perceptual duration controlling pace. Default `0.5`.
- `bounce` -- Bounciness. `0.0` = no bounce, `1.0` = undamped. Negative values
  produce overdamped springs. Default `0.0`.

### Physical Parameters

```swift
Spring(mass: 1.0, stiffness: 100.0, damping: 10.0, allowOverDamping: false)
```

- `mass` -- Mass at end of spring. Default `1.0`.
- `stiffness` -- Spring stiffness coefficient.
- `damping` -- Friction-like drag force.
- `allowOverDamping` -- Permit damping ratio > 1. Default `false`.

### Response-Based

```swift
Spring(response: 0.5, dampingRatio: 0.7)
```

- `response` -- Stiffness expressed as approximate duration in seconds.
- `dampingRatio` -- Fraction of critical damping. `1.0` = critically damped.

### Settling-Based

```swift
Spring(settlingDuration: 1.0, dampingRatio: 0.8, epsilon: 0.001)
```

- `settlingDuration` -- Estimated time to come to rest.
- `dampingRatio` --