From cd087347f7d15570b2a8f9a245854200474ad701 Mon Sep 17 00:00:00 2001
From: Barney Carroll <barney.carroll@gmail.com>
Date: Thu, 15 Apr 2021 19:03:10 +0100
Subject: [PATCH] Document route resolution cancellation, fixes #1759

---
 docs/route.md | 46 +++++++++++++++++++++-------------------------
 1 file changed, 21 insertions(+), 25 deletions(-)

diff --git a/docs/route.md b/docs/route.md
index 454133c6..aa835fc2 100644
--- a/docs/route.md
+++ b/docs/route.md
@@ -26,7 +26,8 @@
 	- [Preloading data](#preloading-data)
 	- [Code splitting](#code-splitting)
 	- [Typed routes](#typed-routes)
-	- [Hidden routes](#typed-routes)
+	- [Hidden routes](#hidden-routes)
+	- [Route cancellation / blocking](#route-cancellation--blocking)
 - [Third-party integration](#third-party-integration)
 
 ---
@@ -856,6 +857,25 @@ m.route(document.body, "/", {
 
 ---
 
+### Route cancellation / blocking
+
+RouteResolver `onmatch` can prevent navigation away from the current route by returning a promise that never resolves:
+
+```javascript
+var blocked = true
+
+m.route(document.body, "/", {
+	"/": {
+		onmatch: function(args) {
+			if (blocked)
+				return new Promise(function() {})
+		},
+	},
+})
+```
+
+---
+
 ### Third-party integration
 
 In certain situations, you may find yourself needing to interoperate with another framework like React. Here's how you do it:
@@ -907,27 +927,3 @@ Vue.component("my-child", {
 	},
 })
 ```
-
-Technically, there's nothing stopping you from even doing it in a Mithril component, even.
-
-```javascript
-// Don't do this. Use a proper global layout component for each route instead,
-// passing your child vnode/component in the attributes or children.
-function Child() {
-	return {
-		oncreate: function(vnode) {
-			m.route(vnode.dom, "/", {
-				// ...
-			})
-		},
-
-		onremove: function() {
-			m.mount(vnode.dom, null)
-		},
-
-		view: function() {
-			return m("div")
-		},
-	}
-}
-```