docs: added a hint for a common error when using use_navigate (#1063)

router/src/hooks.rs

@@ -76,6 +76,23 @@ pub fn use_resolved_path(
 }
 
 /// Returns a function that can be used to navigate to a new route.
+///
+/// ## Panics
+/// `use_navigate` can sometimes panic due to a `BorrowMut` runtime error
+/// if it is called immediately during routing/rendering. In this case, you should
+/// wrap it in [`request_animation_frame`](leptos::request_animation_frame)
+/// to delay it until that routing process is complete.
+/// ```rust
+/// # use leptos::{request_animation_frame,create_scope,create_runtime};
+/// # create_scope(create_runtime(), |cx| {
+/// # if false { // can't actually navigate, no <Router/>
+/// let navigate = leptos_router::use_navigate(cx);
+/// request_animation_frame(move || {
+///     _ = navigate("/", Default::default());
+/// });
+/// # }
+/// # });
+/// ```
 pub fn use_navigate(
     cx: Scope,
 ) -> impl Fn(&str, NavigateOptions) -> Result<(), NavigationError> {
@@ -84,7 +101,7 @@ pub fn use_navigate(
         Rc::clone(&router.inner).navigate_from_route(to, &options)
     }
 }
-
+///
 /// Returns a signal that tells you whether you are currently navigating backwards.
 pub(crate) fn use_is_back_navigation(cx: Scope) -> ReadSignal<bool> {
     let router = use_router(cx);