Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jtrivedi/wave

Wave is a spring-based animation engine for iOS and macOS that makes it easy to create fluid, interruptible animations that feel great.
https://github.com/jtrivedi/wave

animation appkit gestures interaction-design ios motion swift swiftui ui uikit

Last synced: about 15 hours ago
JSON representation

Wave is a spring-based animation engine for iOS and macOS that makes it easy to create fluid, interruptible animations that feel great.

Awesome Lists containing this project

README 

        


    




## Wave



Wave is a spring-based animation engine for iOS, iPadOS, and macOS. It makes it easy to create fluid, interactive, and interruptible animations that feel great.



Wave has no external dependencies, and can be easily dropped into existing UIKit, SwiftUI, or AppKit based projects and apps.



The core feature of Wave is that all animations are _re-targetable_, meaning that you can change an animation’s destination value in-flight, and the animation will gracefully _redirect_ to that new value.



- [Understanding Retargeting](#features)

- [Installation](#installation)

- [Documentation](#documentation)

- [Getting Started](#getting-started)

    - [Block-Based Animation](#block-based-animation)

    - [Property-Based Animation](#property-based-animation)

- [Example Code](#example-code)



#### Understanding Retargeting



Consider these demos of the iOS Picture-in-Picture feature. The screen on the left is created with standard UIKit animations, and the one on the right is created with Wave.



Though both are “interruptible”, the Wave-based implementation handles the interruption much better, and fluidly _arcs_ to its new destination. The UIKit animation feels stiff and jerky in comparison.



At its core, [retargeting](https://developer.apple.com/videos/play/wwdc2018/803/) is the process of preserving an animation’s velocity even as its target changes, which Wave does automatically.



![Demo](./Assets/Retargeting.gif)



### Installation



Add Wave to your app's `Package.swift` file, or selecting `File -> Add Packages` in Xcode:



```swift

.package(url: "https://github.com/jtrivedi/Wave")

```



If you clone the repo, you can run the sample app, which contains a few interactive demos to understand what Wave provides.



Note: To enable high frame-rate animations on ProMotion devices (i.e. 120 fps animation), you'll need to add a key/value pair in your `Info.plist`. Set the key `CADisableMinimumFrameDuration` to `true`. Without this entry, animations will be capped at 60 fps.



### Documentation



There’s a full Wave [documentation site](https://jtrivedi.github.io/Wave/) available for full API and usage documentation.



### Getting Started



There are two ways you can interact with Wave, depending on your needs: the block-based and property-based animations:



#### Block-Based Animation



The easiest way to get started is by using Wave’s block-based APIs that resemble the `UIView.animateWithDuration()` APIs.



This API lets you animate several common UIView and CALayer properties, like `frame`, `center`, `scale`, `backgroundColor`, and more.



For these supported properties, Wave will create, manage, and execute the required spring animations under-the-hood.



For example, animating the above PiP view to its final destination is extremely simple:



```swift

if panGestureRecognizer.state == .ended {



    // Create a spring with some bounciness. `response` affects the animation's duration.

    let animatedSpring = Spring(dampingRatio: 0.68, response: 0.80)



    // Get the gesture's lift-off velocity, and pass it into the Wave animation.

    let gestureVelocity = panGestureRecognizer.velocity(in: view)



    Wave.animate(withSpring: animatedSpring, gestureVelocity: gestureVelocity) {

        // Update animatable properties on the view's `animator` property, _not_ the view itself.

        pipView.animator.center = pipViewDestination     // Some target CGPoint that you calculate.

        pipView.animator.scale = CGPoint(x: 1.1, y: 1.1)

    }

}

```



Note that at _any_ time, you can _retarget_ the view’s `center` property to somewhere else, and it’ll gracefully animate.



##### Supported Animatable Properties



The block-based API currently supports animating the following properties. For other properties, you can use the property-based animation API below.



* `frame`

* `bounds`

* `center`

* `origin`

* `alpha`

* `backgroundColor`

* `cornerRadius`

* `scale`

* `translation`

* `shadowColor/radius/offset/opacity`

* `borderColor/borderWidth`



Upcoming properties:



* `rotation`



#### Property-Based Animation



While the block-based API is often most convenient, you may want to animate something that the block-based API doesn’t yet support (e.x. rotation). Or, you may want the flexibility of getting the intermediate spring values and driving an animation yourself (e.x. a progress value).



For example, to draw the orange path of the PiP demo, we need to know the value of every `CGPoint` from the view’s initial center, to its destination center:



```swift

// When the gesture ends, create a `CGPoint` animator from the PiP view's initial center, to its target.

// The `valueChanged` callback provides the intermediate locations of the callback, allowing us to draw the path.



let positionAnimator = SpringAnimator(spring: animatedSpring)

positionAnimator.value = pipView.center       // The presentation value

positionAnimator.target = pipViewDestination  // The target value

positionAnimator.velocity = gestureVelocity



positionAnimator.valueChanged = { [weak self] location in

    self?.drawPathPoint(at: location)

}



positionAnimator.start()

```



##### Completion Blocks



Both the block-based and property-based APIs support completion blocks. If an animation completes fully, the completion block’s `finished` flag will be true.



However, if an animation’s target was changed in-flight (“retargeted”), `finished` will be false, while `retargeted` will be true.



```swift

Wave.animate(withSpring: Spring.defaultAnimated) {

    myView.animator.backgroundColor = .systemBlue

} completion: { finished, retargeted in

    print(finished, retargeted)

}

```



### Example Code



Exploring the provided sample app is a great way to get started with Wave.



Simply open the `Wave-Sample` Xcode project and hit “Run”. The full source code for the Picture-in-Picture demo is available there, too!



### Acknowledgements



Special thanks to [Ben Oztalay](https://github.com/boztalay) for helping architect the underlying physics of Wave!