Merge branch 'feature/flowstack-rewrite'

.swift-version

@@ -0,0 +1 @@
+5.10

.swiftformat

@@ -0,0 +1,84 @@
+--acronyms ID,URL,UUID
+--allman false
+--anonymousforeach convert
+--assetliterals visual-width
+--asynccapturing 
+--beforemarks 
+--binarygrouping 4,8
+--categorymark "MARK: %c"
+--classthreshold 0
+--closingparen balanced
+--closurevoid remove
+--commas always
+--conflictmarkers reject
+--decimalgrouping 3,6
+--doccomments before-declarations
+--elseposition same-line
+--emptybraces no-space
+--enumnamespaces always
+--enumthreshold 0
+--exponentcase lowercase
+--exponentgrouping disabled
+--extensionacl on-extension
+--extensionlength 0
+--extensionmark "MARK: - %t + %c"
+--fractiongrouping disabled
+--fragment false
+--funcattributes preserve
+--generictypes 
+--groupedextension "MARK: %c"
+--guardelse auto
+--header ignore
+--hexgrouping 4,8
+--hexliteralcase uppercase
+--ifdef indent
+--importgrouping alpha
+--indent 2
+--indentcase false
+--indentstrings false
+--lifecycle 
+--lineaftermarks true
+--linebreaks lf
+--markcategories true
+--markextensions always
+--marktypes always
+--maxwidth none
+--modifierorder 
+--nevertrailing 
+--nospaceoperators 
+--nowrapoperators 
+--octalgrouping 4,8
+--onelineforeach ignore
+--operatorfunc spaced
+--organizetypes actor,class,enum,struct
+--patternlet hoist
+--ranges spaced
+--redundanttype infer-locals-only
+--self remove
+--selfrequired 
+--semicolons inline
+--shortoptionals except-properties
+--smarttabs enabled
+--someany true
+--stripunusedargs always
+--structthreshold 0
+--tabwidth unspecified
+--throwcapturing 
+--trailingclosures 
+--trimwhitespace always
+--typeattributes preserve
+--typeblanklines remove
+--typemark "MARK: - %t"
+--varattributes preserve
+--voidtype void
+--wraparguments preserve
+--wrapcollections preserve
+--wrapconditions preserve
+--wrapeffects preserve
+--wrapenumcases always
+--wrapparameters default
+--wrapreturntype preserve
+--wrapternary default
+--wraptypealiases preserve
+--xcodeindentation disabled
+--yodaswap always

Docs/Migration/Migrating to 1.0.md

@@ -0,0 +1,67 @@
+# Migrating to 1.0
+
+Before its API was brought more in line with `NavigationStack` APIs, previous versions of `FlowStacks` had two major differences:
+
+- Previously the `Router` (now the `FlowStack`) handled both state management _and_ building destination views. The latter has now been decoupled into a separate function `flowDestination(...)`. This decoupling you more flexibility over where you set up flow destinations, but for easy migration, you can keep them in the same place as you initialise the `FlowStack`.
+- Previously the root screen was part of the routes array. The root screen is no longer part of the routes array. Usually that will mean removing the root screen's case from your Screen enum and moving its view creation into the FlowStack initialiser. It might be awkward if your flow supported more than one root screen. In those cases, you will probably want to split the flow into two separate flows, each with its own `FlowStack` and a parent view that switches between them as needed.
+
+Here's an example migration:
+
+<details>
+ <summary>Previous API</summary>
+
+```swift
+enum Screen {
+  case home
+  case numberList
+  case numberDetail(Int)
+}
+
+struct AppCoordinator: View {
+  @State var routes: Routes<Screen> = [.root(.home)]
+
+  var body: some View {
+    Router($routes, embedInNavigationView: true) { screen, _ in
+      switch screen {
+      case .home:
+        HomeView()
+      case .numberList:
+        NumberListView()
+      case .numberDetail(let number):
+        NumberDetailView(number: number)
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+ <summary>New API</summary>
+
+```swift
+enum Screen {
+  case numberList
+  case numberDetail(Int)
+}
+
+struct AppCoordinator: View {
+  @State var routes: [Route<Screen>] = []
+
+  var body: some View {
+    FlowStack($routes, withNavigation: true) { 
+      HomeView()
+        .flowDestination(for: Screen.self) { screen in
+          switch screen {
+          case .numberList:
+            NumberListView()
+          case .numberDetail(let number):
+            NumberDetailView(number: number)
+        }
+    }
+  }
+}
+```
+
+</details>

Docs/Nesting FlowStacks.md

@@ -0,0 +1,20 @@
+# Nesting FlowStacks
+
+Sometimes, it can be useful to break your app's screen flows into several distinct flows of related screens. FlowStacks supports nesting coordinators ('coordinator' is used to describe a view that contains a `FlowStack` to manage a flow of screens). 
+
+Coordinators are just SwiftUI views, so they can be shown in all the normal ways views can. They can even be pushed onto a parent coordinator's `FlowStack`, allowing you to break out parts of your navigation flow into distinct child coordinators. 
+
+The best approach to nesting coordinators will depend on how you are instantiating your `FlowStack`. A `FlowStack` can be instantiated with either:
+
+1. a binding to a `FlowPath`,
+1. no binding at all, or
+1. a binding to a routes array, e.g. `[Route<MyScreen>]`.
+
+
+## Nesting FlowStacks using FlowPaths
+
+In the first two cases, any type can be pushed onto the path, and as long as somewhere in the stack you have declared how to build a flow destination for that data type (using the `flowDestination` modifier), the screen will be shown. That means you can nest any number of child `FlowStack`s of this type, and they will all share the same path state - parent and children all have access to the same shared path that includes all coordinators' screens. See the [example app](FlowStacksApp/Shared/FlowPathView) for how this might work.
+
+## Nesting FlowStacks using Routes Arrays
+
+'If using a binding to a routes array, e.g. `[Route<MyScreen>]`, it's still possible to nest cooordinators, but there are some things to keep in mind. Since only `MyScreen` routes can be added to the array, any nested child `FlowStack`s cannot share the same path state. They will instead have their own independent array of routes. When doing so, it is essential that the child coordinator is always at the top of the parent's routes stack, as it will take over responsibility for pushing and presenting new screens. Otherwise, the parent might attempt to push screen(s) when the child is already pushing screen(s), causing a conflict.