wip: clean up some things

packages/core/src/mutations.rs

@@ -1,45 +1,50 @@
+use fxhash::FxHashSet;
+
 use crate::{arena::ElementId, ScopeId};
 
+/// A container for all the relevant steps to modify the Real DOM
+///
+/// This method returns "mutations" - IE the necessary changes to get the RealDOM to match the VirtualDOM. It also
+/// includes a list of NodeRefs that need to be applied and effects that need to be triggered after the RealDOM has
+/// applied the edits.
+///
+/// Mutations are the only link between the RealDOM and the VirtualDOM.
 #[derive(Debug, Default)]
 #[must_use = "not handling edits can lead to visual inconsistencies in UI"]
 pub struct Mutations<'a> {
+    /// The ID of the subtree that these edits are targetting
     pub subtree: usize,
-    pub template_mutations: Vec<Mutation<'a>>,
-    pub edits: Vec<Mutation<'a>>,
+
+    /// The list of Scopes that were diffed, created, and removed during the Diff process.
+    pub dirty_scopes: FxHashSet<ScopeId>,
+
+    /// Any mutations required to build the templates using [`Mutations`]
+    pub template_edits: Vec<Mutation<'a>>,
+
+    /// Any mutations required to patch the renderer to match the layout of the VirtualDom
+    pub dom_edits: Vec<Mutation<'a>>,
 }
 
 impl<'a> Mutations<'a> {
-    /// A useful tool for testing mutations
-    ///
     /// Rewrites IDs to just be "template", so you can compare the mutations
+    ///
+    /// Used really only for testing
     pub fn santize(mut self) -> Self {
-        for edit in self
-            .template_mutations
+        self.template_edits
             .iter_mut()
-            .chain(self.edits.iter_mut())
-        {
-            match edit {
+            .chain(self.dom_edits.iter_mut())
+            .for_each(|edit| match edit {
                 Mutation::LoadTemplate { name, .. } => *name = "template",
                 Mutation::SaveTemplate { name, .. } => *name = "template",
                 _ => {}
-            }
-        }
+            });
 
         self
     }
-}
 
-impl<'a> std::ops::Deref for Mutations<'a> {
-    type Target = Vec<Mutation<'a>>;
-
-    fn deref(&self) -> &Self::Target {
-        &self.edits
-    }
-}
-
-impl std::ops::DerefMut for Mutations<'_> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.edits
+    /// Push a new mutation into the dom_edits list
+    pub(crate) fn push(&mut self, mutation: Mutation<'static>) {
+        self.dom_edits.push(mutation)
     }
 }
 
@@ -54,7 +59,11 @@ each subtree has its own numbering scheme
 )]
 #[derive(Debug, PartialEq, Eq)]
 pub enum Mutation<'a> {
+    /// Pop the topmost node from our stack and append them to the node
+    /// at the top of the stack.
     AppendChildren {
+        /// How many nodes should be popped from the stack.
+        /// The node remaining on the stack will be the target for the append.
         m: usize,
     },
 
@@ -122,36 +131,61 @@ pub enum Mutation<'a> {
         m: usize,
     },
 
+    /// Save the top m nodes as a placeholder
     SaveTemplate {
+        /// The name of the template that we're saving
         name: &'static str,
+
+        /// How many nodes are being saved into this template
         m: usize,
     },
 
+    /// Set the value of a node's attribute.
     SetAttribute {
+        /// The name of the attribute to set.
         name: &'a str,
+        /// The value of the attribute.
         value: &'a str,
+
+        /// The ID of the node to set the attribute of.
         id: ElementId,
 
-        // value: &'bump str,
         /// The (optional) namespace of the attribute.
         /// For instance, "style" is in the "style" namespace.
         ns: Option<&'a str>,
     },
 
+    /// Set the value of a node's attribute.
     SetStaticAttribute {
+        /// The name of the attribute to set.
         name: &'a str,
+
+        /// The value of the attribute.
         value: &'a str,
+
+        /// The (optional) namespace of the attribute.
+        /// For instance, "style" is in the "style" namespace.
         ns: Option<&'a str>,
     },
 
+    /// Set the value of a node's attribute.
     SetBoolAttribute {
+        /// The name of the attribute to set.
         name: &'a str,
+
+        /// The value of the attribute.
         value: bool,
+
+        /// The ID of the node to set the attribute of.
         id: ElementId,
     },
 
+    /// Set the textcontent of a node.
     SetText {
+        /// The textcontent of the node
         value: &'a str,
+
+        /// The ID of the node to set the textcontent of.
         id: ElementId,
     },
 
@@ -175,11 +209,16 @@ pub enum Mutation<'a> {
         /// The ID of the node to remove.
         id: ElementId,
     },
+
+    /// Remove a particular node from the DOM
     Remove {
+        /// The ID of the node to remove.
         id: ElementId,
     },
 
+    /// Push the given root node onto our stack.
     PushRoot {
+        /// The ID of the root node to push.
         id: ElementId,
     },
 }