Merge pull request #38 from frzi/dev/docs

Dev/docs

Author: frzi

Docs/AnimatingRoutes.md

@@ -1,5 +1,9 @@
 # Animating routes
 
+Simulating screen transitions à la iOS.
+
+## Introduction
+
 On a platform like iOS, users may expect animated screen transitions when navigating through the app. (Less so the case with macOS) Apps get these transitions for free with `NavigationView`. But with SwiftUI Router, however, this is not the case. Ideally, you want a transition that differs as the user goes forward (deeper) in the app and when they go back (higher).
 
 SwiftUI Router exposes the `Navigator` environment object. An object that allows for navigation done programmatically. It also contains the property `.lastAction`, which is of type `NavigationAction?`. This object contains read-only information about the last navigation that occurred. Information like the previous path, the current path, whether the app navigated forward or back. But also the *direction* of the navigation, which is what we're interested in right now.
@@ -16,7 +20,7 @@ struct NavigationTransition: ViewModifier {
 
 	func body(content: Content) -> some View {
 		content
-			.animation(.easeInOut)
+			.animation(.easeInOut, value: navigator.path)
 			.transition(
 				navigator.lastAction?.direction == .deeper || navigator.lastAction?.direction == .sideways
 					? AnyTransition.asymmetric(insertion: .move(edge: .trailing), removal: .move(edge: .leading))
@@ -39,19 +43,19 @@ extension View {
 
 The modifier can be applied to `Route` views:
 ```swift
-Route(path: "news") {
+Route("news") {
 	NewsScreen()
 }
 .navigationTransition()
 ```
 
-The modifier can also be applied to a `SwitchRoutes`. This will apply the animated transition to all `Route` views inside the `SwitchRoutes`.
+The modifier can also be applied to a ``SwitchRoutes``. This will apply the animated transition to all `Route` views inside the ``SwitchRoutes``.
 ```swift
 SwitchRoutes {
-	Route(path: "news/:id", validator: newsIdValidator) { uuid in
+	Route("news/:id", validator: newsIdValidator) { uuid in
 		NewsItemScreen(uuid: uuid)
 	}
-	Route(path: "news") {
+	Route("news") {
 		NewsScreen()
 	}
 	Route {

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.3
+// swift-tools-version:5.5
 
 import PackageDescription
 

README.md

@@ -1,18 +1,19 @@
 <img src="Docs/Images/logo.svg" alt="SwiftUI Router" width="600">
 
-> Easy and maintainable app navigation with path based routing for SwiftUI.
+> Easy and maintainable app navigation with path-based routing for SwiftUI.
 
 ![SwiftUI](https://img.shields.io/github/v/release/frzi/SwiftUIRouter?style=for-the-badge)
 [![SwiftUI](https://img.shields.io/badge/SwiftUI-blue.svg?style=for-the-badge&logo=swift&logoColor=black)](https://developer.apple.com/xcode/swiftui)
 [![Swift](https://img.shields.io/badge/Swift-5.3-orange.svg?style=for-the-badge&logo=swift)](https://swift.org)
 [![Xcode](https://img.shields.io/badge/Xcode-13-blue.svg?style=for-the-badge&logo=Xcode&logoColor=white)](https://developer.apple.com/xcode)
 [![MIT](https://img.shields.io/badge/license-MIT-black.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 
-With **SwiftUI Router** you can power your SwiftUI app with path based routing. By utilizing a path based system, navigation in your app becomes more flexible and easier to maintain.
+With **SwiftUI Router** you can power your SwiftUI app with path-based routing. By utilizing a path-based system, navigation in your app becomes more flexible and easier to maintain.
 
 ## Index
 * [Installation](#installation-)
 * [Documentation](#documentation-)
+* [Examples](#examples-)
 * [Usage](#usage-)
 * [License](#license-)
 
@@ -31,7 +32,15 @@ import SwiftUIRouter
 <br>
 
 ## Documentation 📚
-- [Animating routes](/Docs/AnimatingRoutes.md)
+- [Animating routes](/Sources/SwiftUIRouter/AnimatingRoutes.md)
+
+<br>
+
+## Examples 👀
+- [SwiftUI Router Examples](https://github.com/frzi/SwiftUIRouter-Examples) contains:  
+  ┗ [RandomUsers](https://github.com/frzi/SwiftUIRouter-Examples/tree/main/RandomUsers)  
+  ┗ [Swiping](https://github.com/frzi/SwiftUIRouter-Examples/tree/main/Swiping)  
+  ┗ [TabViews](https://github.com/frzi/SwiftUIRouter-Examples/tree/main/TabViewRouting)
 
 <br>
 
@@ -50,13 +59,13 @@ The entry of a routing environment. Wrap your entire app (or just the part that
 
 ### `Route`
 ```swift
-Route(path: "news/*") {
+Route("news/*") {
 	NewsScreen()
 }
-Route(path: "settings") {
+Route("settings") {
 	SettingsScreen()
 }
-Route(path: "user/:id?") { info in
+Route("user/:id?") { info in
 	UserScreen(id: info.parameters["id"])
 }
 ```
@@ -72,7 +81,7 @@ func validateUserID(routeInfo: RouteInformation) -> UUID? {
 	UUID(routeInfo.parameters["id"] ?? "")
 }
 
-Route(path: "user/:id", validator: validateUserID) { userID in
+Route("user/:id", validator: validateUserID) { userID in
 	UserScreen(userID: userID)
 }
 ```
@@ -97,13 +106,13 @@ A wrapper around a `Button` that will navigate to the given path if pressed.
 ### `SwitchRoutes`
 ```swift
 SwitchRoutes {
-	Route(path: "latest") {
+	Route("latest") {
 		LatestNewsScreen()
 	}
-	Route(path: "article/:id") { info in
+	Route("article/:id") { info in
 		NewsArticleScreen(articleID: info.parameters["id"]!)
 	}
-	Route(path: ":unknown") {
+	Route(":unknown") {
 		ErrorScreen()
 	}
 	Route {

Sources/Navigate.swift

@@ -7,13 +7,13 @@ import SwiftUI
 
 /// When rendered will automatically perform a navigation to the given path.
 ///
-/// This view allows you to pragmatically navigate to a new path in a View's body.
+/// This view allows you to programmatically navigate to a new path in a View's body.
 ///
 /// ```swift
 /// SwitchRoutes {
-/// 	Route(path: "news") { NewsView() }
+/// 	Route("news", content: NewsView())
 /// 	Route {
-/// 		// If this Route gets rendered redirect
+/// 		// If this Route gets rendered it'll redirect
 /// 		// the user to a 'not found' screen.
 /// 		Navigate(to: "/not-found")
 /// 	}
@@ -31,6 +31,7 @@ public struct Navigate: View {
 	private let replace: Bool
 
 	/// - Parameter path: New path to navigate to once the View is rendered.
+	/// - Parameter replace: if `true` will replace the last path in the history stack with the new path.
 	public init(to path: String, replace: Bool = true) {
 		self.path = path
 		self.replace = replace

Sources/Navigator.swift

@@ -68,7 +68,7 @@ public final class Navigator: ObservableObject {
 	/// will be printed to the console.
 	///
 	/// - Parameter path: Path of the new location to navigate to.
-	/// - Parameter replace: if `true`, will not add the current location to the history.
+	/// - Parameter replace: if `true` will replace the last path in the history stack with the new path.
 	public func navigate(_ path: String, replace: Bool = false) {
 		let path = resolvePaths(self.path, path)
 		let previousPath = self.path

Sources/Route.swift

@@ -11,7 +11,7 @@ import SwiftUI
 /// When the environment path matches a `Route`'s path, its contents will be rendered.
 ///
 /// ```swift
-/// Route(path: "settings") {
+/// Route("settings") {
 /// 	SettingsView()
 /// }
 /// ```
@@ -24,7 +24,7 @@ import SwiftUI
 ///
 /// **Note:** Only alphanumeric characters (A-Z, a-z, 0-9) are valid for parameters.
 /// ```swift
-/// Route(path: "/news/:id") { routeInfo in
+/// Route("/news/:id") { routeInfo in
 /// 	NewsItemView(id: routeInfo.parameters["id"]!)
 /// }
 /// ```
@@ -39,7 +39,7 @@ import SwiftUI
 /// 	UUID(info.parameters["uuid"]!)
 /// }
 /// // Will only render if `uuid` is a valid UUID.
-/// Route(path: "user/:uuid", validator: validate) { uuid in
+/// Route("user/:uuid", validator: validate) { uuid in
 /// 	UserScreen(userId: uuid)
 /// }
 /// ```
@@ -48,13 +48,13 @@ import SwiftUI
 /// Every path found in a `Route`'s hierarchy is relative to the path of said `Route`. With the exception of paths
 /// starting with `/`. This allows you to develop parts of your app more like separate 'sub' apps.
 /// ```swift
-/// Route(path: "/news") {
+/// Route("/news") {
 /// 	// Goes to `/news/latest`
 /// 	NavLink(to: "latest") { Text("Latest news") }
 /// 	// Goes to `/home`
 /// 	NavLink(to: "/home") { Text("Home") }
 /// 	// Route for `/news/unknown/*`
-/// 	Route(path: "unknown/*") {
+/// 	Route("unknown/*") {
 /// 		// Redirects to `/news/error`
 /// 		Navigate(to: "../error")
 /// 	}
@@ -79,7 +79,7 @@ public struct Route<ValidatedData, Content: View>: View {
 	/// - Parameter validator: A function that validates and transforms the route parameters.
 	/// - Parameter content: Views to render. The validated data is passed as an argument.
 	public init(
-		path: String = "*",
+		_ path: String = "*",
 		validator: @escaping Validator,
 		@ViewBuilder content: @escaping (ValidatedData) -> Content
 	) {
@@ -88,6 +88,15 @@ public struct Route<ValidatedData, Content: View>: View {
 		self.validator = validator
 	}
 
+	@available(*, deprecated, renamed: "init(_:validator:content:)")
+	public init(
+		path: String,
+		validator: @escaping Validator,
+		@ViewBuilder content: @escaping (ValidatedData) -> Content
+	) {
+		self.init(path, validator: validator, content: content)
+	}
+
 	public var body: some View {
 		let resolvedGlob = resolvePaths(relativePath, path)
 
@@ -96,7 +105,10 @@ public struct Route<ValidatedData, Content: View>: View {
 
 		if !switchEnvironment.isActive || (switchEnvironment.isActive && !switchEnvironment.isResolved) {
 			do {
-				if let matchInformation = try pathMatcher.match(glob: resolvedGlob, with: navigator.path),
+				if let matchInformation = try pathMatcher.match(
+					glob: resolvedGlob,
+					with: navigator.path,
+					relative: relativePath),
 				   let validated = validator(matchInformation)
 				{
 					validatedData = validated
@@ -128,27 +140,44 @@ public struct Route<ValidatedData, Content: View>: View {
 public extension Route where ValidatedData == RouteInformation {
 	/// - Parameter path: A path glob to test with the current path. See documentation for `Route`.
 	/// - Parameter content: Views to render. An `RouteInformation` is passed containing route parameters.
-	init(path: String = "*", @ViewBuilder content: @escaping (RouteInformation) -> Content) {
+	init(_ path: String = "*", @ViewBuilder content: @escaping (RouteInformation) -> Content) {
 		self.path = path
 		self.validator = { $0 }
 		self.content = content
 	}
 
 	/// - Parameter path: A path glob to test with the current path. See documentation for `Route`.
 	/// - Parameter content: Views to render.
-	init(path: String = "*", @ViewBuilder content: @escaping () -> Content) {
+	init(_ path: String = "*", @ViewBuilder content: @escaping () -> Content) {
 		self.path = path
 		self.validator = { $0 }
 		self.content = { _ in content() }
 	}
 
 	/// - Parameter path: A path glob to test with the current path. See documentation for `Route`.
 	/// - Parameter content: View to render (autoclosure).
-	init(path: String = "*", content: @autoclosure @escaping () -> Content) {
+	init(_ path: String = "*", content: @autoclosure @escaping () -> Content) {
 		self.path = path
 		self.validator = { $0 }
 		self.content = { _ in content() }
 	}
+
+	// MARK: - Deprecated initializers.
+	// These will be completely removed in a future version.
+	@available(*, deprecated, renamed: "init(_:content:)")
+	init(path: String, @ViewBuilder content: @escaping (RouteInformation) -> Content) {
+		self.init(path, content: content)
+	}
+
+	@available(*, deprecated, renamed: "init(_:content:)")
+	init(path: String, @ViewBuilder content: @escaping () -> Content) {
+		self.init(path, content: content)
+	}
+
+	@available(*, deprecated, renamed: "init(_:content:)")
+	init(path: String, content: @autoclosure @escaping () -> Content) {
+		self.init(path, content: content)
+	}
 }
 
 
@@ -161,12 +190,19 @@ public extension Route where ValidatedData == RouteInformation {
 /// This object contains the resolved parameters (variables) of the `Route`'s path, as well as the relative path
 /// for all views inside the hierarchy.
 public final class RouteInformation: ObservableObject {
+	/// The resolved path component of the parent `Route`.
+	public let matchedPath: String
+	
+	/// The current relative path.
 	public let path: String
+
+	/// Resolved parameters of the parent `Route`s path.
 	public let parameters: [String : String]
 
-	init(path: String, parameters: [String : String] = [:]) {
-		self.path = path
+	init(path: String, matchedPath: String, parameters: [String : String] = [:]) {
+		self.matchedPath = matchedPath
 		self.parameters = parameters
+		self.path = path
 	}
 }
 
@@ -245,7 +281,7 @@ final class PathMatcher: ObservableObject {
 		return cached!
 	}
 
-	func match(glob: String, with path: String) throws -> RouteInformation? {
+	func match(glob: String, with path: String, relative: String = "/") throws -> RouteInformation? {
 		let compiled = try compileRegex(glob)
 
 		var nsrange = NSRange(path.startIndex..<path.endIndex, in: path)
@@ -278,7 +314,10 @@ final class PathMatcher: ObservableObject {
 		}
 
 		let resolvedGlob = String(path[range])
+		let matchedPath = String(path[relative.endIndex...])
 
-		return RouteInformation(path: resolvedGlob, parameters: parameterValues)
+		print("resolved: \(resolvedGlob), matched: \(matchedPath), relative: \(relative)")
+
+		return RouteInformation(path: resolvedGlob, matchedPath: matchedPath, parameters: parameterValues)
 	}
 }

Sources/Router.swift

@@ -15,7 +15,7 @@ import SwiftUI
 /// Router {
 /// 	HomeView()
 ///
-/// 	Route(path: "/news") {
+/// 	Route("/news") {
 /// 		NewsHeaderView()
 /// 	}
 /// }

Sources/SwiftUIRouter.docc/Resources/logo.png

@@ -0,0 +1,32 @@
+# ``SwiftUIRouter``
+
+Easy and maintainable app navigation with path based routing for SwiftUI.
+
+![SwiftUI Router logo](logo)
+
+With **SwiftUI Router** you can power your SwiftUI app with path based routing. By utilizing a path based system, navigation in your app becomes more flexible and easier to maintain.
+
+### Additional content 
+- Examples can be found on [Github](https://github.com/frzi/SwiftUIRouter-Examples)
+- [Animating routes](https://github.com/frzi/SwiftUIRouter/blob/main/Docs/AnimatingRoutes.md)
+
+## Topics
+
+### Router
+
+- ``Router``
+
+### Routing
+
+- ``Route``
+- ``SwitchRoutes``
+
+### Navigating
+
+- ``NavLink``
+- ``Navigate``
+
+### Environment Objects
+
+- ``Navigator``
+- ``RouteInformation``

Sources/SwiftUIRouter.docc/SwiftUIRouter.md

@@ -12,10 +12,10 @@ import SwiftUI
 ///
 /// ```swift
 /// SwitchRoutes {
-/// 	Route(path: "settings") {
+/// 	Route("settings") {
 /// 		SettingsView()
 /// 	}
-/// 	Route(path: ":id") { info in
+/// 	Route(":id") { info in
 /// 		ContentView(id: info.params.id!)
 /// 	}
 /// 	Route {