swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update doc examples

Browse Source
This commit is contained in:
Evan Almloff committed 2023-05-31 15:51:26 -05:00
1 parent 35befa1784
commit 09cabe4e8b
22 files changed
+474 -518
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/router/src/history/memory.rs
+21 -151
View File
@@ -18,16 +18,31 @@ where
/// Create a [`MemoryHistory`] starting at `path`.
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::with_initial_path("/some/path").unwrap();
/// assert_eq!(history.current_path(), "/some/path");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
///
/// let mut history = MemoryHistory::<Route>::with_initial_path("/").unwrap();
/// assert_eq!(history.current_route(), Route::Index {});
/// assert_eq!(history.can_go_back(), false);
/// ```
pub fn with_initial_path(path: impl Into<String>) -> Result<Self, <R as FromStr>::Err> {
let path = path.into();
pub fn with_initial_path(path: impl AsRef<str>) -> Result<Self, <R as FromStr>::Err> {
let path = path.as_ref();
Ok(Self {
current: R::from_str(&path)?,
current: R::from_str(path)?,
..Default::default()
})
}
@@ -83,148 +98,3 @@ impl<R: Routable> HistoryProvider<R> for MemoryHistory<R> {
self.current = path;
}
}
// #[cfg(test)]
// mod tests {
// use super::*;
// #[test]
// fn default() {
// let mem = MemoryHistory::default();
// assert_eq!(mem.current, Url::parse(INITIAL_URL).unwrap());
// assert_eq!(mem.history, Vec::<String>::new());
// assert_eq!(mem.future, Vec::<String>::new());
// }
// #[test]
// fn with_initial_path() {
// let mem = MemoryHistory::with_initial_path("something").unwrap();
// assert_eq!(
// mem.current,
// Url::parse(&format!("{INITIAL_URL}something")).unwrap()
// );
// assert_eq!(mem.history, Vec::<String>::new());
// assert_eq!(mem.future, Vec::<String>::new());
// }
// #[test]
// fn with_initial_path_with_leading_slash() {
// let mem = MemoryHistory::with_initial_path("/something").unwrap();
// assert_eq!(
// mem.current,
// Url::parse(&format!("{INITIAL_URL}something")).unwrap()
// );
// assert_eq!(mem.history, Vec::<String>::new());
// assert_eq!(mem.future, Vec::<String>::new());
// }
// #[test]
// fn can_go_back() {
// let mut mem = MemoryHistory::default();
// assert!(!mem.can_go_back());
// mem.push(String::from("/test"));
// assert!(mem.can_go_back());
// }
// #[test]
// fn go_back() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("/test"));
// mem.go_back();
// assert_eq!(mem.current, Url::parse(INITIAL_URL).unwrap());
// assert!(mem.history.is_empty());
// assert_eq!(mem.future, vec![format!("{INITIAL_URL}test")]);
// }
// #[test]
// fn can_go_forward() {
// let mut mem = MemoryHistory::default();
// assert!(!mem.can_go_forward());
// mem.push(String::from("/test"));
// mem.go_back();
// assert!(mem.can_go_forward());
// }
// #[test]
// fn go_forward() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("/test"));
// mem.go_back();
// mem.go_forward();
// assert_eq!(
// mem.current,
// Url::parse(&format!("{INITIAL_URL}test")).unwrap()
// );
// assert_eq!(mem.history, vec![INITIAL_URL.to_string()]);
// assert!(mem.future.is_empty());
// }
// #[test]
// fn push() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("/test"));
// assert_eq!(
// mem.current,
// Url::parse(&format!("{INITIAL_URL}test")).unwrap()
// );
// assert_eq!(mem.history, vec![INITIAL_URL.to_string()]);
// assert!(mem.future.is_empty());
// }
// #[test]
// #[should_panic = r#"cannot navigate to paths starting with "//": //test"#]
// #[cfg(debug_assertions)]
// fn push_debug() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("//test"));
// }
// #[test]
// #[cfg(not(debug_assertions))]
// fn push_release() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("//test"));
// assert_eq!(mem.current, Url::parse(INITIAL_URL).unwrap());
// assert!(mem.history.is_empty())
// }
// #[test]
// fn replace() {
// let mut mem = MemoryHistory::default();
// mem.push(String::from("/test"));
// mem.push(String::from("/other"));
// mem.go_back();
// mem.replace(String::from("/replace"));
// assert_eq!(
// mem.current,
// Url::parse(&format!("{INITIAL_URL}replace")).unwrap()
// );
// assert_eq!(mem.history, vec![INITIAL_URL.to_string()]);
// assert_eq!(mem.future, vec![format!("{INITIAL_URL}other")]);
// }
// #[test]
// #[should_panic = r#"cannot navigate to paths starting with "//": //test"#]
// #[cfg(debug_assertions)]
// fn replace_debug() {
// let mut mem = MemoryHistory::default();
// mem.replace(String::from("//test"));
// }
// #[test]
// #[cfg(not(debug_assertions))]
// fn replace_release() {
// let mut mem = MemoryHistory::default();
// mem.replace(String::from("//test"));
// assert_eq!(mem.current, Url::parse(INITIAL_URL).unwrap());
// }
// }
packages/router/src/history/mod.rs
+129 -35
View File
@@ -31,7 +31,7 @@ pub(crate) mod web_scroll;
/// An integration with some kind of navigation history.
///
/// Depending on your use case, your implementation may deviate from the described procedure. This
/// is fine, as long as both `current_path` and `current_query` match the described format.
/// is fine, as long as both `current_route` and `current_query` match the described format.
///
/// However, you should document all deviations. Also, make sure the navigation is user-friendly.
/// The described behaviors are designed to mimic a web browser, which most users should already
@@ -42,12 +42,26 @@ pub trait HistoryProvider<R: Routable> {
/// **Must start** with `/`. **Must _not_ contain** the prefix.
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// assert_eq!(history.current_path(), "/");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.current_route().to_string(), "/");
///
/// history.push(String::from("/path"));
/// assert_eq!(history.current_path(), "/path");
/// history.push(Route::OtherPage {});
/// assert_eq!(history.current_route().to_string(), "/some-other-page");
/// ```
#[must_use]
fn current_route(&self) -> R;
@@ -68,11 +82,21 @@ pub trait HistoryProvider<R: Routable> {
/// If a [`HistoryProvider`] cannot know this, it should return [`true`].
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.can_go_back(), false);
///
/// history.push(String::from("/some-other-page"));
/// history.push(Route::Index {});
/// assert_eq!(history.can_go_back(), true);
/// ```
#[must_use]
@@ -86,18 +110,32 @@ pub trait HistoryProvider<R: Routable> {
/// might be called, even if `can_go_back` returns [`false`].
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// assert_eq!(history.current_path(), "/");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.current_route().to_string(), "/");
///
/// history.go_back();
/// assert_eq!(history.current_path(), "/");
/// assert_eq!(history.current_route().to_string(), "/");
///
/// history.push(String::from("/some-other-page"));
/// assert_eq!(history.current_path(), "/some-other-page");
/// history.push(Route::OtherPage {});
/// assert_eq!(history.current_route().to_string(), "/some-other-page");
///
/// history.go_back();
/// assert_eq!(history.current_path(), "/");
/// assert_eq!(history.current_route().to_string(), "/");
/// ```
fn go_back(&mut self);
@@ -106,11 +144,25 @@ pub trait HistoryProvider<R: Routable> {
/// If a [`HistoryProvider`] cannot know this, it should return [`true`].
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.can_go_forward(), false);
///
/// history.push(String::from("/some-other-page"));
/// history.push(Route::OtherPage {});
/// assert_eq!(history.can_go_forward(), false);
///
/// history.go_back();
@@ -127,16 +179,30 @@ pub trait HistoryProvider<R: Routable> {
/// might be called, even if `can_go_forward` returns [`false`].
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// history.push(String::from("/some-other-page"));
/// assert_eq!(history.current_path(), "/some-other-page");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// history.push(Route::OtherPage {});
/// assert_eq!(history.current_route(), Route::OtherPage {});
///
/// history.go_back();
/// assert_eq!(history.current_path(), "/");
/// assert_eq!(history.current_route(), Route::Index {});
///
/// history.go_forward();
/// assert_eq!(history.current_path(), "/some-other-page");
/// assert_eq!(history.current_route(), Route::OtherPage {});
/// ```
fn go_forward(&mut self);
@@ -148,12 +214,26 @@ pub trait HistoryProvider<R: Routable> {
/// 3. Clear the navigation future.
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// assert_eq!(history.current_path(), "/");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.current_route(), Route::Index {});
///
/// history.push(String::from("/some-other-page"));
/// assert_eq!(history.current_path(), "/some-other-page");
/// history.push(Route::OtherPage {});
/// assert_eq!(history.current_route(), Route::OtherPage {});
/// assert!(history.can_go_back());
/// ```
fn push(&mut self, route: R);
@@ -165,12 +245,26 @@ pub trait HistoryProvider<R: Routable> {
/// untouched.
///
/// ```rust
/// # use dioxus_router_core::history::{HistoryProvider, MemoryHistory};
/// let mut history = MemoryHistory::default();
/// assert_eq!(history.current_path(), "/");
/// # use dioxus_router::history::{HistoryProvider, MemoryHistory};
/// # use dioxus_router::prelude::*;
/// # use serde::{Deserialize, Serialize};
/// # use dioxus::prelude::*;
/// # #[inline_props]
/// # fn Index(cx: Scope) -> Element { todo!() }
/// # #[inline_props]
/// # fn OtherPage(cx: Scope) -> Element { todo!() }
/// #[derive(Clone, Serialize, Deserialize, Routable, Debug, PartialEq)]
/// enum Route {
/// #[route("/")]
/// Index {},
/// #[route("/some-other-page")]
/// OtherPage {},
/// }
/// let mut history = MemoryHistory::<Route>::default();
/// assert_eq!(history.current_route(), Route::Index {});
///
/// history.replace(String::from("/some-other-page"));
/// assert_eq!(history.current_path(), "/some-other-page");
/// history.replace(Route::OtherPage {});
/// assert_eq!(history.current_route(), Route::OtherPage {});
/// assert!(!history.can_go_back());
/// ```
fn replace(&mut self, path: R);
packages/router/src/history/web.rs
+1 -3
View File
@@ -28,7 +28,7 @@ struct WebHistoryState<R> {
scroll: ScrollPosition,
}
/// A [`HistoryProvider`] that integrates with a browser via the [History API].
/// A [`HistoryProvider`] that integrates with a browser via the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
///
/// # Prefix
/// This [`HistoryProvider`] supports a prefix, which can be used for web apps that aren't located
@@ -40,8 +40,6 @@ struct WebHistoryState<R> {
///
/// Application developers are responsible for not rendering the router if the prefix is not present
/// in the URL. Otherwise, if a router navigation is triggered, the prefix will be added.
///
/// [History API]: https://developer.mozilla.org/en-US/docs/Web/API/History_API
pub struct WebHistory<R: Serialize + DeserializeOwned + Routable> {
do_scroll_restoration: bool,
history: History,
packages/router/src/history/web_hash.rs
+1 -3
View File
@@ -17,10 +17,8 @@ const INITIAL_URL: &str = "dioxus-router-core://initial_url.invalid/";
///
/// Early web applications used the hash to store the current path because there was no other way
/// for them to interact with the history without triggering a browser navigation, as the
/// [History API] did not yet exist. While this implementation could have been written that way, it
/// [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) did not yet exist. While this implementation could have been written that way, it
/// was not, because no browser supports WebAssembly without the [History API].
///
/// [History API]: https://developer.mozilla.org/en-US/docs/Web/API/History_API
pub struct WebHashHistory<R: Serialize + DeserializeOwned> {
do_scroll_restoration: bool,
history: History,