add rewritten router book and fix features code

docs/router/src/features/navigation/programmatic.md

@@ -0,0 +1,80 @@
+# Programmatic Navigation
+
+Sometimes we want our application to navigate to another page without having the
+user click on a link. This is called programmatic navigation.
+
+## Acquiring a [`Navigator`]
+To use programmatic navigation, we first have to acquire a [`Navigator`]. For
+that purpose we can use the [`use_navigate`] hook.
+
+```rust,no_run
+# // Hidden lines (like this one) make the documentation tests work.
+# extern crate dioxus;
+use dioxus::prelude::*;
+# extern crate dioxus_router;
+use dioxus_router::prelude::*;
+
+fn Content(cx: Scope) -> Element {
+    let nav = use_navigate(&cx).expect("called inside a router");
+
+    // ...
+    # unimplemented!()
+}
+```
+
+## Triggering a Navigation
+We can use the [`Navigator`] to trigger four different kinds of navigation:
+- `push` will navigate to the target. It works like a regular anchor tag.
+- `replace` works like `push`, except that it replaces the current history entry
+  instead of adding a new one. This means the prior page cannot be restored with
+  the browsers back button.
+- `Go back` works like the browsers back button.
+- `Go forward` works like the browsers forward button (the opposite of the back
+  button).
+
+```rust,no_run
+# // Hidden lines (like this one) make the documentation tests work.
+# extern crate dioxus;
+# use dioxus::prelude::*;
+# extern crate dioxus_router;
+# use dioxus_router::prelude::*;
+#
+fn Content(cx: Scope) -> Element {
+    let nav = use_navigate(&cx).expect("called inside a router");
+
+    // push
+    nav.push("/target");
+
+    // replace
+    nav.replace("/target");
+
+    // go back
+    nav.go_back();
+
+    // go forward
+    nav.go_forward();
+
+    // ...
+    # unimplemented!()
+}
+```
+
+You might have noticed that, like [`Link`], the [`Navigator`]s `push` and
+`replace` functions take a [`NavigationTarget`]. This means we can use
+[`Internal`], [`Named`] and [`External`].
+
+## External Navigation Targets
+Unlike a [`Link`], the [`Navigator`] cannot rely on the browser (or webview) to
+handle navigation to external targets via a generated anchor element.
+
+This means, that under certain conditions, navigation to external targets can
+fail. See the chapter about
+[external navigation failures](../failures/external.md) for more details.
+
+[`External`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.External
+[`Internal`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.Internal
+[`Link`]: https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html
+[`Named`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.Named
+[`NavigationTarget`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html
+[`Navigator`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/hooks/struct.Navigator.html
+[`use_navigate`]: https://docs.rs/dioxus-router/latest/dioxus_router/hooks/fn.use_navigate.html