Add Node::tree_id property for graft support

Author: DataTriny

common/src/lib.rs

@@ -628,6 +628,11 @@ pub enum TextDecoration {
 pub type NodeIdContent = u64;
 
 /// The stable identity of a [`Node`], unique within the node's tree.
+///
+/// Each tree (root or subtree) has its own independent ID space. The same
+/// `NodeId` value can exist in different trees without conflict. When working
+/// with multiple trees, the combination of `NodeId` and [`TreeId`] uniquely
+/// identifies a node.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
@@ -778,6 +783,7 @@ enum PropertyValue {
     Rect(Rect),
     TextSelection(Box<TextSelection>),
     CustomActionVec(Vec<CustomAction>),
+    TreeId(TreeId),
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -894,6 +900,7 @@ enum PropertyId {
     Bounds,
     TextSelection,
     CustomActions,
+    TreeId,
 
     // This MUST be last.
     Unset,
@@ -1695,7 +1702,8 @@ copy_type_getters! {
     (get_usize_property, usize, Usize),
     (get_color_property, u32, Color),
     (get_text_decoration_property, TextDecoration, TextDecoration),
-    (get_bool_property, bool, Bool)
+    (get_bool_property, bool, Bool),
+    (get_tree_id_property, TreeId, TreeId)
 }
 
 box_type_setters! {
@@ -1713,7 +1721,8 @@ copy_type_setters! {
     (set_usize_property, usize, Usize),
     (set_color_property, u32, Color),
     (set_text_decoration_property, TextDecoration, TextDecoration),
-    (set_bool_property, bool, Bool)
+    (set_bool_property, bool, Bool),
+    (set_tree_id_property, TreeId, TreeId)
 }
 
 vec_type_methods! {
@@ -2014,11 +2023,20 @@ property_methods! {
     /// [`transform`]: Node::transform
     (Bounds, bounds, get_rect_property, Option<Rect>, set_bounds, set_rect_property, Rect, clear_bounds),
 
-    (TextSelection, text_selection, get_text_selection_property, Option<&TextSelection>, set_text_selection, set_text_selection_property, impl Into<Box<TextSelection>>, clear_text_selection)
+    (TextSelection, text_selection, get_text_selection_property, Option<&TextSelection>, set_text_selection, set_text_selection_property, impl Into<Box<TextSelection>>, clear_text_selection),
+
+    /// The tree that this node grafts. When set, this node acts as a graft
+    /// point, and its child is the root of the specified subtree.
+    ///
+    /// A graft node must be created before its subtree is pushed.
+    ///
+    /// Removing a graft node or clearing this property removes its subtree,
+    /// unless a new graft node is provided in the same update.
+    (TreeId, tree_id, get_tree_id_property, Option<TreeId>, set_tree_id, set_tree_id_property, TreeId, clear_tree_id)
 }
 
 impl Node {
-    option_properties_debug_method! { debug_option_properties, [transform, bounds, text_selection,] }
+    option_properties_debug_method! { debug_option_properties, [transform, bounds, text_selection, tree_id,] }
 }
 
 #[cfg(test)]
@@ -2123,6 +2141,31 @@ mod text_selection {
     }
 }
 
+#[cfg(test)]
+mod tree_id {
+    use super::{Node, Role, TreeId, Uuid};
+
+    #[test]
+    fn getter_should_return_default_value() {
+        let node = Node::new(Role::GenericContainer);
+        assert!(node.tree_id().is_none());
+    }
+    #[test]
+    fn setter_should_update_the_property() {
+        let mut node = Node::new(Role::GenericContainer);
+        let value = TreeId(Uuid::nil());
+        node.set_tree_id(value);
+        assert_eq!(node.tree_id(), Some(value));
+    }
+    #[test]
+    fn clearer_should_reset_the_property() {
+        let mut node = Node::new(Role::GenericContainer);
+        node.set_tree_id(TreeId(Uuid::nil()));
+        node.clear_tree_id();
+        assert!(node.tree_id().is_none());
+    }
+}
+
 vec_property_methods! {
     (CustomActions, CustomAction, custom_actions, get_custom_action_vec, set_custom_actions, set_custom_action_vec, push_custom_action, push_to_custom_action_vec, clear_custom_actions)
 }
@@ -2291,7 +2334,8 @@ impl Serialize for Properties {
                 Affine,
                 Rect,
                 TextSelection,
-                CustomActionVec
+                CustomActionVec,
+                TreeId
             });
         }
         map.end()
@@ -2421,7 +2465,8 @@ impl<'de> Visitor<'de> for PropertiesVisitor {
                 Affine { Transform },
                 Rect { Bounds },
                 TextSelection { TextSelection },
-                CustomActionVec { CustomActions }
+                CustomActionVec { CustomActions },
+                TreeId { TreeId }
             });
         }
 
@@ -2651,14 +2696,26 @@ pub struct TreeUpdate {
     /// a tree.
     pub tree: Option<Tree>,
 
-    /// The identifier of the tree.
+    /// The identifier of the tree that this update applies to.
+    ///
+    /// Use [`TreeId::ROOT`] for the main/root tree. For subtrees, use a unique
+    /// [`TreeId`] that identifies the subtree.
+    ///
+    /// When updating a subtree (non-ROOT tree_id):
+    /// - A graft node with [`Node::tree_id`] set to this tree's ID must already
+    ///   exist in the parent tree before the first subtree update.
+    /// - The first update for a subtree must include [`tree`](Self::tree) data.
     pub tree_id: TreeId,
 
     /// The node within this tree that has keyboard focus when the native
     /// host (e.g. window) has focus. If no specific node within the tree
     /// has keyboard focus, this must be set to the root. The latest focus state
     /// must be provided with every tree update, even if the focus state
     /// didn't change in a given update.
+    ///
+    /// For subtrees, this specifies which node has focus when the subtree
+    /// itself is focused (i.e., when focus is on the graft node in the parent
+    /// tree).
     pub focus: NodeId,
 }
 

consumer/src/filters.rs

@@ -23,6 +23,11 @@ fn common_filter_base(node: &Node) -> Option<FilterResult> {
         return Some(FilterResult::ExcludeSubtree);
     }
 
+    // Graft nodes are transparent containers pointing to a subtree
+    if node.is_graft() {
+        return Some(FilterResult::ExcludeNode);
+    }
+
     let role = node.role();
     if role == Role::GenericContainer || role == Role::TextRun {
         return Some(FilterResult::ExcludeNode);
@@ -387,4 +392,30 @@ mod tests {
         assert_filter_result(ExcludeSubtree, &tree, NodeId(10));
         assert_filter_result(ExcludeSubtree, &tree, NodeId(11));
     }
+
+    #[test]
+    fn graft_node() {
+        use accesskit::Uuid;
+
+        let subtree_id = TreeId(Uuid::from_u128(1));
+        let update = TreeUpdate {
+            nodes: vec![
+                (NodeId(0), {
+                    let mut node = Node::new(Role::Window);
+                    node.set_children(vec![NodeId(1)]);
+                    node
+                }),
+                (NodeId(1), {
+                    let mut node = Node::new(Role::GenericContainer);
+                    node.set_tree_id(subtree_id);
+                    node
+                }),
+            ],
+            tree: Some(Tree::new(NodeId(0))),
+            tree_id: TreeId::ROOT,
+            focus: NodeId(0),
+        };
+        let tree = crate::Tree::new(update, false);
+        assert_filter_result(ExcludeNode, &tree, NodeId(1));
+    }
 }

consumer/src/iterators.rs

@@ -18,12 +18,13 @@ use crate::{
     tree::State as TreeState,
 };
 
-/// Iterator over child NodeIds.
+/// Iterator over child NodeIds, handling both normal nodes and graft nodes.
 pub enum ChildIds<'a> {
     Normal {
         parent_id: NodeId,
         children: core::slice::Iter<'a, LocalNodeId>,
     },
+    Graft(Option<NodeId>),
 }
 
 impl Iterator for ChildIds<'_> {
@@ -37,6 +38,7 @@ impl Iterator for ChildIds<'_> {
             } => children
                 .next()
                 .map(|child| parent_id.with_same_tree(*child)),
+            Self::Graft(id) => id.take(),
         }
     }
 
@@ -55,6 +57,7 @@ impl DoubleEndedIterator for ChildIds<'_> {
             } => children
                 .next_back()
                 .map(|child| parent_id.with_same_tree(*child)),
+            Self::Graft(id) => id.take(),
         }
     }
 }
@@ -63,6 +66,7 @@ impl ExactSizeIterator for ChildIds<'_> {
     fn len(&self) -> usize {
         match self {
             Self::Normal { children, .. } => children.len(),
+            Self::Graft(id) => usize::from(id.is_some()),
         }
     }
 }
@@ -85,13 +89,18 @@ impl<'a> FollowingSiblings<'a> {
         let parent_and_index = node.parent_and_index();
         let (back_position, front_position, done) =
             if let Some((ref parent, index)) = parent_and_index {
-                let back_position = parent.data().children().len() - 1;
-                let front_position = index + 1;
-                (
-                    back_position,
-                    front_position,
-                    front_position > back_position,
-                )
+                // Graft nodes have only one child (the subtree root)
+                if parent.is_graft() {
+                    (0, 0, true)
+                } else {
+                    let back_position = parent.data().children().len() - 1;
+                    let front_position = index + 1;
+                    (
+                        back_position,
+                        front_position,
+                        front_position > back_position,
+                    )
+                }
             } else {
                 (0, 0, true)
             };
@@ -169,12 +178,18 @@ pub struct PrecedingSiblings<'a> {
 impl<'a> PrecedingSiblings<'a> {
     pub(crate) fn new(node: Node<'a>) -> Self {
         let parent_and_index = node.parent_and_index();
-        let (back_position, front_position, done) = if let Some((_, index)) = parent_and_index {
-            let front_position = index.saturating_sub(1);
-            (0, front_position, index == 0)
-        } else {
-            (0, 0, true)
-        };
+        let (back_position, front_position, done) =
+            if let Some((ref parent, index)) = parent_and_index {
+                // Graft nodes have only one child (the subtree root)
+                if parent.is_graft() {
+                    (0, 0, true)
+                } else {
+                    let front_position = index.saturating_sub(1);
+                    (0, front_position, index == 0)
+                }
+            } else {
+                (0, 0, true)
+            };
         Self {
             back_position,
             done,
@@ -567,9 +582,14 @@ impl<Filter: Fn(&Node) -> FilterResult> FusedIterator for LabelledBy<'_, Filter>
 
 #[cfg(test)]
 mod tests {
-    use crate::tests::*;
-    use accesskit::NodeId as LocalNodeId;
-    use alloc::vec::Vec;
+    use crate::{
+        filters::common_filter,
+        tests::*,
+        tree::{ChangeHandler, TreeIndex},
+        NodeId,
+    };
+    use accesskit::{Node, NodeId as LocalNodeId, Role, Tree, TreeId, TreeUpdate, Uuid};
+    use alloc::{vec, vec::Vec};
 
     #[test]
     fn following_siblings() {
@@ -927,4 +947,92 @@ mod tests {
             .next_back()
             .is_none());
     }
+
+    #[test]
+    fn graft_node_without_subtree_has_no_filtered_children() {
+        let subtree_id = TreeId(Uuid::from_u128(1));
+
+        let update = TreeUpdate {
+            nodes: vec![
+                (LocalNodeId(0), {
+                    let mut node = Node::new(Role::Window);
+                    node.set_children(vec![LocalNodeId(1)]);
+                    node
+                }),
+                (LocalNodeId(1), {
+                    let mut node = Node::new(Role::GenericContainer);
+                    node.set_tree_id(subtree_id);
+                    node
+                }),
+            ],
+            tree: Some(Tree::new(LocalNodeId(0))),
+            tree_id: TreeId::ROOT,
+            focus: LocalNodeId(0),
+        };
+        let tree = crate::Tree::new(update, false);
+
+        let graft_node_id = NodeId::new(LocalNodeId(1), TreeIndex(0));
+        let graft_node = tree.state().node_by_id(graft_node_id).unwrap();
+        assert!(graft_node.filtered_children(common_filter).next().is_none());
+    }
+
+    #[test]
+    fn filtered_children_crosses_subtree_boundary() {
+        struct NoOpHandler;
+        impl ChangeHandler for NoOpHandler {
+            fn node_added(&mut self, _: &crate::Node) {}
+            fn node_updated(&mut self, _: &crate::Node, _: &crate::Node) {}
+            fn focus_moved(&mut self, _: Option<&crate::Node>, _: Option<&crate::Node>) {}
+            fn node_removed(&mut self, _: &crate::Node) {}
+        }
+
+        let subtree_id = TreeId(Uuid::from_u128(1));
+
+        let update = TreeUpdate {
+            nodes: vec![
+                (LocalNodeId(0), {
+                    let mut node = Node::new(Role::Window);
+                    node.set_children(vec![LocalNodeId(1)]);
+                    node
+                }),
+                (LocalNodeId(1), {
+                    let mut node = Node::new(Role::GenericContainer);
+                    node.set_tree_id(subtree_id);
+                    node
+                }),
+            ],
+            tree: Some(Tree::new(LocalNodeId(0))),
+            tree_id: TreeId::ROOT,
+            focus: LocalNodeId(0),
+        };
+        let mut tree = crate::Tree::new(update, false);
+
+        let subtree_update = TreeUpdate {
+            nodes: vec![
+                (LocalNodeId(0), {
+                    let mut node = Node::new(Role::Document);
+                    node.set_children(vec![LocalNodeId(1)]);
+                    node
+                }),
+                (LocalNodeId(1), Node::new(Role::Button)),
+            ],
+            tree: Some(Tree::new(LocalNodeId(0))),
+            tree_id: subtree_id,
+            focus: LocalNodeId(0),
+        };
+        tree.update_and_process_changes(subtree_update, &mut NoOpHandler);
+
+        let root = tree.state().root();
+        let filtered_children: Vec<_> = root.filtered_children(common_filter).collect();
+
+        assert_eq!(1, filtered_children.len());
+        let subtree_root_id = NodeId::new(LocalNodeId(0), TreeIndex(1));
+        assert_eq!(subtree_root_id, filtered_children[0].id());
+
+        let document = &filtered_children[0];
+        let doc_children: Vec<_> = document.filtered_children(common_filter).collect();
+        assert_eq!(1, doc_children.len());
+        let button_id = NodeId::new(LocalNodeId(1), TreeIndex(1));
+        assert_eq!(button_id, doc_children[0].id());
+    }
 }