Adds docs and updates examples

NavigationBackportApp/Shared/ArrayBindingView.swift

@@ -127,26 +127,9 @@ private struct NumberView: View {
 
 private struct EmojiView: View {
   let visualisation: EmojiVisualisation
-  @State var isPushing = false
 
   var body: some View {
-    VStack {
-      Text(visualisation.text)
-      Toggle(isOn: $isPushing, label: { Text("Push") }).labelsHidden()
-    }
-    .nbNavigationDestination(isPresented: $isPushing, destination: {
-      TestView()
-    })
-    .navigationTitle("Visualise \(visualisation.count)")
-  }
-}
-
-struct TestView: View {
-  @Environment(\.presentationMode) var presentationMode
-
-  var body: some View {
-    Button("Back") {
-      presentationMode.wrappedValue.dismiss()
-    }
+    Text(visualisation.text)
+      .navigationTitle("Visualise \(visualisation.count)")
   }
 }

Sources/NavigationBackport/CodableRepresentation.swift

@@ -1,6 +1,7 @@
 import Foundation
 
 public extension NBNavigationPath {
+  /// A codable representation of a navigation path.
   struct CodableRepresentation {
     static let encoder = JSONEncoder()
     static let decoder = JSONDecoder()
@@ -36,6 +37,8 @@ extension NBNavigationPath.CodableRepresentation: Encodable {
     return try _openExistential(element, do: encodeOpened(_:))
   }
 
+  /// Encodes the representation into the encoder's unkeyed container.
+  /// - Parameter encoder: The encoder to use.
   public func encode(to encoder: Encoder) throws {
     var container = encoder.unkeyedContainer()
     for element in elements.reversed() {

Sources/NavigationBackport/DestinationBuilderHolder.swift

@@ -1,6 +1,7 @@
 import Foundation
 import SwiftUI
 
+/// Keeps hold of the destination builder closures for a given type or local destination ID.
 class DestinationBuilderHolder: ObservableObject {
   static func identifier(for type: Any.Type) -> String {
     String(reflecting: type)

Sources/NavigationBackport/DestinationBuilderModifier.swift

@@ -1,6 +1,7 @@
 import Foundation
 import SwiftUI
 
+/// Modifier for appending a new destination builder.
 struct DestinationBuilderModifier<TypedData>: ViewModifier {
   let typedDestinationBuilder: DestinationBuilder<TypedData>
 

Sources/NavigationBackport/DestinationBuilderView.swift

@@ -1,6 +1,7 @@
 import Foundation
 import SwiftUI
 
+/// Builds a view from the given Data, using the destination builder environment object.
 struct DestinationBuilderView<Data>: View {
   let data: Data
 

Sources/NavigationBackport/LocalDestinationBuilderModifier.swift

@@ -1,10 +1,12 @@
 import Foundation
 import SwiftUI
 
+/// Uniquely identifies an instance of a local destination builder.
 struct LocalDestinationID: RawRepresentable, Hashable {
   let rawValue: UUID
 }
 
+/// Persistent object to hold the local destination ID and remove it when the destination builder is removed.
 class LocalDestinationIDHolder: ObservableObject {
   let id = LocalDestinationID(rawValue: UUID())
   weak var destinationBuilder: DestinationBuilderHolder?
@@ -14,6 +16,7 @@ class LocalDestinationIDHolder: ObservableObject {
   }
 }
 
+/// Modifier that appends a local destination builder and ensures the Bool binding is observed and updated.
 struct LocalDestinationBuilderModifier: ViewModifier {
   let isPresented: Binding<Bool>
   let builder: () -> AnyView
@@ -26,26 +29,24 @@ struct LocalDestinationBuilderModifier: ViewModifier {
     destinationBuilder.appendLocalBuilder(identifier: destinationID.id, builder)
     destinationID.destinationBuilder = destinationBuilder
 
-    return Group {
-      content
-        .environmentObject(destinationBuilder)
-        .onChange(of: pathHolder.path) { _ in
-          if isPresented.wrappedValue {
-            if !pathHolder.path.contains(where: { ($0 as? LocalDestinationID) == destinationID.id }) {
-              isPresented.wrappedValue = false
-            }
+    return content
+      .environmentObject(destinationBuilder)
+      .onChange(of: pathHolder.path) { _ in
+        if isPresented.wrappedValue {
+          if !pathHolder.path.contains(where: { ($0 as? LocalDestinationID) == destinationID.id }) {
+            isPresented.wrappedValue = false
           }
         }
-    }
-    .onChange(of: isPresented.wrappedValue) { isPresented in
-      if isPresented {
-        pathHolder.path.append(destinationID.id)
-      } else {
-        let index = pathHolder.path.lastIndex(where: { ($0 as? LocalDestinationID) == destinationID.id })
-        if let index {
-          pathHolder.path.remove(at: index)
+      }
+      .onChange(of: isPresented.wrappedValue) { isPresented in
+        if isPresented {
+          pathHolder.path.append(destinationID.id)
+        } else {
+          let index = pathHolder.path.lastIndex(where: { ($0 as? LocalDestinationID) == destinationID.id })
+          if let index {
+            pathHolder.path.remove(at: index)
+          }
         }
       }
-    }
   }
 }

Sources/NavigationBackport/NBNavigationLink.swift

@@ -2,6 +2,7 @@ import Foundation
 import SwiftUI
 
 @available(iOS, deprecated: 16.0, message: "Use SwiftUI's Navigation API beyond iOS 15")
+/// When value is non-nil, shows the destination associated with its type.
 public struct NBNavigationLink<P: Hashable, Label: View>: View {
   var value: P?
   var label: Label

Sources/NavigationBackport/NBNavigationPath.swift

@@ -2,10 +2,14 @@ import Foundation
 import SwiftUI
 
 @available(iOS, deprecated: 16.0, message: "Use SwiftUI's Navigation API beyond iOS 15")
+/// A type-erased wrapper for an Array of any Hashable types, to be displayed in a `NBNavigationStack`.
 public struct NBNavigationPath: Equatable {
   var elements: [AnyHashable]
 
+  /// The number of screens in the path.
   public var count: Int { elements.count }
+
+  /// WHether the path is empty.
   public var isEmpty: Bool { elements.isEmpty }
 
   public init(_ elements: [AnyHashable] = []) {

Sources/NavigationBackport/NBNavigationStack.swift

@@ -2,6 +2,7 @@ import Foundation
 import SwiftUI
 
 @available(iOS, deprecated: 16.0, message: "Use SwiftUI's Navigation API beyond iOS 15")
+/// A replacement for SwiftUI's `NavigationStack` that's available on older OS versions.
 public struct NBNavigationStack<Root: View, Data: Hashable>: View {
   var unownedPath: Binding<[Data]>?
   @StateObject var ownedPath = NavigationPathHolder()

Sources/NavigationBackport/NavigationBackport.swift

@@ -4,6 +4,11 @@ import SwiftUI
 typealias DestinationBuilder<T> = (T) -> AnyView
 
 enum NavigationBackport {
+  /// Calculates the minimal number of steps to update from one stack of screens to another, within the constraints of SwiftUI.
+  /// - Parameters:
+  ///   - start: The initial state.
+  ///   - end: The goal state.
+  /// - Returns: A series of state updates from the start to end.
   public static func calculateSteps<Screen>(from start: [Screen], to end: [Screen]) -> [[Screen]] {
     let replacableScreens = end.prefix(start.count)
     let remainingScreens = start.count < end.count ? end.suffix(from: start.count) : []

Sources/NavigationBackport/NavigationPathHolder.swift

@@ -1,6 +1,7 @@
 import Foundation
 import SwiftUI
 
+/// An object that publishes changes to the path Array it holds.
 class NavigationPathHolder: ObservableObject {
   @Published var path: [AnyHashable] = []
 }

Sources/NavigationBackport/Navigator.swift

@@ -1,5 +1,6 @@
 import SwiftUI
 
+/// A navigator to use when the `NBNavigationStack` is initialized with a `NBNavigationPath` binding or no binding.`
 public typealias PathNavigator = Navigator<AnyHashable>
 
 /// An object available via the environment that gives access to the current path.

Sources/NavigationBackport/PathAppender.swift

@@ -1,6 +1,7 @@
 import Foundation
 import SwiftUI
 
+/// An object that never publishes changes, but allows appending to an NBNavigationStack's path.
 class PathAppender: ObservableObject {
   var append: ((AnyHashable) -> Void)?
 }

Sources/NavigationBackport/View+nbNavigationDestination.swift

@@ -10,6 +10,42 @@ public extension View {
 
 public extension View {
   @available(iOS, deprecated: 16.0, message: "Use SwiftUI's Navigation API beyond iOS 15")
+  /// Associates a destination view with a binding that can be used to push
+  /// the view onto a ``NBNavigationStack``.
+  ///
+  /// In general, favor binding a path to a navigation stack for programmatic
+  /// navigation. Add this view modifer to a view inside a ``NBNavigationStack``
+  /// to programmatically push a single view onto the stack. This is useful
+  /// for building components that can push an associated view. For example,
+  /// you can present a `ColorDetail` view for a particular color:
+  ///
+  ///     @State private var showDetails = false
+  ///     var favoriteColor: Color
+  ///
+  ///     NBNavigationStack {
+  ///         VStack {
+  ///             Circle()
+  ///                 .fill(favoriteColor)
+  ///             Button("Show details") {
+  ///                 showDetails = true
+  ///             }
+  ///         }
+  ///         .nbNavigationDestination(isPresented: $showDetails) {
+  ///             ColorDetail(color: favoriteColor)
+  ///         }
+  ///         .nbNavigationTitle("My Favorite Color")
+  ///     }
+  ///
+  /// Do not put a navigation destination modifier inside a "lazy" container,
+  /// like ``List`` or ``LazyVStack``. These containers create child views
+  /// only when needed to render on screen. Add the navigation destination
+  /// modifier outside these containers so that the navigation stack can
+  /// always see the destination.
+  ///
+  /// - Parameters:
+  ///   - isPresented: A binding to a Boolean value that indicates whether
+  ///     `destination` is currently presented.
+  ///   - destination: A view to present.
   func nbNavigationDestination<V>(isPresented: Binding<Bool>, @ViewBuilder destination: () -> V) -> some View where V: View {
     let builtDestination = AnyView(destination())
     return modifier(

Sources/NavigationBackport/apply.swift

@@ -1,3 +1,8 @@
+/// Utilty for applying a transform to a value.
+/// - Parameters:
+///   - transform: The transform to apply.
+///   - input: The value to be transformed.
+/// - Returns: The transformed value.
 func apply<T>(_ transform: (inout T) -> Void, to input: T) -> T {
   var transformed = input
   transform(&transformed)