mecomp_tui/ui/widgets/tree/
item.rs

1use std::collections::HashSet;
2
3use ratatui::text::Text;
4
5/// One item inside a [`CheckTree`](super::CheckTree).
6///
7/// Can have zero or more `children`.
8///
9/// # Identifier
10///
11/// The generic argument `Identifier` is used to keep the state like the currently selected or opened [`CheckTreeItem`]s in the [`CheckTreeState`](super::state::CheckTreeState).
12///
13/// It needs to be unique among its siblings but can be used again on parent or child [`CheckTreeItem`]s.
14/// A common example would be a filename which has to be unique in its directory while it can exist in another.
15///
16/// The `text` can be different from its `identifier`.
17/// To repeat the filename analogy: File browsers sometimes hide file extensions.
18/// The filename `main.rs` is the identifier while its shown as `main`.
19/// Two files `main.rs` and `main.toml` can exist in the same directory and can both be displayed as `main` but their identifier is different.
20///
21/// Just like every file in a file system can be uniquely identified with its file and directory names each [`CheckTreeItem`] in a [`CheckTree`](super::CheckTree) can be with these identifiers.
22/// As an example the following two identifiers describe the main file in a Rust cargo project: `vec!["src", "main.rs"]`.
23#[derive(Debug, Clone)]
24#[allow(clippy::module_name_repetitions)]
25pub struct CheckTreeItem<'text, Identifier> {
26    pub(super) identifier: Identifier,
27    pub(super) text: Text<'text>,
28    pub(super) children: Vec<Self>,
29}
30
31impl<'text, Identifier> CheckTreeItem<'text, Identifier>
32where
33    Identifier: Clone + PartialEq + Eq + core::hash::Hash,
34{
35    /// Create a new `CheckTreeItem` without children.
36    #[must_use]
37    pub fn new_leaf<T>(identifier: Identifier, text: T) -> Self
38    where
39        T: Into<Text<'text>>,
40    {
41        Self {
42            identifier,
43            text: text.into(),
44            children: Vec::new(),
45        }
46    }
47
48    /// Create a new `CheckTreeItem` with children.
49    ///
50    /// # Errors
51    ///
52    /// Errors when there are duplicate identifiers in the children.
53    pub fn new<T>(identifier: Identifier, text: T, children: Vec<Self>) -> std::io::Result<Self>
54    where
55        T: Into<Text<'text>>,
56    {
57        let identifiers = children
58            .iter()
59            .map(|item| &item.identifier)
60            .collect::<HashSet<_>>();
61        if identifiers.len() != children.len() {
62            return Err(std::io::Error::new(
63                std::io::ErrorKind::AlreadyExists,
64                "The children contain duplicate identifiers",
65            ));
66        }
67
68        Ok(Self {
69            identifier,
70            text: text.into(),
71            children,
72        })
73    }
74
75    /// Get a reference to the identifier.
76    #[must_use]
77    pub const fn identifier(&self) -> &Identifier {
78        &self.identifier
79    }
80
81    #[must_use]
82    pub fn children(&self) -> &[Self] {
83        &self.children
84    }
85
86    /// Get a reference to a child by index.
87    #[must_use]
88    pub fn child(&self, index: usize) -> Option<&Self> {
89        self.children.get(index)
90    }
91
92    /// Get a mutable reference to a child by index.
93    ///
94    /// When you choose to change the `identifier` the [`CheckTreeState`](super::CheckTreeState) might not work as expected afterwards.
95    #[must_use]
96    pub fn child_mut(&mut self, index: usize) -> Option<&mut Self> {
97        self.children.get_mut(index)
98    }
99
100    #[must_use]
101    pub fn height(&self) -> usize {
102        self.text.height()
103    }
104
105    /// Add a child to the `CheckTreeItem`.
106    ///
107    /// # Errors
108    ///
109    /// Errors when the `identifier` of the `child` already exists in the children.
110    pub fn add_child(&mut self, child: Self) -> std::io::Result<()> {
111        let existing = self
112            .children
113            .iter()
114            .map(|item| &item.identifier)
115            .collect::<HashSet<_>>();
116        if existing.contains(&child.identifier) {
117            return Err(std::io::Error::new(
118                std::io::ErrorKind::AlreadyExists,
119                "identifier already exists in the children",
120            ));
121        }
122
123        self.children.push(child);
124        Ok(())
125    }
126}
127
128#[cfg(test)]
129impl CheckTreeItem<'static, &'static str> {
130    #[must_use]
131    pub(crate) fn example() -> Vec<Self> {
132        vec![
133            Self::new_leaf("a", "Alfa"),
134            Self::new(
135                "b",
136                "Bravo",
137                vec![
138                    Self::new_leaf("c", "Charlie"),
139                    Self::new(
140                        "d",
141                        "Delta",
142                        vec![Self::new_leaf("e", "Echo"), Self::new_leaf("f", "Foxtrot")],
143                    )
144                    .expect("all item identifiers are unique"),
145                    Self::new_leaf("g", "Golf"),
146                ],
147            )
148            .expect("all item identifiers are unique"),
149            Self::new_leaf("h", "Hotel"),
150        ]
151    }
152}
153
154#[cfg(test)]
155mod tests {
156    use super::*;
157
158    #[test]
159    #[should_panic = "duplicate identifiers"]
160    fn tree_item_new_errors_with_duplicate_identifiers() {
161        let item = CheckTreeItem::new_leaf("same", "text");
162        let another = item.clone();
163        CheckTreeItem::new("root", "Root", vec![item, another]).unwrap();
164    }
165
166    #[test]
167    #[should_panic = "identifier already exists"]
168    fn tree_item_add_child_errors_with_duplicate_identifiers() {
169        let item = CheckTreeItem::new_leaf("same", "text");
170        let another = item.clone();
171        let mut root = CheckTreeItem::new("root", "Root", vec![item]).unwrap();
172        root.add_child(another).unwrap();
173    }
174}
mecomp_tui/ui/widgets/tree/item.rs

mecomp_tui/ui/widgets/tree/
item.rs
