dioxus/packages/core/src/virtual_dom.rs

//! # VirtualDOM Implementation for Rust
//! This module provides the primary mechanics to create a hook-based, concurrent VDOM for Rust.
//!
//! In this file, multiple items are defined. This file is big, but should be documented well to
//! navigate the innerworkings of the Dom. We try to keep these main mechanics in this file to limit
//! the possible exposed API surface (keep fields private). This particular implementation of VDOM
//! is extremely efficient, but relies on some unsafety under the hood to do things like manage
//! micro-heaps for components. We are currently working on refactoring the safety out into safe(r)
//! abstractions, but current tests (MIRI and otherwise) show no issues with the current implementation.
//!
//! Included is:
//! - The [`VirtualDom`] itself
//! - The [`Scope`] object for mangning component lifecycle
//! - The [`ActiveFrame`] object for managing the Scope`s microheap
//! - The [`Context`] object for exposing VirtualDOM API to components
//! - The [`NodeFactory`] object for lazyily exposing the `Context` API to the nodebuilder API
//! - The [`Hook`] object for exposing state management in components.
//!
//! This module includes just the barebones for a complete VirtualDOM API.
//! Additional functionality is defined in the respective files.

use crate::{arena::SharedResources, innerlude::*};

use std::any::Any;

use std::any::TypeId;
use std::cell::RefCell;
use std::pin::Pin;

/// An integrated virtual node system that progresses events and diffs UI trees.
/// Differences are converted into patches which a renderer can use to draw the UI.
///
///
///
///
///
///
///
pub struct VirtualDom {
    /// All mounted components are arena allocated to make additions, removals, and references easy to work with
    /// A generational arena is used to re-use slots of deleted scopes without having to resize the underlying arena.
    ///
    /// This is wrapped in an UnsafeCell because we will need to get mutable access to unique values in unique bump arenas
    /// and rusts's guartnees cannot prove that this is safe. We will need to maintain the safety guarantees manually.
    pub shared: SharedResources,

    /// The index of the root component
    /// Should always be the first (gen=0, id=0)
    pub base_scope: ScopeId,

    pub triggers: RefCell<Vec<EventTrigger>>,

    // for managing the props that were used to create the dom
    #[doc(hidden)]
    _root_prop_type: std::any::TypeId,

    #[doc(hidden)]
    _root_props: std::pin::Pin<Box<dyn std::any::Any>>,
}

// ======================================
// Public Methods for the VirtualDom
// ======================================
impl VirtualDom {
    /// Create a new instance of the Dioxus Virtual Dom with no properties for the root component.
    ///
    /// This means that the root component must either consumes its own context, or statics are used to generate the page.
    /// The root component can access things like routing in its context.
    ///
    /// As an end-user, you'll want to use the Renderer's "new" method instead of this method.
    /// Directly creating the VirtualDOM is only useful when implementing a new renderer.
    ///
    ///
    /// ```ignore
    /// // Directly from a closure
    ///
    /// let dom = VirtualDom::new(|cx| cx.render(rsx!{ div {"hello world"} }));
    ///
    /// // or pass in...
    ///
    /// let root = |cx| {
    ///     cx.render(rsx!{
    ///         div {"hello world"}
    ///     })
    /// }
    /// let dom = VirtualDom::new(root);
    ///
    /// // or directly from a fn
    ///
    /// fn Example(cx: Context<()>) -> DomTree  {
    ///     cx.render(rsx!{ div{"hello world"} })
    /// }
    ///
    /// let dom = VirtualDom::new(Example);
    /// ```
    pub fn new(root: FC<()>) -> Self {
        Self::new_with_props(root, ())
    }

    /// Start a new VirtualDom instance with a dependent cx.
    /// Later, the props can be updated by calling "update" with a new set of props, causing a set of re-renders.
    ///
    /// This is useful when a component tree can be driven by external state (IE SSR) but it would be too expensive
    /// to toss out the entire tree.
    ///
    /// ```ignore
    /// // Directly from a closure
    ///
    /// let dom = VirtualDom::new(|cx| cx.render(rsx!{ div {"hello world"} }));
    ///
    /// // or pass in...
    ///
    /// let root = |cx| {
    ///     cx.render(rsx!{
    ///         div {"hello world"}
    ///     })
    /// }
    /// let dom = VirtualDom::new(root);
    ///
    /// // or directly from a fn
    ///
    /// fn Example(cx: Context, props: &SomeProps) -> VNode  {
    ///     cx.render(rsx!{ div{"hello world"} })
    /// }
    ///
    /// let dom = VirtualDom::new(Example);
    /// ```
    pub fn new_with_props<P: Properties + 'static>(root: FC<P>, root_props: P) -> Self {
        let components = SharedResources::new();

        let root_props: Pin<Box<dyn Any>> = Box::pin(root_props);
        let props_ptr = root_props.as_ref().downcast_ref::<P>().unwrap() as *const P;

        let link = components.clone();

        let base_scope = components.insert_scope_with_key(move |myidx| {
            let caller = NodeFactory::create_component_caller(root, props_ptr as *const _);
            Scope::new(caller, myidx, None, 0, &[], link)
        });

        Self {
            base_scope,
            _root_props: root_props,
            shared: components,
            triggers: Default::default(),
            _root_prop_type: TypeId::of::<P>(),
        }
    }

    pub fn launch_in_place(root: FC<()>) -> Self {
        let mut s = Self::new(root);
        s.rebuild_in_place();
        s
    }

    /// Creates a new virtualdom and immediately rebuilds it in place, not caring about the RealDom to write into.
    ///
    pub fn launch_with_props_in_place<P: Properties + 'static>(root: FC<P>, root_props: P) -> Self {
        let mut s = Self::new_with_props(root, root_props);
        s.rebuild_in_place();
        s
    }

    /// Rebuilds the VirtualDOM from scratch, but uses a "dummy" RealDom.
    ///
    /// Used in contexts where a real copy of the  structure doesn't matter, and the VirtualDOM is the source of truth.
    ///
    /// ## Why?
    ///
    /// This method uses the `DebugDom` under the hood - essentially making the VirtualDOM's diffing patches a "no-op".
    ///
    /// SSR takes advantage of this by using Dioxus itself as the source of truth, and rendering from the tree directly.
    pub fn rebuild_in_place(&mut self) -> Result<()> {
        let mut realdom = DebugDom::new();
        let mut edits = Vec::new();
        self.rebuild(&mut realdom, &mut edits)
    }

    /// Performs a *full* rebuild of the virtual dom, returning every edit required to generate the actual dom rom scratch
    ///
    /// The diff machine expects the RealDom's stack to be the root of the application
    pub fn rebuild<'s>(
        &'s mut self,
        realdom: &'_ mut dyn RealDom<'s>,
        edits: &'_ mut Vec<DomEdit<'s>>,
    ) -> Result<()> {
        let mut diff_machine = DiffMachine::new(edits, realdom, self.base_scope, &self.shared);

        let cur_component = diff_machine
            .get_scope_mut(&self.base_scope)
            .expect("The base scope should never be moved");

        // We run the component. If it succeeds, then we can diff it and add the changes to the dom.
        if cur_component.run_scope().is_ok() {
            let meta = diff_machine.create(cur_component.next_frame());
            diff_machine.edits.append_children(meta.added_to_stack);
        } else {
            // todo: should this be a hard error?
            log::warn!(
                "Component failed to run succesfully during rebuild.
                This does not result in a failed rebuild, but indicates a logic failure within your app."
            );
        }

        Ok(())
    }

    ///
    ///
    ///
    ///
    ///
    pub fn queue_event(&self, trigger: EventTrigger) {
        let mut triggers = self.triggers.borrow_mut();
        triggers.push(trigger);
    }

    /// This method is the most sophisticated way of updating the virtual dom after an external event has been triggered.
    ///  
    /// Given a synthetic event, the component that triggered the event, and the index of the callback, this runs the virtual
    /// dom to completion, tagging components that need updates, compressing events together, and finally emitting a single
    /// change list.
    ///
    /// If implementing an external renderer, this is the perfect method to combine with an async event loop that waits on
    /// listeners, something like this:
    ///
    /// ```ignore
    /// while let Ok(event) = receiver.recv().await {
    ///     let edits = self.internal_dom.progress_with_event(event)?;
    ///     for edit in &edits {
    ///         patch_machine.handle_edit(edit);
    ///     }
    /// }
    /// ```
    ///
    /// Note: this method is not async and does not provide suspense-like functionality. It is up to the renderer to provide the
    /// executor and handlers for suspense as show in the example.
    ///
    /// ```ignore
    /// let (sender, receiver) = channel::new();
    /// sender.send(EventTrigger::start());
    ///
    /// let mut dom = VirtualDom::new();
    /// dom.suspense_handler(|event| sender.send(event));
    ///
    /// while let Ok(diffs) = dom.progress_with_event(receiver.recv().await) {
    ///     render(diffs);
    /// }
    ///
    /// ```
    //
    // Developer notes:
    // ----
    // This method has some pretty complex safety guarantees to uphold.
    // We interact with bump arenas, raw pointers, and use UnsafeCell to get a partial borrow of the arena.
    // The final EditList has edits that pull directly from the Bump Arenas which add significant complexity
    // in crafting a 100% safe solution with traditional lifetimes. Consider this method to be internally unsafe
    // but the guarantees provide a safe, fast, and efficient abstraction for the VirtualDOM updating framework.
    //
    // A good project would be to remove all unsafe from this crate and move the unsafety into safer abstractions.
    pub async fn progress_with_event<'a, 's>(
        &'s mut self,
        realdom: &'a mut dyn RealDom<'s>,
        edits: &'a mut Vec<DomEdit<'s>>,
    ) -> Result<()> {
        let trigger = self.triggers.borrow_mut().pop().expect("failed");

        let mut diff_machine = DiffMachine::new(edits, realdom, trigger.originator, &self.shared);

        match &trigger.event {
            // Nothing yet
            VirtualEvent::AsyncEvent { .. } => {}

            // Suspense Events! A component's suspended node is updated
            VirtualEvent::SuspenseEvent { hook_idx, domnode } => {
                // Safety: this handler is the only thing that can mutate shared items at this moment in tim
                let scope = diff_machine.get_scope_mut(&trigger.originator).unwrap();

                // safety: we are sure that there are no other references to the inner content of suspense hooks
                let hook = unsafe { scope.hooks.get_mut::<SuspenseHook>(*hook_idx) }.unwrap();

                let cx = Context { scope, props: &() };
                let scx = SuspendedContext { inner: cx };

                // generate the new node!
                let nodes: Option<VNode<'s>> = (&hook.callback)(scx);
                match nodes {
                    None => {
                        log::warn!("Suspense event came through, but there was no mounted node to update >:(");
                    }
                    Some(nodes) => {
                        let nodes = scope.cur_frame().bump.alloc(nodes);

                        // push the old node's root onto the stack
                        let real_id = domnode.get().ok_or(Error::NotMounted)?;
                        diff_machine.edits.push_root(real_id);

                        // push these new nodes onto the diff machines stack
                        let meta = diff_machine.create(&*nodes);

                        // replace the placeholder with the new nodes we just pushed on the stack
                        diff_machine.edits.replace_with(meta.added_to_stack);
                    }
                }
            }

            // This is the "meat" of our cooperative scheduler
            // As updates flow in, we re-evalute the event queue and decide if we should be switching the type of work
            //
            // We use the reconciler to request new IDs and then commit/uncommit the IDs when the scheduler is finished
            _ => {
                diff_machine
                    .get_scope_mut(&trigger.originator)
                    .map(|f| f.call_listener(trigger));

                // Now, there are events in the queue
                let mut updates = self.shared.borrow_queue();

                // Order the nodes by their height, we want the nodes with the smallest depth on top
                // This prevents us from running the same component multiple times
                updates.sort_unstable();

                log::debug!("There are: {:#?} updates to be processed", updates.len());

                // Iterate through the triggered nodes (sorted by height) and begin to diff them
                for update in updates.drain(..) {
                    log::debug!("Running updates for: {:#?}", update);

                    // Make sure this isn't a node we've already seen, we don't want to double-render anything
                    // If we double-renderer something, this would cause memory safety issues
                    if diff_machine.seen_nodes.contains(&update.idx) {
                        continue;
                    }

                    // Now, all the "seen nodes" are nodes that got notified by running this listener
                    diff_machine.seen_nodes.insert(update.idx.clone());

                    // Start a new mutable borrow to components
                    // We are guaranteeed that this scope is unique because we are tracking which nodes have modified in the diff machine
                    let cur_component = diff_machine
                        .get_scope_mut(&update.idx)
                        .expect("Failed to find scope or borrow would be aliasing");

                    if cur_component.run_scope().is_ok() {
                        let (old, new) = (cur_component.old_frame(), cur_component.next_frame());
                        diff_machine.diff_node(old, new);
                    }
                }
            }
        }

        Ok(())
    }

    pub fn base_scope(&self) -> &Scope {
        unsafe { self.shared.get_scope(self.base_scope).unwrap() }
    }

    pub fn get_scope(&self, id: ScopeId) -> Option<&Scope> {
        unsafe { self.shared.get_scope(id) }
    }
}

// TODO!
// These impls are actually wrong. The DOM needs to have a mutex implemented.
unsafe impl Sync for VirtualDom {}
unsafe impl Send for VirtualDom {}