#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/79236386")] #![doc(html_favicon_url = "https://avatars.githubusercontent.com/u/79236386")] #![deny(missing_docs)] //! Dioxus WebSys //! //! ## Overview //! ------------ //! This crate implements a renderer of the Dioxus Virtual DOM for the web browser using WebSys. This web render for //! Dioxus is one of the more advanced renderers, supporting: //! - idle work //! - animations //! - jank-free rendering //! - controlled components //! - hydration //! - and more. //! //! The actual implementation is farily thin, with the heavy lifting happening inside the Dioxus Core crate. //! //! To purview the examples, check of the root Dioxus crate - the examples in this crate are mostly meant to provide //! validation of websys-specific features and not the general use of Dioxus. pub use crate::cfg::Config; use crate::hydration::SuspenseMessage; use dioxus_core::VirtualDom; use dom::WebsysDom; use futures_util::{pin_mut, select, FutureExt, StreamExt}; mod cfg; mod dom; mod events; pub mod launch; mod mutations; pub use events::*; #[cfg(feature = "document")] mod document; #[cfg(feature = "file_engine")] mod file_engine; #[cfg(feature = "document")] mod history; #[cfg(feature = "document")] pub use document::WebDocument; #[cfg(feature = "file_engine")] pub use file_engine::*; #[cfg(all(feature = "devtools", debug_assertions))] mod devtools; mod hydration; #[allow(unused)] pub use hydration::*; /// Runs the app as a future that can be scheduled around the main thread. /// /// Polls futures internal to the VirtualDOM, hence the async nature of this function. /// /// # Example /// /// ```ignore, rust /// let app_fut = dioxus_web::run_with_props(App, RootProps { name: String::from("foo") }); /// wasm_bindgen_futures::spawn_local(app_fut); /// ``` pub async fn run(mut virtual_dom: VirtualDom, web_config: Config) -> ! { #[cfg(feature = "document")] virtual_dom.in_runtime(document::init_document); let runtime = virtual_dom.runtime(); #[cfg(all(feature = "devtools", debug_assertions))] let mut hotreload_rx = devtools::init(runtime.clone()); let should_hydrate = web_config.hydrate; let mut websys_dom = WebsysDom::new(web_config, runtime); let mut hydration_receiver: Option> = None; if should_hydrate { #[cfg(feature = "hydrate")] { websys_dom.skip_mutations = true; // Get the initial hydration data from the client #[wasm_bindgen::prelude::wasm_bindgen(inline_js = r#" export function get_initial_hydration_data() { const decoded = atob(window.initial_dioxus_hydration_data); return Uint8Array.from(decoded, (c) => c.charCodeAt(0)) } export function get_initial_hydration_debug_types() { return window.initial_dioxus_hydration_debug_types; } export function get_initial_hydration_debug_locations() { return window.initial_dioxus_hydration_debug_locations; } "#)] extern "C" { fn get_initial_hydration_data() -> js_sys::Uint8Array; fn get_initial_hydration_debug_types() -> Option>; fn get_initial_hydration_debug_locations() -> Option>; } let hydration_data = get_initial_hydration_data().to_vec(); // If we are running in debug mode, also get the debug types and locations #[cfg(debug_assertions)] let debug_types = get_initial_hydration_debug_types(); #[cfg(not(debug_assertions))] let debug_types = None; #[cfg(debug_assertions)] let debug_locations = get_initial_hydration_debug_locations(); #[cfg(not(debug_assertions))] let debug_locations = None; let server_data = HTMLDataCursor::from_serialized(&hydration_data, debug_types, debug_locations); // If the server serialized an error into the root suspense boundary, throw it into the root scope if let Some(error) = server_data.error() { virtual_dom.in_runtime(|| dioxus_core::ScopeId::APP.throw_error(error)); } with_server_data(server_data, || { virtual_dom.rebuild(&mut websys_dom); }); websys_dom.skip_mutations = false; let rx = websys_dom.rehydrate(&virtual_dom).unwrap(); hydration_receiver = Some(rx); #[cfg(feature = "mounted")] { // Flush any mounted events that were queued up while hydrating websys_dom.flush_queued_mounted_events(); } } #[cfg(not(feature = "hydrate"))] { panic!("Hydration is not enabled. Please enable the `hydrate` feature."); } } else { virtual_dom.rebuild(&mut websys_dom); websys_dom.flush_edits(); } loop { // if virtual dom has nothing, wait for it to have something before requesting idle time // if there is work then this future resolves immediately. #[cfg(all(feature = "devtools", debug_assertions))] let template; #[allow(unused)] let mut hydration_work: Option = None; { let work = virtual_dom.wait_for_work().fuse(); pin_mut!(work); let mut hydration_receiver_iter = futures_util::stream::iter(&mut hydration_receiver) .fuse() .flatten(); let mut rx_hydration = hydration_receiver_iter.select_next_some(); #[cfg(all(feature = "devtools", debug_assertions))] #[allow(unused)] { let mut devtools_next = hotreload_rx.select_next_some(); select! { _ = work => { template = None; }, new_template = devtools_next => { template = Some(new_template); }, hydration_data = rx_hydration => { template = None; #[cfg(feature = "hydrate")] { hydration_work = Some(hydration_data); } }, } } #[cfg(not(all(feature = "devtools", debug_assertions)))] #[allow(unused)] { select! { _ = work => {}, hyd = rx_hydration => { #[cfg(feature = "hydrate")] { hydration_work = Some(hyd); } } } } } #[cfg(all(feature = "devtools", debug_assertions))] if let Some(hr_msg) = template { // Replace all templates dioxus_devtools::apply_changes(&virtual_dom, &hr_msg); if !hr_msg.assets.is_empty() { crate::devtools::invalidate_browser_asset_cache(); } } #[cfg(feature = "hydrate")] if let Some(hydration_data) = hydration_work { websys_dom.rehydrate_streaming(hydration_data, &mut virtual_dom); } // Todo: This is currently disabled because it has a negative impact on response times for events but it could be re-enabled for tasks // Jank free rendering // // 1. wait for the browser to give us "idle" time // 2. During idle time, diff the dom // 3. Stop diffing if the deadline is exceeded // 4. Wait for the animation frame to patch the dom // wait for the mainthread to schedule us in // let deadline = work_loop.wait_for_idle_time().await; // run the virtualdom work phase until the frame deadline is reached virtual_dom.render_immediate(&mut websys_dom); // wait for the animation frame to fire so we can apply our changes // work_loop.wait_for_raf().await; websys_dom.flush_edits(); } }