diff --git a/packages/core/.vscode/settings.json b/packages/core/.vscode/settings.json new file mode 100644 index 000000000..eb230f7ba --- /dev/null +++ b/packages/core/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "rust-analyzer.checkOnSave.allTargets": false +} diff --git a/packages/core/README.md b/packages/core/README.md index e70872410..7659f6713 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -33,34 +33,45 @@ The `dioxus` crate exports the `rsx` macro which transforms a helpful, simpler s First, start with your app: -```rust, ignore +```rust +# use dioxus::core::Mutations; +use dioxus::prelude::*; + +// First, declare a root component fn app(cx: Scope) -> Element { - cx.render(rsx!( div { "hello world" } )) + cx.render(rsx!{ + div { "hello world" } + }) } + +fn main() { + // Next, create a new VirtualDom using this app as the root component. + let mut dom = VirtualDom::new(app); + + // The initial render of the dom will generate a stream of edits for the real dom to apply + let mutations = dom.rebuild(); + + // Somehow, you can apply these edits to the real dom + apply_edits_to_real_dom(mutations); +} + +# fn apply_edits_to_real_dom(mutations: Mutations) {} ``` -Then, we'll want to create a new VirtualDom using this app as the root component. - -```rust, ignore -let mut dom = VirtualDom::new(app); -``` - -To build the app into a stream of mutations, we'll use [`VirtualDom::rebuild`]: - -```rust, ignore -let mutations = dom.rebuild(); - -apply_edits_to_real_dom(mutations); -``` We can then wait for any asynchronous components or pending futures using the `wait_for_work()` method. If we have a deadline, then we can use render_with_deadline instead: +```rust +# #![allow(unused)] +# use dioxus::prelude::*; -```rust, ignore +# use std::time::Duration; +# async fn wait(mut dom: VirtualDom) { // Wait for the dom to be marked dirty internally dom.wait_for_work().await; // Or wait for a deadline and then collect edits -dom.render_with_deadline(tokio::time::sleep(Duration::from_millis(16))); +let mutations = dom.render_with_deadline(tokio::time::sleep(Duration::from_millis(16))); +# } ``` If an event occurs from outside the VirtualDom while waiting for work, then we can cancel the wait using a `select!` block and inject the event. diff --git a/packages/core/src/virtual_dom.rs b/packages/core/src/virtual_dom.rs index 7369386b5..d05dab347 100644 --- a/packages/core/src/virtual_dom.rs +++ b/packages/core/src/virtual_dom.rs @@ -24,7 +24,9 @@ use std::{any::Any, borrow::BorrowMut, cell::Cell, collections::BTreeSet, future /// /// Components are defined as simple functions that take [`Scope`] and return an [`Element`]. /// -/// ```rust, ignore +/// ```rust +/// # use dioxus::prelude::*; +/// /// #[derive(Props, PartialEq)] /// struct AppProps { /// title: String @@ -39,7 +41,17 @@ use std::{any::Any, borrow::BorrowMut, cell::Cell, collections::BTreeSet, future /// /// Components may be composed to make complex apps. /// -/// ```rust, ignore +/// ```rust +/// # #![allow(unused)] +/// # use dioxus::prelude::*; +/// +/// # #[derive(Props, PartialEq)] +/// # struct AppProps { +/// # title: String +/// # } +/// +/// static ROUTES: &str = ""; +/// /// fn App(cx: Scope) -> Element { /// cx.render(rsx!( /// NavBar { routes: ROUTES } @@ -47,12 +59,33 @@ use std::{any::Any, borrow::BorrowMut, cell::Cell, collections::BTreeSet, future /// Footer {} /// )) /// } +/// +/// #[inline_props] +/// fn NavBar(cx: Scope, routes: &'static str) -> Element { +/// cx.render(rsx! { +/// div { "Routes: {routes}" } +/// }) +/// } +/// +/// fn Footer(cx: Scope) -> Element { +/// cx.render(rsx! { div { "Footer" } }) +/// } +/// +/// #[inline_props] +/// fn Title<'a>(cx: Scope<'a>, children: Element<'a>) -> Element { +/// cx.render(rsx! { +/// div { id: "title", children } +/// }) +/// } /// ``` /// /// To start an app, create a [`VirtualDom`] and call [`VirtualDom::rebuild`] to get the list of edits required to /// draw the UI. /// -/// ```rust, ignore +/// ```rust +/// # use dioxus::prelude::*; +/// # fn App(cx: Scope) -> Element { cx.render(rsx! { div {} }) } +/// /// let mut vdom = VirtualDom::new(App); /// let edits = vdom.rebuild(); /// ```