restore navigator

packages/router/src/contexts/navigator.rs

@@ -0,0 +1,53 @@
+use crate::prelude::{ExternalNavigationFailure, GenericRouterContext, NavigationTarget, Routable};
+
+/// A view into the navigation state of a router.
+#[derive(Clone)]
+pub struct GenericNavigator<R: Routable>(pub(crate) GenericRouterContext<R>);
+
+impl<R: Routable> GenericNavigator<R> {
+    /// Check whether there is a previous page to navigate back to.
+    #[must_use]
+    pub fn can_go_back(&self) -> bool {
+        self.0.can_go_back()
+    }
+
+    /// Check whether there is a future page to navigate forward to.
+    #[must_use]
+    pub fn can_go_forward(&self) -> bool {
+        self.0.can_go_forward()
+    }
+
+    /// Go back to the previous location.
+    ///
+    /// Will fail silently if there is no previous location to go to.
+    pub fn go_back(&self) {
+        self.0.go_back();
+    }
+
+    /// Go back to the next location.
+    ///
+    /// Will fail silently if there is no next location to go to.
+    pub fn go_forward(&self) {
+        self.0.go_forward();
+    }
+
+    /// Push a new location.
+    ///
+    /// The previous location will be available to go back to.
+    pub fn push(
+        &self,
+        target: impl Into<NavigationTarget<R>>,
+    ) -> Option<ExternalNavigationFailure> {
+        self.0.push(target)
+    }
+
+    /// Replace the current location.
+    ///
+    /// The previous location will **not** be available to go back to.
+    pub fn replace(
+        &self,
+        target: impl Into<NavigationTarget<R>>,
+    ) -> Option<ExternalNavigationFailure> {
+        self.0.replace(target)
+    }
+}

packages/router/src/hooks/use_navigator.rs

@@ -0,0 +1,62 @@
+use dioxus::prelude::ScopeState;
+
+use crate::{
+    prelude::{GenericNavigator, GenericRouterContext},
+    routable::Routable,
+};
+
+/// A hook that provides access to the navigator to change the router history. Unlike [`use_router`], this hook will not cause a rerender when the current route changes
+///
+/// > The Routable macro will define a version of this hook with an explicit type.
+///
+/// ```rust
+/// # use dioxus::prelude::*;
+/// # use dioxus_router::prelude::*;
+/// # use serde::{Deserialize, Serialize};
+/// #[derive(Clone, Serialize, Deserialize, Routable)]
+/// enum Route {
+///     #[route("/")]
+///     Index {},
+///     #[route("/:id")]
+///     Dynamic { id: usize },
+/// }
+///
+/// fn App(cx: Scope) -> Element {
+///     render! {
+///         Router {}
+///     }
+/// }
+///
+/// #[inline_props]
+/// fn Index(cx: Scope) -> Element {
+///     let navigator = use_navigator(&cx);
+///
+///     render! {
+///         button {
+///             onclick: move |_| { navigator.push(Route::Dynamic { id: 1234 }); },
+///             "Go to /1234"
+///         }
+///     }
+/// }
+///
+/// #[inline_props]
+/// fn Dynamic(cx: Scope, id: usize) -> Element {
+///     render! {
+///         p {
+///             "Current ID: {id}"
+///         }
+///     }
+/// }
+///
+/// # let mut vdom = VirtualDom::new(App);
+/// # let _ = vdom.rebuild();
+/// ```
+pub fn use_generic_navigator<R: Routable + Clone>(cx: &ScopeState) -> &GenericNavigator<R> {
+    &*cx.use_hook(|| {
+        let router = cx
+            .consume_context::<GenericRouterContext<R>>()
+            .expect("Must be called in a descendant of a Router component");
+
+        GenericNavigator(router)
+    })
+}

packages/router/src/hooks/use_route.rs

@@ -5,6 +5,8 @@ use crate::utils::use_router_internal::use_router_internal;
 
 /// A hook that provides access to information about the current routing location.
 ///
+/// > The Routable macro will define a version of this hook with an explicit type.
+///
 /// # Return values
 /// - None, when not called inside a [`GenericRouter`] component.
 /// - Otherwise the current route.

packages/router/src/hooks/use_router.rs

@@ -5,50 +5,7 @@ use crate::{
     utils::use_router_internal::use_router_internal,
 };
 
-/// A hook that provides access to information about the router. The Router will define a version of this hook with an explicit type.
-///
-/// ```rust
-/// # use dioxus::prelude::*;
-/// # use dioxus_router::prelude::*;
-/// # use serde::{Deserialize, Serialize};
-/// #[derive(Clone, Serialize, Deserialize, Routable)]
-/// enum Route {
-///     #[route("/")]
-///     Index {},
-///     #[route("/:id")]
-///     Dynamic { id: usize },
-/// }
-///
-/// fn App(cx: Scope) -> Element {
-///     render! {
-///         Router {}
-///     }
-/// }
-///
-/// #[inline_props]
-/// fn Index(cx: Scope) -> Element {
-///     let router = use_router(&cx);
-///
-///     render! {
-///         button {
-///             onclick: move |_| { router.push(Route::Dynamic { id: 1234 }); },
-///             "Go to /1234"
-///         }
-///     }
-/// }
-///
-/// #[inline_props]
-/// fn Dynamic(cx: Scope, id: usize) -> Element {
-///     render! {
-///         p {
-///             "Current ID: {id}"
-///         }
-///     }
-/// }
-///
-/// # let mut vdom = VirtualDom::new(App);
-/// # let _ = vdom.rebuild();
-/// ```
+/// A hook that provides access to information about the router.
 pub fn use_generic_router<R: Routable + Clone>(cx: &ScopeState) -> &GenericRouterContext<R> {
     use_router_internal(cx)
         .as_ref()

packages/router/src/lib.rs

@@ -25,9 +25,11 @@ mod components {
 }
 
 mod contexts {
+    pub(crate) mod navigator;
     pub(crate) mod outlet;
     pub(crate) mod router;
-    pub use router::*;
+    pub use navigator::*;
+    pub(crate) use router::*;
 }
 
 mod router_cfg;
@@ -37,10 +39,13 @@ mod history;
 /// Hooks for interacting with the router in components.
 mod hooks {
     mod use_router;
-    pub use use_router::*;
+    pub(crate) use use_router::*;
 
     mod use_route;
     pub use use_route::*;
+
+    mod use_navigator;
+    pub use use_navigator::*;
 }
 
 /// A collection of useful items most applications might need.