SwiftUINavigationTransitions

NavigationTransitionProtocol is the primary interface for defining how a pair of views interact during navigation. It uses a result builder syntax to compose transitions for different lifecycle events.

Commonly, you will implement this protocol by wrapping AtomicTransition types. For example, a Slide implementation might use MirrorPush to coordinate OnInsertion and OnRemoval behaviors for different axes.

Example of a protocol implementation structure:

public struct Slide: NavigationTransitionProtocol {
    private let axis: Axis

    public init(axis: Axis) {
        self.axis = axis
    }

    public var body: some NavigationTransitionProtocol {
        switch axis {
        case .horizontal:
            MirrorPush {
                OnInsertion {
                    Move(edge: .trailing)
                }
                OnRemoval {
                    Move(edge: .leading)
                }
            }
        case .vertical:
            MirrorPush {
                OnInsertion {
                    Move(edge: .bottom)
                }
                OnRemoval {
                    Move(edge: .top)
                }
            }
        }
    }
}

Building custom transitions in this library relies on a layered approach using two primary abstractions: NavigationTransitionProtocol and AtomicTransition.

NavigationTransitionProtocol

This is the high-level construct used to describe a full navigation event. It defines both the push and pop behaviors for both the origin and destination views. While you often interact with type-erased wrappers like CustomNavigationTransition (e.g., .slide), the actual logic resides in types conforming to NavigationTransitionProtocol.

AtomicTransition

An AtomicTransition is a lower-level building block inspired by SwiftUI's AnyTransition. Unlike the protocol above, an AtomicTransition applies to a single view and is agnostic of the navigation intent (it doesn't care if the view is being pushed or popped). It describes specific view changes for both insertion and removal operations.

By composing multiple AtomicTransition instances (like Move) within a NavigationTransitionProtocol using result builder syntax, you can define complex navigation behaviors without writing explicit UIView animation code.

AtomicTransition is used to define how a single view behaves during an insertion or removal operation. It is the granular building block of the library.

A typical implementation involves overriding the transition(_:for:in:) method to manipulate the translation properties of the view's state (initial, animation, or completion) based on the provided Edge and TransitionOperation.

Example of a Move implementation:

public struct Move: AtomicTransition {
    private let edge: Edge

    public init(edge: Edge) {
        self.edge = edge
    }

    public func transition(_ view: TransientView, for operation: TransitionOperation, in container: Container) {
        switch (edge, operation) {
        case (.top, .insertion):
            view.initial.translation.dy = -container.frame.height
            view.animation.translation.dy = 0
        // ... other cases
        }
    }
}

public struct Move: AtomicTransition {
    private let edge: Edge

    public init(edge: Edge) {
        self.edge = edge
    }

    public func transition(_ view: TransientView, for operation: TransitionOperation, in container: Container) {
        switch (edge, operation) {
        case (.top, .insertion):
            view.initial.translation.dy = -container.frame.height
            view.animation.translation.dy = 0

        case (.leading, .insertion):
            view.initial.translation.dx = -container.frame.width
            view.animation.translation.dx = 0

        case (.trailing, .insertion):
            view.initial.translation.dx = container.frame.width
            view.animation.translation.dx = 0

        case (.bottom, .insertion):
            view.initial.translation.dy = container.frame.height
            view.animation.translation.dy = 0

        case (.top, .removal):
            view.animation.translation.dy = -container.frame.height
            view.completion.translation.dy = 0

        case (.leading, .removal):
            view.animation.translation.dx = -container.frame.width
            view.completion.translation.dx = 0

        case (.trailing, .removal):
            view.animation.translation.dx = container.frame.width
            view.completion.translation.dx = 0

        case (.bottom, .removal):
            view.animation.translation.dy = container.frame.height
            view.completion.translation.dy = 0
        }
    }
}

For advanced use cases—such as migrating existing UIViewControllerAnimatedTransitioning implementations or requiring raw UIKit control—you can use PrimitiveNavigationTransition. This is the lowest level of the API and interacts directly with UIKit abstractions.

To implement this, you must provide a transition handler that uses the provided Animator to set up animations and completion logic. This approach automatically handles interactive pops as long as you use the provided Animator.

Warning: This level of granularity is rarely needed and should be avoided unless you specifically require manual control over view snapshotting, hierarchy setup, or animator configuration.

@objc public protocol Animator {
    func addAnimations(_ animation: @escaping () -> Void)
    func addCompletion(_ completion: @escaping (UIViewAnimatingPosition) -> Void)
}

struct MyTransition: PrimitiveNavigationTransition {
    func transition(with animator: Animator, for operation: TransitionOperation, in context: Context) {
        // ...
    }
}