Skip to main content

ftui_widgets/
tree.rs

1//! Tree widget for hierarchical display.
2//!
3//! Renders a tree of labeled nodes with configurable guide characters
4//! and styles, suitable for file trees or structured views.
5//!
6//! # Example
7//!
8//! ```
9//! use ftui_widgets::tree::{Tree, TreeNode, TreeGuides};
10//!
11//! let tree = Tree::new(TreeNode::new("root")
12//!     .child(TreeNode::new("src")
13//!         .child(TreeNode::new("main.rs"))
14//!         .child(TreeNode::new("lib.rs")))
15//!     .child(TreeNode::new("Cargo.toml")));
16//!
17//! assert_eq!(tree.root().label(), "root");
18//! assert_eq!(tree.root().children().len(), 2);
19//! ```
20
21use crate::mouse::MouseResult;
22use crate::stateful::Stateful;
23use crate::undo_support::{TreeUndoExt, UndoSupport, UndoWidgetId};
24use crate::{Widget, clear_text_area, draw_text_span};
25use ftui_core::event::{KeyCode, KeyEvent, KeyEventKind, MouseButton, MouseEvent, MouseEventKind};
26use ftui_core::geometry::Rect;
27use ftui_render::frame::{Frame, HitId, HitRegion};
28use ftui_style::Style;
29use std::any::Any;
30use std::collections::HashSet;
31#[cfg(feature = "tracing")]
32use web_time::Instant;
33
34/// Guide character styles for tree rendering.
35#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
36pub enum TreeGuides {
37    /// ASCII guides: `|`, `+--`, `` `-- ``.
38    Ascii,
39    /// Unicode box-drawing characters (default).
40    #[default]
41    Unicode,
42    /// Bold Unicode box-drawing characters.
43    Bold,
44    /// Double-line Unicode characters.
45    Double,
46    /// Rounded Unicode characters.
47    Rounded,
48}
49
50impl TreeGuides {
51    /// Vertical continuation (item has siblings below).
52    #[must_use]
53    pub const fn vertical(&self) -> &str {
54        match self {
55            Self::Ascii => "|   ",
56            Self::Unicode | Self::Rounded => "\u{2502}   ",
57            Self::Bold => "\u{2503}   ",
58            Self::Double => "\u{2551}   ",
59        }
60    }
61
62    /// Branch guide (item has siblings below).
63    #[must_use]
64    pub const fn branch(&self) -> &str {
65        match self {
66            Self::Ascii => "+-- ",
67            Self::Unicode => "\u{251C}\u{2500}\u{2500} ",
68            Self::Bold => "\u{2523}\u{2501}\u{2501} ",
69            Self::Double => "\u{2560}\u{2550}\u{2550} ",
70            Self::Rounded => "\u{251C}\u{2500}\u{2500} ",
71        }
72    }
73
74    /// Last-item guide (no siblings below).
75    #[must_use]
76    pub const fn last(&self) -> &str {
77        match self {
78            Self::Ascii => "`-- ",
79            Self::Unicode => "\u{2514}\u{2500}\u{2500} ",
80            Self::Bold => "\u{2517}\u{2501}\u{2501} ",
81            Self::Double => "\u{255A}\u{2550}\u{2550} ",
82            Self::Rounded => "\u{2570}\u{2500}\u{2500} ",
83        }
84    }
85
86    /// Empty indentation (no guide needed).
87    #[must_use]
88    pub const fn space(&self) -> &str {
89        "    "
90    }
91
92    /// Width in columns of each guide segment.
93    #[inline]
94    #[must_use]
95    pub fn width(&self) -> usize {
96        4
97    }
98}
99
100/// A node in the tree hierarchy.
101#[derive(Debug, Clone)]
102pub struct TreeNode {
103    label: String,
104    icon: Option<String>,
105    /// Child nodes (crate-visible for undo support).
106    pub(crate) children: Vec<TreeNode>,
107    /// Lazily materialized children.
108    lazy_children: Option<Vec<TreeNode>>,
109    /// Whether this node is expanded (crate-visible for undo support).
110    pub(crate) expanded: bool,
111}
112
113impl TreeNode {
114    /// Create a new tree node with the given label.
115    #[must_use]
116    pub fn new(label: impl Into<String>) -> Self {
117        Self {
118            label: label.into(),
119            icon: None,
120            children: Vec::new(),
121            lazy_children: None,
122            expanded: true,
123        }
124    }
125
126    /// Add a child node.
127    #[must_use]
128    pub fn child(mut self, node: TreeNode) -> Self {
129        self.children.push(node);
130        self
131    }
132
133    /// Set children from a vec.
134    #[must_use]
135    pub fn with_children(mut self, nodes: Vec<TreeNode>) -> Self {
136        self.children = nodes;
137        self
138    }
139
140    /// Set an icon prefix rendered before the label.
141    #[must_use]
142    pub fn with_icon(mut self, icon: impl Into<String>) -> Self {
143        self.icon = Some(icon.into());
144        self
145    }
146
147    /// Configure lazily materialized children.
148    ///
149    /// The node starts collapsed and children are attached when first expanded.
150    #[must_use]
151    pub fn with_lazy_children(mut self, nodes: Vec<TreeNode>) -> Self {
152        self.lazy_children = Some(nodes);
153        self.expanded = false;
154        self
155    }
156
157    /// Set whether this node is expanded.
158    #[must_use]
159    pub fn with_expanded(mut self, expanded: bool) -> Self {
160        if expanded {
161            self.materialize_lazy_children();
162        }
163        self.expanded = expanded;
164        self
165    }
166
167    /// Get the label.
168    #[must_use]
169    pub fn label(&self) -> &str {
170        &self.label
171    }
172
173    /// Get the children.
174    #[must_use]
175    pub fn children(&self) -> &[TreeNode] {
176        &self.children
177    }
178
179    /// Optional icon rendered before label.
180    #[must_use]
181    pub fn icon(&self) -> Option<&str> {
182        self.icon.as_deref()
183    }
184
185    /// Whether this node has loaded or lazy children.
186    #[must_use]
187    pub fn has_children(&self) -> bool {
188        !self.children.is_empty()
189            || self
190                .lazy_children
191                .as_ref()
192                .is_some_and(|children| !children.is_empty())
193    }
194
195    /// Whether this node is expanded.
196    #[must_use]
197    pub fn is_expanded(&self) -> bool {
198        self.expanded
199    }
200
201    /// Toggle the expanded state.
202    pub fn toggle_expanded(&mut self) {
203        if !self.expanded {
204            self.materialize_lazy_children();
205        }
206        self.expanded = !self.expanded;
207    }
208
209    fn materialize_lazy_children(&mut self) {
210        if let Some(mut lazy) = self.lazy_children.take() {
211            self.children.append(&mut lazy);
212        }
213    }
214
215    fn materialize_all_lazy_children(&mut self) {
216        self.materialize_lazy_children();
217        for child in &mut self.children {
218            child.materialize_all_lazy_children();
219        }
220    }
221
222    #[cfg(feature = "tracing")]
223    fn total_count(&self) -> usize {
224        let mut count = 1usize;
225        for child in &self.children {
226            count = count.saturating_add(child.total_count());
227        }
228        if let Some(lazy) = &self.lazy_children {
229            for child in lazy {
230                count = count.saturating_add(child.total_count());
231            }
232        }
233        count
234    }
235
236    #[cfg(feature = "tracing")]
237    fn expanded_count(&self) -> usize {
238        let mut count = usize::from(self.expanded && self.has_children());
239        for child in &self.children {
240            count = count.saturating_add(child.expanded_count());
241        }
242        if let Some(lazy) = &self.lazy_children {
243            for child in lazy {
244                count = count.saturating_add(child.expanded_count());
245            }
246        }
247        count
248    }
249
250    /// Count all visible (expanded) nodes, including this one.
251    #[must_use]
252    pub fn visible_count(&self) -> usize {
253        let mut count = 1;
254        if self.expanded {
255            for child in &self.children {
256                count += child.visible_count();
257            }
258        }
259        count
260    }
261
262    /// Collect all expanded node paths into a set.
263    #[allow(dead_code)]
264    pub(crate) fn collect_expanded(&self, prefix: &str, out: &mut HashSet<String>) {
265        let path = if prefix.is_empty() {
266            self.label.clone()
267        } else {
268            format!("{}/{}", prefix, self.label)
269        };
270
271        if self.expanded && self.has_children() {
272            out.insert(path.clone());
273        }
274
275        for child in &self.children {
276            child.collect_expanded(&path, out);
277        }
278    }
279
280    /// Apply expanded state from a set of paths.
281    #[allow(dead_code)]
282    pub(crate) fn apply_expanded(&mut self, prefix: &str, expanded_paths: &HashSet<String>) {
283        let path = if prefix.is_empty() {
284            self.label.clone()
285        } else {
286            format!("{}/{}", prefix, self.label)
287        };
288
289        if self.has_children() {
290            self.expanded = expanded_paths.contains(&path);
291            if self.expanded {
292                self.materialize_lazy_children();
293            }
294        }
295
296        for child in &mut self.children {
297            child.apply_expanded(&path, expanded_paths);
298        }
299    }
300}
301
302/// Tree widget for rendering hierarchical data.
303#[derive(Debug, Clone)]
304pub struct Tree {
305    /// Unique ID for undo tracking.
306    undo_id: UndoWidgetId,
307    root: TreeNode,
308    /// Whether to show the root node.
309    show_root: bool,
310    /// Guide character style.
311    guides: TreeGuides,
312    /// Style for guide characters.
313    guide_style: Style,
314    /// Style for node labels.
315    label_style: Style,
316    /// Style for the root node label.
317    root_style: Style,
318    /// Optional persistence ID for state saving/restoration.
319    persistence_id: Option<String>,
320    /// Optional hit ID for mouse interaction.
321    hit_id: Option<HitId>,
322    /// Optional case-insensitive search query.
323    search_query: Option<String>,
324}
325
326impl Tree {
327    /// Create a tree widget with the given root node.
328    #[must_use]
329    pub fn new(root: TreeNode) -> Self {
330        Self {
331            undo_id: UndoWidgetId::new(),
332            root,
333            show_root: true,
334            guides: TreeGuides::default(),
335            guide_style: Style::default(),
336            label_style: Style::default(),
337            root_style: Style::default(),
338            persistence_id: None,
339            hit_id: None,
340            search_query: None,
341        }
342    }
343
344    /// Set whether to show the root node.
345    #[must_use]
346    pub fn with_show_root(mut self, show: bool) -> Self {
347        self.show_root = show;
348        self
349    }
350
351    /// Set the guide character style.
352    #[must_use]
353    pub fn with_guides(mut self, guides: TreeGuides) -> Self {
354        self.guides = guides;
355        self
356    }
357
358    /// Set the style for guide characters.
359    #[must_use]
360    pub fn with_guide_style(mut self, style: Style) -> Self {
361        self.guide_style = style;
362        self
363    }
364
365    /// Set the style for node labels.
366    #[must_use]
367    pub fn with_label_style(mut self, style: Style) -> Self {
368        self.label_style = style;
369        self
370    }
371
372    /// Set the style for the root label.
373    #[must_use]
374    pub fn with_root_style(mut self, style: Style) -> Self {
375        self.root_style = style;
376        self
377    }
378
379    /// Set a persistence ID for state saving. Without one the tree has no
380    /// [`StateKey`](crate::stateful::StateKey) and its state is not persisted.
381    #[must_use]
382    pub fn with_persistence_id(mut self, id: impl Into<String>) -> Self {
383        self.persistence_id = Some(id.into());
384        self
385    }
386
387    /// Get the persistence ID, if set.
388    #[must_use]
389    pub fn persistence_id(&self) -> Option<&str> {
390        self.persistence_id.as_deref()
391    }
392
393    /// Set a hit ID for mouse interaction.
394    #[must_use]
395    pub fn hit_id(mut self, id: HitId) -> Self {
396        self.hit_id = Some(id);
397        self
398    }
399
400    /// Apply a case-insensitive search query filter.
401    #[must_use]
402    pub fn with_search_query(mut self, query: impl Into<String>) -> Self {
403        let query = query.into();
404        self.search_query = if query.trim().is_empty() {
405            None
406        } else {
407            Some(query)
408        };
409        self
410    }
411
412    /// Clear search filtering.
413    #[must_use]
414    pub fn without_search_query(mut self) -> Self {
415        self.search_query = None;
416        self
417    }
418
419    #[cfg(feature = "tracing")]
420    fn total_nodes(&self) -> usize {
421        if self.show_root {
422            self.root.total_count()
423        } else if self.root.expanded {
424            self.root
425                .children
426                .iter()
427                .fold(0usize, |acc, child| acc.saturating_add(child.total_count()))
428        } else {
429            0
430        }
431    }
432
433    #[cfg(feature = "tracing")]
434    fn visible_nodes(&self) -> usize {
435        if self.show_root {
436            self.root.visible_count()
437        } else if self.root.expanded {
438            self.root.children.iter().fold(0usize, |acc, child| {
439                acc.saturating_add(child.visible_count())
440            })
441        } else {
442            0
443        }
444    }
445
446    #[cfg(feature = "tracing")]
447    fn expanded_nodes(&self) -> usize {
448        if self.show_root {
449            self.root.expanded_count()
450        } else if self.root.expanded {
451            self.root.children.iter().fold(0usize, |acc, child| {
452                acc.saturating_add(child.expanded_count())
453            })
454        } else {
455            0
456        }
457    }
458
459    /// Get a reference to the root node.
460    #[must_use]
461    pub fn root(&self) -> &TreeNode {
462        &self.root
463    }
464
465    /// Get a mutable reference to the root node.
466    pub fn root_mut(&mut self) -> &mut TreeNode {
467        &mut self.root
468    }
469
470    #[allow(clippy::too_many_arguments)]
471    fn render_node(
472        &self,
473        node: &TreeNode,
474        depth: usize,
475        is_last: &mut Vec<bool>,
476        area: Rect,
477        frame: &mut Frame,
478        current_row: &mut usize,
479        deg: ftui_render::budget::DegradationLevel,
480    ) {
481        if *current_row >= area.height as usize {
482            return;
483        }
484
485        let y = area.y.saturating_add(*current_row as u16);
486        let mut x = area.x;
487        let max_x = area.right();
488
489        // Draw guide characters for each depth level
490        if depth > 0 && deg.apply_styling() {
491            for d in 0..depth {
492                let is_last_at_depth = is_last.get(d).copied().unwrap_or(false);
493                let guide = if d == depth - 1 {
494                    // This is the immediate parent level
495                    if is_last_at_depth {
496                        self.guides.last()
497                    } else {
498                        self.guides.branch()
499                    }
500                } else {
501                    // Ancestor level: show vertical line or blank
502                    if is_last_at_depth {
503                        self.guides.space()
504                    } else {
505                        self.guides.vertical()
506                    }
507                };
508
509                x = draw_text_span(frame, x, y, guide, self.guide_style, max_x);
510            }
511        } else if depth > 0 {
512            // Minimal rendering: indent with spaces
513            // Avoid allocation by drawing chunks iteratively
514            for _ in 0..depth {
515                x = draw_text_span(frame, x, y, "    ", Style::default(), max_x);
516                if x >= max_x {
517                    break;
518                }
519            }
520        }
521
522        // Draw label
523        let style = if depth == 0 && self.show_root {
524            self.root_style
525        } else {
526            self.label_style
527        };
528        if let Some(icon) = node.icon() {
529            let icon_style = if deg.apply_styling() {
530                style
531            } else {
532                Style::default()
533            };
534            x = draw_text_span(frame, x, y, icon, icon_style, max_x);
535            if x < max_x {
536                x = draw_text_span(frame, x, y, " ", icon_style, max_x);
537            }
538        }
539
540        if deg.apply_styling() {
541            draw_text_span(frame, x, y, &node.label, style, max_x);
542        } else {
543            draw_text_span(frame, x, y, &node.label, Style::default(), max_x);
544        }
545
546        // Register hit region for the row
547        if let Some(id) = self.hit_id {
548            let row_area = Rect::new(area.x, y, area.width, 1);
549            frame.register_hit(row_area, id, HitRegion::Content, *current_row as u64);
550        }
551
552        *current_row += 1;
553
554        if !node.expanded {
555            return;
556        }
557
558        let child_count = node.children.len();
559        for (i, child) in node.children.iter().enumerate() {
560            if *current_row >= area.height as usize {
561                break;
562            }
563            is_last.push(i == child_count - 1);
564            self.render_node(child, depth + 1, is_last, area, frame, current_row, deg);
565            is_last.pop();
566        }
567    }
568}
569
570fn filter_node(node: &TreeNode, query_lower: &str) -> Option<TreeNode> {
571    let label_matches = crate::contains_ignore_case(&node.label, query_lower)
572        || node
573            .icon
574            .as_deref()
575            .is_some_and(|icon| crate::contains_ignore_case(icon, query_lower));
576
577    let mut filtered_children = Vec::new();
578    for child in &node.children {
579        if let Some(filtered) = filter_node(child, query_lower) {
580            filtered_children.push(filtered);
581        }
582    }
583
584    let mut filtered_lazy = Vec::new();
585    if let Some(lazy) = &node.lazy_children {
586        for child in lazy {
587            if let Some(filtered) = filter_node(child, query_lower) {
588                filtered_lazy.push(filtered);
589            }
590        }
591    }
592
593    if !label_matches && filtered_children.is_empty() && filtered_lazy.is_empty() {
594        return None;
595    }
596
597    let mut filtered = node.clone();
598    if label_matches {
599        // Search-mode render walks `children`, not `lazy_children`. When a node
600        // itself matches, render the same full subtree that path bookkeeping already
601        // exposes by eagerly materializing lazy descendants in the filtered clone.
602        filtered.materialize_all_lazy_children();
603        filtered.expanded = true;
604    } else {
605        // Materialize filtered lazy matches into `children` so render/flatten traversal,
606        // which walks `children`, includes lazy descendants that matched the query.
607        filtered.children = filtered_children;
608        filtered.children.extend(filtered_lazy);
609        filtered.lazy_children = None;
610        filtered.expanded = true;
611    }
612    Some(filtered)
613}
614
615struct FilteredPathNode {
616    expanded: bool,
617    children: Vec<(usize, FilteredPathNode)>,
618}
619
620fn create_unfiltered_path_node(node: &TreeNode) -> FilteredPathNode {
621    let mut children = Vec::new();
622    for (idx, child) in node.children.iter().enumerate() {
623        children.push((idx, create_unfiltered_path_node(child)));
624    }
625    let lazy_offset = node.children.len();
626    if let Some(lazy) = &node.lazy_children {
627        for (idx, child) in lazy.iter().enumerate() {
628            children.push((lazy_offset + idx, create_unfiltered_path_node(child)));
629        }
630    }
631    FilteredPathNode {
632        expanded: node.expanded,
633        children,
634    }
635}
636
637fn filter_node_paths(
638    node: &TreeNode,
639    query_lower: &str,
640) -> Option<(bool, Vec<(usize, FilteredPathNode)>)> {
641    let label_matches = crate::contains_ignore_case(&node.label, query_lower)
642        || node
643            .icon
644            .as_deref()
645            .is_some_and(|icon| crate::contains_ignore_case(icon, query_lower));
646
647    if label_matches {
648        let mut children = Vec::new();
649        for (idx, child) in node.children.iter().enumerate() {
650            children.push((idx, create_unfiltered_path_node(child)));
651        }
652        let lazy_offset = node.children.len();
653        if let Some(lazy) = &node.lazy_children {
654            for (idx, child) in lazy.iter().enumerate() {
655                children.push((lazy_offset + idx, create_unfiltered_path_node(child)));
656            }
657        }
658        return Some((true, children));
659    }
660
661    let mut filtered_children = Vec::new();
662    for (idx, child) in node.children.iter().enumerate() {
663        if let Some(filtered) = filter_node_paths(child, query_lower) {
664            filtered_children.push((
665                idx,
666                FilteredPathNode {
667                    expanded: filtered.0,
668                    children: filtered.1,
669                },
670            ));
671        }
672    }
673
674    let mut filtered_lazy = Vec::new();
675    let lazy_offset = node.children.len();
676    if let Some(lazy) = &node.lazy_children {
677        for (idx, child) in lazy.iter().enumerate() {
678            if let Some(filtered) = filter_node_paths(child, query_lower) {
679                filtered_lazy.push((
680                    lazy_offset + idx,
681                    FilteredPathNode {
682                        expanded: filtered.0,
683                        children: filtered.1,
684                    },
685                ));
686            }
687        }
688    }
689
690    if filtered_children.is_empty() && filtered_lazy.is_empty() {
691        return None;
692    }
693
694    filtered_children.extend(filtered_lazy);
695    Some((true, filtered_children))
696}
697
698impl Widget for Tree {
699    fn render(&self, area: Rect, frame: &mut Frame) {
700        if area.width == 0 || area.height == 0 {
701            return;
702        }
703
704        #[cfg(feature = "tracing")]
705        let render_start = Instant::now();
706        #[cfg(feature = "tracing")]
707        let total_nodes = self.total_nodes();
708        #[cfg(feature = "tracing")]
709        let visible_nodes = self.visible_nodes();
710        #[cfg(feature = "tracing")]
711        let expanded_count = self.expanded_nodes();
712        #[cfg(feature = "tracing")]
713        let render_span = tracing::debug_span!(
714            "tree.render",
715            total_nodes,
716            visible_nodes,
717            expanded_count,
718            render_duration_us = tracing::field::Empty,
719        );
720        #[cfg(feature = "tracing")]
721        let _render_guard = render_span.enter();
722
723        let deg = frame.buffer.degradation;
724        let base_style = if deg.apply_styling() {
725            self.label_style
726        } else {
727            Style::default()
728        };
729        clear_text_area(frame, area, base_style);
730        let mut current_row = 0;
731        let mut is_last = Vec::with_capacity(8);
732
733        let search_query = self
734            .search_query
735            .as_deref()
736            .filter(|q| !q.trim().is_empty());
737        let is_searching = search_query.is_some();
738        let filtered_root = if let Some(q) = search_query {
739            let query_lower = q.trim().to_lowercase();
740            filter_node(&self.root, &query_lower)
741        } else {
742            Some(self.root.clone())
743        };
744
745        if is_searching && filtered_root.is_none() {
746            #[cfg(feature = "tracing")]
747            {
748                let elapsed = render_start.elapsed();
749                let elapsed_us = elapsed.as_micros() as u64;
750                render_span.record("render_duration_us", elapsed_us);
751                tracing::debug!(
752                    render_duration_us = elapsed_us,
753                    "Tree render complete (empty search)"
754                );
755            }
756            return;
757        }
758
759        let root_fallback = self.root.clone();
760        let root = filtered_root.as_ref().unwrap_or(&root_fallback);
761
762        if self.show_root {
763            self.render_node(root, 0, &mut is_last, area, frame, &mut current_row, deg);
764        } else if root.expanded {
765            // If root is hidden but expanded, render children as top-level nodes.
766            // We do NOT push to is_last for the root level, effectively shifting
767            // the hierarchy up by one level.
768            let child_count = root.children.len();
769            for (i, child) in root.children.iter().enumerate() {
770                is_last.push(i == child_count - 1);
771                self.render_node(
772                    child,
773                    0, // Children become depth 0
774                    &mut is_last,
775                    area,
776                    frame,
777                    &mut current_row,
778                    deg,
779                );
780                is_last.pop();
781            }
782        }
783
784        #[cfg(feature = "tracing")]
785        {
786            let elapsed = render_start.elapsed();
787            let elapsed_us = elapsed.as_micros() as u64;
788            render_span.record("render_duration_us", elapsed_us);
789            tracing::debug!(
790                message = "tree.metrics",
791                tree_render_duration_us = elapsed_us,
792                total_nodes,
793                visible_nodes,
794                expanded_count
795            );
796        }
797    }
798
799    fn is_essential(&self) -> bool {
800        false
801    }
802}
803
804// ============================================================================
805// Stateful Persistence Implementation
806// ============================================================================
807
808/// Persistable state for a [`Tree`] widget.
809///
810/// Stores the set of expanded node paths to restore tree expansion state.
811#[derive(Clone, Debug, Default, PartialEq)]
812#[cfg_attr(
813    feature = "state-persistence",
814    derive(serde::Serialize, serde::Deserialize)
815)]
816pub struct TreePersistState {
817    /// Set of expanded node paths (e.g., "root/src/main.rs").
818    pub expanded_paths: HashSet<String>,
819}
820
821impl crate::stateful::Stateful for Tree {
822    type State = TreePersistState;
823
824    fn state_key(&self) -> Option<crate::stateful::StateKey> {
825        // No persistence_id, no identity: two unnamed trees must not share one.
826        self.persistence_id
827            .as_deref()
828            .map(|id| crate::stateful::StateKey::new("Tree", id))
829    }
830
831    fn save_state(&self) -> TreePersistState {
832        let mut expanded_paths = HashSet::new();
833        self.root.collect_expanded("", &mut expanded_paths);
834        TreePersistState { expanded_paths }
835    }
836
837    fn restore_state(&mut self, state: TreePersistState) {
838        self.root.apply_expanded("", &state.expanded_paths);
839    }
840}
841
842// ============================================================================
843// Undo Support Implementation
844// ============================================================================
845
846impl UndoSupport for Tree {
847    fn undo_widget_id(&self) -> UndoWidgetId {
848        self.undo_id
849    }
850
851    fn create_snapshot(&self) -> Box<dyn Any + Send> {
852        Box::new(self.save_state())
853    }
854
855    fn restore_snapshot(&mut self, snapshot: &dyn Any) -> bool {
856        if let Some(snap) = snapshot.downcast_ref::<TreePersistState>() {
857            self.restore_state(snap.clone());
858            true
859        } else {
860            false
861        }
862    }
863}
864
865impl TreeUndoExt for Tree {
866    fn is_node_expanded(&self, path: &[usize]) -> bool {
867        self.get_node_at_path(path)
868            .map(|node| node.is_expanded())
869            .unwrap_or(false)
870    }
871
872    fn expand_node(&mut self, path: &[usize]) {
873        if let Some(node) = self.get_node_at_path_mut(path) {
874            node.materialize_lazy_children();
875            node.expanded = true;
876        }
877    }
878
879    fn collapse_node(&mut self, path: &[usize]) {
880        if let Some(node) = self.get_node_at_path_mut(path) {
881            node.expanded = false;
882        }
883    }
884}
885
886impl Tree {
887    /// Get the undo widget ID for this tree.
888    #[must_use]
889    pub fn undo_id(&self) -> UndoWidgetId {
890        self.undo_id
891    }
892
893    /// Get a reference to a node at the given path (indices from root).
894    fn get_node_at_path(&self, path: &[usize]) -> Option<&TreeNode> {
895        let mut current = &self.root;
896        for &idx in path {
897            current = current.children.get(idx)?;
898        }
899        Some(current)
900    }
901
902    /// Get a mutable reference to a node at the given path (indices from root).
903    fn get_node_at_path_mut(&mut self, path: &[usize]) -> Option<&mut TreeNode> {
904        let mut current = &mut self.root;
905        for &idx in path {
906            current = current.children.get_mut(idx)?;
907        }
908        Some(current)
909    }
910
911    #[cfg(feature = "tracing")]
912    fn log_expand_collapse(action: &str, source: &str, index: usize, label: &str) {
913        tracing::debug!(
914            message = "tree.toggle",
915            action,
916            source,
917            visible_index = index,
918            label
919        );
920    }
921
922    fn toggle_node_at_visible_index(&mut self, index: usize, source: &str) -> bool {
923        #[cfg(not(feature = "tracing"))]
924        let _ = source;
925        let Some(node) = self.node_at_visible_index_mut(index) else {
926            return false;
927        };
928        if !node.has_children() {
929            return false;
930        }
931        #[cfg(feature = "tracing")]
932        let action = if node.is_expanded() {
933            "collapse"
934        } else {
935            "expand"
936        };
937        #[cfg(feature = "tracing")]
938        let label = node.label().to_owned();
939        node.toggle_expanded();
940        #[cfg(feature = "tracing")]
941        Self::log_expand_collapse(action, source, index, &label);
942        true
943    }
944
945    /// Handle keyboard navigation at the currently selected visible row.
946    ///
947    /// Supported keys:
948    /// - **Enter / Space**: Toggle expand/collapse on the selected node.
949    /// - **Right**: Expand the selected node (if collapsed and has children).
950    /// - **Left**: Collapse the selected node (if expanded).
951    ///
952    /// Returns `true` when an expand/collapse action was applied.
953    ///
954    /// Acts on press and repeat, never release. Terminals with the kitty
955    /// keyboard protocol's event types, and the web backend, report a release
956    /// for every key, so Enter toggled a node open and straight back shut.
957    pub fn handle_key(&mut self, key: &KeyEvent, selected_visible_index: usize) -> bool {
958        if key.kind == KeyEventKind::Release {
959            return false;
960        }
961        match key.code {
962            KeyCode::Enter | KeyCode::Char(' ') => {
963                self.toggle_node_at_visible_index(selected_visible_index, "keyboard")
964            }
965            KeyCode::Right => {
966                // Expand if collapsed and has children.
967                if let Some(node) = self.node_at_visible_index_mut(selected_visible_index)
968                    && !node.is_expanded()
969                    && node.has_children()
970                {
971                    #[cfg(feature = "tracing")]
972                    let label = node.label().to_owned();
973                    node.toggle_expanded();
974                    #[cfg(feature = "tracing")]
975                    Self::log_expand_collapse("expand", "keyboard", selected_visible_index, &label);
976                    return true;
977                }
978                false
979            }
980            KeyCode::Left => {
981                // Collapse if expanded.
982                if let Some(node) = self.node_at_visible_index_mut(selected_visible_index)
983                    && node.is_expanded()
984                    && node.has_children()
985                {
986                    #[cfg(feature = "tracing")]
987                    let label = node.label().to_owned();
988                    node.toggle_expanded();
989                    #[cfg(feature = "tracing")]
990                    Self::log_expand_collapse(
991                        "collapse",
992                        "keyboard",
993                        selected_visible_index,
994                        &label,
995                    );
996                    return true;
997                }
998                false
999            }
1000            _ => false,
1001        }
1002    }
1003
1004    /// Handle a mouse event for this tree.
1005    ///
1006    /// # Hit data convention
1007    ///
1008    /// The hit data (`u64`) encodes the flattened visible row index. When the
1009    /// tree renders with a `hit_id`, each visible row registers
1010    /// `HitRegion::Content` with `data = visible_row_index as u64`.
1011    ///
1012    /// Clicking a parent node (one with children) toggles its expanded state
1013    /// and returns `Activated`. Clicking a leaf returns `Selected`.
1014    ///
1015    /// # Arguments
1016    ///
1017    /// * `event` — the mouse event from the terminal
1018    /// * `hit` — result of `frame.hit_test(event.x, event.y)`, if available
1019    /// * `expected_id` — the `HitId` this tree was rendered with
1020    pub fn handle_mouse(
1021        &mut self,
1022        event: &MouseEvent,
1023        hit: Option<(HitId, HitRegion, u64)>,
1024        expected_id: HitId,
1025    ) -> MouseResult {
1026        match event.kind {
1027            MouseEventKind::Down(MouseButton::Left) => {
1028                if let Some((id, HitRegion::Content, data)) = hit
1029                    && id == expected_id
1030                {
1031                    let index = data as usize;
1032                    if let Some(node) = self.node_at_visible_index_mut(index)
1033                        && !node.has_children()
1034                    {
1035                        return MouseResult::Selected(index);
1036                    }
1037                    if self.toggle_node_at_visible_index(index, "mouse") {
1038                        return MouseResult::Activated(index);
1039                    }
1040                }
1041                MouseResult::Ignored
1042            }
1043            _ => MouseResult::Ignored,
1044        }
1045    }
1046
1047    /// Get a mutable reference to the node at the given visible (flattened) index.
1048    ///
1049    /// The traversal order matches `render_node()`: if `show_root` is true the
1050    /// root is row 0; otherwise children of the root are the top-level rows.
1051    /// Only expanded nodes' children are visited.
1052    pub fn node_at_visible_index_mut(&mut self, target: usize) -> Option<&mut TreeNode> {
1053        let path = self.find_path_indices_at_visible_index(target)?;
1054
1055        let mut current = &mut self.root;
1056        for &idx in &path {
1057            current.materialize_lazy_children();
1058            current = current.children.get_mut(idx)?;
1059        }
1060        Some(current)
1061    }
1062
1063    fn find_path_indices_at_visible_index(&self, target: usize) -> Option<Vec<usize>> {
1064        let query = self
1065            .search_query
1066            .as_deref()
1067            .map(str::trim)
1068            .filter(|q| !q.is_empty());
1069        let mut counter = 0usize;
1070        let mut path = Vec::new();
1071
1072        if let Some(q) = query {
1073            let query_lower = q.to_lowercase();
1074            let (expanded, children) = filter_node_paths(&self.root, &query_lower)?;
1075            let root_node = FilteredPathNode { expanded, children };
1076
1077            if self.show_root {
1078                Self::walk_filtered_path(&root_node, target, &mut counter, &mut path)
1079            } else if root_node.expanded {
1080                for &(idx, ref child) in &root_node.children {
1081                    path.push(idx);
1082                    if let Some(p) =
1083                        Self::walk_filtered_path(child, target, &mut counter, &mut path)
1084                    {
1085                        return Some(p);
1086                    }
1087                    path.pop();
1088                }
1089                None
1090            } else {
1091                None
1092            }
1093        } else {
1094            if self.show_root {
1095                Self::walk_visible_index_path(&self.root, target, &mut counter, &mut path)
1096            } else if self.root.expanded {
1097                for (idx, child) in self.root.children.iter().enumerate() {
1098                    path.push(idx);
1099                    if let Some(p) =
1100                        Self::walk_visible_index_path(child, target, &mut counter, &mut path)
1101                    {
1102                        return Some(p);
1103                    }
1104                    path.pop();
1105                }
1106                None
1107            } else {
1108                None
1109            }
1110        }
1111    }
1112
1113    fn walk_filtered_path(
1114        node: &FilteredPathNode,
1115        target: usize,
1116        counter: &mut usize,
1117        current_path: &mut Vec<usize>,
1118    ) -> Option<Vec<usize>> {
1119        if *counter == target {
1120            return Some(current_path.clone());
1121        }
1122        *counter += 1;
1123        if node.expanded {
1124            for &(idx, ref child) in &node.children {
1125                current_path.push(idx);
1126                if let Some(found) = Self::walk_filtered_path(child, target, counter, current_path)
1127                {
1128                    return Some(found);
1129                }
1130                current_path.pop();
1131            }
1132        }
1133        None
1134    }
1135
1136    fn walk_visible_index_path(
1137        node: &TreeNode,
1138        target: usize,
1139        counter: &mut usize,
1140        current_path: &mut Vec<usize>,
1141    ) -> Option<Vec<usize>> {
1142        if *counter == target {
1143            return Some(current_path.clone());
1144        }
1145        *counter += 1;
1146        if node.expanded {
1147            for (idx, child) in node.children.iter().enumerate() {
1148                current_path.push(idx);
1149                if let Some(found) =
1150                    Self::walk_visible_index_path(child, target, counter, current_path)
1151                {
1152                    return Some(found);
1153                }
1154                current_path.pop();
1155            }
1156        }
1157        None
1158    }
1159}
1160
1161// ---------------------------------------------------------------------------
1162// Test-only flatten helpers
1163// ---------------------------------------------------------------------------
1164
1165#[cfg(test)]
1166#[derive(Debug, Clone, PartialEq, Eq)]
1167struct FlatNode {
1168    label: String,
1169    depth: usize,
1170}
1171
1172#[cfg(test)]
1173fn flatten_visible(node: &TreeNode, depth: usize, out: &mut Vec<FlatNode>) {
1174    out.push(FlatNode {
1175        label: node.label.clone(),
1176        depth,
1177    });
1178    if node.expanded {
1179        for child in &node.children {
1180            flatten_visible(child, depth + 1, out);
1181        }
1182    }
1183}
1184
1185#[cfg(test)]
1186impl Tree {
1187    fn flatten(&self) -> Vec<FlatNode> {
1188        let mut out = Vec::new();
1189        let search_query = self
1190            .search_query
1191            .as_deref()
1192            .filter(|q| !q.trim().is_empty());
1193        let is_searching = search_query.is_some();
1194        let filtered_root = if let Some(q) = search_query {
1195            let query_lower = q.trim().to_lowercase();
1196            filter_node(&self.root, &query_lower)
1197        } else {
1198            Some(self.root.clone())
1199        };
1200
1201        if is_searching && filtered_root.is_none() {
1202            return out;
1203        }
1204
1205        let root_fallback = self.root.clone();
1206        let root = filtered_root.as_ref().unwrap_or(&root_fallback);
1207        if self.show_root {
1208            flatten_visible(root, 0, &mut out);
1209        } else if root.expanded {
1210            for child in &root.children {
1211                flatten_visible(child, 0, &mut out);
1212            }
1213        }
1214        out
1215    }
1216}
1217
1218#[cfg(test)]
1219mod tests {
1220    use super::*;
1221    use ftui_render::frame::Frame;
1222    use ftui_render::grapheme_pool::GraphemePool;
1223    #[cfg(feature = "tracing")]
1224    use std::sync::{Arc, Mutex};
1225    #[cfg(feature = "tracing")]
1226    use tracing::Subscriber;
1227    #[cfg(feature = "tracing")]
1228    use tracing_subscriber::Layer;
1229    #[cfg(feature = "tracing")]
1230    use tracing_subscriber::layer::{Context, SubscriberExt};
1231
1232    fn line_text(frame: &Frame, y: u16, width: u16) -> String {
1233        (0..width)
1234            .map(|x| {
1235                frame
1236                    .buffer
1237                    .get(x, y)
1238                    .and_then(|cell| cell.content.as_char())
1239                    .unwrap_or(' ')
1240            })
1241            .collect()
1242    }
1243
1244    fn simple_tree() -> TreeNode {
1245        TreeNode::new("root")
1246            .child(
1247                TreeNode::new("a")
1248                    .child(TreeNode::new("a1"))
1249                    .child(TreeNode::new("a2")),
1250            )
1251            .child(TreeNode::new("b"))
1252    }
1253
1254    #[cfg(feature = "tracing")]
1255    #[derive(Debug, Default)]
1256    struct TreeTraceState {
1257        tree_render_seen: bool,
1258        has_total_nodes_field: bool,
1259        has_visible_nodes_field: bool,
1260        has_expanded_count_field: bool,
1261        render_duration_recorded: bool,
1262        toggle_events: usize,
1263    }
1264
1265    #[cfg(feature = "tracing")]
1266    struct TreeTraceCapture {
1267        state: Arc<Mutex<TreeTraceState>>,
1268    }
1269
1270    #[cfg(feature = "tracing")]
1271    impl<S> Layer<S> for TreeTraceCapture
1272    where
1273        S: Subscriber + for<'lookup> tracing_subscriber::registry::LookupSpan<'lookup>,
1274    {
1275        fn on_new_span(
1276            &self,
1277            attrs: &tracing::span::Attributes<'_>,
1278            _id: &tracing::Id,
1279            _ctx: Context<'_, S>,
1280        ) {
1281            if attrs.metadata().name() != "tree.render" {
1282                return;
1283            }
1284            let fields = attrs.metadata().fields();
1285            let mut state = self.state.lock().expect("tree trace state lock");
1286            state.tree_render_seen = true;
1287            state.has_total_nodes_field |= fields.field("total_nodes").is_some();
1288            state.has_visible_nodes_field |= fields.field("visible_nodes").is_some();
1289            state.has_expanded_count_field |= fields.field("expanded_count").is_some();
1290        }
1291
1292        fn on_record(
1293            &self,
1294            id: &tracing::Id,
1295            values: &tracing::span::Record<'_>,
1296            ctx: Context<'_, S>,
1297        ) {
1298            let Some(span) = ctx.span(id) else {
1299                return;
1300            };
1301            if span.metadata().name() != "tree.render" {
1302                return;
1303            }
1304
1305            struct DurationVisitor {
1306                saw_duration: bool,
1307            }
1308            impl tracing::field::Visit for DurationVisitor {
1309                fn record_u64(&mut self, field: &tracing::field::Field, _value: u64) {
1310                    if field.name() == "render_duration_us" {
1311                        self.saw_duration = true;
1312                    }
1313                }
1314
1315                fn record_debug(
1316                    &mut self,
1317                    field: &tracing::field::Field,
1318                    _value: &dyn std::fmt::Debug,
1319                ) {
1320                    if field.name() == "render_duration_us" {
1321                        self.saw_duration = true;
1322                    }
1323                }
1324            }
1325
1326            let mut visitor = DurationVisitor {
1327                saw_duration: false,
1328            };
1329            values.record(&mut visitor);
1330            if visitor.saw_duration {
1331                self.state
1332                    .lock()
1333                    .expect("tree trace state lock")
1334                    .render_duration_recorded = true;
1335            }
1336        }
1337
1338        fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1339            struct MessageVisitor {
1340                message: Option<String>,
1341            }
1342            impl tracing::field::Visit for MessageVisitor {
1343                fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
1344                    if field.name() == "message" {
1345                        self.message = Some(value.to_owned());
1346                    }
1347                }
1348
1349                fn record_debug(
1350                    &mut self,
1351                    field: &tracing::field::Field,
1352                    value: &dyn std::fmt::Debug,
1353                ) {
1354                    if field.name() == "message" {
1355                        self.message = Some(format!("{value:?}").trim_matches('"').to_owned());
1356                    }
1357                }
1358            }
1359
1360            let mut visitor = MessageVisitor { message: None };
1361            event.record(&mut visitor);
1362            if visitor.message.as_deref() == Some("tree.toggle") {
1363                let mut state = self.state.lock().expect("tree trace state lock");
1364                state.toggle_events = state.toggle_events.saturating_add(1);
1365            }
1366        }
1367    }
1368
1369    #[test]
1370    fn tree_node_basics() {
1371        let node = TreeNode::new("hello");
1372        assert_eq!(node.label(), "hello");
1373        assert!(node.children().is_empty());
1374        assert!(node.is_expanded());
1375    }
1376
1377    #[test]
1378    fn tree_node_children() {
1379        let root = simple_tree();
1380        assert_eq!(root.children().len(), 2);
1381        assert_eq!(root.children()[0].label(), "a");
1382        assert_eq!(root.children()[0].children().len(), 2);
1383    }
1384
1385    #[test]
1386    fn tree_node_visible_count() {
1387        let root = simple_tree();
1388        // root + a + a1 + a2 + b = 5
1389        assert_eq!(root.visible_count(), 5);
1390    }
1391
1392    #[test]
1393    fn tree_node_collapsed() {
1394        let root = TreeNode::new("root")
1395            .child(
1396                TreeNode::new("a")
1397                    .with_expanded(false)
1398                    .child(TreeNode::new("a1"))
1399                    .child(TreeNode::new("a2")),
1400            )
1401            .child(TreeNode::new("b"));
1402        // root + a (collapsed, so no a1/a2) + b = 3
1403        assert_eq!(root.visible_count(), 3);
1404    }
1405
1406    #[test]
1407    fn tree_node_toggle() {
1408        let mut node = TreeNode::new("x");
1409        assert!(node.is_expanded());
1410        node.toggle_expanded();
1411        assert!(!node.is_expanded());
1412        node.toggle_expanded();
1413        assert!(node.is_expanded());
1414    }
1415
1416    #[test]
1417    fn tree_node_lazy_children_materialize_on_expand() {
1418        let mut node = TreeNode::new("root")
1419            .with_lazy_children(vec![TreeNode::new("child"), TreeNode::new("child2")]);
1420        assert!(!node.is_expanded());
1421        assert_eq!(node.children().len(), 0);
1422        assert!(node.has_children());
1423
1424        node.toggle_expanded();
1425        assert!(node.is_expanded());
1426        assert_eq!(node.children().len(), 2);
1427    }
1428
1429    #[test]
1430    fn tree_guides_unicode() {
1431        let g = TreeGuides::Unicode;
1432        assert!(g.branch().contains('├'));
1433        assert!(g.last().contains('└'));
1434        assert!(g.vertical().contains('│'));
1435    }
1436
1437    #[test]
1438    fn tree_guides_ascii() {
1439        let g = TreeGuides::Ascii;
1440        assert!(g.branch().contains('+'));
1441        assert!(g.vertical().contains('|'));
1442    }
1443
1444    #[test]
1445    fn tree_guides_width() {
1446        for g in [
1447            TreeGuides::Ascii,
1448            TreeGuides::Unicode,
1449            TreeGuides::Bold,
1450            TreeGuides::Double,
1451            TreeGuides::Rounded,
1452        ] {
1453            assert_eq!(g.width(), 4);
1454        }
1455    }
1456
1457    #[test]
1458    fn tree_render_basic() {
1459        let tree = Tree::new(simple_tree());
1460
1461        let mut pool = GraphemePool::new();
1462        let mut frame = Frame::new(40, 10, &mut pool);
1463        let area = Rect::new(0, 0, 40, 10);
1464        tree.render(area, &mut frame);
1465
1466        // Root label at (0, 0)
1467        let cell = frame.buffer.get(0, 0).unwrap();
1468        assert_eq!(cell.content.as_char(), Some('r'));
1469    }
1470
1471    #[test]
1472    fn tree_render_guides_present() {
1473        let tree = Tree::new(simple_tree()).with_guides(TreeGuides::Ascii);
1474
1475        let mut pool = GraphemePool::new();
1476        let mut frame = Frame::new(40, 10, &mut pool);
1477        let area = Rect::new(0, 0, 40, 10);
1478        tree.render(area, &mut frame);
1479
1480        // Row 1 should be child "a" with branch guide "+-- "
1481        // First char of guide at (0, 1)
1482        let cell = frame.buffer.get(0, 1).unwrap();
1483        assert_eq!(cell.content.as_char(), Some('+'));
1484    }
1485
1486    #[test]
1487    fn tree_render_last_guide() {
1488        let tree = Tree::new(
1489            TreeNode::new("root")
1490                .child(TreeNode::new("a"))
1491                .child(TreeNode::new("b")),
1492        )
1493        .with_guides(TreeGuides::Ascii);
1494
1495        let mut pool = GraphemePool::new();
1496        let mut frame = Frame::new(40, 10, &mut pool);
1497        let area = Rect::new(0, 0, 40, 10);
1498        tree.render(area, &mut frame);
1499
1500        // Row 1: "+-- a" (not last)
1501        let cell = frame.buffer.get(0, 1).unwrap();
1502        assert_eq!(cell.content.as_char(), Some('+'));
1503
1504        // Row 2: "`-- b" (last child)
1505        let cell = frame.buffer.get(0, 2).unwrap();
1506        assert_eq!(cell.content.as_char(), Some('`'));
1507    }
1508
1509    #[test]
1510    fn tree_render_icon_before_label() {
1511        let tree = Tree::new(TreeNode::new("root").with_icon(">"));
1512        let mut pool = GraphemePool::new();
1513        let mut frame = Frame::new(12, 2, &mut pool);
1514        tree.render(Rect::new(0, 0, 12, 2), &mut frame);
1515
1516        assert_eq!(
1517            frame.buffer.get(0, 0).and_then(|c| c.content.as_char()),
1518            Some('>')
1519        );
1520        assert_eq!(
1521            frame.buffer.get(2, 0).and_then(|c| c.content.as_char()),
1522            Some('r')
1523        );
1524    }
1525
1526    #[test]
1527    fn tree_search_query_filters_to_matching_branches() {
1528        let tree = Tree::new(
1529            TreeNode::new("root")
1530                .child(TreeNode::new("alpha").child(TreeNode::new("target-file")))
1531                .child(TreeNode::new("beta")),
1532        )
1533        .with_search_query("target");
1534
1535        let flat = tree.flatten();
1536        assert_eq!(flat.len(), 3);
1537        assert_eq!(flat[0].label, "root");
1538        assert_eq!(flat[1].label, "alpha");
1539        assert_eq!(flat[2].label, "target-file");
1540    }
1541
1542    #[test]
1543    fn tree_search_query_includes_lazy_matching_descendants() {
1544        let tree =
1545            Tree::new(TreeNode::new("root").child(
1546                TreeNode::new("alpha").with_lazy_children(vec![TreeNode::new("target-file")]),
1547            ))
1548            .with_search_query("target");
1549
1550        let flat = tree.flatten();
1551        assert_eq!(flat.len(), 3);
1552        assert_eq!(flat[0].label, "root");
1553        assert_eq!(flat[1].label, "alpha");
1554        assert_eq!(flat[2].label, "target-file");
1555    }
1556
1557    #[test]
1558    fn tree_search_query_on_matching_parent_includes_immediate_lazy_children() {
1559        let tree = Tree::new(TreeNode::new("root").child(
1560            TreeNode::new("alpha").with_lazy_children(vec![
1561                TreeNode::new("lazy-child")
1562                    .with_lazy_children(vec![TreeNode::new("deep-grandchild")]),
1563            ]),
1564        ))
1565        .with_search_query("alpha");
1566
1567        let flat = tree.flatten();
1568        assert_eq!(flat.len(), 3);
1569        assert_eq!(flat[0].label, "root");
1570        assert_eq!(flat[1].label, "alpha");
1571        assert_eq!(flat[2].label, "lazy-child");
1572    }
1573
1574    #[test]
1575    fn tree_render_zero_area() {
1576        let tree = Tree::new(simple_tree());
1577        let mut pool = GraphemePool::new();
1578        let mut frame = Frame::new(40, 10, &mut pool);
1579        tree.render(Rect::new(0, 0, 0, 0), &mut frame); // No panic
1580    }
1581
1582    #[test]
1583    fn tree_render_shorter_label_clears_stale_suffix() {
1584        let mut pool = GraphemePool::new();
1585        let mut frame = Frame::new(20, 3, &mut pool);
1586        let area = Rect::new(0, 0, 20, 3);
1587
1588        Tree::new(TreeNode::new("root-with-long-tail")).render(area, &mut frame);
1589        Tree::new(TreeNode::new("r")).render(area, &mut frame);
1590
1591        assert_eq!(line_text(&frame, 0, 20), "r                   ");
1592        assert_eq!(line_text(&frame, 1, 20), "                    ");
1593        assert_eq!(line_text(&frame, 2, 20), "                    ");
1594    }
1595
1596    #[test]
1597    fn tree_render_truncated_height() {
1598        let tree = Tree::new(simple_tree());
1599        let mut pool = GraphemePool::new();
1600        let mut frame = Frame::new(40, 2, &mut pool);
1601        let area = Rect::new(0, 0, 40, 2);
1602        tree.render(area, &mut frame); // Only first 2 rows render, no panic
1603    }
1604
1605    #[test]
1606    fn is_not_essential() {
1607        let tree = Tree::new(TreeNode::new("x"));
1608        assert!(!tree.is_essential());
1609    }
1610
1611    #[test]
1612    fn tree_root_access() {
1613        let mut tree = Tree::new(TreeNode::new("root"));
1614        assert_eq!(tree.root().label(), "root");
1615        tree.root_mut().toggle_expanded();
1616        assert!(!tree.root().is_expanded());
1617    }
1618
1619    #[test]
1620    fn tree_guides_default() {
1621        let g = TreeGuides::default();
1622        assert_eq!(g, TreeGuides::Unicode);
1623    }
1624
1625    #[test]
1626    fn tree_guides_rounded() {
1627        let g = TreeGuides::Rounded;
1628        assert!(g.last().contains('╰'));
1629    }
1630
1631    #[test]
1632    fn tree_deep_nesting() {
1633        let node = TreeNode::new("d3");
1634        let node = TreeNode::new("d2").child(node);
1635        let node = TreeNode::new("d1").child(node);
1636        let root = TreeNode::new("root").child(node);
1637
1638        let tree = Tree::new(root);
1639        let flat = tree.flatten();
1640        assert_eq!(flat.len(), 4);
1641        assert_eq!(flat[3].depth, 3);
1642    }
1643
1644    #[test]
1645    fn tree_node_with_children_vec() {
1646        let root = TreeNode::new("root").with_children(vec![
1647            TreeNode::new("a"),
1648            TreeNode::new("b"),
1649            TreeNode::new("c"),
1650        ]);
1651        assert_eq!(root.children().len(), 3);
1652    }
1653
1654    // --- Stateful Persistence tests ---
1655
1656    use crate::stateful::Stateful;
1657
1658    #[test]
1659    fn tree_with_persistence_id() {
1660        let tree = Tree::new(TreeNode::new("root")).with_persistence_id("file-tree");
1661        assert_eq!(tree.persistence_id(), Some("file-tree"));
1662    }
1663
1664    #[test]
1665    fn tree_default_no_persistence_id() {
1666        let tree = Tree::new(TreeNode::new("root"));
1667        assert_eq!(tree.persistence_id(), None);
1668    }
1669
1670    #[test]
1671    fn tree_save_restore_round_trip() {
1672        // Create tree with some nodes expanded, some collapsed
1673        let mut tree = Tree::new(
1674            TreeNode::new("root")
1675                .child(
1676                    TreeNode::new("src")
1677                        .child(TreeNode::new("main.rs"))
1678                        .child(TreeNode::new("lib.rs")),
1679                )
1680                .child(TreeNode::new("tests").with_expanded(false)),
1681        )
1682        .with_persistence_id("test");
1683
1684        // Verify initial state: root and src expanded, tests collapsed
1685        assert!(tree.root().is_expanded());
1686        assert!(tree.root().children()[0].is_expanded()); // src
1687        assert!(!tree.root().children()[1].is_expanded()); // tests
1688
1689        let saved = tree.save_state();
1690
1691        // Verify saved state captures expanded nodes
1692        assert!(saved.expanded_paths.contains("root"));
1693        assert!(saved.expanded_paths.contains("root/src"));
1694        assert!(!saved.expanded_paths.contains("root/tests"));
1695
1696        // Modify tree state (collapse src)
1697        tree.root_mut().children[0].toggle_expanded();
1698        assert!(!tree.root().children()[0].is_expanded());
1699
1700        // Restore
1701        tree.restore_state(saved);
1702
1703        // Verify restored state
1704        assert!(tree.root().is_expanded());
1705        assert!(tree.root().children()[0].is_expanded()); // src restored
1706        assert!(!tree.root().children()[1].is_expanded()); // tests still collapsed
1707    }
1708
1709    #[test]
1710    fn tree_state_key_uses_persistence_id() {
1711        let tree = Tree::new(TreeNode::new("root")).with_persistence_id("project-explorer");
1712        let key = tree.state_key().expect("named tree has a key");
1713        assert_eq!(key.widget_type, "Tree");
1714        assert_eq!(key.instance_id, "project-explorer");
1715    }
1716
1717    #[test]
1718    fn tree_without_id_is_not_persisted() {
1719        assert!(Tree::new(TreeNode::new("root")).state_key().is_none());
1720    }
1721
1722    #[test]
1723    fn tree_persist_state_default() {
1724        let persist = TreePersistState::default();
1725        assert!(persist.expanded_paths.is_empty());
1726    }
1727
1728    #[test]
1729    fn tree_collect_expanded_only_includes_nodes_with_children() {
1730        let tree = Tree::new(
1731            TreeNode::new("root").child(TreeNode::new("leaf")), // leaf has no children
1732        );
1733
1734        let saved = tree.save_state();
1735
1736        // Only root is expanded (and has children)
1737        assert!(saved.expanded_paths.contains("root"));
1738        // leaf has no children, so it's not tracked
1739        assert!(!saved.expanded_paths.contains("root/leaf"));
1740    }
1741
1742    // ============================================================================
1743    // Undo Support Tests
1744    // ============================================================================
1745
1746    #[test]
1747    fn tree_undo_widget_id_unique() {
1748        let tree1 = Tree::new(TreeNode::new("root1"));
1749        let tree2 = Tree::new(TreeNode::new("root2"));
1750        assert_ne!(tree1.undo_id(), tree2.undo_id());
1751    }
1752
1753    #[test]
1754    fn tree_undo_snapshot_and_restore() {
1755        // Nodes must have children for their expanded state to be tracked
1756        let mut tree = Tree::new(
1757            TreeNode::new("root")
1758                .child(
1759                    TreeNode::new("a")
1760                        .with_expanded(true)
1761                        .child(TreeNode::new("a_child")),
1762                )
1763                .child(
1764                    TreeNode::new("b")
1765                        .with_expanded(false)
1766                        .child(TreeNode::new("b_child")),
1767                ),
1768        );
1769
1770        // Create snapshot
1771        let snapshot = tree.create_snapshot();
1772
1773        // Verify initial state
1774        assert!(tree.is_node_expanded(&[0])); // a
1775        assert!(!tree.is_node_expanded(&[1])); // b
1776
1777        // Modify state
1778        tree.collapse_node(&[0]); // collapse a
1779        tree.expand_node(&[1]); // expand b
1780        assert!(!tree.is_node_expanded(&[0]));
1781        assert!(tree.is_node_expanded(&[1]));
1782
1783        // Restore snapshot
1784        assert!(tree.restore_snapshot(&*snapshot));
1785
1786        // Verify restored state
1787        assert!(tree.is_node_expanded(&[0])); // a back to expanded
1788        assert!(!tree.is_node_expanded(&[1])); // b back to collapsed
1789    }
1790
1791    #[test]
1792    fn tree_expand_collapse_node() {
1793        let mut tree =
1794            Tree::new(TreeNode::new("root").child(TreeNode::new("child").with_expanded(true)));
1795
1796        // Initial state
1797        assert!(tree.is_node_expanded(&[0]));
1798
1799        // Collapse
1800        tree.collapse_node(&[0]);
1801        assert!(!tree.is_node_expanded(&[0]));
1802
1803        // Expand again
1804        tree.expand_node(&[0]);
1805        assert!(tree.is_node_expanded(&[0]));
1806    }
1807
1808    #[test]
1809    fn tree_node_path_navigation() {
1810        let tree = Tree::new(
1811            TreeNode::new("root")
1812                .child(
1813                    TreeNode::new("a")
1814                        .child(TreeNode::new("a1"))
1815                        .child(TreeNode::new("a2")),
1816                )
1817                .child(TreeNode::new("b")),
1818        );
1819
1820        // Test path navigation
1821        assert_eq!(tree.get_node_at_path(&[]).map(|n| n.label()), Some("root"));
1822        assert_eq!(tree.get_node_at_path(&[0]).map(|n| n.label()), Some("a"));
1823        assert_eq!(tree.get_node_at_path(&[1]).map(|n| n.label()), Some("b"));
1824        assert_eq!(
1825            tree.get_node_at_path(&[0, 0]).map(|n| n.label()),
1826            Some("a1")
1827        );
1828        assert_eq!(
1829            tree.get_node_at_path(&[0, 1]).map(|n| n.label()),
1830            Some("a2")
1831        );
1832        assert!(tree.get_node_at_path(&[5]).is_none()); // Invalid path
1833    }
1834
1835    #[test]
1836    fn tree_restore_wrong_snapshot_type_fails() {
1837        use std::any::Any;
1838        let mut tree = Tree::new(TreeNode::new("root"));
1839        let wrong_snapshot: Box<dyn Any + Send> = Box::new(42i32);
1840        assert!(!tree.restore_snapshot(&*wrong_snapshot));
1841    }
1842
1843    // --- Mouse handling tests ---
1844
1845    use crate::mouse::MouseResult;
1846    use ftui_core::event::{KeyCode, KeyEvent, MouseButton, MouseEvent, MouseEventKind};
1847
1848    #[test]
1849    fn tree_click_expands_parent() {
1850        let mut tree = Tree::new(
1851            TreeNode::new("root")
1852                .child(
1853                    TreeNode::new("a")
1854                        .child(TreeNode::new("a1"))
1855                        .child(TreeNode::new("a2")),
1856                )
1857                .child(TreeNode::new("b")),
1858        );
1859        assert!(tree.root().children()[0].is_expanded());
1860
1861        // Click on row 1 which is node "a" (a parent node)
1862        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 1);
1863        let hit = Some((HitId::new(1), HitRegion::Content, 1u64));
1864        let result = tree.handle_mouse(&event, hit, HitId::new(1));
1865        assert_eq!(result, MouseResult::Activated(1));
1866        assert!(!tree.root().children()[0].is_expanded()); // toggled to collapsed
1867    }
1868
1869    #[test]
1870    fn tree_click_selects_leaf() {
1871        let mut tree = Tree::new(
1872            TreeNode::new("root")
1873                .child(
1874                    TreeNode::new("a")
1875                        .child(TreeNode::new("a1"))
1876                        .child(TreeNode::new("a2")),
1877                )
1878                .child(TreeNode::new("b")),
1879        );
1880
1881        // Row 4 is "b" (a leaf): root=0, a=1, a1=2, a2=3, b=4
1882        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 5, 4);
1883        let hit = Some((HitId::new(1), HitRegion::Content, 4u64));
1884        let result = tree.handle_mouse(&event, hit, HitId::new(1));
1885        assert_eq!(result, MouseResult::Selected(4));
1886    }
1887
1888    #[test]
1889    fn tree_click_wrong_id_ignored() {
1890        let mut tree = Tree::new(TreeNode::new("root").child(TreeNode::new("a")));
1891        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1892        let hit = Some((HitId::new(99), HitRegion::Content, 0u64));
1893        let result = tree.handle_mouse(&event, hit, HitId::new(1));
1894        assert_eq!(result, MouseResult::Ignored);
1895    }
1896
1897    #[test]
1898    fn tree_click_no_hit_ignored() {
1899        let mut tree = Tree::new(TreeNode::new("root"));
1900        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 0);
1901        let result = tree.handle_mouse(&event, None, HitId::new(1));
1902        assert_eq!(result, MouseResult::Ignored);
1903    }
1904
1905    #[test]
1906    fn tree_right_click_ignored() {
1907        let mut tree = Tree::new(TreeNode::new("root").child(TreeNode::new("a")));
1908        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Right), 0, 0);
1909        let hit = Some((HitId::new(1), HitRegion::Content, 0u64));
1910        let result = tree.handle_mouse(&event, hit, HitId::new(1));
1911        assert_eq!(result, MouseResult::Ignored);
1912    }
1913
1914    #[test]
1915    fn tree_node_at_visible_index_with_show_root() {
1916        let mut tree = Tree::new(
1917            TreeNode::new("root")
1918                .child(
1919                    TreeNode::new("a")
1920                        .child(TreeNode::new("a1"))
1921                        .child(TreeNode::new("a2")),
1922                )
1923                .child(TreeNode::new("b")),
1924        );
1925
1926        // Visible order: root=0, a=1, a1=2, a2=3, b=4
1927        assert_eq!(
1928            tree.node_at_visible_index_mut(0)
1929                .map(|n| n.label().to_string()),
1930            Some("root".to_string())
1931        );
1932        assert_eq!(
1933            tree.node_at_visible_index_mut(1)
1934                .map(|n| n.label().to_string()),
1935            Some("a".to_string())
1936        );
1937        assert_eq!(
1938            tree.node_at_visible_index_mut(2)
1939                .map(|n| n.label().to_string()),
1940            Some("a1".to_string())
1941        );
1942        assert_eq!(
1943            tree.node_at_visible_index_mut(3)
1944                .map(|n| n.label().to_string()),
1945            Some("a2".to_string())
1946        );
1947        assert_eq!(
1948            tree.node_at_visible_index_mut(4)
1949                .map(|n| n.label().to_string()),
1950            Some("b".to_string())
1951        );
1952        assert!(tree.node_at_visible_index_mut(5).is_none());
1953    }
1954
1955    #[test]
1956    fn tree_node_at_visible_index_hidden_root() {
1957        let mut tree = Tree::new(
1958            TreeNode::new("root")
1959                .child(TreeNode::new("a").child(TreeNode::new("a1")))
1960                .child(TreeNode::new("b")),
1961        )
1962        .with_show_root(false);
1963
1964        // Root hidden: a=0, a1=1, b=2
1965        assert_eq!(
1966            tree.node_at_visible_index_mut(0)
1967                .map(|n| n.label().to_string()),
1968            Some("a".to_string())
1969        );
1970        assert_eq!(
1971            tree.node_at_visible_index_mut(1)
1972                .map(|n| n.label().to_string()),
1973            Some("a1".to_string())
1974        );
1975        assert_eq!(
1976            tree.node_at_visible_index_mut(2)
1977                .map(|n| n.label().to_string()),
1978            Some("b".to_string())
1979        );
1980        assert!(tree.node_at_visible_index_mut(3).is_none());
1981    }
1982
1983    #[test]
1984    fn tree_node_at_visible_index_collapsed() {
1985        let mut tree = Tree::new(
1986            TreeNode::new("root")
1987                .child(
1988                    TreeNode::new("a")
1989                        .with_expanded(false)
1990                        .child(TreeNode::new("a1"))
1991                        .child(TreeNode::new("a2")),
1992                )
1993                .child(TreeNode::new("b")),
1994        );
1995
1996        // root=0, a=1 (collapsed, so a1/a2 hidden), b=2
1997        assert_eq!(
1998            tree.node_at_visible_index_mut(0)
1999                .map(|n| n.label().to_string()),
2000            Some("root".to_string())
2001        );
2002        assert_eq!(
2003            tree.node_at_visible_index_mut(1)
2004                .map(|n| n.label().to_string()),
2005            Some("a".to_string())
2006        );
2007        assert_eq!(
2008            tree.node_at_visible_index_mut(2)
2009                .map(|n| n.label().to_string()),
2010            Some("b".to_string())
2011        );
2012        assert!(tree.node_at_visible_index_mut(3).is_none());
2013    }
2014
2015    #[test]
2016    fn tree_click_toggles_collapsed_node() {
2017        let mut tree = Tree::new(
2018            TreeNode::new("root")
2019                .child(
2020                    TreeNode::new("a")
2021                        .with_expanded(false)
2022                        .child(TreeNode::new("a1")),
2023                )
2024                .child(TreeNode::new("b")),
2025        );
2026        assert!(!tree.root().children()[0].is_expanded());
2027
2028        // Click on "a" (row 1) to expand it
2029        let event = MouseEvent::new(MouseEventKind::Down(MouseButton::Left), 0, 1);
2030        let hit = Some((HitId::new(1), HitRegion::Content, 1u64));
2031        let result = tree.handle_mouse(&event, hit, HitId::new(1));
2032        assert_eq!(result, MouseResult::Activated(1));
2033        assert!(tree.root().children()[0].is_expanded()); // now expanded
2034    }
2035
2036    #[test]
2037    fn tree_handle_key_enter_toggles_parent() {
2038        let mut tree = Tree::new(
2039            TreeNode::new("root")
2040                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2041                .child(TreeNode::new("b")),
2042        );
2043
2044        // root=0, a=1, a1=2, b=3
2045        assert!(tree.root().children()[0].is_expanded());
2046        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Enter), 1));
2047        assert!(!tree.root().children()[0].is_expanded());
2048        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Char(' ')), 1));
2049        assert!(tree.root().children()[0].is_expanded());
2050    }
2051
2052    #[test]
2053    fn tree_handle_key_ignores_key_release() {
2054        // With release events reported, Enter collapsed the node on press
2055        // and expanded it again on release.
2056        let mut tree = Tree::new(
2057            TreeNode::new("root")
2058                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2059                .child(TreeNode::new("b")),
2060        );
2061        let enter = KeyEvent::new(KeyCode::Enter);
2062        assert!(tree.handle_key(&enter, 1));
2063        assert!(!tree.handle_key(&enter.with_kind(KeyEventKind::Release), 1));
2064        assert!(!tree.root().children()[0].is_expanded());
2065    }
2066
2067    // =========================================================================
2068    // Keyboard navigation tests (bd-1lg.26)
2069    // =========================================================================
2070
2071    #[test]
2072    fn tree_handle_key_right_expands_collapsed_node() {
2073        let mut tree = Tree::new(
2074            TreeNode::new("root")
2075                .child(
2076                    TreeNode::new("a")
2077                        .with_expanded(false)
2078                        .child(TreeNode::new("a1")),
2079                )
2080                .child(TreeNode::new("b")),
2081        );
2082        assert!(!tree.root().children()[0].is_expanded());
2083
2084        // Right arrow on collapsed parent should expand it.
2085        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Right), 1));
2086        assert!(tree.root().children()[0].is_expanded());
2087    }
2088
2089    #[test]
2090    fn tree_handle_key_right_on_expanded_node_is_noop() {
2091        let mut tree = Tree::new(
2092            TreeNode::new("root")
2093                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2094                .child(TreeNode::new("b")),
2095        );
2096        assert!(tree.root().children()[0].is_expanded());
2097
2098        // Right arrow on already-expanded node should be no-op.
2099        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Right), 1));
2100        assert!(tree.root().children()[0].is_expanded());
2101    }
2102
2103    #[test]
2104    fn tree_handle_key_right_on_leaf_is_noop() {
2105        let mut tree = Tree::new(
2106            TreeNode::new("root")
2107                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2108                .child(TreeNode::new("b")),
2109        );
2110
2111        // Right arrow on leaf node "b" (index 3) should be no-op.
2112        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Right), 3));
2113    }
2114
2115    #[test]
2116    fn tree_handle_key_left_collapses_expanded_node() {
2117        let mut tree = Tree::new(
2118            TreeNode::new("root")
2119                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2120                .child(TreeNode::new("b")),
2121        );
2122        assert!(tree.root().children()[0].is_expanded());
2123
2124        // Left arrow on expanded parent should collapse it.
2125        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Left), 1));
2126        assert!(!tree.root().children()[0].is_expanded());
2127    }
2128
2129    #[test]
2130    fn tree_handle_key_left_on_collapsed_node_is_noop() {
2131        let mut tree = Tree::new(
2132            TreeNode::new("root")
2133                .child(
2134                    TreeNode::new("a")
2135                        .with_expanded(false)
2136                        .child(TreeNode::new("a1")),
2137                )
2138                .child(TreeNode::new("b")),
2139        );
2140        assert!(!tree.root().children()[0].is_expanded());
2141
2142        // Left arrow on already-collapsed node should be no-op.
2143        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Left), 1));
2144        assert!(!tree.root().children()[0].is_expanded());
2145    }
2146
2147    #[test]
2148    fn tree_handle_key_left_on_leaf_is_noop() {
2149        let mut tree = Tree::new(
2150            TreeNode::new("root")
2151                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2152                .child(TreeNode::new("b")),
2153        );
2154
2155        // Left arrow on leaf node "b" (index 3) should be no-op.
2156        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Left), 3));
2157    }
2158
2159    #[test]
2160    fn tree_handle_key_left_right_round_trip() {
2161        let mut tree = Tree::new(
2162            TreeNode::new("root")
2163                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2164                .child(TreeNode::new("b")),
2165        );
2166
2167        // Collapse with Left.
2168        assert!(tree.root().children()[0].is_expanded());
2169        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Left), 1));
2170        assert!(!tree.root().children()[0].is_expanded());
2171
2172        // Expand with Right.
2173        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Right), 1));
2174        assert!(tree.root().children()[0].is_expanded());
2175    }
2176
2177    #[test]
2178    fn tree_handle_key_unhandled_keys_return_false() {
2179        let mut tree = Tree::new(
2180            TreeNode::new("root")
2181                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2182                .child(TreeNode::new("b")),
2183        );
2184
2185        // Up/Down are not handled by the tree widget (caller manages selection).
2186        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Up), 1));
2187        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Down), 1));
2188        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Tab), 1));
2189        assert!(!tree.handle_key(&KeyEvent::new(KeyCode::Escape), 1));
2190    }
2191
2192    #[test]
2193    fn tree_visible_index_navigation_after_collapse() {
2194        let mut tree = Tree::new(
2195            TreeNode::new("root")
2196                .child(
2197                    TreeNode::new("a")
2198                        .child(TreeNode::new("a1"))
2199                        .child(TreeNode::new("a2")),
2200                )
2201                .child(TreeNode::new("b")),
2202        );
2203
2204        // Before collapse: root=0, a=1, a1=2, a2=3, b=4
2205        assert_eq!(
2206            tree.node_at_visible_index_mut(4)
2207                .map(|n| n.label().to_string()),
2208            Some("b".to_string())
2209        );
2210
2211        // Collapse "a" with Left key
2212        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Left), 1));
2213
2214        // After collapse: root=0, a=1, b=2
2215        assert_eq!(
2216            tree.node_at_visible_index_mut(2)
2217                .map(|n| n.label().to_string()),
2218            Some("b".to_string())
2219        );
2220        assert!(tree.node_at_visible_index_mut(3).is_none());
2221    }
2222
2223    // =========================================================================
2224    // Lazy loading tests (bd-1lg.26)
2225    // =========================================================================
2226
2227    #[test]
2228    fn tree_lazy_children_materialized_visible_count() {
2229        let mut node = TreeNode::new("root").with_lazy_children(vec![
2230            TreeNode::new("child1").child(TreeNode::new("grandchild")),
2231            TreeNode::new("child2"),
2232        ]);
2233
2234        // Before expand: only root visible.
2235        assert_eq!(node.visible_count(), 1);
2236
2237        // Expand → lazy children materialize.
2238        node.toggle_expanded();
2239        // root + child1 (expanded) + grandchild + child2 = 4
2240        assert_eq!(node.visible_count(), 4);
2241    }
2242
2243    #[test]
2244    fn tree_lazy_children_second_toggle_collapses() {
2245        let mut node = TreeNode::new("root")
2246            .with_lazy_children(vec![TreeNode::new("child1"), TreeNode::new("child2")]);
2247
2248        // Expand.
2249        node.toggle_expanded();
2250        assert!(node.is_expanded());
2251        assert_eq!(node.children().len(), 2);
2252
2253        // Collapse. Children stay materialized but hidden.
2254        node.toggle_expanded();
2255        assert!(!node.is_expanded());
2256        assert_eq!(node.children().len(), 2); // still there
2257        assert_eq!(node.visible_count(), 1); // only root visible
2258    }
2259
2260    #[test]
2261    fn tree_lazy_children_with_right_key() {
2262        let mut tree = Tree::new(TreeNode::new("root").child(
2263            TreeNode::new("lazy-parent").with_lazy_children(vec![TreeNode::new("lazy-child")]),
2264        ));
2265
2266        // root=0, lazy-parent=1 (collapsed, has lazy children)
2267        assert!(!tree.root().children()[0].is_expanded());
2268        assert!(tree.root().children()[0].has_children());
2269
2270        // Right key should expand and materialize lazy children.
2271        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Right), 1));
2272        assert!(tree.root().children()[0].is_expanded());
2273        assert_eq!(tree.root().children()[0].children().len(), 1);
2274        assert_eq!(
2275            tree.root().children()[0].children()[0].label(),
2276            "lazy-child"
2277        );
2278    }
2279
2280    // =========================================================================
2281    // Search filter tests (bd-1lg.26)
2282    // =========================================================================
2283
2284    #[test]
2285    fn tree_search_case_insensitive() {
2286        let tree = Tree::new(
2287            TreeNode::new("root")
2288                .child(TreeNode::new("Alpha"))
2289                .child(TreeNode::new("Beta")),
2290        )
2291        .with_search_query("alpha");
2292
2293        let flat = tree.flatten();
2294        assert_eq!(flat.len(), 2); // root + Alpha
2295        assert_eq!(flat[1].label, "Alpha");
2296    }
2297
2298    #[test]
2299    fn tree_search_no_match_returns_empty() {
2300        let tree = Tree::new(
2301            TreeNode::new("root")
2302                .child(TreeNode::new("Alpha"))
2303                .child(TreeNode::new("Beta")),
2304        )
2305        .with_search_query("zzz-no-match");
2306
2307        let flat = tree.flatten();
2308        // When nothing matches (including root), filter_node returns None,
2309        // so flatten should return an empty tree.
2310        assert_eq!(flat.len(), 0);
2311    }
2312
2313    #[test]
2314    fn tree_search_no_match_clears_stale_rows() {
2315        let base_tree = Tree::new(
2316            TreeNode::new("root")
2317                .child(TreeNode::new("Alpha"))
2318                .child(TreeNode::new("Beta")),
2319        );
2320        let filtered_tree = Tree::new(
2321            TreeNode::new("root")
2322                .child(TreeNode::new("Alpha"))
2323                .child(TreeNode::new("Beta")),
2324        )
2325        .with_search_query("zzz-no-match");
2326
2327        let mut pool = GraphemePool::new();
2328        let mut frame = Frame::new(20, 4, &mut pool);
2329        let area = Rect::new(0, 0, 20, 4);
2330
2331        base_tree.render(area, &mut frame);
2332        filtered_tree.render(area, &mut frame);
2333
2334        assert_eq!(line_text(&frame, 0, 20), "                    ");
2335        assert_eq!(line_text(&frame, 1, 20), "                    ");
2336        assert_eq!(line_text(&frame, 2, 20), "                    ");
2337        assert_eq!(line_text(&frame, 3, 20), "                    ");
2338    }
2339
2340    #[test]
2341    fn tree_search_cleared() {
2342        let tree = Tree::new(
2343            TreeNode::new("root")
2344                .child(TreeNode::new("Alpha"))
2345                .child(TreeNode::new("Beta")),
2346        )
2347        .with_search_query("alpha")
2348        .without_search_query();
2349
2350        let flat = tree.flatten();
2351        assert_eq!(flat.len(), 3); // root + Alpha + Beta
2352    }
2353
2354    // =========================================================================
2355    // Expansion state correctness (bd-1lg.26)
2356    // =========================================================================
2357
2358    #[test]
2359    fn tree_expand_deep_nesting() {
2360        let mut tree = Tree::new(
2361            TreeNode::new("root").child(
2362                TreeNode::new("d1").with_expanded(false).child(
2363                    TreeNode::new("d2")
2364                        .with_expanded(false)
2365                        .child(TreeNode::new("d3")),
2366                ),
2367            ),
2368        );
2369
2370        // Initially: root + d1 (collapsed) = 2 visible
2371        assert_eq!(tree.root().visible_count(), 2);
2372
2373        // Expand d1
2374        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Right), 1));
2375        // root + d1 + d2 (collapsed) = 3 visible
2376        assert_eq!(tree.root().visible_count(), 3);
2377
2378        // Expand d2 (now at index 2)
2379        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Right), 2));
2380        // root + d1 + d2 + d3 = 4 visible
2381        assert_eq!(tree.root().visible_count(), 4);
2382    }
2383
2384    #[test]
2385    fn tree_collapse_parent_hides_all_descendants() {
2386        let mut tree = Tree::new(
2387            TreeNode::new("root")
2388                .child(
2389                    TreeNode::new("a")
2390                        .child(TreeNode::new("a1").child(TreeNode::new("a1x")))
2391                        .child(TreeNode::new("a2")),
2392                )
2393                .child(TreeNode::new("b")),
2394        );
2395
2396        // All expanded: root + a + a1 + a1x + a2 + b = 6
2397        assert_eq!(tree.root().visible_count(), 6);
2398
2399        // Collapse "a" → hides a1, a1x, a2
2400        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Left), 1));
2401        // root + a (collapsed) + b = 3
2402        assert_eq!(tree.root().visible_count(), 3);
2403    }
2404
2405    #[cfg(feature = "tracing")]
2406    #[test]
2407    fn tree_tracing_span_and_toggle_events_are_emitted() {
2408        let trace_state = Arc::new(Mutex::new(TreeTraceState::default()));
2409        let _trace_test_guard = crate::tracing_test_support::acquire();
2410        let subscriber = tracing_subscriber::registry().with(TreeTraceCapture {
2411            state: Arc::clone(&trace_state),
2412        });
2413        let _guard = tracing::subscriber::set_default(subscriber);
2414        tracing::callsite::rebuild_interest_cache();
2415
2416        let mut tree = Tree::new(
2417            TreeNode::new("root")
2418                .child(TreeNode::new("a").child(TreeNode::new("a1")))
2419                .child(TreeNode::new("b")),
2420        );
2421        let mut pool = GraphemePool::new();
2422        let mut frame = Frame::new(20, 6, &mut pool);
2423        tracing::callsite::rebuild_interest_cache();
2424        tree.render(Rect::new(0, 0, 20, 6), &mut frame);
2425        tracing::callsite::rebuild_interest_cache();
2426        assert!(tree.handle_key(&KeyEvent::new(KeyCode::Enter), 1));
2427
2428        tracing::callsite::rebuild_interest_cache();
2429        let snapshot = trace_state.lock().expect("tree trace state lock");
2430        assert!(snapshot.tree_render_seen, "expected tree.render span");
2431        assert!(
2432            snapshot.has_total_nodes_field,
2433            "tree.render missing total_nodes"
2434        );
2435        assert!(
2436            snapshot.has_visible_nodes_field,
2437            "tree.render missing visible_nodes"
2438        );
2439        assert!(
2440            snapshot.has_expanded_count_field,
2441            "tree.render missing expanded_count"
2442        );
2443        assert!(
2444            snapshot.render_duration_recorded,
2445            "tree.render did not record render_duration_us"
2446        );
2447        assert!(
2448            snapshot.toggle_events >= 1,
2449            "expected tree.toggle debug event"
2450        );
2451    }
2452}